Re: All caps .TH page title

Alejandro Colomar
2022-07-22T22:20:45Z

[-- Attachment #1.1: Type: text/plain, Size: 9940 bytes --]

Hi Branden,

On 7/22/22 21:03, G. Branden Robinson wrote:
> Hi Alex,
>
> At 2022-07-22T13:46:37+0200, Alejandro Colomar wrote:
>> On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote:
>>> BTW, I think I didn't reply (or if I did was very short) to your
>>> comment that other languages may find it difficult to mirror our use
>>> of subsections, since their main section is already a subsection
>>> (e.g., 3pl).
>
> In my (Debian-centric) experience, I see "3perl"--just a detail.

Yeah, I was talking from memory. You can tell how little perl I write.
Most of my perl knowledge is PCRE (actually, I know quite a bit of
that), but not much actual perl.

>
> .\" Localize manual section titles for English.
> .de an*localize-strings
> . ds an*section1 General Commands Manual\"
> . ds an*section2 System Calls Manual\"
> . ds an*section3 Library Functions Manual\"
> . ds an*section4 Kernel Interfaces Manual\"

4 is special files for me. Kernel interfaces? that's a very unclear
name to me. syscalls are also kernel interfaces.

> . ds an*section5 File Formats Manual\"
> . ds an*section6 Games Manual\"

If we have a whole section for rogue(6), anything can get its own section ;)

> . ds an*section7 Miscellaneous Information Manual\" > . ds an*section8 System Manager's Manual\"
> . ds an*section9 Kernel Developer's Manual\"

I wonder why the Linux kernel doesn't use this one. Did it ever do?
I've seen some man9 pages floating around, but I don't know where they
come from, and why they aren't in the Linux man-pages project.

>
> Literally none of this necessarily implies the use of C. Instead these
> sections are a coalition--perhaps an uneasy one--of three different
> categorical axes.
>
> (1) who needs the information--users, programmers, or administrators
> (2) whether the information is a kernel-invariant or not
> (3) the syntax of data presented to other system components
>
> I suggest that this arrangement survives not just due to blind inertia,
> though that may be the preponderant factor, but because in a POSIX
> system these categories remain fairly stable. One can bloat or shrink
> the kernel but there's always going to be a kernel. There is a sharp
> distinction between kernel (or supervisor) mode and user mode. Some
> users are more privileged than others, and perform administrative tasks.
> The file metaphor as a persistent array of (often seekable, often
> persistent) bytes is deeply entrenched.

That makes sense. Maybe 3type is good.

