[groff] 10/15: tmac/an.tmac: Refactor hyperlink management.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit bff14ae4f43cadb0019a2eadc0d13bb0ebd70445
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Feb 1 17:39:10 2024 -0600

    tmac/an.tmac: Refactor hyperlink management.
    
    * tmac/an.tmac: Refactor to distinguish visible hyperlinks from those
      that are sent only to device control commands.
    
      (an*begin-hyperlink): Rename existing string `an*hyperlink` to
      `an*visible-hyperlink`, which is the argument passed in via `UR` and
      `MT` calls.  Redefine `an*hyperlink` as the same argument, but with
      the `an*prefix` that its caller may specify.  (This feature is used to
      get the "mailto:"; URI scheme into links but not clutter the page text
      with them.)
    
      (an*end-hyperlink): Use `an*hyperlink` in device control commands
      instead of the catenation of `an*prefix` and `an*hyperlink`.  When
      there is no link text, use `an*visible-hyperlink` for it.  Remove both
      of these strings when done with them.
---
 ChangeLog    | 16 ++++++++++++++++
 tmac/an.tmac | 24 +++++++++++++-----------
 2 files changed, 29 insertions(+), 11 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index ebbf2f305..9ec620251 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2024-02-01  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * tmac/an.tmac: Refactor to distinguish visible hyperlinks from
+       those that are sent only to device control commands.
+       (an*begin-hyperlink): Rename existing string `an*hyperlink` to
+       `an*visible-hyperlink`, which is the argument passed in via `UR`
+       and `MT` calls.  Redefine `an*hyperlink` as the same argument,
+       but with the `an*prefix` that its caller may specify.  (This
+       feature is used to get the "mailto:"; URI scheme into links but
+       not clutter the page text with them.)
+       (an*end-hyperlink): Use `an*hyperlink` in device control
+       commands instead of the catenation of `an*prefix` and
+       `an*hyperlink`.  When there is no link text, use
+       `an*visible-hyperlink` for it.  Remove both of these strings
+       when done with them.
+
 2024-02-01  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * src/roff/troff/input.cpp (token::description): Fix code style
diff --git a/tmac/an.tmac b/tmac/an.tmac
index 83c144139..a6e9f26ca 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -1113,7 +1113,8 @@ contains unsupported escape sequence
 .
 .\" Store the argument and begin a diversion for link text.
 .de an*begin-hyperlink
-.  ds an*hyperlink \\$1\"
+.  ds an*hyperlink \\*[an*prefix]\\$1\"
+.  ds an*visible-hyperlink \\$1\" in case there is no link text
 .  \" We want the diversion to format as if it has an indentation of
 .  \" zero (that comes for free when we switch environments), and we
 .  \" want the line length reduced by the amount of indentation that
@@ -1156,12 +1157,12 @@ contains unsupported escape sequence
 .    \" Was any link text present?
 .    ie \\n[dn] \{\
 .      if '\*[.T]'html' \
-.        nop \X'html:<a href="\\*[an*prefix]\\*[an*hyperlink]">'\c
+.        nop \X'html:<a href="\\*[an*hyperlink]">'\c
 .      if '\*[.T]'pdf' \{\
-.        pdfhref W -D \\*[an*prefix]\\*[an*hyperlink] -- "|"
+.        pdfhref W -D \\*[an*hyperlink] -- "|"
 .      \}
 .      if \\n[an*is-output-terminal] \
-.        nop \X'tty: link \\*[an*prefix]\\*[an*hyperlink]'\c
+.        nop \X'tty: link \\*[an*hyperlink]'\c
 .      \" Replace the final newline of the diversion.
 .      chop an*link-text
 .      as an*link-text \&\c
@@ -1180,14 +1181,13 @@ contains unsupported escape sequence
 .    \" don't add angle brackets here.
 .    el \{\
 .      if '\*[.T]'html' \
-.        nop \X'html:<a href="\\*[an*prefix]\\*[an*hyperlink]">\
-\\*[an*hyperlink]</a>'\c
+.        nop \X'html:<a href="\\*[an*hyperlink]">\
+\\*[an*visible-hyperlink]</a>'\c
 .      if '\*[.T]'pdf' \
-.        pdfhref W -D \\*[an*prefix]\\*[an*hyperlink] -- \
-\\*[an*hyperlink]\c
+.        pdfhref W -D \\*[an*hyperlink] -- \\*[an*visible-hyperlink]\c
 .      if \\n[an*is-output-terminal] \
-.        nop \X'tty: link \\*[an*prefix]\\*[an*hyperlink]'\
-\\*[an*hyperlink]\X'tty: link'\c
+.        nop \X'tty: link \\*[an*hyperlink]'\
+\\*[an*visible-hyperlink]\X'tty: link'\c
 .    \}
 .    nop \&\\$1\"
 .  \}
@@ -1195,10 +1195,12 @@ contains unsupported escape sequence
 .  \" diversion, so the link text has already been formatted normally.
 .  el \{\
 .    nh
-.    nop \\[la]\\*[an*hyperlink]\\[ra]\\$1
+.    nop \\[la]\\*[an*visible-hyperlink]\\[ra]\\$1
 .    hy \\n[an*hyphenation-mode]
 .  \}
 .  rm an*link-text
+.  rm an*hyperlink
+.  rm an*visible-hyperlink
 ..
 .
 .\" Begin email hyperlink.  Input until the next `ME` call is stored in