[groff] 02/08: [ms]: Move P1 description and make clarifications.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d013a2e39c886b4f6375f39e48ef7af2e2f33abd
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Mar 21 17:14:27 2021 +1100

    [ms]: Move P1 description and make clarifications.
    
    The P1 macro (from 4.2BSD) isn't a document description macro, but a
    header management macro.
    
    * doc/groff.texi (ms Document Description Macros): Simplify sentence by
      listing the macros that require .TL to be called.  Move footnote
      regarding efficacy of ND macro from section introduction to ND
      description.  Move documentation of P1 macro from here...
      (ms Headers and Footers): ...to here.
    
    * doc/ms.ms:
    * tmac/groff_ms.7.man: Syncronize with above changes.
---
 doc/groff.texi      | 23 +++++++---------
 doc/ms.ms           | 78 +++++++++++++++++++++++++++--------------------------
 tmac/groff_ms.7.man | 66 ++++++++++++++++++++-------------------------
 3 files changed, 79 insertions(+), 88 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 2a16789..2b1022d 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2918,11 +2918,8 @@ Define these data by using the macros below in the order 
shown;
 @code{DA} or @code{ND} can be called to set the document date (or other
 identifier) at any time before (a) the abstract, if present, or (b) the
 end of the first page.  Use of these macros is optional, except that
-@code{TL} is mandatory if any other document description macro is
-called,@footnote{Strictly, a @code{TL} call is not mandated by @code{DA}
-or @code{ND}, but the latter has no visible effect in the absence of a
-cover page when the default footers are used (@pxref{ms Headers and
-Footers}).} and @code{AE} is mandatory if @code{AB} is called.
+@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}
 Use the ``report'' (@acronym{AT&T}: ``released paper'') format for your
@@ -2935,14 +2932,6 @@ page but does not repeat any of its information on 
page@tie{}1 (see the
 @code{DA} macro below regarding the date).
 @endDefmac
 
-@Defmac {P1, , ms}
-Print the header on page@tie{}1.  The default is to suppress the header
-on that page.  This is a Berkeley extension.@footnote{Version@tie{}10
-@c possibly V9
-Research Unix supported a pair of @code{P1} and @code{P2} macros (for
-setting code examples); @code{groff} @file{ms} does not.}
-@endDefmac
-
 @Defmac {TL, , ms}
 Specify the document title.  @file{ms} collects text on input lines
 following a call to this macro into the title until reaching an
@@ -3873,6 +3862,14 @@ You can replace the quote (@code{'}) marks with any 
character not
 appearing in the header or footer text.
 @endDefmac
 
+@Defmac {P1, , ms}
+Print the header on page@tie{}1.  By default, no header is printed on
+that page.  This is a Berkeley extension.@footnote{Version@tie{}10
+@c possibly V9
+Research Unix supported a pair of @code{P1} and @code{P2} macros (for
+setting code examples); @code{groff} @file{ms} does not.}
+@endDefmac
+
 To specify custom header and footer processing, redefine the following
 macros:
 
diff --git a/doc/ms.ms b/doc/ms.ms
index 7c5972a..357865d 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -408,21 +408,13 @@ or (b) the end of the first page.
 Use of these macros is optional,
 except that
 .CW .TL
-is mandatory if any other document description macro is called,\**
-.
-.FS
-Strictly,
-a
-.CW .TL
-call is not mandated by
-.CW .DA
+is mandatory if any of
+.CW .RP ,
+.CW .AU ,
+.CW .AI ,
 or
-.CW .ND ,
-but the latter has no visible effect in the absence of a cover page when
-the default footers are used.
-.\" TODO: (see section \[lq]Headers and Footers\[rq] below).
-.FE
-.
+.CW .AB
+is called,
 and
 .CW .AE
 is mandatory if
@@ -463,27 +455,6 @@ page\~1
 macro below regarding the date).
 T}
 _
-\&.P1  T{
-Print the header on page\~1.
-.
-The default is to suppress the header on that page.
-.
-This is a Berkeley extension.\**
-.
-.FS
-Version\~10
-.\" possibly V9
-Research Unix supported a pair of
-.CW P1
-and
-.CW P2
-macros
-(for setting code examples);
-.I "groff ms"
-does not.
-.FE
-T}
-_
 \&.TL  T{
 Specify the document title.
 .
@@ -549,13 +520,12 @@ _
 Print the current date,
 or any
 .I x , arguments\~ x
-in footers,
-and,
 if
 .CW .RP
 is also called,
 left-aligned after other document description information on the cover
-page.
+page,
+but not in footers.
 .
 This is the
 .I "groff ms"
@@ -1988,6 +1958,38 @@ The syntax for these macros is as follows:
 .LP
 You can replace the neutral apostrophes (\[aq]) with any character not
 appearing in the header or footer text.
+.
+.
+.TS
+box;
+lb lb
+lf(CR) lx.
+Macro  Description
+_
+\&.P1  T{
+Print the header on page\~1.
+.
+By default,
+no header is printed on that page.
+.
+This is a Berkeley extension.\**
+.
+.FS
+Version\~10
+.\" possibly V9
+Research Unix supported a pair of
+.CW P1
+and
+.CW P2
+macros
+(for setting code examples);
+.I "groff ms"
+does not.
+.FE
+T}
+.TE
+.
+.
 .\" ------------------------
 .KS
 .NH 2
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index babef08..0e586c2 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -302,17 +302,13 @@ or (b) the end of the first page.
 Use of these macros is optional,
 except that
 .B .TL
-is mandatory if any other document description macro is called
-(strictly,
-a
-.B .TL
-call is not mandated by
-.B .DA
+is mandatory if any of
+.BR .RP ,
+.BR .AU ,
+.BR .AI ,
 or
-.BR .ND ,
-but the latter has no visible effect in the absence of a cover page when
-the default footers are used)
-.\" TODO: (see subsection \[lq]Headers and Footers\[rq] below).
+.B .AB
+is called,
 and
 .B .AE
 is mandatory if
@@ -348,26 +344,6 @@ macro below regarding the date).
 .
 .
 .TP
-.B .P1
-Print the header on page\~1.
-.
-The default is to suppress the header on that page.
-.
-This is a Berkeley extension.
-.
-(Version\~10
-.\" possibly V9
-Research Unix supported a pair of
-.B P1
-and
-.B P2
-macros
-[for setting code examples];
-.I groff ms
-does not.)
-.
-.
-.TP
 .B .TL
 Specify the document title.
 .
@@ -439,17 +415,12 @@ page.
 Print the current date,
 or any
 .RI arguments\~ x ,
-in footers,
-and,
 if
 .B .RP
 is also called,
 left-aligned after other document description information on the cover
-page.
-.
-This is the
-.I groff ms
-default.
+page,
+but not in footers.
 .
 .
 .TP
@@ -1349,6 +1320,27 @@ You can replace the quote (\[aq]) marks with any 
character not
 appearing in the header or footer text.
 .
 .
+.TP
+.B .P1
+Print the header on page\~1.
+.
+By default,
+no header is printed on that page.
+.
+This is a Berkeley extension.
+.
+(Version\~10
+.\" possibly V9
+Research Unix supported a pair of
+.B P1
+and
+.B P2
+macros
+[for setting code examples];
+.I groff ms
+does not.)
+.
+.
 .IP \[bu]
 You can redefine the
 .B PT