feat: Added {before/after}_help_long to App struct, closed clap-rs#1903

src/build/app/mod.rs

@@ -79,7 +79,9 @@ pub struct App<'b> {
     pub(crate) about: Option<&'b str>,
     pub(crate) long_about: Option<&'b str>,
     pub(crate) before_help: Option<&'b str>,
+    pub(crate) before_help_long: Option<&'b str>,
     pub(crate) after_help: Option<&'b str>,
+    pub(crate) after_help_long: Option<&'b str>,
     pub(crate) aliases: Vec<(&'b str, bool)>, // (name, visible)
     pub(crate) usage_str: Option<&'b str>,
     pub(crate) usage: Option<String>,
@@ -340,6 +342,25 @@ impl<'b> App<'b> {
         self
     }
 
+    /// Adds additional help information to be displayed in addition to auto-generated help. This
+    /// information is displayed **after** the auto-generated help information and is meant to be
+    /// more verbose than `after_help`. This is often used for man pages.. This is often used
+    /// to describe how to use the arguments, or caveats to be noted in man pages.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use clap::App;
+    /// App::new("myprog")
+    ///     .after_help_long("Does really amazing things to great people... but be careful with -R, \
+    ///                      like, for real, be careful with this!")
+    /// # ;
+    /// ```
+    pub fn after_help_long<S: Into<&'b str>>(mut self, help: S) -> Self {
+        self.after_help_long = Some(help.into());
+        self
+    }
+
     /// Adds additional help information to be displayed in addition to auto-generated help. This
     /// information is displayed **before** the auto-generated help information. This is often used
     /// for header information.
@@ -357,6 +378,23 @@ impl<'b> App<'b> {
         self
     }
 
+    /// Adds additional help information to be displayed in addition to auto-generated help. This
+    /// information is displayed **before** the auto-generated help information and is meant to be more
+    /// verbose than `before_help`. This is often used for header information in man pages.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use clap::App;
+    /// App::new("myprog")
+    ///     .before_help_long("Some verbose and long info I'd like to appear before the help info")
+    /// # ;
+    /// ```
+    pub fn before_help_long<S: Into<&'b str>>(mut self, help: S) -> Self {
+        self.before_help_long = Some(help.into());
+        self
+    }
+
     /// Sets a string of the version number to be displayed when displaying version or help
     /// information with `-V`.
     ///
@@ -2091,7 +2129,9 @@ impl<'a> From<&'a Yaml> for App<'a> {
         yaml_str!(a, yaml, bin_name);
         yaml_str!(a, yaml, about);
         yaml_str!(a, yaml, before_help);
+        yaml_str!(a, yaml, before_help_long);
         yaml_str!(a, yaml, after_help);
+        yaml_str!(a, yaml, after_help_long);
         yaml_str!(a, yaml, alias);
         yaml_str!(a, yaml, visible_alias);
 

src/output/help.rs

@@ -820,7 +820,23 @@ impl<'b, 'c, 'd, 'w> Help<'b, 'c, 'd, 'w> {
     /// Writes default help for a Parser Object to the wrapped stream.
     pub(crate) fn write_default_help(&mut self) -> ClapResult<()> {
         debug!("Help::write_default_help");
-        if let Some(h) = self.parser.app.before_help {
+        if self.use_long {
+            if let Some(h) = self
+                .parser
+                .app
+                .before_help_long
+                .or_else(|| self.parser.app.before_help)
+            {
+                self.write_before_after_help(h)?;
+                self.none("\n\n")?;
+            }
+        }
+        else if let Some(h) = self
+            .parser
+            .app
+            .before_help
+            .or_else(|| self.parser.app.before_help_long)
+        {
             self.write_before_after_help(h)?;
             self.none("\n\n")?;
         }
@@ -867,7 +883,25 @@ impl<'b, 'c, 'd, 'w> Help<'b, 'c, 'd, 'w> {
             self.write_all_args()?;
         }
 
-        if let Some(h) = self.parser.app.after_help {
+        if self.use_long {
+            if let Some(h) = self
+                .parser
+                .app
+                .after_help_long
+                .or_else(|| self.parser.app.after_help)
+            {
+                if flags || opts || pos || subcmds {
+                    self.none("\n\n")?;
+                }
+                self.write_before_after_help(h)?;
+            }
+        }
+        else if let Some(h) = self
+            .parser
+            .app
+            .after_help
+            .or_else(|| self.parser.app.after_help_long)
+        {
             if flags || opts || pos || subcmds {
                 self.none("\n\n")?;
             }

tests/help.rs

@@ -102,6 +102,20 @@ FLAGS:
 
 some text that comes after the help";
 
+static AFTER_HELP_LONG: &str = "some longer text that comes before the help
+
+clap-test v1.4.8
+tests clap library
+
+USAGE:
+    clap-test
+
+FLAGS:
+    -h, --help       Prints help information
+    -V, --version    Prints version information
+
+some longer text that comes after the help";
+
 static HIDDEN_ARGS: &str = "prog 1.0
 
 USAGE:
@@ -722,6 +736,21 @@ fn after_and_before_help_output() {
     ));
 }
 
+#[test]
+fn after_and_before_help_long_output() {
+    let app = App::new("clap-test")
+        .version("v1.4.8")
+        .about("tests clap library")
+        .before_help_long("some longer text that comes before the help")
+        .after_help_long("some longer text that comes after the help");
+    assert!(utils::compare_output(
+        app,
+        "clap-test --help",
+        AFTER_HELP_LONG,
+        false
+    ));
+}
+
 #[test]
 fn multi_level_sc_help() {
     let app = App::new("ctest").subcommand(