[groff] 26/31: [man]: Refactor PDF bookmark support.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ea3b27102f1f84af4cf88f999266f10603c53628
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Jan 31 21:10:56 2022 +1100

    [man]: Refactor PDF bookmark support.
    
    * tmac/an.tmac (an*bookmark): New internal macro calls `pdfbookmark`
      (only if the output device is 'pdf' and the `BM` register is true).
    
      (initialization): Migrate macro appendments to appropriate
      definitions.  Two cases...
    
      (SH, SS): ...were straightforward.
    
      (initialization): Another (for the man page title) was poorly placed
      when appended to the `TH` macro, skipping over the page header.  Move
      it instead...
    
      (PT): ...here.  But to keep this bookmark from being generated on
      every page of a document, we need a new variable
      `an*was-TH-bookmark-emitted` which is tested here and assigned once
      one bookmark corresponding to a `TH` call has been written.
    
      (TH): Initialize `an*was-TH-bookmark-emitted` to zero.
    
      (SS): Write the bookmark _before_ the subsection heading text.
    
      (initialization): Drop short-lived `BM` register.  It seems harmless
      to unconditionally include bookmarks in PDF output.  A PDF tool can
      strip them out if they're not desired, and viewers seem capable of
      minimizing or reducing the navigation pane (if they even offer one in
      the first place).
    
    * tmac/an.tmac (initialization): Rename new `BN` register to `BD`...
    
    * tmac/groff_man.7.man.in (Options) <BD>: ...and document it.  Also
      document `PT`'s new bookmarking responsibility.
---
 ChangeLog               | 30 ++++++++++++++++++++++++++++
 tmac/an.tmac            | 52 +++++++++++++++++++++----------------------------
 tmac/groff_man.7.man.in | 21 ++++++++++++++++++--
 3 files changed, 71 insertions(+), 32 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index b2ede9ff..5966c7d9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,33 @@
+2022-01-31  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [man]: Refactor PDF bookmark support.
+
+       * tmac/an.tmac (an*bookmark): New internal macro calls
+       `pdfbookmark` (only if the output device is 'pdf' and the `BM`
+       register is true).
+       (initialization): Migrate macro appendments to appropriate
+       definitions.  Two cases...
+       (SH, SS): ...were straightforward.
+       (initialization): Another (for the man page title) was poorly
+       placed when appended to the `TH` macro, skipping over the page
+       header.  Move it instead...
+       (PT): ...here.  But to keep this bookmark from being generated
+       on every page of a document, we need a new variable
+       `an*was-TH-bookmark-emitted` which is tested here and assigned
+       once one bookmark corresponding to a `TH` call has been written.
+       (TH): Initialize `an*was-TH-bookmark-emitted` to zero.
+       (SS): Write the bookmark _before_ the subsection heading text.
+       (initialization): Drop short-lived `BM` register.  It seems
+       harmless to unconditionally include bookmarks in PDF output.  A
+       PDF tool can strip them out if they're not desired, and viewers
+       seem capable of minimizing or reducing the navigation pane (if
+       they even offer one in the first place).
+
+       * tmac/an.tmac (initialization): Rename new `BN` register to
+       `BD`...
+       * tmac/groff_man.7.man.in (Options) <BD>: ...and document it.
+       Also document `PT`'s new bookmarking responsibility.
+
 2022-01-31  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [grohtml,groff,nroff,troff]: Tweak usage message.
diff --git a/tmac/an.tmac b/tmac/an.tmac
index bf11c034..7b1ca4d0 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -159,7 +159,6 @@
 .  el        .bp 1
 ..
 .
-.
 .\" Localize manual section titles for English.
 .de an*localize
 .  ds an*section1 General Commands Manual\"
@@ -173,6 +172,14 @@
 .  ds an*section9 Kernel Developer's Manual\"
 ..
 .
+.\" Write a bookmark/anchor/link target $2 at hierarchical depth $1.
+.de an*bookmark
+.  if '\\*[.T]'pdf' \{\
+.    nr an*bookmark-depth \\n[BD]+\\$1
+.    pdfbookmark \\n[an*bookmark-depth] \\$2
+.    rr an*bookmark-depth
+.  \}
+..
 .
 .\" Begin man page.
 .\" .TH title section[ extra1[ extra2[ extra3]]]
@@ -292,6 +299,9 @@
 .    DEVTAG-EO-TL
 .  \}
 .
