Display help for all subcommands at the same time

[mmstick]

Maintainer's note: Proposed solution

Setting:

• help_includes_subcommands or help_shows_subcommands
  • trying to keep what the setting impacts first, otherwise I would have done flatten_subcommands_in_help
  • not starting with subcommand because this is set on the parent of the subcommands rather than a subcommand itself

Help output:

• USAGE includes regular usage and usage for each subcommand that is visible in short help
• Show current command's subcommand and arguments like normal
  • Even if parent has help_includes_subcommands set (this diverges from git stash <command> -h which shows git stash -h)
• After current command's arguments, for each subcommand visible in short help
  • Show a header for the subcommand
  • Show short-help arguments under the above heading (ie ignore help headings)
    • Ideally, hide all generated and global arguments
  • Do not list subcommands

Man page:

• Same as above but show long-help
• This will actually be split out into a separate issue

Open question:

• Do we recurse?
  • If so, we should elide intermediate subcommands that only have generated arguments

Implementation:

• Usage generation will need to be refactored so we can request the parts of it that we need

---

The API is very large and I've struggled to find any examples or hints pointing to this possibility. Is it possible for the help page for a program to list the help pages of all subcommands at the same time, rather than just the current scope? That way the user does not need to also request for the help info from each subcommand.

[epage]

Do you have examples of commands that do that today? I'm having a hard time picturing this not being overwhelming.

[mmstick]

I would have examples if clap supported it. Command line applications don't always have 100s of options. Underwhelming is how I'd describe the current usefulness of the help info generated right now.

[mmstick]

# system76-power -h
system76-power 1.1.20
Utility for managing graphics and power profiles

USAGE:
    system76-power <SUBCOMMAND>

OPTIONS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    charge-thresholds    Set thresholds for battery charging
    daemon               Runs the program in daemon mode
    graphics             Query or set the graphics mode
    help                 Prints this message or the help of the given subcommand(s)
    profile              Query or set the power profile

# system76-power profile -h
system76-power-profile
Queries or sets the power profile.

 - If an argument is not provided, the power profile will be queried
 - Otherwise, that profile will be set, if it is a valid profile

USAGE:
    system76-power profile [profile]

OPTIONS:
    -h, --help    Prints help information

ARGS:
    <profile>    set the power profile [possible values: battery, balanced, performance]

Would be much more useful combined.

[mkayaalp]

# opkg
opkg must have one sub-command argument
usage: opkg [options...] sub-command [arguments...]
where sub-command is one of:

Package Manipulation:
	update			Update list of available packages
	upgrade <pkgs>		Upgrade packages
	install <pkgs>		Install package(s)
	configure <pkgs>	Configure unpacked package(s)
	remove <pkgs|regexp>	Remove package(s)
	flag <flag> <pkgs>	Flag package(s)
	 <flag>=hold|noprune|user|ok|installed|unpacked (one per invocation)

Informational Commands:
	list			List available packages
	list-installed		List installed packages
	list-upgradable		List installed and upgradable packages
	list-changed-conffiles	List user modified configuration files
	files <pkg>		List files belonging to <pkg>
	search <file|regexp>	List package providing <file>
	find <regexp>		List packages whose name or description matches <regexp>
	info [pkg|regexp]	Display all info for <pkg>
	status [pkg|regexp]	Display all status for <pkg>
	download <pkg>		Download <pkg> to current directory
	compare-versions <v1> <op> <v2>
	                    compare versions using <= < > >= = << >>
	print-architecture	List installable package architectures
	depends [-A] [pkgname|pat]+
	whatdepends [-A] [pkgname|pat]+
	whatdependsrec [-A] [pkgname|pat]+
	whatrecommends[-A] [pkgname|pat]+
	whatsuggests[-A] [pkgname|pat]+
	whatprovides [-A] [pkgname|pat]+
	whatconflicts [-A] [pkgname|pat]+
	whatreplaces [-A] [pkgname|pat]+

Options:
	-A			Query all packages not just those installed
	-V[<level>]		Set verbosity level to <level>.
	--verbosity[=<level>]	Verbosity levels:
					0 errors only
					1 normal messages (default)
					2 informative messages
					3 debug
					4 debug level 2
	-f <conf_file>		Use <conf_file> as the opkg configuration file
	--conf <conf_file>
	--cache <directory>	Use a package cache
	-d <dest_name>		Use <dest_name> as the the root directory for
	--dest <dest_name>	package installation, removal, upgrading.
				<dest_name> should be a defined dest name from
				the configuration file, (but can also be a
				directory name in a pinch).
	-o <dir>		Use <dir> as the root directory for
	--offline-root <dir>	offline installation of packages.
	--verify-program <path>	Use the given program to verify usign signatures
	--add-arch <arch>:<prio>	Register architecture with given priority
	--add-dest <name>:<path>	Register destination with given path

