[groff] 15/15: [man]: Fix Savannah #61434.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a183afb8ab45275ea09adecd3a72c8eb7feebb21
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Feb 1 21:49:10 2024 -0600

    [man]: Fix Savannah #61434.
    
    * tmac/an.tmac: Support `UR`/`UE` and `MT`/`ME` hyperlinks as paragraph
      tags.
    
      (an*begin-hyperlink): Kick away the guard that prevented attempts to
      do so, now that support has been refactored in underneath it.
    
    * tmac/groff_man.7.man.in (Hyperlink macros): De-document lack of
      support for this.  Retain caveat that if the output device lacks
      hyperlink support, the hyperlink is typeset as part of the paragraph
      body rather than the tag.  I could not see any way to achieve the
      alternative given the way this package uses traps and diversions.  We
      might make a virtue of necessity by noting that paragraph tags could
      be lengthy, and URLs often will be, and it will be hella ugly to have
      the tag break.  Furthermore, if we implement automated generation of
      link anchors based on `TP` paragraph tags, not having their
      destination URLs in the tag text means we don't have to scrape them
      out later.
    
    * tmac/tests/an_link-macros-work-in-paragraph-tags.sh: Update test
      expectations.
    
    * NEWS: Add item.
    
    Fixes <https://savannah.gnu.org/bugs/?61434>.
    
    Also bump copyright notices on relevant files.
---
 ChangeLog                                          | 29 +++++++++++++
 NEWS                                               |  5 +++
 tmac/an.tmac                                       | 10 +----
 tmac/groff_man.7.man.in                            | 15 ++++---
 .../tests/an_link-macros-work-in-paragraph-tags.sh | 48 +++++++++-------------
 5 files changed, 63 insertions(+), 44 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 4c6e8659f..0dc65ba62 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,32 @@
+2024-02-01  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [man]: Fix Savannah #61434.
+
+       * tmac/an.tmac: Support `UR`/`UE` and `MT`/`ME` hyperlinks as
+       paragraph tags.
+       (an*begin-hyperlink): Kick away the guard that prevented
+       attempts to do so, now that support has been refactored in
+       underneath it.
+
+       * tmac/groff_man.7.man.in (Hyperlink macros): De-document lack
+       of support for this.  Retain caveat that if the output device
+       lacks hyperlink support, the hyperlink is typeset as part of the
+       paragraph body rather than the tag.  I could not see any way to
+       achieve the alternative given the way this package uses traps
+       and diversions.  We might make a virtue of necessity by noting
+       that paragraph tags could be lengthy, and URLs often will be,
+       and it will be hella ugly to have the tag break.  Furthermore,
+       if we implement automated generation of link anchors based on
+       `TP` paragraph tags, not having their destination URLs in the
+       tag text means we don't have to scrape them out later.
+
+       * tmac/tests/an_link-macros-work-in-paragraph-tags.sh: Update
+       test expectations.
+
+       * NEWS: Add item.
+
+       Fixes <https://savannah.gnu.org/bugs/?61434>.
+
 2024-02-01  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/an.tmac: Refactor.  Give `TP` its own trap.
diff --git a/NEWS b/NEWS
index 9b4e1d323..77570e9b8 100644
--- a/NEWS
+++ b/NEWS
@@ -107,6 +107,11 @@ o Hyperlink support is now enabled by default on non-HTML 
devices that
   Instructions and commented code for disabling it remain in the
   "man.local" file.
 
+o The an (man) package now supports use of its hyperlink macros (`UR`,
+  `UE`, `MT`, and `ME`) as paragraph tags (that is, on the next line
+  after a `TP` macro call).  Use of the `MR` man page cross reference
+  macro as a tag was already supported in groff 1.23.0.
+
 o The an (man), doc (mdoc), and doc-old (mdoc-old) macro packages have
   changed the default line length when formatting on terminals from 78n
   to 80n.  The latter is a vastly more common configuration, but that
diff --git a/tmac/an.tmac b/tmac/an.tmac
index 2b78deb7a..04873aebf 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -1,6 +1,6 @@
 .\" groff implementation of man(7) package
 .\"
-.\" Copyright (C) 1989-2023 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2024 Free Software Foundation, Inc.
 .\"      Written by James Clark (jjc@jclark.com)
 .\" Enhanced by: Werner Lemberg <wl@gnu.org>
 .\"              Larry Kollar <kollar@alltel.net>
@@ -1131,13 +1131,7 @@ contains unsupported escape sequence
 .  \" obtains when we output it.
 .  nr an*saved-line-length \\n[.l]
 .  nr an*saved-indentation \\n[.i]
