manual section titles (was: All caps .TH page title)

[G. Branden Robinson]

Hi Alex,

[Dropping linux-man from the CC list as I am sure some of the kernel
hackers there, if they bother to read my remarks below, will take
offense.  As they should.

By the way, I was able to follow up with a screenshot of the tm.3type
page rendered as PostScript, but it was rejected from the linux-man list
due to its size.  You'll have to view it via the groff list archives.

Content warning: This message turned largely into a dyspeptic
lamentation on the state of the industry.]

At 2022-07-23T00:20:32+0200, Alejandro Colomar wrote:
> On 7/22/22 21:03, G. Branden Robinson wrote:
> >    .\" 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.

Yes, but special to what?  The kernel.  ;-)

> Kernel interfaces?  that's a very unclear name to me.  syscalls are
> also kernel interfaces.

I grant both your points.  I think the idea is that section 4 is for
every way into the kernel that _isn't_ a system call.  In contrast to my
observation about stability earlier in this thread, this has been an
area of constant experimentation in *nix systems.  Sockets or streams?
Streams or STREAMS (as Ritchie famously said, it "means something
different when shouted").  System V IPC?  Berkeley Packet Filters?
Writable files in /proc?  Some of these fit into the syscall model and
others do not (or no effort has been made to do so).

> >    .  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 ;)

I don't regard this section's existence as waste or excess, but as a
litmus test for organizations that deploy *nix systems.  If the people
in the C suite insist that this stuff be chopped out "because IT is
serious business", you know that you're dealing with an organization
that is more dedicated than most to ensuring that individual
contributors experience their labor as a drudge.  Gotta maximize the
extraction of surplus value, ya know.

> >    .  ds an*section9 Kernel Developer's Manual\"
> 
> I wonder why the Linux kernel doesn't use this one.  Did it ever do?

Not to my knowledge, and I believe I recall (many years ago) an express
allergy being expressed toward it, possibly by Torvalds himself.  Kernel
hackers are busy folks.  They don't have time to write man pages.  If
you want to know how something works, read the sources.  A less cynical
explanation is that Torvalds's insistence of "never breaking userspace"
was coupled with a militant defense of the freedom to experiment right
up to that boundary, and it is those very areas that section 9 would
document.  So, when you're expecting a great deal of flux, it makes
sense not to suggest more stability than you really have.

But that was 20+ years ago.  The Linux kernel is now the world's biggest
software supertanker, complete with a cartel of large corporations
directing it from its bridge, and even where protected by the userspace
boundary, its internals do not change direction swiftly.  Con Kolivas
has stories he could tell you.

People did realize this, to an extent, and began to undertake
documentation, with much bikeshedding about Sphinx and Markdown and
whatever.  Man pages were, and are, old and "not sexy".  I think a lot
of these people miscalcuated where they'd spend their time as
documentors, weighting the sex appeal of the markup language far too
strongly.

The vast majority of my time as a documenter of groff is spent on the
discipline of crafting _English_, not markup.

But you can't get this message through to a lot of people.  Writing
English doesn't seem to them like something that will impress anyone
reading their résumé.  And, to be sure, for a lot of the people they're
trying to get jobs from, they're right.

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

You have to recall (or imagine) the delirious excitement of the dot-com
era.  Solve a problem by ramming a feature in, describe it exclusively
with buzzwords, refuse to document it, hype its performance beyond
recognition, post anonymous comments referring to yourself as a rock
star programmer, and watch your salary double overnight.  Also change
jobs frequently enough that your legacy of BS never catches up to you.
Think of yourself as wealthy because you have a ton of unvested RSUs.

Things have settled down a little.  I think.

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

Lightning will not strike in the same way again.  But we are engineers.
We should not give in to despair.  The rewards will be great if we can
replace C with a better language, or Linux (or *BSD) with a better
kernel.  And if we can't do those things, we could still see some
substantial payoffs if we rewrite the C stdio and string libraries.
Korn and Vo pretty much did the former, and knowledge about how to do
the latter is getting better socialized, where it's more a matter of
consistently using improved functions of more recent vintage, and not
thoughtlessly recapitulating bad examples from days of yore.

The only thing worse than being Schlemiel the Painter is copying his
approach blindly.

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

C'mon, you know the answer already.  It was less typing.  :-|

One of the best lessons we can teach programmers of the post-Unix
generations is that you do not have to Huffman code everything at the
first opportunity, especially in a casual, ad hoc manner.

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

I personally would prefer "3type" to an unprecedented[citation needed]
two-digit section number!

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

IMO system_data_types(7) bit off too much to chew.  The Linux system
programming interface is a collection of independently developed
components, generally with loose coupling.  At the risk of repeating
myself, I think the data types of these components are best documented
near where the functions that use them are.  And where the API is large,
as with ncurses, in a "base page" that introduces the library itself.

[typedefs and the structure tag name space]
> 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.

One of the things I like about Linux is its unashamed use of the struct
keyword.  It strikes me as more honest than introducing a struct and
then instantly concealing it behind a typedef.  The latter is not
encapsulation, it's obfuscation.  Oh, but it's a few more characters of
typing to say "struct ".  Many decades ago the observation was made that
source code is read much more often than it is written.

Rock star programmers have a rejoinder for that: "not mine!"  Move fast,
break stuff.  If no one can understand your code, you must be a genius.

> 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).

While I remain dubious about the utility of having a suffix at all, as I
said in a previous discussion, I don't see it as harmful because it can
be unwound without much disruption.  I therefore suggest "3const".

> I think there's no need (yet) for new whole sections; you convinced me
> about that. :-)

The po-faced gatekeepers of conservatism would smile, were they capable.

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

I want to say that came in with C99 or C11, but I'm honestly not sure.
I think it's better for array length conformance to be an opt-in feature
than a mandatory one with "no escape", as Kernighan memorably put it.

I am old enough that the following valid C18 declaration shocks me.

void f(double a[static 10], float b[const restrict 20], int [*][*]);

Regards,
Branden

signature.asc
Description: PGP signature