Force Options:
	--force-depends		Install/remove despite failed dependencies
	--force-maintainer	Overwrite preexisting config files
	--force-reinstall	Reinstall package(s)
	--force-overwrite	Overwrite files from other package(s)
	--force-downgrade	Allow opkg to downgrade packages
	--force-space		Disable free space checks
	--force-postinstall	Run postinstall scripts even in offline mode
	--force-remove	Remove package even if prerm script fails
	--force-checksum	Don't fail on checksum mismatches
	--no-check-certificate Don't validate SSL certificates
	--noaction		No action -- test only
	--download-only	No action -- download only
	--nodeps		Do not follow dependencies
	--nocase		Perform case insensitive pattern matching
	--size			Print package size when listing available packages
	--strip-abi		Print package name without appended ABI version
	--force-removal-of-dependent-packages
				Remove package and all dependencies
	--autoremove		Remove packages that were installed
				automatically to satisfy dependencies
	-t			Specify tmp-dir.
	--tmp-dir		Specify tmp-dir.
	-l			Specify lists-dir.
	--lists-dir		Specify lists-dir.

 regexp could be something like 'pkgname*' '*file*' or similar
 e.g. opkg info 'libstd*' or opkg search '*libop*' or opkg remove 'libncur*'

[epage]

Do you have examples of commands that do that today? I'm having a hard time picturing this not being overwhelming.

I would have examples if clap supported it. Command line applications don't always have 100s of options. Underwhelming is how I'd describe the current usefulness of the help info generated right now.

I was hoping for precedent from another CLI to take inspiration from and to see how well it works in practice

@mkayaalp I see that opkg shows subcommand usage. Is that your proposal for this? Looks similar to #962

[dpc]

I was hoping for precedent from another CLI to take inspiration from and to see how well it works in practice

cargo-crev has many, often multiple level commands, like cargo crev repo fetch all --someoptions. There's currently no way for the users to get all the possible commands in one go, which hurts discoverability.

[epage]

@dpc mind hacking up example output of what your ideal would look like with cargo-crev?

[dpc]

No strong opinions, but seems to me like just expanding every subcommand under SUBCOMMANDS and displaying instead what <command> <that-subcommand> -h would.

[epage]

With clap, we are trying to balance ease of use, flexibility, and compile-time / binary size.

We have plans for decoupling help generation, allowing custom formatting. I have a feeling that this might be the best way forward for this. We wouldn't have a built-in "show all subcommands" flag but give you the tools to auto-generate the help output to look like you want it to.

I'm going to mark this issue as blocked on #2914 to make sure we track the requirements needed for this and I'm assuming we will close this out when #2914 is resolved.

If there are concerns about this plan, let us know!

[epage]

Been thinking on this as we've been iterating on #3174. I realized there is a good template for us to use for this, git stash -h / git stash --help.

[epage]

One idea I was toying with

Setting:

• help_includes_subcommands or help_shows_subcommands
  • trying to keep what the setting impacts first, otherwise I would have done flatten_subcommands_in_help
  • not starting with subcommand because this is set on the parent of the subcommands rather than a subcommand itself

Help output:

• USAGE includes regular usage and usage for each subcommand that is visible in short help
• Show current command's subcommand and arguments like normal
  • Even if parent has help_includes_subcommands set (this diverges from git stash <command> -h which shows git stash -h)
• After current command's arguments, for each subcommand visible in short help
  • Show a header for the subcommand
  • Show short-help arguments under the above heading (ie ignore help headings)
    • Ideally, hide all generated and global arguments
  • Do not list subcommands

Man page:

• Same as above but show long-help

Open question:

• Do we recurse?
  • If so, we should elide intermediate subcommands that only have generated arguments

[epage]

Anyone have thoughts on how to refer to / what to call the difference in subcommands between git and git stash? gits subcommands act like external subcommands though whether all of them are is an implementation detail. Since external subcommands are about the implementation, it'd be hard to reuse that name.

[lu-zero]

decoupled/coupled subcommand help maybe? Assuming you want to mention all the subcommand in the same --help for the latter and show it for --all-help for the former.

[epage]

Would love feedback on #5206