Re: Why no cd(1) man page in Ubuntu? (was: man-intro)

[James K. Lowden]

On Sun, 23 May 2021 13:55:58 +1000
"G. Branden Robinson" <g.branden.robinson@gmail.com> wrote:

> But as a Unix expert of long pedigree (unfurled above), you must
> surely already appreciate why "cd" in particular is a tricky case.
> 
> Commands get man pages.  So do library functions, system calls, device
> interfaces, and file formats.
> 
> "cd" is none of these.

"man cd" made me think about the Right Way [tm] to document shell
builtins.  I think I know, but I don't think it can be done. 

On machines close at hand, "man cd" produces

        macOS: BSD builtin(7)
        NetBSD: man page from csh
        Ubuntu: No manual entry for cd

I would argue the Ubuntu result is the best of a bad lot, because the
other two document builtin commands for shells the user is very likely
not using. 

I don't think anyone would argue that the user experience of the
shell's "help" feature is superior to a man(1) system that returns
accurate information about a command in the context of the user's
current shell.  So, why isn't that what happens?  It's a classic
example of Worse is Better.  

Take "man cd" for example.  Please.  

As a technical matter, of course it's no problem at all to document each
builtin with its own man page.  To prevent clashes, each shell could be
assigned its own subsection: 1sh, 1bash, 1csh, 1zsh, etc. 

To ensure the right page is requested,  the shell could implement a
"man" builtin to intercept the command.  Unless the command specified a
section, it could insert one, so that

        $ man cd
became
        $ man -s 1bash cd

It might be sufficient to define a "man" function that inserts the
section name if $1 matches any builtin, and then invokes /usr/bin/man. 

Even better would be a man system that supported indexed terms, so that
the command coud be converted to 

        $ man -x cd bash

but ... I think we know that. 

Alas, ideas are cheap. 

Much as I'd like to think my brilliant idea is original, I have to
think someone else already went down this road and rejected it as too
much work.  

Not technical work.  The technical work of converting the bash help
text to mdoc pages and writing the function to cause them to be found
is perhaps a few days' effort.  Preparing a patch and submitting it
might take a week, all in.  

But the hours or cultural massaging would be unbearable. Would only
that one could show up and say "Look!  man pages!" and be greeted with
the barest of encouragement. 

My own personal success rate with that approach has been exactly zero.
There is a lot of anti-man-page sentiment out there, and documentation
re-tooling (changing the autoconf work) is no one's idea of a good
time.  

Q: How many psychologists does it take to change a lightbulb? 

A: One, but the lightbulb has to want to change. 

The aversion the bash project once had to man pages has dissipated, as
evidenced by its abandonment of info(1) in favor of man(1).  But the
conversion is incomplete and (in my estimation) likely to remain that
way. 

--jkl

P.S.  I have version 2 of man-intro.1 ready, but I want to make sure
I've incorporated all feedback before I post it.  As you can see from
this post and the next, I got ... distracted.