[groff] 40/41: [man]: Tweak customization management.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

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

diff --git a/ChangeLog b/ChangeLog
index 9ea3bc38..f45c5639 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,20 @@
+2022-03-06  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [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>.
+
 2022-03-06  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [refer,mm]: Add and use `ref*reset` macro to clean up between
diff --git a/tmac/an.tmac b/tmac/an.tmac
index 91462999..f14b3c7f 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.
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 6fc1fd35..2240ce8b 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -2838,6 +2838,11 @@ Set the page header text
 (\(lqpage trap\(rq).
 .
 .
+.P
+If you want to remove a page header or footer entirely,
+`define' the appropriate macro as empty rather than deleting it.
+.
+.
 .\" ====================================================================
 .SS "Deprecated features"
 .\" ====================================================================