[groff] 04/05: [ms]: Revise documentation of cover page macros.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 5be3f4fce7f47ca2a9296b7d48fd16a0ebb40648
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Mar 20 20:13:02 2021 +1100

    [ms]: Revise documentation of cover page macros.
    
    * doc/groff.texi (ms Document Structure):
      - Say that macros are "called", not "invoked", for consistency with
        other documentation.
      - Stop providing mnemonic for RP macro here, since it has two
        different ones.
      - Loosen claim: .RP does not have to be the first line of an input
        document; it simply needs to be early.
      - More carefully distinguish between what groff (or troff) does and
        what the macro package does.
      - Say "document description" instead of "cover page [information]"--a
        cover page is only present if .RP is called.
      - Be more clear that multiple authors can be declared with .AU.
      - Be more clear that the arguments to .DA or .ND need not be a date.
      - Refer to the "body" of the text additionally as the "main matter",
        since we also must cope with the subjects of tables of contents and
        indices.
    
      (ms Cover Page Macros):
      - Rename node/section to "ms Document Description Macros".  Update
        node structure accordingly.
      - Add motivating paragraph to introduce section.
      - Clarify ordering & presence restrictions on cover page macro calls.
      - Describe macros using imperative mood instead of sentence fragments.
      - Describe diversion-creating macros in a way that suggests their
        operation (without using the technical term).
      - Be more clear about what macro calls terminate these diversions.
      - Say "cover page" instead of "title page".
      - Be specific that the document "date" (DA/ND arguments) appear on a
        cover page but not otherwise prior to the main matter.
      - <RP> Be more specific about default placement of cover page
        information.
      - <RP> Note AT&T expansion of macro name.
      - <P1> Document as Berkeley Unix extension.  Note existence of
        conflicting V10 Unix macro.
      - <AU> Replace example of multiple authors with explanatory prose.
      - <AI> Clarify behavior when called multiple times.
      - <DA> Give argument(s) a metasyntactic variable instead of merely an
        ellipsis.
      - <DA> Undocument this as the "nroff default".  GNU ms does not work
        this way.
      - <ND> Make synopsis consistent with DA since it treats its arguments
        the same way.
      - Use more idiomatic input in the example.
    
    * doc/ms.ms:
      - Add empty request macro between sentences.
      - Add two empty request macros where vertical space is expected.
      - Synchronize language with our Texinfo manual.
    
      (General structure of an -ms document):
      - Convert colon-terminated sentence fragment to a complete sentence.
    
      (Cover page macros):
      - Rename section to "Document description macros".  Update references.
    
    * tmac/groff_ms.7.man:
      - Synchronize language with doc/ms.ms, omitting new motivational
        paragraph since this man page will ultimately become a relatively
        terse reference document.
---
 ChangeLog           |   7 ++
 doc/groff.texi      | 184 ++++++++++++++++---------------
 doc/ms.ms           | 307 +++++++++++++++++++++++++++++++++++-----------------
 tmac/groff_ms.7.man | 240 ++++++++++++++++++++++++++++------------
 4 files changed, 480 insertions(+), 258 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index aaffd21..dc6d53e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2021-03-20  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * doc/groff.texi (ms Cover Page Macros):
+       * doc/ms.ms (Cover page macros):
+       * tmac/groff_ms.7.man (Usage/Cover page macros): Revise and
+       rename (sub)sections to "Document description macros".
+
 2021-03-15  Dave Kemper <saint.snit@gmail.com>
 
        * Makefile.am: Fix typos.  Thanks to Bjarni Ingi Gislason for
diff --git a/doc/groff.texi b/doc/groff.texi
index 7125b61..53c8bf1 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2489,7 +2489,7 @@ equations, diagrams, and standardized bibliographic 
citations.
 * ms Introduction::
 * ms Document Structure::
 * ms Document Control Settings::
-* ms Cover Page Macros::
+* ms Document Description Macros::
 * ms Body Text::
 * ms Page Layout::
 * Differences from AT&T ms::
@@ -2552,29 +2552,29 @@ blank lines.  Longer documents have a structure as 
follows.
 
 @table @strong
 @item Document type
