On Jun 29, 2019 5:50 PM, Ingo Schwarze <schwa...@usta.de> wrote: > > 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). >
I don't think this would be needed on openbsd as the default install has everything you need for a basic system and it's easy to add additional packages. However, as I learned when I set up a Debian box for my son to play Minecraft it didn't. So it was kinda nice when I typed ifconfig it informed me what package to install and I eventually got everything working no thanks to the piss poor manual pages provided. Edgar > 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 >
