Hi Alejandro,
Alejandro Colomar wrote on Fri, Jul 29, 2022 at 01:33:12PM +0200:
> 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.
I just looked at my forest (i.e., my collection of trees).
Version 3 AT&T UNIX contains these files in man/man0/:
* a macro file "aa" setting adjustment mode, indentation,
and something for page breaks and header or footer lines
* a file "basinf", kind of a quick start guide for UNIX,
mostly about logging in and out, but also containing
some remarks about programming and text processing
* a sed script "headrc", rather cryptic
* the famous permuted "index" file that used to be printed
together with the UNIX manuals
* a file "intro" containing the title page, preface,
and introduction for the manuals
* a file "toc" containing the table of contents of the manuals,
in the typical section-then-alphabetic order
* an ed script "tocrc", rather cryptic
* a file "xx", obviously intended as a template for writing
a new manual page
The following systems use man/man0 for similar purposes:
* v4, v6, PWB, v7, 32v, v8, v10, System III
* 3BSD, 4.0BSD, 4.1BSD, 4.2BSD, 4.3BSD-Tahoe, 4.3BSD-Reno
* 4.4BSD, 4.4BSD-Lite1, 4.4BSD-Lite2, NetBSD
The exact content varies, but it's always used for auxiliary files
like macros files, scripts, tools, and front matter.
Usage of man/man0 is especially extensive in v10, which
contains several man/man0 directories in various places
with several dozen files contained in them.
> 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)).
That practice is deprecated in OpenBSD:
$ uname -a
OpenBSD isnote.usta.de 7.1 GENERIC.MP#613 amd64
$ man string
man: No entry for string in the manual.
The way to get this information looks like this now:
$ man -k In=string.h
bit_alloc, bit_clear, bit_decl, bit_ffc, bit_ffs, bit_nclear, bit_nset,
bit_set, bit_test, bitstr_size(3) - bit-string manipulation macros
bzero, explicit_bzero(3) - write zeroes to a byte string
memccpy(3) - copy string until character found
memchr, memrchr(3) - locate byte in byte string
memcmp(3) - compare byte string
memcpy(3) - copy bytes
memmem(3) - locate a byte substring in a byte string
memmove(3) - copy bytes
memset(3) - write a byte to byte string
stpcpy, stpncpy(3) - copy strings
strcat(3) - concatenate two strings without bounds checking
strchr, index(3) - locate first occurrence of a character in a string
strcmp, strncmp(3) - compare strings
strcoll, strcoll_l(3) - compare strings according to current collation
strcpy(3) - copy a string without bounds checking
strcspn(3) - span the complement of a string
strdup, strndup(3) - save a copy of a string
strerror, strerror_l, strerror_r(3) - get error message string
strlcpy, strlcat(3) - size-bounded string copying and concatenation
strlen, strnlen(3) - find length of a string
strmode(3) - convert inode status information into a symbolic string
strncat(3) - concatenate a string with part of another
strncpy(3) - copy part of a string to another
strpbrk(3) - locate multiple characters in string
strrchr, rindex(3) - locate last occurrence of a character in a string
strsep(3) - separate strings
strsignal(3) - get signal description string
strspn(3) - span a string
strstr, strcasestr(3) - locate a substring in a string
strtok, strtok_r(3) - string token operations
strxfrm, strxfrm_l(3) - transform a string under locale
timingsafe_bcmp, timingsafe_memcmp(3) - timing-safe byte sequence comparisons
audio, audioctl(4) - device-independent audio driver layer
The reason for deprecating pages with names of the form "header_name(3)"
is less that we don't want non-function-name pages in section 3 and more
that we don't want manual pages for header files.
I don't think FreeBSD and NetBSD deprecated such pages though;
i still see lib/libc/string/string.3 in FreeBSD and NetBSD.
> Done by Linux man-pages, and BSDs (see BSD's sysexits(3)).
OpenBSD deprecated sysexits(3) - the whole feature, not only the
name of the manual page. The DESCRIPTION in our page starts as
follows:
A few programs exit with the following non-portable error codes.
Do not use them.
While i highly respect Eric Allman, IMHO inventing "sysexits"
was a bad idea.
> 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).
Sounds like the least bad solution to me.
> - 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.
As explained above, man/man0 has traditionally been used for
something else. The traditional use has lost much of its
importance during the last two decades and right now, it doesn't
seem likely to me that it might need to be revived, but still,
not clashing with it seems better if it can be avoided.
> - Putting them in man7.
> Debian moves man0 pages to 7POSIX (but uses man7/).
I don't like that. The "Miscellaneous Information Manual" (section 7)
is mostly intended to be user-facing pages like editline(7),
environ(7), glob(7), hier(7), man(7), packages(7), ports(7),
re_format(7), symlink(7), utf8(7). Pages that are only interesting
for programmers are less welcome in section 7, even though a few
exceptions exist, for example operator(7).
Manual pages for C header files clearly need to be part of
the "Library Functions Manual" (section 3).
> 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).
That all makes sense to me.
> - BSDs still have a few (maybe only one?) header page in man3: sysexits(3).
Don't worry about that one, it is utterly unimportant, and almost
nobody uses it.
> - Section 0 becomes desert, and maybe someone can give it a new use in
> the future, if a new section is ever need.
As argued above, it might be best to not repurpose man/man0.
Yours,
Ingo
