bugGNU roff - Bugs: bug #60927, improve pdfmark documentation,...

 
 

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

Submitter:  T. Kurt Bond <tkurtbond>
Submitted:  Fri 16 Jul 2021 11:39:22 PM UTC
   
 
Category:  Macro - others/general Severity:  3 - Normal
Item Group:  Documentation Status:  In Progress
Privacy:  Public Assigned to:  keithmarshall
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Wed 10 Apr 2024 12:52:43 PM UTC, comment #5: 

This is still a work in progress.  I consider the pdfroff(1) manual page to be complete, but I still plan to provide two more: groff_pdfmark(7) and groff_pdfhref(7).  I also have more content, which I plan to add, via pdfmark.ms, to pdfmark.pdf.

Meanwhile, I have now (as of 9-Apr-2024) posted significant additions to pdfmark.pdf; these may be found at https://osdn.net/users/keith/pf/groff-pdfmark/wiki/FrontPage

Keith Marshall <keithmarshall>
Group Member
Mon 27 Feb 2023 10:06:18 PM UTC, comment #4: 

comment #3:

> comment #2:
> > Further work is still required, to cover the semantics of pdfroff(1),
>
> Should this further work be documented in a ticket on OSDN?

I plan to cover it in section 4 of pdfmark.pdf, which I am currently working on, so a specific ticket should not be necessary at this stage.  However, if there are any specific topics, which you think I may otherwise overlook, please do feel free to open a ticket.

Keith Marshall <keithmarshall>
Group Member
Mon 27 Feb 2023 09:37:02 PM UTC, comment #3: 

comment #2:

> Further work is still required, to cover the semantics of pdfroff(1),


Hi Keith,

Should this further work be documented in a ticket on OSDN?

Kurt, in case you weren't aware, pdfmark source management will officially move from the groff GNU-hosted source tree to a separate and more up-to-date repository at osdn.net, as bug #63827 discusses.  That bug's comment 1 points to OSDN's ticketing system (https://osdn.net/users/keith/pf/groff-pdfmark/ticket), where any future issues with pdfmark should be reported.

Dave <barx>
Group Member
Tue 01 Mar 2022 03:52:11 PM UTC, comment #2: 

An expanded version of the pdfmark.pdf publication may be found at https://osdn.net/users/keith/pf/groff-pdfmark/wiki/FrontPage

Further work is still required, to cover the semantics of pdfroff(1), but section 2 does now provide substantially complete coverage of cross-reference mark-up, and section 3 now covers ms document structuring considerations, including the use of macros such as XH, XN, and their user-redefinable hooks, for mark-up of section headings.

Keith Marshall <keithmarshall>
Group Member
Sun 03 Oct 2021 11:41:45 AM UTC, comment #1: 

Hi Kurt,

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

Keith Marshall <keithmarshall>
Group Member
Fri 16 Jul 2021 11:39:22 PM UTC, 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."

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:

T. Kurt Bond <tkurtbond>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Digest:
   bug dependencies.

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by barx (Posted a comment)
  • -email is unavailable- added by gbranden (Updated the item)
  • -email is unavailable- added by keithmarshall (Posted a comment)
  • -email is unavailable- added by tkurtbond (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 4 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2024-04-10 keithmarshall StatusNone In Progress
        Assigned toNone keithmarshall
    2022-01-25 gbranden CategoryNone Macro - others/general
    2021-09-25 keithmarshall Dependencies- Depends on bugs #58946

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code