Help text for -h is too long for two-column short help

[bgilbert]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Rust Version

rustc 1.64.0 (Fedora 1.64.0-1.fc36)

Clap Version

4.0.17

Minimal reproducible code

use clap::Parser;

#[derive(Parser)]
pub struct Cmd {
    /// Process an integer
    ///
    /// Convert an integer into a more pleasing format.
    #[clap(long, value_name = "INTEGER")]
    process_int: Option<i64>,

    /// Process a string
    ///
    /// Convert an integer into a more pleasing format.
    #[clap(long, value_name = "STRING")]
    process_string: Option<String>,
}

fn main() {
    Cmd::parse();
}

Cargo.toml:

[package]
name = "clap-help"
version = "0.0.0"
edition = "2021"

[dependencies]
clap = { version = "4", features = ["derive", "wrap_help"] }

Steps to reproduce the bug with the above code

cargo run -- -h

Actual Behaviour

On an 80-column terminal, short help uses multiple lines per option:

Usage: clap-help [OPTIONS]

Options:
      --process-int <INTEGER>
          Process an integer
      --process-string <STRING>
          Process a string
  -h, --help
          Print help information (use `--help` for more detail)

Expected Behaviour

Short help uses two-column format:

Usage: clap-help [OPTIONS]

Options:
      --process-int <INTEGER>    Process an integer
      --process-string <STRING>  Process a string
  -h, --help                     Print help ('--help' for more)

Additional Context

Applications may want to constrain their short help to use the two-column format so the -h output is as compact as possible. They might do this by optimizing short help texts to fit within the right-hand column on 80-character terminals, and then providing long help texts with more info. However, #4159 made the short help text for -h/--help much longer when the short and long help are different, forcing short help to wrap to the multiple-line format if medium-sized option/value names are used.

Proposed fix in #4408.

Debug Output

No response

[epage]

Related

• -h short help switches from single to multiple lines when adding a value_name entry #3300
• Help output format in Clap 3.x #3663

[epage]

Framing this in a different way, what do you see is the appropriate reserved size for the flag column and the help column? Without having a guiding number, it is hard to make decisions on what are appropriate trade offs.

[bgilbert]

I think it makes sense to leave those tradeoffs to the application as much as possible. In my application we have one subcommand with really tight spacing constraints, where we've sometimes had to choose between shortening a value name or rewording a help text to keep to 80 columns while retaining as much clarity as possible. (And we've had to carefully choose long option names as well.) Having the flexibility to trade one column against the other is helpful here, and the shorter the -h help text is, the more room it leaves for the application to make those choices.

[bgilbert]

Anything I can do to help unblock this? The fix for this regression is just a string change, which should be ready to go in #4408.

[epage]

imo "as short as possible" and contorting the text to do so, is not acceptable. We should have a suggested length so we can better discuss acceptable trade offs in what we do with the clarity of the text.

[bgilbert]

In my experience, short help text always has to be contorted for compactness, similar to fitting a meaningful Git commit summary into 50 characters. In the application I mentioned, using clap 4, the tightest constraint is a subcommand that needs 27 characters for long options and (abbreviated) value names. Subtracting 8 characters for short options and padding, that leaves 45 characters for short help.

It's maybe worth noting that the reason we're so aggressive about optimizing short help is that if any one option exceeds the character limit, clap sparsifies the entire help section, rather than merely wrapping that message onto a second line within its column. We even ended up adding a CI check for it. That's out of scope for this issue, of course.

#4405 currently uses 30 characters for -h short help, but if you have some slightly longer text that you'd prefer, I'd be happy to update the PR. clap 4 currently uses 53 characters, leaving 19 characters for long options and value names (enough for e.g. --run-thing <thing>), which seems pretty limited. This is actually longer than the --help long help, which only uses 47 characters. For comparison, clap 3 used 15.

[epage]

In my experience, short help text always has to be contorted for compactness, similar to fitting a meaningful Git commit summary into 50 characters. In the application I mentioned, using clap 4, the tightest constraint is a subcommand that needs 27 characters for long options and (abbreviated) value names. Subtracting 8 characters for short options and padding, that leaves 45 characters for short help.

I suspect some additional constraints are at play as I see ripgrep and cargo seem to be fairly generous with their short helps. Some additional context would help.

It's maybe worth noting that the reason we're so aggressive about optimizing short help is that if any one option exceeds the character limit, clap sparsifies the entire help section, rather than merely wrapping that message onto a second line within its column. We even ended up adding a CI check for it. That's out of scope for this issue, of course.

That might be the more important conversation to have though (over in #3300 most likely)

[bgilbert]

cargo and ripgrep both allow their help lines to overflow the terminal onto a second line, sometimes breaking in the middle of a word. That's functional but doesn't seem especially readable.

Re context, this is a low-level tool (an OS installer) which is often run from a Linux virtual console (not a graphical session). It has many options, and most users probably don't run it often enough to memorize its CLI. So I'd expect the short help to be consulted fairly often, and would like it to be nicely formatted and not to produce many screenfuls of text. These seem like reasonable goals for many programs though.

Re line wrapping, I'll comment over in #3300.