On Jun 29, 2019 5:50 PM, Ingo Schwarze <schwarze@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
>
No comments:
Post a Comment