[groff] 34/45: [ms]: Recast overview/document structure stuff.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a6358b529c89584f6721c52ced2fa529f80899aa
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jan 19 20:24:16 2022 +1100

    [ms]: Recast overview/document structure stuff.
    
    Make the discussion of tables of contents and indices a bit less feeble.
    Much of it may not remain long where it is; we could use a real
    discussion of the `IX` macro and a bit of user tutorial about handling
    the tasks of generating these.
    
    Also bring our 3(!) copies of this material into sync.
---
 doc/groff.texi      |  58 ++++++++++++++---------------
 doc/ms.ms           | 103 ++++++++++++++++++++++++++++------------------------
 tmac/groff_ms.7.man |  88 ++++++++++++++++++++++++++++++++++----------
 3 files changed, 153 insertions(+), 96 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index b465057a..7a20f0df 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2575,25 +2575,24 @@ We have used an arrow @arrow{} in the above to indicate 
a tab character.
 @subsection General structure of an @file{ms} document
 @cindex @code{ms} macros, general structure
 
-The @file{ms} macro package expects a certain amount of structure, but
-not as much as packages such as @file{man} or @file{mdoc}.  The simplest
-documents can begin with a paragraph macro (such as @code{LP} or
-@code{PP}), and consist of text separated by paragraph macros or even
-blank lines.  Longer documents have a structure as follows.
+The @file{ms} macro package expects a certain amount of structure:
+a well-formed document contains at least one paragraphing or sectioning
+macro call.  To compose a document from scratch, begin it by calling
+@code{LP} or @code{PP}.  Longer documents have a structure as follows.
 
 @table @strong
 @item Document type
-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}.
+Calling the @code{RP} macro at the beginning of your document puts the
+document description (see below) on a cover page.  Otherwise, @file{ms}
+places the information (if any) on the first page, followed immediately
+by the body text.  Some document types found in other @file{ms}
+implementations are specific to @acronym{AT&T} or Berkeley, and are not
+supported by @code{groff} @file{ms}.
 
 @item Format and layout
-By setting registers and strings, you can change your document's type
-(font and point size), margins, spacing, headers and footers, and
-footnote arrangment.  @xref{ms Document Control Settings}.
+By setting registers and strings, you can change your document's
+typeface, margins, spacing, headers and footers, and footnote
+arrangment.  @xref{ms Document Control Settings}.
 
 @item Document description
 A document description consists of any of: a title, one or more authors'
@@ -2605,21 +2604,22 @@ 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
-produce by placing the @code{TC} macro at the end of your document.
-Printing the table of contents at the end is necessary since
-GNU @code{troff}, like its @acronym{AT&T} ancestor, is a single-pass
-text formatter; it thus cannot determine the page number of a division
-of the text until it has been set and output.  Since @file{ms} output is
-designed for hard copy, you can manually relocate the pages containing
-the table of contents between the cover page and the body text after
-printing.@footnote{This limitation could also be overcome by using
-PostScript or PDF file manipulation utilities to resequence pages in the
-document, facilitated by specially-formatted comments (``device tags'')
-placed in the output by @file{ms}.}
+similar material.  @xref{ms Body Text}.
+
+@item Tables of contents and indexes
+Macros enable the collection of entries for a table of contents (or
+index) as the material they discuss appears in the document.  You then
+call a macro to emit the table of contents at the end of your document.
+The table of contents must necessarily follow the rest of the text since
+GNU @code{troff} is a single-pass formatter; it thus cannot determine
+the page number of a division of the text until it has been set and
+output.  Since @file{ms} was designed for the production of hard copy,
+the traditional procedure was to manually relocate the pages containing
+the table of contents between the cover page and the body text.  Today,
+page resequencing can be done in the digital domain with tools like
+@cite{pdfjam@r{(1)}}.  An index works similarly, but because it
+typically needs to be sorted after collection, its preparation requires
+separate processing.
 @end table
 
 @c ---------------------------------------------------------------------
diff --git a/doc/ms.ms b/doc/ms.ms
index 5df1a9a3..dc30c5bf 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -190,46 +190,47 @@ document
 .LP
 The
 .I ms
-macro package expects a certain amount of structure,
-but not as much as packages such as
-.I man
-or
-.I mdoc .
-.
+macro package expects a certain amount of structure:
+a well-formed document contains at least one paragraphing or sectioning
+macro call.
 .
-.PP
-The simplest documents can begin with a paragraph macro
-(such as
+To compose a document from scratch,
+begin it by calling
 .CW .LP
 or
-.CW .PP ),
-and consist of text separated by paragraph macros
-or even blank lines.
+.CW .PP .
 .
 Longer documents have a structure as follows.
 .
 .
 .IP "\fBDocument type\fP"
-If you call the
+Calling the
 .CW .RP
-macro at the beginning of your document,
+macro at the beginning of your document puts the document description
+(see below)
+on a cover page.
+.
+Otherwise,
 .I ms
-prints the document description on its own page;
-otherwise it prints the information
+places this information
 (if any)
-on the first page with your document text immediately following.
+on the first page,
+followed immediately by the body text.
 .
 Some document types found in other
 .I ms
 implementations are specific to AT&T or Berkeley,
