Quest issue: how can we improve --help output

[withoutboats]

This is a tracking issue for figuring out how to make the output cargo $subcommand --help more useable. We discussed this at the cargo team meeting today and a few ideas we had:

• Make unstable options only visible if you call it as --help -Z unstable-options. Hide unstable options from --help without -Z unstable-options #6102
• Make some lesser used flags only visible if you call it as --help --verbose
• Organize flags into categories so that they are grouped together in the help output.

Other ideas appreciated! Also appreciated would be any PRs to make the wording of help output clearer or more concise.

[ehuss]

clap currently supports the ability to have a short/verbose help by using -h or --help. See ripgrep as an example that makes extensive use of this. Personally I don't find that very obvious (I usually assume those two flags are the same), but it could help. Thoughts?

clap 3.0 has some more options for controlling the help display. help_heading can be used to aggregate related options (which would make the display longer, but would help separate unrelated options). There's also display_order which exists in 2.x.

I've been wanting to write more extensive documentation for each command, but I'm uncertain where it should live. I fear putting it in the --help text would contribute to making it overwhelming. However, putting it in the reference manual may make it hard to discover. This documentation would discuss more about what the command actually does, what the default target/profile selections are, usage examples, etc.

[alexcrichton]

I'm personally fond of -h --verbose vs -h like what rustc does, which meakse -h pretty usable by default and then we just dump everything else in --verbose. I would also be wary of differentiating between -h and --help, I would also expect them to be the same!

For more long-form documentation though I think using HTML docs is probably better, and I think we could also place urls to those documentation as well perhaps?

[ehuss]

-h --verbose vs -h

It's a bit tricky to do that in clap, but it should be possible. I can put together a prototype to see what it looks like.

[Nemo157]

For more long-form documentation though I think using HTML docs is probably better, and I think we could also place urls to those documentation as well perhaps?

Could also include those files with the cargo install and support something like --help --open to open them in a browser.

[alexcrichton]

Seems plausible to me!

[ehuss]

@joshtriplett Here is the option grouping support in clap v3: https://github.com/clap-rs/clap/blob/eaa0700e7ed76f37d245a6878deb3b8e81754d6c/src/build/app/mod.rs#L645-L651 and what it looks like: https://github.com/clap-rs/clap/blob/eaa0700e7ed76f37d245a6878deb3b8e81754d6c/tests/help.rs#L1395-L1416

It's not clear to me what's going on with clap 3. It looks like there's a lot of good stuff, but there hasn't been much progress recently.

I looked at implementing -h --verbose, but I hit a roadblock (clap-rs/clap#1350), and I don't think it is possible at this time. We could hack in something (look at the args before clap parsing, and just print a hand-written document).

[pickfire]

I believe we should bold the b in build for short alias for cargo subcommand and other subcommands to aid command discovery. Before I saw https://cheats.rs/#cargo, I am not aware of cargo b. (same goes for t and r and c).

[pksunkara]

If you specify alias for the subcommand, the help message should automatically show you the alias. It will even work with InferSubcommands turned on. We don't need to do the bold proposed above.

[pickfire]

@pksunkara It removes the alias in the command, I don't know what is the reason

cargo/src/bin/cargo/commands/build.rs

Line 8 in 805462e

// .alias("b")

But it have https://github.com/rust-lang/cargo/blob/master/src/bin/cargo/main.rs#L50-L71 instead.

[epage]

As an update on this issue, clap 3 is out with help heading support. It should be relatively easy to jump start cargo with this because the man pages are already organized into sections.

As for brief vs verbose help, I don't think a separate flag is needed.

• clap behavior
  • -h: brief help
  • --help: verbose help (if defined, otherwise brief help)
  • help <cmd>: verbose help
• git
  • -h: short help
  • --help: man page (verbose help)
  • help <cmd>: man page (verbose help)
• cargo
  • -h: brief help
  • --help: brief help
  • help <cmd>: man page (verbose help)

There already exists a pattern that -h is brief and --help / help are verbose. We can double down on this by using clap's short vs long specialization to make -h briefer, like Arg::hide_short_help or to make --help more verbose (like Arg_long_help).

[weihanglo]

Several people from local communities report that Cargo doesn't have a good command line help text, but it turns out that they don't even know the existence of cargo help <cmd>. There are also some issues out there were resolved when we pointed out cargo help <cmd>. I wonder if we could make --help more verbose or output the same man pages as cargo help does.

[epage]

If cargo wants to go the git route of --help showing man pages, clap currently does not have full support for that.

A CLI can create separate -h with ArgAction:Help and --help with ArgAction::SetTrue. How well --help works depends on the other possible flags. For example, required or conflicting flags will need to be resolved before --help will show up.

When clap maintainers created ArgAction , we intended to open the the API for custom actions but we needed time to see how actions worked and we've also had other priorities (atm its colors). We have several action-related issues but none that directly have this request. Instead, the details are in our brainstorming thread

[pickfire]

IIRC I mentioned this in another issue. One possible downside is the lack of global man pages, which breaks fish alt+h and also breaks if user tried man -k or man cargo, so it is harder to discover that the man pages is accessible through rustup man cargo which is pretty much non-standard, although there is a reason for this given that different toolchains may be used at different place.

The -h is a short version, --help is a longer version, rustup man is the longest version, but I bet most people can't even find --help, and rustup man feels like an easter egg that probably most people won't even find out.

For me, I rather have the default stable toolchain as the global man page and then in the man page mention a big To browse man page for current toolchain use rustup man warning, like nix manual warning.

[epage]

help_heading was added in #11905

[epage]

cargo add is an example of a command using clap's short vs long help. With the newer versions of clap, you get hints about this

$ cargo add -h
...
-h, --help                 Print help (see more with '--help')
...
$ cargo add --help
...
  -h, --help
          Print help (see a summary with '-h')
...

Then with #12578, we've added styling to highlight the suggestion to run cargo help <cmd>.

Between these and previous changes, I'm not seeing much more we can/should do for this and would recommend we track further improvements in more specific, individual issues.