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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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

Attachment: OpenPGP_signature
Description: OpenPGP digital signature


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux