Re: All caps .TH page title

[G. Branden Robinson]

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.

Regard,
Branden

signature.asc
Description: PGP signature