[groff] 33/78: [docs]: Update discussion of ms page titles.

[G. Branden Robinson]

gbranden pushed a commit to branch branden-2023-04-07
in repository groff.

commit c58e38fa936a2e45ef65896e4a15ec2821a38d8c
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Apr 5 07:08:16 2023 -0500

    [docs]: Update discussion of ms page titles.
    
    * Mention the special behavior of the % character in titles.
    * Characterize traps as a formatter feature.
---
 doc/groff.texi      | 13 +++++++------
 doc/ms.ms           | 15 +++++++++++----
 tmac/groff_ms.7.man | 18 +++++++++++-------
 3 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index e662db212..91931b0c9 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -4230,8 +4230,9 @@ and even-numbered (verso) pages, respectively; the 
@code{OF} and
 @code{EF} macros define footers for them.
 @endDefmac
 
-By default, @file{ms} places no header on any page numbered ``1''
-(regardless of its number format).
+With either method, a percent sign @code{%} in header or footer text is
+replaced by the current page number.  By default, @file{ms} places no
+header on a page numbered ``1'' (regardless of its number format).
 
 @Defmac {P1, , ms}
 Typeset the header even on page@tie{}1.  To be effective, this macro
@@ -4246,10 +4247,10 @@ redefinition of the macros that are called when the 
@code{groff} traps
 that ordinarily cause the headers and footers to be output are sprung.
 @code{PT} (``page trap'') is called by @file{ms} when the header is to
 be written, and @code{BT} (``bottom trap'') when the footer is to be.
-The page location trap that @file{ms} sets up to format the header also
-calls the (normally undefined) @code{HD} macro after @code{PT}; you can
-define @code{HD} if you need additional processing after setting the
-header (for example, to draw a line below it).
+The @code{groff} page location trap that @file{ms} sets up to format the
+header also calls the (normally undefined) @code{HD} macro after
+@code{PT}; you can define @code{HD} if you need additional processing
+after setting the header (for example, to draw a line below it).
 @c Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
 The @code{HD} hook is a Berkeley extension.  Any such macros you
 (re)define must implement any desired specialization for odd-, even-, or
diff --git a/doc/ms.ms b/doc/ms.ms
index a3573e6b4..fd55fabbe 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -36,8 +36,8 @@
 .nr TC-MARGIN \w'00' \" expect 2-digit page numbers at most
 .ie t .nr PI 3.5n
 .el   .nr PI 4n
-.ND February 2023
-.EH '%''February 2023'
+.ND April 2023
+.EH '%''April 2023'
 .EF ''''
 .OH 'Using \f[I]groff\f[] with the \f[I]ms\f[] macros''%'
 .OF ''''
@@ -3197,9 +3197,14 @@ T}
 .
 .
 .PP
+With either method,
+a percent sign
+.B %
+in header or footer text is replaced by the current page number.
+.
 By default,
 .I ms
-places no header on any page numbered \[lq]1\[rq]
+places no header on a page numbered \[lq]1\[rq]
 (regardless of its number format).
 .
 .
@@ -3246,7 +3251,9 @@ and
 (\[lq]bottom trap\[rq])
 when the footer is to be.
 .
-The page location trap that
+The
+.I groff
+page location trap that
 .I ms
 sets up to format the header also calls the
 (normally undefined)
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 01afe61c7..64d4ad7e8 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1891,9 +1891,14 @@ macros define footers for them.
 .
 .
 .P
+With either method,
+a percent sign
+.B %
+in header or footer text is replaced by the current page number.
+.
 By default,
 .I ms
-places no header on any page numbered \[lq]1\[rq]
+places no header on a page numbered \[lq]1\[rq]
 (regardless of its number format).
 .
 .
@@ -1911,11 +1916,8 @@ This is a Berkeley extension.
 .P
 For even greater flexibility,
 .I ms
-is designed to permit the redefinition of the macros that are called
-when the
-.I groff
-traps that ordinarily cause the headers and footers to be output are
-sprung.
+permits redefinition of the macros called when the page header and
+footer traps are sprung.
 .
 .B PT
 (\[lq]page trap\[rq])
@@ -1927,7 +1929,9 @@ and
 (\[lq]bottom trap\[rq])
 when the footer is to be.
 .
-The page location trap that
+The
+.I groff
+page location trap that
 .I ms
 sets up to format the header also calls the
 (normally undefined)