[groff] 07/31: [man] Give `PT`, `BT` macros more responsibility.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 5297ce54d559559633be7439bd6bca9f6591beec
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: 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.
---
 ChangeLog               |  7 +++++++
 tmac/an.tmac            | 22 ++++++++++++++--------
 tmac/groff_man.7.man.in | 10 ++++++++--
 3 files changed, 29 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index b8c1b879..b62b623d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -12,6 +12,13 @@
        (TH): Move planting of `an-header` trap from out of the midst of
        footer trap management.  Add comments.
 
+       (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.
+
 2022-01-27  Dave Kemper <saint.snit@gmail.com>
 
        [man pages]: Add more references to pic(1)'s .PF.
diff --git a/tmac/an.tmac b/tmac/an.tmac
index 2c596cce..bf11c034 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -345,12 +345,26 @@
 ..
 .
 .\" Write the page header; can be redefined by man.local.
+.\"
+.\" In continuous rendering mode, we need to extend the page length to
+.\" accommodate the vertical size of our header (plus any spacing).
 .de1 PT
+.  ie \\n[cR] .pl +1v
+.  el         .sp .5i
 .  tl '\\*[an-pageref]'\\*[an-extra3]'\\*[an-pageref]'
+.  ie \\n[cR] \{\
+.    pl +1v
+.    sp 1v
+.  \}
+.  el .sp |1i
 ..
 .
 .\" Write the page footer; can be redefined by man.local.
+.\"
+.\" In continuous rendering mode, we need to extend the page length to
+.\" accommodate the vertical size of our footer (plus any spacing).
 .de1 BT
+.  if \\n[cR] .pl +1v
 .  ie \\n[D] \{\
 .    if o .tl '\\*[an-ifoot]'\\*[an-extra1]'\\*[an-outer-footer-text]'
 .    if e .tl '\\*[an-outer-footer-text]'\\*[an-extra1]'\\*[an-ifoot]'
@@ -479,14 +493,7 @@
 .  vs \\n[VS]u
 .  lt \\n[LT]u
 .  an*prepare-page-title
-.  ie \\n[cR] .pl +1v
-.  el         .sp .5i
 .  PT
-.  ie \\n[cR] \{\
-.    pl +1v
-.    sp 1v
-.  \}
-.  el .sp |1i
 .  ev
 .  ns
 ..
@@ -516,7 +523,6 @@
 .    \}
 .  \}
 .  an-prepare-inner-footer
-.  if \\n[cR] .pl +1v
 .  BT
 .  rm an-outer-footer-text
 .  ev
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 257a9a57..81b39f05 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -2759,8 +2759,14 @@ Because these macros are hooks for
 internals,
 man pages have no reason to call them.
 .
-A macro definition for these hooks typically consists of a \[lq].tl\[rq]
-request.
+Such hook definitions will likely consist of \[lq].sp\[rq] and
+\[lq].tl\[rq] requests.
+.
+They must also increase the page length with \[lq].pl\[rq] requests in
+continuous rendering mode;
+consult the existing implementations in
+.I an.tmac
+when drafting your replacement.
 .
 .
 .TP