[groff] 08/15: [pdf,man,mdoc]: Refactor a recent feature.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 5058bc7ea64fbc88e534cbeaa3b85b2e0d2014d8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Mar 16 10:48:21 2024 -0500

    [pdf,man,mdoc]: Refactor a recent feature.
    
    The "pdfhref pipe" feature recently added used in-band signaling to
    indicate that a PDF mark hotspot should be left open by the `pdhref`
    hyperlink management macro.  I'm uneasy with this because it forecloses
    the possibility of using the chosen in-band signal content as link text.
    (Compounding the risk of user frustration is that there's no
    documentation of any of this.)  Replace it by adding a new `-S` flag to
    the `pdfhref` macro, indicating the caller's desire to manage closing of
    the hotspot themselves, as "tmac/an.tmac" does already.
    
    See <https://savannah.gnu.org/bugs/?61434#comment5>.
    
    * tmac/pdf.tmac (pdfhref): Initialize `pdf:href-S` register to zero
      (false).
      (pdf:href.opt-S): Define new alias for `pdf:href.flag`, so the
      {complex, Unix command-emulating} `pdfhref` argument management system
      treats it as a Boolean parameter.
      (pdf*href): Rename `pdf:href.pipe` register to
      `pdf:href.leave-mark-open`.  Throw error and don't honor "-S"
      parameter if the user has also specified a link text appendment with
      the "-A" option.  (If we're not closing the hotspot, we don't know
      where the appendment will go.)  Stop treating link text (the
      `PDFHREF.DESC` string) specially if it is "|".
    
    * tmac/an.tmac (an*end-hyperlink, MR):
    * tmac/doc.tmac (doc-begin-hyperlink-pdf): Migrate to new API.
---
 ChangeLog     | 31 +++++++++++++++++++++++++++++++
 tmac/an.tmac  |  6 +++---
 tmac/doc.tmac |  2 +-
 tmac/pdf.tmac | 20 +++++++++++++++-----
 4 files changed, 50 insertions(+), 9 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 3b4b7d8ac..3ca83582c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,34 @@
+2024-03-16  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [pdf,man,mdoc]: Refactor a recent feature.
+
+       The "pdfhref pipe" feature recently added used in-band signaling
+       to indicate that a PDF mark hotspot should be left open by the
+       `pdhref` hyperlink management macro.  I'm uneasy with this
+       because it forecloses the possibility of using the chosen
+       in-band signal content as link text.  (Compounding the risk of
+       user frustration is that there's no documentation of any of
+       this.)  Replace it by adding a new `-S` flag to the `pdfhref`
+       macro, indicating the caller's desire to manage closing of the
+       hotspot themselves, as "tmac/an.tmac" does already.
+
+       See <https://savannah.gnu.org/bugs/?61434#comment5>.
+
+       * tmac/pdf.tmac (pdfhref): Initialize `pdf:href-S` register to
+       zero (false).
+       (pdf:href.opt-S): Define new alias for `pdf:href.flag`, so the
+       {complex, Unix command-emulating} `pdfhref` argument management
+       system treats it as a Boolean parameter.
+       (pdf*href): Rename `pdf:href.pipe` register to
+       `pdf:href.leave-mark-open`.  Throw error and don't honor "-S"
+       parameter if the user has also specified a link text appendment
+       with the "-A" option.  (If we're not closing the hotspot, we
+       don't know where the appendment will go.)  Stop treating link
+       text (the `PDFHREF.DESC` string) specially if it is "|".
+
+       * tmac/an.tmac (an*end-hyperlink, MR):
+       * tmac/doc.tmac (doc-begin-hyperlink-pdf): Migrate to new API.
+
 2024-03-16  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/pdf.tmac (pdf*href): Fix derpy syntax error, introduced
diff --git a/tmac/an.tmac b/tmac/an.tmac
index 21c8314f3..fab6fdd64 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -1179,7 +1179,7 @@ contains unsupported escape sequence
 .      if '\*[.T]'html' \
 .        nop \X'html:<a href="\\*[an*hyperlink]">'\c
 .      if '\*[.T]'pdf' \
-.        pdfhref W -D \\*[an*hyperlink] -- |
+.        pdfhref W -S -D \\*[an*hyperlink]
 .      if \\n[an*is-output-terminal] \
 .        nop \X'tty: link \\*[an*hyperlink]'\c
 .      unformat an*link-text \" ...so it adjusts in its new context.
@@ -1316,10 +1316,10 @@ contains unsupported escape sequence
 .        ds an*destination-bookmark-tag \\$1(\\$2)\"
 .        pdf:lookup \\*[an*destination-bookmark-tag]
 .        ie !'\\*[pdf:lookup-result]'' \
-.          pdfhref L -D \\*[an*destination-bookmark-tag] -- "|"
+.          pdfhref L -S -D \\*[an*destination-bookmark-tag]
 .        el \{\
 .          nop \&\m[\\*[PDFHREF.TEXT.COLOUR]]\c
-.          pdfhref W -D \\*[an*url] -- "|"
+.          pdfhref W -S -D \\*[an*url]
 .        \}
 .      \}
 .      if \\n[an*is-output-terminal] \
