Open nwalfield opened 4 months ago
I know at least git
has the help -a
flag (along with help -g
, see #5332). Cargo has the top-level --list
. Know of any other prior art?
My first concern is with how people discover this. People aren't likely to run sq help help
. Git advertises the flag with an after_help
'git help -a' and 'git help -g' list available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.
See 'git help git' for an overview of the system.
I would be loathe to add a blanket after help for people. Maybe them adding it is their way to "opt in".
My second concern is I'm unsure if a flag is the right approach. I feel like this would be better served as a "topic" (sq help commands
) rather than a flag. Mostly, this feels more consistent to me. In part, I've wondered about allowing you to take arbitrary commands and inserting a help
in the middle (much like you can with --help
) which means we need to ignore all flags.
I know at least git has the help -a flag (along with help -g, see https://github.com/clap-rs/clap/discussions/5332). Cargo has the top-level --list. Know of any other prior art?
gpg
has --dump-options
.
I would be loathe to add a blanket after help for people. Maybe them adding it is their way to "opt in".
I don't completely understand the suggestion. Do you mean people adding a "table-of-contents" flag is opting in, or people adding an after_help is opting in? Isn't the latter ambiguous, as someone could add an after_help for other reasons?
My second concern is I'm unsure if a flag is the right approach. I feel like this would be better served as a "topic" (sq help commands) rather than a flag.
I'd be fine with this. -a
was just inspired by git
.
I don't completely understand the suggestion. Do you mean people adding a "table-of-contents" flag is opting in, or people adding an after_help is opting in? Isn't the latter ambiguous, as someone could add an after_help for other reasons?
One idea is that we support -a
unconditionally but leave it to the caller to decide if they want to "support it" by them specifying the after_help
, rather than us doing it automatically.
Thanks for the clarification. I think you are saying that -a
is always implemented, but it is up to the application to document that. I think that is okay. But, it should probably still be documented under help
, even if most people probably do not run cli help help
:
$ sq help help
Print this message or the help of the given subcommand(s)
Usage: sq help [COMMAND]...
Arguments:
[COMMAND]... Print help for the subcommand(s)
Please complete the following tasks
Clap Version
4.5.0
Describe your use case
sq
is the command-line front end forsequoia-openpgp
. It has a dozen subcommands, and most of the subcommands have their own subcommands. This deep hierarchical structure means getting an overview ofsq
's functionality is not straightforward.Describe the solution you'd like
Most non-fiction books include a table of contents, which gives the reader a quick overview of what is covered and where. It would be nice if clap could offer similar functionality.
One idea what we had is to extended the
help
subcommand with an option, perhaps-a
, which recursively lists all subcommands. Right now,sq help
shows:-a
could perhaps show something like:I've spent some time looking at clap's documentation, but I couldn't find a way to extend the automatically generated
help
subcommand. One option would be to disable thehelp
subcommand and reimplement it insq
with the added functionality. This seems brittle, however.Alternatives, if applicable
No response
Additional Context
No response