-If you invoke the @code{RP} (report) macro on the first line of the
-document, @file{ms} prints the cover page information on its own
-page; otherwise it prints the information (if any) on the first page
-with your document text immediately following.  Some document types
-found in @acronym{AT&T} @code{troff} are specific to @acronym{AT&T} or
-Berkeley, and are not supported in @code{groff}.
+If you call the @code{RP} macro at the beginning of your document,
+@file{ms} prints the document description on its own page; otherwise it
+prints the information (if any) on the first page with your document
+text immediately following.  Some document types found in other
+@file{ms} implementations are specific to @acronym{AT&T} or Berkeley,
+and are not supported in @code{groff} @file{ms}.
 
 @item Format and layout
 By setting registers (and one string), you can change your document's
 type (font and point size), margins, spacing, headers and footers, and
 footnotes.  @xref{ms Document Control Settings}.
 
-@item Cover page
-A cover page consists of a title, the author's name and institution, an
-abstract, and the date.@footnote{Actually, only the title is required.}
-@xref{ms Cover Page Macros}.
+@item Document description
+A document description consists of any of: a title, one or more authors'
+names and affiliated institutions, an abstract, and a date or other
+identifier.  @xref{ms Document Description Macros}.
 
-@item Body
-Following the cover page is your document.  @file{ms} supports highly
-structured documents consisting of paragraphs interspersed with
-multi-level headings (chapters, sections, subsections, and so forth) and
-augmented by lists, footnotes, tables, diagrams, and similar.  @xref{ms
-Body Text}.
+@item Body text
+The main matter of your document follows its description (if any).
+@file{ms} supports highly structured text consisting of paragraphs
+interspersed with multi-level headings (chapters, sections, subsections,
+and so forth) and augmented by lists, footnotes, tables, diagrams, and
+similar.  @xref{ms Body Text}.
 
 @item Table of contents
 Longer documents usually include a table of contents, which you can
@@ -2593,7 +2593,7 @@ placed in the output by @file{ms}.}
 
 @c ---------------------------------------------------------------------
 
-@node ms Document Control Settings, ms Cover Page Macros, ms Document 
Structure, ms
+@node ms Document Control Settings, ms Document Description Macros, ms 
Document Structure, ms
 @subsection Document control settings
 @cindex @code{ms} macros, document control settings
 
@@ -2905,85 +2905,94 @@ Default: 2@dmn{n}.
 
 @c ---------------------------------------------------------------------
 
-@node ms Cover Page Macros, ms Body Text, ms Document Control Settings, ms
-@subsection Cover page macros
-@cindex @code{ms} macros, cover page
-@cindex cover page macros, [@code{ms}]
-
-Use the following macros to create a cover page for your document in the
-order shown.
+@node ms Document Description Macros, ms Body Text, ms Document Control 
Settings, ms
+@subsection Document Description Macros
+@cindex @code{ms} macros, document description
+@cindex document description macros, [@code{ms}]
+
+All but the simplest documents bear a title.  As their level of
+sophistication (or complexity) increases, they tend to acquire dates of
+revision, explicitly identified authors, sponsoring institutions for
+authors, and, at the rarefied heights, an abstract of their content.
+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.
 
 @Defmac {RP, [@code{no}], ms}
-Specifies the report format for your document.  The report format
-creates a separate cover page.  The default action (no @code{RP} macro)
-is to print a subset of the cover page on page@tie{}1 of your document.
-
-If you use the word @code{no} as an optional argument, @code{groff}
-prints a title page but does not repeat any of the title page
-information (title, author, abstract, etc.@:) on page@tie{}1 of the
-document.
+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, 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).
 @endDefmac
 
 @Defmac {P1, , ms}
-(P-one) Prints the header on page@tie{}1.  The default is to suppress
-the header.
+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}
-Specifies the document title.  @code{groff} collects text following the
-@code{TL} macro into the title, until reaching the author name or
-abstract.
+Specify the document title.  @file{ms} collects text on input lines
+following a call to this macro into the title until reaching an
+@code{AU}, @code{AB}, or heading or paragraph macro call.
 @endDefmac
 
 @Defmac {AU, , ms}
-Specifies the author's name, which appears on the line (or lines)
-immediately following.  You can specify multiple authors as follows:
-
-@CartoucheExample
-.AU
-John Doe
-.AI
-University of West Bumblefuzz
-.AU
-Martha Buck
-.AI
-Monolithic Corporation
-
-...
-@endCartoucheExample
+Specify an author's name.  @file{ms} collects text on input lines
+following a call to this macro into the author's name until reaching an
+@code{AI}, @code{AB}, or heading or paragraph macro call.  Call
+@code{AU} repeatedly to specify multiple authors.
 @endDefmac
 
 @Defmac {AI, , ms}
