fix(man): Forward, rather than ignore, user styling

clap_mangen/Cargo.toml

@@ -34,15 +34,18 @@ bench = false
 
 [dependencies]
 roff = "0.2.1"
+anstyle-roff = { version = "0.3.8", optional = true }
 clap = { path = "../", version = "4.0.0", default-features = false, features = ["std", "env"] }
 
 [dev-dependencies]
 snapbox = { version = "0.6.0", features = ["diff"] }
-clap = { path = "../", version = "4.0.0", default-features = false, features = ["std", "help"] }
+clap = { path = "../", version = "4.0.0", default-features = false, features = ["std", "help", "string", "color"] }
 automod = "1.0.14"
+anstyle = "1.0.11"
 
 [features]
 default = []
+ansi = ["dep:anstyle-roff", "clap/color"]
 debug = ["clap/debug"]
 
 [lints]

clap_mangen/src/render.rs

@@ -23,7 +23,7 @@ pub(crate) fn description(roff: &mut Roff, cmd: &clap::Command) {
             if line.trim().is_empty() {
                 roff.control("PP", []);
             } else {
-                roff.text([roman(line)]);
+                roff.extend([anstyle_roff::to_roff(line)]);
             }
         }
     }
@@ -140,7 +140,7 @@ pub(crate) fn options(roff: &mut Roff, items: &[&Arg]) {
         let mut arg_help_written = false;
         if let Some(help) = option_help(opt) {
             arg_help_written = true;
-            body.push(roman(help.to_string()));
+            body.push(roman(help.ansi().to_string()));
         }
 
         roff.control("TP", []);
@@ -174,7 +174,7 @@ pub(crate) fn options(roff: &mut Roff, items: &[&Arg]) {
         let mut body = vec![];
         let mut arg_help_written = false;
         if let Some(help) = option_help(pos) {
-            body.push(roman(help.to_string()));
+            body.push(roman(help.ansi().to_string()));
             arg_help_written = true;
         }
 
@@ -229,7 +229,7 @@ pub(crate) fn subcommands(roff: &mut Roff, cmd: &clap::Command, section: &str) {
 
         if let Some(about) = sub.get_about().or_else(|| sub.get_long_about()) {
             for line in about.to_string().lines() {
-                roff.text([roman(line)]);
+                roff.extend([anstyle_roff::to_roff(line)]);
             }
         }
     }
@@ -247,7 +247,7 @@ pub(crate) fn version(cmd: &clap::Command) -> String {
 pub(crate) fn after_help(roff: &mut Roff, cmd: &clap::Command) {
     if let Some(about) = cmd.get_after_long_help().or_else(|| cmd.get_after_help()) {
         for line in about.to_string().lines() {
-            roff.text([roman(line)]);
+            roff.extend([anstyle_roff::to_roff(line)]);
         }
     }
 }
@@ -368,7 +368,8 @@ fn format_possible_values(possibles: &Vec<&clap::builder::PossibleValue>) -> Vec
         let val_name = value.get_name();
         match value.get_help() {
             Some(help) => {
-                roff.text([roman(format!("{val_name}: {help}"))]);
+                roff.text([roman(val_name.to_owned()), roman(": ")]);
+                roff.extend([anstyle_roff::to_roff(&help.to_string())]);
             }
             None => {
                 roff.text([roman(val_name.to_owned())]);
@@ -398,3 +399,17 @@ fn option_sort_key(arg: &Arg) -> (usize, String) {
     };
     (arg.get_display_order(), key)
 }
+
+#[cfg(feature = "ansi")]
+fn style(s: &clap::StyledStr) -> Roff {
+    #[cfg(feature = "ansi")]
+    {
+        anstyle_roff::to_roff(&s.to_string())
+    }
+    #[cfg(not(feature = "ansi"))]
+    {
+        let mut roff = Roff::default();
+        roff.text([roman(s.to_string())]);
+        roff
+    }
+}

clap_mangen/tests/snapshots/styled.bash.roff

@@ -0,0 +1,28 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH my-app 1  "my-app " 
+.SH NAME
+my\-app \- Hello about!
+.SH SYNOPSIS
+\fBmy\-app\fR [\fB\-h\fR|\fB\-\-help\fR] [\fIarg\fR] 
+.SH DESCRIPTION
+Hello about!
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help (see a summary with \*(Aq\-h\*(Aq)
+.TP
+[\fIarg\fR]
+Hello help!
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+fast
+.IP \(bu 2
+slow: Hello PossibleValue!
+.RE
+.SH EXTRA
+Hello after_help!

clap_mangen/tests/testsuite/common.rs

@@ -473,3 +473,26 @@ pub(crate) fn default_subcmd_order(name: &'static str) -> clap::Command {
         ),
     ])
 }
+
+pub(crate) fn styled(name: &'static str) -> clap::Command {
+    const ALL_STYLES: anstyle::Style = anstyle::Style::new()
+        .fg_color(Some(anstyle::Color::Ansi(anstyle::AnsiColor::Red)))
+        .bg_color(Some(anstyle::Color::Ansi(anstyle::AnsiColor::Blue)))
+        .bold()
+        .italic()
+        .underline();
+    clap::Command::new(name)
+        .about(format!("Hello {ALL_STYLES}about{ALL_STYLES:#}!"))
+        .before_help(format!("Hello {ALL_STYLES}before_help{ALL_STYLES:#}!"))
+        .after_help(format!("Hello {ALL_STYLES}after_help{ALL_STYLES:#}!"))
+        .override_usage(format!("Hello {ALL_STYLES}usage{ALL_STYLES:#}!"))
+        .arg(
+            clap::Arg::new("arg")
+                .value_parser([
+                    PossibleValue::new("fast"),
+                    PossibleValue::new("slow")
+                        .help(format!("Hello {ALL_STYLES}PossibleValue{ALL_STYLES:#}!")),
+                ])
+                .help(format!("Hello {ALL_STYLES}help{ALL_STYLES:#}!")),
+        )
+}

clap_mangen/tests/testsuite/roff.rs

@@ -189,3 +189,10 @@ fn default_subcmd_order() {
         cmd,
     );
 }
+
+#[test]
+fn styled() {
+    let name = "my-app";
+    let cmd = common::styled(name);
+    common::assert_matches(snapbox::file!["../snapshots/styled.bash.roff"], cmd);
+}