[groff] 14/30: [mm]: Add new `Rfstyle` register.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit b563a25bf0ea46f85fc99e64d9d359d97a12151a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Oct 9 17:48:01 2024 -0500

    [mm]: Add new `Rfstyle` register.
    
    The package no longer superscripts _and_ brackets a reference mark (the
    `Rf` string).  Instead, the new `Rfstyle` register controls its
    formatting.  The default, 0, selects bracketing in nroff mode and
    superscripting in troff mode.  Set `Rfstyle` to 3 in a document to
    obtain groff mm's previous mark formatting behavior.
    
    * contrib/mm/m.tmac (initialization): Assign zero to `Rfstyle`.  Define
      new `ref*{n,t}roff-{(,)}` strings.  Define `Rf` in terms of new
      `ref*(` and `ref*)` strings below.  Call `ref*set-mark-style`.
    
      (ref*set-mark-style): New macro maps a `Rfstyle` to 1 (nroff-style) or
      2 (troff-style) as described above and defines `ref*(` and `ref*)`
      strings per that value.
    
      (RS): Call `ref*set-mark-style`, handling the case where the document
      changes its reference mark formatting style midstream.
    
    * contrib/mm/refer-mm.tmac ([., .]): Use new `ref*(` and `ref*)`
      strings.
    
    * contrib/mm/groff_mm.7.man (Macros) <RS>: Cross reference `Rfstyle`
      register description.
    
      (Strings) <Rf>: Drop incorrect (oversimplified) description of how the
      reference mark is formatted.
    
      (Registers) <Rfstyle>: Document it.
    
    NEWS: Add item.
---
 NEWS                      |  6 ++++++
 contrib/mm/ChangeLog      | 26 ++++++++++++++++++++++++
 contrib/mm/groff_mm.7.man | 51 ++++++++++++++++++++++++++++++++++++++---------
 contrib/mm/m.tmac         | 36 ++++++++++++++++++++++++++++++---
 contrib/mm/refer-mm.tmac  |  6 +++---
 5 files changed, 110 insertions(+), 15 deletions(-)

diff --git a/NEWS b/NEWS
index ef3f60076..ff94d0b3b 100644
--- a/NEWS
+++ b/NEWS
@@ -398,6 +398,12 @@ Macro packages
    now interprets an argument to its `-I` option in ens instead of ems
    by default.
 
+*  The m (mm) macro package no longer superscripts _and_ brackets a
+   reference mark (the `Rf` string).  Instead, the new `Rfstyle`
+   register controls its formatting.  The default, 0, selects bracketing
+   in nroff mode and superscripting in troff mode.  Set `Rfstyle` to 3
+   in a document to obtain groff mm's previous mark formatting behavior.
+
 *  The m (mm) macro package's `Li` register now defaults to 5 ens (not
    6) to align with the `Pi` register default.
 
diff --git a/contrib/mm/ChangeLog b/contrib/mm/ChangeLog
index e7cb91cb1..f99f03ea5 100644
--- a/contrib/mm/ChangeLog
+++ b/contrib/mm/ChangeLog
@@ -1,3 +1,29 @@
+2024-10-09  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       The package no longer superscripts _and_ brackets a reference
+       mark (the `Rf` string).  Instead, the new `Rfstyle` register
+       controls its formatting.  The default, 0, selects bracketing in
+       nroff mode and superscripting in troff mode.  Set `Rfstyle` to 3
+       in a document to obtain groff mm's previous mark formatting
+       behavior.
+
+       * m.tmac (initialization): Assign zero to `Rfstyle`.  Define new
+       `ref*{n,t}roff-{(,)}` strings.  Define `Rf` in terms of new
+       `ref*(` and `ref*)` strings below.  Call `ref*set-mark-style`.
+       (ref*set-mark-style): New macro maps a `Rfstyle` to 1
+       {nroff-style} or 2 {troff-style} as described above and defines
+       `ref*(` and `ref*)` strings per that value.
+       (RS): Call `ref*set-mark-style`, handling the case where the
+       document changes its reference mark formatting style midstream.
+
+       * refer-mm.tmac ([., .]): Use new `ref*(` and `ref*)` strings.
+
+       * groff_mm.7.man (Macros) <RS>: Cross reference `Rfstyle`
+       register description.
+       (Strings) <Rf>: Drop incorrect (oversimplified) description of
+       how the reference mark is formatted.
+       (Registers) <Rfstyle>: Document it.
+
 2024-10-09  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * m.tmac: Refactor.  Define new internal strings `ref*(` and
diff --git a/contrib/mm/groff_mm.7.man b/contrib/mm/groff_mm.7.man
index 542452552..c66956543 100644
--- a/contrib/mm/groff_mm.7.man
+++ b/contrib/mm/groff_mm.7.man
@@ -3466,6 +3466,13 @@ where the reference mark should be and write the 
reference between
 .BR RS / RF
 on an input line after the reference mark.
 .
