fix(help): Consistently use [] for positionals

In the usaeg we use `[]` but in the arg list we use `<>`.

clap_complete/tests/snapshots/aliases.bash

@@ -19,7 +19,7 @@ _my-app() {
 
     case "${cmd}" in
         my__app)
-            opts="-F -f -O -o -h -V --flg --flag --opt --option --help --version <positional>"
+            opts="-F -f -O -o -h -V --flg --flag --opt --option --help --version [positional]"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

clap_complete/tests/snapshots/feature_sample.bash

@@ -25,7 +25,7 @@ _my-app() {
 
     case "${cmd}" in
         my__app)
-            opts="-C -c -h -V --conf --config --help --version <file> first second test help"
+            opts="-C -c -h -V --conf --config --help --version [file] first second test help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

clap_complete/tests/snapshots/special_commands.bash

@@ -34,7 +34,7 @@ _my-app() {
 
     case "${cmd}" in
         my__app)
-            opts="-C -c -h -V --conf --config --help --version <file> first second test some_cmd some-cmd-with-hyphens some-hidden-cmd help"
+            opts="-C -c -h -V --conf --config --help --version [file] first second test some_cmd some-cmd-with-hyphens some-hidden-cmd help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -160,7 +160,7 @@ _my-app() {
             return 0
             ;;
         my__app__some_cmd)
-            opts="-h -V --config --help --version <path>..."
+            opts="-h -V --config --help --version [path]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

clap_complete/tests/snapshots/sub_subcommands.bash

@@ -31,7 +31,7 @@ _my-app() {
 
     case "${cmd}" in
         my__app)
-            opts="-C -c -h -V --conf --config --help --version <file> first second test some_cmd help"
+            opts="-C -c -h -V --conf --config --help --version [file] first second test some_cmd help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

clap_complete/tests/snapshots/value_hint.bash

@@ -19,7 +19,7 @@ _my-app() {
 
     case "${cmd}" in
         my__app)
-            opts="-p -f -d -e -c -u -H -h --choice --unknown --other --path --file --dir --exe --cmd-name --cmd --user --host --url --email --help <command_with_args>..."
+            opts="-p -f -d -e -c -u -H -h --choice --unknown --other --path --file --dir --exe --cmd-name --cmd --user --host --url --email --help [command_with_args]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

examples/escaped-positional-derive.md

@@ -12,7 +12,7 @@ Usage:
     escaped-positional-derive[EXE] [OPTIONS] [-- <SLOP>...]
 
 Arguments:
-    <SLOP>...    
+    [SLOP]...    
 
 Options:
     -f               

examples/escaped-positional.md

@@ -12,7 +12,7 @@ Usage:
     escaped-positional[EXE] [OPTIONS] [-- <SLOP>...]
 
 Arguments:
-    <SLOP>...    
+    [SLOP]...    
 
 Options:
     -f               

examples/git-derive.md

@@ -111,7 +111,7 @@ Usage:
     git-derive[EXE] stash pop [STASH]
 
 Arguments:
-    <STASH>    
+    [STASH]    
 
 Options:
     -h, --help    Print help information

examples/git.md

@@ -109,7 +109,7 @@ Usage:
     git[EXE] stash pop [STASH]
 
 Arguments:
-    <STASH>    
+    [STASH]    
 
 Options:
     -h, --help    Print help information

examples/pacman.md

@@ -59,7 +59,7 @@ Usage:
     pacman[EXE] {sync|--sync|-S} [OPTIONS] [--] [package]...
 
 Arguments:
-    <package>...    packages
+    [package]...    packages
 
 Options:
     -s, --search <search>...    search remote repositories for matching strings

examples/tutorial_builder/01_quick.md

@@ -11,7 +11,7 @@ Subcommands:
     help    Print this message or the help of the given subcommand(s)
 
 Arguments:
-    <name>    Optional name to operate on
+    [name]    Optional name to operate on
 
 Options:
     -c, --config <FILE>    Sets a custom config file

