[groff] 09/11: [man]: Add `MR` macro for man page xrefs.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 999f5083158c77871efdcbbbc072df25039b021f
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Oct 5 20:16:36 2021 +1100

    [man]: Add `MR` macro for man page xrefs.
    
    [man]: Add `MR` macro for man page cross references.
    
    * tmac/an.tmac (an-prepare-page-title): After a possibly abbreviated man
      page title is determined, redefine `an-pageref` to set the title
      portion in the font stored in the `MF` string and bracket it with
      italic corrections if that font is thought to be oblique.
    
      (MR): Add macro to format the text of a man page cross reference, and
      hyperlink it on HTML and terminal output devices if permitted by the
      `U` register.
    
      (initialization): Define `MF` string as `I` if not already set.
      Define `an-lic` and `an-ic` strings as either empty or as containing
      italic corrections.
    
    * tmac/an-ext.tmac (MR): If the formatter is not GNU troff, define macro
      to format the text of a man page cross reference.
    
    * tmac/groff_man.7.man.in: Document it.
    
      (Description): Add macro to summary table.
    
      (Description/Hyperlink macros): Document new feature.  Note origin in
      Plan 9 troff.  [style] Add examples of use.
    
      (Description/Font style macros): Drop man page cross references from
      list of items whose typeface conventions are disputed, since we have a
      semantic macro now and a configurable means of resolving the problem.
    
      (History): Add `MR` item.
    
      (Options) <MF>: Document new string.
    
      (Files) <an-ext.tmac>: Revise discussion to accommodate `MR`.
    
      (Authors): Add myself an author of extension macros.
    
    * tmac/tests/an_MR-works.sh: Test it.
    * tmac/tmac.am (tmac_TESTS): Run test.
    
    * NEWS: Add item.
    
    Also, in man page(s), add an email address for Ingo and refer to authors
    using only surnames after first occurrence.
---
 ChangeLog                 |  37 +++++++++++
 NEWS                      |  29 +++++++++
 tmac/an-ext.tmac          |  14 +++++
 tmac/an.tmac              |  41 ++++++++++++
 tmac/groff_man.7.man.in   | 157 +++++++++++++++++++++++++++++++++++++++++-----
 tmac/tests/an_MR-works.sh |  55 ++++++++++++++++
 tmac/tmac.am              |   1 +
 7 files changed, 317 insertions(+), 17 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 79d4486..2a9afb7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,42 @@
 2021-10-05  G. Branden Robinson <g.branden.robinson@gmail.com>
 
+       [man]: Add `MR` macro for man page cross references.
+
+       * tmac/an.tmac (an-prepare-page-title): After a possibly
+       abbreviated man page title is determined, redefine `an-pageref`
+       to set the title portion in the font stored in the `MF` string
+       and bracket it with italic corrections if that font is thought
+       to be oblique.
+       (MR): Add macro to format the text of a man page cross
+       reference, and hyperlink it on HTML and terminal output devices
+       if permitted by the `U` register.
+       (initialization): Define `MF` string as `I` if not already set.
+       Define `an-lic` and `an-ic` strings as either empty or as
+       containing italic corrections.
+
+       * tmac/an-ext.tmac (MR): If the formatter is not GNU troff,
+       define macro to format the text of a man page cross reference.
+
+       * tmac/groff_man.7.man.in: Document it.
+       (Description): Add macro to summary table.
+       (Description/Hyperlink macros): Document new feature.  Note
+       origin in Plan 9 troff.  [style] Add examples of use.
+       (Description/Font style macros): Drop man page cross references
+       from list of items whose typeface conventions are disputed,
+       since we have a semantic macro now and a configurable means of
+       resolving the problem.
+       (History): Add `MR` item.
+       (Options) <MF>: Document new string.
+       (Files) <an-ext.tmac>: Revise discussion to accommodate `MR`.
+       (Authors): Add myself an author of extension macros.
+
+       * tmac/tests/an_MR-works.sh: Test it.
+       * tmac/tmac.am (tmac_TESTS): Run test.
+
+       * NEWS: Add item.
+
+2021-10-05  G. Branden Robinson <g.branden.robinson@gmail.com>
+
        * tmac/an.tmac (SH, SS): Invoke `ne` request _before_ performing
        font remapping: any page-breaking decision will be taken before
        the remapping happens, and so won't be in effect across a page
diff --git a/NEWS b/NEWS
index d8da06e..3b0f8b1 100644
--- a/NEWS
+++ b/NEWS
@@ -136,6 +136,35 @@ o The an (man) macro package can now produce clickable 
hyperlinks within
   "grotty(1)" and no additional garbage characters, then you may wish to
   edit "man.local" to remove the lines that disable this feature.
 
