[docs]: Update discussion of ms page titles.

* Mention the special behavior of the % character in titles.
* Characterize traps as a formatter feature.

2 files changed, 18 insertions, 10 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)