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.

[epage]

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

    /// 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(help_heading = "GLOBAL OPTIONS", global = true)]
    pub verbose: LevelFilter,

See #3855

EDIT: I guess that points back to #3822 (comment) which is a reply to you...

[Gankra]

Yeah I think I was working on migrating to the new 4.0 API and then you added a way to silence the deprecations and I decided to forget about it for now, hoping a better answer would come along.

I just did a hacked up TypedParser and some quick fixups to the markdown hack to get it working again. You can see the full snapshot diffs here, if you're curious: mozilla/cargo-vet#316

[Gankra]

Oh also: big fan of killing the version info at the start of help, it's not very helpful and also makes snapshots tests randomly churn whenever I cut a releases, which is mildly annoying (my code is also riddled with #[clap(disable_version_flag = true)] because subcommand version flags are also weird noise).

[epage]

it's not very helpful and also makes snapshots tests randomly churn

Which snapshot solution do you use? With snapbox, we support wildcards like [..], see one of clap's examples

my code is also riddled with #[clap(disable_version_flag = true)] because subcommand version flags are also weird noise

Why not just drop propagate_version = true? That will make it so you only get the version flag on the commands you explicitly apply the version attribute to.

[Gankra]

We use cargo-insta in the most naive possible way, because I do want to get notified about any and all changes to output (and insta makes it really easy to go "yep fine"). Version bumps are just the more annoying one, probably because I haven't setup cargo-release for my projects. X3

[ducaale]

The greens and yellows are gone, instead using bold, underline, and dimmed: #4117 though #3108

• Dimmed was removed from placeholders in fix(help): Don't dim placeholders #4126

Reduce the ALL CAPS: #4123

• 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

One argument for keeping ALL CAPS is that it mirrors the heading in man pages. Also, I find the underline to hurt the readability of lowercased headings (see how g and p are rendered when underlined in #4132 (comment)).

[epage]

I thought I'd record my usage experiments

Current:

git-stash

Usage:
    git-derive stash [OPTIONS]
    git-derive stash <COMMAND>

Commands:
    push
    pop
    apply
    help     Print this message or the help of the given subcommand(s)

Options:
    -m, --message <MESSAGE>
    -h, --help                 Print help information

• Takes up an extra line

Same line

git-stash

Usage: git-derive stash [OPTIONS]
       git-derive stash <COMMAND>

Commands:
    push
    pop
    apply
    help     Print this message or the help of the given subcommand(s)

Options:
    -m, --message <MESSAGE>
    -h, --help                 Print help information

• Extra indentation

git-style

git-stash

Usage: git-derive stash [OPTIONS]
   or: git-derive stash <COMMAND>

Commands:
    push
    pop
    apply
    help     Print this message or the help of the given subcommand(s)

Options:
    -m, --message <MESSAGE>
    -h, --help                 Print help information

• Extra indentation and noisier

Shell prompt

git-stash

$ git-derive stash [OPTIONS]
$ git-derive stash <COMMAND>

Commands:
    push
    pop
    apply
    help     Print this message or the help of the given subcommand(s)

Options:
    -m, --message <MESSAGE>
    -h, --help                 Print help information

• Too clever?

Overall, I'm leaning towards leaving the usage the same

[Seltyk]

The man-like output of v3 was something I really liked, so the move to a more… dare I say, Pythonic style in v4 is a letdown. But more importantly, not having colors is a total dealbreaker, for the exact same reasons as AmionSky wrote above.

[tijoer]

I saw this wall of text linked on Stackoverflow. I cannot get colors in my help pages to work, even though I have the following: #[clap(author, version, about, arg_required_else_help = true, color=ColorChoice::Always)]

How can I get colors back, as it helps to understand the information in the help page way better.

[epage]

The very first item in the issue is about that. Other styling was selected instead for clap v4's default (#4117).

The item ends with

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)

If you follow that issue, it is still open though it is my priority to work on when I am able to focus more on clap. I am trying to get some stuff done on another project atm.

[DianaNites]

The only way to get the colors back is stay on the previous clap version. This is what I do in my new and existing projects, just use clap v3.

[tijoer]

Thank you for the answer.

[NuSkooler]

I'm having a hard time following this -- I was surprised when I upgraded to 4.x and the color went away. Is the official answer to stick with v3? That seems quite off. Is an option for re-enabling the color for --help in the pipeline?

Additionally, was https://no-color.org/ considered?

[epage]

@NuSkooler

From the Issue's description

The greens and yellows are gone, instead using bold, underline, and dimmed: #4117 though #3108

towards the end is

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)

This is my top clap priority (though I have another project that is a higher priority atm). If this is a blocker for someone then, yes using clap v3 is the answer.

Additionally, was https://no-color.org/ considered?

Unsure how this is relevant. #2963 captures the motivation which in summary which led us to be more neutral in our default terminal styling. no-color would not help with that but instead helps with enabling/disabling application styling. I also hope to respect more env variables like this by default in the future.

[NuSkooler]

