[groff] 03/07: groff_ms(7): Update table of contents discussion.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 256d165f40d8a630dacc8bcfc749088fa65152fb
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Oct 2 15:33:18 2021 +1000

    groff_ms(7): Update table of contents discussion.
    
    * Say "TC-LEADER" and "TC-MARGIN", not "TC_LEADER" and "TC_MARGIN".
    * Update document control settings preamble to include mention of
      special characters.
    * Use \[aq] for literal neutral apostrophes.
    * Document the `SN` string; it was documented in 4.2BSD (Kies/Tuthill).
    * Revamp discussion of tables of contents.
      - Recast and tighten wording.
      - Offer advice about use of the `XS`, `XA`, and `XE` macros.
      - Give each of the TOC macros a tagged paragraph to synopsize it.
        Describe their operation in more detail.
    
    I feel a twinge about the name "TC-MARGIN"...isn't it more of a field
    width?
---
 ChangeLog           |   2 +-
 tmac/groff_ms.7.man | 200 +++++++++++++++++++++++++++++++++++-----------------
 2 files changed, 138 insertions(+), 64 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 64123bb..02becbd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -128,7 +128,7 @@
        hard-wired definition, within PX; see
        <https://savannah.gnu.org/bugs/?61157>.
 
-       * tmac/groff_ms.7.man (TC_LEADER, TC_MARGIN): Document them.
+       * tmac/groff_ms.7.man (TC-LEADER, TC-MARGIN): Document them.
 
 2021-09-28  G. Branden Robinson <g.branden.robinson@gmail.com>
 
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 24b0176..f67a279 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -172,7 +172,9 @@ macro at the end of your document.
 The following tables list the document control registers and strings.
 .
 For any parameter whose default is unsatisfactory,
-define its register or string before calling any
+define its register,
+string,
+or special character before calling any
 .I ms
 macro other than
 .BR RP .
@@ -321,10 +323,10 @@ Other settings
 Parameter      Definition      Effective       Default
 _
 \[rs]n[MINGW]  Minimum gutter width    next page       2n
-\[rs]n[TC_MARGIN]      TOC page number margin width    next PX call\
-       \[rs]w'000'
-\[rs][TC_LEADER]       TOC leader character    next PX call\
-       .\[rs]h'1m'
+\[rs]n[TC\-MARGIN]     TOC page number margin width    next PX call\
+       \[rs]w\[aq]000\[aq]
+\[rs][TC\-LEADER]      TOC leader character    next PX call\
+       .\[rs]h\[aq]1m\[aq]
 _
 .TE
 .
@@ -350,12 +352,10 @@ is the gap between columns in multiple-column page 
arrangements.
 .
 The
 .B TC_MARGIN
-register,
-and the
+register and
 .B TC_LEADER
-special character,
-take effect when printing any table of contents,
-which has been assembled using the
+special character affect the formatting of tables of contents assembled
+by the
 .BR XS ,
 .BR XA ,
 and
@@ -385,7 +385,7 @@ multiplied by\~1000.
 In
 .I ms
 documents that don't need to be portable to other implementations,
-using a scaling indicator,
+use of a scaling indicator,
 as in
 .RB \[lq] ".nr PS 10.5p" \[rq],
 is preferable.
@@ -803,6 +803,12 @@ of
 following redefinition of the alias for
 .BR \[rs]*[SN\-STYLE] .
 .
+The formatted number of the current section is available in
+.B \[rs]*[SN],
+facilitating its inclusion in
+.BR .XS / .XA / .XE
+table of contents entries.
+.
 .
 .TP
 .B .SH\c
@@ -1818,76 +1824,144 @@ it is a GNU extension.
 .SS "Creating a table of contents"
 .\" ====================================================================
 .
-Wrap text that you want to appear in the table of contents in
+Define an entry to appear in the table of contents by bracketing its
+text between calls to
+the
 .B XS
 and
 .B XE
 macros.
 .