-Specifies the author's institution.  You can specify multiple
-institutions in the same way that you specify multiple authors.
+Specify the preceding author's institution.  An @code{AU} call is
+usefully followed by at most one @code{AI} call; if there are more, the
+last @code{AI} call controls.  @file{ms} collects text on input lines
+following a call to this macro into the author's institution until
+reaching an @code{AU}, @code{AB}, or heading or paragraph macro call.
 @endDefmac
 
-@Defmac {DA, [@dots{}], ms}
-(optional) Prints the current date, or the arguments to the macro if
-any, on the title page (if specified) and in the footers.  This is the
-default for @code{nroff}.
+@Defmac {DA, [@Var{x} @dots{}], ms}
+Print the current date, or any arguments @var{x} in footers, and, if
+@code{RP} is also called, left-aligned after other document description
+information on the cover page.
+@c see Savannah #59826
 @endDefmac
 
-@Defmac {ND, [@dots{}], ms}
-(optional) Prints the current date, or the arguments to the macro if
-any, on the title page (if specified) but not in the footers.  This is
-the default for @code{troff}.
+@Defmac {ND, [@Var{x} @dots{}], ms}
+Print the current date, or any arguments @var{x}, if @code{RP} is also
+called, left-aligned after other document description information on the
+cover page, but not in footers.  This is the @code{groff} @file{ms}
+default.
 @endDefmac
 
 @Defmac {AB, [@code{no}], ms}
-Begins the abstract.  The default is to print the word
-@acronym{ABSTRACT}, centered and in italics, above the text of the
-abstract.  The word @code{no} as an optional argument suppresses this
-heading.
+Begin the abstract.  @file{ms} collects text on input lines following a
+call to this macro into the abstract until reaching an @code{AE} call.
+By default, @file{ms} places the word ``ABSTRACT'' centered and in
+italics above the text of the abstract.  The optional argument @code{no}
+suppresses this heading.
 @endDefmac
 
 @Defmac {AE, , ms}
-Ends the abstract.
+End the abstract.
 @endDefmac
 
-The following is example mark-up for a title page.
-@cindex title page, example markup
-@cindex example markup, title page
+An example document description, using a cover page, follows.
+@cindex cover page in [@code{ms}], example markup
+@cindex example markup, cover page in [@code{ms}]
 
 @CartoucheExample
 .RP
@@ -2991,33 +3000,32 @@ The following is example mark-up for a title page.
 The Inevitability of Code Bloat
 in Commercial and Free Software
 .AU
-J. Random Luser
+J.\& Random Luser
 .AI
 University of West Bumblefuzz
 .AB
-This report examines the long-term growth
-of the code bases in two large, popular software
-packages; the free Emacs and the commercial
-Microsoft Word.
-While differences appear in the type or order
-of features added, due to the different
-methodologies used, the results are the same
-in the end.
+This report examines the long-term growth of the code
+bases in two large,
+popular software packages;
+the free Emacs and the commercial Microsoft Word.
+While differences appear in the type or order of
+features added,
+due to the different methodologies used,
+the results are the same in the end.
 .PP
-The free software approach is shown to be
-superior in that while free software can
-become as bloated as commercial offerings,
-free software tends to have fewer serious
-bugs and the added features are in line with
-user demand.
+The free software approach is shown to be superior in
+that while free software can become as bloated as
+commercial offerings,
+free software tends to have fewer serious bugs and the
+added features are more in line with user demand.
 .AE
 
-... the rest of the paper follows ...
+@r{@dots{}the rest of the paper@dots{}}
 @endCartoucheExample
 
 @c ---------------------------------------------------------------------
 
-@node ms Body Text, ms Page Layout, ms Cover Page Macros, ms
+@node ms Body Text, ms Page Layout, ms Document Description Macros, ms
 @subsection Body text
 @cindex @code{ms} macros, body text
 
diff --git a/doc/ms.ms b/doc/ms.ms
index c84f412..d05aa97 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -217,22 +217,27 @@ or
 .CW .PP ),
 and consist of text separated by paragraph macros
 or even blank lines.
-Longer documents have a structure as follows:
+.
+Longer documents have a structure as follows.
+.
+.
 .IP "\fBDocument type\fP"
-If you invoke the
+If you call the
 .CW .RP
