[groff] 12/28: tmac/an.tmac: Annotate macOS man URL perversity.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 1970969d85db5922cd188f475aaa295945e36b65
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Mar 3 18:58:36 2024 -0600

    tmac/an.tmac: Annotate macOS man URL perversity.
    
    I had forgotten why we couldn't just have a user-configurable prefix
    string for man page URLs.  Prompted by having to port this pain to mdoc.
---
 tmac/an.tmac | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/tmac/an.tmac b/tmac/an.tmac
index 925d6d56d..9773b2848 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -1264,6 +1264,17 @@ contains unsupported escape sequence
 .\" 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.
+.\"
+.\" Given a man page reference id(section) (like ls(1)), we have these.
+.\"
+.\" man:id(section)                  - GNOME, KDE   (Linux)
+.\" x-man-page://section/id          - Terminal.app (macOS 10.3+)
+.\" man:id.section                   - Bwana        (macOS)
+.\" x-man-doc://section/id(section)  - ManOpen      (macOS)
+.\"
+.\" A configurable prefix/schema string is inadequate because the
+.\" arrangement of the rest of the URL is variable.  Further, the schema
+.\" doesn't unambiguously indicate the remainder of the URL format.
 .nr an*MR-URL-format 1
 .
 .\" Set a man page cross reference.
@@ -1271,13 +1282,13 @@ contains unsupported escape sequence
 .de1 MR
 .  if ((\\n[.$] < 2) : (\\n[.$] > 3)) \
 .    an-style-warn .\\$0 expects 2 or 3 arguments, got \\n[.$]
-.  ds an*url man:\\$1(\\$2)\" used everywhere but macOS
+.  ds an*url man:\\$1(\\$2)\"
 .  if (\\n[an*MR-URL-format] = 2) \
-.    ds an*url x-man-page://\\$2/\\$1\" macOS/Mac OS X since 10.3
+.    ds an*url x-man-page://\\$2/\\$1\"
 .  if (\\n[an*MR-URL-format] = 3) \
-.    ds an*url man:\\$1.\\$2\" Bwana (Mac OS X)
+.    ds an*url man:\\$1.\\$2\"
 .  if (\\n[an*MR-URL-format] = 4) \
-.    ds an*url x-man-doc://\\$2/\\$1(\\$2)\" ManOpen (Mac OS X pre-2005)
+.    ds an*url x-man-doc://\\$2/\\$1(\\$2)\"
 .  nh
 .  if \\n[an*do-hyperlink] \{\
 .    if '\*[.T]'html' \