Re: preview of man(7) navigation/hyperlink features in groff 1.23

[G. Branden Robinson]

Hi, Thomas!

I should mention that my email to the linux-man list bounced.  The
attachment made the message too big.  I guess the list config served as
the better angel of my nature: I hate marketing.

At 2022-01-27T18:04:44+0000, Thomas Dupond wrote:
> Hi Branden,
> 
> This is incredibly better for discoverability, thank you very much to
> you and Deri James.

It's no exaggeration to say that I've been working toward this goal
since I first started contributing to groff in 2017.  There were many
bugs to fix in batch rendering of man pages, and I had much to learn
before I could fix them.

A significant amount of work remains with respect to improving page
content.  That effort will extend well past the 1.23 release, I expect.

There is also the issue of converting the `MR` macro hyperlinks (the new
thing from October of last year for man page cross references) into
within-document PDF links.  Deri's already sent me an example
implementation of that, which I'm still studying.  It needs to be an
optional feature: man pages will not always, and perhaps not often, be
compiled as we are doing (except in our own distribution).

I'm also extending these features to our mdoc(7) implementation, and am
curious to see what Ingo has to say.  I'm putting on my asbestos long
johns, as they used to say on USENET.  ;-)

> I noticed that the PDF you are showing includes all groff related man
> pages.  How did you generate this PDF?

We're generating it as part of the build.  The PDFfy bits are embedded
in the macro package.  The rest is a matter of selecting which man(7)
and mdoc(7) documents you want, and telling groff to render them.

First we build a big list of our man pages (actually 3 lists because
of localization gymnastics combined with lexicographical ordering[1]).
https://git.savannah.gnu.org/cgit/groff.git/tree/doc/doc.am#n147

Then we define a Makefile target to depend on those man pages and
generate a PDF from them.
https://git.savannah.gnu.org/cgit/groff.git/tree/doc/doc.am#n225

Nothing about this is intended to be specialized for or confined to
groff man pages.  These are features any man(7) page can take advantage
of when rendered to PDF with groff, without even having to do any
work--with the exception of the `MR` macro.  Even without that, any set
of man pages can get the results seen in my screenshot, because it
doesn't show the `MR`->PDF hyperlink translation feature in place.

I've pushed the commits that enable PDF bookmarks for man pages, so
people can play with it now if they want to.

I join you in thanking Deri.  He understands PDF, and I truly don't.

Regards,
Branden

[1] This happily also serves as a sensitive regression test for
localization issues, since the Swedish groff locale has to be loaded, a
page rendered using it, and then the English groff locale re-loaded,
all without screwing up man(7) volume section titles, inter-sentence
spacing, or hyphenation.  It took me several tries to get this right.

signature.asc
Description: PGP signature