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.
> > I'd say that since C is the native Unix language, and others are
> > just... others?, I'd optimize for C, and let other languages find a
> > way to document their things. It would be easy to say just go away,
> > the man pages are for C, but I won't dare to say that, since I like
> > man pages, and I'd like to see more documentation for languages that
> > I sometimes have to use be in the form of man pages, so I'll try to
> > come up with a more imaginative answer: how about using
> > subsubsections of the form 3pl_type? At least it's a possibility.
> > man(1) would handle them as any other subsection, but that's not a
> > big problem. Maybe man(1) could develop a way to provide
> > subsubsections... Colin, any ideas in this regard?
I don't see any reason to privilege the C language more than it already
is. Let us review the default manual section titles--the material that
appears in the center header by default when man pages are rendered.
.\" 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\"
. ds an*section5 File Formats Manual\"
. ds an*section6 Games Manual\"
. ds an*section7 Miscellaneous Information Manual\"
. ds an*section8 System Manager's Manual\"
. ds an*section9 Kernel Developer's Manual\"
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.
> 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)".
(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.)
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.
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."
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.
[3] https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=87152052
Attachment:
signature.asc
Description: PGP signature
