Re: Linux man-pages Makefile portability

[Ingo Schwarze]

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