fix(help): Shorten --help short help to shorten short help
#4408
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
epage
reviewed
Oct 20, 2022
epage
reviewed
Oct 20, 2022
epage
reviewed
Oct 20, 2022
2 tasks
|
Updated for comments! |
Use single quotes around the strings `-h` and `--help` in help output. This is more consistent and improves readability a bit.
Applications may want to constrain their short help to use the two-column format so the -h output is as compact as possible. They might do this by optimizing short help texts to fit within the right-hand column on 80-character terminals, and then providing long help texts with more info. However, c1c269b made the short help text for -h/--help much longer when the short and long help are different, forcing short help to wrap to the multiple-line format if medium-sized option/value names are used. Reword the short help for this case to be as compact as possible. The net length is still a few characters longer than in clap 3, but this still substantially increases the maximum width of the left column while continuing to document the difference between -h and --help. Fixes #4409
|
And CI is now passing. |
epage
added a commit
to epage/clap
that referenced
this pull request
Jan 3, 2023
This is an intermediate solution for clap-rs#4408. As there were no agreeed upon goals, I went with what I felt read well and that I saw commonly used on non-clap commands.
epage
added a commit
to epage/clap
that referenced
this pull request
Jan 3, 2023
This is an intermediate solution for clap-rs#4408. As there were no agreeed upon goals, I went with what I felt read well and that I saw commonly used on non-clap commands. I originally favored `Print this help` but realied that doesn't read correctly in completions. Fixes clap-rs#4409
epage
added a commit
to epage/clap
that referenced
this pull request
Jan 3, 2023
This is an intermediate solution for clap-rs#4408. As there were no agreeed upon goals, I went with what I felt read well and that I saw commonly used on non-clap commands. - "information" isn't really a necessary word. - I originally favored `Print this help` but realied that doesn't read correctly in completions. - Besides being shorter, the reason for the flipped short/long hint is it gives people the context they need for scanning, emphasizing "summary" and "more". Fixes clap-rs#4409
|
#4601 superseded this, |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Applications may want to constrain their short help to use the two-column format so the
-houtput is as compact as possible. They might do this by optimizing short help texts to fit within the right-hand column on 80-character terminals, and then providing long help texts with more info. However, #4159 made the short help text for-h/--helpmuch longer when the short and long help are different, forcing short help to wrap to the multiple-line format if medium-sized option/value names are used.Reword the short help for this case to be as compact as possible. The net length is still a few characters longer than in clap 3, but this still substantially increases the maximum width of the left column while continuing to document the difference between
-hand--help.Also use single quotes around the strings
-hand--helpin help output. This is more consistent and improves readability a bit.Fixes #4409.