[bug #58946] [ms] adapt to use the facilities of pdfmark

[Keith Marshall]

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/