Re: All caps .TH page title

[Alejandro Colomar (man-pages)]

On 7/22/22 04:14, G. Branden Robinson wrote:
> > At least, _Exit(2) and _exit(2) point to the same page.  nan(3) and
> > NAN(3) don't, though!
>
> Pretty gross.  A useful counterexample of good practice, though.
>
> > We can't blame the writers, since the identifiers have those names in
> > C.  Luckily, man(1) shows you the right page if you specify the right
> > string.
>
> Yes, and at least they're closely related and from the same project.
>
> This is the only man page I know of that documents only simple (i.e.,
> not function-like) C preprocessor macros.  You're more conversant with
> libc-ish man pages so you may know of others,

Actually, I don't.

At least not previous to my introduction of intN_t(3type), which 
documents things like INT8_WIDTH and INT8_MAX (although I didn't [yet] 
create link pages with those name).

> but this is the sort of
> content that, as a user, I would prefer to find in, say, a "math.h(3)"
> man page.  Having these constants in a page by themselves does little to
> situate them within the context of the C math library API.  But I know I
> have suggested this to you before.  ;-)

I remember.  And I didn't ignore the suggestion; I've been thinking 
about it several times.

There are various problems with documenting math.h(0) (section 0 was 
introduced for header files, but I don't know when, how, or why that 
happened; see the man-pages-posix repo for example.  Other projects 
(Oracle? I don't remember well) use a subsection 3head, though.

I think I don't like the idea of _only_ documenting macros in a header 
file doc.  That is likely to produce a huge page such as 
system_data_types(7) once was, or queue(3).  limits.h(0) is an exception 
in my head, since even though it's huge, all of them are related (all 
are limits), and it's easy to read.  limits.h(0) has the advantage that 
you can navigate the page to see the limit that best fits your need; I 
would counter argue that with the following for the general case: man(1) 
supports regex search, so if you just want to search for all limits, 
man(1) supports regex searching, so you could do `man -k -s3def _MAX` to 
serach for *_MAX limits in a hypothetical 3def (or 3macro?) subsection 
dedicated to macros.  See for example:

$ man -s3type -k int._t
int8_t (3type)       - fixed-width basic integer types
intN_t (3type)       - fixed-width basic integer types
uint8_t (3type)      - fixed-width basic integer types
uintN_t (3type)      - fixed-width basic integer types


> I observe that the most popular simple macro of all, NULL, has no man
> page.

Oh, I had been thinking about it exactly yesterday, as I was wroking 
with the both loved and hated void(3type).

Maybe NULL(3something) starts a brand new subsection soon.  Do you have 
any preferences for the section name, since you mentioned it?  :-)


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).  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 feel a need to fix this lack of precision in the page titles.
> > Unless someone opposes to it with some strong reason, which I don't
> > expect.
>
> You never know.  But keep in mind that a strong objection is not the
> same thing as a strong reason.

Yup.  I expect the former, but not the latter. ;)

> > It'll take some time to do it, but if no-one speaks in a reasonable
> > time, I'll start doing it :).
>
> We should all practice our scowling faces for anyone who dares to
> promulgate man pages named "lS", "prIntf", or similar.

Oh, I trust people is not so evil... I'll train the face just in case, 
though.


Cheers,

Alex

> Regards,
> Branden

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