[groff] 08/35: [ms]: Add new `RP` optional arguments.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d2ab4774f24480aaf4c0d55410e0c1e745b585f9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Jul 8 02:24:52 2022 -0500

    [ms]: Add new `RP` optional arguments.
    
    * tmac/s.tmac (RP): Recognize new optional arguments `no-renumber` and
      `no-repeat-info`, the latter as a synonym for the existing `no`.  The
      former suppresses the page number manipulation that normally occurs.
      Drop now-unnecessary `pn 0` request.
    
      (top level, cov*first-page-init, RP, cov*print): Rename
      `cov*rp-format` to `cov*use-rp-format` for clarity.
    
      (cov*break-page): New macro breaks the cover page at the end,
      resetting next page number to 1 only if desired by user.
    
      (cov*print, cov*rp-print): Call `cov*break-page` instead of invoking
      `bp`.
    
    * doc/groff.texi (Document Description Macros) <RP>:
    * doc/ms.ms (Document description macros) <RP>:
    * tmac/groff_ms.7.man (Document description macros) <RP>: Document them.
    
    * NEWS: Add item.
    
    Prompted by formatting Kernighan & Cherry's "Typesetting Mathematics --
    User's Guide (Second Edition) from the Unix V7 Programmer's Manual for
    PDF, where the page numbers in a viewer's navigation sidebar are out of
    sync with those formatted on the pages.
---
 ChangeLog           | 21 +++++++++++++++++++++
 NEWS                |  7 +++++++
 doc/groff.texi      | 17 +++++++++++------
 doc/ms.ms           | 27 +++++++++++++++++++++------
 tmac/groff_ms.7.man | 28 ++++++++++++++++++++++------
 tmac/s.tmac         | 31 +++++++++++++++++++++----------
 6 files changed, 103 insertions(+), 28 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 6b72624a..edbb811a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,24 @@
+2022-07-08  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * tmac/s.tmac (RP): Recognize new optional arguments
+       `no-renumber` and `no-repeat-info`, the latter as a synonym for
+       the existing `no`.  The former suppresses the page number
+       manipulation that normally occurs.  Drop now-unnecessary `pn 0`
+       request.
+       (top level, cov*first-page-init, RP, cov*print): Rename
+       `cov*rp-format` to `cov*use-rp-format` for clarity.
+       (cov*break-page): New macro breaks the cover page at the end,
+       resetting next page number to 1 only if desired by user.
+       (cov*print, cov*rp-print): Call `cov*break-page` instead of
+       invoking `bp`.
+
+       * doc/groff.texi (Document Description Macros) <RP>:
+       * doc/ms.ms (Document description macros) <RP>:
+       * tmac/groff_ms.7.man (Document description macros) <RP>:
+       Document them.
+
+       * NEWS: Add item.
+
 2022-07-08  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/s.tmac: Rename register `cov*rp-no` to
diff --git a/NEWS b/NEWS
index ae23a480..7adba61f 100644
--- a/NEWS
+++ b/NEWS
@@ -349,6 +349,13 @@ o The s (ms) macro package has added a hook macro, 
`FS-MARK`, which is
   distributed with groff as `pdfmark.ms`, uses this technique.  Thanks
   to Keith Marshall.
 
+o The s (ms) macro package's `RP` macro recognizes a new optional
+  argument, `no-renumber`, which suppresses the renumbering of the page
+  after the cover page as page 1.  It furthermore recognizes the
+  optional argument `no-repeat-info`, which has the same effect as `no`;
+  the latter will continue to be supported for backward compatibility.
+  Optional arguments to `RP` can be given in any order.
+
 o The "a4.tmac" file has been dropped from the distribution.  Its
   successor, "papersize.tmac", has been present and documented for
   nearly 20 years.  See subsection "Paper size" of groff(1).
diff --git a/doc/groff.texi b/doc/groff.texi
index fc7ebeb4..2a6e01e1 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3068,14 +3068,19 @@ except that @code{TL} is mandatory if any of @code{RP}, 
@code{AU},
 @code{AI}, or @code{AB} is called, and @code{AE} is mandatory if
 @code{AB} is called.
 
-@Defmac {RP, [@code{no}], ms}
+@Defmac {RP, [@code{no-repeat-info}] [@code{no-renumber}], ms}
 Use the ``report'' (@acronym{AT&T}: ``released paper'') format for your
 document, creating a separate cover page.  The default arrangement is to
-print most of the document description (title, author names and
-institutions, and abstract, but not the date) at the top of page@tie{}1.
-If the optional @code{no} argument is given, @file{ms} prints a cover
-page but does not repeat any of its information on page@tie{}1 (see the
-@code{DA} macro below regarding the date).
+place most of the document description (title, author names and
+institutions, and abstract, but not the date) at the top of the first
+page.  If the optional @code{no-repeat-info} argument is given,
+@file{ms} produces a cover page but does not repeat any of its
+information subsequently (but see the @code{DA} macro below regarding
+the date).  Normally, @code{RP} sets the page number following the cover
+page to@tie{}1.  Specifying the optional @code{no-renumber} argument
+suppresses this alteration.  Optional arguments can occur in any order.
+@code{no} is recognized as a synonym of @code{no-repeat-info} for
+@code{AT&T} compatibility.
 @endDefmac
 
 @Defmac {TL, , ms}
diff --git a/doc/ms.ms b/doc/ms.ms
index 9c77e065..63a5929e 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -643,28 +643,43 @@ lf(CR) lx.
 Macro  Description
 _
 .TH
