[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Keith Marshall
Subject: [bug #60927] improve pdfmark documentation, including pdfroff(1)
Date: Sun, 3 Oct 2021 07:41:45 -0400 (EDT)
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:92.0) Gecko/20100101 Firefox/92.0

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:


  Message sent via Savannah

reply via email to

[Prev in Thread] Current Thread [Next in Thread]