[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: All caps .TH page title

From: Alejandro Colomar
Subject: Re: All caps .TH page title
Date: Fri, 22 Jul 2022 20:31:08 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.0.2

Hi Branden, Doug,

On 7/22/22 14:48, G. Branden Robinson wrote:
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

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'd just use the following rule: match the string used in NAME (or Name).

In fact, if that were standard practise, mandoc(7) wouldn't need to special-case the title in .TH, as Ingo reported, so the simplicity of all caps comes with the complexity of the pregrams needing to parse it. If programs that parse it have extra complexity, I'd expect brains of readers to also have to deal with extra complexity, even if it's not enough to make them noticeable most of the time.

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.

Yup, loswercase until something else forces us to do otherwise is a simple rule, and consistent with everything else in Unix, I'd say.

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.

I'd like to read it, if it's so high quality. Would you mind pointing me to it?

Also, now that we speak about these things... I've always wondered what happened to learn(1). It's a program mentioned[1] in UNIX for Beginners [2nd ed.; K.], that doesn't seem to exist anymore (on Debian at least). Does it still exist anywhere? I'd like to see it, if someone knows of it.

[1]: <>

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.

Just imagine if manuals didn't stop at section 9 (kernel routines)... :P




reply via email to

[Prev in Thread] Current Thread [Next in Thread]