why page-local macro definitions come after `TH` call in man(7)

[G. Branden Robinson]

Hi Thomas,

I saw the following recent commit to the X11 Athena widget set.[1]

commit 080e6e49825c2e03adb0c5dd8dad53767ec41ce6
Author:     Thomas E. Dickey <dickey@invisible-island.net>
AuthorDate: Thu Feb 29 18:12:40 2024 -0500
Commit:     Thomas E. Dickey <dickey@his.com>
CommitDate: Sat Mar 2 16:40:07 2024 +0000

    manpage: assume .EX/.EE macros

    Branden Robinson says macros have to go after ".TH"; the existing macros did
    not match the format used in groff, etc., and can be simply removed.  The
    ".TQ" macro is used only without a parameter, causing an extra space to be
    emitted (and fixed that by dropping the parameter).

    Signed-off-by: Thomas E. Dickey <dickey@invisible-island.net>

Being cited as an authority stimulated in me not just a desire to pull a
James "Kibo" Parry impression but also to further clarify this topic in
the groff_man(7) document.

The reason for this placement is the widespread usage of the "mandoc"
wrapper, which isn't a mere GNUism as one might suspect, but dates all
the way back to 4.3BSD-Reno (1990).

https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Reno/share/tmac/tmac.andoc

diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index ea94a1122..1ee2bb055 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -3824,6 +3824,22 @@ .SH Files
 .I \%andoc
 reloads each macro package as necessary.
 .
+Page-local redefinitions of names used by the
+.I man
+or
+.I mdoc
+packages prior to
+.B .TH
+or
+.B .Dd
+calls will be \(lqclobbered\(rq by the reloading process.
+.
+If you want to provide your own definition of an extension macro to
+ensure its availability,
+the
+.I \%an\-ext\:.tmac
+entry below offers advice.
+.
 .
 .TP
 .I @MACRODIR@/\:\%an\-ext\:.tmac
@@ -3852,26 +3868,21 @@ .SH Files
 implementations or work-alike systems that format man pages
 to re-use them.
 .
+To ensure reliable rendering,
+`define' them after your page calls
+.BR .TH ;
+see the discussion of
+.I \%andoc\:.tmac
+above.
 .
-.IP
-The definitions for these macros are read after a page calls
-.BR .TH ,
-so they will replace any macros of the same names preceding it in your
-file.
-.
-If you use your own implementations of these macros,
-they must be defined after
-.B .TH
-is called to have effect.
-.
-Furthermore,
+Further,
 it is wise to `define' such page-local macros
 (if at all)
 after the \(lqName\(rq section to accommodate timid
 .MR makewhatis 8
 or
 .MR mandb 8
-implementations that give up scans for indexing material early.
+implementations that easily give up scanning for indexing material.
 .
 .
 .TP

(The funny quotes around "define" are because this is an m4 document.)

FYI; and as always I welcome comments on further improvements I can make
to groff's man(7) documentation.

Regards,
Branden

[1] 
https://gitlab.freedesktop.org/xorg/lib/libxaw/-/commit/080e6e49825c2e03adb0c5dd8dad53767ec41ce6

signature.asc
Description: PGP signature