Skip to content

Commit

Permalink
fix(help): Don't rely on ALL CAPS for headers
Browse files Browse the repository at this point in the history 
I see them fulfilling two roles
- A form of bolding
- As a callback to their placeholder in usage

However, it is a bit of an unpolished look and no other CLI seems to do
it.  This looks a bit more proefessional.  We have colored help for
formatting and I think the sections relation to usage will be clear
enough.
  • Loading branch information
@epage
epage committed Aug 26, 2022
1 parent 1682649 commit 6c29148
Show file tree
Hide file tree
Showing 84 changed files with 674 additions and 665 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Expand Up @@ -83,6 +83,7 @@ MSRV is now 1.60.0
- *(help)* Use `Command::display_name` in the help title rather than `Command::bin_name`
- *(help)* Show when a flag is `ArgAction::Count` by adding an `...`
- *(help)* Use a more neutral palette for coloring
- *(help)* Don't rely on ALL CAPS for help headers
- *(version)* Use `Command::display_name` rather than `Command::bin_name`
- *(parser)* Assert on unknown args when using external subcommands (#3703)
- *(parser)* Always fill in `""` argument for external subcommands (#3263)
Expand Down
10 changes: 5 additions & 5 deletions examples/cargo-example-derive.md
View file
Expand Up @@ -8,24 +8,24 @@ The help looks like:
$ cargo-example-derive --help
cargo

USAGE:
Usage:
cargo <SUBCOMMAND>

OPTIONS:
Options:
-h, --help Print help information

SUBCOMMANDS:
Subcommands:
example-derive A simple to use, efficient, and full-featured Command Line Argument Parser
help Print this message or the help of the given subcommand(s)

$ cargo-example-derive example-derive --help
cargo-example-derive [..]
A simple to use, efficient, and full-featured Command Line Argument Parser

USAGE:
Usage:
cargo example-derive [OPTIONS]

OPTIONS:
Options:
--manifest-path <MANIFEST_PATH>
-h, --help Print help information
-V, --version Print version information
Expand Down
10 changes: 5 additions & 5 deletions examples/cargo-example.md
View file
Expand Up @@ -8,24 +8,24 @@ The help looks like:
$ cargo-example --help
cargo

USAGE:
Usage:
cargo <SUBCOMMAND>

OPTIONS:
Options:
-h, --help Print help information

SUBCOMMANDS:
Subcommands:
example A simple to use, efficient, and full-featured Command Line Argument Parser
help Print this message or the help of the given subcommand(s)

$ cargo-example example --help
cargo-example [..]
A simple to use, efficient, and full-featured Command Line Argument Parser

USAGE:
Usage:
cargo example [OPTIONS]

OPTIONS:
Options:
--manifest-path <PATH>
-h, --help Print help information
-V, --version Print version information
Expand Down
6 changes: 3 additions & 3 deletions examples/demo.md
View file
Expand Up @@ -3,10 +3,10 @@ $ demo --help
clap [..]
A simple to use, efficient, and full-featured Command Line Argument Parser

USAGE:
demo[EXE] [OPTIONS] --name <NAME>
Usage:
demo [OPTIONS] --name <NAME>

OPTIONS:
Options:
-n, --name <NAME> Name of the person to greet
-c, --count <COUNT> Number of times to greet [default: 1]
-h, --help Print help information
Expand Down
12 changes: 6 additions & 6 deletions examples/derive_ref/custom-bool.md
View file
Expand Up @@ -7,13 +7,13 @@ $ custom-bool --help
clap [..]
A simple to use, efficient, and full-featured Command Line Argument Parser

USAGE:
custom-bool[EXE] [OPTIONS] --foo <FOO> <BOOM>
Usage:
custom-bool [OPTIONS] --foo <FOO> <BOOM>

ARGS:
Arguments:
<BOOM> [possible values: true, false]

OPTIONS:
Options:
--foo <FOO> [possible values: true, false]
--bar <BAR> [default: false]
-h, --help Print help information
Expand All @@ -25,8 +25,8 @@ error: The following required arguments were not provided:
--foo <FOO>
<BOOM>

USAGE:
custom-bool[EXE] [OPTIONS] --foo <FOO> <BOOM>
Usage:
custom-bool [OPTIONS] --foo <FOO> <BOOM>

For more information try --help

Expand Down
32 changes: 16 additions & 16 deletions examples/derive_ref/interop_tests.md
View file
Expand Up @@ -39,8 +39,8 @@ error: Found argument '--unknown' which wasn't expected, or isn't valid in this

If you tried to supply `--unknown` as a value rather than a flag, use `-- --unknown`

USAGE:
interop_augment_args[EXE] [OPTIONS]
Usage:
interop_augment_args [OPTIONS]

For more information try --help

Expand Down Expand Up @@ -77,8 +77,8 @@ error: Found argument '--unknown' which wasn't expected, or isn't valid in this

If you tried to supply `--unknown` as a value rather than a flag, use `-- --unknown`

USAGE:
interop_augment_subcommands[EXE] derived [OPTIONS]
Usage:
interop_augment_subcommands derived [OPTIONS]

For more information try --help

Expand All @@ -89,8 +89,8 @@ $ interop_augment_subcommands unknown
? failed
error: Found argument 'unknown' which wasn't expected, or isn't valid in this context

USAGE:
interop_augment_subcommands[EXE] [SUBCOMMAND]
Usage:
interop_augment_subcommands [SUBCOMMAND]

For more information try --help

Expand All @@ -103,14 +103,14 @@ $ interop_hand_subcommand
? failed
clap

USAGE:
interop_hand_subcommand[EXE] [OPTIONS] <SUBCOMMAND>
Usage:
interop_hand_subcommand [OPTIONS] <SUBCOMMAND>

OPTIONS:
Options:
-t, --top-level
-h, --help Print help information

SUBCOMMANDS:
Subcommands:
add
remove
help Print this message or the help of the given subcommand(s)
Expand Down Expand Up @@ -154,8 +154,8 @@ error: Found argument '--unknown' which wasn't expected, or isn't valid in this

If you tried to supply `--unknown` as a value rather than a flag, use `-- --unknown`

USAGE:
interop_hand_subcommand[EXE] add [NAME]...
Usage:
interop_hand_subcommand add [NAME]...

For more information try --help

Expand Down Expand Up @@ -198,8 +198,8 @@ $ interop_hand_subcommand unknown
? failed
error: Found argument 'unknown' which wasn't expected, or isn't valid in this context

USAGE:
interop_hand_subcommand[EXE] [OPTIONS] <SUBCOMMAND>
Usage:
interop_hand_subcommand [OPTIONS] <SUBCOMMAND>

For more information try --help

Expand Down Expand Up @@ -255,8 +255,8 @@ error: Found argument '--unknown' which wasn't expected, or isn't valid in this

If you tried to supply `--unknown` as a value rather than a flag, use `-- --unknown`

USAGE:
interop_flatten_hand_args[EXE] [OPTIONS]
Usage:
interop_flatten_hand_args [OPTIONS]

For more information try --help

Expand Down
12 changes: 6 additions & 6 deletions examples/escaped-positional-derive.md
View file
Expand Up @@ -8,13 +8,13 @@ $ escaped-positional-derive --help
clap [..]
A simple to use, efficient, and full-featured Command Line Argument Parser

USAGE:
escaped-positional-derive[EXE] [OPTIONS] [-- <SLOP>...]
Usage:
escaped-positional-derive [OPTIONS] [-- <SLOP>...]

ARGS:
Arguments:
<SLOP>...

OPTIONS:
Options:
-f
-p <PEAR>
-h, --help Print help information
Expand All @@ -37,8 +37,8 @@ $ escaped-positional-derive foo bar
? failed
error: Found argument 'foo' which wasn't expected, or isn't valid in this context

USAGE:
escaped-positional-derive[EXE] [OPTIONS] [-- <SLOP>...]
Usage:
escaped-positional-derive [OPTIONS] [-- <SLOP>...]

For more information try --help

Expand Down
12 changes: 6 additions & 6 deletions examples/escaped-positional.md
View file
Expand Up @@ -8,13 +8,13 @@ $ escaped-positional --help
clap [..]
A simple to use, efficient, and full-featured Command Line Argument Parser

USAGE:
escaped-positional[EXE] [OPTIONS] [-- <SLOP>...]
Usage:
escaped-positional [OPTIONS] [-- <SLOP>...]

ARGS:
Arguments:
<SLOP>...

OPTIONS:
Options:
-f
-p <PEAR>
-h, --help Print help information
Expand All @@ -37,8 +37,8 @@ $ escaped-positional foo bar
? failed
error: Found argument 'foo' which wasn't expected, or isn't valid in this context

USAGE:
escaped-positional[EXE] [OPTIONS] [-- <SLOP>...]
Usage:
escaped-positional [OPTIONS] [-- <SLOP>...]

For more information try --help

Expand Down
6 changes: 3 additions & 3 deletions examples/find.md
View file
Expand Up @@ -5,10 +5,10 @@ $ find --help
clap 4.0.0-alpha.0
A simple to use, efficient, and full-featured Command Line Argument Parser

USAGE:
find[EXE] [OPTIONS] --name <NAME>
Usage:
find [OPTIONS] --name <NAME>

OPTIONS:
Options:
-h, --help Print help information
-V, --version Print version information

Expand Down
56 changes: 28 additions & 28 deletions examples/git-derive.md
View file
Expand Up @@ -9,13 +9,13 @@ $ git-derive
git
A fictional versioning CLI

USAGE:
git-derive[EXE] <SUBCOMMAND>
Usage:
git-derive <SUBCOMMAND>

OPTIONS:
Options:
-h, --help Print help information

SUBCOMMANDS:
Subcommands:
clone Clones repos
push pushes things
add adds things
Expand All @@ -26,13 +26,13 @@ $ git-derive help
git
A fictional versioning CLI

USAGE:
git-derive[EXE] <SUBCOMMAND>
Usage:
git-derive <SUBCOMMAND>

OPTIONS:
Options:
-h, --help Print help information

SUBCOMMANDS:
Subcommands:
clone Clones repos
push pushes things
add adds things
Expand All @@ -43,13 +43,13 @@ $ git-derive help add
git-add
adds things

USAGE:
git-derive[EXE] add <PATH>...
Usage:
git-derive add <PATH>...

ARGS:
Arguments:
<PATH>... Stuff to add

OPTIONS:
Options:
-h, --help Print help information

```
Expand All @@ -61,13 +61,13 @@ $ git-derive add
git-add
adds things

USAGE:
git-derive[EXE] add <PATH>...
Usage:
git-derive add <PATH>...

ARGS:
Arguments:
<PATH>... Stuff to add

OPTIONS:
Options:
-h, --help Print help information

$ git-derive add Cargo.toml Cargo.lock
Expand All @@ -80,15 +80,15 @@ Default subcommand:
$ git-derive stash -h
git-stash

USAGE:
git-derive[EXE] stash [OPTIONS]
git-derive[EXE] stash <SUBCOMMAND>
Usage:
git-derive stash [OPTIONS]
git-derive stash <SUBCOMMAND>

OPTIONS:
Options:
-m, --message <MESSAGE>
-h, --help Print help information

SUBCOMMANDS:
Subcommands:
push
pop
apply
Expand All @@ -97,23 +97,23 @@ SUBCOMMANDS:
$ git-derive stash push -h
git-stash-push

USAGE:
git-derive[EXE] stash push [OPTIONS]
Usage:
git-derive stash push [OPTIONS]

OPTIONS:
Options:
-m, --message <MESSAGE>
-h, --help Print help information

$ git-derive stash pop -h
git-stash-pop

USAGE:
git-derive[EXE] stash pop [STASH]
Usage:
git-derive stash pop [STASH]

ARGS:
Arguments:
<STASH>

OPTIONS:
Options:
-h, --help Print help information

$ git-derive stash -m "Prototype"
Expand Down

0 comments on commit 6c29148

Please sign in to comment.