[groff] 33/39: [ms]: Document new XN/XH and related macros.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 5c4515eea241423fd8b7eb960d22e33403cd60c6
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Oct 9 11:57:58 2022 -0500

    [ms]: Document new XN/XH and related macros.
    
    * doc/groff.texi (Creating a table of contents):
    * doc/ms.ms (Creating a table of contents):
    * tmac/groff_ms.7.man (Creating a table of contents): Do it.
    
    Fixes <https://savannah.gnu.org/bugs/?63110>.
---
 ChangeLog           |  10 +++
 doc/groff.texi      |  76 ++++++++++++++++---
 doc/ms.ms           | 210 ++++++++++++++++++++++++++++++++++++++++++++++------
 tmac/groff_ms.7.man | 208 +++++++++++++++++----------------------------------
 4 files changed, 335 insertions(+), 169 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f318c1d9c..f2f6001db 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2022-10-09  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [ms]: Document new XN/XH and related macros.
+
+       * doc/groff.texi (Creating a table of contents):
+       * doc/ms.ms (Creating a table of contents):
+       * tmac/groff_ms.7.man (Creating a table of contents): Do it.
+
+       Fixes <https://savannah.gnu.org/bugs/?63110>.
+
 2022-10-09  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [gxditview]: Support `-version`, `--version` option.  As a C
diff --git a/doc/groff.texi b/doc/groff.texi
index 93668fc83..a7ec0b567 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -4349,6 +4349,8 @@ numerals, and call @code{PX} (with a @code{no} argument, 
if present).
 @endDefmac
 
 Here's an example of typical @file{ms} table of contents preparation.
+We employ horizontal escape sequences @code{\h} to indent the entries by
+sectioning depth.
 
 @CartoucheExample
 .NH 1
@@ -4360,10 +4362,10 @@ Introduction
 .NH 2
 Methodology
 .XS
-Methodology
+\h'2n'Methodology
 .XA
-@arrow{}@arrow{}Fassbinder's Approach
-@arrow{}@arrow{}Kahiu's Approach
+\h'4n'Fassbinder's Approach
+\h'4n'Kahiu's Approach
 .XE
 @r{@dots{}}
 .NH 1
@@ -4375,13 +4377,69 @@ Findings
 .TC
 @endCartoucheExample
 
-Provins's ``Groff and Friends HOWTO'' includes a @code{sed} script that
-automatically inserts @code{XS} and @code{XE} entries after each heading
-in a document.  Altering the @code{NH} macro to automatically build the
-table of contents is perhaps initially more difficult, but could save a
-great deal of time in the long run if you use @file{ms} regularly.
+The remaining features in this subsubsection are GNU extensions.
+@code{groff} @file{ms} obviates the need to repeat heading text after
+@code{XS} calls.  Call @code{XN} and @code{XH} after @code{NH} and
+@code{SH}, respectively.
+
+@DefmacList {XN, @Var{heading-text}, ms}
+@DefmacListEndx {XH, @Var{depth} @Var{heading-text}, ms}
+Format @var{heading-text} and create a corresponding table of contents
+entry.  @code{XN} computes the indentation from the depth of the
+preceding @code{NH} call; @code{XH} requires a @var{depth} argument to
+do so.
+@endDefmac
+
+@code{groff} @file{ms} encourages customization of table of contents
+entry production.
+
+@DefmacList {XN-REPLACEMENT, @Var{heading-text}, ms}
+@DefmacListEndx {XH-REPLACEMENT, @Var{depth} @Var{heading-text}, ms}
+These hook macros implement @code{XN} and @code{XH}, respectively.
+They call @code{XN-INIT} and pass their @var{heading-text} arguments to
+@code{XH-UPDATE-TOC}.
+@endDefmac
+
+@DefmacList {XN-INIT, , ms}
+@DefmacListEndx {XH-UPDATE-TOC, @Var{depth} @Var{heading-text}, ms}
+The @code{XN-INIT} hook macro does nothing by default.
+@code{XH-UPDATE-TOC} brackets @var{heading-text} with @code{XS} and
+@code{XE} calls, indenting it by 2 ens per level of @var{depth} beyond
+the first.
+@endDefmac
+
+We could therefore produce a table of contents similar to that in the
+previous example with fewer macro calls.  (The difference is that this
+input follows the ``Approach'' entries with leaders and page numbers.)
+
+@CartoucheExample
+.NH 1
+.XN Introduction
+@r{@dots{}}
+.NH 2
+.XN Methodology
+.XH 3 "Fassbinder's Approach"
+.XH 3 "Kahiu's Approach"
+@r{@dots{}}
+.NH 1
+.XN Findings
+@r{@dots{}}
+@endCartoucheExample
+
+To get the section number of the numbered headings into the table of
+contents entries, we might define @code{XN-REPLACEMENT} as follows.
+(We obtain the heading depth from @code{groff} @file{ms}'s internal
+register @code{nh*hl}.)
+
+@CartoucheExample
+.de XN-REPLACEMENT
+.XN-INIT
+.XH-UPDATE-TOC \\n[nh*hl] \\$@@
+\&\\*[SN] \\$*
+..
+@endCartoucheExample
 
