Skip to content

Commit 11d560f

Browse files
aparcarepage
aparcar
authored and
epage
committed
feat(mangen): Support flatten_help
The `flatten_help` argument combines all subcommands on a single page. Until now this wasn't supported for `mangen`. With this command the sections `SYNOPSIS` as well as `SUBCOMMANDS` are changed to imitate the style of `git stash --help`. Differences between flattened `--help` and the flattened man: * `--help` prints the description at the very beginning while Man uses a section called DESCRIPTION below the USAGE. * `--help` prints placeholder `[OPTIONS]` while Man prints all options * `--help` prints positional options (aka arguments) in its own section called arguments while Man prints them at the end of OPTIONS. * `--help` prints subcommands as their own section after the options section while Man uses an extra section called SUBCOMMANDS * `--help` prints `after_long_help` at the very end while Man uses the section EXTRA which comes before the sections VERSION and AUTHORS Signed-off-by: Paul Spooren <[email protected]>
1 parent 78a738b commit 11d560f

15 files changed

+163
-57
lines changed

‎clap_mangen/src/lib.rs‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -289,7 +289,11 @@ impl Man {
289289
fn _render_subcommands_section(&self, roff: &mut Roff) {
290290
let heading = subcommand_heading(&self.cmd);
291291
roff.control("SH", [heading]);
292-
render::subcommands(roff, &self.cmd, &self.section);
292+
if self.cmd.is_flatten_help_set() {
293+
render::flat_subcommands(roff, &self.cmd);
294+
} else {
295+
render::subcommands(roff, &self.cmd, &self.section);
296+
}
293297
}
294298

295299
/// Render the EXTRA section into the writer.

‎clap_mangen/src/render.rs‎

Lines changed: 55 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -30,20 +30,42 @@ pub(crate) fn description(roff: &mut Roff, cmd: &clap::Command) {
3030
}
3131

3232
pub(crate) fn synopsis(roff: &mut Roff, cmd: &clap::Command) {
33-
let name = cmd.get_bin_name().unwrap_or_else(|| cmd.get_name());
34-
let mut line = usage(cmd, name);
35-
36-
if cmd.has_subcommands() {
37-
let (lhs, rhs) = subcommand_markers(cmd);
38-
line.push(roman(lhs));
39-
line.push(italic(
40-
cmd.get_subcommand_value_name()
41-
.unwrap_or_else(|| subcommand_heading(cmd))
42-
.to_lowercase(),
43-
));
44-
line.push(roman(rhs));
33+
let flatten = cmd.is_flatten_help_set();
34+
let mut first = true;
35+
if !cmd.is_subcommand_required_set() || cmd.is_args_conflicts_with_subcommands_set() {
36+
let mut line = usage(cmd, cmd.get_bin_name().unwrap_or_else(|| cmd.get_name()));
37+
if cmd.has_subcommands() && !flatten {
38+
let (lhs, rhs) = subcommand_markers(cmd);
39+
line.push(roman(lhs));
40+
line.push(italic(
41+
cmd.get_subcommand_value_name()
42+
.unwrap_or_else(|| subcommand_heading(cmd))
43+
.to_lowercase(),
44+
));
45+
line.push(roman(rhs));
46+
}
47+
roff.text(line);
48+
first = false;
49+
}
50+
if flatten {
51+
let mut ord_v = Vec::new();
52+
for subcommand in cmd.get_subcommands() {
53+
ord_v.push((
54+
subcommand.get_display_order(),
55+
subcommand.get_bin_name().unwrap_or_else(|| cmd.get_name()),
56+
subcommand,
57+
));
58+
}
59+
ord_v.sort_by(|a, b| (a.0, &a.1).cmp(&(b.0, &b.1)));
60+
for (_, name, cmd) in ord_v {
61+
if !first {
62+
roff.control("br", []);
63+
} else {
64+
first = false;
65+
}
66+
roff.text(usage(cmd, name));
67+
}
4568
}
46-
roff.text(line);
4769
}
4870

4971
fn usage(cmd: &clap::Command, name: &str) -> Vec<Inline> {
@@ -222,6 +244,26 @@ pub(crate) fn subcommands(roff: &mut Roff, cmd: &clap::Command, section: &str) {
222244
}
223245
}
224246

247+
pub(crate) fn flat_subcommands(roff: &mut Roff, cmd: &clap::Command) {
248+
for sub in cmd.get_subcommands().filter(|s| !s.is_hide_set()) {
249+
roff.control("TP", []);
250+
251+
let mut line = usage(sub, sub.get_name());
252+
253+
if let Some(about) = sub.get_long_about().or_else(|| sub.get_about()) {
254+
line.push(roman("\n"));
255+
line.push(roman(about.to_string()));
256+
}
257+
258+
if let Some(after_help) = sub.get_after_help() {
259+
line.push(roman("\n"));
260+
line.push(roman(after_help.to_string()));
261+
}
262+
263+
roff.text(line);
264+
}
265+
}
266+
225267
pub(crate) fn version(cmd: &clap::Command) -> String {
226268
format!(
227269
"v{}",

‎clap_mangen/tests/snapshots/flatten_arg_required.roff‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,11 @@
44
.SH NAME
55
parent \- parent command
66
.SH SYNOPSIS
7-
\fBparent\fR <\fB\-\-parent\fR> [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
7+
\fBparent\fR <\fB\-\-parent\fR> [\fB\-h\fR|\fB\-\-help\fR]
8+
.br
9+
\fBparent test\fR <\fB\-\-child\fR> [\fB\-h\fR|\fB\-\-help\fR]
10+
.br
11+
\fBparent help\fR
812
.SH DESCRIPTION
913
parent command
1014
.SH OPTIONS
@@ -16,8 +20,8 @@ parent command
1620
Print help
1721
.SH SUBCOMMANDS
1822
.TP
19-
parent\-test(1)
23+
\fBtest\fR <\fB\-\-child\fR> [\fB\-h\fR|\fB\-\-help\fR]
2024
test command
2125
.TP
22-
parent\-help(1)
26+
\fBhelp\fR
2327
Print this message or the help of the given subcommand(s)

‎clap_mangen/tests/snapshots/flatten_basic.roff‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,11 @@
44
.SH NAME
55
parent \- parent command
66
.SH SYNOPSIS
7-
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
7+
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR]
8+
.br
9+
\fBparent test\fR [\fB\-\-child\fR] [\fB\-h\fR|\fB\-\-help\fR]
10+
.br
11+
\fBparent help\fR
812
.SH DESCRIPTION
913
parent command
1014
.SH OPTIONS
@@ -16,8 +20,8 @@ parent command
1620
Print help
1721
.SH SUBCOMMANDS
1822
.TP
19-
parent\-test(1)
23+
\fBtest\fR [\fB\-\-child\fR] [\fB\-h\fR|\fB\-\-help\fR]
2024
test command
2125
.TP
22-
parent\-help(1)
26+
\fBhelp\fR
2327
Print this message or the help of the given subcommand(s)

‎clap_mangen/tests/snapshots/flatten_help.roff‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,11 @@
44
.SH NAME
55
my\-app
66
.SH SYNOPSIS
7-
\fBmy\-app\fR [\fB\-c \fR] [\fB\-v \fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
7+
\fBmy\-app\fR [\fB\-c \fR] [\fB\-v \fR] [\fB\-h\fR|\fB\-\-help\fR]
8+
.br
9+
\fBmy\-app test\fR [\fB\-d \fR]... [\fB\-c \fR] [\fB\-h\fR|\fB\-\-help\fR]
10+
.br
11+
\fBmy\-app help\fR
812
.SH DESCRIPTION
913
.SH OPTIONS
1014
.TP
@@ -18,9 +22,9 @@ my\-app
1822
Print help
1923
.SH SUBCOMMANDS
2024
.TP
21-
my\-app\-test(1)
25+
\fBtest\fR [\fB\-d \fR]... [\fB\-c \fR] [\fB\-h\fR|\fB\-\-help\fR]
2226
Subcommand
2327
with a second line
2428
.TP
25-
my\-app\-help(1)
29+
\fBhelp\fR
2630
Print this message or the help of the given subcommand(s)

‎clap_mangen/tests/snapshots/flatten_help_cmd.roff‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,11 @@
44
.SH NAME
55
parent \- parent command
66
.SH SYNOPSIS
7-
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
7+
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR]
8+
.br
9+
\fBparent test\fR [\fB\-\-child\fR] [\fB\-h\fR|\fB\-\-help\fR]
10+
.br
11+
\fBparent help\fR
812
.SH DESCRIPTION
913
parent command
1014
.SH OPTIONS
@@ -16,8 +20,8 @@ bar
1620
Print help (see a summary with \*(Aq\-h\*(Aq)
1721
.SH SUBCOMMANDS
1822
.TP
19-
parent\-test(1)
20-
test command
23+
\fBtest\fR [\fB\-\-child\fR] [\fB\-h\fR|\fB\-\-help\fR]
24+
long some
2125
.TP
22-
parent\-help(1)
26+
\fBhelp\fR
2327
Print this message or the help of the given subcommand(s)

‎clap_mangen/tests/snapshots/flatten_help_subcommand_required.roff‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@
44
.SH NAME
55
my\-app
66
.SH SYNOPSIS
7-
\fBmy\-app\fR [\fB\-c \fR] [\fB\-v \fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIsubcommands\fR>
7+
\fBmy\-app test\fR [\fB\-d \fR]... [\fB\-c \fR] [\fB\-h\fR|\fB\-\-help\fR]
8+
.br
9+
\fBmy\-app help\fR
810
.SH DESCRIPTION
911
.SH OPTIONS
1012
.TP
@@ -18,9 +20,9 @@ my\-app
1820
Print help
1921
.SH SUBCOMMANDS
2022
.TP
21-
my\-app\-test(1)
23+
\fBtest\fR [\fB\-d \fR]... [\fB\-c \fR] [\fB\-h\fR|\fB\-\-help\fR]
2224
Subcommand
2325
with a second line
2426
.TP
25-
my\-app\-help(1)
27+
\fBhelp\fR
2628
Print this message or the help of the given subcommand(s)

‎clap_mangen/tests/snapshots/flatten_hidden_command.roff‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,15 @@
44
.SH NAME
55
parent \- parent command
66
.SH SYNOPSIS
7-
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
7+
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR]
8+
.br
9+
\fBparent child1\fR [\fB\-\-child1\fR] [\fB\-h\fR|\fB\-\-help\fR]
10+
.br
11+
\fBparent child2\fR [\fB\-\-child2\fR] [\fB\-h\fR|\fB\-\-help\fR]
12+
.br
13+
\fBparent child3\fR [\fB\-\-child3\fR] [\fB\-h\fR|\fB\-\-help\fR]
14+
.br
15+
\fBparent help\fR
816
.SH DESCRIPTION
917
parent command
1018
.SH OPTIONS
@@ -16,11 +24,11 @@ parent command
1624
Print help
1725
.SH SUBCOMMANDS
1826
.TP
19-
parent\-child1(1)
27+
\fBchild1\fR [\fB\-\-child1\fR] [\fB\-h\fR|\fB\-\-help\fR]
2028
child1 command
2129
.TP
22-
parent\-child2(1)
30+
\fBchild2\fR [\fB\-\-child2\fR] [\fB\-h\fR|\fB\-\-help\fR]
2331
child2 command
2432
.TP
25-
parent\-help(1)
33+
\fBhelp\fR
2634
Print this message or the help of the given subcommand(s)

‎clap_mangen/tests/snapshots/flatten_not_recursive.roff‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,15 @@
44
.SH NAME
55
parent \- parent command
66
.SH SYNOPSIS
7-
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
7+
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR]
8+
.br
9+
\fBparent child1\fR [\fB\-\-child1\fR] [\fB\-h\fR|\fB\-\-help\fR]
10+
.br
11+
\fBparent child2\fR [\fB\-\-child2\fR] [\fB\-h\fR|\fB\-\-help\fR]
12+
.br
13+
\fBparent child3\fR [\fB\-\-child3\fR] [\fB\-h\fR|\fB\-\-help\fR]
14+
.br
15+
\fBparent help\fR
816
.SH DESCRIPTION
917
parent command
1018
.SH OPTIONS
@@ -16,14 +24,14 @@ parent command
1624
Print help
1725
.SH SUBCOMMANDS
1826
.TP
19-
parent\-child1(1)
27+
\fBchild1\fR [\fB\-\-child1\fR] [\fB\-h\fR|\fB\-\-help\fR]
2028
child1 command
2129
.TP
22-
parent\-child2(1)
30+
\fBchild2\fR [\fB\-\-child2\fR] [\fB\-h\fR|\fB\-\-help\fR]
2331
child2 command
2432
.TP
25-
parent\-child3(1)
33+
\fBchild3\fR [\fB\-\-child3\fR] [\fB\-h\fR|\fB\-\-help\fR]
2634
child3 command
2735
.TP
28-
parent\-help(1)
36+
\fBhelp\fR
2937
Print this message or the help of the given subcommand(s)

‎clap_mangen/tests/snapshots/flatten_recursive.roff‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,15 @@
44
.SH NAME
55
parent \- parent command
66
.SH SYNOPSIS
7-
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
7+
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR]
8+
.br
9+
\fBparent child1\fR [\fB\-\-child1\fR] [\fB\-h\fR|\fB\-\-help\fR]
10+
.br
11+
\fBparent child2\fR [\fB\-\-child2\fR] [\fB\-h\fR|\fB\-\-help\fR]
12+
.br
13+
\fBparent child3\fR [\fB\-\-child3\fR] [\fB\-h\fR|\fB\-\-help\fR]
14+
.br
15+
\fBparent help\fR
816
.SH DESCRIPTION
917
parent command
1018
.SH OPTIONS
@@ -16,11 +24,11 @@ parent command
1624
Print help
1725
.SH SUBCOMMANDS
1826
.TP
19-
parent\-child1(1)
27+
\fBchild1\fR [\fB\-\-child1\fR] [\fB\-h\fR|\fB\-\-help\fR]
2028
child1 command
2129
.TP
22-
parent\-child2(1)
30+
\fBchild2\fR [\fB\-\-child2\fR] [\fB\-h\fR|\fB\-\-help\fR]
2331
child2 command
2432
.TP
25-
parent\-help(1)
33+
\fBhelp\fR
2634
Print this message or the help of the given subcommand(s)

0 commit comments

Comments
 (0)