+o The an (man) macro package supports a new macro, "MR", intended for
+  use by man page cross references in preference to the font style
+  alternation macros historically used.  Where before you would write
+    .BR ls (1).
+  or
+    .IR ls (1).
+  you should now write
+    .MR ls 1 .
+  (the third argument, typically used for trailing punctuation, is
+  optional).  Because the macro semantically identifies a man page, it
+  also creates a clickable hyperlink ("man:ls(1)" for the above example)
+  on supporting devices.  A new string, MF, defines the font to be used
+  for setting man page titles (the first argument to .MR and .TH),
+  permitting its configuration by distributions, sites, and users.
+
+  The MR macro is offered for compatibility with Plan 9 troff, which
+  introduced it in August 2020, and to ameliorate several long-standing
+  problems with man page cross references: (1) the package's lack of
+  inherent hyperlink support for them; (2) false-positive identification
+  of strings resembling man page cross references (as can happen with
+  "exit(1)", "while(1)", "sleep(5)", "time(0)" and others) by terminal
+  emulators and other programs; (3) the unwanted intrusion of hyphens in
+  man page names, which frustrates copy-and-paste operations (this
+  problem has always been avoidable through use of the \% escape
+  sequence, but cross references are frequent in man pages and some page
+  authors are inexpert *roff users); and (4) deep divisions in man page
+  maintenance communities over which typeface should be used to set the
+  man page title (italics, roman, or bold).
+
 o Part of the an (man) macro package has been renamed from "an-old.tmac"
   to "an.tmac", replacing a file that sourced the "andoc.tmac" wrapper.
   This means that the "-man" argument to groff (or nroff, or troff) will
diff --git a/tmac/an-ext.tmac b/tmac/an-ext.tmac
index 7a45222..a6f6d6a 100644
--- a/tmac/an-ext.tmac
+++ b/tmac/an-ext.tmac
@@ -193,6 +193,20 @@
 ..
 .
 .