-You can customize the style of the leader that bridges each table of
+You can change the style of the leader that bridges each table of
 contents entry with its page number; define the @code{TC-LEADER} special
 character by using the @code{char} request.  A typical leader combines
 the dot glyph @samp{.} with a horizontal motion escape sequence to
diff --git a/doc/ms.ms b/doc/ms.ms
index 4a8a06eb7..85817bd00 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -3516,6 +3516,10 @@ Here's an example of typical
 table of contents preparation and
 its result.
 .
+We employ horizontal escape sequences
+.CW \[rs]h
+to indent the entries by sectioning depth.
+.
 .TS
 box center;
 L.
@@ -3533,11 +3537,11 @@ Introduction
 \&.NH 2
 Methodology
 \&.XS
-\[->]Methodology
+\[rs]h\[aq]2n\[aq]Methodology
 \&.XA no
-\[->]\[->]Fassbinder\[aq]s Approach
+\[rs]h\[aq]4n\[aq]Fassbinder\[aq]s Approach
 \&.XA no
-\[->]\[->]Kahiu\[aq]s Approach
+\[rs]h\[aq]4n\[aq]Kahiu\[aq]s Approach
 \&.XE
 .R
 \&.\|.\|.
@@ -3574,11 +3578,11 @@ Introduction
 .NH 2
 Methodology
 .XS
-       Methodology
+\h'2n'Methodology
 .XA no
-               Fassbinder's Approach
+\h'4n'Fassbinder's Approach
 .XA no
-               Kahiu's Approach
+\h'4n'Kahiu's Approach
 .XE
 .nr % 5
 .NH 1
@@ -3604,27 +3608,191 @@ Findings
 .
 .
 .PP
-Provins's
-.I "Groff and Friends HOWTO"
-includes a
-.I sed
-script that automatically inserts
-.CW .XS
+The remaining features in this subsection are GNU extensions.
+.
+.I "groff ms"
+obviates the need to repeat heading text after
+.CW XS
+calls.
+.
+Call
+.CW XN
 and
-.CW .XE
-entries after each heading in a document.
+.CW XH
+after
+.CW NH
+and
+.CW SH ,
+respectively.
+.
 .
