keithmarshall pushed a commit to branch master in repository groff. commit a50942f656386f04ec91be3e8813ab75fc56519f Author: Keith Marshall <keith.d.marsh...@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.marsh...@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.marsh...@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.marsh...@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 _______________________________________________ Groff-commit mailing list Groff-commit@gnu.org https://lists.gnu.org/mailman/listinfo/groff-commit