Hello Kristaps, Jörg and Ingo,

Ingo Schwarze <schwarze@usta.de> wrote:
 |Steffen Nurpmeso wrote on Mon, Mar 09, 2015 at 12:09:08PM +0100:
 |> Kristaps Dzonsons <kristaps@bsd.lv> wrote:
 |>> Summary: mdoc(7) has linking, but it's very restrictive.  You can link

 |Then again, we have a tradition of having good designs override
 |bad ones soon afterwards (no insult intended :).
 |
 |> I have proposed something similar back in September 2014 on groff@
 |
 |Exactly what i wanted to say.  :-)
 |
 |The thread is here:
 |
 |  http://lists.gnu.org/archive/html/groff/2014-09/msg00145.html
 |
 |> and implemented a complete package that can do this and much more
 |> with an interface that follows Ingo's suggestions since then.
 |> The macro is .Mx, the documentation, troff(1) awk(1) preprocessor,
 |> mdoc(1) macro extensions etc., and a patch for less(1) v471 that
 |> allows internal (including .Sh and .Ss, but many more) and
 |> external anchors (for .Xr) to be followed are available.  Use it
 |> or leave it.

 |Even though Steffen rightfully says that i influenced the design
 |he finally chose, and even though that design seemed better to me
 |than what was initially proposed, and even though Steffen was
 |positively enthusiastic about it, i wasn't quite satisfied yet.
 |
 |So my hope is that what we finally arrive at will at least be as
 |powerful as the union of your two implementations and at most as
 |complex as the intersection of both of them, or maybe even better...

That would be my hope, too -- moving the current state forward.
And maybe my final words were a bit too strong too, honestly
at least they were.  :-)

I'm still enthusiastic since it is a real improvement to work with
these more interactive manuals.  And i surely would like to know
any criticism you might have in order to be able to address it,
shall that be possible from the troff(1) side of the road.
Please let me attach the latest version of mdocmx.7 (from January
19th) to make sure we talk about the same state of affairs.

I want to point out that this is a mature and usable system,
regarding the entire mdocmx(1) (awk(1) preprocessor) / mdoc(7)
/ grotty(1) / less(1) pipeline.
Let me elaborate a bit on what i personally miss from that
onwards:

(1) Better performance: the last commit i made to mdocmx(7)
(2015-02-05) was a massive performance improvement (excerpt):

  Before:
        ?0[]$ time (mdocmx.sh nail.1|
        groff -Tutf8 -mdoc -dmx-toc-force=1 -dmx-debug=1 >/dev/null)
            0m1.25s real     0m1.59s user     0m0.06s system
        ?0[]$ time (export MDOCMX_ENABLE=1; mdocmx.sh nail.1|
        groff -Tutf8 -mdoc -dmx-toc-force=1 -dmx-debug=1 >MAN.before)
            0m7.36s real     0m7.73s user     0m0.08s system

  After:
        ?0[]$ time (mdocmx.sh nail.1|
        groff -Tutf8 -mdoc -dmx-toc-force=1 -dmx-debug=1 >/dev/null)
            0m1.19s real     0m1.59s user     0m0.06s system
        ?0[]$ time (export MDOCMX_ENABLE=1; mdocmx.sh nail.1|
        groff -Tutf8 -mdoc -dmx-toc-force=1 -dmx-debug=1 >MAN.old)
            0m2.56s real     0m2.97s user     0m0.07s system

  After, with an experimental .hash troff(1) builtin:
        ?0[]$ time (export MDOCMX_ENABLE=1; mdocmx.sh nail.1|
        groff -Tutf8 -mdoc -dmx-toc-force=1 -dmx-debug=1 >MAN.new)
            0m2.19s real     0m2.61s user     0m0.07s system

  For comparison, here is plain mdocml(1):
        ?0[]$ time (mdocmx.sh nail.1|mandoc > /dev/null)
            0m0.26s real     0m0.19s user     0m0.07s system

This is extreme but nail.1 results in ~4500 lines of rendered
text, the difference for NetBSD's bus_dma.9 for example is much
much smaller.

Shall mdocml(1) go that route i wouldn't even expect a measurable
impact, the problem with troff(1) is that we cannot have hashmaps
or trees from within macros.  (And of course the way mdoc(7) is
implemented is a problem; that can be improved, i would know how,
which would then also allow referenced HTML and PDF etc. output.)

(2) An index facility is missing.  I still find myself using
less(1)'s search command in order to get myself going in manuals.
It would be better if beside automatic TOC creation there would be
automatic index creation -- this is possible with mdocmx(7) and it
will happen: like this you scroll to e.g. the end of the manual to
the index and then can jump directly to the desired anchor.

(3) Due to the way mdoc(7) is implemented the reference anchors
can only be suffixes, not prefixes as is known from lynx(1).
I think it wouldn't bother anyone if mdocml(1) would start
generating anchors for less(1) as prefixes right from the start,
over time i will adjust the mdoc(7) macros (or at least plan to do
so) so they can follow.

--steffen