Re: pdfroff and tables of contents

[G. Branden Robinson]

At 2021-07-15T12:34:40-0400, T. Kurt Bond wrote:
> The pdfroff man page says:
> 
> > It transparently handles the mechanics of multiple pass groff
> > processing, when applied to suitably marked up groff source files,
> > such that tables of contents and body text are formatted separately,
> > and are subsequently combined in the correct order, for final
> > publication as a single PDF document.
> 
> What does "suitably marked up" mean?  Looking at pdfmark.ms I see that
> it is marked up with the .XN macro,which it says is to used to
> addressed ms's "standard mechanism for generating a table of contents
> entry based on the text of the section heading; neither is there any
> recognised standard method for establishing a cross reference link to
> the section."  (This seems to ignore the .TC macro entirely, which
> does output a table of contents built from the text of the section
> headings, just at the end of the document, not at the beginning.)
> Other than its use in pdfmark.ms there seem to be no documentation for
> .XN.  The section in pdfmark.ms about .XN has no contents, alas.

Yes.  pdfmark.ms's incompleteness has defeated me more than once.  :(

XN is not a part of any _ms_ implementation I'm aware of, not even
groff's.  It does not appear in 4.2BSD ms or Version 10 Research Unix,
either.

In the groff system, XN is defined in spdf.tmac, which is itself part of
contrib/pdfmark.  There are some good comments in the file, including
one specifically documenting XN, so I won't repeat that material[1]
here.

> Would it be worth mentioning the existence of pdfmark.pdf (and
> pdfmark.ms, since its use of .XN is the only example) in pdfroff(1)?

Yes, I think so; given the tenor of response to other feedback on
pdfroff (sorry, I don't have a link handy), I think this point could
bear some emphasis.  There is a lot about pdfmark, and PDF processing in
general that I don't understand, but the impression I have formed is
that pdfroff and pdfmark are their own mini-ecosystem within groff.  To
some extent, they have to be, to resolve the forward reference problem.
Documenter's Workbench troff had an "mm" command to perform this work,
invoking multiple passes of the formatter to produce an internally
cross-referenced document.  We have the moral equivalent in
mmroff(1)[2].

Sometimes "groff -Tpdf" is all you require, and sometimes it isn't.

Kurt, could you file some Savannah bugs about this and the previous
issue you raised, about font repertoires?  My to-do list grows faster
than I can shrink it, but I do burn items off occasionally.

Regards,
Branden

[1] 
https://git.savannah.gnu.org/cgit/groff.git/tree/contrib/pdfmark/spdf.tmac#n70
[2] I've toyed with the idea of writing an "msroff" script since I've
    found I enjoy working with ms(7), and my hair-splitting revision of
    Larry Kollar's ms.ms document is reaching the point where I have
    little else to do but grapple with the table of contents and
    indexing discussions, which are at present insufficiently developed.

signature.asc
Description: PGP signature