Re: Linux man-pages Makefile portability

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 5984 bytes --]

Hi Ingo!

On 7/22/22 18:59, Ingo Schwarze 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".

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

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 guess Illumos shares this subsectioning scheme.

Do you know from the top of your head if any of those is dedicated to 
constants such as NULL, PATH_MAX, or BUFSIZ?

In my git clone of Illumos, I can't find anything relevant:

alx@asus5775:~/src/illumos$ find  | grep -i null | grep man
./illumos-gate/usr/src/man/man9f/nulldev.9f
./illumos-gate/usr/src/man/man4d/null.4d
./illumos-gate/usr/src/man/man4d/nulldriver.4d


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

I actually make it as easy as I can to modify directory names in the 
Makefile through the standard GNU directory variables.

>   - file names

I don't expect them to change filenames, even if they change dirs.  It 
wouldn't make sense at all.

>   - .TH macros

The same as fith file names.  I expect them to want the pages to be in 
subsections, even if they wouldn't like the directory structure.

>   - and manual page cross references

That's a more difficult one.  They would need to run a sed script for 
every release.  A good reason to not modify it.

If they change dirs and don't change this, they'd break .so links.

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

:)

Cheers,

Alex

> 
> Yours,
>    Ingo

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]