fix(help): Don't rely on ALL CAPS for headers

CHANGELOG.md

@@ -48,6 +48,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Removed lifetimes from `Command`, `Arg`, `ArgGroup`, and `PossibleValue`
 - *(help)* Make `DeriveDisplayOrder` the default and removed the setting.  To sort help, set `next_display_order(None)` (#2808)
 - *(help)* Subcommand display order respects `Command::next_display_order` instead of `DeriveDisplayOrder` and using its own initial display order value (#2808)
+- *(help)* Help headings are now title cased, making any user-provided help headings inconsistent
 - *(env)* Parse `--help` and `--version` like any `ArgAction::SetTrue` flag (#3776)
 - *(derive)* Changed the default for arguments from `parse` to `value_parser`., removing `parse` support
 - *(derive)* `subcommand_required(true).arg_required_else_help(true)` is set instead of `SubcommandRequiredElseHelp` (#3280)
@@ -83,6 +84,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)

examples/cargo-example-derive.md

@@ -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

examples/cargo-example.md

@@ -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

examples/demo.md

@@ -3,10 +3,10 @@ $ demo --help
 clap [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
-USAGE:
+Usage:
     demo[EXE] [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

examples/derive_ref/custom-bool.md

@@ -7,13 +7,13 @@ $ custom-bool --help
 clap [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
-USAGE:
+Usage:
     custom-bool[EXE] [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
@@ -25,7 +25,7 @@ error: The following required arguments were not provided:
     --foo <FOO>
     <BOOM>
 
-USAGE:
+Usage:
     custom-bool[EXE] [OPTIONS] --foo <FOO> <BOOM>
 
 For more information try --help

examples/derive_ref/interop_tests.md

@@ -39,7 +39,7 @@ 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:
+Usage:
     interop_augment_args[EXE] [OPTIONS]
 
 For more information try --help
@@ -77,7 +77,7 @@ 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:
+Usage:
     interop_augment_subcommands[EXE] derived [OPTIONS]
 
 For more information try --help
@@ -89,7 +89,7 @@ $ interop_augment_subcommands unknown
 ? failed
 error: Found argument 'unknown' which wasn't expected, or isn't valid in this context
 
-USAGE:
+Usage:
     interop_augment_subcommands[EXE] [SUBCOMMAND]
 
 For more information try --help
@@ -103,14 +103,14 @@ $ interop_hand_subcommand
 ? failed
 clap 
 
-USAGE:
+Usage:
     interop_hand_subcommand[EXE] [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)
@@ -154,7 +154,7 @@ 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:
+Usage:
     interop_hand_subcommand[EXE] add [NAME]...
 
 For more information try --help
@@ -198,7 +198,7 @@ $ interop_hand_subcommand unknown
 ? failed
 error: Found argument 'unknown' which wasn't expected, or isn't valid in this context
 
-USAGE:
+Usage:
     interop_hand_subcommand[EXE] [OPTIONS] <SUBCOMMAND>
 
 For more information try --help
@@ -255,7 +255,7 @@ 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:
+Usage:
     interop_flatten_hand_args[EXE] [OPTIONS]
 
 For more information try --help

examples/escaped-positional-derive.md

@@ -8,13 +8,13 @@ $ escaped-positional-derive --help
 clap [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
-USAGE:
+Usage:
     escaped-positional-derive[EXE] [OPTIONS] [-- <SLOP>...]
 
-ARGS:
+Arguments:
     <SLOP>...    
 
-OPTIONS:
+Options:
     -f               
     -p <PEAR>        
     -h, --help       Print help information
@@ -37,7 +37,7 @@ $ escaped-positional-derive foo bar
 ? failed
 error: Found argument 'foo' which wasn't expected, or isn't valid in this context
 
-USAGE:
+Usage:
     escaped-positional-derive[EXE] [OPTIONS] [-- <SLOP>...]
 
 For more information try --help

examples/escaped-positional.md

@@ -8,13 +8,13 @@ $ escaped-positional --help
 clap [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
-USAGE:
+Usage:
     escaped-positional[EXE] [OPTIONS] [-- <SLOP>...]
 
-ARGS:
+Arguments:
     <SLOP>...    
 
-OPTIONS:
+Options:
     -f               
     -p <PEAR>        
     -h, --help       Print help information
@@ -37,7 +37,7 @@ $ escaped-positional foo bar
 ? failed
 error: Found argument 'foo' which wasn't expected, or isn't valid in this context
 
-USAGE:
+Usage:
     escaped-positional[EXE] [OPTIONS] [-- <SLOP>...]
 
 For more information try --help

examples/find.md

@@ -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:
+Usage:
     find[EXE] [OPTIONS] --name <NAME>
 
-OPTIONS:
+Options:
     -h, --help       Print help information
     -V, --version    Print version information
 

examples/git-derive.md

@@ -9,13 +9,13 @@ $ git-derive
 git 
 A fictional versioning CLI
 
-USAGE:
+Usage:
     git-derive[EXE] <SUBCOMMAND>
 
-OPTIONS:
+Options:
     -h, --help    Print help information
 
-SUBCOMMANDS:
+Subcommands:
     clone    Clones repos
     push     pushes things
     add      adds things
@@ -26,13 +26,13 @@ $ git-derive help
 git 
 A fictional versioning CLI
 
-USAGE:
+Usage:
     git-derive[EXE] <SUBCOMMAND>
 
-OPTIONS:
+Options:
     -h, --help    Print help information
 
-SUBCOMMANDS:
+Subcommands:
     clone    Clones repos
     push     pushes things
     add      adds things
@@ -43,13 +43,13 @@ $ git-derive help add
 git-add 
 adds things
 
-USAGE:
+Usage:
     git-derive[EXE] add <PATH>...
 
-ARGS:
+Arguments:
     <PATH>...    Stuff to add
 
-OPTIONS:
+Options:
     -h, --help    Print help information
 
 ```
@@ -61,13 +61,13 @@ $ git-derive add
 git-add 
 adds things
 
-USAGE:
+Usage:
     git-derive[EXE] add <PATH>...
 
-ARGS:
+Arguments:
     <PATH>...    Stuff to add
 
-OPTIONS:
+Options:
     -h, --help    Print help information
 
 $ git-derive add Cargo.toml Cargo.lock
@@ -80,15 +80,15 @@ Default subcommand:
 $ git-derive stash -h
 git-stash 
 
-USAGE:
+Usage:
     git-derive[EXE] stash [OPTIONS]
     git-derive[EXE] stash <SUBCOMMAND>
 
-OPTIONS:
+Options:
     -m, --message <MESSAGE>    
     -h, --help                 Print help information
 
-SUBCOMMANDS:
+Subcommands:
     push     
     pop      
     apply    
@@ -97,23 +97,23 @@ SUBCOMMANDS:
 $ git-derive stash push -h
 git-stash-push 
 
-USAGE:
+Usage:
     git-derive[EXE] stash push [OPTIONS]
 
-OPTIONS:
+Options:
     -m, --message <MESSAGE>    
     -h, --help                 Print help information
 
 $ git-derive stash pop -h
 git-stash-pop 
 
-USAGE:
+Usage:
     git-derive[EXE] stash pop [STASH]
 
-ARGS:
+Arguments:
     <STASH>    
 
-OPTIONS:
+Options:
     -h, --help    Print help information
 
 $ git-derive stash -m "Prototype"