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

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

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

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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]