[groff] 09/10: [man]: Make multiple URL formats available.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 93fd4f9f5899cc9d5a0bb9c4f71373a2c00d80c7
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Feb 11 10:14:57 2023 -0600

    [man]: Make multiple URL formats available.
    
    * tmac/an.tmac: Add internal register `an*MR-URL-format` to select from
      a few known formats of man page hyperlink.  There are three known on
      macOS, and one used everywhere else.
    
    * tmac/man.local: Document this feature so macOS users can enjoy the OSC
      8 hyperlink feature if their terminal application supports it.
    
    I hope that this feature will be a temporary measure while macOS
    implements support for the man page URL format used everywhere else in
    the world.
    
    Fixes <https://savannah.gnu.org/bugs/?63768>.  Thanks to John Gardner
    for the report, research, consultation, and testing.
    
    ANNOUNCE: Update bug counts.
    
    Also wrap previous ChangeLog entry at 72 columns.
---
 ANNOUNCE       |  6 +++---
 ChangeLog      | 24 ++++++++++++++++++++----
 tmac/an.tmac   | 19 ++++++++++++++++---
 tmac/man.local | 10 ++++++++++
 4 files changed, 49 insertions(+), 10 deletions(-)

diff --git a/ANNOUNCE b/ANNOUNCE
index 8bc51aeea..34c0b1d59 100644
--- a/ANNOUNCE
+++ b/ANNOUNCE
@@ -58,7 +58,7 @@ release shipped with three automated unit tests; this one 
ships with
 over 160 unit and regression tests.
 
 As of this writing, per the GNU Savannah bug tracker, the groff project
-has resolved 412 problems as fixed for the 1.23.0 release.  Some of the
+has resolved 413 problems as fixed for the 1.23.0 release.  Some of the
 bugs we've corrected were over 30 years old.
 
 Classifying these issues by type and the component of the project to
@@ -69,14 +69,14 @@ which they apply, we find the following.
   Build/installation           38   Core                           94
   Crash/unresponsive           11   Driver: grohtml                 7
   Documentation                99   Driver: gropdf                  9
-  Feature change               39   Driver: grops                   2
+  Feature change               40   Driver: grops                   2
   Incorrect behavior          129   Driver: grotty                  4
   Lint                         15   Driver: others/general          8
   Rendering/cosmetics          10   Font: devpdf                    1
   Test                          4   Font: devps                     3
   Warning/suspicious behavior  67   Font: others/general            4
                                     General                        46
-                                    Macros: man                    32
+                                    Macros: man                    33
                                     Macros: mdoc                   13
                                     Macros: me                     36
                                     Macros: mm                     20
diff --git a/ChangeLog b/ChangeLog
index c48799f7e..9ed3f2813 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,17 +1,33 @@
+2023-02-11  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * tmac/an.tmac: Add internal register `an*MR-URL-format` to
+       select from a few known formats of man page hyperlink.  There
+       are three known on macOS, and one used everywhere else.
+       * tmac/man.local: Document this feature so macOS users can enjoy
+       the OSC 8 hyperlink feature if their terminal application
+       supports it.
+
+       I hope that this feature will be a temporary measure while macOS
+       implements support for the man page URL format used everywhere
+       else in the world.
+
+       Fixes <https://savannah.gnu.org/bugs/?63768>.  Thanks to John
+       Gardner for the report, research, consultation, and testing.
+
 2023-02-11  Deri James  <deri@chuzzlewit.myzen.co.uk>
 
        [BuildFoundries]: Fails if neither ghostcript nor URW fonts
        are installed.
 
