bugGNU roff - Bugs: bug #61954, [man] customizable `PT` and `BT`...

 
 

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

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Fri 28 Jan 2022 06:31:20 PM UTC
   
 
Category:  Macro package man Severity:  3 - Normal
Item Group:  Incorrect behaviour Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Mon 07 Mar 2022 01:27:30 AM UTC, comment #6: 

Very nice, it is!  Thanks for enabling groff_man(7) as a generic macro package :-)

Alejandro Colomar <alx>
Sat 05 Mar 2022 09:12:00 PM UTC, comment #5: 


commit b0b99ee646994e1df618b3fd083351c5e4807ee2
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Mar 6 06:36:11 2022 +1100

    [man]: Tweak customization management.

    * tmac/an.tmac: Load "man.local" with `msoquiet` request, so people can
      get rid of the file if they don't need it.

      (PT, BT): Define these macros only if not already defined.  This is
      slightly less paranoid but far more ergonomic, given interactions with
      the andoc wrapper.  Now user-defined page header traps (PT) defined in
      man.local can take effect on the first page rendered.

    * tmac/groff_man.7.man.in (Hooks): Document how to remove page headers
      and/or footers entirely.

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


G. Branden Robinson <gbranden>
Group administrator
Sat 05 Mar 2022 07:27:11 PM UTC, comment #4: 

I found a much, much simpler way to deal with this.

All I had to give up was a little paranoia.  In practice, mdoc(7) is not going to redefine `PT` or `BT`--they are outside its name space, and in any case we can be darned sure groff mdoc won't do such a thing.

That leaves the threat of man/mdoc documents themselves stomping on these macro names, but we were already helpless in the face of that.


diff --git a/tmac/an.tmac b/tmac/an.tmac
index 914629994..f14b3c7fc 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -25,8 +25,8 @@
 .\" <http://www.gnu.org/licenses/>.
 .
 .
-.\" Put local additions in the file man.local, loaded near the end of
-.\" this file.  If you need to add things to TH, use '.am1 TH'.
+.\" Put site additions in the file man.local, loaded near the end of
+.\" this file.  To add things to TH, use '.am1 TH'.
 .
 .if !\n(.g \
 .  ab groff man macros require groff extensions; aborting
@@ -378,6 +378,7 @@
 .\"
 .\" In continuous rendering mode, we need to extend the page length to
 .\" accommodate the vertical size of our header (plus any spacing).
+.if d PT .ig
 .de1 PT
 .  ie \\n[cR] .pl +1v
 .  el         .sp .5i
@@ -397,6 +398,7 @@
 .\"
 .\" In continuous rendering mode, we need to extend the page length to
 .\" accommodate the vertical size of our footer (plus any spacing).
+.if d BT .ig
 .de1 BT
 .  if \\n[cR] .pl +1v
 .  ie \\n[D] \{\
@@ -1111,8 +1113,8 @@
 .\" Load man macro extensions.
 .mso an-ext.tmac
 .
-.\" Load local modifications.
-.mso man.local
+.\" Load site modifications.
+.msoquiet man.local
 .
 .\" Set each rendering parameter only if its -[dr] option or man.local
 .\" did not.


So check this out.  Here's the input file.


$ cat EXPERIMENTS/not-a-man-page.man
.\" an example for Alejandro Colomar
.ds PT \" empty
.ds BT \" empty
.TH junk 1
.SH Prologue
Snow,
tenderly caught by eddying breezes,
swirled and spun in to and out of bright,
lustrous shapes that gleamed against the emerald-blazoned black drape of
sky and sparkled there for a moment,
hanging,
before settling gently to the soft,
green-tufted plain with all the sickly sweetness of an overwritten
sentence.
.SH "Chapter 1"
Cheryl's mind turned like the vanes of a wind-powered turbine,
chopping
her sparrow-like thoughts into bloody pieces that fell onto a growing
pile of forgotten memories.
.SS "Some Unexpected Visitors"
As the sun dropped below the horizon,
the safari guide confirmed the approaching cape buffaloes were
herbivores,
which calmed everyone in the group,
except for Herb,
of course.


I'm attaching screenshots of the foregoing working just fine with -man and -mandoc.  You can even render a real man page afterwards; all that's missing are the headers and footers, as intended.


G. Branden Robinson <gbranden>
Group administrator
Sat 12 Feb 2022 08:04:08 PM UTC, comment #3: 

I don't understand the changes very much.  There's still no way to have the first page with a custom title, is it?

If there is, please post an example, since I don't yet understand groff enough.

Alejandro Colomar <alx>
Sat 12 Feb 2022 12:03:23 PM UTC, comment #2: 

Alejandro, what's your view on the status of this ticket?

G. Branden Robinson <gbranden>
Group administrator
Tue 01 Feb 2022 06:54:22 AM UTC, comment #1: 

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.

G. Branden Robinson <gbranden>
Group administrator
Fri 28 Jan 2022 06:31:20 PM UTC, original submission:  

This issue arose consequent to a
groff mailing list exchange with Alejandro Colomar.

The customizable `PT` and `BT` macros, called by header and
footer traps, are not flexible enough.

A custom `PT` trap doesn't kick in until the second page because
we tell people not to redefine it until after `TH`, but by then
it is too late because `TH` causes the header trap to be
sprung.

Input:


$ cat EXPERIMENTS/two-pages-no-titles.man
.TH foo 1 2022-01-29 "groff foo test suite"
.de PT
.tl 'ABC'DEF'GHI'
..
.de BT
.tl 'JKL'MNO'PQR'
..
.SH Name
foo \- frobnicate a baz
.TH bar 1 2022-01-29 "groff bar test suite"
.SH Name
bar \- masticate a qux


groff 1.22.4 output:


$ nroff -man EXPERIMENTS/two-pages-no-titles.man
foo(1)                      General Commands Manual                     foo(1)



Name
       foo - frobnicate a baz



ABC                                   DEF                                  GHI



Name
       bar - masticate a qux



JKL                                   MNO                                  PQR


(The page footer for the foo(1) page was not written either.
That was bug #60609, fixed last May in groff Git HEAD.)

(The extra lines in the output are bug #60653, fixed last June
in groff Git HEAD.)

The "obvious" fix is to redefine `PT` before calling `TH`.

But it doesn't work in groff 1.22.4.

In groff Git HEAD, the package misbehaves differently; instead
the header on the first page (only) goes missing.

If we use the `-mandoc` option, instead of `-man`, the page
header on the second page reverts to the man(7) default!

I'm working on a fix.

G. Branden Robinson <gbranden>
Group administrator

 

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

Attach Files:
   
   
Comment:
   

Attached Files

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by alx (Posted a comment)
  • -email is unavailable- added by gbranden
  • -email is unavailable- added by gbranden (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 9 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-03-05 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2022-03-05 gbranden Attached File- Added man-fixed-trap-redefs-1.png, #52959
        Attached File- Added man-fixed-trap-redefs-2.png, #52960
        StatusNeed Info In Progress
    2022-02-12 gbranden StatusNone Need Info
    2022-02-01 gbranden StatusIn Progress None
        Carbon-Copy- Added alejandro colomar (man-pages) <alx.manpages@gmail.com>

    Back to the top

    Powered by Savane 3.13-caa5.
    Corresponding source code