[groff] 05/05: [ms]: Restore support for AT&T ms PN register.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 3d7a207e853468c78391ae66f9350a5328deac4b
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun May 2 06:12:42 2021 +1000

    [ms]: Restore support for AT&T ms PN register.
    
    * tmac/s.tmac (pg): Make register PN an alias of %.
    
    * doc/groff.texi (Differences from AT&T ms):
    * doc/ms.ms (Differences from AT&T ms):
    * tmac/groff_ms.7.man (Differences from troff ms): We don't need PN, and
      it was removed in commit 08291b40 (25 October 2020), but since it is
      documented in Lesk 1978 we're stuck with it.  Advise users to stick
      with %.  Also warn them of the hoop they must jump through if they
      redefine the page trap macro PT, which Lesk 1978 also encourages.
    
    Fixes <https://savannah.gnu.org/bugs/?59823>.
---
 ChangeLog           | 15 ++++++++++++++-
 doc/groff.texi      | 11 +++++++++++
 doc/ms.ms           | 36 ++++++++++++++++++++++++++++++++++++
 tmac/groff_ms.7.man | 33 +++++++++++++++++++++++++++++++++
 tmac/s.tmac         |  1 +
 5 files changed, 95 insertions(+), 1 deletion(-)

diff --git a/ChangeLog b/ChangeLog
index e143714..0ebe6a3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,10 +1,23 @@
 2021-05-02  G. Branden Robinson <g.branden.robinson@gmail.com>
 
-       Add regression test for Savannah #59923.
+       [ms]: Restore support for AT&T ms PN register.
+
+       * tmac/s.tmac (pg): Make register PN an alias of %.
+
+       * doc/groff.texi (Differences from AT&T ms):
+       * doc/ms.ms (Differences from AT&T ms):
+       * tmac/groff_ms.7.man (Differences from troff ms): We don't need
+       PN, and it was removed in commit 08291b40 (25 October 2020), but
+       since it is documented in Lesk 1978 we're stuck with it.  Advise
+       users to stick with %.  Also warn them of the hoop they must
+       jump through if they redefine the page trap macro PT, which Lesk
+       1978 also encourages.
 
        * tmac/tests/s_PN-works.sh: Test it.
        * tmac/tmac.am (tmac_TESTS): Run test.
 
+       Fixes <https://savannah.gnu.org/bugs/?59823>.
+
 2021-05-01  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        Restore default IP paragraph indentation after an SH call.
diff --git a/doc/groff.texi b/doc/groff.texi
index 1c4008e..fd7e10a 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -4221,6 +4221,17 @@ R} will right adjust lines, but it doesn't work''.  In 
@code{groff}
 @item
 @code{groff} @file{ms} handles @code{S} as the first argument to the
 @code{NH} macro specially, allowing explicit numbering of headings.
+
+@item
+@code{groff} @file{ms} supports the @code{PN} register, but it is not
+necessary; you can access the page number via the usual @code{%}
+register and use the @code{af} request to assign a different format to
+it if desired.@footnote{If you redefine the @file{ms} @code{PT} macro
+@c I wouldn't mention that, but Lesk 1978 encourages doing so.  :-/
+and desire special treatment of certain page numbers (like @samp{1}),
+you may need to handle a non-decimal page number format, as @code{groff}
+@file{ms}'s @code{PT} does; see the macro package source.  @code{groff}
+@file{ms} aliases the @code{PN} register to @code{%}.}
 @end itemize
 
 @Defmpreg {GS, ms}
diff --git a/doc/ms.ms b/doc/ms.ms
index 0654482..6d08d31 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -2445,6 +2445,42 @@ macros and
 .Acr AT&T
 .I "troff ms"
 macros.
+.
+.
+.PP
+.I "groff ms"
+supports the
+.CW PN
+register,
+but it is not necessary;
+you can access the page number via the usual
+.CW %
+register and use the
+.CW af
+request to assign a different format to it if desired.\**
+.FS
+If you redefine the
+.I ms
+.CW PT
+macro \" I wouldn't mention that, but Lesk 1978 encourages doing so. :-/
+and desire special treatment of certain page numbers
+(like
+.CW 1 \[rq], \[lq]
+you may need to handle a non-decimal page number format,
+as
+.I "groff ms" 's
+.CW .PT
+does;
+see the macro package source.
+.
+.I "groff ms"
+aliases the
+.CW PN
+register to
+.CW % .
+.FE
+.
+.
 .NH 2
 .BI troff
 macros not appearing in
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 1d4b512..1acd96f 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1696,6 +1696,39 @@ allowing explicit numbering of headings.
 .
 .
 .IP \[bu]
+.I groff ms
+supports the
+.B PN
+register,
+but it is not necessary;
+you can access the page number via the usual
+.B %
+register and use the
+.B af
+request to assign a different format to it if desired.
+.
+(If you redefine the
+.I ms
+.B PT
+macro \" I wouldn't mention that, but Lesk 1978 encourages doing so. :-/
+and desire special treatment of certain page numbers\[em]like
+.\" I wouldn't mention that, but Lesk 1978 encourages doing so.  :-/
+.RB \[lq] 1 \[rq]\[em]you
+may need to handle a non-decimal page number format,
+as
+.IR "groff ms" 's
+.B .PT
+does;
+see the macro package source.
+.
+.I groff ms
+aliases the
+.B PN
+register to
+.BR % .)
+.
+.
+.IP \[bu]
 The register
 .B GS
 is set to\~1 by the
diff --git a/tmac/s.tmac b/tmac/s.tmac
index 95ac843..765130d 100644
--- a/tmac/s.tmac
+++ b/tmac/s.tmac
@@ -495,6 +495,7 @@ along with this program.  If not, see 
<http://www.gnu.org/licenses/>.
 .als EH OH
 .als OF OH
 .als EF OH
+.aln PN % \" Lesk 1978 documents PN.
 .de PT
 .\" To compare the page number to 1, we need it in decimal.
 .ds pg*saved-page-number-format \\g%\"