Follow-up Comment #10, bug #58946 (project groff): I have now reworked spdf.tmac, to incorporate only those macros identified in comment #9 as "necessary"; I _have_ included a completely reworked implementation of "XN", (which also serves as a new "XH" macro, courtesy of groff's .als mechanism).
As now implemented, the "XH" and "XN" macros conform to the following calling syntax: .SH .XH [-option ...] <outline-level> <heading-text> ... .NH <outline-level> .XN [-option ...] <heading-text> ... In both cases, the permitted options are: -N <name> Place a pdfhref destination mark, with the given name, at the location of this heading. -S Sanitize <heading-text> (by removal of "\F" escapes) for use in the PDF document outline. -X Create a pdfhref cross-reference dictionary entry for this heading; use the destination name specified by -N <name>, if given, or the first word taken from <heading-text> if not. Both of these new macro implementations ("XH" and "XN") reproduce their <heading-text> argument(s) as running text, in the appropriate heading font/size, and as PDF document outline entries, at the specified <outline-level>, and sanitized as required. Neither creates a TOC entry, by default; however, each invokes a pair of callback hooks: XH-INIT XN-INIT Called on entry to XH, and XN respectively; by default, each is a no-op, but either, or both, may be redefined by the user, to perform any respective initialization, for use by: XH-UPDATE-TOC <outline-level> [<section-number>] <heading-text> Called by both XH and XN, (the <section-number> argument is omitted, when called by XH, and always present, when called by XN); once again, this is a no-op by default, but may be redefined by the user, to generate TOC entries. As I had previously observed in comment #4, neither this implementation of "XN", nor its new "XH" sibling, is an appropriate candidate for inclusion in s.tmac; however, given this statement in the groff online manual <https://www.gnu.org/software/groff/manual/html_node/ms-TOC.html#ms-TOC> (not reproduced in groff_ms(7)): The Groff and Friends HOWTO includes a sed script that automatically inserts XS and XE macro entries after each heading in a document. Altering the NH macro to automatically build the table of contents is perhaps initially more difficult, but would save a great deal of time in the long run if you use ms regularly. and given that "XH" and "XN" can facilitate linking of TOC entries to section headings, I'm wondering if there may be some justification for incorporation of simplified versions of each of these, and maybe also a minimal default implementation of "XH-UPDATE-TOC", within s.tmac? What do you think? _______________________________________________________ Reply to this item at: <https://savannah.gnu.org/bugs/?58946> _______________________________________________ Message sent via Savannah https://savannah.gnu.org/