Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add an option to show aliases to --help #3994

Closed
2 tasks done
poma opened this issue Jul 26, 2022 · 6 comments
Closed
2 tasks done

Add an option to show aliases to --help #3994

poma opened this issue Jul 26, 2022 · 6 comments
Labels
A-help Area: documentation, including docs.rs, readme, examples, etc... C-enhancement Category: Raise on the bar on expectations S-waiting-on-design Status: Waiting on user-facing design to be resolved before implementing

Comments

@poma
Copy link

poma commented Jul 26, 2022

Please complete the following tasks

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
Copy link
Member

epage commented Jul 26, 2022

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 epage added A-help Area: documentation, including docs.rs, readme, examples, etc... S-waiting-on-design Status: Waiting on user-facing design to be resolved before implementing labels Jul 26, 2022
@epage
Copy link
Member

epage commented Jul 26, 2022

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
Copy link
Author

poma commented Jul 26, 2022

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
Copy link
Member

epage commented Jul 27, 2022

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
Copy link
Author

poma commented Jul 27, 2022

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
Copy link
Member

epage commented Jul 27, 2022

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-help Area: documentation, including docs.rs, readme, examples, etc... C-enhancement Category: Raise on the bar on expectations S-waiting-on-design Status: Waiting on user-facing design to be resolved before implementing
Projects
None yet
Development

No branches or pull requests

2 participants