Is there any way to make argument help text from multiple different help headings aligned?

[ClementTsang]

I'm currently using .next_help_heading() to create custom help headings to better group together relevant arguments - however, one thing I've noticed is that this makes the argument help text misaligned. For example:

Temperature Options:
  -c, --celsius     Use Celsius as the temperature unit.
  -f, --fahrenheit  Use Fahrenheit as the temperature unit.
  -k, --kelvin      Use Kelvin as the temperature unit.

CPU Options:
  -a, --hide_avg_cpu  Hides the average CPU usage.

Is there any way of forcing them all to be aligned? If not, I can open an issue if that seems like a reasonable behaviour to have.

[epage]

At this time, no.

I feel like this has come up before but I'm not seeing it. iirc the main concerns are (1) one group being unusually long, negatively impacting others and (2) our trying to carefully balance the costs/benefits of extra configuration

I suspect this is less of an issue for larger groups. To test that out, I ran cargo check and then aligned the groups.

$ cargo check
Check a local package and all of its dependencies for errors

Usage: cargo check [OPTIONS]

Options:
      --ignore-rust-version     Ignore `rust-version` specification in packages
      --future-incompat-report  Outputs a future incompatibility report at the end of the build
      --message-format <FMT>    Error format
  -q, --quiet                   Do not print cargo log messages
  -v, --verbose...              Use verbose output (-vv very verbose/build.rs output)
      --color <WHEN>            Coloring: auto, always, never
      --config <KEY=VALUE>      Override a configuration value
  -Z <FLAG>                     Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
  -h, --help                    Print help

Package Selection:
  -p, --package [<SPEC>]  Package(s) to check
      --workspace         Check all packages in the workspace
      --exclude <SPEC>    Exclude packages from the check
      --all               Alias for --workspace (deprecated)

Target Selection:
      --lib               Check only this package's library
      --bins              Check all binaries
      --bin [<NAME>]      Check only the specified binary
      --examples          Check all examples
      --example [<NAME>]  Check only the specified example
      --tests             Check all test targets
      --test [<NAME>]     Check only the specified test target
      --benches           Check all bench targets
      --bench [<NAME>]    Check only the specified bench target
      --all-targets       Check all targets

Feature Selection:
  -F, --features <FEATURES>  Space or comma separated list of features to activate
      --all-features         Activate all available features
      --no-default-features  Do not activate the `default` feature

Compilation Options:
  -j, --jobs <N>                Number of parallel jobs, defaults to # of CPUs.
      --keep-going              Do not abort the build as soon as there is an error
  -r, --release                 Check artifacts in release mode, with optimizations
      --profile <PROFILE-NAME>  Check artifacts with the specified profile
      --target [<TRIPLE>]       Check for the target triple
      --target-dir <DIRECTORY>  Directory for all generated artifacts
      --unit-graph              Output build graph in JSON (unstable)
      --timings[=<FMTS>]        Timing output formats (unstable) (comma separated): html, json

Manifest Options:
      --manifest-path <PATH>  Path to Cargo.toml
      --frozen                Require Cargo.lock and cache are up to date
      --locked                Require Cargo.lock is up to date
      --offline               Run without accessing the network

Run `cargo help check` for more detailed information.

$ cargo check
Check a local package and all of its dependencies for errors

Usage: cargo check [OPTIONS]

Options:
      --ignore-rust-version     Ignore `rust-version` specification in packages
      --future-incompat-report  Outputs a future incompatibility report at the end of the build
      --message-format <FMT>    Error format
  -q, --quiet                   Do not print cargo log messages
  -v, --verbose...              Use verbose output (-vv very verbose/build.rs output)
      --color <WHEN>            Coloring: auto, always, never
      --config <KEY=VALUE>      Override a configuration value
  -Z <FLAG>                     Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
  -h, --help                    Print help

Package Selection:
  -p, --package [<SPEC>]        Package(s) to check
      --workspace               Check all packages in the workspace
      --exclude <SPEC>          Exclude packages from the check
      --all                     Alias for --workspace (deprecated)

Target Selection:
      --lib                     Check only this package's library
      --bins                    Check all binaries
      --bin [<NAME>]            Check only the specified binary
      --examples                Check all examples
      --example [<NAME>]        Check only the specified example
      --tests                   Check all test targets
      --test [<NAME>]           Check only the specified test target
      --benches                 Check all bench targets
      --bench [<NAME>]          Check only the specified bench target
      --all-targets             Check all targets

Feature Selection:
  -F, --features <FEATURES>     Space or comma separated list of features to activate
      --all-features            Activate all available features
      --no-default-features     Do not activate the `default` feature

Compilation Options:
  -j, --jobs <N>                Number of parallel jobs, defaults to # of CPUs.
      --keep-going              Do not abort the build as soon as there is an error
  -r, --release                 Check artifacts in release mode, with optimizations
      --profile <PROFILE-NAME>  Check artifacts with the specified profile
      --target [<TRIPLE>]       Check for the target triple
      --target-dir <DIRECTORY>  Directory for all generated artifacts
      --unit-graph              Output build graph in JSON (unstable)
      --timings[=<FMTS>]        Timing output formats (unstable) (comma separated): html, json

Manifest Options:
      --manifest-path <PATH>    Path to Cargo.toml
      --frozen                  Require Cargo.lock and cache are up to date
      --locked                  Require Cargo.lock is up to date
      --offline                 Run without accessing the network

Run `cargo help check` for more detailed information.

Interesting that in the browser the lack of alignment stands out more to me than on the command-line. Is it the colors that make it work better for me? Unsure.

[epage]

If we consider changing this, we should survey the popular user-facing bins that use help_heading (e.g. cargo) to get a sense of positive / negative impact.

[ClementTsang]

Yep, fair enough. I guess for me I noticed it more since I went from having just everything lumped under one group to multiple smaller groups.

[ClementTsang]

Taking a second look, it also looks a bit jarring for me for some options in a situation like this:

GPU Options:
      --enable_gpu  Enable collecting and displaying GPU usage.

Style Options:
      --color <COLOR SCHEME>  Use a color scheme, use --help for info on the colors. [possible
                              values: default, default-light, gruvbox, gruvbox-light, nord,
                              nord-light]

The first entry is aligned very far left since it's the only entry, but this causes it to look really strange with the second entry since that one has a short argument name but it takes a value.

For what its worth I think (if possible) a change to "fix" this would be best if it was an optional config and not necessarily changing the default look for everyone... though I'm not sure how easy that is.

[epage]

In general, we try to take the approach of finding universal defaults and only fallback to a config when there is a strong justification for it.