On Mon, 11 Aug 2025 at 13:19, Wiley Young <wyeth2...@gmail.com> wrote:
> The reverse case applies with `getopts --help` vs. `getopt --help` as well
> as with `dir --help` vs. `dirs --help`.
Those would simply report 4 different messages (some of which might be
complaints --help is an unknown option).
Are you perhaps thinking of 'help dir', which would report on the built-in
'dirs' command (since 'dir' is a prefix of 'dirs')?
Perhaps (and I'm not convinced) 'help' could be augmented, so that as well
as its current behaviour (showing the help strings for all built-in
commands that have the given token as a lexical prefix), it would *also* show
a brief message for each matching command anywhere in PATH, perhaps along
the lines of:
$ help dir
Built-in commands matching 'dir*' include:
dirs: dirs [-clpv] [+N] [-N]
Display directory stack.
* [snip]*
Exit Status:
Returns success unless an invalid option is supplied or an error occurs.
For a list of built-in commands, try 'help help'.
Programs matching 'dir*' include:
dir (/usr/bin/dir)
dirac (/usr/local/bin/dirac)
dircolors (~/.local/bin/dircolors,
/bin/dircolors)
direct (/opt/navigate/bin/direct)
dirname (/usr/bin/dirname)
Try 'man -k dir' or 'info dir'
Functions matching 'dir*' include:
dir
dirty
To see the definition of the function 'dir', type:
declare -f dir
(Functions take precedence over programs with the same names.)
Aliases matching 'dir*' include:
dirty
To see the definition of the alias 'dirty', type:
alias dirty
(Aliases take precedence over both functions and programs with the same
names.)
If we're taking this path, then...
Too many matches for a given name should result in abbreviated output:
$ help x
help: no help topics match 'x*'; for a list of built-in commands, type:
help help
208 programs match 'x*'; for the full list type:
compgen -c x
Also try 'man -k x' or 'info x'
44 functions match 'x*'; for the full list type:
compgen -A function x
(Functions take precedence over programs with the same names.)
1 alias matches 'x*'; for the full list type:
compgen -A alias x
(Aliases take precedence over both functions and programs with the same
names.)
And perhaps 'help' could gain options to limit the output to each class of
command:
help [-A builtin|-b] BUILTIN-COMMAND
help [-A command|-c] PROGRAM-NAME
help -A function FUNCTION
help -A alias ALIAS
(Admittedly, anything other than -b is going to produce minimal output.)
Lastly, I suggest adding pseudo built-ins for 'man' and 'info' that provide
documentation but no implementation, along the lines of:
$ help man
man: man PROGRAM
The 'man' program provides information about programs (and some other
resources).
To obtain information about a system-provided program such as 'ls', type:
man ls
To obtain information about a built-in command such as 'cd', type:
man bash
-Martin