-and are not supported in
+and are not supported by
 .I "groff ms" .
 .
 .
 .IP "\fBFormat and layout\fP"
-By setting registers,
-you can change your document's type (font and size),
-margins, spacing, headers and footers, and footnotes.
+By setting registers and strings,
+you can change your document's typeface,
+margins,
+spacing,
+headers and footers,
+and footnote arrangement.
 .
 See section \[lq]Document control settings\[rq] below.
 .
@@ -238,52 +239,60 @@ See section \[lq]Document control settings\[rq] below.
 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.
+an abstract,
+and a date or other identifier.
 .
 See section \[lq]Document description macros\[rq] below.
 .
 .
-.IP "\fBBody\fP"
+.IP "\fBBody text\fP"
 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.
-The package is designed for structured documents,
-consisting of paragraphs interspersed with headings
-and augmented by lists, footnotes, tables, and other
-common constructs.
+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 material.
 .
 See section \[lq]Body text\[rq] below.
 .
 .
-.IP "\fBTable of contents\fP"
-Longer documents include a table of contents,
-which you can invoke by placing the
-.CW .TC
-macro at the end of your document.\**
-.FS
-The
-.I ms
-macros have minimal indexing facilities, consisting of the
-.CW .IX
-macro, which prints an entry on standard error.
-.FE
+.IP "\fBTables of contents and indexes\fP"
+Macros enable the collection of entries for a table of contents
+(or index)
+as the material they discuss appears in the document.
+.
+You then call a macro to emit the table of contents at the end of
+your document.
 .
-Printing the table of contents at the end is necessary since
+The table of contents must necessarily follow the rest of the text since
 GNU
 .I troff
-is a single-pass text formatter;
+is a single-pass formatter;
 it thus cannot determine the page number of a division of the text until
 it has been set and output.
 .
 Since
 .I ms
-output was intended for hardcopy,
-the standard procedure was to manually relocate the pages containing
-the table of contents between the cover page and the
-body text.
+output was designed for the production of hard copy,
+the traditional procedure was to manually relocate the pages containing
+the table of contents between the cover page and the body text.
+.
+Today,
+page resequencing can be done in the digital domain with tools like
+.I pdfjam (1).
+.
+An index works similarly,
+but because it typically needs to be sorted after collection,
+its preparation requires separate processing.
 .
 .
 .\" ------------------------
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index a9e0c246..5088c0e6 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -104,24 +104,32 @@ and Tenth Edition Research Unix have been recreated.
 .
 The
 .I ms
-macro package expects files to have a certain amount of structure.
+macro package expects a certain amount of structure:
+a well-formed document contains at least one paragraphing or sectioning
+macro call.
 .
-The simplest documents can begin with a paragraph macro and consist of
-text separated by paragraph macros or even blank lines.
+To compose a document from scratch,
+begin it by calling
+.B .LP
+or
+.BR .PP .
 .
 Longer documents have a structure as follows.
 .
 .
 .TP
 .B Document type
-If you call the
+Calling the
 .B RP
-macro at the beginning of the document,
-.I groff
-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.
+macro at the beginning of your document puts the document description
+(see below)
+on a cover page.
+.
+Otherwise,
+.I ms
+places this information
+on the first page,
+followed immediately by the body text.
 .
 Some document types found in other
 .I ms
@@ -133,9 +141,11 @@ and are not supported in
 .TP
 .B "Format and layout"
 By setting registers and strings,
-you can change your document's
-margins, spacing, headers and footers, footnotes,
-and the base point size for the text.
+you can change your document's typeface,
+margins,
+spacing,
+headers and footers,
+and footnotes arrangement.
 .
 See subsection \[lq]Document control settings\[rq] below.
 .
@@ -145,24 +155,62 @@ See subsection \[lq]Document control settings\[rq] below.
 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.
+an abstract,
+and a date or other identifier.
 .
 See subsection \[lq]Document description macros\[rq] below.
 .
 .
 .TP
-.B "Body"
+.B Body text
 The main matter of your document follows its description
 (if any).
 .
-It consists of paragraphs, headings, and lists.
+.I 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 material.
+.
+The preponderance of subsections below covers these matters.
+.
 .
 .TP
 .B "Table of contents"
-Longer documents usually include a table of contents,
-which you can add by placing the
-.B TC
-macro at the end of your document.
+Macros enable the collection of entries for a table of contents
+(or index)
+as the material they discuss appears in the document.
+.
+You then call a macro to emit the table of contents at the end of
+your document.
+.
+The table of contents must necessarily follow the rest of the text since
+GNU
+.I troff \" GNU
+is a single-pass formatter;
+it thus cannot determine the page number of a division of the text until
+it has been set and output.
+.
+Since
+.I ms
+output was designed for the production of hard copy,
+the traditional procedure was to manually relocate the pages containing
+the table of contents between the cover page and the body text.
+.
+Today,
+page resequencing can be done in the digital domain with tools like
+.MR pdfjam 1 .
+.
+An index works similarly,
+but because it typically needs to be sorted after collection,
+its preparation requires separate processing.
 .
 .
 .\" ====================================================================