fix(help): Clarify short vs long help

In reviewing CLIs for clap-rs#4132, I found some were providing helps on `-h`
vs `--help` and figured that could be built directly into clap.  I had
considered not making this hint automatic but I figured the overhead of
checking if long exists wouldn't be too bad.  The code exists (no binary
size increase) and just a simple iteration is probably not too slow
compared to everything else.

Fixes clap-rs#1015

CHANGELOG.md

@@ -101,6 +101,7 @@ Deprecated
 - *(help)* Show all `[positional]` in usage
 - *(help)* Polish up subcommands by referring to them as commands
 - *(help)* Trim extra whitespace to avoid artifacts from different uses of templates
+- *(help)* Hint to the user the difference between `-h` / `--help` when applicable (#4159)
 - *(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)

clap_mangen/tests/snapshots/possible_values.bash.roff

@@ -25,7 +25,7 @@ slow: use the slow method
 .RE
 .TP
 /fB/-h/fR, /fB/-/-help/fR
-Print help information
+Print help information (use `/-h` for a summary)
 .TP
 [/fIpositional_choice/fR]
 Pick the Position you want the command to run in

clap_mangen/tests/snapshots/value_env.bash.roff

@@ -15,4 +15,4 @@ May also be specified with the /fBCONFIG_FILE/fR environment variable.
 .RE
 .TP
 /fB/-h/fR, /fB/-/-help/fR
-Print help information
+Print help information (use `/-h` for a summary)

src/builder/command.rs

@@ -102,6 +102,7 @@ pub struct Command {
     subcommand_value_name: Option<Str>,
     subcommand_heading: Option<Str>,
     external_value_parser: Option<super::ValueParser>,
+    long_help_exists: bool,
 }
 
 /// # Basic API
@@ -4124,13 +4125,21 @@ impl Command {
     pub(crate) fn _check_help_and_version(&mut self) {
         debug!("Command::_check_help_and_version:{}", self.name,);
 
+        self.long_help_exists = self.long_help_exists_();
+
         if !self.is_disable_help_flag_set() {
             debug!("Command::_check_help_and_version: Building default --help");
-            let arg = Arg::new(Id::HELP)
+            let mut arg = Arg::new(Id::HELP)
                 .short('h')
                 .long("help")
-                .action(ArgAction::Help)
-                .help("Print help information");
+                .action(ArgAction::Help);
+            if self.long_help_exists {
+                arg = arg
+                    .help("Print help information (use `--help` for more detail)")
+                    .long_help("Print help information (use `-h` for a summary)");
+            } else {
+                arg = arg.help("Print help information");
+            }
             // Avoiding `arg_internal` to not be sensitive to `next_help_heading` /
             // `next_display_order`
             self.args.push(arg);
@@ -4454,10 +4463,10 @@ impl Command {
         debug!(
             "Command::write_help_err: {}, use_long={:?}",
             self.get_display_name().unwrap_or_else(|| self.get_name()),
-            use_long && self.use_long_help(),
+            use_long && self.long_help_exists(),
         );
 
-        use_long = use_long && self.use_long_help();
+        use_long = use_long && self.long_help_exists();
         let usage = Usage::new(self);
 
         let mut styled = StyledStr::new();
@@ -4473,8 +4482,13 @@ impl Command {
         styled
     }
 
-    pub(crate) fn use_long_help(&self) -> bool {
-        debug!("Command::use_long_help");
+    pub(crate) fn long_help_exists(&self) -> bool {
+        debug!("Command::long_help_exists: {}", self.long_help_exists);
+        self.long_help_exists
+    }
+
+    fn long_help_exists_(&self) -> bool {
+        debug!("Command::long_help_exists");
         // In this case, both must be checked. This allows the retention of
         // original formatting, but also ensures that the actual -h or --help
         // specified by the user is sent through. If hide_short_help is not included,
@@ -4545,6 +4559,7 @@ impl Default for Command {
             subcommand_value_name: Default::default(),
             subcommand_heading: Default::default(),
             external_value_parser: Default::default(),
+            long_help_exists: false,
         }
     }
 }

tests/builder/help.rs

@@ -272,7 +272,7 @@ Usage:
     clap-test
 
 Options:
-    -h, --help       Print help information
+    -h, --help       Print help information (use `--help` for more detail)
     -V, --version    Print version information
 
 some text that comes after the help
@@ -288,7 +288,7 @@ Usage:
 
 Options:
     -h, --help
-            Print help information
+            Print help information (use `-h` for a summary)
 
     -V, --version
             Print version information
@@ -494,7 +494,7 @@ Options:
               - second: short help
 
     -h, --help
-            Print help information
+            Print help information (use `-h` for a summary)
 ";
     let cmd = Command::new("test")
         .term_width(67)
@@ -678,7 +678,7 @@ Options:
             A coffeehouse, coffee shop, or café.
 
     -h, --help
-            Print help information
+            Print help information (use `-h` for a summary)
 
     -V, --version
             Print version information
@@ -1021,7 +1021,7 @@ Arguments:
 
 Options:
     -h, --help
-            Print help information
+            Print help information (use `-h` for a summary)
 
     -V, --version
             Print version information
@@ -1743,7 +1743,7 @@ Usage:
     test [OPTIONS] --song <song> --song-volume <volume>
 
 Options:
-    -h, --help       Print help information
+    -h, --help       Print help information (use `--help` for more detail)
     -V, --version    Print version information
 
 OVERRIDE SPECIAL:
@@ -1796,7 +1796,7 @@ Usage:
 
 Options:
     -h, --help
-            Print help information
+            Print help information (use `-h` for a summary)
 
     -V, --version
             Print version information
@@ -1820,7 +1820,7 @@ Usage:
     ctest foo
 
 Options:
-    -h, --help       Print help information
+    -h, --help       Print help information (use `--help` for more detail)
     -V, --version    Print version information
 ";
 
@@ -1847,7 +1847,7 @@ Arguments:
 
 Options:
     -f            
-    -h, --help    Print help information
+    -h, --help    Print help information (use `--help` for more detail)
 ";
 
     let cmd = Command::new("demo")
@@ -2006,7 +2006,7 @@ Options:
             and on, so I'll stop now.
 
     -h, --help
-            Print help information
+            Print help information (use `-h` for a summary)
 ";
 
     let cmd = Command::new("prog").arg(

tests/builder/hidden_args.rs

@@ -40,7 +40,7 @@ Usage:
 
 Options:
     -v, --visible    This text should be visible
-    -h, --help       Print help information
+    -h, --help       Print help information (use `--help` for more detail)
     -V, --version    Print version information
 ";
 
@@ -86,7 +86,7 @@ Options:
             This text should be visible
 
     -h, --help
-            Print help information
+            Print help information (use `-h` for a summary)
 
     -V, --version
             Print version information
@@ -125,7 +125,7 @@ Options:
             This text should be visible
 
     -h, --help
-            Print help information
+            Print help information (use `-h` for a summary)
 
     -V, --version
             Print version information
@@ -164,7 +164,7 @@ Usage:
 Options:
     -c, --config     Some help text describing the --config arg
     -v, --visible    This text should be visible
-    -h, --help       Print help information
+    -h, --help       Print help information (use `--help` for more detail)
     -V, --version    Print version information
 ";
 

tests/derive/help.rs

@@ -414,7 +414,7 @@ Arguments:
 
 Options:
     -h, --help
-            Print help information
+            Print help information (use `-h` for a summary)
 ";
 
     /// Application help

tests/ui/arg_required_else_help_stderr.toml

@@ -14,6 +14,6 @@ Commands:
 
 Options:
         --verbose    log
-    -h, --help       Print help information
+    -h, --help       Print help information (use `--help` for more detail)
     -V, --version    Print version information
 """

tests/ui/h_flag_stdout.toml

@@ -13,7 +13,7 @@ Commands:
 
 Options:
         --verbose    log
-    -h, --help       Print help information
+    -h, --help       Print help information (use `--help` for more detail)
     -V, --version    Print version information
 """
 stderr = ""

tests/ui/help_cmd_stdout.toml

@@ -18,7 +18,7 @@ Options:
             more log
 
     -h, --help
-            Print help information
+            Print help information (use `-h` for a summary)
 
     -V, --version
             Print version information

tests/ui/help_flag_stdout.toml

@@ -18,7 +18,7 @@ Options:
             more log
 
     -h, --help
-            Print help information
+            Print help information (use `-h` for a summary)
 
     -V, --version
             Print version information