[bug #60927] improve pdfmark documentation, including pdfroff(1)

[Keith Marshall]

Follow-up Comment #1, bug #60927 (project groff):

Hi Kurt,

[comment #0 original submission:]
> Although pdfroff(1) mentions that "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" it does not indicate
> how to "suitably mark up groff source files."
Suitable mark-up is that described in section 2 of our pdfmark.pdf document,
(which is generated from pdfmark.ms).  Granted, that is rather incomplete; I
am working on it, and have several patches (mostly) ready to commit.

I believe that we could also benefit from the addition of a pdfmark(7), or
maybe better named as groff_pdfmark(7) manpage, and maybe also accompanied by
a groff_pdfhref(7) manpage, to document the appropriate mark-up.  I may
provide something suitable, after I've made pdfmark.pdf more complete.
> The pdfmark.ms file mentions that the .XN macro should be used to
> do this marking up, but the section about the .XN macro is empty
> so how to use it is not documented anywhere.
Uhmm, no.  "XN" (which is provided by spdf.tmac) is only a small element of
the "suitable mark-up"; it serves a very specific purpose, (viz. the
duplication of section heading text, following a "NH" macro call, into the PDF
document outline, and — now optionally — into the TOC diversion, as I've
recently explained on [bug #58946 ticket #58946]), but plays no specific rôle
in controlling the operation of pdfroff(1).

The collation effect of pdfroff(1) is actually controlled by a troff register,
named "PHASE"; if no collation is required, (e.g. as specified by the
"--no-toc-relocation" option), this may remain undefined, or may be defined as
zero; otherwise, it will be defined as 1, in the TOC generation phase, and as
2, in the body-content generation phase.  In each of these phases, the user's
document source is expected to set troff's "pen" state, through "\O" escapes,
as appropriate for each type of content; (completely blank pages, as generated
in the "pen-up" state — and thus, not pertinent in the active phase — will
be discarded during collation).  When formatting with "-mspdf", these phases
are handled transparently, but specific handling may be necessary, for users
of other primary formatting macro packages.

I plan to cover this, in pdfmark.pdf, but I agree that it should also be
documented in the pdfroff(1) manpage.

    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?60927>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/