-.  \" We can only hyperlink if we're not in a diversion.
-.  \" XXX: There's no fundamental reason for that, just a simple matter
-.  \" of macro programming.
-.  ie !'\\n[.z]'' \
-.    an-warn cannot nest .MT or .UR inside .TP; ending paragraph tag
-.  el .if \\n[an*do-hyperlink] \{\
-.    nr an*is-in-link-text-diversion 1
+.  if \\n[an*do-hyperlink] \{\
 .    \" Start diversion in a new environment.
 .    nr an*is-in-link-text-diversion 1
 .    ev an*link-text-env
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index d7f4a272d..4fda4a6a2 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -1557,16 +1557,15 @@ _endif()dnl
 .
 .
 .P
-The hyperlinking of
+If a
 .B .TP
-paragraph tags with
+call is followed immediately by hyperlinking macros
 .BR .UR / .UE
-and
-.BR .MT / .ME
-is not yet supported;
-if attempted,
-the hyperlink will be typeset at the beginning of the indented paragraph
-even on hyperlink-supporting devices.
+or
+.BR .MT / .ME ,
+and the device doesn't support hyperlinking,
+the hyperlink is set at the beginning of the indented paragraph,
+not as part of the tag.
 .
 .
 .\" ====================================================================
diff --git a/tmac/tests/an_link-macros-work-in-paragraph-tags.sh 
b/tmac/tests/an_link-macros-work-in-paragraph-tags.sh
index 0cbb3f2c6..fd77602be 100755
--- a/tmac/tests/an_link-macros-work-in-paragraph-tags.sh
+++ b/tmac/tests/an_link-macros-work-in-paragraph-tags.sh
@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2021 Free Software Foundation, Inc.
+# Copyright (C) 2021-2024 Free Software Foundation, Inc.
 #
 # This file is part of groff.
 #
@@ -22,7 +22,7 @@ groff="${abs_top_builddir:-.}/test-groff"
 
 input=$(cat <<EOF
 .TH foo 1 2021-11-05 "groff test suite"
-.TP
+.TP 9n
 .UR https://\:github.com/\:Alhadis/\:Roff\:.js/
 .I Roff.js
 .UE
@@ -44,48 +44,40 @@ output=$(printf "%s" "$input" \
     | "$groff" -bww -Tascii -P-cbou $uflag -man)
 echo "$output"
 
-echo "checking for paragraph tag on line by itself ($uflag)" >&2
-echo "$output" | grep -qx '     Roff\.js' || wail # 5 spaces
+echo "checking for tag on same line as body ($uflag)" >&2
+echo "$output" | grep -Eq '^     Roff\.js  +.*is a' || wail # 5 spaces
 
 echo "checking for presence of typeset URI ($uflag)" >&2
-echo "$output" \
-    | grep -q '^            <https://github\.com/Alhadis/Roff\.js/>' \
-    || wail # 12 spaces
-
-output=$(printf "%s" "$input" \
-    | "$groff" -bww -Tascii -P-cbou $uflag -rLL=130n -man)
-echo "$output"
+echo "$output" | grep -Fq '<https://github.com/Alhadis/Roff.js/>' \
+    || wail
 
 # Sloppy handling of UE, ME macro arguments can cause unwanted space.
 echo "checking for normative (no extra) spacing after URI ($uflag)" >&2
 echo "$output" | grep -q '> is a viewer for intermediate' || wail
 
 # Now check for good formatting when URIs are hyperlinked.
+# Unfortunately we have to abandon `-cbou` or groff will (correctly)
+# detect that hyperlinks are impossible, and render them as text.  That
+# makes pattern matching harder because any old crazy,
+# terminal-dependent escape sequences could be present.
 uflag=-rU1
 
-output=$(printf "%s" "$input" \
-    | "$groff" -bww -Tutf8 -P-cbou $uflag -man)
+output=$(printf "%s" "$input" | "$groff" -bww -Tascii $uflag -man)
 echo "$output"
 
-echo "checking for paragraph tag on line by itself ($uflag)" >&2
-echo "$output" | grep -qx '     Roff\.js' || wail # 5 spaces
+echo "checking for tag on same line as body ($uflag)" >&2
+echo "$output" | grep -Eq 'Roff\.js.*is a viewer' || wail
 
-# Hyperlinking paragraph tags was not supported in groff 1.22.4 and
-# still isn't.
-#echo "checking for absence of typeset URI" >&2
-#! echo "$output" | grep -q https || wail
+text='is a viewer for intermediate output written in JavaScript.'
+echo "checking for normative (no extra) spacing after URI ($uflag)" >&2
+echo "$output" | grep -Fq "$text" || wail
 
-output=$(printf "%s" "$input" \
-    | "$groff" -bww -Tascii -P-cbou $uflag -rLL=130n -man)
+output=$(printf "%s" "$input" | "$groff" -bww -Tascii $uflag -man -Z \
+    | grep '^t')
 echo "$output"
 
-echo "checking for normative (no extra) spacing after URI ($uflag)" >&2
-# This is what we expect when linking the tag works.
-#echo "$output" \
-#    | grep -q '^              is a viewer for intermediate' \
-#    || wail # 14 spaces
-# ...but in the meantime...
-echo "$output" | grep -q '[^[:space:]] is a viewer for' || wail
+echo "checking for absence of typeset URI" >&2
+! echo "$output" | grep https || wail
 
 test -z "$fail"