@epage Thanks for the quick response!

Understood on priority et al., 'tis life!

NO_COLOR is specifically designed to allow applications to default to color terminal output unless told otherwise. In general, the styling falls into this category as well as various terminals or environments (say stdout captured to file for example) become full of ANSI escape sequences with any of it enabled.

From the page:

Command-line software which adds ANSI color to its output by default should check for a NO_COLOR environment variable that, when present and not an empty string (regardless of its value), prevents the addition of ANSI color.

[dtolnay]

It's wild how opposite my point of view is to all the ones voiced above. I agree with many of the comments from #2906 -- I always hated the v3 --help color scheme, I found it gaudy and I disabled it in all of my CLIs. I love the v4 color scheme. I think it looks refined and I think Ed did a terrific job with it.

I've been wondering how much of the difference is people's legitimate personal preference vs people's terminals being differently configured to make one or the other theme look bad.

[epage]

@dtolnay thanks for providing another voice. As there is no way to make accurate internet polls on these types of things, its hard to sift through the bias of who is currently speaking.

I look forward to the experimentation and the learning that will happen when theming support is in and am curious to see if someone is able to popularize an alternative that meets the needs discussed in #2906.

[LuckyTurtleDev]

I've been wondering how much of the difference is people's legitimate personal preference vs people's terminals being differently configured to make one or the other

After seeing @dtolnay's screenshots I think the terminal / terminal-theme has an huge effect on this. At the provided screenshots the v3 theme looks more ugly and the v4 theme looks much nicer and modern.
But for example at the alacritty terminal with the default configuration it is the opposite.
I extremely like the colored output here, but found the v4 theme ugly and less easy to survey. The v3 looks much modern here.

v3	v4

Of course this is probably also only a personal preference.

I think the NO_COLOR idea would be a very good compromise. So the user can decide what they will prefer and is not bound to the choose of the developer.
So clap can use the v3 theme if NO_COLOR is not present otherwise it can use the v4 theme.
The problem with this would be that many users are not aware of this option.
So the developer with does not like v3 would probably hard code v4 again. So we need also on option to explicit enable it again, by the user. Sadly NO_COLOR=false is not supported by https://no-color.org/ and will even leads other programs to disable colors. So maybe using a different environment variable like CLAP_COLOR and only fall back to NO_COLOR, if CLAP_COLOR does not exist would be an better option. The downside of this would be that this would be a island solution, only supported by clap. Maybe suggesting to add a PREFER_COLOR to https://no-color.org/ would be an better option.

[epage]

I think the NO_COLOR idea would be a very good compromise. So the user can decide what they will prefer and is not bound to the choose of the developer.

Except NO_COLOR really means "no ansi codes" which means it would disable all formatting. Ideally, the rest of the application would also support it so it would remove everything completely. This is why I was wondering why it was relevant to this conversation.

At one point someone requested a clap-specific environment variable to allow users to control this but that is a policy that I don't think clap should take on but application authors. Users interact with the author's application, not clap, and we shouldn't bypass that relationship. This also gets into compatibility issues for the author if they switch parsers.

[NuSkooler]

Just to be clear around formatting, this is ANSI/Escape code formatting only (ie: color, underlines, bold, so on).

I don't want to be a dead horse, but I'd think the following would be the proper path, reflecting what other tools do and NO_COLOR:

• Reinstate the previous colors as the default that Clap provides unless told otherwise by the developer
• Proceed with the support of themes (this is a great enhancement!)
• Respect NO_COLOR. Users that don't want color at all set this in their terminals. Some users may for example use a --no-color CLI option as well either built in or supplied by the dev

An aside: By using the base 16 ANSI colors, users can control what "red" for example looks like in their terminal emulator; Or in other words, allows user to control what their terminal looks like without you going much at all.

[epage]

@NuSkooler while I plan to eventually have NO_COLOR support, it is not part of solution to this because

• It disables colors for error messages
• It disables colors through the rest of the application

When all a user or developer wanted is to disable color in the help. Yes, we have disable_colored_help for application authors but we are trying to pair down the number of knobs to control things.

The path forward is

1. Theming support
2. People experiment with ideas and a de facto standard arises
3. We evaluate and possibly update clap to that de facto standard with theming support being an escape hatch for people who are not happy with it.

[NuSkooler]

@epage I think that all makes sense. I guess the main thing I'm confused about is why now default to no color -- even when I as a developer told Clap to explicitly utilize it? Most if not all of the modern CLI apps that I can think of that support color at all, default to using that color.

[epage]

@NuSkooler

even when I as a developer told Clap to explicitly utilize it

Because "color" is a common stand-in word for "terminal styling"

. I guess the main thing I'm confused about is why now default to no color

