On Sun, Aug 10, 2025, at 7:47 PM, Wiley Young wrote:
> Well, by common convention, I suppose. A great many system commands do
> offer a '--help' option. In comparison very few system commands have shell
> builtins with the same name. Most of the time, whenever anyone types in
> `[CMD] --help` interactively, they're looking for the help file from a
> binary command. That's why.
No. They're looking for help for the same command that would run
if they ran CMD with any other arguments, regardless of whether
it's built-in or external. That's why bash's built-ins recognize
a "--help" argument in the first place.
> "See also: /bin/kill --help" might be a worthwhile addition to the output
> of `help kill`, in my opinion.
Firstly, there might be multiple external implementations available,
not just /bin/kill (if that's even the right location on the user's
system). How would bash know which one is the "best" one to draw
attention to?
Secondly, why point users to the documentation of an implementation
they don't intend to use? So they can get confused when they try
doing something with plain "kill" and it disagrees with what that
other documentation says?
> The '--timeout' option for /bin/kill is particularly useful.
GNU kill is not the only external implementation.
> Since people
> learn how, in part, to use commands from the outputs of `[CMD] --help`,
> obfuscating that info seems counterproductive.
It's not obfuscation. "Other implementations may work differently"
is something you could say about literally any command, anywhere.
Should they all waste text pointing this out? Should the bash
documentation go out of its way to mention that dash, ksh, and zsh
work differently, as well?
> Besides, '--help' isn't a listed option for builtin kill (or printf).
>
> $ builtin kill ps; echo $?
> bash: kill: ps: arguments must be process or job IDs
> 1
>
> The string '--help' is obviously neither (process ID nor job ID), but
> there's no formal error message.
GNU kill doesn't mention "--help" in this scenario either.
In any case, this would be trivial to change, if desired.
> Rather the help file for builtin kill is
> printed, when it isn't positively known either way which help message any
> user at the CLI might want to see.
This is like arguing that when the user runs
kill
"it isn't positively known either way which [implementation] any
user at the CLI might want to [use]." Strictly speaking, true.
In practice, not a useful thing to think about.
The shell cannot read the user's mind. The only sane thing to do
is follow the established command lookup procedure. The presence
of a "--help" argument doesn't change that.
> In `man bash` the only mention of '--help' is in the OPTIONS section near
> the top, where it's intended to refer to `bash --help`. That command/option
> combo prints a help file for the bash binary. In the last 10 lines thereof,
> there are some pointers about how to get some more information on shell
> builtins.
>
> Perhaps (builtin) `kill --help` should print the same output as `bash
> --help`? In that case, at least any help file printed from a '--help'
> option would consistently refer to the optargs of a binary.
Responding to the user's request for help with one command (kill)
by printing information for a different command (bash) would not
be helpful.
--
vq
