On Sun, 23 May 2021 13:55:58 +1000 "G. Branden Robinson" <g.branden.robin...@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.