+The mark may be bracketed,
+superscripted,
+or both;
+see the
+.B \%Rfstyle
+register.
+.
 If
 .I reference-string
 is specified,
@@ -4524,15 +4531,6 @@ the number is used by the next
 .B RS
 call.
 .
-In
-.I troff
-mode,
-the marker is superscripted;
-in
-.I nroff
-mode,
-it is surrounded by square brackets.
-.
 .
 .TP
 .B Rp
@@ -5437,6 +5435,41 @@ and
 .BR 0 ).
 .
 .
+.TP
+.B Rfstyle
+determines the format of the reference number in the
+.B Rf
+string.
+.
+.I "groff mm"
+maps
+.B 0
+to
+.B 1
+in
+.I nroff
+mode
+and
+.B 2
+in
+.I troff
+mode
+.RB ( 0 ).
+.
+.
+.IP
+.TS
+tab(@);
+lb lb
+l l.
+Value@Meaning
+0@automatic
+1@bracketed
+2@superscripted
+3@bracketed and superscripted
+.TE
+.
+.
 .\" XXX: Why is this not named `Rpej`?
 .TP
 .B Rpe
diff --git a/contrib/mm/m.tmac b/contrib/mm/m.tmac
index b955c758b..5c684c6b3 100644
--- a/contrib/mm/m.tmac
+++ b/contrib/mm/m.tmac
@@ -370,6 +370,9 @@ http://savannah.gnu.org/bugs/?group=groff.
 .ds Qrf See chapter \E*[Qrfh], page \E*[Qrfp].
 .\" output reference marks to standard error?
 .if !r Ref .nr Ref 0
+.\" reference mark style
+.\" 0 = auto (nroff/troff); 1 = bracket; 2 = superscript; 3 = both
+.nr Rfstyle 0
 .\" reference list page ejection policy
 .nr Rpe 0
 .\" use section-page page numbering?
@@ -3062,13 +3065,40 @@ exceeds depth of nested lists (\\n[li*lvl])
 .aln :R ref*nr
 .nr ref*nr-width 5n
 .nr ref*flag 0         \" for end-of-text
-.ds ref*( \v'-.4m'\s-3[
-.ds ref*) ]\s0\v'.4m'
-.ds Rf \*[ref*(]\\n+[ref*nr]\*[ref*)]
+.ds ref*nroff-( [
+.ds ref*troff-( \v'-.4m'\s-3
+.ds ref*nroff-) ]
+.ds ref*troff-) \s0\v'.4m'
+.
+.de ref*set-mark-style
+.nr ref*mark-style \\n[Rfstyle]
+.if \\n[Rfstyle]=0 \{\
+.      if n .nr ref*mark-style 1
+.      if t .nr ref*mark-style 2
+.\}
+.if \\n[ref*mark-style]=1 \{\
+.      ds ref*( \\*[ref*nroff-(]
+.      ds ref*) \\*[ref*nroff-)]
+.\}
+.if \\n[ref*mark-style]=2 \{\
+.      ds ref*( \\*[ref*troff-(]
+.      ds ref*) \\*[ref*troff-)]
+.\}
+.if \\n[ref*mark-style]=3 \{\
+.      ds ref*( \\*[ref*troff-(]\\*[ref*nroff-(]
+.      ds ref*) \\*[ref*nroff-)]\\*[ref*troff-)]
+.\}
+.rr ref*mark-style
+..
+.
+.ref*set-mark-style
+.ds Rf \\*[ref*(]\\n+[ref*nr]\\*[ref*)]
+.
 .\"
 .\" start reference
 .\"------------
 .de RS
+.ref*set-mark-style \" in case the document changed it
 .if !''\\$1' .ds \\$1 \*[ref*(]\\n[ref*nr]\*[ref*)]
 .nr ref*flag 1
 .am ref*mac
diff --git a/contrib/mm/refer-mm.tmac b/contrib/mm/refer-mm.tmac
index b0a8147a7..ae3ec5922 100644
--- a/contrib/mm/refer-mm.tmac
+++ b/contrib/mm/refer-mm.tmac
@@ -1,6 +1,6 @@
 .\" Refer support for mm macros.
 .\"
-.\" Copyright (C) 2011-2022 Free Software Foundation, Inc.
+.\" Copyright (C) 2011-2024 Free Software Foundation, Inc.
 .\"   Written by Werner Lemberg (wl@gnu.org)
 .\"
 .\" This file is part of groff.
@@ -45,8 +45,8 @@
 .ds ref*refnum-start \" empty
 .ds ref*refnum-end   .\"
 .
-.ds [. \v'-.4m'\s-3[\"
-.ds .] ]\s0\v'.4m'\"
+.ds [. \\*[ref*(]\"
+.ds .] \\*[ref*)]\"
 .
 .ds ref*spec!0  Q A T S V N P I C D O
 .ds ref*spec!1  Q A T J S V N P I C D O