Hi folks, I've seen this crop up a few times in ad hoc testing but was never able to track it down and now I have.
The mdoc macros of groff 1.22.4 and earlier won't render the page
headers and footers ("titles") of groff 1.23.0's groff_mdoc(7) page.
Nor will they of any mdoc(7) page that adopts mixed-case section titles.
The root cause is that groff 1.22.4's mdoc implementation only sets up
the page titles if it sees a section heading called exactly "NAME"[1].
"Name", as will appear in 1.23's groff_mdoc(7)[2], doesn't match.
I'm not sure where to document this; at first I thought, "NEWS", but
it's not a NEWS item for groff 1.23 per se, which has become _more_
flexible in interpreting section titles (it recognizes both "NAME" and
"Name"). Then I thought "PROBLEMS", but (1) I don't think many people
read that file and (2) again, it's not a groff 1.23 problem, but a
historical issue.
Also, how much of a problem this turns out to be in the real world
depends on (A) when we get groff 1.23 released and (B) how aggressively
authors of mdoc(7) pages in general adopt mixed-case section headings.
My hunch is that the magnitude of (B) will not be large. I don't expect
the groff_mdoc(7) page itself to expose this problem often because it
will surely be rare for anyone to construct or distribute a chimera of a
pre-1.23 groff mdoc package and 1.23's groff_mdoc(7) man page.
Please find attached a 4-line patch to the (stripped, installed) groff
1.22.4 mdoc macros to work around the problem.
Above all I dread anyone running into this problem, being mystified by
it, and finding themselves unable to locate a solution, so I wanted to
inject this knowledge into the collective consciousness.
Feedback is appreciated.
Regards,
Branden
[1]
https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/doc-common-u?id=cc292790528abb8985c8b743ac3887f7f393cd7a#n1047
https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/doc-common-u?id=cc292790528abb8985c8b743ac3887f7f393cd7a#n1090
[2] https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/groff_mdoc.7.man#n55
--- a/usr/share/groff/1.22.4/tmac/mdoc/doc-common 2021-07-24 06:56:19.265894282 +1000
+++ b/usr/share/groff/1.22.4/tmac/mdoc/doc-common 2021-07-24 06:56:12.645896850 +1000
@@ -947,6 +947,10 @@
.if t \
.ad
.doc-first-parameter \$*
+.if "\*[doc-str-dfp]"Name" \{\
+.doc-setup-header
+.in 0
+.\}
.ie "\*[doc-str-dfp]"\*[doc-section-name]" \{\
.doc-setup-header
.in 0
signature.asc
Description: PGP signature
