[bug #58950] [man] adapt to use the facilities of pdfmark

[G. Branden Robinson]

Update of bug #58950 (project groff):

                  Status:                    None => Fixed                  
             Assigned to:                    None => gbranden               
             Open/Closed:                    Open => Closed                 
         Planned Release:                    None => 1.23.0                 

    _______________________________________________________

Follow-up Comment #2:

I reckon this was done recently.


commit 98112bfecad04b5568755cc531cc86d0b4553cf5
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Fri Jan 28 02:33:22 2022 +1100

    Implement PDF bookmark support for man pages.

    Limitation: A (sub)section can only be bookmarked if it is specified in
    the arguments to the `SH` or `SS` requests, not on the next line in an
    input trap.  Thanks to Deri James for providing the fundamentals (blame
    me for any weird bits).

    * tmac/an.tmac (an-prepare-page-title): Define a new string,
      `an*page-ref-string`, which is the man page's own reference (such as
      "groff(1)") without any abbreviation, ellipsis, or font selection or
      italic correction escape sequences.

      (SS): Define a new string, `an*subsection-heading`, storing the macro
      arguments (if any).  These could contain font selection escape
      sequences, for instance, a fact that becomes important later.

      (initialization):
      - Recognize `BM` register to enable PDF bookmarks (only on the 'pdf'
        output device); defaults on.  Recognize `BN` register to set a base
        level/depth for the bookmarks; this is to ease embedding of man
        pages in other PDF documents that already use bookmarks.  The
        default is 0.  The registers are not yet documented.
      - If the output device is 'pdf' and bookmarks are enabled, set
        `PDFOUTLINE.FOLDLEVEL` and `PDFHREF.VIEW.LEADING` registers
        (recognized by 'pdf.tmac').  Append to `TH`, `SH`, `SS` to get the
        `an*page-ref-string`, `an-section-heading`, and
        `an*subsection-heading` bookmarks in the document at the applicable
        levels.

    * tmac/mdoc/doc-common: Add straw-man implementation--it doesn't support
      the `BM` and `BN` configuration parameters yet.  (This is enough to
      get the groff_mdoc(7) page to correctly appear in the new
      'groff-man-pages.pdf' document.)

      (Dt, Sh, Ss): If the output device is 'pdf', place bookmarks in the
      document at levels 1, 2, and 3.

commit ea3b27102f1f84af4cf88f999266f10603c53628
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Mon Jan 31 21:10:56 2022 +1100

    [man]: Refactor PDF bookmark support.

    * tmac/an.tmac (an*bookmark): New internal macro calls `pdfbookmark`
      (only if the output device is 'pdf' and the `BM` register is true).

      (initialization): Migrate macro appendments to appropriate
      definitions.  Two cases...

      (SH, SS): ...were straightforward.

      (initialization): Another (for the man page title) was poorly placed
      when appended to the `TH` macro, skipping over the page header.  Move
      it instead...

      (PT): ...here.  But to keep this bookmark from being generated on
      every page of a document, we need a new variable
      `an*was-TH-bookmark-emitted` which is tested here and assigned once
      one bookmark corresponding to a `TH` call has been written.

      (TH): Initialize `an*was-TH-bookmark-emitted` to zero.

      (SS): Write the bookmark _before_ the subsection heading text.

      (initialization): Drop short-lived `BM` register.  It seems harmless
      to unconditionally include bookmarks in PDF output.  A PDF tool can
      strip them out if they're not desired, and viewers seem capable of
      minimizing or reducing the navigation pane (if they even offer one in
      the first place).

    * tmac/an.tmac (initialization): Rename new `BN` register to `BD`...

    * tmac/groff_man.7.man.in (Options) <BD>: ...and document it.  Also
      document `PT`'s new bookmarking responsibility.



    _______________________________________________________

Reply to this item at:

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

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