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.