feat(mangen): support flatten_help

The `flatten_help` argument combines all subcommands on a single page.
Until now this wasn't supported for `mangen`. With this command the
sections `SYNOPSIS` as well as `(SUB)COMMANDS` are changed to imitate
the style of `git stash --help`.

Signed-off-by: Paul Spooren <[email protected]>

Author: aparcar

clap_mangen/src/lib.rs

@@ -221,7 +221,14 @@ impl Man {
 
     fn _render_synopsis_section(&self, roff: &mut Roff) {
         roff.control("SH", ["SYNOPSIS"]);
-        render::synopsis(roff, &self.cmd);
+        if self.cmd.is_flatten_help_set() {
+            for sc in self.cmd.get_subcommands() {
+                render::synopsis(roff, sc);
+                roff.control("br", []);
+            }
+        } else {
+            render::synopsis(roff, &self.cmd);
+        }
     }
 
     /// Render the DESCRIPTION section into the writer.
@@ -251,7 +258,11 @@ impl Man {
     /// Render the SUBCOMMANDS section into the writer.
     pub fn render_subcommands_section(&self, w: &mut dyn Write) -> Result<(), std::io::Error> {
         let mut roff = Roff::default();
-        self._render_subcommands_section(&mut roff);
+        if self.cmd.is_flatten_help_set() {
+            self._render_flat_subcommands_section(&mut roff);
+        } else {
+            self._render_subcommands_section(&mut roff);
+        }
         roff.to_writer(w)
     }
 
@@ -261,6 +272,11 @@ impl Man {
         render::subcommands(roff, &self.cmd, &self.section);
     }
 
+    fn _render_flat_subcommands_section(&self, roff: &mut Roff) {
+        roff.control("SH", ["COMMANDS"]);
+        render::flat_subcommands(roff, &self.cmd, &self.section);
+    }
+
     /// Render the EXTRA section into the writer.
     pub fn render_extra_section(&self, w: &mut dyn Write) -> Result<(), std::io::Error> {
         let mut roff = Roff::default();

clap_mangen/src/render.rs

@@ -74,7 +74,7 @@ pub(crate) fn synopsis(roff: &mut Roff, cmd: &clap::Command) {
         line.push(roman(" "));
     }
 
-    if cmd.has_subcommands() {
+    if cmd.has_subcommands() && !cmd.is_flatten_help_set() {
         let (lhs, rhs) = subcommand_markers(cmd);
         line.push(roman(lhs));
         line.push(italic(
@@ -220,6 +220,71 @@ pub(crate) fn subcommands(roff: &mut Roff, cmd: &clap::Command, section: &str) {
     }
 }
 
+pub(crate) fn flat_subcommands(roff: &mut Roff, cmd: &clap::Command, section: &str) {
+    for sub in cmd.get_subcommands().filter(|s| !s.is_hide_set()) {
+        roff.control("TP", []);
+
+        let name = sub.get_name();
+        let mut line = vec![bold(name), roman(" ")];
+
+        for opt in sub.get_arguments().filter(|i| !i.is_hide_set()) {
+            if opt.get_short() == Some('h') || opt.get_long() == Some("help") {
+                continue;
+            }
+            let (lhs, rhs) = option_markers(opt);
+            match (opt.get_short(), opt.get_long()) {
+                (Some(short), Some(long)) => {
+                    line.push(roman(lhs));
+                    line.push(bold(format!("-{short}")));
+                    line.push(roman("|"));
+                    line.push(bold(format!("--{long}",)));
+                    line.push(roman(rhs));
+                }
+                (Some(short), None) => {
+                    line.push(roman(lhs));
+                    line.push(bold(format!("-{short} ")));
+                    line.push(roman(rhs));
+                }
+                (None, Some(long)) => {
+                    line.push(roman(lhs));
+                    line.push(bold(format!("--{long}")));
+                    line.push(roman(rhs));
+                }
+                (None, None) => continue,
+            };
+
+            if matches!(opt.get_action(), ArgAction::Count) {
+                line.push(roman("..."));
+            }
+            line.push(roman(" "));
+        }
+
+        for arg in sub.get_positionals() {
+            let (lhs, rhs) = option_markers(arg);
+            line.push(roman(lhs));
+            if let Some(value) = arg.get_value_names() {
+                line.push(italic(value.join(" ")));
+            } else {
+                line.push(italic(arg.get_id().as_str()));
+            }
+            line.push(roman(rhs));
+            line.push(roman(" "));
+        }
+
+        if let Some(about) = sub.get_long_about().or_else(|| sub.get_about()) {
+            line.push(roman("\n"));
+            line.push(roman(about.to_string()));
+        }
+
+        if let Some(after_help) = sub.get_after_help() {
+            line.push(roman("\n"));
+            line.push(roman(after_help.to_string()));
+        }
+
+        roff.text(line);
+    }
+}
+
 pub(crate) fn version(cmd: &clap::Command) -> String {
     format!(
         "v{}",