Re: Linux man-pages Makefile portability

[Ingo Schwarze <schwarze@usta.de>]

Hi Alejandro,

Alejandro Colomar wrote on Fri, Jul 22, 2022 at 07:37:14PM +0200:
> On 7/22/22 18:59, Ingo Schwarze wrote:
>> Alejandro Colomar wrote:

>>> I considered[6] using man3type, and used man3 in the end just because
>>> when in doubt I opted for the smallest change.  Knowing that it breaks
>>> mandoc(1), I'll definitely move to <man3type/>.

>> I didn't mean to say man3/id_t.3type "breaks mandoc".  Quite to the
>> contrary, the above quotation explains that mandoc copes with it.

> Yeah, I didn't mean break as in "mandoc(1) goes nuts, or crashes", but 
> rather as in "it doesn't do what I wanted it to do".

Even that is an overstatement.  The difference between being in section 3p
only and being in both section 3p and 3 is barely user-visible.

Here is a manual page that is in section 3p and in section 3p only,
on OpenBSD-current:

   $ man -w warnings
  /usr/share/man/man3p/warnings.3p
   $ grep  '^\.TH' $(man -w warnings)
  .TH warnings 3p "2021-03-02" "perl v5.32.1" "Perl Programmers Reference Guide"

But lo and behold:

   $ man -s 3 -w warnings
  /usr/share/man/man3p/warnings.3p

Mandoc still finds the page in section 3 because "3" is a substring of "3p",
and that not only makes sense from the string processing perspective
but also from a logical perspective because section 3p is a particular
corner of section 3 after all.

To cause mandoc to *not* find the page in section 3, the user would have
to type something like

   $ man -k 'sec~3$' -a warnings
  man: nothing appropriate

Even i don't normally use such advanced syntax (regex matching on section
names using the "sec" search keyword and the explicit regex operator
and the -a logical operator for the conjunction of two search criteria).
I doubt whether man-db even supports similar features...

[...]
>> The system making the heaviest use of section suffixes i'm aware of
>> is Solaris:
>> 
>>    > uname -a
>>    SunOS unstable11s 5.11 11.3 sun4u sparc SUNW,SPARC-Enterprise
>>    > ls /usr/share/man/
>>    entities      man3dat       man3mvec      man3sysevent    man4b
>>    fr            man3dax       man3nsl       man3tcl         man5
>>    fr.ISO8859-1  man3devid     man3nvpair    man3tecla       man5oldap
>>    fr.UTF-8      man3devinfo   man3oldap     man3tiff        man5openssl
>>    it            man3dlpi      man3openssl   man3tsol        man7
>>    it.ISO8859-1  man3dns_sd    man3p         man3uuid        man7d
>>    it.UTF-8      man3elf       man3pam       man3volmgt      man7fs
>>    ja_JP.UTF-8   man3exacct    man3pcap      man3x           man7i
>>    man-index     man3ext       man3perl      man3x11         man7ipp
>>    man.cf        man3f         man3pi        man3xau         man7m
>>    man1          man3fcoe      man3picl      man3xaw         man7openssl
>>    man1b         man3fm        man3picltree  man3xcb         man7p
>>    man1c         man3fstyp     man3plot      man3xcomposite  man8
>>    man1m         man3gen       man3pool      man3xcurses     man8oldap
>>    man1oldap     man3gss       man3proc      man3xcursor     man8s
>>    man1openssl   man3hbaapi    man3project   man3xevie       man9
>>    man1s         man3head      man3rad       man3xext        man9e
>>    man1t         man3iscsit    man3reparse   man3xi          man9f
>>    man2          man3kstat     man3resolv    man3xinerama    man9p
>>    man3          man3kvm       man3rpc       man3xmu         man9s
>>    man3archive   man3layout    man3sasl      man3xnet        pl
>>    man3c         man3ldap      man3scf       man3xrandr      pl.ISO8859-2
>>    man3c_db      man3lgrp      man3sec       man3xss         pl.UTF-8
>>    man3cc4       man3lib       man3sip       man3xt          ru.KOI8-R
>>    man3cfgadm    man3m         man3slp       man3xtsol       ru.UTF-8
>>    man3cmi       man3mail      man3snmp      man3xtst        zh_CN.UTF-8
>>    man3commputil man3malloc    man3socket    man3xv
>>    man3contract  man3mlib      man3srpt      man3xxf86vm
>>    man3cpc       man3mp        man3ssh2      man3zonestat
>>    man3curses    man3mpapi     man3stmf      man4

> Wow!
> Although it's interesting to know that this list exists:
> I can check it when trying to come up with a section name.

I would somewhat advise against that.  While i do think that consistency
is good *if* you decide to use a section suffix, i'd still recommend
to use section suffixes sparingly, at least in operating systems
that use them sparingly now.  They provide relatively little value,
make the top directory of the manpath larger and less readable,
and they are in particular *not* well suited to moving stuff out of
the non-suffix directories that users may not wish to see by default.
For example, suppose you created a directory man3py to document
python library functions.  As explained above, these pages will *still*
show up even when people type "man 3" or "man 3p" rather than "man 3py".

> I guess Illumos shares this subsectioning scheme.

More or less, according to
https://src.illumos.org/source/xref/illumos-gate/usr/src/man/ -
it's not identical though.

> Do you know from the top of your head if any of those is dedicated to 
> constants such as NULL, PATH_MAX, or BUFSIZ?

I doubt it, for two reasons.  On the one hand, my impression is that
at least in Solaris, section suffixes are not so much used for
logical subdivision of sections but more according to provenance;
for example, man1b is for BSD compat features, man1s is for commands
specific to SunOS, man3c is for libc, man3ext is for an "extended
library", man3p is for the Sun performance library (available for
both C and FORTRAN 95), and so on.

On the other hand, naming manual pages after symbolic constants
or after type names is so unsual that i doubt any scheme exists
for that.  The most widely used way to look up manual pages
by the names of symbolic constants or type names probably is
using macro keys as implemented in the mandoc version of apropos(1).
That is used by most FreeBSD, OpenBSD, Alpine Linux, and Void Linux.
I admit that doesn't qualify as "widely used", but "most widely used"
is probably true all the same.  ;-)

Yours,
  Ingo