groff
[Top][All Lists]
Advanced

[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: Sat, 23 Jul 2022 00:20:32 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.0.2

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


reply via email to

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