Re: Linux man-pages PDF book

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 4534 bytes --]

Hi Branden,

On Sun, Apr 14, 2024 at 03:25:28PM -0500, G. Branden Robinson wrote:
> Hi Alex,
> 
> Wow, I'm envious.  For you, lore let those gigantic attachments through.

They've recently changed the infrastructure; maybe something has
changed.  I remember the limit was 100k in the past, while my
attachments were 8.8M each, so it clearly seems to have been lifted.  I
didn't really think too much; we probably don't want to abuse that.
I'll try to be careful.

> At 2024-04-14T21:55:00+0200, Alejandro Colomar wrote:
> > I forgot to mention that while I can't reproduce the performance
> > regression, I see a regression in the navigation panel.  When using
> > groff.git HEAD's an.tmac, the navigation panel doesn't allow
> > collapsing an entire chapter, while the Linux man-pages fork of it
> > does allow.  Both PDF books are attached to this message.
> 
> I see what you mean.
> 
> One bet is that I messed something up here and Deri's first or second
> hypothesis will be correct.
> 
> Here's mine.
> 
> You might need to set a register I added in this commit.
> 
> commit 5fbc22d022c07f517bc83aa9b8c97ea5536efd18
> Author: G. Branden Robinson <g.branden.robinson@gmail.com>
> Date:   Sun Mar 3 23:57:38 2024 -0600
> 
>     [man]: Add `an*bookmark-base-level` register.
> 
>     * tmac/an.tmac: Add experimental feature to support increasing the base
>       level of PDF bookmarks.  Define register `an*bookmark-base-level`,
>       initialized to zero.
> 
>       (PT): Add 1 to it when producing document bookmark.
> 
>       (SH): Add 2 to it when producing section heading bookmark.
> 
>       (SS): Add 3 to it when producing subsection heading bookmark.
> 
> I don't know what you're using to produce the chapter headings in the
> navigation panel, but that likely needs to be at level 0 (or 1,
> depending on the convention the PDF spec uses).
> 
> I added the foregoing feature because it was obvious to me that someone
> might want to incorporate a man page collection into a larger work.
> 
> I admit I didn't think of the chapter organization application.

If you often open the Linux man-pages book you'll realize why you want
it.  If you want to navigate to a page in chapter 7, you don't want to
scroll down 1000+ bookmarks.  You want to close the navigation for the
first 6 chapters (and their subchapters), and easily arrive to
chapter 7.

> 
> So you'd likely do something like this when building with groff Git
> HEAD.
> 
>   '-r an*bookmark-base-level=1'

It doesn't seem to work.  I did the following.  I don't see a behavior
change at all.


diff --git a/share/mk/build/pdf/book/_.mk b/share/mk/build/pdf/book/_.mk
index 166cd28a6..46ede414a 100644
--- a/share/mk/build/pdf/book/_.mk
+++ b/share/mk/build/pdf/book/_.mk
@@ -31,20 +31,21 @@ _PDF_BOOK := $(_PDFDIR)/$(PDF_BOOK)
 
 
 $(_PDF_BOOK): $(_MANPAGES) $(_TINOS) $(MKBOOK) $(MK) | $$(@D)/
	$(info  $(INFO_)GROPDF          $@)
	$(MKBOOKDIR)/prepare.pl $(_MANDIR) \
	| $(CAT) $(MKBOOKDIR)/front.roff /dev/stdin \
	| $(PRECONV) \
	| $(PIC) \
	| $(TBL) \
	| $(EQN) -Tpdf \
-       | $(TROFF) -man -Tpdf -F$(_FONTSDIR) -dpaper=a4 $(TROFFFLAGS) \
+       | $(TROFF) -man -Tpdf -F$(_FONTSDIR) -dpaper=a4 \
+               '-r an*bookmark-base-level=1' $(TROFFFLAGS) \
	| $(GROPDF) -F$(_FONTSDIR) -pa4 $(GROPDFFLAGS) \
	| $(SPONGE) $@
 
 
 .PHONY: build-pdf-book
 build-pdf-book: $(_PDF_BOOK);
 
 
 endif  # include guard


> Let me know if that works out.
> 
> The foregoing is not documented because it needs field testing.  Now
> maybe it will get some.
> 
> > > $ 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.)
> 
> This is very good news.

:-)

BTW, the bookmarks for section headings and subsections don't have a
friendly name; they are of the form `#pdf:bm6`.  Maybe you could form a
name of the form `#intro.1:NOTES:Login`, or whatever form makes sense to
you, but based on the actual text of the bookmark.

Have a lovely night!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]