+.  \" A bookmark is attached to the page header, but only on the first
+.  \" page of the document.
+.  nr an*was-TH-bookmark-emitted 0
 .  an-header
 .
 .  if !\\n[cR] \{\
@@ -351,6 +361,10 @@
 .de1 PT
 .  ie \\n[cR] .pl +1v
 .  el         .sp .5i
+.  if !\\n[an*was-TH-bookmark-emitted] \{\
+.    an*bookmark 1 \E*[an*page-ref-string]
+.    nr an*was-TH-bookmark-emitted 1
+.  \}
 .  tl '\\*[an-pageref]'\\*[an-extra3]'\\*[an-pageref]'
 .  ie \\n[cR] \{\
 .    pl +1v
@@ -605,6 +619,7 @@
 .  if \\n[.$] \{\
 .    ds an-section-heading \\$*\"
 .    if \\n[CS] .stringup an-section-heading
+.    an*bookmark 2 \E*[an-section-heading]
 \&\\*[an-section-heading]
 .  \}
 .  if \\n[an-remap-I-style-in-headings] .ftr I I
@@ -627,8 +642,9 @@
 .  ft \\*[HF]
 .  if \\n[an-remap-I-style-in-headings] .ftr I \\*[an-heading-family]BI
 .  if \\n[.$] \{\
-.    nop \&\\$*
 .    ds an*subsection-heading \\$*\"
+.    an*bookmark 3 \E*[an*subsection-heading]
+.    nop \&\\$*
 .  \}
 .  if \\n[an-remap-I-style-in-headings] .ftr I I
 ..
@@ -1033,37 +1049,13 @@
 .\" Set each rendering parameter only if its -[dr] option or man.local
 .\" did not.
 .
-.\" Enable within-page navigation via bookmarks--only operational with
-.\" output device 'pdf', but could be extended to others contingent on
-.\" their supporting features.
-.if !r BM .nr BM 1
-.
 .\" base depth for bookmarks (for embedding man pages in other docs)
-.if !r BN .nr BN 0
+.if !r BD .nr BD 0
 .
-.\" Make man pages navigable in PDF output.  Thanks to Deri James.
 .if '\*[.T]'pdf' \{\
-.  if \n[BM] \{\
-.    nr PDFOUTLINE.FOLDLEVEL 1
-.    nr PDFHREF.VIEW.LEADING 10p
-.    am1 TH
-.      nr an*bookmark-depth \n[BN]+1
-.      pdfbookmark \\n[an*bookmark-depth] \\*[an*page-ref-string]
-.      rr an*bookmark-depth
-.    .
-.
-.    am1 SH
-.      nr an*bookmark-depth \n[BN]+2
-.      pdfbookmark \\n[an*bookmark-depth] \\*[an-section-heading]
-.      rr an*bookmark-depth
-.    .
-.
-.    am1 SS
-.      nr an*bookmark-depth \n[BN]+3
-.      pdfbookmark \\n[an*bookmark-depth] \\*[an*subsection-heading]
-.      rr an*bookmark-depth
-.    .
-.  \}
+.  \" FIXME: The following registers are documented only in pdf.tmac.
+.  if !r PDFOUTLINE.FOLDLEVEL .nr PDFOUTLINE.FOLDLEVEL 1
+.  if !r PDFHREF.VIEW.LEADING .nr PDFHREF.VIEW.LEADING 10p
 .\}
 .
 .\" continuous rendering (one long page)
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 86525936..86906503 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -2764,9 +2764,13 @@ Such hook definitions will likely consist of 
\[lq].sp\[rq] and
 .
 They must also increase the page length with \[lq].pl\[rq] requests in
 continuous rendering mode;
-consult the existing implementations in
+.B .PT
+furthermore has the responsibility of emitting a PDF bookmark after
+writing the first page header in a document.
+.
+Consult the existing implementations in
 .I an.tmac
-when drafting your replacement.
+when drafting replacements.
 .
 .
 .TP
@@ -3123,6 +3127,19 @@ for less-common choices.
 .
 .
 .TP
+.BI \-rBD= base-bookmark-depth
+Set the depth below which all man pages' PDF bookmarks will be arranged.
+.
+The default is 0;
+changing it may be useful if a man page is to be embedded in a larger
+PDF document.
+.
+This option is only meaningful when producing output for the
+.B pdf
+device.
+.
+.
+.TP
 .B \-rcR=1
 Enable continuous rendering.
 .