Re: man -M tcl (was: All caps .TH page title)

[Alejandro Colomar]

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 open
>
> > Now 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/>

OpenPGP_signature
Description: OpenPGP digital signature