[groff] 01/01: .MT/.ME and .UR/.UE hyperlinking for pdf output

[Deri James]

deri pushed a commit to branch master
in repository groff.

commit d71f9264f8c187aee1161f27cda7d42c4ad7065e
Author: Deri James <deri@chuzzlewit.myzen.co.uk>
AuthorDate: Fri Jan 26 15:47:28 2024 +0000

    .MT/.ME and .UR/.UE hyperlinking for pdf output
    
    Our documentation groff_man.7 documents that these requests are
    for hyperlinks. The .pdfhref W command expects the hotspot text
    to be passed as a parameter, but these pairs of requests enclose
    the required text. To solve this conundrum if the given
    hyperlink text to the .pdfhref request is the single pipe
    character "|" then mark all following text sent for output as
    the hotspot, terminate the hotspot on receipt of \X'pdf:
    markend' escape. This new facility is only available using -T
    pdf, not using -T ps and the pdfmark macros. Note the advice in
    the gropdf man page to use \X'pdf: marksuspend' and \X'pdf:
    markrestart' to protect any headers and footers becoming part of
    the hotspot in case the hyperlinked text crosses a page
    boundary.
    
    * tmac/an.tmac: add code to use .pdfhref W for these hyperlinks
    and protect against crossing page boundaries.
    
    * tmac/pdf.tmac: if the given text for a hyperlink consists of
    a single pipe character "|", start the hotspot and only
    terminate when \X'pdf: markend' is received.
---
 ChangeLog     | 23 +++++++++++++++++++++++
 tmac/an.tmac  | 12 +++++++++---
 tmac/pdf.tmac |  9 ++++++---
 3 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 7c42add2e..19d9b6a80 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,26 @@
+2024-01-26  Deri James  <deri@chuzzlewit.myzen.co.uk>
+
+       Our documentation groff_man.7 documents that these requests are
+       for hyperlinks. The .pdfhref W command expects the hotspot text
+       to be passed as a parameter, but these pairs of requests enclose
+       the required text. To solve this conundrum if the given
+       hyperlink text to the .pdfhref request is the single pipe
+       character "|" then mark all following text sent for output as
+       the hotspot, terminate the hotspot on receipt of \X'pdf:
+       markend' escape. This new facility is only available using -T
+       pdf, not using -T ps and the pdfmark macros. Note the advice in
+       the gropdf man page to use \X'pdf: marksuspend' and \X'pdf:
+       markrestart' to protect any headers and footers becoming part of
+       the hotspot in case the hyperlinked text crosses a page
+       boundary.
+
+       * tmac/an.tmac: add code to use .pdfhref W for these hyperlinks
+       and protect against crossing page boundaries.
+
+       * tmac/pdf.tmac: if the given text for a hyperlink consists of
+       a single pipe character "|", start the hotspot and only
+       terminate when \X'pdf: markend' is received.
+
 2024-01-25  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [troff]: Trivially refactor (trap Booleans).
diff --git a/tmac/an.tmac b/tmac/an.tmac
index a60eb888f..cfedbe28b 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -587,6 +587,7 @@ contains unsupported escape sequence
 .  PT
 .  ev
 .  ns
+.  if '\\*[.T]'pdf' .pdfmarkrestart
 ..
 .
 .\" Schedule a page break when the next output line is written (not
@@ -598,6 +599,7 @@ contains unsupported escape sequence
 .\" Prepare the footer for a page of the document.
 .de1 an-footer
 .  if \\n[an-suppress-header-and-footer] .return
+.  if '\\*[.T]'pdf' .pdfmarksuspend
 .  ev an*env-header-and-footer
 .  ie \\n[cR] \
 .    ds an*ofoot "\\*[an-pageref]\"
@@ -1106,6 +1108,7 @@ contains unsupported escape sequence
 .  if (\\n[an*is-in-link-text-diversion] & \\n[an*do-hyperlink]) \{\
 .    \" Start diversion in a new environment.
 .    ev an*link-text-env
+.    if \\n[an*is-output-pdf] \&\m[\\*[PDFHREF.TEXT.COLOUR]]\c
 .    di an*link-text-div
 .    ll (\\n[an*saved-line-length]u - \\n[an*saved-indentation]u)
 .  \}
