Redux: linking in mdoc(7)?

Redux: linking in mdoc(7)?

[Kristaps Dzonsons]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Hi,

I saw on groff another post about indexing, so I thought to bring this
up again.  I'm wary of mdocmx because it's unreadably huge.  Manpages
should be simple.

A few months ago, I floated an implementation of an mdoc(7) macro
(plus one more, for completion), `Ix', that's an invisible anchor to
which `Sx' can point.  I implemented an active front-end in -Thtml
mode: there's no console mode because I'm not aware of link support in
stock less(1).  In HTML, obviously, `Ix' is implemented as an empty
<span id=""> to which subsequent <a href="#"> can link.

The concept of `Ix' arises from the desire to link not only to
sections and subsections, but also subsubsections and other textual
components.  The mdoc(7) manual is an excellent example, which abuses
`Ss' to allow linking to descriptions of individual macros.

The ``pro'' of `Ix' is that it's trivially easy to support in
mandoc(1) (patch was included) and can be just as easily ignored in
groff(1).  (I go for ``ignore'' because that's what groff already does
with Sx and Ss and friends, which are the proto-Ix.)  The patch is
dead easy to read.

The ``con'' is that it's a new macro.  To which I argue that, yes, it
is a new macro, but we already have a crippled form of the
functionality it provides (via `Sh' and `Ss'): this merely completes it.

Is this a reasonable concept to move forward with?  Thoughts?  The
patch I provided is implementation-complete.  I leave a PS/PDF
bookmark implementation as an exercise to the reader.

Best,

Kristaps
-----BEGIN PGP SIGNATURE-----
Comment: GPGTools - https://gpgtools.org

iQIcBAEBCgAGBQJVQk1/AAoJEMT2SUY9XBESHC4QALIlN5bruIt9bZ+muHt1+QuI
yjsccCwcxsJTk4adxFxYv/I4TAbeY7EAHFIJe+TpVsCeGuYx34ftKbbm2SdTx6Al
w4njGy7H0nXfNlBUo4n5z2QgVBIkzmgeGDXTpDdjFnlKD3xeFCMIxmZkQ8YSSY53
ADPnVqtSOAvrMgWkv+xR3lAhLF7si2ZpOC6Pe5EMF9iYnHdhh4R97E2crI+aRUkn
aAVddRvt4bwq5p3JH2SYtI+BfzrWLd6hkAJg+2Rzma1ZLtTtctYVSa8Zntiy7WRF
mKn7EwIWOHpWUe3nEJPyDbrs+QBrnN3unQmogVPik3YakwhDItabILSi9bH1BMtd
CN3MuFKtGLTpYohXEEUOL1lW9WKYDVDiih3YX/5eDz3K7SqTwjNWbS5/AOHw3UkX
JJPrJ95TV50mkoOh20tLW4nD9k0h2eyP2BrLT+1B+WHt85POhcmLadYpECfjGicV
23czGrxYiD24ZNXARXZZjbnY47SY+cdrLA5kej6RC5DSEKVwXAKbk6skYkb7xPx6
P+ptEl1rKfkQazcaLf7Ui+t2wwfP8KFSg8P44zb28hv/ekeVdKTfsrCzH3TSu6Gn
gJ7mHGA3DOwhQSYgjgMCZqIcQyOI3Bxs4wlK4+QdhztUgAA+g8yImbCK6t+IIIkp
QAvPfwQkQYXsnTkV2geP
=+/TN
-----END PGP SIGNATURE-----
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Redux: linking in mdoc(7)?

[Steffen Nurpmeso]

Kristaps Dzonsons <kristaps@bsd.lv> wrote:
 |I saw on groff another post about indexing, so I thought to bring this
 |up again.  I'm wary of mdocmx because it's unreadably huge.  Manpages

Oh no, it really isn't.  23139 bytes for all that functionality,
including (joking, maybe) HTML and PDF support?

 |should be simple.

And simple it is.  What do you mean by "wary", "huge" and "not
simple"?  These ~23000 bytes include a lot of comments, and of the
rest a lot of circumvent missing groff(1) datatypes and groff(1)
bugs.  What can these poor troff(1) macros do otherwise, without
a hashmap / tree and faced with those bugs.  In fact i'm happy
that it works -- and it *works*.

Try to break the less(1) or grotty(1) parts by providing nonsense
input: i think even the current AFL hype couldn't achieve that.

 |A few months ago, I floated an implementation of an mdoc(7) macro

I really thought and think about using your patch to implement .Mx
in mandoc(1) and offering the patch, of course.  The original plan
was to do so before i release the next version of the MUA
i maintain, in order to be able to produce the online manual with
mandoc(1); unfortunately this MUA turns me into a madcap, so the
release is out without that.  (I tested grohtml(1), and whereas
i get all the mdoxmx(7) links and the TOC just right, the
generated output is ridiculous beside that.)

 |(plus one more, for completion), `Ix', that's an invisible anchor to
 |which `Sx' can point.  I implemented an active front-end in -Thtml
 |mode: there's no console mode because I'm not aware of link support in
 |stock less(1).  In HTML, obviously, `Ix' is implemented as an empty

Stock less(1), yes.  At least still, i'm still hoping that it will
be accepted upstream, at least as an optional (selectable) part.
I personally hate HTML pretty much, but reading Unix manuals via
HTML is *complete* nonsense.  Really, what should that be good
for, on a local box, for a locally installed program/xy?

Note the mdocmx patch for less(1) is really super simple
(basically we forward-, then possibly backward-search for
a particular string).
And you do not only get local referenceability, but .Xr references
are also possible, temporarily replacing less(1) with man(1) to
read the external manual.  ~10000 bytes including manual update!

If you got that mail i've posted, look into, e.g., the attached
mdocmx.7 once like also posted:

  ( export MDOCMX_ENABLE=1
    mdocmx.sh mdocmx.7 |
    groff -Tutf8 -mdoc -dmx-toc-force=tree |
    LESS= less --RAW-CONTROL-CHARS --ignore-case --no-init )

You will get a manual page with all-in-all 80 active references
that can be sprung to via ^A in less(1), with a two-level table of
contents.  80 references, 36 of which are document-local, the
remaining reference external man(1)uals.  HTML?  What for?

 |<span id=""> to which subsequent <a href="#"> can link.
 |
 |The concept of `Ix' arises from the desire to link not only to
 |sections and subsections, but also subsubsections and other textual
 |components.  The mdoc(7) manual is an excellent example, which abuses
 |`Ss' to allow linking to descriptions of individual macros.
 |
 |The ``pro'' of `Ix' is that it's trivially easy to support in
 |mandoc(1) (patch was included) and can be just as easily ignored in
 |groff(1).  (I go for ``ignore'' because that's what groff already does
 |with Sx and Ss and friends, which are the proto-Ix.)  The patch is

No longer with mdocmx(7).

 |dead easy to read.
 |
 |The ``con'' is that it's a new macro.  To which I argue that, yes, it
 |is a new macro, but we already have a crippled form of the
 |functionality it provides (via `Sh' and `Ss'): this merely completes it.
 |
 |Is this a reasonable concept to move forward with?  Thoughts?  The
 |patch I provided is implementation-complete.  I leave a PS/PDF
 |bookmark implementation as an exercise to the reader.

So is there anything *i* could do for that?  I would love to see
just one extension that gets adapted and then just works!

If you need an additional anchor that can be sprung to: like i've
said the last time, the TTY output can't do that unless there is
"some meat" we can use to inject the necessary backspace sequence
(*unless* mdoc(7) has been rewritten completely, just like i've
posted (solution also in mdocmx.tmac i think)).

If it is ok for you that the TTY mode won't work, why not add ".Mx
-anchor BLA", shorter alias ".Mx -a BLA", or whatever you want,
i would however suggest ".Mx WHATEVER CATEGORY NAME", so that the
lists can be subdivided based on CATEGORY (to avoid linear list
searches, which are *really* slow in groff(1)).  If i recall
correctly something similar was your desire anyway?  It is just
fine as long as CATEGORY and NAME can both be used to ".ds"
a troff(1) string.  ".Mx -sxanchor CAT NAME"?

If done like that, and referenced via .Sx, it'll get slow --
mdocmx(7) first tries .Sh, then .Ss, then would try each CATEGORY
in order...  To improve that, .Sx had to gain a parameter, which
is not compatible.  Alternatively yet another .Mx mode had to be
added, say, ".Mx -sxlink CATEGORY" or whatever, which could set
an internal flag that would be inspected when looking up the next
.Sx parameter.  I think any .Mx usage (directly or indirectly)
should reset that flag again.

So that could be done, of course i'm absolutely open and willing
to add the final solution to mdocmx/.Mx.  All i'm interested in is
that manuals become more interactive (especially on the TTY where
i use them), and i'd be hoping for improved keyword searches and
manual section TOCs.  I.e., what made texinfo attractive (but with
external man(1)ual references).
One restriction: it should be compatible with *roff(1), and with
acceptable performance.

--steffen
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Redux: linking in mdoc(7)?

[Kristaps Dzonsons]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Folks,

Let's please focus on mdoc(7) and mandoc(1).  I'm only interested in
groff(1) insofar as it's able to cope easily with any mdoc(7) additions.

- From what I understand from mdocmx(7), `Mx' is an indexer.  This
sounds relevant for a text processor, but indexes aren't part of the
manpage tradition.  I don't see what problem `Mx' solves--I don't know
of any manpages having or in need of an index.  Most importantly,
here's no mandoc(1) `Mx' patch.  So not only do I not understand the
problem that's being solved, I don't know how you plan on solving it
with mandoc(1).

`Ix' exists for a concrete reason: allowing mdoc(7) to be compatible
with the existing (and many) Texinfo and DocBook documents, both of
which allow and use intra-document linking.  `Ix' implements these
constructs using the mechanism already in place in mdoc(7): `Sx'.  (I
added an `Lkx' to allow `Sx' to arbitrary names.  It should probably
have another name.)

The `Ix' concept benefits mdoc(7) a lot: with it and texinfo2mdoc(1),
real, existing, and useful manuals can be remapped into mdoc(7).
Think GSL, CVS, GCC, GMP, etc.  Not in theory, and not after a
monumental patch.  The patch exists, texinfo2mdoc(1) can do the work
already.  (docbook2mdoc(1) needs to be patched...)

I'm yet to hear anybody nay-say the idea or the implementation: I just
don't have a tmac patch that disregards the `Ix' for groff(1) to float
by the groff list.

Best,

Kristaps
-----BEGIN PGP SIGNATURE-----
Comment: GPGTools - https://gpgtools.org

iQIcBAEBCgAGBQJVQrWPAAoJEMT2SUY9XBESLGIQALST5vOpQMhbvsOK+jiYlq2s
EilHGxzXpyeL1EuaSSdH8ZvXJW2FivVaAYYvh3/J9VJCFRCaEOXO+oiIM5aygLur
evSvCPGrzeHsB1Tz0Yui7sp0O9MGQTFrPzxvvX4c64P1dx2mNrawN2iOUWYrNKk2
omklYG4YJUCIuTQFRDjG1ASOGcMWkleFj7VHjH4dWCOEfwV22BzQ6C3UR3BwSTXG
j8DpOKjO6jEvPxDpThAgRx+bnvMdF8uKK3CVKNBqyRqUUHTNuc68bMqYDIYsah96
5FGpS7uuQ02W0rjSkFhgMOazJO1Z/T8Y7Tj1obbb103+G+Bo/iOjkhXPYp/DH+Zj
1Czjfu7D5q7XrADQFB9GJEp8CHMMyMj+4RXCJOxJqoiAkfsZsTc//NDvdBX2fk3e
dn4jAAV5bts3HFTrYpXtOFdb4TgFteNiXgrCy1GJEtHwmcWIMZTvejP9uyZ2F21w
//8ofWulCNZKGJLS6PLpazqF+G8MhmYJoGL16v6EObzMQMjDXU1t85sjTVU1PTAN
Q2pK/8r+gGMmaSLkUQ4lJPgvxbHRuVY4VktsPFBwfzEVFRRsNZjfCXbkDDGw/xD2
mXT46nXmlPYJ8i0RK3bVrUXKMHIOmpVvKG5JnU7lhwVLAIVGw0fRGLnU3gzKEOd/
xQoHr/iWUX8/Sb2Vf+a5
=xkx5
-----END PGP SIGNATURE-----
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Redux: linking in mdoc(7)?

[Steffen Nurpmeso]

Happy 1st of May :o,

Kristaps Dzonsons <kristaps@bsd.lv> wrote:
 |with the existing (and many) Texinfo and DocBook documents, both of
 |which allow and use intra-document linking.
 
How about that?
It is missing mdocmx.sh preprocessor support yet (so that only
references to anchors already defined work).

.....

commit 7b77631 (HEAD, refs/heads/crawl)
Author: Steffen Nurpmeso <sdaoden@users.sf.net>
Date:   2015-05-01 21:51:10 +0200

    FIXME [mdocmx] Add ".Mx -ix [CAT] KEY" and ".Mx -sx [CAT]" \
    (Kristaps Dzonsons)..

    Kristaps Dzonsons (kristaps at bsd dot lv) prodded multiple times
    for freely definable anchors on (discuss at mdocml dot bsd dot lv)
    in order to be able to implement texi2mdoc etc.
    This is my proposed solution, and it'll do fine if the anchor is
    placed carefully, which should be no problem for automated
    converters.

.....

Note that in the next anchors[57] refers to the freely defined
"usage forms anchors" in the first text line (you would see it
with -dmx-debug=1).

.....

Freely definable anchors and references[15]
 Via the ‘.Mx -ix category key’ and ‘.Mx -ix key’ usage forms anchors can
 be defined almost anywhere, e.g., ‘.Mx -ix subsubsection "An interesting
 topic"’ defines the anchor ‘An interesting topic’ for the “key”
 ‘subsubsection’.  The form without a specified category will use the
 builtin name ‘ixsx’ instead.

 References to anchors[57] that have been created via -ix can be made by
 activating the .Sx search extension via ‘.Mx -sx category’ (or ‘.Mx -sx’
 for the builtin ‘ixsx’ category) followed by a normal local reference
 lookup:

       .Mx -sx subsubsection
       .Sx "An interesting topic"

 It should be noted that these usage forms are mostly ment for automated
 conversion tools rather than for human manual creators: their use is non-
 trivial (which is owed to the implementation of mdoc(7)[58]) and the
 resulting visual output should always be verified!  As a rule of thumb
 anchors should always created inside some “normal” text so that they can
 be attached to something “physical”.

--steffen
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Redux: linking in mdoc(7)?

[Steffen Nurpmeso]

FYI,

i've completed the mdocmx(7) side of the road.
Ciao.

 Freely definable anchors and references[15]
   Via the ‘.Mx -ix category key’ and ‘.Mx -ix key’ usage forms anchors can

(Btw., does anone knows how to do that as
  .Mx -ix [category] key
i.e., using .Op for category --- while still having the entire
thing inside of, and quoted by, .Ql?  mdoc(7) no-go i guess?)

   be defined almost anywhere, e.g., ‘.Mx -ix subsubsection "An interesting
   topic"’ defines the anchor ‘An interesting topic’ for the “key”
   ‘subsubsection’.  The form without a specified category will use the
   builtin name ‘ixsx’ instead.

   References to anchors that have been created via -ix can be made by acti‐
   vating the .Sx search extension via ‘.Mx -sx category’ (or ‘.Mx -sx’ for
   the builtin ‘ixsx[58]’ category) followed by a normal local reference
   lookup:

         .Mx -sx subsubsection
         .Sx "An interesting topic"

   It should be noted that these usage forms are mostly ment for automated
   conversion tools rather than for human manual creators: their use is non-
   trivial (which is owed to the implementation of mdoc(7)[59]) and the
   resulting visual output should always be verified!  As a rule of thumb
   anchors should always be created inside some “normal” text so that they
   can be attached to something “physical”.

--steffen
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv