fix: Show possible values in generated man file

This adds feature parity for mangen with the standard help output. Users
will now see the list of possible values for value arguments.

One change that was made to make this possible was adding the method
`get_possible_values` to the public API for an arg. I tried to think of
a way to get around this, but because this is the interface that the
help generation uses, and it is part of the crate public interface
I thing adding it as a part of the public API might be for the best.

fixes: clap-rs#3861

clap_mangen/src/render.rs

@@ -106,11 +106,25 @@ pub(crate) fn options(roff: &mut Roff, cmd: &clap::Command) {
             header.push(roman(&defs));
         }
 
+
         let mut body = vec![];
         if let Some(help) = opt.get_long_help().or_else(|| opt.get_help()) {
             body.push(roman(help));
         }
 
+        let possibles = &opt.get_possible_values();
+        if !possibles.is_empty() {
+            let pos_options: Vec<&str> = possibles
+                .iter()
+                .filter(|pos| !pos.is_hide_set())
+                .map(|pos| pos.get_name())
+                .collect();
+            body.push(Inline::LineBreak);
+            body.push(roman("[possible values: "));
+            body.push(italic(pos_options.join(", ")));
+            body.push(roman("]"));
+        }
+
         roff.control("TP", []);
         roff.text(header);
         roff.text(body);

clap_mangen/tests/snapshots/value_hint.bash.roff

@@ -9,7 +9,8 @@ my/-app
 .SH OPTIONS
 .TP
 /fB/-/-choice/fR
-
+.br
+[possible values: /fIbash, fish, zsh/fR]
 .TP
 /fB/-/-unknown/fR
 

src/builder/arg.rs

@@ -3659,7 +3659,9 @@ impl<'help> Arg<'help> {
         Some(longs)
     }
 
-    pub(crate) fn get_possible_values(&self) -> Vec<PossibleValue> {
+    /// Get the names of possible values for this argument. Only useful for user
+    /// facing applications, such as building help messages or man files
+    pub fn get_possible_values(&self) -> Vec<PossibleValue> {
         if !self.is_takes_value_set() {
             vec![]
         } else {
@@ -3680,6 +3682,19 @@ impl<'help> Arg<'help> {
         }
     }
 
+    // Get the names of possible values for this argument
+    // pub fn get_possible_value_names(&self) -> Option<Vec<&'help str>> {
+        // let possible_values = self.get_possible_values();
+        // if !possible_values.is_empty() {
+            // let possible_options: Vec<&str> = possible_values.iter().map(|pos| pos.get_name()).collect();
+            // Some(possible_options)
+        // }
+        // else {
+            // None
+        // }
+
+    // }
+
     /// Get the number of values for this argument.
     #[inline]
     pub fn get_num_args(&self) -> Option<ValueRange> {