@@ -1129,9 +1132,9 @@ contains unsupported escape sequence
 .    ie \\n[dn] \{\
 .      if \\n[an*is-output-html] \
 .        nop \X^html:<a href="\\*[an*prefix]\\*[an*hyperlink]">^\c
-.      if \\n[an*is-output-pdf] \
-.        pdfhref W -D \\*[an*prefix]\\*[an*hyperlink] -- \
-\\*[an*hyperlink]\c
+.      if \\n[an*is-output-pdf] \{\
+.        pdfhref W -D \\*[an*prefix]\\*[an*hyperlink] -- "|"
+.      \}
 .      if \\n[an*is-output-terminal] \
 .        nop \X^tty: link \\*[an*prefix]\\*[an*hyperlink]^\c
 .      \" Strip off the final newline of the diversion and emit it.
@@ -1142,6 +1145,8 @@ contains unsupported escape sequence
 .        nop \X^html:</a>^\c
 .      if \\n[an*is-output-terminal] \
 .        nop \X^tty: link^\c
+.      if \\n[an*is-output-pdf] \
+.        nop \X'pdf: markend'\m[\\*[pdf:curcol]]\c
 .    \}
 .    \" If there was no link text, format URI as its own link text.  We
 .    \" don't add angle brackets here.
@@ -1336,6 +1341,7 @@ contains unsupported escape sequence
 .
 .nr an*can-hyperlink 0
 .if (  \n[an*is-output-html] \
+     : \n[an*is-output-pdf] \
      : \n[an*is-output-terminal]) \
 .  nr an*can-hyperlink 1
 .
diff --git a/tmac/pdf.tmac b/tmac/pdf.tmac
index 68d5557e0..54175434f 100644
--- a/tmac/pdf.tmac
+++ b/tmac/pdf.tmac
@@ -383,7 +383,7 @@ am solely responsible for any bugs I may have introduced 
into this file.
 .\" blue components of the colour specification in the RGB colour
 .\" domain, which is shared by "groff" and the PDF readers.
 .\"
-.ds PDFHREF.COLOUR   0.35 0.00 0.60
+.ds PDFHREF.COLOUR   0.00 0.35 0.60
 .defcolor pdf:href.colour rgb \*[PDFHREF.COLOUR]
 .\"
 .\" "PDFHREF.TEXT.COLOUR", on the other hand, is simply defined
@@ -680,6 +680,7 @@ am solely responsible for any bugs I may have introduced 
into this file.
 .\" And now, we have no further use for "pdf*href.link".
 .\"
 .rm pdf*href.link
+.nr pdf:href.pipe 0
 .\"
 .\" If the user specified any "link prefix" text, (using the "-P text"
 .\" option), then emit it BEFORE processing the "link text" itself.
@@ -713,10 +714,12 @@ am solely responsible for any bugs I may have introduced 
into this file.
 .   \" text positions.
 .   \"
 \#.   if dPDFHREF.COLOUR .defcolor pdf:href.colour rgb \\*[PDFHREF.COLOUR]
+.   ds pdf:curcol \\n[.m]
 .   nr pdf:bm.width \\w'\\*[PDFHREF.DESC]'
+.   if '\\*[PDFHREF.DESC]'|' .nr pdf:href.pipe 1
 .   nop \&\m[\\*[PDFHREF.TEXT.COLOUR]]\c
 .   device pdf: markstart \\n[rst] \\n[rsb] \\n[PDFHREF.LEADING] 
\\*[pdf:href.link]
-.   nop \&\\*[PDFHREF.DESC]\X'pdf: markend'\m[]\c
+.   if !\\n[pdf:href.pipe] .nop \&\\*[PDFHREF.DESC]\X'pdf: 
markend'\m[\\*[pdf:curcol]]\c
 .   \"
 .   \" Clean up the temporary registers and strings, used to
 .   \" compute the "hot-spot" bounds, and format the reference,
@@ -733,7 +736,7 @@ am solely responsible for any bugs I may have introduced 
into this file.
 .\" And then, if the user specified any affixed text, (using the
 .\" "-A text" option), we tack it on at the end.
 .\"
-.nop \&\\*[pdf:href-A]
+.if !\\n[pdf:href.pipe] .nop \&\\*[pdf:href-A]
 ..
 .\" Macro "pdf*href-I" is used for one time initialisation of special
 .\" "pdfhref" features; (currently, only the above page trap hook is