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
Description: PGP signature