+.\" Set a man page cross reference.
+.\" .MR page-title page-section [trailing-text]
+.if !\n(.g \{\
+.  de MR
+.    nh
+.    ie \\n(.$=1 \
+.      I \\$1
+.    el \
+.      IR \\$1 (\\$2)\\$3
+.    hy \\n(HY
+..
+.\}
+.
+.
 .\" Continuation line for .TP header.
 .de TQ
 .  br
diff --git a/tmac/an.tmac b/tmac/an.tmac
index 7de948f..f4686b2 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -367,6 +367,8 @@
 .    nr an-header-width \
        \\w'\\*[an-pageref]\\*[an-extra3]\\*[an-pageref]'
 .  \}
+.  ds an-pageref \\*[an-lic]\f[\\*[MF]]\\*[an-title-abbv]\\*[an-ic]\
+\f[R](\\*[an-section])\"
 .  rr an-title-length-prev
 .  rr an-mark1
 .  rr an-mark2
@@ -801,6 +803,29 @@
 .    RB "[" "\\$1" "]"
 ..
 .
+.\" Set a man page cross reference.
+.\" .MR page-title page-section [trailing-text]
+.de1 MR
+.  if ((\\n[.$] < 2) : (\\n[.$] > 3)) \
+.    an-style-warn .\\$0 expects 2 or 3 arguments, got \\n[.$]
+.  nh
+.  if (\\n[U] & \\n[mU]) \{\
+.    if \\n(mH \
+\X^html:<a href="man:\\$1(\\$2)">^\c
+.    if \\n(mY \
+\X^tty: link man:\\$1(\\$2)^\c
+.  \}
+\&\\*[an-lic]\f[\\*[MF]]\\$1\\*[an-ic]\f[R](\\$2)\c
+.  if (\\n[U] & \\n[mU]) \{\
+.    if \\n(mH \
+\X^html:</a>^\c
+.    if \\n(mY \
+\X^tty: link^\c
+.  \}
+\&\\$3
+.  hy \\n[HY]
+..
+.
 .\" tbl(1) table support
 .
 .\" Start table.
@@ -1093,6 +1118,22 @@
 .rr an-HF-length
 .rm an-heading-style
 .
+.\" man page title font
+.if !d MF \
+.  ds MF I\"
+.
+.\" Define italic correction strings.  Initially, they are empty.  If MF
+.\" is an oblique style, append the corrections.
+.ds an-lic \" left italic correction
+.ds an-ic \" italic correction
+.ds an-page-title-style \*[MF]\"
+.substring an-page-title-style -1 -1
+.if '\*[an-page-title-style]'I' \{\
+.  as an-lic \,\"
+.  as an-ic \/
+.\}
+.rm an-page-title-style
+.
 .if \n[cR] \
 .  an-set-up-continuous-rendering
 .
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 7410daf..218fe9f 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -154,6 +154,7 @@ _
 \&.IR  Italic, roman alternating       Font style macros
 \&.LP  (Left) paragraph        Paragraph macros
 \&.ME  Mail-to end     Hyperlink macros
+\&.MR  Man page cross reference        Hyperlink macros
 \&.MT  Mail-to start   Hyperlink macros
 \&.P   Paragraph       Paragraph macros
 \&.PP  Paragraph       Paragraph macros
@@ -1118,14 +1119,46 @@ _endif()dnl
 .SS "Hyperlink macros"
 .\" ====================================================================
 .
+Man page cross references
+_ifstyle()dnl
+like
+.MR ls 1
+_endif()dnl
+are best presented with
+.BR .MR .
+.
 Email addresses are bracketed with
 .BR .MT / .ME
 and other forms of hyperlink with
 .BR .UR / .UE .
 .
+Hyperlinked text is supported on the
+.B html
+and
+.B tty
+output devices;
+terminals and pager programs must support EMCA-48 OSC\~8 escape
+sequences
+(see
+.MR grotty @MAN1EXT@ ).
+.
+When device support is unavailable or disabled with the
+.B U
+register
+(see section \[lq]Options\[rq] below),
+.B .MT
+and
+.B .UR
+URIs are rendered after the linked text.
+.
 .
 .P
-These macros are GNU extensions not defined on systems running
+.BR .MT ,
+.BR .ME ,
+.BR .UR ,
+and
+.B .UE
+are GNU extensions not defined on systems running
 AT&T,
 Plan\~9,
 or
@@ -1135,6 +1168,54 @@ see
 .I an\-ext.tmac
 in section \(lqFiles\(rq below.
 .
+Plan\~9
+.I troff \" Plan 9
+implements
+.BR .MR .
+.
+.
+.TP
+.BI .MR "\~page-title page-section"\c
+.RI \~[ trailing-text ]
+Set a man page cross reference as
+.RI \[lq] page-title ( page-section )\[rq].
+.
+If
+.I trailing-text
+(typically punctuation)
+is specified,
+it follows the closing parenthesis without intervening space.
+.
+Hyphenation is disabled while the cross reference is set.
+.
+.I page-title
+is set in the font specified by the
+.B MF
+string.
+.
+The cross reference hyperlinks to a URI of the form
+.RB \[lq] man:\c
+.IR page-title ( page-section )\[rq].
+.
+.
+_ifstyle()dnl
+.RS
+.IP
+.EX
+The output driver
+\&.MR grops 1
+produces Postscript from
+\&.I troff
+output.
+\&.
+The Ghostscript program (\[rs]c
+\&.MR gs 1)
+interprets Postscript and PDF.
+.EE
+.RE
+_endif()dnl
+.
+.
 .
 .TP
 .BI .MT " address"
@@ -1316,8 +1397,7 @@ Because font styles are presentational rather than 
semantic,
 conflicting traditions have arisen regarding which font styles should be
 used to mark file or path names,
 environment variables,
-in-line literals,
-and man page cross-references.
+and inlined literals.
 _endif()dnl
 .
 .
@@ -2919,6 +2999,16 @@ SunOS\~4.0 (1988) may have been the first to support
 .\" time and did not support the macro.  SunOS 4.0.3 (May 1989)
 .\" contained over 2,100 uses of .SB.
 .
+Plan\~9
+.I troff \" Plan 9
+introduced
+.B .MR
+in 2020.
+.\" https://github.com/9fans/plan9port/commit/\
+.\"  977b25a76ae8263e53fb4eb1abfc395769f23e3d
+.\"  d32deab17bfffa5bffc5fab3e6577558e40888c5
+.\"  36cd4c58c1346375b98f517fb8568be5bb47618d
+.
 .
 .\" ====================================================================
 .SH Options
@@ -3121,6 +3211,30 @@ is used for the title length.
 .
 .
 .TP
+.BI \-dMF= man-page-title-font
+Set the font used for man page titles named in
+.B .TH
+and
+.B .MR
+calls;
+the default is
+.RB \(lq I \(rq
+(italic).
+.
+Any valid argument to
+.IR groff 's
+\[lq].ft\[rq] request may be used;
+see
+.MR groff @MAN7EXT@ .
+.
+If the
+.B MF
+string ends in \[lq]I\[rq],
+it is assumed to be an oblique typeface,
+and italic corrections are applied before and after man page titles.
+.
+.
+.TP
 .BI \-rP n
 Start enumeration of pages at
 .I n
@@ -3260,15 +3374,21 @@ The extension macro definitions for
 .BR .UR / .UE ,
 and
 .BR .MT / .ME
-are contained in this file,
-which is written to be compatible with AT&T
-.I troff
+are contained in this file;
+if the formatter is not GNU
+.IR troff , \" GNU
+it also provides an
+.B .MR
+implementation that does not attempt hyperlinking.
+.
+These macros are written to be compatible with AT&T
+.I troff \" AT&T
 and permissively licensed\(emnot copylefted.
 .
 Man page authors concerned about portability to legacy Unix systems are
 encouraged to copy these definitions into their pages,
 and maintainers of
-.I troff
+.I troff \" generic
 implementations or work-alike systems that format man pages are
 encouraged to re-use them.
 .
@@ -3622,10 +3742,13 @@ macro package was written by James Clark and 
contributors.
 The extension macros were written by
 .MT wl@\:gnu\:.org
 Werner Lemberg
-.ME
-and
+.ME ,
 .MT esr@\:thyrsus\:.com
 Eric S.\& Raymond
+.ME ,
+and
+.MT g.branden\:.robinson@\:gmail\:.com
+G.\& Branden Robinson
 .ME .
 .
 .
@@ -3635,16 +3758,16 @@ This document was originally written for the Debian 
GNU/Linux system by
 Susan G.\& Kleinmann
 .ME .
 .
-It was corrected and updated by Werner Lemberg and
-.MT g.branden\:.robinson@\:gmail\:.com
-G.\& Branden Robinson
-.ME .
+It was corrected and updated by Lemberg and Robinson.
 .
-The extension macros were documented by Eric S.\& Raymond.
+The extension macros were documented by Raymond and Robinson.
 _ifstyle()dnl
-He also originated the portability section,
-to which Ingo Schwarze contributed most of the material on escape
-sequences.
+Raymond also originated the portability section,
+to which
+.MT schwarze@\:usta\:.de
+Ingo Schwarze
+.ME
+contributed most of the material on escape sequences.
 _endif()dnl
 .
 .
diff --git a/tmac/tests/an_MR-works.sh b/tmac/tests/an_MR-works.sh
new file mode 100755
index 0000000..f185562
--- /dev/null
+++ b/tmac/tests/an_MR-works.sh
@@ -0,0 +1,55 @@
+#!/bin/sh
+#
+# Copyright (C) 2021 Free Software Foundation, Inc.
+#
+# This file is part of groff.
+#
+# groff is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# groff is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+groff="${abs_top_builddir:-.}/test-groff"
+
+# Regression-test Savannah #61279.
+#
+# If a SH or SS (sub)section heading was about to be output at the
+# bottom of a page but wasn't because of the vertical space .ne-eded,
+# we want to ensure that font remapping for the headings doesn't affect
+# page footers and headers.
+
+FAIL=
+
+INPUT='.TH \\fIfoo\\fP 1 2021-10-04 "groff test suite"
+.SH Name
+foo \\- a command with a very short name
+.SH Description
+The real work is done by
+.MR bar 1 .'
+
+OUTPUT=$(echo "$INPUT" | "$groff" -Tascii -man -Z)
+
+# Expected:
+#   87  tby
+#   88  wf2
+#   89  h24
+#   90  tbar
+#   91  f1
+#   92  t(1).
+#   93  n40 0
+
+set -e
+echo "$OUTPUT" | nl | grep -E '88[[:space:]]+wf2'
+echo "$OUTPUT" | nl | grep -E '91[[:space:]]+f1'
+echo "$OUTPUT" | nl | grep -E '92[[:space:]]+t\(1\).'
+
+# vim:set ai et sw=4 ts=4 tw=72:
diff --git a/tmac/tmac.am b/tmac/tmac.am
index 7febbb6..4f3135b 100644
--- a/tmac/tmac.am
+++ b/tmac/tmac.am
@@ -159,6 +159,7 @@ tmac_TESTS = \
   tmac/tests/an_CT-register-unspecified.sh \
   tmac/tests/an_FT-bad-value-should-not-trash-titles.sh \
   tmac/tests/an_LL-init-sanely.sh \
+  tmac/tests/an_MR-works.sh \
   tmac/tests/an_TH-repairs-ad-damage.sh \
   tmac/tests/an_TH-repairs-hy-damage.sh \
   tmac/tests/an_TS-do-not-keep-tables-when-cR-set.sh \