[groff] 02/03: [ms]: Provide global default XH and XN implementations.

[Keith Marshall]

keithmarshall pushed a commit to branch master
in repository groff.

commit a50942f656386f04ec91be3e8813ab75fc56519f
Author: Keith Marshall <keith.d.marshall@ntlworld.com>
AuthorDate: Sun Oct 24 21:53:47 2021 +0100

    [ms]: Provide global default XH and XN implementations.
    
    cf. <https://savannah.gnu.org/bugs/?58946#comment13>
    
    * tmac/s.tmac (XH-INIT, XN-INIT, XH-UPDATE-TOC)
    (XH, XN, XH-REPLACEMENT, XN-REPLACEMENT): Implement them, and...
    * tmac/groff_ms.7.man: ...document them.
---
 ChangeLog           |  18 ++++++
 tmac/groff_ms.7.man | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 tmac/s.tmac         |  49 ++++++++++++++++
 3 files changed, 224 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 3d3ef44..48da2de 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,23 @@
 2021-10-24  Keith Marshall  <keith.d.marshall@ntlworld.com>
 
+       [ms]: Provide global default XH and XN implementations.
+
+       cf. <https://savannah.gnu.org/bugs/?58946#comment13>
+
+       * tmac/s.tmac (XH-INIT, XN-INIT, XH-UPDATE-TOC)
+       (XH, XN, XH-REPLACEMENT, XN-REPLACEMENT): Implement them, and...
+       * tmac/groff_ms.7.man: ...document them.
+
+2021-10-24  Keith Marshall  <keith.d.marshall@ntlworld.com>
+
+       [ms]: Fix misleading NH macro indentation.
+
+       * tmac/s.tmac (@NH) [.T is html]: .if statement should exhibit same
+       indentation as preceding .DEVTAG-NH statement, but is overindented;
+       fix it.
+
+2021-10-24  Keith Marshall  <keith.d.marshall@ntlworld.com>
+
        [ms]: Fix misleading NH macro indentation.
 
        * tmac/s.tmac (@NH) [.T is html]: .if statement should exhibit same
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 135c76d..e4138f9 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1960,6 +1960,163 @@ The width of the page number field is stored in the
 register.
 .
 .
+.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;
+.I groff ms
+mitigates this limitation,
+by providing the following pair of macros,
+(for use after
+.B .NH
+and
+.B .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 ).
+.
+.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.
+.
+.IP
+When called by
+.BR .XN ,
+in addition to the inference of the
+.I \%outline\-level
+argument,
+the
+.I text
+arguments are augmented,
+by prefixing the current section number,
+(which is also deduced from the last preceding use of
+.BR .NH ).
+.
+.P
+In addition to
+.BR \%XH\-UPDATE\-TOC ,
+the default
+.B XN
+and
+.B XH
+implementations support the following pair of callback macros:
+.
+.TP
+.B \%.XN\-INIT
+.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
+.BR .XH ,
+then it may also be appropriate to redefine
+.BR \%XN\-INIT ,
+or
+.BR \%XH\-INIT ,
+or both,
+to handle the required discriminatory effect.
+.
+.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.
+.
+.
 .\" ====================================================================
 .SH "Differences from AT&T \f[I]ms\f[]"
 .\" ====================================================================
diff --git a/tmac/s.tmac b/tmac/s.tmac
index ebc5817..907146e 100644
--- a/tmac/s.tmac
+++ b/tmac/s.tmac
@@ -1741,6 +1741,55 @@ along with this program.  If not, see 
<http://www.gnu.org/licenses/>.
 .\}
 .el .@error .XE without .XS
 ..
+.\" Rudimentary integration of TOC generation with SH and NH;
+.\" (called by XH and XN respectively, to capture heading text
+.\" for reuse as TOC entry); may be redefined, to achieve more
+.\" sophisticated TOC layout effects.
+.\"
+.\" No-op initializers are called by XH and XN respectively,
+.\" before XH-UPDATE-TOC is called; if XH-UPDATE-TOC has been
+.\" redefined, then it may also be necessary to redefine either,
+.\" or both of these, to perform any initialization specific
+.\" to use after SH and NH respectively.
+.de XH-INIT de
+.de XN-INIT
+..
+.de XH-UPDATE-TOC
+.\" .XH-UPDATE-TOC <outline-level> [<section-number>] <text>
+.\" (<section-number> present only when called by XN)
+.XS
+.shift\" don't use <outline-level> in rudimentary style
+\&\\$*\" capture <section-number> (if present) and <text>
+.XE
+..
+.\" Rudimentary integration hook, to be called (nominally)
+.\" after SH, but acceptable in any body-text context
+.de XH de
+.\" .XH <outline-level> <text>
+.rn XH-REPLACEMENT XH
+.XH \\$@
+.de XH-REPLACEMENT
+.XH-INIT
+.XH-UPDATE-TOC \\$@
+.shift
+\&\\$*
+..
+.\" Rudimentary integration hook, to be called after NH
+.de XN de
+.\" .XN <text>
+.ie \\n[nh*hl] .toc*xn-init \\$@
+.el \{ .@error .XN is not allowed before .NH
+.      nop \&\\$*
+.   \}
+.de toc*xn-init de
+.rn XN-REPLACEMENT XN
+.XN \\$@
+.rm \\$0
+.de XN-REPLACEMENT
+.XN-INIT
+.XH-UPDATE-TOC \\n[nh*hl] \\*[SN] \\$@
+\&\\$*
+..
 .de toc*end-entry
 \\a\\t\\*[toc*num]
 .br