Skip to content

feat(mangen): Support flatten_help #5769

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

feat(mangen): Support flatten_help #5769

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ecd76b5
test(mangen): Add test for flatten_help
aparcar Oct 17, 2024
3829964
test(mangen): Add all flatten related tests from builder
aparcar Oct 23, 2024
78a738b
refactor(mangen): Split out usage() function
aparcar Oct 17, 2024
11d560f
feat(mangen): Support flatten_help
aparcar Feb 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion clap_mangen/src/lib.rs
View file
Open in desktop
Copy link
Member

@epage epage Oct 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Most of these differences sound unrelated to flattening

Original file line number Diff line number Diff line change
Expand Up @@ -289,7 +289,11 @@ impl Man {
fn _render_subcommands_section(&self, roff: &mut Roff) {
let heading = subcommand_heading(&self.cmd);
roff.control("SH", [heading]);
render::subcommands(roff, &self.cmd, &self.section);
if self.cmd.is_flatten_help_set() {
render::flat_subcommands(roff, &self.cmd);
} else {
render::subcommands(roff, &self.cmd, &self.section);
}
}

/// Render the EXTRA section into the writer.
Expand Down
68 changes: 55 additions & 13 deletions clap_mangen/src/render.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,20 +30,42 @@ pub(crate) fn description(roff: &mut Roff, cmd: &clap::Command) {
}

pub(crate) fn synopsis(roff: &mut Roff, cmd: &clap::Command) {
let name = cmd.get_bin_name().unwrap_or_else(|| cmd.get_name());
let mut line = usage(cmd, name);

if cmd.has_subcommands() {
let (lhs, rhs) = subcommand_markers(cmd);
line.push(roman(lhs));
line.push(italic(
cmd.get_subcommand_value_name()
.unwrap_or_else(|| subcommand_heading(cmd))
.to_lowercase(),
));
line.push(roman(rhs));
let flatten = cmd.is_flatten_help_set();
let mut first = true;
if !cmd.is_subcommand_required_set() || cmd.is_args_conflicts_with_subcommands_set() {
let mut line = usage(cmd, cmd.get_bin_name().unwrap_or_else(|| cmd.get_name()));
if cmd.has_subcommands() && !flatten {
let (lhs, rhs) = subcommand_markers(cmd);
line.push(roman(lhs));
line.push(italic(
cmd.get_subcommand_value_name()
.unwrap_or_else(|| subcommand_heading(cmd))
.to_lowercase(),
));
line.push(roman(rhs));
}
roff.text(line);
first = false;
}
if flatten {
let mut ord_v = Vec::new();
for subcommand in cmd.get_subcommands() {
ord_v.push((
subcommand.get_display_order(),
subcommand.get_bin_name().unwrap_or_else(|| cmd.get_name()),
subcommand,
));
}
Comment on lines +50 to +58
Copy link
Member

@epage epage Jul 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't recursive but should be (same with flat_subcommands)

ord_v.sort_by(|a, b| (a.0, &a.1).cmp(&(b.0, &b.1)));
for (_, name, cmd) in ord_v {
if !first {
roff.control("br", []);
} else {
first = false;
}
roff.text(usage(cmd, name));
}
}
roff.text(line);
}

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

pub(crate) fn flat_subcommands(roff: &mut Roff, cmd: &clap::Command) {
for sub in cmd.get_subcommands().filter(|s| !s.is_hide_set()) {
roff.control("TP", []);

let mut line = usage(sub, sub.get_name());

if let Some(about) = sub.get_long_about().or_else(|| sub.get_about()) {
line.push(roman("\n"));
line.push(roman(about.to_string()));
}

if let Some(after_help) = sub.get_after_help() {
line.push(roman("\n"));
line.push(roman(after_help.to_string()));
}

roff.text(line);
}
}

pub(crate) fn version(cmd: &clap::Command) -> String {
format!(
"v{}",
Expand Down
10 changes: 7 additions & 3 deletions clap_mangen/tests/snapshots/flatten_arg_required.roff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,11 @@
.SH NAME
parent \- parent command
.SH SYNOPSIS
\fBparent\fR <\fB\-\-parent\fR> [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
\fBparent\fR <\fB\-\-parent\fR> [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent test\fR <\fB\-\-child\fR> [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent help\fR
.SH DESCRIPTION
parent command
.SH OPTIONS
Expand All @@ -16,8 +20,8 @@ parent command
Print help
.SH SUBCOMMANDS
.TP
parent\-test(1)
\fBtest\fR <\fB\-\-child\fR> [\fB\-h\fR|\fB\-\-help\fR]
test command
.TP
parent\-help(1)
\fBhelp\fR
Print this message or the help of the given subcommand(s)
10 changes: 7 additions & 3 deletions clap_mangen/tests/snapshots/flatten_basic.roff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,11 @@
.SH NAME
parent \- parent command
.SH SYNOPSIS
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent test\fR [\fB\-\-child\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent help\fR
.SH DESCRIPTION
parent command
.SH OPTIONS
Expand All @@ -16,8 +20,8 @@ parent command
Print help
.SH SUBCOMMANDS
.TP
parent\-test(1)
\fBtest\fR [\fB\-\-child\fR] [\fB\-h\fR|\fB\-\-help\fR]
test command
.TP
parent\-help(1)
\fBhelp\fR
Print this message or the help of the given subcommand(s)
10 changes: 7 additions & 3 deletions clap_mangen/tests/snapshots/flatten_help.roff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,11 @@
.SH NAME
my\-app
.SH SYNOPSIS
\fBmy\-app\fR [\fB\-c \fR] [\fB\-v \fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
\fBmy\-app\fR [\fB\-c \fR] [\fB\-v \fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBmy\-app test\fR [\fB\-d \fR]... [\fB\-c \fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBmy\-app help\fR
.SH DESCRIPTION
.SH OPTIONS
.TP
Expand All @@ -18,9 +22,9 @@ my\-app
Print help
.SH SUBCOMMANDS
.TP
my\-app\-test(1)
\fBtest\fR [\fB\-d \fR]... [\fB\-c \fR] [\fB\-h\fR|\fB\-\-help\fR]
Subcommand
with a second line
.TP
my\-app\-help(1)
\fBhelp\fR
Print this message or the help of the given subcommand(s)
12 changes: 8 additions & 4 deletions clap_mangen/tests/snapshots/flatten_help_cmd.roff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,11 @@
.SH NAME
parent \- parent command
.SH SYNOPSIS
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent test\fR [\fB\-\-child\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent help\fR
.SH DESCRIPTION
parent command
.SH OPTIONS
Expand All @@ -16,8 +20,8 @@ bar
Print help (see a summary with \*(Aq\-h\*(Aq)
.SH SUBCOMMANDS
.TP
parent\-test(1)
test command
\fBtest\fR [\fB\-\-child\fR] [\fB\-h\fR|\fB\-\-help\fR]
long some
.TP
parent\-help(1)
\fBhelp\fR
Print this message or the help of the given subcommand(s)
8 changes: 5 additions & 3 deletions clap_mangen/tests/snapshots/flatten_help_subcommand_required.roff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@
.SH NAME
my\-app
.SH SYNOPSIS
\fBmy\-app\fR [\fB\-c \fR] [\fB\-v \fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIsubcommands\fR>
\fBmy\-app test\fR [\fB\-d \fR]... [\fB\-c \fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBmy\-app help\fR
.SH DESCRIPTION
.SH OPTIONS
.TP
Expand All @@ -18,9 +20,9 @@ my\-app
Print help
.SH SUBCOMMANDS
.TP
my\-app\-test(1)
\fBtest\fR [\fB\-d \fR]... [\fB\-c \fR] [\fB\-h\fR|\fB\-\-help\fR]
Subcommand
with a second line
.TP
my\-app\-help(1)
\fBhelp\fR
Print this message or the help of the given subcommand(s)
16 changes: 12 additions & 4 deletions clap_mangen/tests/snapshots/flatten_hidden_command.roff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,15 @@
.SH NAME
parent \- parent command
.SH SYNOPSIS
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent child1\fR [\fB\-\-child1\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent child2\fR [\fB\-\-child2\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent child3\fR [\fB\-\-child3\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent help\fR
.SH DESCRIPTION
parent command
.SH OPTIONS
Expand All @@ -16,11 +24,11 @@ parent command
Print help
.SH SUBCOMMANDS
.TP
parent\-child1(1)
\fBchild1\fR [\fB\-\-child1\fR] [\fB\-h\fR|\fB\-\-help\fR]
child1 command
.TP
parent\-child2(1)
\fBchild2\fR [\fB\-\-child2\fR] [\fB\-h\fR|\fB\-\-help\fR]
child2 command
.TP
parent\-help(1)
\fBhelp\fR
Print this message or the help of the given subcommand(s)
18 changes: 13 additions & 5 deletions clap_mangen/tests/snapshots/flatten_not_recursive.roff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,15 @@
.SH NAME
parent \- parent command
.SH SYNOPSIS
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent child1\fR [\fB\-\-child1\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent child2\fR [\fB\-\-child2\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent child3\fR [\fB\-\-child3\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent help\fR
.SH DESCRIPTION
parent command
.SH OPTIONS
Expand All @@ -16,14 +24,14 @@ parent command
Print help
.SH SUBCOMMANDS
.TP
parent\-child1(1)
\fBchild1\fR [\fB\-\-child1\fR] [\fB\-h\fR|\fB\-\-help\fR]
child1 command
.TP
parent\-child2(1)
\fBchild2\fR [\fB\-\-child2\fR] [\fB\-h\fR|\fB\-\-help\fR]
child2 command
.TP
parent\-child3(1)
\fBchild3\fR [\fB\-\-child3\fR] [\fB\-h\fR|\fB\-\-help\fR]
child3 command
.TP
parent\-help(1)
\fBhelp\fR
Print this message or the help of the given subcommand(s)
16 changes: 12 additions & 4 deletions clap_mangen/tests/snapshots/flatten_recursive.roff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,15 @@
.SH NAME
parent \- parent command
.SH SYNOPSIS
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent child1\fR [\fB\-\-child1\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent child2\fR [\fB\-\-child2\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent child3\fR [\fB\-\-child3\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent help\fR
.SH DESCRIPTION
parent command
.SH OPTIONS
Expand All @@ -16,11 +24,11 @@ parent command
Print help
.SH SUBCOMMANDS
.TP
parent\-child1(1)
\fBchild1\fR [\fB\-\-child1\fR] [\fB\-h\fR|\fB\-\-help\fR]
child1 command
.TP
parent\-child2(1)
\fBchild2\fR [\fB\-\-child2\fR] [\fB\-h\fR|\fB\-\-help\fR]
child2 command
.TP
parent\-help(1)
\fBhelp\fR
Print this message or the help of the given subcommand(s)
8 changes: 6 additions & 2 deletions clap_mangen/tests/snapshots/flatten_single_hidden_command.roff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,11 @@
.SH NAME
parent \- parent command
.SH SYNOPSIS
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent child1\fR [\fB\-\-child1\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent help\fR
.SH DESCRIPTION
parent command
.SH OPTIONS
Expand All @@ -16,5 +20,5 @@ parent command
Print help
.SH SUBCOMMANDS
.TP
parent\-help(1)
\fBhelp\fR
Print this message or the help of the given subcommand(s)
10 changes: 7 additions & 3 deletions clap_mangen/tests/snapshots/flatten_with_args_conflicts_with_subcommands.roff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,11 @@
.SH NAME
parent \- parent command
.SH SYNOPSIS
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIsubcommands\fR>
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent test\fR [\fB\-\-child\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent help\fR
.SH DESCRIPTION
parent command
.SH OPTIONS
Expand All @@ -16,8 +20,8 @@ parent command
Print help
.SH SUBCOMMANDS
.TP
parent\-test(1)
\fBtest\fR [\fB\-\-child\fR] [\fB\-h\fR|\fB\-\-help\fR]
test command
.TP
parent\-help(1)
\fBhelp\fR
Print this message or the help of the given subcommand(s)
10 changes: 7 additions & 3 deletions clap_mangen/tests/snapshots/flatten_with_external_subcommand.roff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,11 @@
.SH NAME
parent \- parent command
.SH SYNOPSIS
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
\fBparent\fR [\fB\-\-parent\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent test\fR [\fB\-\-child\fR] [\fB\-h\fR|\fB\-\-help\fR]
.br
\fBparent help\fR
.SH DESCRIPTION
parent command
.SH OPTIONS
Expand All @@ -16,8 +20,8 @@ parent command
Print help
.SH SUBCOMMANDS
.TP
parent\-test(1)
\fBtest\fR [\fB\-\-child\fR] [\fB\-h\fR|\fB\-\-help\fR]
test command
.TP
parent\-help(1)
\fBhelp\fR
Print this message or the help of the given subcommand(s)
Loading