Hi Branden, G. Branden Robinson <g.branden.robin...@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
