fix(man): show the environment info with separate paragraph (#3631)

This commit updates the man page renderer to use a relative margin
indent for environment variable text instead of appending to the
existing help text.

Signed-off-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>
Fixes: #3630

clap_mangen/src/render.rs

@@ -112,13 +112,15 @@ pub(crate) fn options(roff: &mut Roff, cmd: &clap::Command) {
             body.push(roman(help));
         }
 
-        if let Some(mut env) = option_environment(opt) {
-            body.append(&mut env);
-        }
-
         roff.control("TP", []);
         roff.text(header);
         roff.text(body);
+
+        if let Some(env) = option_environment(opt) {
+            roff.control("RS", []);
+            roff.text(env);
+            roff.control("RE", []);
+        }
     }
 
     for pos in items.iter().filter(|a| a.is_positional()) {
@@ -141,13 +143,15 @@ pub(crate) fn options(roff: &mut Roff, cmd: &clap::Command) {
             body.push(roman(&help.to_string()));
         }
 
-        if let Some(mut env) = option_environment(pos) {
-            body.append(&mut env);
-        }
-
         roff.control("TP", []);
         roff.text(header);
         roff.text(body);
+
+        if let Some(env) = option_environment(pos) {
+            roff.control("RS", []);
+            roff.text(env);
+            roff.control("RE", []);
+        }
     }
 }
 

clap_mangen/tests/common.rs

@@ -231,6 +231,18 @@ pub fn hidden_option_command(name: &'static str) -> clap::Command<'static> {
         )
 }
 
+pub fn env_value_command(name: &'static str) -> clap::Command<'static> {
+    clap::Command::new(name).arg(
+        clap::Arg::new("config")
+            .short('c')
+            .long_help("Set configuration file path")
+            .required(false)
+            .takes_value(true)
+            .default_value("config.toml")
+            .env("CONFIG_FILE"),
+    )
+}
+
 pub fn assert_matches_path(expected_path: impl AsRef<std::path::Path>, cmd: clap::Command) {
     let mut buf = vec![];
     clap_mangen::Man::new(cmd).render(&mut buf).unwrap();

clap_mangen/tests/roff.rs

@@ -55,3 +55,10 @@ fn hidden_options() {
     let cmd = common::hidden_option_command(name);
     common::assert_matches_path("tests/snapshots/hidden_option.bash.roff", cmd);
 }
+
+#[test]
+fn value_env() {
+    let name = "my-app";
+    let cmd = common::env_value_command(name);
+    common::assert_matches_path("tests/snapshots/value_env.bash.roff", cmd);
+}

clap_mangen/tests/snapshots/value_env.bash.roff

@@ -0,0 +1,18 @@
+.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/-h/fR|/fB/-/-help/fR] [/fB/-c /fR] 
+.SH DESCRIPTION
+.SH OPTIONS
+.TP
+/fB/-h/fR, /fB/-/-help/fR
+Print help information
+.TP
+/fB/-c/fR [default: config.toml]
+Set configuration file path
+.RS
+May also be specified with the /fBCONFIG_FILE/fR environment variable. 
+.RE