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