-Use the
-.B TC
-macro to print the table of contents at the end of the document,
-resetting the page number to\~\c
-.B i
-(Roman numeral\~1);
-(note that the
+A typical application is to call them immediately after
+.B NH
+or
+.B SH
+and repeat the heading text within them.
+.
+The
+.B XA
+macro,
+used within
+.BR .XS / .XE
+pairs,
+supplements an entry\[em]for instance,
+when it requires multiple output lines,
+whether because a heading is too long to fit or because style dictates
+that page numbers not be repeated.
+.
+In a document with a multi-level sectioning structure,
+you may wish to indent the text thus wrapped to correspond to its
+sectioning depth;
+this can be done in the entry text by prefixing it with tabs or
+horizontally spacing escape sequences,
+or by providing a second argument to the
+.B XA
+macro.
+.
+.B .XS
+and
+.B .XA
+automatically associate the page number where they are called with the
+text following them,
+but they accept arguments to override this behavior.
+.
+At the end of the document,
+call
 .B TC
-macro ultimately calls the
+or
 .B PX
-macro,
-to print the table of contents,
-after resetting the page number).
+to emit the table of contents;
+.B .TC
+resets the page number
+.RB to\~ i
+(Roman numeral one),
+and then calls
+.BR PX .
 .
 .
-.P
-You can manually create a table of contents
-by specifying a page number as the first argument to
-.BR XS .
+.TP
+.B .XS\c
+.RI \~[ page-number ]
+.TQ
+.B .XA\c
+.RI \~[ page-number \~[ indentation ]]
+.TQ
+.B .XE
+Begin,
+supplement,
+and end a table of contents entry.
+.
+Each entry is associated with
+.I page-number
+(otherwise the current page number);
+a
+.I page-number
+of
+.RB \[lq] no \[rq]
+prevents a leader and page number from being emitted for that entry.
 .
-Add subsequent entries using the
-.B XA
-macro.
+Use of
+.B .XA
+within
+.BR .XS / .XE
+is optional;
+it can be repeated.
 .
-Use the
-.B PX
-macro to print a manually-generated table of contents
-without resetting the page number.
+If
+.I indentation
+is present,
+a supplemental entry is indented by that amount;
+ens are assumed if no unit is indicated.
 .
+Text on input lines between
+.B .XS
+and
+.B .XE
+is stored for later recall by
+.BR .PX .
 .
-.P
-If you give the argument
+.
+.TP
+.BR .PX \~[ no ]
+Switch to single-column layout.
+.
+Unless
 .RB \[lq] no \[rq]
-to either
-.B PX
-or
-.BR TC ,
-.I groff
-suppresses printing the title
-specified by the
+is specified,
+center and interpolate
 .B \[rs]*[TOC]
-string.
+in bold and two points larger than the body text.
+.
+Emit the table of contents entries.
+.
+.
+.TP
+.BR .TC \~[ no ]
+Set the page number to 1,
+the page number format to lowercase Roman numerals,
+and call
+.B PX
+(with a
+.RB \[lq] no \[rq]
+argument,
+if present).
 .
-.P
-You may control the style of the leaders,
-which extend each table of contents entry to fill the output line,
-to the beginning of the right side page margin field
-in which the page number is printed,
-by defining the
-.B TC_LEADER
-special character,
-(typically a combination of the
-.RB \[lq] . \[rq]
-glyph,
-and a specification for any space which is desired
-between adjacent leader dots).
 .
 .P
-You may adjust the width of the right-aligned page margin field,
-in which the page number is printed,
-(and which effectively increases
-the width of the right side page margin),
-by setting the
-.B TC_MARGIN
+You can customize the style of the leader that bridges each table of
+contents entry with its page number;
+define the
+.B TC\-LEADER
+special character by using the
+.B char
+request.
+.
+A typical leader combines the dot glyph
+.RB \[lq] .\& \[rq]
+with a horizontal space escape sequence to spread the dots.
+.
+The width of the page number field is stored in the
+.B TC\-MARGIN
 register.
 .
 .