Do we want clap's context-aware usage strings or our custom usage strings?
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 24.1k
- Forks
- 2k
- Avg merge
- 1d 5h
- Merged PRs (30d)
- 365
Description
It looks like all utilities specify their own usage string. For example, sort:
fn get_usage() -> String {
format!(
"{0} [OPTION]... [FILE]...
Write the sorted concatenation of all FILE(s) to standard output.
Mandatory arguments for long options are mandatory for short options too.
With no FILE, or when FILE is -, read standard input.",
NAME
)
}
Quoting clap's documentation of usage():
CAUTION: Using this setting disables
claps "context-aware" usage strings. After this
setting is set, this will be the only usage string displayed to the user!
This means that when you give the wrong argument (let's say you write sort -o x -o y), you don't get a usage string about the misused flag (USAGE: sort --output <FILENAME>), but you always get our custom usage string.
I quite like the context-aware usage strings, and I wondered if we could not specify our own usage strings but let clap generate them instead in all cases. In the help output they'd look a bit different (sort [FLAGS] [OPTIONS] [--] [files]..., or sort [OPTIONS] [--] [files]... if we enable UnifiedHelpMessage).
Thoughts?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the utilities' custom get_usage implementations, using sort as the example, and read clap's usage() documentation alongside the UnifiedHelpMessage behavior. Determine how context-aware errors and help output would change; the work is done only after the project decides between the approaches and applies the chosen policy consistently.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100