examples/tutorial_builder/03_03_positional.md

@@ -7,7 +7,7 @@ Usage:
     03_03_positional[EXE] [name]
 
 Arguments:
-    <name>    
+    [name]    
 
 Options:
     -h, --help       Print help information

examples/tutorial_builder/03_03_positional_mult.md

@@ -7,7 +7,7 @@ Usage:
     03_03_positional_mult[EXE] [name]...
 
 Arguments:
-    <name>...    
+    [name]...    
 
 Options:
     -h, --help       Print help information

examples/tutorial_builder/03_04_subcommands.md

@@ -22,7 +22,7 @@ Usage:
     03_04_subcommands[EXE] add [NAME]
 
 Arguments:
-    <NAME>    
+    [NAME]    
 
 Options:
     -h, --help       Print help information

examples/tutorial_builder/03_05_default_values.md

@@ -7,7 +7,7 @@ Usage:
     03_05_default_values[EXE] [NAME]
 
 Arguments:
-    <NAME>    [default: alice]
+    [NAME]    [default: alice]
 
 Options:
     -h, --help       Print help information

examples/tutorial_builder/04_03_relations.md

@@ -7,7 +7,7 @@ Usage:
     04_03_relations[EXE] [OPTIONS] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE]
 
 Arguments:
-    <INPUT_FILE>    some regular input
+    [INPUT_FILE]    some regular input
 
 Options:
         --set-ver <VER>        set version manually

examples/tutorial_builder/04_04_custom.md

@@ -7,7 +7,7 @@ Usage:
     04_04_custom[EXE] [OPTIONS] [INPUT_FILE]
 
 Arguments:
-    <INPUT_FILE>    some regular input
+    [INPUT_FILE]    some regular input
 
 Options:
         --set-ver <VER>        set version manually

examples/tutorial_derive/01_quick.md

@@ -11,7 +11,7 @@ Subcommands:
     help    Print this message or the help of the given subcommand(s)
 
 Arguments:
-    <NAME>    Optional name to operate on
+    [NAME]    Optional name to operate on
 
 Options:
     -c, --config <FILE>    Sets a custom config file

examples/tutorial_derive/03_03_positional.md

@@ -7,7 +7,7 @@ Usage:
     03_03_positional_derive[EXE] [NAME]
 
 Arguments:
-    <NAME>    
+    [NAME]    
 
 Options:
     -h, --help       Print help information

examples/tutorial_derive/03_03_positional_mult.md

@@ -7,7 +7,7 @@ Usage:
     03_03_positional_mult_derive[EXE] [NAME]...
 
 Arguments:
-    <NAME>...    
+    [NAME]...    
 
 Options:
     -h, --help       Print help information

examples/tutorial_derive/03_04_subcommands.md

@@ -22,7 +22,7 @@ Usage:
     03_04_subcommands_derive[EXE] add [NAME]
 
 Arguments:
-    <NAME>    
+    [NAME]    
 
 Options:
     -h, --help       Print help information

examples/tutorial_derive/03_05_default_values.md

@@ -7,7 +7,7 @@ Usage:
     03_05_default_values_derive[EXE] [NAME]
 
 Arguments:
-    <NAME>    [default: alice]
+    [NAME]    [default: alice]
 
 Options:
     -h, --help       Print help information

examples/tutorial_derive/04_03_relations.md

@@ -7,7 +7,7 @@ Usage:
     04_03_relations_derive[EXE] [OPTIONS] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE]
 
 Arguments:
-    <INPUT_FILE>    some regular input
+    [INPUT_FILE]    some regular input
 
 Options:
         --set-ver <VER>        set version manually

examples/tutorial_derive/04_04_custom.md

@@ -7,7 +7,7 @@ Usage:
     04_04_custom_derive[EXE] [OPTIONS] [INPUT_FILE]
 
 Arguments:
-    <INPUT_FILE>    some regular input
+    [INPUT_FILE]    some regular input
 
 Options:
         --set-ver <VER>        set version manually

src/builder/arg.rs

@@ -3970,7 +3970,7 @@ impl Arg {
         }
     }
 
-    pub(crate) fn stylized(&self) -> StyledStr {
+    pub(crate) fn stylized(&self, required: Option<bool>) -> StyledStr {
         let mut styled = StyledStr::new();
         // Write the name such --long or -l
         if let Some(l) = self.get_long() {
@@ -3980,11 +3980,11 @@ impl Arg {
             styled.literal("-");
             styled.literal(s);
         }
-        styled.extend(self.stylize_arg_suffix().into_iter());
+        styled.extend(self.stylize_arg_suffix(required).into_iter());
         styled
     }
 
-    pub(crate) fn stylize_arg_suffix(&self) -> StyledStr {
+    pub(crate) fn stylize_arg_suffix(&self, required: Option<bool>) -> StyledStr {
         let mut styled = StyledStr::new();
 
         let mut need_closing_bracket = false;
@@ -4005,7 +4005,8 @@ impl Arg {
             }
         }
         if self.is_takes_value_set() || self.is_positional() {
-            let arg_val = self.render_arg_val();
+            let required = required.unwrap_or_else(|| self.is_required_set());
+            let arg_val = self.render_arg_val(required);
             styled.placeholder(arg_val);
         } else if matches!(*self.get_action(), ArgAction::Count) {
             styled.placeholder("...");
@@ -4018,7 +4019,7 @@ impl Arg {
     }
 
     /// Write the values such as <name1> <name2>
-    fn render_arg_val(&self) -> String {
+    fn render_arg_val(&self, required: bool) -> String {
         let mut rendered = String::new();
 
         let num_vals = self.get_num_args().expect(INTERNAL_ERROR_MSG);
@@ -4036,7 +4037,7 @@ impl Arg {
 
         debug_assert!(self.is_takes_value_set());
         for (n, val_name) in val_names.iter().enumerate() {
-            let arg_name = if self.is_positional() && num_vals.min_values() == 0 {
+            let arg_name = if self.is_positional() && (num_vals.min_values() == 0 || !required) {
                 format!("[{}]", val_name)
             } else {
                 format!("<{}>", val_name)
@@ -4098,7 +4099,7 @@ impl Eq for Arg {}
 
 impl Display for Arg {
     fn fmt(&self, f: &mut Formatter) -> fmt::Result {
-        self.stylized().fmt(f)
+        self.stylized(None).fmt(f)
     }
 }
 
@@ -4372,6 +4373,14 @@ mod test {
         let mut p = Arg::new("pos").index(1).num_args(1..);
         p._build();
 
+        assert_eq!(p.to_string(), "[pos]...");
+    }
+
+    #[test]
+    fn positional_display_multiple_values_required() {
+        let mut p = Arg::new("pos").index(1).num_args(1..).required(true);
+        p._build();
+
         assert_eq!(p.to_string(), "<pos>...");
     }
 
@@ -4388,6 +4397,14 @@ mod test {
         let mut p = Arg::new("pos").index(1).num_args(1..);
         p._build();
 
+        assert_eq!(p.to_string(), "[pos]...");
+    }
+
+    #[test]
+    fn positional_display_one_or_more_values_required() {
+        let mut p = Arg::new("pos").index(1).num_args(1..).required(true);
+        p._build();
+
         assert_eq!(p.to_string(), "<pos>...");
     }
 
@@ -4407,6 +4424,17 @@ mod test {
         let mut p = Arg::new("pos").index(1).action(ArgAction::Append);
         p._build();
 
+        assert_eq!(p.to_string(), "[pos]...");
+    }
+
+    #[test]
+    fn positional_display_multiple_occurrences_required() {
+        let mut p = Arg::new("pos")
+            .index(1)
+            .action(ArgAction::Append)
+            .required(true);
+        p._build();
+
         assert_eq!(p.to_string(), "<pos>...");
     }
 
@@ -4423,6 +4451,17 @@ mod test {
         let mut p = Arg::new("pos").index(1).value_names(["file1", "file2"]);
         p._build();
 
+        assert_eq!(p.to_string(), "[file1] [file2]");
+    }
+
+    #[test]
+    fn positional_display_val_names_required() {
+        let mut p = Arg::new("pos")
+            .index(1)
+            .value_names(["file1", "file2"])
+            .required(true);
+        p._build();
+
         assert_eq!(p.to_string(), "<file1> <file2>");
     }
 

src/output/help.rs

@@ -447,7 +447,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         self.none(TAB);
         self.short(arg);
         self.long(arg);
-        self.writer.extend(arg.stylize_arg_suffix().into_iter());
+        self.writer.extend(arg.stylize_arg_suffix(None).into_iter());
         self.align_to_about(arg, next_line_help, longest);
 
         let about = if self.use_long {

src/output/usage.rs

@@ -418,10 +418,11 @@ impl<'cmd> Usage<'cmd> {
                 if !is_present {
                     if arg.is_positional() {
                         if incl_last || !arg.is_last_set() {
-                            required_positionals.insert((arg.index.unwrap(), arg.stylized()));
+                            required_positionals
+                                .insert((arg.index.unwrap(), arg.stylized(Some(true))));
                         }
                     } else {
-                        required_opts.insert(arg.stylized());
+                        required_opts.insert(arg.stylized(Some(true)));
                     }
                 }
             } else {
@@ -445,7 +446,7 @@ impl<'cmd> Usage<'cmd> {
                         group_members
                             .iter()
                             .flat_map(|id| self.cmd.find(id))
-                            .map(|arg| arg.stylized()),
+                            .map(|arg| arg.stylized(Some(true))),
                     );
                 }
             }

tests/builder/app_settings.rs

@@ -20,9 +20,9 @@ Usage:
     clap-test [arg1] [arg2] [arg3]
 
 Arguments:
-    <arg1>    some
+    [arg1]    some
-    <arg2>    some
+    [arg2]    some
-    <arg3>    some
+    [arg3]    some
 
 Options:
     -h, --help       Print help information
@@ -292,7 +292,7 @@ Usage:
     test [OPTIONS] [arg1]
 
 Arguments:
-    <arg1>    some pos arg
+    [arg1]    some pos arg
 
 Options:
     -o, --opt <opt>    some option

tests/builder/default_missing_vals.rs

@@ -260,7 +260,7 @@ fn delimited_missing_value() {
 
 #[cfg(debug_assertions)]
 #[test]
-#[should_panic = "Argument `arg`'s default_missing_value=\"value\" failed validation: error: \"value\" isn't a valid value for '<arg>'"]
+#[should_panic = "Argument `arg`'s default_missing_value=\"value\" failed validation: error: \"value\" isn't a valid value for '[arg]'"]
 fn default_missing_values_are_possible_values() {
     use clap::{Arg, Command};
 
@@ -275,7 +275,7 @@ fn default_missing_values_are_possible_values() {
 
 #[cfg(debug_assertions)]
 #[test]
-#[should_panic = "Argument `arg`'s default_missing_value=\"value\" failed validation: error: Invalid value \"value\" for '<arg>"]
+#[should_panic = "Argument `arg`'s default_missing_value=\"value\" failed validation: error: Invalid value \"value\" for '[arg]"]
 fn default_missing_values_are_valid() {
     use clap::{Arg, Command};
 

tests/builder/default_vals.rs

@@ -794,7 +794,7 @@ fn required_args_with_default_values() {
 
 #[cfg(debug_assertions)]
 #[test]
-#[should_panic = "Argument `arg`'s default_value=\"value\" failed validation: error: \"value\" isn't a valid value for '<arg>'"]
+#[should_panic = "Argument `arg`'s default_value=\"value\" failed validation: error: \"value\" isn't a valid value for '[arg]'"]
 fn default_values_are_possible_values() {
     use clap::{Arg, Command};
 
@@ -809,7 +809,7 @@ fn default_values_are_possible_values() {
 
 #[cfg(debug_assertions)]
 #[test]
-#[should_panic = "Argument `arg`'s default_value=\"one\" failed validation: error: Invalid value \"one\" for '<arg>"]
+#[should_panic = "Argument `arg`'s default_value=\"one\" failed validation: error: Invalid value \"one\" for '[arg]"]
 fn invalid_default_values() {
     use clap::{Arg, Command};
 
@@ -838,7 +838,7 @@ fn valid_delimited_default_values() {
 
 #[cfg(debug_assertions)]
 #[test]
-#[should_panic = "Argument `arg`'s default_value=\"one\" failed validation: error: Invalid value \"one\" for '<arg>"]
+#[should_panic = "Argument `arg`'s default_value=\"one\" failed validation: error: Invalid value \"one\" for '[arg]"]
 fn invalid_delimited_default_values() {
     use clap::{Arg, Command};
 

tests/builder/groups.rs

@@ -12,7 +12,7 @@ For more information try --help
 ";
 
 static REQ_GROUP_CONFLICT_USAGE: &str =
-    "error: The argument '--delete' cannot be used with '<base>'
+    "error: The argument '--delete' cannot be used with '[base]'
 
 Usage:
     clap-test <base|--delete>
@@ -267,7 +267,7 @@ Usage:
     prog <A>
 
 Arguments:
-    <A>    
+    [A]    
 
 Options:
     -h, --help    Print help information

tests/builder/help.rs

@@ -123,8 +123,8 @@ Usage:
     flamegraph [OPTIONS] [BINFILE] [-- <ARGS>...]
 
 Arguments:
-    <BINFILE>    The path of the binary to be profiled. for a binary.
+    [BINFILE]    The path of the binary to be profiled. for a binary.
-    <ARGS>...    Any arguments you wish to pass to the being profiled.
+    [ARGS]...    Any arguments you wish to pass to the being profiled.
 
 Options:
     -v, --verbose              Prints out more stuff.
@@ -212,9 +212,9 @@ Subcommands:
     help      Print this message or the help of the given subcommand(s)
 
 Arguments:
-    <positional>        tests positionals
+    [positional]        tests positionals
-    <positional2>       tests positionals with exclusions
+    [positional2]       tests positionals with exclusions
-    <positional3>...    tests specific values [possible values: vi, emacs]
+    [positional3]...    tests specific values [possible values: vi, emacs]
 
 Options:
     -o, --option <opt>...                    tests options
@@ -549,7 +549,7 @@ Usage:
     clap-test subcmd [OPTIONS] [--] [scpositional]
 
 Arguments:
-    <scpositional>    tests positionals
+    [scpositional]    tests positionals
 
 Options:
     -o, --option <scoption>...     tests options
@@ -801,7 +801,7 @@ Usage:
     ctest [mode]
 
 Arguments:
-    <mode>    x, max, maximum   20 characters, contains
+    [mode]    x, max, maximum   20 characters, contains
               symbols.
               l, long           Copy-friendly, 14
               characters, contains symbols.
@@ -965,8 +965,8 @@ Usage:
     myapp [OPTIONS] [--] [ARGS]
 
 Arguments:
-    <arg1>       some option
+    [arg1]       some option
-    <arg2>...    some option
+    [arg2]...    some option
 
 Options:
     -s, --some <some>         some option
@@ -1024,7 +1024,7 @@ Usage:
     myapp [arg1]
 
 Arguments:
-    <arg1>
+    [arg1]
             some option
 
 Options:
@@ -1108,7 +1108,7 @@ Subcommands:
     help    Print this message or the help of the given subcommand(s)
 
 Arguments:
-    <PATH>    help
+    [PATH]    help
 
 Options:
     -o, --opt <FILE>    tests options
@@ -1160,7 +1160,7 @@ Subcommands:
     help    Print this message or the help of the given subcommand(s)
 
 Arguments:
-    <PATH>    help
+    [PATH]    help
 
 Options:
     -f, --flag          testing flags
@@ -1187,7 +1187,7 @@ Usage:
     prog [OPTIONS] [PATH]
 
 Arguments:
-    <PATH>    some
+    [PATH]    some
 
 Options:
     -f, --flag          testing flags
@@ -1337,8 +1337,8 @@ Usage:
 
 Arguments:
     <TARGET>     some
-    <CORPUS>     some
+    [CORPUS]     some
-    <ARGS>...    some
+    [ARGS]...    some
 
 Options:
     -h, --help       Print help information
@@ -1368,7 +1368,7 @@ Usage:
 
 Arguments:
     <TARGET>     some
-    <CORPUS>     some
+    [CORPUS]     some
     <ARGS>...    some
 
 Options:
@@ -1405,7 +1405,7 @@ Subcommands:
 
 Arguments:
     <TARGET>     some
-    <CORPUS>     some
+    [CORPUS]     some
     <ARGS>...    some
 
 Options:
@@ -1444,8 +1444,8 @@ Subcommands:
 
 Arguments:
     <TARGET>     some
-    <CORPUS>     some
+    [CORPUS]     some
-    <ARGS>...    some
+    [ARGS]...    some
 
 Options:
     -h, --help       Print help information
@@ -1851,7 +1851,7 @@ Usage:
     demo [OPTIONS] [FILES]...
 
 Arguments:
-    <FILES>...    
+    [FILES]...    
 
 Options:
     -f            
@@ -1885,8 +1885,8 @@ Usage:
     ctest <arg1|arg2>
 
 Arguments:
-    <arg1>    
+    [arg1]    
-    <arg2>    
+    [arg2]    
 
 Options:
     -h, --help    Print help information
@@ -2274,8 +2274,8 @@ Usage:
     deno <pos1|--option1> [pos2]
 
 Arguments:
-    <pos1>    
+    [pos1]    
-    <pos2>    
+    [pos2]    
 
 Options:
         --option1    
@@ -2306,14 +2306,14 @@ Usage:
     test [ARGS]
 
 Arguments:
-    <gear>    Which gear
+    [gear]    Which gear
 
 Options:
     -h, --help       Print help information
     -V, --version    Print version information
 
 NETWORKING:
-    <speed>    How fast
+    [speed]    How fast
 ";
 
 #[test]
@@ -2355,7 +2355,7 @@ Usage:
     test [speed]
 
 NETWORKING:
-    <speed>    How fast
+    [speed]    How fast
 ";
 
 #[test]
@@ -2413,7 +2413,7 @@ Usage:
     test [arg1] <arg2>
 
 Arguments:
-    <arg1>    
+    [arg1]    
     <arg2>    
 
 Options:
@@ -2439,9 +2439,9 @@ Usage:
     test [ARGS]
 
 Arguments:
-    <foo>       
+    [foo]       
-    <bar>       
+    [bar]       
-    <baz>...    
+    [baz]...    
 
 Options:
     -h, --help    Print help information

tests/builder/hidden_args.rs

@@ -197,7 +197,7 @@ Usage:
     test [another]
 
 Arguments:
-    <another>    another pos
+    [another]    another pos
 
 Options:
     -h, --help       Print help information

tests/builder/subcommands.rs

@@ -580,7 +580,7 @@ Usage:
     foo bar [value]
 
 Arguments:
-    <value>    
+    [value]    
 
 Options:
     -h, --help       Print help information
@@ -603,7 +603,7 @@ Usage:
     foo bar [value]
 
 Arguments:
-    <value>    
+    [value]    
 
 Options:
     -h, --help       Print help information
@@ -626,7 +626,7 @@ Usage:
     foo bar [value]
 
 Arguments:
-    <value>    
+    [value]    
 
 Options:
     -h, --help       Print help information