Hi Doug,
At 2022-07-22T07:36:03-0400, Douglas McIlroy wrote:
Changing the .TH case convention throughout the Unix world is about as
futile an effort as English spelling reform.
I love a challenge.
Doing it for groff-related man pages only would simply brand groff as
quirky.
True, but on the one hand I don't mind, and on the other, as indicated
by the start of this thread, Alejandro is seriously considering doing so
for the Linux man-pages project, the corpus of which is large and is the
uncontested resource for the Linux system call interface and standard C
library implementations (with various extensions to the formal standard
distinguished and discussed). Conceivably, this practice could swiftly
pass from quirky to ordinary.
On GNU/Linux systems, that is.
And, as I shall never cease to remind people, the man(7) `PT` and `BT`
traps are replaceable, thanks to the efforts of Larry Kollar around 20
years ago.
At least the current convention has the virtue of simplicity.
I think this simplicity took a conceptual blow when the disciples of
Wirth arrived with their StudlyCapped identifiers, and a concrete one
with the appearance of the X Window System.
A convention of matching the case of commands or functions needs extra
rules to settle how to render titles like INTRO(1), EXEC(3),
STRING(3), or various stuff in man7.
I perceive no great difficulty here; one uses the casing that is
"natural", which for most Unix-savvy (or simply lazy) typists will be
full lowercase. The quantity of man pages available on a system can be
much larger today than it was on Research Unix, so I anticipate that
most man pages are discovered through search or via cross reference than
by experimentally testing various names.
intro(x) pages are sorely neglected these days, a sad situation.
A couple of years ago someone on this list proposed a revised intro(1),
which people on this list found to be high quality, but it needed a
champion to sponsor it to the Linux man-pages project, and such a person
did not appear.
As for the history, Dennis's original man-page template was generally
deemed worthy. The only discussions I remember were about the overall
division into sections and how to organize pages within a section. The
overall division turned out to be a little squishy, witness the
aimless evolution of the remits of sections 5-7. I am happy to note
that the organization within section--intro plus alphabetic--has held
firm. (My most substantive contribution to the v1 manual was holding
out for alphabetization versus a topical outline. My main talking
point was the inutility of topical organization in the 15th edition of
Encyclopaedia Britannica.)
The practice of physically printing and binding the man pages, or even
compiling them into a single digital document, has fallen so far into
disuse that when I resurrected it for groff-man-pages.pdf, I experienced
for the _first_ time the temptation of a topical organization. I don't
think it's tractable to undertake, and objectivity is a greater
challenge with that approach than with alphabetical ordering. But it is
a seductive thought.
Something that I think will surprise people is that, of the 385 pages of
U.S. letter-sizes pages in the compiled groff man pages, documentation
of commands--section 1--ends on page 137. Our section 5 (file format)
pages run from 138 to 164, and the balance is section 7.
People who think the manual stops at section 1, or 3, are missing a
great deal.