-Altering the
+.TS
+box;
+cb cb
+lf(CR) lx .
+Macro  Description
+_
+\&.XN \f[I]heading-text        T{
+Format
+.I heading-text
+and create a corresponding table of contents entry;
+the indentation is computed from the depth of the preceding
 .CW NH
-macro to automatically build the table of contents is perhaps initially
-more difficult,
-but could save a great deal of time in the long run if you use
-.I ms
-regularly.
+call.
+T}
+\&.XH \f[I]depth heading-text  T{
+As
+.CW .XN ,
+but use
+.I depth
+to determine the indentation.
+T}
+.TE
+.
+.
+.KS
+.PP
+.I groff ms
+encourages customization of table of contents entry production.
+.
+.
+.TS
+box;
+cb cb
+lf(CR) lx .
+Macro  Description
+_
+\&.XN\-REPLACEMENT \f[I]heading-text   T{
+These hook macros implement
+.CW .XN
+and
+.CW .XH ,
+respectively.
+.
+They call
+.CW \%XN\-INIT
+and
+pass their
+.I heading-text
+arguments to
+.CW .\%XH\-UPDATE\-TOC .
+T}
+\&.XH\-REPLACEMENT \f[I]depth heading-text     \^
+\&.XH\-INIT    T{
+This hook macro does nothing by default.
+T}
+\&.XH\-UPDATE\-TOC\~ \f[I]depth heading-text   T{
+Bracket
+.I heading-text
+with
+.CW XS
+and
+.CW XE
+calls,
+indenting it by 2 ens per level of
+.I depth
+beyond the first.
+T}
+.TE
+.KE
+.
+.
+.LP
+.TS
+box center;
+L.
+T{
+.nf
+.CW
+\&.NH 1
+\&.XN Introduction
+.R
+\&.\|.\|.
+.CW
+\&.NH 2
+\&.XN Methodology
+\&.XH 3 \[dq]Fassbinder\[aq]s Approach\[dq]
+\&.XH 3 \[dq]Kahiu\[aq]s Approach\[dq]
+.R
+\&.\|.\|.
+.CW
+\&.NH 1
+\&.XN Findings
+.R
+\&.\|.\|.
+.CW
+\&.TC
+.fi
+T}
+.TE
+.
+.nr SavedPageNumber \n%
+.nr SavedH1 \n[H1] \" groff ms internal name
+.nr SavedH2 \n[H2] \" groff ms internal name
+.nr % 1
+.rr H1
+.rr H2
+.als SavedTOC toc*div \" groff ms internal name
+.rm toc*div
+.di ThrowAway
+.NH 1
+.XN Introduction
+.nr % 2
+.NH 2
+.XN Methodology
+.XH 3 "Fassbinder's Approach"
+.XH 3 "Kahiu's Approach"
+.nr % 5
+.NH 1
+.XN Findings
+.br
+.di
+.\" We can't emit the TOC inside a B1/B2 box, so use lines instead.
+.R
+\l'\n[.l]u'
+.PX
+\l'\n[.l]u'
+.als toc*div SavedTOC
+.rm SavedTOC
+.nr % \n[SavedPageNumber]
+.nr H1 \n[SavedH1]
+.nr H2 \n[SavedH2]
+.rr SavedPageNumber
+.rr SavedH1
+.rr SavedH2
+.
+.
+.PP
+To get the section number of the numbered headings into the table of
+contents entries,
+we might define
+.CW \%XN\-REPLACEMENT
+as follows.
+.
+(We obtain the heading depth from
+.I "groff ms" 's
+internal register
+.CW nh*hl .)
+.
+.
+.LP
+.TS
+box center;
+L.
+T{
+.nf
+.CW
+\&.de XN\-REPLACEMENT
+\&.XN\-INIT
+\&.XH\-UPDATE\-TOC \[rs]\[rs]n[nh*hl] \[rs]\[rs]$@
+\&\[rs]&\[rs]\[rs]*[SN] \[rs]\[rs]$*
+\&..
+T}
+.TE
 .
 .
 .PP
-You can customize the style of the leader that bridges each table of
+You can change the style of the leader that bridges each table of
 contents entry with its page number;
 define the
 .CW TC\-LEADER
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 7dfede673..c0368bb79 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -2134,163 +2134,93 @@ if present).
 .
 .
 .P
-When creating a table of contents,
-incorporating content derived from headings specified by
-.B .NH
-and
-.B .SH ,
-traditional
-.I ms
-implementations provide no convenient mechanism
-for duplication of the heading text into the table of contents;
+The remaining features in this subsection are GNU extensions.
+.
 .I groff ms
-mitigates this limitation,
-by providing the following pair of macros,
-(for use after
+obviates the need to repeat heading text after
+.B .XS
+calls.
+.
+Call
+.B .XN
+and
+.B .XH
+after
 .B .NH
 and
-.B .SH
-respectively):
+.BR .SH ,
+respectively.
 .
-.TP
-.BI .XN\~ text\ ...
-.TQ
-.BI .XH\~ outline\-level\ text\ ...
-Duplicate
-.I text\~...
-added to the body ot the document,
-to create a table of contents entry,
-(which may be indented in accordance with
-.IR outline\-level ).
+Text to be appended to the formatted section heading,
+but not to appear in the table of contents entry,
+can follow these calls.
 .
