[Top][All Lists]

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

Re: All caps .TH page title

From: Alejandro Colomar (man-pages)
Subject: Re: All caps .TH page title
Date: Fri, 22 Jul 2022 12:35:31 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.8.1

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

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

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

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.




Alejandro Colomar
Linux man-pages comaintainer;

reply via email to

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