Add an option to show aliases to --help

[poma]

Please complete the following tasks

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

Clap Version

3.0.10

Describe your use case

Currently the developer either specifies alias or visible_alias so that aliases for commands are either always shown or always hidden in the help. On one hand, the developers want users to be able to discover shortcuts for the commands from help message, but on the other hand having aliases for each command clutters the screen and makes it less readable.

Example with aliases:

    to-dec                 Convert hex value into a decimal number. [aliases: td, 2d]
    to-fix                 Convert an integer into a fixed point number. [aliases: tf, 2f]
    to-hex                 Convert an integer to hex. [aliases: th, 2h]
    to-hexdata             Normalize the input to lowercase, 0x-prefixed hex. [aliases: thd, 2hd]
    to-int256              Convert a number to a hex-encoded int256. [aliases: ti, 2i]
    to-rlp                 RLP encodes hex data, or an array of hex data
    to-uint256             Convert a number to a hex-encoded uint256. [aliases: tu, 2u]

Without:

    to-dec                 Convert hex value into a decimal number.
    to-fix                 Convert an integer into a fixed point number.
    to-hex                 Convert an integer to hex.
    to-hexdata             Normalize the input to lowercase, 0x-prefixed hex.
    to-int256              Convert a number to a hex-encoded int256.
    to-rlp                 RLP encodes hex data, or an array of hex data
    to-uint256             Convert a number to a hex-encoded uint256.

Describe the solution you'd like

Add an additional argument to --help that prints help as if all alias items were visible_alias ones. This way aliases would stay hidden by default to avoid screen clutter, but there would still be a way to discover them.

Not sure how to better implement it

Alternatives, if applicable

No response

Additional Context

No response

[epage]

An alternative solution would be for us to elide more information with -h but still show it with --help (we already specialize --help to be a verbose help output).

[epage]

Most likely any solution would not be automatic but opt-in as some CLI authors very intentionally want some aliases hidden from the user.

This means this issue is not as likely to be solved directly because we are making a concerted effort to trim down clap (#1365). Instead of offering a flag for people to tweak individual piece of behavior, we are instead limiting those to the common case and offering the less common cases the building blocks they need to get the behavior they want. In this case, the building block is likely our decoupling of help generation from formatting so users can format it as they wish while still getting a lot of the basics taken care of.

[poma]

What about -h always hiding aliases and --help showing visible_alias ones? Or maybe even hiding aliases only when no command is used and help is printed?

#2914 is very cool but will probably take a long time to implement

[epage]

Yes, I brought that up earlier (-h / --help). My main concern is either justifying the change enough to not require consensus or gathering consensus that this is justifiable.

Or maybe even hiding aliases only when no command is used and help is printed?

I'd be concerned about adding a third help mode (two help modes can already be confusing).

[poma]

Oh well I guess we'll have to settle with current state until modular help rendering is implemented. I saw an issue to make aliases grey in colored output, that would also help with readability if it's possible to implement it earlier than modular rendering.

[epage]

It is. I was going to turn my attention to how we deal with colors in clap 4.1 (currently focused on 4.0). If someone wants to take a crack at that subset of it earlier, they are welcome to it.