Re: All caps .TH page title

[G. Branden Robinson]

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

signature.asc
Description: PGP signature