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

[8573]

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.

[kbknapp]

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.

[8573]

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.

[martinvonz]

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.

[AndreKR]

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

Yes, they should absolutely be on separate lines if they do different things. The distinction between short and long help might make sense but putting -h, --help and expecting that users realize that they are different does not.

[epage]

For those that only want one or the other, #3405 might be a way of forcing it by having HelpShort, HelpLong, and HelpAuto actions.

[epage]

Thought it was interesting to see how some tools handle this

$ rg -h 
...
Use -h for short descriptions and --help for more details.
...

$ rg --help
...
Use -h for short descriptions and --help for more details.
...

$ bat -h
...
Note: `bat -h` prints a short and concise overview while `bat --help` gives all details.

$ bat --help
...
Note: `bat -h` prints a short and concise overview while `bat --help` gives all details.

What if we changed the help description for -h / --help

.help("Print this help message.  Use `--help` for more detail")
.long_help("Print this help message..  Use `-h` for a summary")

As kbknapp said earlier in this thread

True, but then again they might do the same thing

Since then

• The derive has become the go-to way of configuring clap, making it more natural (or accidental) to provide long help
• PossibleValue now has help which, if specified, will cause long help to be used

I'm thinking that putting these hints in the description for help would be good enough at this point in time to resolve this. cargo is a popular counter example that doesn't use long help. I wonder if it should make --help go to the man page like the help subcommand does though, like git.

[epage]

We could also auto-detect if long help is used. Unsure if we want to pay that runtime price though.

[gasche]

I hit this issue when using jj: I was reading doc using -h, it was missing the information I needed, and I wasted time because I did not think of using --help which I assumed was doing the exact same thing.

I am used to CLI interface conventions where the long and short names of an option do the same thing. It would never occur to me that -h and --help, if they both show help, would show different amount of help.

Personally I think that if two options do different things, they should have different short and long names. For example, one could have -h / --help on one hand and -sh / --short-help or -hs / --help-summary on the other hand.

[gasche]

(Or maybe -h / --help for short help and --doc for "documentation" (long help).)

[epage]

@gasche does jjs help output for --help say to use --help for more information?

I am used to CLI interface conventions where the long and short names of an option do the same thing. It would never occur to me that -h and --help, if they both show help, would show different amount of help.

I found it odd at first as well but it isn't unique to clap. git stash -h will show brief information and git stash --help will show the man page.

We are unlikely to remove support for it at this point due to compatibility within the applications that use it. We have made it configurable in 4.3.14, so applications can choose to switch to something else. We can explore changing the defaults though. However, the case for it would likely need to be strong due to the people relying on the current behavior.

The current convention is entrenched enough that we are unlikely to change i