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/24/22 16:57, Ingo Schwarze wrote:
[...]
I'm not happy with this approach.  I don't want to be typing paths for
system stuff (your /usr/local is /usr in GNU/Linux systems;

Then use an alias like

   alias tclman='man -M /usr/local/lib/tcl/tcl8.5/man/'

It's not like users are normally using dozens of different languages
at the same time, nor is the number of languages that provide a
collection of manual pages very significant.  So there isn't any
real-world problem that needs solving.

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.

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

Would your -M require that the pages live in a separate path? Or could it support subpaths?


Disclaimer: the above is not a finished design, just a preliminary
idea.  But i'm very certain that -M or something derived from -M
is the tool for the job and -s or something derived from -s is not.
Because when you want a python manual page, you most definitely want
"Python only" and it serves no purpose whatsoever to search through
various trees and various sections, and least of all to badly design
a string-based composite data type like "number_language": that causes
all the ambiguity and confusion you are already discussing, and
it is error-prone and fragile in the parser on top of that.

Also, the concept of "for which language" and the concept of sections
are orthognal.  A programming langauge system usually provides
utility programs (1), library functions (3), file formats(5),
administration tools (8), and so on.

Agree.


The reason i didn't pursue the man.conf(5) alias idea so far is that
the practical need for it is very limited.  No one ever asked me for
it as far as i recall, shell aliases do the job just fine. >

If you want to search pages in section 3type, `man -s3type regex`.
However, having some pages in subsections of 3, and others in the main 3
section, is good for pages in subsections, but bad for pages in the main
section (`man -s3 regex` would show all of the subsections' pages).
That has a simple solution: move libc pages to man3c (and libm to man3m,
...).  Since `man 3 printf` will continue working if this change is
done, it doesn't seem to have backwards compatibility issues.

While the effect on the end user is indeed limited, you are proposing
a massive file system reshuffle here that seems somewhat in search of
a problem it wants to solve.  Yes, systems do exist that traditionally
use lots of section suffixes, so it *is* vital that man(1) implementations
support such suffixes.  But i claim that even in Solaris, those suffixes
serve little practical purpose and users are best off simply ignoring
them.

I do want to document types (even if I had to document them in function pages, I'd add link pages with the name of the type, for reasons already stated in several other threads).

Types are better documented standalone, IMO, also for reasons I detailed in several other threads.

And, as also discussed in several threads, having type pages in man3 is problematic (collisions, ambiguity (does foo(3) refer to a function or a type? foo(3type) does certainly refer to a type; and foo(3[c]) should certainly refer to a function).




Also, you can put unimportant subsections at the end of the search
list, to not hide other more important pages.

In *BSD, support for changing the search list was deleted years ago.
That feature was an example of overengineering and useless complication.
I don't recall even one single complaint from a user who wanted the
feature back or explained what they were using it for.  Not one
person needing it in over half a decade since it was deleted...

Okay.


Cheers,

Alex

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