Re: Linux man-pages Makefile portability

Ingo Schwarze
2022-07-22T16:59:31Z

Hi Alejandro,

Alejandro Colomar wrote on Thu, Jul 21, 2022 at 04:17:18PM +0200:
> On 7/3/22 23:44, Alejandro Colomar wrote:

>> [added Branden, as he was involved in discussions regarding man3type;
>> Branden, you might want to visit this thread from the begining, as I
>> only copied the minimum to reply; it's in linux-man@]

>> On 6/20/22 15:49, Ingo Schwarze wrote:
> [...]
>>> That said, other projects are of course free to have such pages if
>>> they want to.  The mandoc(1) program is also able to handle paths like
>>> "man3/id_t.3type".  It will consider that page to be *both* in section
>>> "3" (as specified by the directory name) and in section "3type" (as
>>> specified by the file name and by the .TH macro).  I would consider
>>> it better style to keep section names consistent, i.e. to use either
>>> "man3/id_t.3" .TH id_t 3 or "man3type/id_t.3type" .TH id_t 3type,
>>> but it's not a big deal: since many systems (in particular various
>>> Linux distros) suffer from such inconsistencies, handling such
>>> inconsistencies gracefully is an important feature that certainly
>>> won't get removed.

>> 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.

However, when it comes to robustness with respect to *other* man(1)
implementations apart from mandoc and man-db, i suspect the most
portable and reliable way is using man1 - man9 only with no suffixes,
consistent suffixes like "man3type/id_t.3type" are probably medium
portability and medium reliability, and inconsistent suffixes
like "man3/id_t.3type" and "man3type/id_t.3" are likely the least
portable and the most fragile.

So your change is an improvement.

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

Inside these directories, they are *mostly* using the convention
"keep both section names consistent", so i do think that is good
to follow. Even Solaris isn't perfect in that respect, though,
they have, for example,

/usr/share/man/man3cc4/cartpol.3

but on first sight, i only found about two dozen such examples.

> I fixed it:
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=451a27a78d51973b01bfb5d3b1e0ec081d9161e1>

I did not scrutinize your change in detail, but had a brief look at it
and did not see any obvious problems.

> And Debian seems to work fine with man3type/ and man2type/ out of the
> box, so I prefer it this way. I hope that other projects follow the
> example; and that packagers/distributions also create subsection
> directories, and don't undo my work.

On Linux, undoing it would make very little sense to me because i expect
that all man(1) programs commonly used on Linux can cope with section
suffixes, and in particular with consistent use of session suffixes.
Besides, undoing it properly is hardly possibly for a packager.
If would require changing all these:

- directory names
- file names
- .TH macros
- and manual page cross references

So for better or worse, the only sane option for a packages is to follow
your lead.

Yours,
Ingo