-       * font/devpdf/util/BuildFoundries.pl: When the change to hold paths
-       in an array, rather than a delimited string (see commit
+       * font/devpdf/util/BuildFoundries.pl: When the change to hold
+       paths in an array, rather than a delimited string (see commit
        4ae4aeb6555f4f16c28fcb03eb1f56577826054c), the FindGSpath
        subroutine should return a pointer to an empty array when the
        call to ghostscript fails, rather than return an empty string,
        as was done previously.
 
-       See <https://lists.gnu.org/archive/html/groff/2023-02/msg00042.html>
-       thanks to Bruno Haible for the report.
+       See <https://lists.gnu.org/archive/html/groff/2023-02/\
+       msg00042.html>; thanks to Bruno Haible for the report.
 
 2023-02-09  G. Branden Robinson <g.branden.robinson@gmail.com>
 
diff --git a/tmac/an.tmac b/tmac/an.tmac
index a00340573..7ab3ccae1 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -1,6 +1,6 @@
 .\" groff implementation of man(7) package
 .\"
-.\" Copyright (C) 1989-2022 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2023 Free Software Foundation, Inc.
 .\"      Written by James Clark (jjc@jclark.com)
 .\" Enhanced by: Werner Lemberg <wl@gnu.org>
 .\"              Larry Kollar <kollar@alltel.net>
@@ -1161,17 +1161,30 @@ contains unsupported escape sequence
 .  rm an*prefix
 ..
 .
+.\" There is no standardized format for man page URLs, but the default
+.\" is expected to work (or be harmlessly ignored) everywhere except
+.\" macOS.  Override in man.local if desired.
+.nr an*MR-URL-format 1
+.
 .\" Set a man page cross reference.
 .\" .MR page-topic page-section [trailing-text]
 .de1 MR
 .  if ((\\n[.$] < 2) : (\\n[.$] > 3)) \
 .    an-style-warn .\\$0 expects 2 or 3 arguments, got \\n[.$]
+.  if (\\n[an*MR-URL-format] = 1) \
+.    ds an*url man:\\$1(\\$2)\" used everywhere but macOS
+.  if (\\n[an*MR-URL-format] = 2) \
+.    ds an*url man:\\$1.\\$2\" Bwana (macOS)
+.  if (\\n[an*MR-URL-format] = 3) \
+.    ds an*url x-man-doc://\\$2/\\$1(\\$2)\" ManOpen (macOS)
+.  if (\\n[an*MR-URL-format] = 4) \
+.    ds an*url x-man-page://\\$2/\\$1\" Terminal.app, iTerm (macOS)
 .  nh
 .  if \\n[an*do-hyperlink] \{\
 .    if \\n[an*is-output-html] \
-.      nop \X^html:<a href="man:\\$1(\\$2)">^\c
+.      nop \X^html:<a href="\\*[an*url]">^\c
 .    if \\n[an*is-output-terminal] \
-.      nop \X^tty: link man:\\$1(\\$2)^\c
+.      nop \X^tty: link \\*[an*url]^\c
 .  \}
 .      nop \&\\*[an-lic]\f[\\*[MF]]\\$1\\*[an-ic]\f[R](\\$2)\c
 .  if \\n[an*do-hyperlink] \{\
diff --git a/tmac/man.local b/tmac/man.local
index ed5706b41..6b30900f6 100644
--- a/tmac/man.local
+++ b/tmac/man.local
@@ -14,6 +14,16 @@
 .\" might prefer to remap it to bold ("B") instead.
 .\" .if n .ftr CW R
 .\"
+.\" A de facto standard URL format for man pages is recognized
+.\" everywhere except Apple, where different macOS applications expect
+.\" different formats.
+.\"   1: man:groff(1)           -- package default
+.\"   2: man:groff.1            -- Bwana (macOS)
+.\"   3: x-man-doc://1/groff(1) -- ManOpen (macOS)
+.\"   4: x-man-page://1/groff   -- Terminal.app, iTerm (macOS)
+.\" Set this register to configure which the `MR` macro uses.
+.\" .nr an*MR-URL-format 1
+.\"
 .\" Local Variables:
 .\" mode: nroff
 .\" fill-column: 72