diff --git a/tmac/doc.tmac b/tmac/doc.tmac
index 595632672..9bb8ec012 100644
--- a/tmac/doc.tmac
+++ b/tmac/doc.tmac
@@ -4552,7 +4552,7 @@ arguments
 .
 .eo
 .de doc-begin-hyperlink-pdf
-.  pdfhref W -D \$1 -- |
+.  pdfhref W -S -D \$1
 ..
 .ec
 .
diff --git a/tmac/pdf.tmac b/tmac/pdf.tmac
index 6b149637e..1b2415270 100644
--- a/tmac/pdf.tmac
+++ b/tmac/pdf.tmac
@@ -444,9 +444,10 @@ am solely responsible for any bugs I may have introduced 
into this file.
 .   \"
 .      nr pdf:href.ok 1
 .   \"
-.   \" Initialise -E and -X flags in the OFF state
+.   \" Initialise -E, -S, and -X flags in the OFF state
 .   \"
 .      nr pdf:href-E 0
+.      nr pdf:href-S 0
 .      nr pdf:href-X 0
 .   \"
 .   \" Handle the case where subcommand is specified as "-class",
@@ -530,6 +531,7 @@ am solely responsible for any bugs I may have introduced 
into this file.
 .als pdf:href.opt-E pdf:href.flag     \" echo link descriptor
 .als pdf:href.opt-F pdf:href.option   \" remote file specifier
 .als pdf:href.opt-N pdf:href.option   \" reference name
+.als pdf:href.opt-S pdf:href.flag     \" start mark only, "leaving open"
 .als pdf:href.opt-P pdf:href.option   \" prefixed text
 .als pdf:href.opt-T pdf:href.option   \" bookmark "tag"
 .als pdf:href.opt-X pdf:href.flag     \" cross reference
@@ -714,7 +716,16 @@ 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
+.nr pdf:href.leave-mark-open 0
+.\"
+.\" Does the user want to leave the mark hanging open (using the "-S"
+.\" flag)?  If so, it's their responsibility to close it by issuing the
+.\" "pdf: markend" device control command.
+.if \\n[pdf:href-S] \{\
+.  ie !'\\*[pdf:href-A]'' .pdf:error pdfhref flag '-S' cannot be used \
+with '-A' option
+.  el .nr pdf:href.leave-mark-open 1
+.\}
 .\"
 .\" If the user specified any "link prefix" text, (using the "-P text"
 .\" option), then emit it BEFORE processing the "link text" itself.
@@ -756,11 +767,10 @@ am solely responsible for any bugs I may have introduced 
into this file.
 \#.   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]
 '   fl
-.   if !\\n[pdf:href.pipe] \{\
+.   if !\\n[pdf:href.leave-mark-open] \{\
 .     nop \&\\*[PDFHREF.DESC]\c
 .     device pdf: markend
 '     fl
@@ -782,7 +792,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.
 .\"
-.if !\\n[pdf:href.pipe] .nop \&\\*[pdf:href-A]
+.if !\\n[pdf:href.leave-mark-open] .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