• I agree with the sentiment that there were problems with the old colors.
• We want to have "safe" defaults
• In coming up with a solution, I mostly had to do it alone. Few people were willing to collaborate on this, to try understand needs outside of their own position and finding new solutions. Instead people have been very reactionary, wanting hardline solution that are non-starters (no terminal styling by default, clap v2 colors are the only way)
• I expected theming support to be released soon after. I was working on it directly after 4.0 but then (1) a higher priority came in and (2) I needed to take some family leave, severely limiting my availability for the last couple of months
• Addressing terminal styling would have gone faster if just a few of those complaining had stepped up to help despite mentioning in various places what the work is that we need to do.
• In contrast to the above, I've had a drag on my time repeatedly answering the same questions in the same threads.

Most if not all of the modern CLI apps that I can think of that support color at all, default to using that color.

I feel like there is something missing in this statement as it comes across as circular to me.

[NuSkooler]

@epage Firstly, I appreciate your willingness to debate here! I hope I'm not coming off as complaining, it's certainly not my intent. Your work is extremely appreciated. I maintain a number of OSS projects myself and know how it can be!

Understood on all notes. FWIW, I'm happy to try and help! I don't know the Clap code base well other than my external usage, but I do know terminals, ANSI, and some of the various standards, caveats, so on around them.

I may not be following the last statement about "circular":
What I'm suggesting is that modern terminal applications that themselves have color at all (some are still just plain text) provide color by default, and generally follow the NO_COLOR and/or --no-color or similar CLI options. But again, by default, they provide color in a 'default' theme even if exposing the ability for users to provide alternate themes.

And to further point out: Instead of disabling colors all together, one can use the "base" ANSI 0-16 colors, allowing the terminal emulator itself (generally exposed to the user in configuration -- you can see this in MS terminal now even!). This allows the user to define what each of the 0-16 resolve to. In other words, if you say set the "Usage" to color 4, my terminal and your terminal may look quite different based on our individual preferences. If you instead set the color to a specific value (using 256 or true color syntax), the terminal will just show that.

[epage]

@NuSkooler

Understood on all notes. FWIW, I'm happy to try and help! I don't know the Clap code base well other than my external usage, but I do know terminals, ANSI, and some of the various standards, caveats, so on around them.

Thats actually more what we need than clap help. My requirements for theming and custom user styled text is that we don't take on a whole terminal styling API in clap. The path forward

• A minimal API for defining terminal styles with no other policy. The remaining work is being tracked at https://github.com/epage/anstyle/issues/14 and Allow good/warning/error/hint color to be customized #3234 is for the clap side of things
• Leverage ANSI escape codes in Strings as the stable API for styled text. The bulk of the work is being tracked in https://github.com/epage/anstyle/issues/5 and Allow styled text in template #1433 and The header for my examples are not colored like the others #3108 are for the clap side to track the work

What I'm suggesting is that modern terminal applications that themselves have color at all (some are still just plain text) provide color by default, and generally follow the NO_COLOR and/or --no-color or similar CLI options. But again, by default, they provide color in a 'default' theme even if exposing the ability for users to provide alternate themes.

I feel like we are talking in circles on this topic which makes me think one of us is missing something about the other's responses. I've previously replied on why I think NO_COLOR, while a useful feature to support, is unrelated to this topic.

And to further point out: Instead of disabling colors all together, one can use the "base" ANSI 0-16 colors, allowing the terminal emulator itself (generally exposed to the user in configuration -- you can see this in MS terminal now even!). This allows the user to define what each of the 0-16 resolve to. In other words, if you say set the "Usage" to color 4, my terminal and your terminal may look quite different based on our individual preferences. If you instead set the color to a specific value (using 256 or true color syntax), the terminal will just show that.

Yes, I'm aware. That is one of the reasons I prefer the basic 16 / other effects over 256 and truecolor, we are more likely to be able to adapt to the users theme. However, different themes still optimize for different colors having better contrast or not. People are not going to theme their terminal specifically for clap. If we do use any colors, they likely need to have the widest theme compatibility for contrast, light and dark (I know, I'm one of those weird people who prefers light themes).

[epage]

Support for [theming] is now available as Command::styles with v4.2.3 when the unstable-styles feature is enabled.

Note: we are not guaranteeing semver compatibility on this feature until the feature flag is removed.

Please post feedback on #3234

[corneliusroemer]

Thanks for working on bringing colors back @epage! Questions of taste are always tricky.

@Gankra

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

I find the compact usage useful to quickly remember exact option names, when I have a rough idea but can't remember the exact syntax. Like in this case with --interactive which I would otherwise almost need to scroll for:

Show `git commit -h` screenshot

But I agree that when the dense options become too many, they become useless, like for snakemake (this goes one for another screen...).

Show `snakemake -h` screenshot

[epage]

To prevent usages from being overwhelming is why clap only shows positionals and commands and not options.

The downside to overriding the usage is we show that in errors rather than the "smart" usage that adapts to the users arguments.

#4191 explores some ideas for improving usage with hints like

• split a mutually exclusive arg group into its own usage
• force showing an option
• force showing the options in an arg group, with one usage per arg group

There is another issue for flattening the help for subcommands much like git stash which will show a usage per subcommand rather than a generic usage