Short/long help distinction seems unclear to the end-user

[epage]

Issue by 8573
Saturday Jul 29, 2017 at 08:31 GMT
Originally opened as clap-rs/clap#1015

---

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

This default help message, produced by clap version 2.25.1, seems to
me to imply that -h and --help do the same thing, when they don't
necessarily. For Args defined with both help and long_help,
--help may provide much more information than -h, but as far as I
can tell there is nothing to make the end-user aware of this, which
seems problematic to me.

[epage]

Comment by kbknapp
Saturday Jul 29, 2017 at 19:35 GMT

---

True, but then again they might do the same thing. Programs that opt in to differences (via Arg::long_help and friends) can also change the default help message to reflect those differences, such as how ripgrep does it.

I do believe this should be marked as a documentation issue.

[epage]

Comment by 8573
Saturday Jul 29, 2017 at 22:14 GMT

---

True, but then again they might do the same thing. Programs that
opt in to differences (via Arg::long_help and friends) can also
change the default help message to reflect those differences, such as how
ripgrep
does it.

Oh huh, I'd never noticed that in ripgrep; thanks for the tip.

I do believe this should be marked as a documentation issue.

Okay.

[epage]

Comment by martinvonz
Saturday Aug 28, 2021 at 20:36 GMT

---

Is it reasonable for clap to split up -h and --help into two arguments, so they appear on two lines in the help text?

I think much of the problem is that they're presented as -h, --help, which made at least me (as a user) think that they're just aliases. I'm a little worried that, even if I (as a developer) add a custom help message with App::help_message() to clarify that the two flags are different, my users might make not even read that because they see -h, --help and assume they're aliases without reading the description.