Repository: clap-rs/clap
Pull request #3470 (2022-02-14 22:26:17)

fix(help): Improve pacman help output
This fixes issues with the output and makes it more consistent.

See #1361 for example pacman output for any concern of inconsistency with that.  Pacman uses a space for alternate.  The original PR used a comma.  This switches to pipe since that is the generally expected alternate character in usage.


Patch:
diff --git a/clap_complete/src/shells/fish.rs b/clap_complete/src/shells/fish.rs
index 3327dbc1..06342296 100644
--- a/clap_complete/src/shells/fish.rs
+++ b/clap_complete/src/shells/fish.rs
@@ -158,8 +158,8 @@ fn value_completion(option: &Arg) -> String {
                 } else {
                     Some(format!(
                         "{}\t{}",
-                        escape_string(value.get_name()).as_str(),
-                        escape_string(value.get_help().unwrap_or_default()).as_str()
+                        value.get_name(),
+                        value.get_help().unwrap_or_default()
                     ))
                 })
                 .collect::<Vec<_>>()
diff --git a/examples/pacman.md b/examples/pacman.md
index dff5149a..7f6c5a7d 100644
--- a/examples/pacman.md
+++ b/examples/pacman.md
@@ -49,16 +49,16 @@ OPTIONS:
     -V, --version    Print version information
 
 SUBCOMMANDS:
-    -Q--queryquery    Query the package database.
-    -S--syncsync      Synchronize packages.
-    help              Print this message or the help of the given subcommand(s)
+    help                Print this message or the help of the given subcommand(s)
+    query -Q --query    Query the package database.
+    sync -S --sync      Synchronize packages.
 
 $ pacman -S -h
 pacman[EXE]-sync 
 Synchronize packages.
 
 USAGE:
-    pacman[EXE] {sync, --sync, -S} [OPTIONS] [--] [package]...
+    pacman[EXE] {sync|--sync|-S} [OPTIONS] [--] [package]...
 
 ARGS:
     <package>...    packages
@@ -77,7 +77,7 @@ $ pacman -S -s foo -i bar
 error: The argument '--search <search>...' cannot be used with '--info'
 
 USAGE:
-    pacman[EXE] {sync, --sync, -S} --search <search>... <package>...
+    pacman[EXE] {sync|--sync|-S} --search <search>... <package>...
 
 For more information try --help
 
diff --git a/src/build/app.rs b/src/build/app.rs
index 5f435ec4..bcc36ea2 100644
--- a/src/build/app.rs
+++ b/src/build/app.rs
@@ -4003,11 +4003,11 @@ impl<'help> App<'help> {
         let mut sc_names = sc.name.clone();
         let mut flag_subcmd = false;
         if let Some(l) = sc.long_flag {
-            write!(sc_names, ", --{}", l).unwrap();
+            write!(sc_names, "|--{}", l).unwrap();
             flag_subcmd = true;
         }
         if let Some(s) = sc.short_flag {
-            write!(sc_names, ", -{}", s).unwrap();
+            write!(sc_names, "|-{}", s).unwrap();
             flag_subcmd = true;
         }
 
diff --git a/src/output/help.rs b/src/output/help.rs
index 0b5bed56..b1faad88 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -844,13 +844,13 @@ impl<'help, 'app, 'writer> Help<'help, 'app, 'writer> {
             .filter(|subcommand| should_show_subcommand(subcommand))
         {
             let mut sc_str = String::new();
+            sc_str.push_str(subcommand.get_name());
             if let Some(short) = subcommand.get_short_flag() {
-                write!(sc_str, "-{}", short).unwrap();
+                write!(sc_str, " -{}", short).unwrap();
             }
             if let Some(long) = subcommand.get_long_flag() {
-                write!(sc_str, "--{}", long).unwrap();
+                write!(sc_str, " --{}", long).unwrap();
             }
-            sc_str.push_str(subcommand.get_name());
             longest = longest.max(display_width(&sc_str));
             ord_v.push((subcommand.get_display_order(), sc_str, subcommand));
         }


Test patch:
diff --git a/clap_complete/tests/completions/fish.rs b/clap_complete/tests/completions/fish.rs
index beb0ae39..0da349c2 100644
--- a/clap_complete/tests/completions/fish.rs
+++ b/clap_complete/tests/completions/fish.rs
@@ -1,5 +1,3 @@
-use clap::PossibleValue;
-
 use super::*;
 
 fn build_app() -> App<'static> {
@@ -174,7 +172,6 @@ fn build_app_sub_subcommands() -> App<'static> {
                     Arg::new("config")
                         .long("--config")
                         .takes_value(true)
-                        .possible_values([PossibleValue::new("Lest quotes aren't escaped.")])
                         .help("the other case to test"),
                 ),
             ),
@@ -193,7 +190,7 @@ complete -c my_app -n "__fish_seen_subcommand_from some_cmd; and not __fish_seen
 complete -c my_app -n "__fish_seen_subcommand_from some_cmd; and not __fish_seen_subcommand_from sub_cmd; and not __fish_seen_subcommand_from help" -s V -l version -d 'Print version information'
 complete -c my_app -n "__fish_seen_subcommand_from some_cmd; and not __fish_seen_subcommand_from sub_cmd; and not __fish_seen_subcommand_from help" -f -a "sub_cmd" -d 'sub-subcommand'
 complete -c my_app -n "__fish_seen_subcommand_from some_cmd; and not __fish_seen_subcommand_from sub_cmd; and not __fish_seen_subcommand_from help" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
-complete -c my_app -n "__fish_seen_subcommand_from some_cmd; and __fish_seen_subcommand_from sub_cmd" -l config -d 'the other case to test' -r -f -a "{Lest quotes aren\'t escaped.	}"
+complete -c my_app -n "__fish_seen_subcommand_from some_cmd; and __fish_seen_subcommand_from sub_cmd" -l config -d 'the other case to test' -r
 complete -c my_app -n "__fish_seen_subcommand_from some_cmd; and __fish_seen_subcommand_from sub_cmd" -s h -l help -d 'Print help information'
 complete -c my_app -n "__fish_seen_subcommand_from some_cmd; and __fish_seen_subcommand_from sub_cmd" -s V -l version -d 'Print version information'
 complete -c my_app -n "__fish_seen_subcommand_from some_cmd; and __fish_seen_subcommand_from help" -s h -l help -d 'Print help information'
diff --git a/tests/builder/flag_subcommands.rs b/tests/builder/flag_subcommands.rs
index 9decadfd..fc1b1c2b 100644
--- a/tests/builder/flag_subcommands.rs
+++ b/tests/builder/flag_subcommands.rs
@@ -453,7 +453,7 @@ static FLAG_SUBCOMMAND_HELP: &str = "pacman-query
 Query the package database.
 
 USAGE:
-    pacman {query, --query, -Q} [OPTIONS]
+    pacman {query|--query|-Q} [OPTIONS]
 
 OPTIONS:
     -h, --help                  Print help information
@@ -507,7 +507,7 @@ static FLAG_SUBCOMMAND_NO_SHORT_HELP: &str = "pacman-query
 Query the package database.
 
 USAGE:
-    pacman {query, --query} [OPTIONS]
+    pacman {query|--query} [OPTIONS]
 
 OPTIONS:
     -h, --help                  Print help information
@@ -560,7 +560,7 @@ static FLAG_SUBCOMMAND_NO_LONG_HELP: &str = "pacman-query
 Query the package database.
 
 USAGE:
-    pacman {query, -Q} [OPTIONS]
+    pacman {query|-Q} [OPTIONS]
 
 OPTIONS:
     -h, --help                  Print help information