[TO += Colin; CC += man-dv-devel@;
there's a bug in man(1)'s autocomplete]
Hi Ingo (and Colin),
On 7/23/22 20:16, Ingo Schwarze wrote:
[...]
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,
I don't think there's any benefit of keeping $(mandir) contain only the
standard man? subdirs. Everybody already knows about them, so nobody
needs to read the output of ls(1) in such a system. On the other hand,
reading the output of ls(1) in a system with free use of subsections
provides useful information. If one needs to filter a bit, standard
Unix tools come into play.
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".
But the good thing is they can be put the last in the list of pages to
be shown by man(1), so they won't hide another page.
In my Debian system, man(1) shows:
1 n l 8 3 0 2 3posix 3pm 3perl 3am 5 4 9 6 7
3type and 3const could go at the end of that, to avoid hiding pages in
section 7.
While testing some related stuff to add to my arguments, I just
understood of a bug that I knew existed but never thought too much about
it, and related to one that Branden reported to me recently:
man 3 foo[TAB]
autocomplete is smart enough to only search pages in section 3 (I don't
know if it finds pages in subsections from 3; I guess it does).
man [-s]3type foo[TAB]
autocomplete should search in 3type, but it doesn't quite work.
However, I noticed there's a difference in behavior between 3posix and
3type (3posix only exists as a suffix, but pages live in man3; 3type is
a correct subsection, using man3type and .3type), so maybe my work can
help fix that bug in the autocomplete scripts.
I know you don't use autocomplete for those things, but it comes in
handy to me :)
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.
Actually, man3type exists in several systems. Solaris has it (I guess
Illumos too), and I've seen it in other systems (something from Oracle,
IIRC). libbsd(7) also documents types, although they put them in the
global namespace, which I think you and I agree that it's not quite
right because of "documentation about a non-function in man3".
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. ;-)
That leaves out man(7). And types tend to be not very well documented
if they are documented as part of a function page. And they also tend
to be documented several times (out of sync, of course).
Cheers,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
