Hi Ingo, On 7/27/22 17:32, Ingo Schwarze wrote:
Hi Alejandro, Alejandro Colomar wrote on Sun, Jul 24, 2022 at 06:17:40PM +0200:On 7/24/22 16:57, Ingo Schwarze wrote:I even considered supporting aliases for manpath directories in man.conf(5), something like being able to say alias tcl /usr/local/lib/tcl/tcl8.5/man/ in /etc/man.conf and then being able to say man -M tcl openNow we're talking. I've long missed such a thing. Let's please discuss it.Well, it wouldn't be the first time i implemented a feature in mandoc that is not very urgently needed on OpenBSD but where the main need came from Linux (or Illumos or MacOS, for that matter). If it doesn't cause disruption or excessive complexity, which seems unlikely in this case, we can consider it. Do you think this would really get used in practice?
I don't know. I haven't received any such feature requests from users.But I've many times had the feeling that the man hierarchy is so flat and is so overpopulated (as soon as you start installing some packages; especially those that document their API in man3) that it's hard to find what you want. That's one of the reasons that I think man3type, man3const are better outside of man3.
If so, as a motivation, it would be useful to collect a handful of languages that would use this. So far, i'm mostly aware of Tcl and Tk. And of the POSIX manual pages.
BTW, I guess you also have the POSIX man pages in BSDs. Do they come from the kernel repo that I maintain, or do you have your own separate repos?
Of course i can't speak for man-db and other man(1) implementations. Then again, even if other man(1) implementations would not follow, maybe having -M aliases might be useful even in a single implementation. Users of the others could still use shell aliases.
Yep. I don't think that should be a problem.
One side effect useful for myself would be that i could do, in man.conf(5), alias B /usr/share/man alias P /usr/local/man alias X /usr/X11R6/man and then say man -kMB sha256 when i only want to base system pages and be undisturbed by ports pages - right now, i type "-M /usr/share/man" relatively often.
Yes, I also often want to compare the differences between the last release of the man-pages, and the page that I'm modifying, and that would be simpler with such a feature.
Or say man -MP:B to play with precedence.I wondered for a long time what happens if you create subdirs within a man? section. How do man(1)s handle </usr/share/man/man3/python/foo.3>?On *BSD systems, that typically means: The architecture-specific library function foo(3) for the "python" hardware architecture. Here are a few examples from OpenBSD: /usr/share/man/man1/sparc64/mksuncd.1 /usr/share/man/man2/armv7/arm_sync_icache.2 /usr/share/man/man2/i386/i386_iopl.2 /usr/share/man/man3/octeon/cacheflush.3 /usr/share/man/man3/sgi/get_fpc_csr.3 /usr/share/man/man4/alpha/irongate.4 /usr/share/man/man4/amd64/mpbios.4 /usr/share/man/man4/luna88k/cbus.4 /usr/share/man/man4/macppc/openpic.4 /usr/share/man/man4/powerpc64/opalcons.4 /usr/share/man/man4/riscv64/sfgpio.4 /usr/share/man/man5/sparc64/ldom.conf.5 /usr/share/man/man8/hppa/boot.8 /usr/share/man/man8/macppc/pdisk.8 /usr/share/man/man8/sgi/sgivol.8 /usr/share/man/man8/sparc64/ldomctl.8 So, lets assume i'm on a amd64 machine and want to learn how logical domains (a virtualization feature implemented in SPARC hardware) are configured: $ arch OpenBSD.amd64 $ man ldom.conf man: No entry for ldom.conf in the manual. $ man -S sparc64 ldom.conf [...] NAME ldom.conf Logical Domain configuration [...] Note that i said -S there, not -s nor -M. So i advise against doing that for python: the namespace is already taken for a different purpose.
Yeah, idea discarded.
Using /usr/share/man/python/man3/foo.3 would be similarly bad, that usually means: The translation of /usr/share/man/man3/foo.3 into the natural language "python". Typical examples on OpenBSD: /usr/local/man/ja/man1/w3m.1 /usr/local/man/pt_BR/man6/wesnoth.6 /usr/local/man/de/man1/dvipdf.1
Makes, sense; also discarded.
Would your -M require that the pages live in a separate path? Or could it support subpaths?The directory -M points to needs to contain the usual man1/ man3/ man5/ etc. subdirectories. Where exactly you put that doesn't matter for man(1), but i strongly advise against putting it into /usr/share/man because all the namespace in there is already taken for other purposes, and putting it in there anyway is likely to confuse tools like makewhatis(8), mandb(8), catman(8), and apropos(1). If a language is so large that it comes with a whole suite of manual pages (as ooposed to a language like awk(1) small enough to be documented in a single page), then that language is likely to already have its own directory for data files, typically somewhere below /usr/share/. Maybe it even has its own directory below /usr/share/doc/ already. For example, /usr/share/doc/python already exists on Debian, so /usr/share/doc/python/man/man[1-5]/... might one be reasoable choice, albeit certainly not the only option.
I'd like to discuss about the best place to recommend putting manual pages.Do you know if any projects (Tcl and Tk maybe) are already using a specific path for man pages?
I think something under $docdir would be a nice place. The FHS mentions[1] </usr[/local]/share/doc>.GNU specifies[2] that $docdir should be </usr/local/share/doc/pkgname> for a </usr/local> prefix.
So they seem to agree in where $docdir lives. Then we could make the pkg-specific mandirs be </usr/local/share/doc/pkgname/man/man*>.
What are your thoughts? Cheers, Alex [1]: <https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s11.html> [2]: <https://www.gnu.org/prep/standards/html_node/Directory-Variables.html> -- Alejandro Colomar <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
