Re: Milestone reached: hyperlinked mdoc(7) documents in PDF

[Alejandro Colomar]

Hi Branden!

On Sun, Mar 17, 2024 at 05:23:20PM -0500, G. Branden Robinson wrote:
> Hi folks,
> 
> Following up my earlier announcement regarding man(7),[1], I'm pleased
> to report that we have a functioning PDF hyperlink story for the mdoc
> package.
> 
> * The Mt macro hyperlinks email addresses.
> * The Lk macro hyperlinks general URLs.
> * The Xr macro produces "man:foo(1)"-style hyperlinks.
> 
> I've also refactored groff's "an.tmac" file sufficiently that the macro
> redefinitions that Deri contributed as part of the "doc/GMPfront.t"
> file[2] are no longer necessary.
> 
> The new GMPfront.t is smaller and more obviously performative of the
> straightforward business of formatting a cover page, so that other
> projects that want to collect their man pages into a PDF can use it as a
> model without being baffled by macro appendments and quadruply-escaped
> expressions.  Even better, because we are no longer appending to macros,
> the input line numbers are not made inaccurate in the event of
> diagnostic messages.[3]
> 
> Thus, if you build groff Git HEAD from source, the generated
> groff-man-pages.pdf is now internally linked between not only all the
> man(7) format pages, but the mdoc(7) one as well.
> 
> A copy is available at the usual Dropbox, of course.
> 
> https://www.dropbox.com/sh/17ftu3z31couf07/AAC_9kq0ZA-Ra2ZhmZFWlLuva?dl=0
> 
> As a further demonstration, and as a gift (bone?) to mdoc(7) mavens, I'm
> attaching a PDF of all the mandoc(1) man pages, along with the 2-line
> shell script I used to produce it.
> 
> I welcome feedback, as always.  And bug reports.
> 
> Regards,
> Branden
> 
> P.S. Alex, you might want to consider simplifying your cover page
>      similarly once you bring your copy of groff up to date.

How much would you consider having a release sooner than expected, and
then have what originally would have been 1.24.0 be 1.25.0?  :)

I would prefer using a packaged version of groff, for two reasons:

-  I got impedance mismatches, when I see stuff like the 5n base-
   paragraph indent, but contributors are still seeing 7n.

-  In my server, I have a script that builds the man-pages book for
   every push to the main branch (true for both the Linux man-pages and
   shadow), and another that runs the lints and checks for the Linux
   man-pages.  Having built-from-source software in my computer is less
   of a problem, but in a server, it's less comfortable.  (I already
   have Deri's branch in there, and I'm not in love with that.)

But yeah, I'm willing to simplify as much as possible!  ;)

Cheers,
Alex

> https://git.savannah.gnu.org/cgit/groff.git/tree/doc/GMPfront.t.in
> 
> [1] https://lists.gnu.org/archive/html/groff/2024-01/msg00125.html
> 
> [2] ...now generated from "doc/GMPfront.t.in" at build time, so that the
>     cover page can include the groff version number without requiring
>     manual maintenance.
> 
> [3] This is a long-standing deficiency of GNU troff.  Would take some
>     doing to solve, I think; the whole concept of a line number could no
>     longer be expressed as an integer, but would instead require a
>     structured object of some kind.  Possibly a recursively structured
>     object at that, since `am` requests could occur inside portions of
>     macros that were themselves populated by `am`...


> sed -i -e 
> '/^\.Dt/{s/Dt/99/;y/ABCDEFGHIJKLMNOPQRSTUVWXYZ/abcdefghijklmnopqrstuvwxyz/;s/99/Dt/;}'
>  *.[1-8]
> for s in 1 3 5 7 8; do echo *.$s; done | xargs groff -t -mdoc -Tpdf >| 
> mandoc-groffed.pdf




-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

signature.asc
Description: PGP signature