collected groff man pages and performance (was: Syntax errors in makeindex.1)

"G. Branden Robinson" <[email protected]> Wed, 29 Apr 2026 18:41:13 -0500
Newsgroups	gmane.comp.tex.tex-k,gmane.comp.printing.groff.general
Message-ID	<20260429234113.6epmbnrkkobdonwy@illithid>
I'm pleased to be able to split off one (or two) topics from the fairly
wide-ranging parent thread.  :)

At 2026-04-29T16:20:08-0600, Karl Berry wrote:
> By the way, I wonder if it would be useful for the groff distribution
> to include a single pdf document with all of groff's .7 man pages
> (maybe also .1's and .5's, for that matter), with a brief introduction
> and listing.

I think it would.  I've thought so for a while, and also wished that any
project could collect their man pages into a single document, rendered
as a PDF, with working hyperlinks.

So, modulus the brief introduction, and delegating the task of listing
to a PDF viewers outline pane, I'm pleased to offer you exactly that.

https://www.gnu.org/software/groff/manual/groff-man-pages.pdf

It was a surprising amount of work to get there from groff 1.22.4.  The
man and mdoc macro packages needed a lot of work: some to enhance their
cooperation with each other, but more to ensure that all kinds of
parameters were reset correctly when changing from one man page document
to another, because man page authors will get up to _anything_.  I
pretty much solved that problem for groff 1.23.0.

PDF hyperlinks were harder.  That demanded teamwork from groff's PDF
guru Deri James and me: I had to learn my way around some esoteric
and mostly undocumented parts of the formatter (troff proper) to achieve
a solution that was general enough to suit my standards of cleanliness
and elegance.  I made several mistakes along the way.  But in the end I
was able to deliver an interface that I think Deri found
satisfactory.[1]  And then I had to hook up to the output driver's
"device control extensions" to the man(7) and mdoc(7) macro packages
themselves.  He's doing some work on our ms(7) package now to similarly
equip it, and things look promising so far!

https://lists.gnu.org/archive/html/groff/2026-04/msg00045.html

> I, at least, would find such a thing highly convenient to have. Such
> overviews + tables-of-contents are not where man pages shine .. it is
> hard to know what's even available without some digging.

Strongly agreed.  The groff-man-pages.pdf we have today was a dream in
my mind, and an at first unspoken goal, when I started contributing to
groff in 2017.  I'm pretty pleased with the result.

There is, of course, always more to be done.  :)

Regards,
Branden

[1] ...modulus a slower PDF bookmark lookup procedure, which wasn't bad
    enough to gate the 1.24.0 release,[2] but which I'd still like to
    tackle.  groff's collected man pages run to only about 60 documents
    in 400 pages.  The Linux man-pages project offers more like 450
    documents in something like 9,000 pages, as I recall.

[2] On my machine, rebuilding "groff-man-pages.pdf" in groff 1.23.0 and
    groff 1.24.0 burns the clock as follows.

[groff-1.23.0]$ $ time make doc/groff-man-pages.pdf
...
real    0m5.595s
user    0m6.429s
sys     0m0.097s

[groff-1.24.0]$ $ time make doc/groff-man-pages.pdf
...
real    0m6.724s
user    0m8.595s
sys     0m0.172s

    So I can't fairly characterize Deri as satisfied until I've sorted
    out the "9,000% slowdown" he observed with an input specimen of his.

    https://lists.gnu.org/archive/html/groff/2024-12/msg00132.html
    https://lists.gnu.org/archive/html/bug-groff/2025-09/msg00080.html

    Regarding the 2nd link, so far I've only taken flak for a massive
    slowdown in _grotty_ performance, of all things.  As ever, the man
    page rendered to the terminal is the tail wagging groff's dog.

    https://savannah.gnu.org/bugs/?68145
signature.asc (application/pgp-signature, 833 B)