feat(mangen): Separate options based on help_heading

clap_mangen/src/lib.rs

@@ -244,8 +244,38 @@ impl Man {
     }
 
     fn _render_options_section(&self, roff: &mut Roff) {
-        roff.control("SH", ["OPTIONS"]);
-        render::options(roff, &self.cmd);
+        let help_headings = self
+            .cmd
+            .get_arguments()
+            .filter_map(|arg| arg.get_help_heading())
+            .fold(vec![], |mut acc, header| {
+                if !acc.contains(&header) {
+                    acc.push(header);
+                }
+
+                acc
+            });
+
+        let (args, mut args_with_heading) =
+            self.cmd
+                .get_arguments()
+                .filter(|a| !a.is_hide_set())
+                .partition::<Vec<_>, _>(|a| a.get_help_heading().is_none());
+
+        if !args.is_empty() {
+            roff.control("SH", ["OPTIONS"]);
+            render::options(roff, &args);
+        }
+
+        for heading in help_headings {
+            let args;
+            (args, args_with_heading) = args_with_heading
+                .into_iter()
+                .partition(|&a| a.get_help_heading() == Some(heading));
+
+            roff.control("SH", [heading.to_uppercase().as_str()]);
+            render::options(roff, &args);
+        }
     }
 
     /// Render the SUBCOMMANDS section into the writer.

clap_mangen/src/render.rs

@@ -88,9 +88,7 @@ pub(crate) fn synopsis(roff: &mut Roff, cmd: &clap::Command) {
     roff.text(line);
 }
 
-pub(crate) fn options(roff: &mut Roff, cmd: &clap::Command) {
-    let items: Vec<_> = cmd.get_arguments().filter(|i| !i.is_hide_set()).collect();
-
+pub(crate) fn options(roff: &mut Roff, items: &[&Arg]) {
     for opt in items.iter().filter(|a| !a.is_positional()) {
         let mut header = match (opt.get_short(), opt.get_long()) {
             (Some(short), Some(long)) => {

clap_mangen/tests/snapshots/help_headings.bash.roff

@@ -0,0 +1,25 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH my-app 1  "my-app " 
+.SH NAME
+my\-app
+.SH SYNOPSIS
+\fBmy\-app\fR [\fB\-r\fR|\fB\-\-recursive\fR] [\fB\-f\fR|\fB\-\-force\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIcolor\fR] 
+.SH DESCRIPTION
+.SH OPTIONS
+.TP
+\fB\-r\fR, \fB\-\-recursive\fR
+
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.SH "CONFLICT OPTIONS"
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+
+.SH "GLOBAL OPTIONS"
+.TP
+[\fIcolor\fR]
+
+.br
+[\fIpossible values: \fRalways, never, auto]

clap_mangen/tests/testsuite/common.rs

@@ -323,3 +323,26 @@ pub(crate) fn value_name_without_arg(name: &'static str) -> clap::Command {
             .action(clap::ArgAction::SetTrue),
     )
 }
+
+pub(crate) fn help_headings(name: &'static str) -> clap::Command {
+    clap::Command::new(name)
+        .arg(
+            clap::Arg::new("recursive")
+                .long("recursive")
+                .short('r')
+                .action(clap::ArgAction::SetTrue),
+        )
+        .next_help_heading("Conflict Options")
+        .arg(
+            clap::Arg::new("force")
+                .long("force")
+                .short('f')
+                .action(clap::ArgAction::SetTrue),
+        )
+        .next_help_heading("Global Options")
+        .arg(
+            clap::Arg::new("color")
+                .global(true)
+                .value_parser(["always", "never", "auto"]),
+        )
+}

clap_mangen/tests/testsuite/roff.rs

@@ -96,6 +96,13 @@ fn sub_subcommands_help() {
     }
 }
 
+#[test]
+fn help_headings() {
+    let name = "my-app";
+    let cmd = common::help_headings(name);
+    common::assert_matches(snapbox::file!["../snapshots/help_headings.bash.roff"], cmd);
+}
+
 #[test]
 fn value_name_without_arg() {
     let name = "my-app";