-(report) macro on the first line of the document,
-.I groff
-prints the cover page information on its own page;
-otherwise it prints the information on the
-first page with your document text immediately following.
-Other document formats found in
-.Acr AT&T
-.I troff
-are specific to
-.Acr AT&T
-or Berkeley, and are not supported in
-.I groff .
+macro at the beginning of your document,
+.I ms
+prints the document description on its own page;
+otherwise it prints the information
+(if any)
+on the first page with your document text immediately following.
+.
+Some document types found in other
+.I ms
+implementations are specific to AT&T or Berkeley,
+and are not supported in
+.I "groff ms" .
+.
+.
 .IP "\fBFormat and layout\fP"
 By setting number registers,
 you can change your document's type (font and size),
@@ -242,17 +247,20 @@ See
 .I "Document control settings"
 below for more details.
 .
-.IP "\fBCover page\fP"
-A cover page consists of a title, the author's name and institution,
-an abstract, and the date.\**
-.FS
-Actually, only the title is required.
-.FE
-See
-.I "Cover page macros"
-below for more details.
+.
+.IP "\fBDocument description\fP"
+A document description consists of any of:
+a title,
+one or more authors' names and affiliated institutions,
+an abstract, and a date or other identifier.
+.
+See section \[lq]Document description macros\[rq] below.
+.
+.
 .IP "\fBBody\fP"
-Following the cover page is your document.
+The main matter of your document follows its description
+(if any).
+.
 You can use the
 .I -ms
 macros to write reports, letters, books, and so forth.
@@ -361,16 +369,65 @@ Changes to the footnote length ratio
 take effect with the next footnote written in single-column
 arrangements,
 but on the next page in multiple-column contexts.
+.
+.
 .\" ------------------------
 .bp
 .NH 1
-Cover page macros
+Document description macros
 .XS
-Cover page macros
+Document description macros
 .XE
+.
+.
 .LP
-Use the following macros to create a cover page for your document
-in the order shown.
+All but the simplest documents bear a title.
+.
+As their level of sophistication
+(or complexity)
+increases,
+they tend to acquire dates of revision,
+explicitly identified authors,
+sponsoring institutions for authors,
+and,
+at the rarefied heights,
+an abstract of their content.
+.
+Define these data by using the macros below in the order shown;
+.CW .DA
+or
+.CW .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
+.CW .TL
+is mandatory if any other document description macro is called,\**
+.
+.FS
+Strictly,
+a
+.CW .TL
+call is not mandated by
+.CW .DA
+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
+.
+and
+.CW .AE
+is mandatory if
+.CW .AB
+is called.
+.
+.
 .TS H
 box;
 lb lb
@@ -378,100 +435,146 @@ lf(CR) lx.
 Macro  Description
 _
 .TH
