fix: Compatibility with help2man

clap_derive/tests/doc-comments-help.rs

@@ -60,7 +60,7 @@ fn empty_line_in_doc_comment_is_double_linefeed() {
     struct LoremIpsum {}
 
     let help = get_long_help::<LoremIpsum>();
-    assert!(help.starts_with("lorem-ipsum \nFoo.\n\nBar\n\nUSAGE:"));
+    assert!(help.starts_with("lorem-ipsum \n\nFoo.\n\nBar\n\nUSAGE:"));
 }
 
 #[test]

src/build/app/mod.rs

@@ -847,9 +847,11 @@ impl<'help> App<'help> {
     ///   * `{version}`             - Version number.
     ///   * `{author}`              - Author information.
     ///   * `{author-with-newline}` - Author followed by `\n`.
+    ///   * `{author-section}`      - Author preceded and followed by `\n`.
     ///   * `{about}`               - General description (from [`App::about`] or
     ///                               [`App::long_about`]).
     ///   * `{about-with-newline}`  - About followed by `\n`.
+    ///   * `{about-section}`       - About preceded and followed by '\n'.
     ///   * `{usage-heading}`       - Automatically generated usage heading.
     ///   * `{usage}`               - Automatically generated or given usage string.
     ///   * `{all-args}`            - Help for all arguments (options, flags, positional

src/output/help.rs

@@ -51,15 +51,17 @@ pub(crate) struct Help<'help, 'app, 'parser, 'writer> {
 impl<'help, 'app, 'parser, 'writer> Help<'help, 'app, 'parser, 'writer> {
     const DEFAULT_TEMPLATE: &'static str = "\
         {before-help}{bin} {version}\n\
-        {author-with-newline}{about-with-newline}\n\
+        {author-section}\
+        {about-section}\n\
         {usage-heading}\n    {usage}\n\
         \n\
         {all-args}{after-help}\
     ";
 
     const DEFAULT_NO_ARGS_TEMPLATE: &'static str = "\
         {before-help}{bin} {version}\n\
-        {author-with-newline}{about-with-newline}\n\
+        {author-section}\
+        {about-section}\n\
         {usage-heading}\n    {usage}{after-help}\
     ";
 
@@ -642,30 +644,48 @@ impl<'help, 'app, 'parser, 'writer> Help<'help, 'app, 'parser, 'writer> {
         prefix.to_string() + &spec_vals.join(" ")
     }
 
-    fn write_about(&mut self, new_line: bool) -> io::Result<()> {
+    fn write_about(&mut self, before_new_line: bool, after_new_line: bool) -> io::Result<()> {
         let about = if self.use_long {
             self.parser.app.long_about.or(self.parser.app.about)
         } else {
             self.parser.app.about
         };
         if let Some(output) = about {
+            if before_new_line {
+                self.none("\n")?;
+            }
             self.none(text_wrapper(output, self.term_w))?;
-            if new_line {
+            if after_new_line {
                 self.none("\n")?;
             }
         }
         Ok(())
     }
 
-    fn write_author(&mut self, new_line: bool) -> io::Result<()> {
+    fn write_author(&mut self, before_new_line: bool, after_new_line: bool) -> io::Result<()> {
         if let Some(author) = self.parser.app.author {
+            if before_new_line {
+                self.none("\n")?;
+            }
             self.none(text_wrapper(author, self.term_w))?;
-            if new_line {
+            if after_new_line {
                 self.none("\n")?;
             }
         }
         Ok(())
     }
+
+    fn write_version(&mut self) -> io::Result<()> {
+        let version = if self.use_long {
+            self.parser.app.long_version.or(self.parser.app.version)
+        } else {
+            self.parser.app.version
+        };
+        if let Some(output) = version {
+            self.none(text_wrapper(output, self.term_w))?;
+        }
+        Ok(())
+    }
 }
 
 /// Methods to write a single subcommand
@@ -988,21 +1008,25 @@ impl<'help, 'app, 'parser, 'writer> Help<'help, 'app, 'parser, 'writer> {
                         self.write_bin_name()?;
                     }
                     "version" => {
-                        if let Some(s) = self.parser.app.version {
-                            self.none(s)?;
-                        }
+                        self.write_version()?;
                     }
                     "author" => {
-                        self.write_author(false)?;
+                        self.write_author(false, false)?;
                     }
                     "author-with-newline" => {
-                        self.write_author(true)?;
+                        self.write_author(false, true)?;
+                    }
+                    "author-section" => {
+                        self.write_author(true, true)?;
                     }
                     "about" => {
-                        self.write_about(false)?;
+                        self.write_about(false, false)?;
                     }
                     "about-with-newline" => {
-                        self.write_about(true)?;
+                        self.write_about(false, true)?;
+                    }
+                    "about-section" => {
+                        self.write_about(true, true)?;
                     }
                     "usage-heading" => {
                         self.warning("USAGE:")?;

tests/app_from_crate.rs

@@ -1,7 +1,9 @@
 use clap::{app_from_crate, ErrorKind};
 
 static EVERYTHING: &str = "clap {{version}}
+
 Kevin K. <kbknapp@gmail.com>:Clap Maintainers
+
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
 USAGE:

tests/app_settings.rs

@@ -38,7 +38,9 @@ OPTIONS:
     -o, --opt=<FILE>    some";
 
 static UNIFIED_HELP: &str = "test 1.3
+
 Kevin K.
+
 tests stuff
 
 USAGE:
@@ -54,7 +56,9 @@ OPTIONS:
     -V, --version         Prints version information";
 
 static SKIP_POS_VALS: &str = "test 1.3
+
 Kevin K.
+
 tests stuff
 
 USAGE:

tests/arg_aliases.rs

@@ -3,6 +3,7 @@ mod utils;
 use clap::{App, Arg};
 
 static SC_VISIBLE_ALIAS_HELP: &str = "ct-test 1.2
+
 Some help
 
 USAGE:
@@ -17,6 +18,7 @@ OPTIONS:
     -o, --opt <opt>    [aliases: visible]";
 
 static SC_INVISIBLE_ALIAS_HELP: &str = "ct-test 1.2
+
 Some help
 
 USAGE:

tests/arg_aliases_short.rs

@@ -3,6 +3,7 @@ mod utils;
 use clap::{App, Arg};
 
 static SC_VISIBLE_ALIAS_HELP: &str = "ct-test 1.2
+
 Some help
 
 USAGE:
@@ -17,6 +18,7 @@ OPTIONS:
     -o, --opt <opt>    [short aliases: v]";
 
 static SC_INVISIBLE_ALIAS_HELP: &str = "ct-test 1.2
+
 Some help
 
 USAGE:

tests/cargo.rs

@@ -1,6 +1,7 @@
 use clap::{crate_authors, crate_description, crate_name, crate_version, App, ErrorKind};
 
 static DESCRIPTION_ONLY: &str = "prog 1
+
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
 USAGE:
@@ -12,6 +13,7 @@ FLAGS:
 ";
 
 static AUTHORS_ONLY: &str = "prog 1
+
 Kevin K. <kbknapp@gmail.com>:Clap Maintainers
 
 USAGE:

tests/flag_subcommands.rs

@@ -408,6 +408,7 @@ fn flag_subcommand_long_infer_exact_match() {
 }
 
 static FLAG_SUBCOMMAND_HELP: &str = "pacman-query 
+
 Query the package database.
 
 USAGE:
@@ -462,6 +463,7 @@ fn flag_subcommand_long_short_normal_usage_string() {
 }
 
 static FLAG_SUBCOMMAND_NO_SHORT_HELP: &str = "pacman-query 
+
 Query the package database.
 
 USAGE:
@@ -515,6 +517,7 @@ fn flag_subcommand_long_normal_usage_string() {
 }
 
 static FLAG_SUBCOMMAND_NO_LONG_HELP: &str = "pacman-query 
+
 Query the package database.
 
 USAGE:

tests/help.rs

@@ -3,7 +3,9 @@ mod utils;
 use clap::{clap_app, App, AppSettings, Arg, ArgGroup, ArgSettings, ErrorKind};
 
 static REQUIRE_DELIM_HELP: &str = "test 1.3
+
 Kevin K.
+
 tests stuff
 
 USAGE:
@@ -17,7 +19,9 @@ OPTIONS:
     -f, --fake <some>:<val>    some help";
 
 static HELP: &str = "clap-test v1.4.8
+
 Kevin K. <kbknapp@gmail.com>
+
 tests clap library
 
 USAGE:
@@ -91,6 +95,7 @@ SUBCOMMANDS:
 static AFTER_HELP: &str = "some text that comes before the help
 
 clap-test v1.4.8
+
 tests clap library
 
 USAGE:
@@ -105,6 +110,7 @@ some text that comes after the help";
 static AFTER_LONG_HELP: &str = "some longer text that comes before the help
 
 clap-test v1.4.8
+
 tests clap library
 
 USAGE:
@@ -133,7 +139,9 @@ OPTIONS:
     -o, --opt <FILE>    tests options";
 
 static SC_HELP: &str = "clap-test-subcmd 0.1
+
 Kevin K. <kbknapp@gmail.com>
+
 tests subcommands
 
 USAGE:
@@ -194,7 +202,9 @@ FLAGS:
     -V, --version    Prints version information";
 
 static MULTI_SC_HELP: &str = "ctest-subcmd-multi 0.1
+
 Kevin K. <kbknapp@gmail.com>
+
 tests subcommands
 
 USAGE:
@@ -317,7 +327,9 @@ OPTIONS:
                              Gaussian, Lanczos3]";
 
 static ISSUE_702: &str = "myapp 1.0
+
 foo
+
 bar
 
 USAGE:
@@ -338,8 +350,10 @@ OPTIONS:
 
 static ISSUE_777: &str = "A app with a crazy very long long
 long name hahaha 1.0
+
 Some Very Long Name and crazy long
 email <email@server.com>
+
 Show how the about text is not
 wrapped
 
@@ -514,7 +528,9 @@ FLAGS:
     -V, --version    Prints version information";
 
 static LONG_ABOUT: &str = "myapp 1.0
+
 foo
+
 something really really long, with
 multiple lines of text
 that should be displayed
@@ -584,7 +600,9 @@ OPTIONS:
     -p, --pos <VAL>      Some vals [possible values: fast, slow]";
 
 static CUSTOM_HELP_SECTION: &str = "blorp 1.4
+
 Will M.
+
 does stuff
 
 USAGE:
@@ -1806,7 +1824,9 @@ fn custom_headers_headers() {
 }
 
 static MULTIPLE_CUSTOM_HELP_SECTIONS: &str = "blorp 1.4
+
 Will M.
+
 does stuff
 
 USAGE:
@@ -1884,6 +1904,7 @@ fn multiple_custom_help_headers() {
 }
 
 static ISSUE_897: &str = "ctest-foo 0.1
+
 Long about foo
 
 USAGE:
@@ -1913,6 +1934,7 @@ fn show_long_about_issue_897() {
 }
 
 static ISSUE_897_SHORT: &str = "ctest-foo 0.1
+
 About foo
 
 USAGE: