Hi Alejandro, Alejandro Colomar wrote on Sun, Jul 24, 2022 at 01:09:23PM +0200: > On 7/23/22 20:16, Ingo Schwarze wrote: >> Alejandro Colomar wrote: [...] >>> 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. Admitted, it's a weak argument. Having lots of useless directories does not do *significant* harm. Then again, in general, i would say it is good practice to not add needless files or directories, even when they are not particularly harmful. They still make find(1) and ls -R output and Makefiles longer. Not doing needless things is a general aim of design economy. Besides, when there is not much to gain in the first place, even weak counter-arguments wield non-zero weight. > On the other hand, reading the output of ls(1) in a system with free > use of subsections provides useful information. I flatly deny that argument. The Solaris list of suffixes deleted above does not tell me anything of value. It's just a list of random sources of software, often with arbitrary partitions, and many of the suffixes are non-descriptive. [...] >> 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 Not on the Solaris 11 system i have access to: > uname -a SunOS unstable11s 5.11 11.3 sun4u sparc SUNW,SPARC-Enterprise > man -K e | grep 3type [ no output] > ls -d /usr/share/man/*type* /usr/share/man/*type*: No such file or directory > ls -d /usr/gnu/share/man/*type* /usr/gnu/share/man/*type*: No such file or directory > (I guess Illumos too), Not according to https://src.illumos.org/source/search?path=3type nor according to https://src.illumos.org/source/xref/illumos-gate/usr/src/man/ . Again, Solaris suffixes do *not* indicate logical subdivisions, but only a rather fuzzy, arbitrary, and inconsistent "where we got these files from", at least if i understand correctly. > 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". That argument has no merit. The pre-eminent rule is "all documentation of function libraries belongs in section 3" and explaining data types (typically defined by the function libraries in the same header files as the functions) are clearly part of that. The rule "all library documentation should be organized by functions" is secondary to that, and the rule "all section 3 names should be function names" is merely a corollary to that. So even if you throw the rule "all library dicumentation should be organized by functions" overboard, that is still no excuse for moving part of the library documentation out of section 3. It also makes sense to keep it all together in the same section because it is needed by exactly the same people (programmers) in exactly the same way (when reading and writing code and wondering what words contained in the code mean). >> 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). Yes. Searching for preprocessor constants and searching for data type names are essentially semantic search features. So it is your choice to pick a 197x-era markup language that does not provide semantic markup but only physical markup. But than it feels irrational to me to turn around and complain not getting semantic search. Unless you are a Prime Minister, you cannot have your cake and eat it. Trying to work around the lack of semantic markup by moving everything into the manual page names feels like very poor design to me. > And types tend to be not very well documented if they are > documented as part of a function page. We disagree about that, and i won't repeat my full explanation why. I'll repeat only this one aspect: There are few syntax elements where context matters as much as for types; types live by how they are used. Separating their description from the functions using them is a disservice to users, forcing them to jump around various pages instead of having explained together what belongs together. > And they also tend to be documented several times (out of sync, > of course). Any kind of documentation needs discipline and diligence and maintenance, and none of it can ever be perfect. But that's no excuse for artificially tearing apart what users need together. Yours, Ingo
