Re: Redux: linking in mdoc(7)?

[Steffen Nurpmeso <sdaoden@yandex.com>]

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