Re: All caps .TH page title

[Alejandro Colomar (man-pages)]

Hi Ingo,

On 7/23/22 21:29, Ingo Schwarze wrote:
> Hi Alejandro,
>
> On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote:
>
> > 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).
>
> Other languages are usually better off to live *outside* the $MANPATH
> and tell users to use "man -M" to access their documentation.
> For example, on OpenBSD, the TCL manuals live
> in /usr/local/lib/tcl/tcl8.5/man/ .
> Putting them into /usr/local/man/ would be quite disruptive because
> that would cause lots of clashes, including "apply", "break", "cd",
> "close", "eval", "exec", "exit", "expr", "glob", "info", "join", "open",
> "puts", "pwd", "read", "socket", "time", and so on.  I expect most
> other language will cause similar noise.
> Perl is better because the clashing names are mostly part of perlfunc(1),
> and the majority of other Perl manual page names contain colons.
> FORTRAN (traditionally in man3f) is also better because in this
> instance, the cryptic FORTAN six-letter identifiers become a virtue
> in so far as they prevent clashes.

I'm not happy with this approach.  I don't want to be typing paths for 
system stuff (your /usr/local is /usr in GNU/Linux systems; BTW, that's 
a thing I don't like at all from BSDs; IMO (and FHS's), /usr/local is 
for sysadmins to build from source; optional _packages_ should go to /opt).

If you want to search pages in section 3type, `man -s3type regex`. 
However, having some pages in subsections of 3, and others in the main 3 
section, is good for pages in subsections, but bad for pages in the main 
section (`man -s3 regex` would show all of the subsections' pages). 
That has a simple solution: move libc pages to man3c (and libm to man3m, 
...).  Since `man 3 printf` will continue working if this change is 
done, it doesn't seem to have backwards compatibility issues.

Also, you can put unimportant subsections at the end of the search list, 
to not hide other more important pages.

Cheers,

Alex

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