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? :DPermit 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:
OpenPGP_signature
Description: OpenPGP digital signature
