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
