Hi Branden, Deri,

On Sun, Apr 14, 2024 at 07:56:53AM -0500, G. Branden Robinson wrote:

Hi Alex,

At 2024-04-14T14:25:28+0200, Alejandro Colomar wrote:

quoted

On Sun, Apr 14, 2024 at 07:01:45AM -0500, G. Branden Robinson wrote:

quoted

I've since refactored everything that hyperlinked book generation
needed in that respect into groff's "an.tmac" (in Git), leaving the
cover page to do only cover page things.

https://git.savannah.gnu.org/cgit/groff.git/tree/doc/GMPfront.t.in

Hmmm.  I notice that your cover page has a few things that we have as
part of the prepare.pl script:
<https://git.savannah.gnu.org/cgit/groff.git/tree/doc/GMPfront.t.in#n7>
<https://git.savannah.gnu.org/cgit/groff.git/tree/doc/GMPfront.t.in#n42>
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/share/mk/build/pdf/book/prepare.pl#n86>

Maybe we could do the same, to reduce the work of prepare.pl?

I didn't look closely at that complicated Perl script, but it seems
likely.  Essentially, anything that didn't need to be parameterized
(i.e., lines you write out with Perl but don't need to do any Perl
variable interpolation in), I would keep in a plain text document.

I'd like to see how you build your book.

quoted

Our front page is also clean from an.tmac stuff.  We have the an.tmac
fork here:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/share/mk/build/pdf/book/an.tmac>

Might be worth diffing that with groff Git HEAD.

Attached are diffs against HEAD and against 1.23.0.

quoted

And the front page is:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/share/mk/build/pdf/book/front.roff>

Yup, that's pretty clean and focused.

quoted

However, our an.tmac is not for appending, but for replacing man(7).
:( I'd like to get rid of that an.tmac fork.  Does your message mean
that if I use groff git HEAD to build our book I can just drop the
fork and use man(7), and groff(1) will do the right thing?

I think so, and want to know if it doesn't.  Also, fair warning, Deri
said he observed a CRAZY bad performance regression when building the
Linux man-pages book with groff Git HEAD.  If you can reproduce that,
then I have some work to do.  Let me know.

Can't reproduce.  I've removed the an.tmac fork, and added -man to
troff(1)'s invocation, and get the same times.

$ time make build-pdf-book 2>/dev/null
GROPDF		.tmp/man-pages-6.7-53-g5125d867d.pdf

real	0m13.307s
user	0m16.229s
sys	0m0.481s

$ time make build-pdf-book 2>/dev/null
GROPDF		.tmp/man-pages-6.7-53-g5125d867d-dirty.pdf

real	0m13.564s
user	0m17.060s
sys	0m0.510s

(I've built all the dependencies before hand, so that only the PDF is
 built in these invocations.)
(The -dirty one uses -man.)

quoted

Also, what does .t mean (in GMPfront.t.in)?  I changed the file
extension to .roff (so, <front.roff>) in the Linux man-pages, as it's
just a roff(7) file.

It was Deri's choice.  Some people have historically used the `t` suffix
to indicate a "troff" file.  I don't employ that practice, personally,
because it's also popular as a suffix for "test script", and troff
documents can also be rendered with nroff.

Personally, I use `.roff` for *roff documents I intend to be portable
between AT&T/DWB troff and GNU troff, and `.groff` for ones that use GNU
extensions.

Hmmm.  Does the front use GNU features?  Should I change the extension?

At 2024-04-14T14:32:25+0200, Alejandro Colomar wrote:

quoted

Hmmmm.  Maybe I should follow v7's tradition and restart the page
number at each TH.  Let's call it an accidental improvement, and not a
regression.  :)

I think it's a matter of taste.  This issue came up last month on the
groff list.  As often happens with me, it turned into an episode of Unix
History Detectives.  :-|

https://lists.gnu.org/archive/html/groff/2024-03/msg00163.html

Hmmm.  Your obvservation about matching the PDF navigator makes sense.
Deri, was the removal of -rC1 on purpose?

quoted

Although it would be interesting to learn when/why this changed.

The default has never changed in groff as far as I know, and I'm certain
I haven't personally touched it--I'd remember writing the usual 20,000
word essay with 2 dozen citations that usually accompanies my breaks
with tradition.

Regards,
Branden

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>