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

[T. Kurt Bond]

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

                 Summary: improve pdfmark documentation, including pdfroff(1)
                 Project: GNU troff
            Submitted by: tkurtbond
            Submitted on: Fri 16 Jul 2021 11:39:22 PM UTC
                Category: None
                Severity: 3 - Normal
              Item Group: Documentation
                  Status: None
                 Privacy: Public
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: None

    _______________________________________________________

Details:

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."

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.

pdfroff(1) mentions that it can make multiple passes over the document source
to resolve cross references, but the pdfmark.ms sections that are supposed to
describe this are empty.

groff.texi does not mention the existence of pdfmark.pdf, even though
pdfmark.pdf gets installed in the pdf subdirectory of the groff doc directory
hierarchy.  (For comparison, mom-pdf.pdf, which is also installed, *is*
mentioned in groff.texi.)

Mailing list discussion:

* Beginning of thread:
https://lists.gnu.org/archive/html/groff/2021-07/msg00051.html
* Branden's explaining and asking for bug submission:
https://lists.gnu.org/archive/html/groff/2021-07/msg00054.html




    _______________________________________________________

Reply to this item at:

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

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