-.P
-Either,
-or both of
-.B XN
-and
-.B XH
-may be redefined by the user,
-(preferably by definition of the replacement hook macros,
-.BR \%XN\-REPLACEMENT ,
-and
-.B \%XH\-REPLACEMENT
-respectively);
-in their default implementations,
-both emit their
-.I text
-arguments into the body of the document,
-as heading text;
-they also pass this same text to the callback macro:
 .
 .TP
-.BI \%.XH\-UPDATE\-TOC\~ \%outline\-level\ text\ ...
-Encapsulate
-.I text
-within
-.BR \%.XS ... XE ,
-to create a table of contents entry.
-This macro is called by both
-.B .XN
-and
-.B .XH
-(no complementary
-.B \%XN\-UPDATE\-TOC
-macro is required),
-and may be redefined by the user;
-in its default implementation,
-its
-.I \%outline\-level
-argument,
-(which is inferred from the last\[hy]specified
-.B .NH
-heading level,
-when called by
-.BR .XN ),
-is simply ignored,
-but may be used by any user\[hy]defined replacement,
-for example,
-to control indentation of the table of contents.
+.BI .XN\~ heading-text
+Format
+.I heading-text
+and create a corresponding table of contents entry;
+the indentation is computed from the
+.I depth
+argument of the preceding
+.B NH
+call.
+.
 .
-.IP
-When called by
+.TP
+.BI .XH\~ "depth heading-text"
+As
 .BR .XN ,
-in addition to the inference of the
-.I \%outline\-level
-argument,
-the
-.I text
-arguments are augmented,
-by prefixing the current heading number,
-(which is also deduced from the last preceding use of
-.BR .NH ).
+but use
+.I depth
+to determine the indentation.
+.
 .
 .P
-In addition to
-.BR \%XH\-UPDATE\-TOC ,
-the default
-.B XN
-and
-.B XH
-implementations support the following pair of callback macros:
+.I groff ms
+encourages customization of table of contents entry production.
+.
+(Re-)define any of the following macros as desired.
 .
 .
-.br
-.ne 4v
 .TP
-.B \%.XN\-INIT
+.BI \%.XN\-REPLACEMENT\~ heading-text
 .TQ
-.B \%.XH\-INIT
-Called by
-.BR .XN ,
-and by
-.B .XH
-respectively,
-.I before
-.B \%.XH\-UPDATE\-TOC
-is called;
-in their default implementations,
-neither does anything,
-but either,
-or both,
-may be redefined by the user.
-.
-.P
-If the user has chosen to redefine
-.BR \%XH\-UPDATE\-TOC ,
-in some fashion which requires descrimination
-between the cases of having been called by
-.BR .XN ,
-or by
+.BI \%.XH\-REPLACEMENT\~ "depth heading-text"
+These hook macros implement
+.B .XN
+and
 .BR .XH ,
-then it may also be appropriate to redefine
-.BR \%XN\-INIT ,
-or
+and call
+.B \%XN\-INIT
+and
 .BR \%XH\-INIT ,
-or both,
-to handle the required discriminatory effect.
+respectively,
+then call
+.B \%XH\-UPDATE\-TOC
+with the arguments given them.
 .
-.P
-It should be noted that,
-whereas
-.I groff ms
-will emit an error diagnostic,
-and will
-.I not
-create any table of contents entry,
-if
-.B .XN
-is used before the first use of
-.BR .NH ,
-no such restriction is imposed on the use of
-.BR .XH .
-Thus,
-while it is nominally intended for use after
-.BR .SH ,
-.B .XH
-may be used in any context,
-in which use of
-.BR \%.XS ... XE
-is permitted.
+.
+.TP
+.B \%.XH\-INIT
+.TQ
+.B \%.XN\-INIT
+These hook macros do nothing by default.
+.
+.
+.TP
+.BI \%.XH\-UPDATE\-TOC\~ "depth heading-text"
+Bracket
+.I heading-text
+with
+.B XS
+and
+.B XE
+calls,
+indenting it by 2 ens per level of
+.I depth
+beyond the first.
 .
 .
 .P