[bug #61954] [man] customizable `PT` and `BT` macros are not flexible enough

[G. Branden Robinson]

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

This is partially addressed.


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' [REDACTED]).
    
      (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.

commit 5297ce54d559559633be7439bd6bca9f6591beec
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Jan 29 07:52:38 2022 +1100

    [man] Give `PT`, `BT` macros more responsibility.
    
    * tmac/an.tmac (an-header): Move `pl` and `sp` requests from here...
      (PT): ...to here.  While it's conceptually nice to have these macros
      consist solely of `tl` requests, it doesn't yield enough power to
      those who want to redefine them.  Add comment.
    
      (an-footer, BT): ...simile.
    
    * tmac/groff_man.man.in (Hooks): Recharacterize these as containing `sp`
      requests as well as `tl` ones, and note continuous rendering mode
      responsibilities.

commit 091a6cd7dd96f3525f8e0c7f1ba9e9dd34bdccae
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Jan 29 06:44:27 2022 +1100

    [man]: Slightly refactor.
    
    * tmac/an.tmac (an-prepare-page-title): Rename to...
      (an*prepare-page-title): ...this.  Also simplify numeric expression.
      Add comment regarding necessity of correct environment.
    
      (an-header): Update call site of `an*prepare-page-title`.


This may be as far as I can take this without an architectural change, given a
dependency loop.

PT depends on TH having been run to define parameters (the page title and
manual section) that determine its default output.  (Technically, PT depends
on an*prepare-page-title which depends on TH having been run.)

At the same time we tell people to redefine PT only _after_ TH has been
called.  This is because andoc.tmac depends on seeing TH as the first macro
call in the page so that it knows when to reload an.tmac.

The only way I can think of out of this is to support a new configuration
file, say 'man-page-trap.local' (so named to discourage abuse for other
purposes) and source that early in tmac/an.tmac.  Possibly in TH itself
(though that risks redundantly reloading it many times in batch rendering),
but I suspect simply having it at the "top level" before PT's own definition,
which is then conditionalized on 'd PT', will be enough.

For that matter, we can load this new file with `soquiet` so we don't need to
ship it (just document it), and we can migrate the loading of 'man.local' to
soquiet while we're at it.

    _______________________________________________________

Reply to this item at:

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

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