Hi Thomas, I saw the following recent commit to the X11 Athena widget set.[1]
commit 080e6e49825c2e03adb0c5dd8dad53767ec41ce6
Author: Thomas E. Dickey <dic...@invisible-island.net>
AuthorDate: Thu Feb 29 18:12:40 2024 -0500
Commit: Thomas E. Dickey <dic...@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 <dic...@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
