[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Alejandro Colomar (man-pages)
Subject: Re: manual section titles (was: All caps .TH page title)
Date: Sun, 24 Jul 2022 13:54:57 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.8.1

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]: <>

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

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(&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]: <>




Alejandro Colomar
Linux man-pages comaintainer;

reply via email to

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