Polishing `--help` output

[epage]

We are looking to polish the help as part of the v4 release since some parts of an applications help might be dependent on how clap renders things (e.g. to match clap's ALL CAPS help headings, a user might put theirs in ALL CAPS).

So far we have made the following changes:

• The greens and yellows are gone, instead using bold, underline, and dimmed: PR 4117 though some more work might be needed to enable colored help, depending on the needs
  • See PR for screenshot
  • Dimmed was removed from placeholders in fix(help): Don't dim placeholders #4126
  • Some liked the colors (example), some hated them (example)
  • Color makes it easier to scan
  • Some applications have specific branding that it clashed with (Make colored help output more compatible with an applications overall theme #2963)
  • True colors would be prettier but requires getting into terminal theme detection to make sure it plays nice and hesistant to do that at the moment
  • Users can't rollback until theming support is in (Allow good/warning/error/hint color to be customized #3234) though they can just disable the coloring with Command::disable_colored_help(true)
• Reduce the ALL CAPS: PR 4123
  • See PR for screenshot
  • ARGS and OPTIONS matched the usage and worked as non-colored headings but it feels a bit unpolished
  • I was hard pressed to find other CLIs that do this
  • All caps mirrors man pages
  • Mixed with underlining, it can be hard to see the bottom of "y", "g", etc.
  • Users can rollback to the old behavior with Command::help_template, Command:subcommand_help_heading, and Arg::help_heading
• List subcommands before args/options: PR 4125
  • See PR for screenshot
  • At the end represents where someone might put it in the usage compared to everything else but generally a user's primary focus is on the subcommand they are going to call so that is where the help's focus should be
  • Users can rollback to the old behavior with Command::help_template
• List of positional Arguments use [] for optional PR 4144
• Always show optional positional arguments in usage, rather than collapsing them PR 4151
  • Generally there will be few enough positional arguments that this shouldn't be a big deal
  • Optional flags/options can be more numerous and clog up the usage, making it impossible to deal with (e.g. git)
• Renaming SUBCOMMAND value name and Subcommand section headers to COMMAND and Command: PR 4155
  • "Subcommand" looks weird to me
  • Hard pressed to find other CLIs that do this
  • Users can rollback to the old behavior with Command::subcommand_help_heading and Command::subcommand_value_name
• Hint to the user the difference between -h and --help: PR 4159
• Remove <name> <verson> from the start of --help: PR 4160
  • It takes up precious vertical space but doesn't seem justified, especially when --version exists and when a subcommand doesn't have a version, it feels out of place (see cargo check -h)
  • Again, hard pressed to find other CLIs that do this
  • This does leave where to put authors if people specify them
  • Since all help is rendered from a template, this runs into problems when Command::about is unspecified as it leaves a blank line at the top of the help. fix(help): Always trim output #4156 resolves that
  • Users can rollback to the old behavior with Command::help_template
• Collapse usage to one line PR 4188
  • After looking at several CLIs, it seemed to fit and helps reduce length of output
  • See Polishing --help output #4132 (comment) for alternatives considered
• Reduce blank lines when overflowing short help onto next line PR 4190
• Reduce indentation from 4 to 2 to reduce the chance of wrapping PR 4192
  • flags/options already have a lot of whitespace, we probably don't need as much everywhere
  • Inspired by podman -h
  • While refactor(help): Reduce magic numbers for indentation #4161 will make it easier to do on the implementation side, I'm losing steam and don't want to go update all of those tests

Rejected

• Some CLIs put Usage before the <about> and collapse it to Usage: <usage> if its a single line (e.g. find --help)
  • Putting usage closer to the arguments seems better
  • Otherwise, the difference seems trivial without a reason to go one way or the other
• Should Arguments and Options be under a single heading by default?
  • I feel like there is a distinct enough difference in how they are used to call them out separately
  • A user can force them to be merged via Arg::help_heading

Future improvements

• Clap derive should parse markdown doc comment into normal text #2389
• Allow good/warning/error/hint color to be customized #3234
• The header for my examples are not colored like the others #3108
• Allow styled text in template #1433
• Multiple subcommand categories / help_headings #1553

Note: While I mentioning non-clap CLIs, I want to be clear that we don't just want to conform to what is out there. We should be aiming to make the defaults as polished as possible which can include taking inspiration from others.

[Gankra]

Gonna dump some comparisons/notes here and then do a summary of my thoughts once I've seen it all.

Here's a before (3.2.17, left) and after (current git tip, right) of minidump-stackwalk on powershell:

Fixes I needed to make (fairly painless with the CHANGELOG's advice, nice!):

• possible_values = [...] => value_parser([...])
• DeriveDisplayOrder => <deleted, now the default, sick!>

[epage]

Here's a before (3.2.17, left) and after (current git tip, right) of minidump-stackwalk on powershell:

Fixes I needed to make ...

For anyone else, I want to say that I only consider the changelog to be in draft form at the moment plus we'll write a migration guide like we did for clap 3.

[Gankra]

cargo-vet (this one is a bit messier because we have proper subcommands so lining things up is gonna be wonky...):

required diff

@@ -215,6 +225,18 @@ dependencies = [
PS C:\Users\ninte\dev\cargo-vet> git diff .\src\cli.rs
diff --git a/src/cli.rs b/src/cli.rs
index f19d89d..2ad2914 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -18,7 +18,6 @@ pub enum FakeCli {
 #[clap(version)]
 #[clap(bin_name = "cargo vet")]
 #[clap(args_conflicts_with_subcommands = true)]
-#[clap(global_setting(clap::AppSettings::DeriveDisplayOrder))]
 /// Supply-chain security for Rust
 ///
 /// When run without a subcommand, `cargo vet` will invoke the `check`
@@ -30,7 +29,7 @@ pub struct Cli {

     // Top-level flags
     /// Path to Cargo.toml
-    #[clap(long, name = "PATH", parse(from_os_str))]
+    #[clap(long, name = "PATH", value_parser)]
     #[clap(help_heading = "GLOBAL OPTIONS", global = true)]
     pub manifest_path: Option<PathBuf>,

@@ -48,7 +47,7 @@ pub struct Cli {
     pub no_default_features: bool,

     /// Space-separated list of features to activate
-    #[clap(long, action, require_value_delimiter = true, value_delimiter = ' ')]
+    #[clap(long, action, value_delimiter = ' ')]
     #[clap(help_heading = "GLOBAL OPTIONS", global = true)]
     pub features: Vec<String>,

@@ -73,7 +72,7 @@ pub struct Cli {
     /// How verbose logging should be (log level)
     #[clap(long, action)]
     #[clap(default_value_t = LevelFilter::WARN)]
-    #[clap(possible_values = ["off", "error", "warn", "info", "debug", "trace"])]
+    #[clap(value_parser(["off", "error", "warn", "info", "debug", "trace"]))]
     #[clap(help_heading = "GLOBAL OPTIONS", global = true)]
     pub verbose: LevelFilter,

Looking at subcommand's --help:

[epage]

@Gankra

Tip: value_parser (without a value) was only needed in clap 3.2 to opt-in to the new clap v4 behavior. In v4 it is assumed and not needed.

@@ -30,7 +29,7 @@ pub struct Cli {
     // Top-level flags
     /// Path to Cargo.toml
-    #[clap(long, name = "PATH", parse(from_os_str))]
+    #[clap(long, name = "PATH", value_parser)]
     #[clap(help_heading = "GLOBAL OPTIONS", global = true)]
     pub manifest_path: Option<PathBuf>,

[epage]

Seeing cargo-vet-vert-certify

• I think there is a bug with the positional arguments, they should probably be using []
• We collapse options because there can be so many but we should probably not collapse down to [ARGS] as that is most likely the core of what people are doing and the usage is a bit meaningless otherwise.

[epage]

Seeing --filter-graphs help, you might find #3108 useful (ie allow formatting in user provided strings). Everything in the v4 API that accepts StyledStr will allow user styling once we implement #3108. We have a placeholder type in there for now so it isn't a breaking change.

[Gankra]

So the fact that cargo-vet 0.3.0 and cargo-vet-certify 0.3.0 is now cargo-vet-vet 0.3.0 and cargo-vet-vet-certify 0.3.0 seems like a minor regression/mess for cargo-subcommands, not sure if the CHANGELOG notes something about this or if I'm using the wrong "hack" for cargo-subcommands to work right.

I definitely like that subcommands come first! I had been considering a hack to do that in the post-processed markdown version of this output (the impl if you want to see my current horrors, which are almost certainly going to be broken by 4.0 but I begrudge no one but myself for this fact).

I definitely like that DeriveDisplayOrder is the default! I am very particular about my output! In this vein I've also been hurting for a way to create extra headings for subcommand families, a la git (cargo-vet has too many subcommands because it has both plumbing and porcelain commands, and it's hard to indicate that some commands are "core functionality, use these every day" and these others are "utilities that are good to know about but you'll probably never need"):

I'm a bit sad to lose the splash of color, I find that it helps me quickly scan the verbose help output and breaks up the monotony. That said my opinion isn't strong enough for me to kick up a fuss.

ARGS vs Arguments I could take or leave, don't really care either way. (And I've never really understood the motivation of distinguishing arguments from options...)

Looking at these screenshots I am reminded that a higher-impact thing clap could be doing with my help messages is doing some cleanup of artifacts in the text that exist for rustdoc's sake (since this is pulling from docstrings which need to be valid markdown). Obviously "add a fuckin' markdown parser to clap" is a big ask, but it's unfortunate (and iirc I had to do some very careful work to not have the bullets in --filter-graph get completely messed up).

[Gankra]

We collapse options because there can be so many but we should probably not collapse down to [ARGS] as that is most likely the core of what people are doing and the usage is a bit meaningless otherwise.

I'm increasingly of the opinion that usage strings basically suck at the best of times, and actually am already hardcoding them away in rust-minidump (3 years ago or whatever clap was deriving absolute nonsense so I just burnt it to the ground).

Like I don't know how anyone ever looks at something like this and goes "yes this helps me" lol

[Gankra]

Oh wait oh god I in fact did not do the migration correct, my cli tests now all die with

---- tests::violations::mock_simple_violation_cur_exemptions stdout ----
thread 'tests::violations::mock_simple_violation_cur_exemptions' panicked at 'Mismatch between definition and access of `verbose`. Could not downcast to tracing_core::metadata::LevelFilter, need to downcast to alloc::string::String
', src\cli.rs:77:18

Why is --verbose of all things the flag that keeps breaking between clap versions x3

[epage]

So the fact that cargo-vet 0.3.0 and cargo-vet-certify 0.3.0 is now cargo-vet-vet 0.3.0 and cargo-vet-vet-certify 0.3.0 seems like a minor regression/mess for cargo-subcommands, not sure if the CHANGELOG notes something about this or if I'm using the wrong "hack" for cargo-subcommands to work right.

I might need to play with that to see whats going on. We switched up how we render the name to fix #992 and I'm unsure if your code is needing a change or if this is a bug.

In this vein I've also been hurting for a way to create extra headings for subcommand families,

#1553 which I'm hoping to fit into v4 but it could probably be made in any 4.x release once I get the derive macros done for #1807

I'm a bit sad to lose the splash of color, I find that it helps me quickly scan the verbose help output and breaks up the monotony. That said my opinion isn't strong enough for me to kick up a fuss.

I agree that color helps.

The concerns with color

• Do the colors picked have enough of a polished look
• Do the colors work well with terminal's theme (e.g. I'm trying to avoid true colors due to extra complexity of working with the theme)
• Do the colors work well with application's theme (Make colored help output more compatible with an applications overall theme #2963)

We do plan to allow people to customize colors during the 4.x release, see #3234

(And I've never really understood the motivation of distinguishing arguments from options...)

Hey, at least we stopped distinguishing between flags and options!

I'll have to give this some thought.

Obviously "add a fuckin' markdown parser to clap" is a big ask, but it's unfortunate (and iirc I had to do some very careful work to not have the bullets in --filter-graph get completely messed up).

Its a big ask but we need to at least make it possible, even if we make it either opt-in or opt-out: #2389 (which builds on top of the other issue I linked to for --filter-graph)

Like I don't know how anyone ever looks at something like this and goes "yes this helps me" lol

Yes, this is why I still think we should collapse to [OPTIONS] as they are more plentiful and can easily overwhelm the user. [ARGS] tend to not do that so much.