Hi Ian,
ropers wrote on Sat, Jun 29, 2019 at 10:40:30PM +0200:
> This relates to a long-standing annoyance: When I do `man kill` for
> example, the manpage shown is for code that won't be what runs when I
> do `kill <something>`.
> I suppose the general case is that there can be discrepancies between
>
>>> $ which kill
>>> /bin/kill
>>> $ type kill
>>> kill is a shell builtin
>
> and perhaps `man kill` too (kill is just an example; the issue
> generalises).
> As much as this looks like a problem that wants solving, it's such a
> long-standing and fundamental issue that I'm not sure what can be
> done. Is there any sense in adding some checks to man(1) to ensure the
> "wrong" information is not displayed?
It isn't the wrong information. The command
$ man kill
means:
Show me the manual page with the name "kill".
Clearly, that will be kill(1) and not ksh(1).
If what you mean is:
Show me the manual pages documenting "kill", no matter whether
as a stand-alone command or an internal command built-in to another
program.
Then you need to say:
$ man -k Ic,Nm=kill
or something similar.
> An added complication: When users are looking at the respective
> sections for builtins in `man sh` vs `man ksh`, it may not always be
> clear which description and behaviour would actually apply.
> It's also very cumbersome to jump to the correct section e.g. in `man
> ksh`, even if the user already knows what kind of command and
> documentation to look for (which is half the battle). One way I
> sometimes do that is:
> >> $ man ksh
> >> G?The following describes/<builtin_name>
> This obviously isn't ideal, but I have not found any applicable
> shortcuts. Would it be possible to add some way to make it easier to
> accomplish the task "show me the documentation of builtin <foo> in man
> ksh"?
What's wrong with:
$ man -O tag=kill ksh
It's documented in
$ man -O tag=tag mandoc
Alternatively, type this:
man ksh<ENTER>:tkill<ENTER>
As documented here:
$ man -O tag=MANPAGER man
> Anyway, in an ideal world, typing man <command> would always show the
> man page actually relevant to what the box would do if the user typed
> <command> at the prompt.
No. That's not how man(1) is defined. It's
usage: man [-acfhklw] [-C file] [-M path] [-m path] [-S subsection]
[[-s] section] name ...
not
usage: man ... command ...
Besides, how man(1) searches for the "name" should absolutely not
depend on the shell the user is currently running.
What next? When you run
$ perl -e 'system qw(man kill)'
you want to see the same as with:
$ perldoc -f kill
> I don't know how this could be solved though; I'm just noticing that
> there's much inconsistency and considerable possibility for user
> confusion in that area.
No man(1) begaves quite consistently and predictably. You are
merely confused about what the man(1) "name" argument is and how
to search for internal commands of arbitrary programs instead.
> As another aside:
> On Ubuntu (and probably Debian), when the user types a command name
> that does not correspond to any program actually installed, but that
> *does* correspond to an executable present in a .deb package present
> in currently configured repositories, the system will recommend that
> package (sometimes several packages) and helpfully print what the user
> would have to type to install said package(s).
How revolting. That's very contrary to the spirit of Unix.
We certainly don't want to copy that. No program should attempt
to implement its very own partial solution for every *other* task
under the sun, but instead focus on doiing its own task well.
If you want to search for a manual page, use man(1).
If you want to search for packages, use pkglocate(1).
This is perfectly fine, exactly as it should be:
schwarze@isnote $ man bash
man: No entry for bash in the manual.
schwarze@isnote $ pkglocate bin/bash | head -n1
bash-5.0.7p0:shells/bash:/usr/local/bin/bash
> To end on a positive: Can I add how much I appreciate that OpenBSD
> hard-links help(1) to man(1),
Heh; deraadt@ did that on Sep 14, 1998 for OpenBSD 2.4 ...
> and that man will default to `man help` when called as help?
and aaron@ added the help(1) manual page on Oct 18, 1999
for OpenBSD 2.6.
> This elegant way of having OpenBSD respond to `help` is really
> n00b-friendly.
And yet, even among those tiny innovations that are somehow neat,
not all get picked up elsewhere:
https://man.openbsd.org/FreeBSD-12.0/help
https://man.openbsd.org/NetBSD-8.0/help
https://man.openbsd.org/Linux-5.01/help
Yours,
Ingo
