Re: All caps .TH page title

[Alejandro Colomar]

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/>

OpenPGP_signature
Description: OpenPGP digital signature