man0, man3head (was: All caps .TH page title)

Alejandro Colomar
2022-07-29T11:33:24Z

[-- Attachment #1.1: Type: text/plain, Size: 4152 bytes --]

[dropped groff@; irrelevant to them]

Hi Branden,

On 7/27/22 18:05, Ingo Schwarze wrote:
> Hi Branden,
>
> G. Branden Robinson wrote on Sun, Jul 24, 2022 at 10:44:47AM -0500:
>> At 2022-07-24T16:57:19+0200, Ingo Schwarze wrote:
>
>>> But dismissing decade-old *BSD standards like the use of /usr/ for the
>>> base system and /usr/local/ for packages as a standard violation, and
>>> promoting /opt/ which is firmly a Linux-only invention,
>
>> Oh, no it's not. I remember that thing from Solaris 2.3 or 2.4.
>> Here's a slightly later source.
>>
>> https://docs.oracle.com/cd/E19455-01/805-6331/fsadm-17/index.html
>
> Oops, thanks for setting me right.
>
> Confirmed:
>
> > uname -a
> SunOS unstable11s 5.11 11.3 sun4u sparc SUNW,SPARC-Enterprise
> > ls -al /opt
> total 2613
> drwxr-xr-x 12 root other 13 Dec 31 2020 .
> drwxr-xr-x 19 root root 22 Aug 17 2018 ..
> drwxr-xr-x 4 root other 4 Feb 10 2015 bop
> drwxr-xr-x 25 root bin 29 Dec 1 2017 csw
> drwxr-xr-x 10 root sys 11 Aug 17 2018 developerstudio12.5
> drwxr-xr-x 10 root sys 11 Aug 17 2018 developerstudio12.6
> drwxr-xr-x 3 root root 3 Feb 10 2015 local
> drwxr-xr-x 12 root sys 12 Jan 22 2015 solarisstudio12.3
> drwxr-xr-x 10 root sys 11 Dec 22 2015 solarisstudio12.4
> drwxr-xr-x 13 root sys 13 Jan 22 2015 solstudio12.2
> drwxr-xr-x 13 root sys 15 Oct 29 2015 SUNWspro
> -rw------- 1 root root 1311633 Oct 29 2015 uninstall_Sun_Studio_12.class
> drwxr-xr-x 3 root root 3 Feb 18 2015 VRTS
>
> It doesn't look as if modern Oracle Solaris uses it very extensively,
> but still, it does exist.

BTW, Branden, you asked why would I use section 0 for header files
(although since the lists have been very hot these days, I won't care
finding the exact email).

I didn't inaugurate section 0 for that. I just followed existing
practice. But, considering our discussions about the topic, and
considering that I already changed CONFORMING TO to STANDARDS for
consistency across all manual pages in existence, I'll reconsider.

So, existing practice seems to be divided in:

- Putting header files' pages directly in man3 (e.g., string(3)).
Done by Linux man-pages, and BSDs (see BSD's sysexits(3)).
I don't like the idea, especially if the page name doesn't have a
trailing '.h', since they live in different namespaces.

- Putting them in man3head.
Done by some Oracle OSes (at least for some versions).

- Putting them in man0.
Done exclusively by the posix man pages.
Not even something POSIX is responsible for, AFAIK,
since we create the pages from the HTML source,
which has noting to do with sections.
Debian for example, changes this (see below).
It seems to be the only place man0 is being used,
and I have control over it.

- Putting them in man7.
Debian moves man0 pages to 7POSIX (but uses man7/).

Since there's much division, and I have complete control over one (or
even two if I can avoid Debian moving the pages to man7) of the
variants, I could help unify header files manual pages across Unix
systems by moving POSIX header file manual pages to man3head.

I would also move the only page in the Linux man pages that is in man0
(added recently by me; sysexits.h(0)) and the man3 header pages from the
Linux man-pages (such as string(3)) to man3head.

Maybe Debian also gives up modifying upstream pages, since I'll make it
really hard for them to "fix" man3type anyway (not on purpose, but
they'll need to come up with a script to modify the link pages).

That would leave us with the following situation:

- Most header file pages would be in man3head (Oracle, POSIX, Linux).

- BSDs still have a few (maybe only one?) header page in man3: sysexits(3).

- Section 0 becomes desert, and maybe someone can give it a new use in
the future, if a new section is ever need.

Much nicer than before.

Cheers,

Alex

--
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]