-\&.RP [\fBno\fP]       T{
-Specifies the report format for your document.
+\&.RP \f[R][\f[]no\f[R]]       T{
+Use the \[lq]report\[rq]
+(AT&T: \[lq]released paper\[rq])
+format for your document,
+creating a separate cover page.
 .
-The report format creates a separate cover page.
-.
-The default action
-(no
-.CW .RP
-macro)
-is to print a subset of the cover page on page 1 of your document.
+The default arrangement is to print most of the document description
+(title,
+author names and institutions,
+abstract,
+but not the date)
+at the top of page\~1.
 .
 .
 .sp \n[PD]u
-If you use the optional
-.B no
-argument,
-.I groff
-prints a title page but
-does not repeat any of the title page information
-(title, author, abstract, etc.)
-on page 1 of the document.
+If the optional
+.CW no
+argument is given,
+.I ms
+prints a cover page but does not repeat any of its information on
+page\~1
+(but see the
+.CW DA
+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{
-Specifies the document title.
+Specify the document title.
 .
-.I groff
-collects text following the
-.CW .TL
-macro into the title, until reaching the author name or abstract.
+.I ms
+collects text on input lines following a call to this macro into the
+title until reaching an
+.CW .AU ,
+.CW .AB ,
+or heading or paragraph macro call.
 T}
 _
 \&.AU  T{
-Specifies the author's name,
-which appears on the line
-(or lines)
-immediately following.
-.
-You can specify multiple authors as follows.
-.
+Specify an author's name.
 .
-.DS I
-.CW
-\&.AU
-John Doe
-\&.AI
-University of West Bumblefuzz
-\&.AU
-Martha Buck
-\&.AI
-Monolithic Corporation
-.R
-\&.\|.\|.
-.DE
+.I ms
+collects text on input lines following a call to this macro into the
+author's name until reaching an
+.CW .AI ,
+.CW .AB ,
+or heading or paragraph macro.
+.
+Call
+.CW .AU
+repeatedly to specify multiple authors.
 T}
 _
 \&.AI  T{
-Specifies the author's institution.
+Specify the preceding author's institution.
+.
+An
+.CW .AU
+call is usefully followed by at most one
+.CW .AI
+call;
+if there are more,
+the last
+.CW .AI
+call controls.
 .
-You can specify multiple institutions in the same way that you specify
-multiple authors.
+.I ms
+collects text on input lines following a call to this macro into the
+author's institution until reaching an
+.CW .AU ,
+.CW .AB ,
+or heading or paragraph macro call.
 T}
 _
-\&.DA [\fIxxx\fP]      T{
-(optional) Print the current date,
-or the arguments to the macro if any,
-on the title page
-(if specified)
-and in the footers.
-.
-This is the default for
-.I nroff .
+\&.DA \f[R][\f[I]x\f[] .\|.\|.\&]      T{
+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.
+.\" see Savannah #59826
 T}
 _
-\&.ND xxx [\fIxxx\fP]  T{
-(optional) Print the current date,
-or the arguments to the macro if any,
-on the title page
-(if specified)
-but not in the footers.
-.
-This is the default for
-.I troff .
+\&.ND \f[R][\f[I]x\f[] .\|.\|.\&]      T{
+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.
+.
+This is the
+.I "groff ms"
+default.
 T}
 _
 \&.AB [no]     T{
-Begins the abstract.
+Begin the abstract.
 .
-The default is to print the word
-.Acr ABSTRACT ,
-centered and in italics,
-above the text of the abstract.
+.I ms
+collects text on input lines following a call to this macro into the
+abstract until reaching an
+.CW .AE
+call.
+.
+By default,
+.I ms
+places the word \[lq]ABSTRACT\[rq] centered and in italics above the
+text of the abstract.
 .
-The option
+The optional argument
 .CW no
 suppresses this heading.
 T}
@@ -482,7 +585,9 @@ _
 .
 .KS
 .LP
-The following is example markup for a title page.
+An example document description,
+using a cover page,
+follows.
 .
 .
 .\" Wrap lines in the code example below at 64 columns.
@@ -496,7 +601,7 @@ T{
 \&.TL
 The Inevitability of Code Bloat in Commercial and Free Software
 \&.AU
-J. Random Luser
+J.\[rs]& Random Luser
 \&.AI
 University of West Bumblefuzz
 \&.AB
@@ -511,10 +616,10 @@ the results are the same in the end.
 The free software approach is shown to be superior in that while
 free software can become as bloated as commercial offerings,
 free software tends to have fewer serious bugs and the added
-features are in line with user demand.
+features are more in line with user demand.
 \&.AE
 .R
-\&.\|.\|.\|the rest of the paper follows\|.\|.\|.
+\&.\|.\|.\|the rest of the paper\|.\|.\|.
 .fi
 T}
 .TE
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 1029330..f216d3f 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -86,23 +86,27 @@ macro package expects files to have a certain amount of 
structure.
 The simplest documents can begin with a paragraph macro and consist of
 text separated by paragraph macros or even blank lines.
 .
-Longer documents have a structure as follows:
+Longer documents have a structure as follows.
+.
 .
 .TP
-.B "Document type"
-If you use the
+.B Document type
+If you call the
 .B RP
-(report) macro at the beginning of the document,
+macro at the beginning of the document,
 .I groff
-prints the cover page information on its own page;
-otherwise it prints the information on the
-first page with your document text immediately following.
+prints the document description on its own page;
+otherwise it prints the information
+(if any)
+on the first page with your document text immediately following.
 .
-Other document formats found in AT&T
-.I troff
-are specific to AT&T or Berkeley, and are not supported in
+Some document types found in other
+.I ms
+implementations are specific to AT&T or Berkeley,
+and are not supported in
 .IR "groff ms" .
 .
+.
 .TP
 .B "Format and layout"
 By setting registers and strings,
@@ -114,19 +118,22 @@ See
 .I "Document control settings"
 below for more details.
 .
+.
 .TP
-.B "Cover page"
-A cover page consists of a title,
-and optionally the author's name and institution,
-an abstract, and the date.
+.B Document description
+A document description consists of any of:
+a title,
+one or more authors' names and affiliated institutions,
+an abstract, and a date or other identifier.
+.
+See subsection \[lq]Document description macros\[rq] below.
 .
-See
-.I "Cover page macros"
-below for more details.
 .
 .TP
 .B "Body"
-Following the cover page is your document.
+The main matter of your document follows its description
+(if any).
+.
 It consists of paragraphs, headings, and lists.
 .
 .TP
@@ -278,98 +285,193 @@ is the gap between columns in multiple-column page 
arrangements.
 .
 .
 .\" ====================================================================
-.SS "Cover page macros"
+.SS "Document description macros"
 .\" ====================================================================
 .
-Use the following macros to create a cover page for your document
-in the order shown.
+Define information describing the document by using the macros below in
+the order shown;
+.B .DA
+or
+.B .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
+.B .TL
+is mandatory if any other document description macro is called
+(strictly,
+a
+.B .TL
+call is not mandated by
+.B .DA
+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).
+and
+.B .AE
+is mandatory if
+.B .AB
+is called.
+.
 .
 .TP
-.BR ".RP " [ no ]
-Specifies the report format for your document.
+.BR ".RP\~" [ no ]
+Use the \[lq]report\[rq]
+(AT&T: \[lq]released paper\[rq])
+format for your document,
+creating a separate cover page.
 .
-The report format creates a separate cover page.
+The default arrangement is to print most of the document description
+(title,
+author names and institutions,
+abstract,
+but not the date)
+at the top of page\~1.
 .
-With no
-.B RP
-macro,
-.I groff
-prints a subset of the
-cover page on page\~1 of your document.
 .
 .IP
-If you use the optional
+If the optional
 .B no
-argument,
-.I groff
-prints a title page but
-does not repeat any of the title page information
-(title, author, abstract, etc.\&)
-on page\~1 of the document.
+argument is given,
+.I ms
+prints a cover page but does not repeat any of its information on
+page\~1
+(but see the
+.B DA
+macro below regarding the date).
+.
 .
 .TP
 .B .P1
-(P-one) Prints the header on page\~1.
+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.)
 .
-The default is to suppress the header.
 .
 .TP
 .B .TL
-Specifies the document title.
+Specify the document title.
+.
+.I ms
+collects text on input lines following a call to this macro into the
+title until reaching an
+.BR .AU ,
+.BR .AB ,
+or heading or paragraph macro call.
 .
-.I groff
-collects text following the
-.B TL
-macro into the title, until reaching the author name or abstract.
 .
 .TP
 .B .AU
-Specifies the author's name.
+Specify an author's name.
+.
+.I ms
+collects text on input lines following a call to this macro into the
+author's name until reaching an
+.BR .AI ,
+.BR .AB ,
+or heading or paragraph macro.
+.
+Call
+.B .AU
+repeatedly to specify multiple authors.
 .
-You can specify multiple authors by using an
-.B AU
-macro for each author.
 .
 .TP
 .B .AI
-Specifies the author's institution.
+Specify the preceding author's institution.
+.
+An
+.B .AU
+call is usefully followed by at most one
+.B .AI
+call;
+if there are more,
+the last
+.B .AI
+call controls.
+.
+.I ms
+collects text on input lines following a call to this macro into the
+author's institution until reaching an
+.BR .AU ,
+.BR .AB ,
+or heading or paragraph macro call.
 .
-You can specify multiple institutions.
 .
 .TP
 .B .DA\c
-.RI " [" xxx ]
-(optional) Print the current date,
-or the arguments to the macro if any,
-on the title page (if specified)
-and in the footers.
+.RI "\~[" x "\~.\|.\|.]"
+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.
+.\" see Savannah #59826
 .
-This is the default for
-.IR nroff .
 .
 .TP
 .B .ND\c
-.RI " [" xxx ]
-(optional) Print the current date,
-or the arguments to the macro if any,
-on the title page (if specified)
-but not in the footers.
+.RI "\~[" x "\~.\|.\|.]"
+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.
 .
-This is the default for
-.IR troff .
 .
 .TP
 .BR ".AB " [ no ]
-Begins the abstract.
+Begin the abstract.
 .
-The default is to print the word \[lq]ABSTRACT\[rq],
-centered and in italics,
-above the text of the abstract.
+.I ms
+collects text on input lines following a call to this macro into the
+abstract until reaching an
+.B .AE
+call.
+.
+By default,
+.I ms
+places the word \[lq]ABSTRACT\[rq] centered and in italics above the
+text of the abstract.
 .
-The option
+The optional argument
 .B no
 suppresses this heading.
 .
+.
 .TP
 .B .AE
 End the abstract.