fix(clap_mangen): Render optional and multiple values

In #3358 we discovered clapmangen wouldn’t
render optional required_equals values with [=<VALUE>].
After further experimentation it was also found out
that it didn’t appropriately render optional values [VALUE]
 and variadic values <Val>…  as well.
This commit adds a check to the options render section
Where it will add the correct formatting. e.g instead of

—-option=VALUE it will render —option <VALUE>, —option [VALUE]
—-option[=VALUE] or option <VALUE>… and so on

Fixes #3358.

Author: Eric Gumba

clap_mangen/src/render.rs

@@ -99,10 +99,28 @@ pub(crate) fn options(roff: &mut Roff, items: &[&Arg]) {
             (None, None) => vec![],
         };
 
-        if opt.get_num_args().expect("built").takes_values() {
-            if let Some(value) = &opt.get_value_names() {
-                header.push(roman("="));
-                header.push(italic(value.join(" ")));
+        let arg_range = opt.get_num_args().expect("built");
+        if arg_range.takes_values() {
+            if let Some(value_names) = &opt.get_value_names() {
+                let (lhs, rhs) = option_value_markers(opt);
+
+                header.push(roman(lhs));
+                for (i, name) in value_names.iter().enumerate() {
+                    if i > 0 {
+                        header.push(italic(" "));
+                    }
+
+                    let mut val = format!("<{name}>");
+
+                    // If this is the last value and it's variadic, add "..."
+                    let is_last = i == value_names.len() - 1;
+
+                    if is_last && arg_range.max_values() > value_names.len() {
+                        val.push_str("...");
+                    }
+                    header.push(italic(val));
+                }
+                header.push(roman(rhs));
             }
         }
 
@@ -251,6 +269,31 @@ fn markers(required: bool) -> (&'static str, &'static str) {
     }
 }
 
+fn option_value_markers(arg: &Arg) -> (&'static str, &'static str) {
+    let range = arg.get_num_args().expect("built");
+
+    if !range.takes_values() {
+        return ("", ""); // no value, so nothing to render
+    }
+
+    let required = range.min_values() > 0;
+    let require_equals = arg.is_require_equals_set();
+
+    match (required, require_equals) {
+        // Required, no equals: <VALUE>
+        (true, false) => (" ", ""),
+
+        // Optional, no equals: [<VALUE>]
+        (false, false) => (" [", "]"),
+
+        // Optional, with equals: [=<VALUE>]
+        (false, true) => ("[=", "]"),
+
+        // Required, with equals
+        (true, true) => ("=", ""),
+    }
+}
+
 fn short_option(opt: char) -> Inline {
     bold(format!("-{opt}"))
 }

clap_mangen/tests/snapshots/multiple_optional_values.bash.roff

@@ -8,7 +8,7 @@ my\-app
 .SH DESCRIPTION
 .SH OPTIONS
 .TP
-\fB\-\-config\fR=\fIFILE1 FILE2\fR
+\fB\-\-config\fR [\fI<FILE1>\fR\fI \fR\fI<FILE2>\fR]
 Optional config file
 .TP
 \fB\-h\fR, \fB\-\-help\fR

clap_mangen/tests/snapshots/optional_value.bash.roff

@@ -8,7 +8,7 @@ my\-app
 .SH DESCRIPTION
 .SH OPTIONS
 .TP
-\fB\-\-config\fR=\fIFILE\fR
+\fB\-\-config\fR [\fI<FILE>\fR]
 Optional config file
 .TP
 \fB\-h\fR, \fB\-\-help\fR

clap_mangen/tests/snapshots/optional_with_required_equals_value.bash.roff

@@ -8,7 +8,7 @@ my\-app
 .SH DESCRIPTION
 .SH OPTIONS
 .TP
-\fB\-\-config\fR=\fIFILE\fR
+\fB\-\-config\fR[=\fI<FILE>\fR]
 Optional config file
 .TP
 \fB\-h\fR, \fB\-\-help\fR

clap_mangen/tests/snapshots/value_with_required_equals.bash.roff

@@ -8,7 +8,7 @@ my\-app
 .SH DESCRIPTION
 .SH OPTIONS
 .TP
-\fB\-\-config\fR=\fIFILE\fR
+\fB\-\-config\fR=\fI<FILE>\fR
 Optional config file
 .TP
 \fB\-h\fR, \fB\-\-help\fR

clap_mangen/tests/snapshots/variadic_values.bash.roff

@@ -8,7 +8,7 @@ my\-app
 .SH DESCRIPTION
 .SH OPTIONS
 .TP
-\fB\-\-config\fR=\fIFILE1 FILE2\fR
+\fB\-\-config\fR \fI<FILE1>\fR\fI \fR\fI<FILE2>...\fR
 Optional config file
 .TP
 \fB\-h\fR, \fB\-\-help\fR