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

[Thomas Dupond]

Hi Branden,

G. Branden Robinson <g.branden.robinson@gmail.com> wrote:

> 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.

Thank you very much for this detailed answer.  I discovered the .lf
macro thanks to this Makefile, very interesting.

> 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.

--
Regards,
Thomas