Merge pull request #6217 from epage/man

fix(man): Always show possible values as a list

Author: epage

clap_mangen/src/render.rs

@@ -193,33 +193,22 @@ pub(crate) fn options(roff: &mut Roff, items: &[&Arg]) {
 }
 
 fn possible_options(roff: &mut Roff, arg: &Arg, arg_help_written: bool) {
-    if let Some((possible_values_text, with_help)) = get_possible_values(arg) {
+    if let Some(possible_values_text) = get_possible_values(arg) {
         if arg_help_written {
             // It looks nice to have a separation between the help and the values
             roff.text([Inline::LineBreak]);
         }
-        if with_help {
-            roff.text([Inline::LineBreak, italic("Possible values:")]);
-
-            // Need to indent twice to get it to look right, because .TP heading indents, but
-            // that indent doesn't Carry over to the .IP for the bullets. The standard shift
-            // size is 7 for terminal devices
-            roff.control("RS", ["14"]);
-            for line in possible_values_text {
-                roff.control("IP", ["\\(bu", "2"]);
-                roff.text([roman(line)]);
-            }
-            roff.control("RE", []);
-        } else {
-            let possible_value_text: Vec<Inline> = vec![
-                Inline::LineBreak,
-                roman("["),
-                italic("possible values: "),
-                roman(possible_values_text.join(", ")),
-                roman("]"),
-            ];
-            roff.text(possible_value_text);
+        roff.text([Inline::LineBreak, italic("Possible values:")]);
+
+        // Need to indent twice to get it to look right, because .TP heading indents, but
+        // that indent doesn't Carry over to the .IP for the bullets. The standard shift
+        // size is 7 for terminal devices
+        roff.control("RS", ["14"]);
+        for line in possible_values_text {
+            roff.control("IP", ["\\(bu", "2"]);
+            roff.extend([line]);
         }
+        roff.control("RE", []);
     }
 }
 
@@ -357,7 +346,7 @@ fn option_default_values(opt: &Arg) -> Option<String> {
     None
 }
 
-fn get_possible_values(arg: &Arg) -> Option<(Vec<String>, bool)> {
+fn get_possible_values(arg: &Arg) -> Option<Vec<Roff>> {
     if arg.is_hide_possible_values_set() {
         return None;
     }
@@ -372,21 +361,22 @@ fn get_possible_values(arg: &Arg) -> Option<(Vec<String>, bool)> {
     None
 }
 
-fn format_possible_values(possibles: &Vec<&clap::builder::PossibleValue>) -> (Vec<String>, bool) {
+fn format_possible_values(possibles: &Vec<&clap::builder::PossibleValue>) -> Vec<Roff> {
     let mut lines = vec![];
-    let with_help = possibles.iter().any(|p| p.get_help().is_some());
-    if with_help {
-        for value in possibles {
-            let val_name = value.get_name();
-            match value.get_help() {
-                Some(help) => lines.push(format!("{val_name}: {help}")),
-                None => lines.push(val_name.to_string()),
+    for value in possibles {
+        let mut roff = Roff::default();
+        let val_name = value.get_name();
+        match value.get_help() {
+            Some(help) => {
+                roff.text([roman(format!("{val_name}: {help}"))]);
+            }
+            None => {
+                roff.text([roman(val_name.to_owned())]);
             }
         }
-    } else {
-        lines.append(&mut possibles.iter().map(|p| p.get_name().to_string()).collect());
+        lines.push(roff);
     }
-    (lines, with_help)
+    lines
 }
 
 fn subcommand_sort_key(command: &clap::Command) -> (usize, &str) {

clap_mangen/tests/snapshots/feature_sample.bash.roff

@@ -24,7 +24,13 @@ some input file
 [\fIchoice\fR]
 
 .br
-[\fIpossible values: \fRfirst, second]
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+first
+.IP \(bu 2
+second
+.RE
 .SH SUBCOMMANDS
 .TP
 my\-app\-test(1)

clap_mangen/tests/snapshots/help_headings.bash.roff

@@ -22,4 +22,12 @@ Print help
 [\fIcolor\fR]
 
 .br
-[\fIpossible values: \fRalways, never, auto]
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+always
+.IP \(bu 2
+never
+.IP \(bu 2
+auto
+.RE

clap_mangen/tests/snapshots/possible_values.bash.roff

@@ -11,7 +11,15 @@ my\-app
 \fB\-\-choice\fR
 
 .br
-[\fIpossible values: \fRbash, fish, zsh]
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+bash
+.IP \(bu 2
+fish
+.IP \(bu 2
+zsh
+.RE
 .TP
 \fB\-\-method\fR
 

clap_mangen/tests/snapshots/special_commands.bash.roff

@@ -24,7 +24,13 @@ some input file
 [\fIchoice\fR]
 
 .br
-[\fIpossible values: \fRfirst, second]
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+first
+.IP \(bu 2
+second
+.RE
 .SH SUBCOMMANDS
 .TP
 my\-app\-test(1)

clap_mangen/tests/snapshots/sub_subcommands.bash.roff

@@ -24,7 +24,13 @@ some input file
 [\fIchoice\fR]
 
 .br
-[\fIpossible values: \fRfirst, second]
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+first
+.IP \(bu 2
+second
+.RE
 .SH SUBCOMMANDS
 .TP
 my\-app\-test(1)

clap_mangen/tests/snapshots/value_hint.bash.roff

@@ -11,7 +11,15 @@ my\-app
 \fB\-\-choice\fR
 
 .br
-[\fIpossible values: \fRbash, fish, zsh]
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+bash
+.IP \(bu 2
+fish
+.IP \(bu 2
+zsh
+.RE
 .TP
 \fB\-\-unknown\fR