[groff] 05/15: [man]: Handle "internal" `MR` link targets.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit aa43ffcfb87c27b888dfaf94d5cb3ce0a5ceac3a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Mar 16 10:12:54 2024 -0500

    [man]: Handle "internal" `MR` link targets.
    
    [man]: When formatting PDF, attempt lookups of `MR` destinations as
    internal bookmark tags.  If lookup succeeds, link to the within-document
    destination rather than an "external" URL like "man:foobar(1)".
    
    * doc/GMPfront.t.in: Drop `END` dummy macro and redefinition of `MR`
      macro, moving the logic from here...
    * tmac/an.tmac (MR): ...to here, and trivially refactoring to rename
      variables for intelligibility.  Also simplify, using the "dangling
      open mark" incantation of the `pdfhref` macro that Deri innovated,
      since the existing logic unconditionally writes the link text
      subsequently.
    
    Now "doc/GMPfront.t.in" really is just a cover/front page, no longer
    rewriting any man(7) macros.  It should be easy for maintainers of other
    man page corpora to see how to adapt it for their project and use groff
    man(7) to produce internally hyperlinked PDFs.  Splendid.
    
    Thanks to Deri James for blazing the trail.
---
 ChangeLog         | 15 +++++++++++++++
 doc/GMPfront.t.in | 34 ----------------------------------
 tmac/an.tmac      | 10 ++++++++--
 3 files changed, 23 insertions(+), 36 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index a324d8033..6e8b9389e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2024-03-16  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [man]: When formatting PDF, attempt lookups of `MR` destinations
+       as internal bookmark tags.  If lookup succeeds, link to the
+       within-document destination rather than an "external" URL like
+       "man:foobar(1)".
+
+       * doc/GMPfront.t.in: Drop `END` dummy macro and redefinition of
+       `MR` macro, moving the logic from here...
+       * tmac/an.tmac (MR): ...to here, and trivially refactoring to
+       rename variables for intelligibility.  Also simplify, using the
+       "dangling open mark" incantation of the `pdfhref` macro that
+       Deri innovated, since the existing logic unconditionally writes
+       the link text subsequently.
+
 2024-03-16  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [man]: When formatting PDF, automatically give each `TH` call a
diff --git a/doc/GMPfront.t.in b/doc/GMPfront.t.in
index 5fa592ace..2ecc6ead9 100644
--- a/doc/GMPfront.t.in
+++ b/doc/GMPfront.t.in
@@ -8,40 +8,6 @@
 .defcolor pdf:href.colour rgb 0.00 0.25 0.75
 .pdfinfo /Title "groff Collected Reference Pages"
 .
-.de END
-..
-.
-.am reload-man END
-.de1 MR
-.  if ((\\\\n[.$] < 2) : (\\\\n[.$] > 3)) \
-.    an-style-warn .\\\\$0 expects 2 or 3 arguments, got \\\\n[.$]
-.  ds an*url man:\\\\$1(\\\\$2)\"
-.  if (\\\\n[an*MR-URL-format] = 2) \
-.    ds an*url x-man-page://\\\\$2/\\\\$1\"
-.  if (\\\\n[an*MR-URL-format] = 3) \
-.    ds an*url man:\\\\$1.\\\\$2\"
-.  if (\\\\n[an*MR-URL-format] = 4) \
-.    ds an*url x-man-doc://\\\\$2/\\\\$1(\\\\$2)\"
-.  nh
-.  ie (\\\\n[.$] = 1) \
-.    nop \&\\\\*[an-lic]\f[\\\\*[MF]]\\$1\\\\*[an-ic]\f[]\c
-.  el \{\
-.    ds an*page-ref-nm \\\\$1(\\\\$2)\"
-.    pdf:lookup \\\\*[an*page-ref-nm]
-.    ie !'\\\\*[pdf:lookup-result]'' \
-.      pdfhref L -D \\\\*[an*page-ref-nm] -A \c -- 
\f[\\\\*[MF]]\\\\$1\f[](\\\\$2)
-.    el \{\
-.      nop \&\m[\\\\*[PDFHREF.TEXT.COLOUR]]\c
-.      pdfhref W -D \\\\*[an*url] -- "|"
-.      nop \&\\\\*[an-lic]\f[\\\\*[MF]]\\\\$1\\\\*[an-ic]\f[R](\\\\$2)\c
-.      nop \X'pdf: markend'\m[default]\c
-.    \}
-.  \}
-.  nop \&\\\\$3
-.  hy \\\\n[an*hyphenation-mode]
-..
-.END
-.
 .de Hl
 .br
 \l'\\n[.l]u-\\n[.i]u\&\\$1'
diff --git a/tmac/an.tmac b/tmac/an.tmac
index c3881bd46..21c8314f3 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -1313,8 +1313,14 @@ contains unsupported escape sequence
 .      if '\*[.T]'html' \
 .        nop \X'html:<a href="\\*[an*url]">'\c
 .      if '\*[.T]'pdf' \{\
-.        nop \&\m[\\*[PDFHREF.TEXT.COLOUR]]\c
-.        pdfhref W -D \\*[an*url] -- "|"
+.        ds an*destination-bookmark-tag \\$1(\\$2)\"
+.        pdf:lookup \\*[an*destination-bookmark-tag]
+.        ie !'\\*[pdf:lookup-result]'' \
+.          pdfhref L -D \\*[an*destination-bookmark-tag] -- "|"
+.        el \{\
+.          nop \&\m[\\*[PDFHREF.TEXT.COLOUR]]\c
+.          pdfhref W -D \\*[an*url] -- "|"
+.        \}
 .      \}
 .      if \\n[an*is-output-terminal] \
 .        nop \X'tty: link \\*[an*url]'\c