-\&.RP \f[R][\f[]no\f[R]]       T{
+\&.RP \f[R][\f[I]option\f[] .\|.\|.]   T{
 Use the \[lq]report\[rq]
 (AT&T: \[lq]released paper\[rq])
 format for your document,
 creating a separate cover page.
 .
-The default arrangement is to print most of the document description
+The default arrangement is to place most of the document description
 (title,
 author names and institutions,
 and abstract,
 but not the date)
-at the top of page\~1.
+at the top of the first page.
 .
 If the optional
-.CW no
+.CW no\-repeat\-info
 argument is given,
 .I ms
-prints a cover page but does not repeat any of its information on
-page\~1
+produces a cover page but does not repeat any of its information
+subsequently
 (but see the
 .CW DA
 macro below regarding the date).
+.
+Normally,
+.CW .RP
+sets the page number following the cover page to\~1.
+.
+Specifying the optional
+.CW no\-renumber
+argument suppresses this alteration.
+.
+Optional arguments can occur in any order.
+.
+.CW no
+is recognized as a synonym of
+.CW no\-repeat\-info
+for AT&T compatibility.
 T}
 _
 \&.TL  T{
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 6513ccfe..e04bdd31 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -444,29 +444,45 @@ is called.
 .
 .
 .TP
-.BR ".RP\~" [ no ]
+.BR .RP\~ [ no\-repeat\-info ]\~[ no\-renumber ]
 Use the \[lq]report\[rq]
 (AT&T: \[lq]released paper\[rq])
 format for your document,
 creating a separate cover page.
 .
-The default arrangement is to print most of the document description
+The default arrangement is to place most of the document description
 (title,
 author names and institutions,
 and abstract,
 but not the date)
-at the top of page\~1.
+at the top of the first page.
 .
 If the optional
-.RB \[lq] no \[rq]
+.B no\-repeat\-info
 argument is given,
 .I ms
-prints a cover page but does not repeat any of its information on
-page\~1
+produces a cover page but does not repeat any of its information on
+subsequently
 (but see the
 .B DA
 macro below regarding the date).
 .
+Normally,
+.B .RP
+sets the page number following the cover page to\~1.
+.
+Specifying the optional
+.B no\-renumber
+argument suppresses this alteration.
+.
+Optional arguments can occur in any order.
+.\" Including the next sentence harms U.S. letter pagination... :-/
+.\"
+.\".RB \[lq] no \[rq]
+.\"is recognized as a synonym of
+.\".B no\-repeat\-info
+.\"for AT&T compatibility.
+.
 .
 .TP
 .B .TL
diff --git a/tmac/s.tmac b/tmac/s.tmac
index 5a8f89f7..11f50711 100644
--- a/tmac/s.tmac
+++ b/tmac/s.tmac
@@ -187,7 +187,7 @@ along with this program.  If not, see 
<http://www.gnu.org/licenses/>.
 .par@init
 .als RP cov*err-not-after-first-page
 .@init
-.ie \\n[cov*rp-format] \{\
+.ie \\n[cov*use-rp-format] \{\
 .      pg@cs-top
 .      als FS cov*FS
 .      als FE cov*FE
@@ -206,14 +206,21 @@ along with this program.  If not, see 
<http://www.gnu.org/licenses/>.
 .br
 \\*[FS]\\
 ..
-.nr cov*rp-format 0
+.nr cov*use-rp-format 0
+.\" If we add more cover page formats, these behaviors and names could
+.\" be generalized.
 .nr cov*rp-no-repeat-info 0
-.\" released paper format
+.nr cov*rp-no-renumber 0
+.\" report (AT&T: "released paper") document type
 .de RP
-.nr cov*rp-format 1
-.if \\n[.$] .if '\\$1'no' .nr cov*rp-no-repeat-info 1
+.nr cov*use-rp-format 1
+.while \\n[.$] \{\
+.      if '\\$1'no' .nr cov*rp-no-repeat-info 1
+.      if '\\$1'no-repeat-info' .nr cov*rp-no-repeat-info 1
+.      if '\\$1'no-renumber' .nr cov*rp-no-renumber 1
+.      shift
+.\}
 .if rPO .po \\n(POu
-.pn 0
 ..
 .de TL
 .br
@@ -365,16 +372,20 @@ along with this program.  If not, see 
<http://www.gnu.org/licenses/>.
 .de @div-end!cov*ab-div
 .AE
 ..
+.de cov*break-page
+.ie \\n[cov*rp-no-renumber] .bp
+.el .bp 1
+..
 .de cov*print
 .als cov*print @nop
 .ie d cov*tl-div \{\
-.      ie \\n[cov*rp-format] .cov*rp-print
+.      ie \\n[cov*use-rp-format] .cov*rp-print
 .      el .cov*draft-print
 .\}
 .el \{\
-.      if \\n[cov*rp-format] \{\
+.      if \\n[cov*use-rp-format] \{\
 .              @warning .RP format but no .TL
-.              bp 1
+.              .cov*break-page
 .              als FS @FS
 .              als FE @FE
 .              CHECK-FOOTER-AND-KEEP
@@ -416,7 +427,7 @@ along with this program.  If not, see 
<http://www.gnu.org/licenses/>.
 .if -\\n[FM]/2+1v+\\n[cov*page-length]<\\n[nl] \
 .      @error cover sheet overflow
 .pl \\n[cov*page-length]u
-.bp 1
+.cov*break-page
 .if !\\n[cov*rp-no-repeat-info] .cov*tl-au-print
 .rs
 .sp 1