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

[Alejandro Colomar (man-pages)]

On 7/23/22 21:30, G. Branden Robinson wrote:
> 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.

That's what had been done until now.
I've told this many times to different people (Ingo, contributors to 
linux-man, ...): that approach has many issues:

- Types tend to be not so well documented in the pages that mainly 
document a function.

- Types tend to be documented in either several pages, or zero pages, 
but only rarely you'll find a type that is documented exactly in one 
function page.  In the case that types are not documented at all, it'll 
be largely considered too obvious, but it may not be for some[1].  In 
the case it is documented several times, you can guess that they'll be 
out of sync, having to read many of those pages to get the full picture 
(and you'll likely only read one of them and get a wrong/old/incomplete 
idea of the type).

- Sometimes you want to get information about types without needing info 
about their APIs, because you may be designing a new API.  If you don't 
know all of the already existing types, you may:

  - Develop a new type that is the same as an existing type;
  - Or use a less-than-ideal type for the function you re creating.


For all of those reasons, I'm strongly convinced that man3type is a 
necessity.


[1]: 
<https://stackoverflow.com/questions/55190317/where-is-ssize-t-defined-in-linux>

     Funny note: just as I opened SO to check the link to the question, 
I had a notification that I had +10 reputation because of an upvote to a 
question.  Can you guess which question it was? :p

     BTW, it's my most-rated question on SO, at more than double the 
score of my second-most-rated question.  It seems there's many people 
wondering where types are documented.


>  And where the API is large,
> as with ncurses, in a "base page" that introduces the library itself.

I'm not saying that's bad; if we add link pages to it, with the names of 
the types.  But then, we go to square one of system_data_types(7).  The 
idea was good at first, but it will inevitably grow too much with time.

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

I do.  I always use struct/union/enum keywords explicitly in my code.  I 
don't see a good reason to obfuscate them.  However, I still use _s for 
structs, maybe to make it easy to grep for things like '\bfoo\b' and 
'\bfoo_s\b' separately.


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

3const came through my mind, but was discarded too soon for no really 
good reasons (I think my reason was that I wanted to propose the 
obviously wrong name, to get better proposals, without suggesting a 
good-enough one that didn't trigger better suggestions).  Since I've 
been suggested 3const by several people, I'll take it.

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

That's been in the language forever, AFAIK.  In fact, I think it was the 
way C++ arrays were originally implemented to reject different sizes. 
You can wonder why I hate C++ so much.

> I am old enough that the following valid C18 declaration shocks me.
>
> void f(double a[static 10], float b[const restrict 20], int [*][*]);

'static' is something I'd really like out of the standard.  It doesn't 
make any sense at all:

a is required to have at least 10 elements, and cannot be a null pointer.

b, as surprising as it may be, can be a null pointer, and can have less, 
more, or exactly 20 elements (so the 20 is effectively ignored).

I think C should add the _Nonnull[2] attribute, to allow the slightly 
better syntax (and deprecate static for that purpose):

void f2(double a2[_Nonnull 10], float b2[const restrict 20]);

a2 would be required to have at least 10 elements, and couldn't be a 
null pointer.

b2 would be required to have at least 20 elements if it;s not a null 
pointer, which it would also be allowed to be.

[2]: 
<https://clang.llvm.org/docs/AttributeReference.html#nullability-attributes>
> Regards,
> Branden

Cheers,

Alex

--
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/