>
>> Or, maybe it's the time to write a whole new volume? I think there's
>> a comparable difference between 3type and 3 than between 2 and 3 or 1
>> and 8, so it would be merited. I didn't do it before for two reasons:
>> it might break software that assumes than Unix manuals use a single
>> number followed by an optional string (I'd say it's not a fair
>> assumption to say that man9 would be the last one ever used; if
>> there's 9, there might be a 10 some day), and because other projects
>> had already used 3type.
>>
>> But, that would start a clean namespace. Maybe it's worth it.
>>
>> How would you feel if I inaugurate man10 for types, and later man11 for
>> non-function-like macros? :D
>
> Permit me to play an unaccustomed role as a voice of conservatism. I
> don't think we need the section number, or even a section suffix, to
> communicate information about a data type.
>
> (A) Header files could be put in section 3 under their names as-is. We
> should remember that C standard library header files, per ISO C,
> need not be literally present on the file system; they can be
> provided by the compiler using unspecified means. I point this out
> to emphasize their exotic nature. They need not be ordinary files,
> though on POSIX systems we should expect this. I don't think
> inaugurating a "section 0" serves any use here, since C identifiers
> will not collide with them. We do not write a stand-alone man page
> for a member of a structure, so the element "h" of a hypothetical
> "struct math" will be documented in "math(3)", not "math.h(3)".

Regarding structure tags, I aready defended the need to do something,
when I added the -struct suffix (which was a poor man's subsection).

If I were to rewrite the C library and kernel from scratch, without
backwards compatibility, I'd fix many many things. But that train
passed many years before I was born.

For one example, we have stat(2) and stat(3type). Why did they exploit
the fact that C allows calling a function and a struct the same? Don't
ask me. But they did.

So we need to be able to distinguish struct, union, and enum tags from
global namespace identifiers. -struct was an option. man3type is much
better, IMO (and already in use by Illumos and other systems). Maybe
man10 would be going too far.

But I strongly disagree with the initial temporary solution Michael and
I decided at first, which was simply to avoid adding a link page stat(3)
(and a few others) to system_data_types(7), even though we actually
documented stat in system_data_types(7).
There's a problem, and I want to solve it.

>
> (B) Collisions in C's name spaces are discouraged by common practice and
> seldom leveraged even where syntactically distinct. Functions and
> variables ("objects") are in the same name space in C, and data
> types and objects are so confusable[1] that in practice programmers
> treat them as being in the same name space. For example, structure
> tags enjoy their own name space but most novice and even many
> experienced C programmers are shaky on the fact. (This ignorance
> was compounded for decades by a common idiom of introducing type
> aliases ("typedefs"[2]) for structs as soon as they were declared.)

I wish they used _s suffix for structs, or that at least they didn't
abuse this C feature, but they did. It's too late to change that.

>
> The above points are why I think we not only don't need new sections of
> the manual, but that suffixes like "type" and "def" are not performing
> any service for the reader that isn't clearly and obviously communicated
> in the text of the man page, if it is written to a minimum level of
> quality. The synopsis will say what is needed, and within a programming
> language, names exposed by an API should not be ambiguous, so the suffix
> won't be necessary to aid the apropos/"man -k"-using reader.

For the replies above, I'm strongly pushing for a 3type and a
3somethingelse subsections.

Now, I'd really like to get a good name for the constants subsection.
3def seems to be too constrained to C's #define (and when C adds
constexpr some day, man3def might be not a good name anymore).

>
> Here, let me do an impression. [tousels hair; puts on big glasses;
> becomes copyright rentier; indulges predatory, monopolistic practices]
>
> "Nine sections of the manual ought to be enough for anybody."

I think there's no need (yet) for new whole sections; you convinced me
about that. :-)

>
> Regards,
> Branden
>
> [1] https://en.wikipedia.org/wiki/Lexer_hack
> [2] A deceitful little term if there ever was one, because it does
> _nothing_ to enhance type conformance checking. Kernighan pointed
> out that "strong typing is not dimensional analysis" in his article
> "Why Pascal Is Not My Favorite Programming Language", when
> enumerating deficiencies of that language. Here's his example.
>
> type
> apple = integer;
> orange = integer;
>
> C works similarly.
>
> typedef int apple;
> typedef int orange;
>
> Kernighan failed to note that strong typing _could_ be dimensional
> analysis, if taken seriously. Perhaps he didn't because the same
> criticism could then be made of C, which had his name on it and
> proceeded to eat much of Pascal's lunch in the '80s and '90s--for
> reasons conspicuously distinct from the quality of its type
> checking.
>
> If you want real checking of a primitive type in C, you have to wrap
> it in a one-member struct. Even then you don't get range
> constraints, which are frequently valuable and which Pascal did
> support. Kernighan clucked in the same paper that range checks
> "seemed like a service, though they too exact a run-time penalty".
> In other words, they are costly. I wonder how we might measure the
> cost of failures to observe CERT'S INT{30,32}-C[3] in the quest for
> bragging rights about performance. Obviously its magnitude was
> recognized only in retrospect.
>
> Now, lest I seem hard on Kernighan here, let me note that, among
> other excellent points in the paper, his thorough trashing of
> Pascal's array handling, where the size was regarded as an
> integral part of the data type, was completely deserved. For those
> who haven't read the paper, this means that, yes, in pre-ISO Pascal,
> your function which operated on char arrays of length 4 would not be
> permitted to operate on char arrays of length 5. The compiler (or
> interpreter) would stop you. It is hard for me to imagine, as a
> workaday programmer, how Wirth let the language escape the
> laboratory with this defect.

BTW, you can do something similar in C:

int foo(int (*foo)[3]);

int a[3], b[4];

foo(&a);
foo(&b); // compiler error

Not that I see much usefulness in it, but it's curious.

>
> [3] https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=87152052

Cheers,

Alex

--
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]