[groff] 11/18: groff_mm(7): Recast .TC, \*[Ci], and \n[Cl] descs.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit b9a24dd5ec6a137970002e505f8dae608e214154
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Apr 4 10:04:38 2023 -0500

    groff_mm(7): Recast .TC, \*[Ci], and \n[Cl] descs.
    
    Also fix an orphaned line by adjusting dead-tree typography of `P` macro
    description.
---
 contrib/mm/groff_mm.7.man | 178 +++++++++++++++++++++++++++-------------------
 1 file changed, 106 insertions(+), 72 deletions(-)

diff --git a/contrib/mm/groff_mm.7.man b/contrib/mm/groff_mm.7.man
index 658532970..5b0dc439e 100644
--- a/contrib/mm/groff_mm.7.man
+++ b/contrib/mm/groff_mm.7.man
@@ -2744,6 +2744,9 @@ odd-numbered page.
 .
 Does not output an empty page if currently at the top of an odd page.
 .
+.
+.br
+.ne 4v
 .TP
 .BI P\  \fR[\fPtype\fR]\fP
 Begin new paragraph.
@@ -3275,10 +3278,19 @@ as a heading.
 .
 .
 .TP
-.BI TC\  "\fR[\fPslevel \fR[\fPspacing \fR[\fPtlevel \fR[\fPtab \fR[\fPh1 
\fR[\fPh2 \fR[\fPh3 \fR[\fPh4 \fR[\fPh5\fR]]]]]]]]]\fP"
-Table of contents.
+.BR TC \~\c
+.RI [ slevel\~\c
+.RI [ spacing\~\c
+.RI [ tlevel\~\c
+.RI [ tab\~\c
+.RI [ h1\~\c
+.RI [ h2\~\c
+.RI [ h3\~\c
+.RI [ h4\~\c
+.RI [ h5 ]]]]]]]]]
+Output table of contents.
 .
-This macro is normally used as the last line of the document.
+This macro is normally the last called in the document.
 .
 It flushes any pending displays and,
 if any references are pending
@@ -3287,106 +3299,105 @@ if any references are pending
 calls
 .BR RP .
 .
-The pages of the table of contents are numbered with Roman numerals;
-their appearance can be suppressed with the
-.B Oc
-register.
+It then begins a new page with the contents caption,
+stored in the string
+.BR Licon ,
+centered at the top.
 .
-It generates a table of contents with headings up to the level
-controlled by register
-.BR Cl .
+The entries follow after three vees of space.
 .
-Note that
+Each entry is a
+saved section
+(number and)
+heading title
+(see the
 .B Cl
-controls the saving of headings, it has nothing to do with
-.BR TC .
+register),
+along with its associated page number.
+.
+By default,
+an entry is indented by an amount corresponding to its heading level
+and the maximum heading length encountered at that heading level;
+if defined,
+the string
+.B Ci
+overrides these indentations.
 .
-Headings with a level less than or equal to
+Entries at heading levels up to and including
 .I slevel
-get
+are preceded by
 .I spacing
-number of lines before them.
+vees of space.
 .
-Headings with a level less than or equal to
+Entries at heading levels up to and including
 .I tlevel
-have their page numbers right\-justified with dots or spaces separating
-the text and the page number.
+are followed by a leader and a right-aligned page number.
 .
-Spaces are used if
+If the Boolean-valued
 .I tab
-is greater than zero, dots otherwise.
+argument is true,
+the leader is replaced with horizontal motion in the same amount.
 .
-Other headings have the page number directly at the end of the heading
-text
-.RI ( ragged-right ).
+For entries above heading level
+.IR tlevel ,
+the page number follows the heading text after a word space.
+.
+Each argument
+.IR h1 .\|.\|. h5
+appears in order on its own line,
+centered,
+above the contents caption.
+.
+Page numbering restarts at 1,
+in register format \[lq]i\[rq].
+.
+If the
+.B Oc
+register is true,
+numbering of these pages is suppressed.
 .
-.IP
-The rest of the arguments is printed, centered, before the table of
-contents.
 .
 .IP
-The user-defined macros
-.B TX
-and
-.B TY
-are used if
+If
 .B TC
-is called with at most four arguments.
-.
+is called with at most four arguments,
+it calls the user-defined macro
 .B TX
-is called before the printing of the string \[lq]CONTENTS\[rq],
+(if defined)
+prior to formatting the contents caption,
 and
 .B TY
-is called instead of printing \[lq]CONTENTS\[rq].
+(if defined)
+.I instead
+of formatting the contents caption.
+.
 .
 .IP
-Equivalent macros can be defined for list of figures, tables, equations
-and exhibits by defining
+Analogous handling of lists of figures,
+tables,
+equations,
+and exhibits is achieved by defining
 .BI TX xx
-or
-.BI TY xx\fR,\fP
+and
+.BI TY xx
+macros,
 where
 .I xx
-is \[lq]Fg\[rq],
+is \[lq]FG\[rq],
 \[lq]TB\[rq],
 \[lq]EC\[rq],
 or \[lq]EX\[rq],
 respectively.
 .
-.IP
-String
-.B Ci
-can be set to control the indentations for each heading-level.
-.
-It must be scaled, like
-.
-.RS
-.IP
-.EX
-\&.ds Ci .25i .5i .75i 1i 1i
-.EE
-.RE
-.
-.IP
-By default, the indentation is controlled by the maximum length of
-headings in each level.
-.
-.IP
-The strings
+Similarly,
+the strings
 .BR Lifg ,
 .BR Litb ,
 .BR Liex ,
-.BR Liec ,
 and
-.B Licon
-contain \[lq]Figure\[rq],
-\[lq]TABLE\[rq],
-\[lq]Exhibit\[rq],
-\[lq]Equation\[rq],
-and \[lq]CONTENTS\[rq],
-respectively.
+.B Liec
+determine captions for their respective lists.
 .
-These can be redefined to other languages.
 .
 .TP
 .B TE
@@ -3687,8 +3698,16 @@ interpolates a bullet
 .
 .TP
 .B Ci
-list of indentation amounts to use for table of contents heading levels,
-overriding automatic computation
+is a list of indentation amounts to use for table of contents heading
+levels,
+overriding their automatic computation.
+.
+Each word must be a horizontal measurement
+(like
+.RB \[lq] 1i \[rq])
+and is mapped one-to-one to heading levels 1,
+2,
+and so on.
 .
 .
 .TP
@@ -4103,6 +4122,21 @@ and
 .B TC
 .RB ( 2 ).
 .
+The
+.B Cl
+register controls whether a heading is
+.I saved
+for output in the table of contents at the time
+.B H
+or
+.B HU
+is called;
+if you change
+.BR Cl 's
+value immediately prior to calling
+.BR TC ,
+you are unlikely to get the result you want.
+.
 .
 .TP
 .B Cp