The help message offset is inconsistent

[epage]

Issue by marmistrz
Tuesday Jul 25, 2017 at 10:40 GMT
Originally opened as clap-rs/clap#1013

---

Rust Version

1.19.0

Affected Version of clap

2.25.1

Issue description

Take this Rust project: marmistrz/randmockery@3fa575f

(I specify the commit because the app may be developed further). When launching randmockery --help I get

randmockery 0.1.0
Marcin Mielniczuk <mail>
Proof-of-concept that we can mock randomness

USAGE:
    randmockery [OPTIONS] <command>...

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -l <library>...        Adds a library to be injected

ARGS:
    <command>...    The command to be executed

I'd expect all the help messages to be aligned to each other:

FLAGS:
    -h, --help             Prints help information
    -V, --version          Prints version information

OPTIONS:
    -l <library>...        Adds a library to be injected

ARGS:
    <command>...           The command to be executed

[epage]

Comment by kbknapp
Wednesday Oct 04, 2017 at 02:48 GMT

---

The alignment is per section (i.e. ARGS, FLAGS, etc.). In small programs like the example, I agree it looks better aligned as a single unit, but in large programs this actually looks worse (subjective opinion I know).

I'm going to close this as just by design. But I'm open to discussing the issue if there is an argument to be made.

[epage]

Comment by marmistrz
Wednesday Oct 04, 2017 at 08:26 GMT

---

Since it's subjective, what about making it configurable?

[epage]

Comment by kbknapp
Tuesday Oct 24, 2017 at 01:54 GMT

---

@marmistrz apologies I didn't get the ping that a comment was made!

In general I'm ok with making things configurable, and I'm not against adding a setting does exactly this. I'll re-open the issue but can't promise when it'll be done due to my work schedule lately. I'd be happy to help someone figure this out if they'd like to work on a fairly easy to implement issue.

[epage]

Comment by pksunkara
Wednesday Oct 27, 2021 at 09:24 GMT

---

@epage What do you think of this?

[epage]

Comment by epage
Wednesday Oct 27, 2021 at 18:05 GMT

---

My general stance is to push back against configuration and prefer making a decision one way or the other :), depending on how hard the workarounds are, the number of people affected, etc.

For those unaware, my motivations for low configuration are:

• Keep the API more focused. Its hard to find relevant parts of the API because the surface area is so large.
• Keep the number of supported cases down (not number of flags but their permutations) since we've seen a lot of problems crop up from unexpected interactions
• Keep the code base smaller / more nimble

We might be able to re-frame this to have it and keep low configuration, like with clap-rs/clap#2913 or clap-rs/clap#2914. We could keep the mainline clap behavior less configurable but allow people in the more corner cases to drop down to lower level APIs that offer them more flexibility to do what they want We can then keep on an eye on these (especially with crates.io's reverse dependencies) and use that as feedback for where we should take clap.

As for timelines, I wouldn't think this is a priority for 3.1. Putting it in my buckets (Focus Area, Planned, Someday), the prior conversation makes this seem like a Planned but my suggestion above makes this sound like a Someday or that it is Planned but blocked on #2913 and would then be targeted as a change to the lower level help generator only.

[epage]

Comment by pksunkara
Wednesday Oct 27, 2021 at 20:32 GMT

---

My general stance is to push back against configuration and prefer making a decision one way or the other :), depending on how hard the workarounds are, the number of people affected, etc.

I guess that's where we differ. I envision clap (and clap had always been) to allow all kinds of configuration so that users can choose their own preferences.

Our job as maintainers is to grow the codebase to make sure those configuration options are not workarounds but rather modular and the number of people affected are less because they can opt-out.

In fact, I would wager that the reason clap is so popular is because of it's flexibility.