feat(mangen): Support flatten_help #5769

aparcar · 2024-10-07T09:11:58Z

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 (SUB)COMMANDS are changed to imitate the style of git stash --help.

I reached out via discussions and it looks like this doesn't work just yet #5761

This is not necessarily the most beautiful implementation due to my limited knowledge of both clap and Rust itself.

I implemented this for a project I'm working on and the results look quite okay:

Not using man.render() but call each command manually feels a bit awkward but does work just fine, see example here https://github.com/rosenpass/rosenpass/pull/434/files#diff-352422e105afd3138a54ea14e33af782243398f1d768d271655729dd4bcb99d2R18

clap_mangen/src/lib.rs

clap_mangen/src/render.rs

clap_mangen/tests/testsuite/roff.rs

clap_mangen/src/render.rs

aparcar · 2024-10-17T13:43:26Z

~~I added a wip commit to handle is_subcommand_required. Still trying to figure out is_args_conflicts_with_subcommands_set~~ Incorporated is_subcommand_required and is_args_conflicts_with_subcommands_set

aparcar · 2024-10-21T13:29:51Z

I added the differences between flattened --help and flattened Man to the commit description, below are screenshots of what I used for comparison.

`--help`

Man

aparcar · 2024-10-21T15:45:41Z

@epage hey Ed I covered your comments as good as I could and think this is ready

clap_mangen/src/render.rs

epage · 2024-10-22T18:09:13Z

clap_mangen/src/lib.rs

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

clap_mangen/tests/testsuite/roff.rs

clap_mangen/tests/snapshots/flatten_help.roff

clap_mangen/tests/testsuite/roff.rs

clap_mangen/src/render.rs

clap_mangen/tests/testsuite/roff.rs

epage · 2024-10-23T21:16:26Z

clap_mangen/tests/testsuite/roff.rs

+#[test]
+fn flatten_help_true() {
+    let name = "my-app";
+    let cmd = common::basic_command(name).flatten_help(true);
+    common::assert_matches(snapbox::file!["../snapshots/flatten_help.roff"], cmd);
+}
+
+#[test]
+fn flatten_help_true_subcommand_required_true() {
+    let name = "my-app";
+    let cmd = common::basic_command(name)
+        .flatten_help(true)
+        .subcommand_required(true);
+    common::assert_matches(
+        snapbox::file!["../snapshots/flatten_help_subcommand_required.roff"],
+        cmd,
+    );
+}
+
+#[test]
+fn flatten_help_true_subcommand_args_conflicts_with_subcommands() {


Are these tests still needed with the addition of the --help tests?

This test shows that the output stays the same independent of the value of `flatten_help`. Further commits may implement `flatten_help` for `clap_mangen`. Signed-off-by: Paul Spooren <[email protected]>

Add all tests from tests/builder/help.rs to mangen, too. Signed-off-by: Paul Spooren <[email protected]>

The function prints the usage of a (sub)command. Signed-off-by: Paul Spooren <[email protected]>

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]>

epage · 2025-07-10T15:39:08Z

clap_mangen/src/render.rs

+    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,
+            ));
+        }


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

epage · 2025-07-10T15:40:24Z

I've cleaned up the commits and rebased but this is still lacking recursion, there is a question on whether tests are redundant, and the PR description seems to be describing more than just flattening.

epage

See #5769 (comment)

aparcar force-pushed the flat-man branch from a502399 to 911cb8c Compare October 7, 2024 09:12

aparcar mentioned this pull request Oct 7, 2024

feat(cli): Automatically generate man page rosenpass/rosenpass#434

Merged

aparcar force-pushed the flat-man branch 2 times, most recently from 4823360 to 09f42dc Compare October 7, 2024 09:20

epage reviewed Oct 7, 2024

View reviewed changes

clap_mangen/src/lib.rs Outdated Show resolved Hide resolved

epage reviewed Oct 7, 2024

View reviewed changes

clap_mangen/src/lib.rs Outdated Show resolved Hide resolved

epage reviewed Oct 7, 2024

View reviewed changes

clap_mangen/src/lib.rs Show resolved Hide resolved

aparcar force-pushed the flat-man branch 3 times, most recently from 3f70e85 to c2c7c26 Compare October 16, 2024 15:15

aparcar commented Oct 16, 2024

View reviewed changes

clap_mangen/src/render.rs Outdated Show resolved Hide resolved

aparcar marked this pull request as ready for review October 16, 2024 16:09

epage reviewed Oct 16, 2024

View reviewed changes

clap_mangen/tests/testsuite/roff.rs Outdated Show resolved Hide resolved

epage reviewed Oct 16, 2024

View reviewed changes

clap_mangen/src/render.rs Outdated Show resolved Hide resolved

epage reviewed Oct 16, 2024

View reviewed changes

clap_mangen/src/render.rs Outdated Show resolved Hide resolved

epage reviewed Oct 16, 2024

View reviewed changes

clap_mangen/src/render.rs Outdated Show resolved Hide resolved

epage reviewed Oct 16, 2024

View reviewed changes

clap_mangen/src/render.rs Outdated Show resolved Hide resolved

epage reviewed Oct 16, 2024

View reviewed changes

clap_mangen/src/render.rs Outdated Show resolved Hide resolved

aparcar force-pushed the flat-man branch 2 times, most recently from 5094ea2 to 77e56f6 Compare October 17, 2024 13:10

aparcar marked this pull request as draft October 17, 2024 13:42

aparcar force-pushed the flat-man branch 2 times, most recently from 7acd84c to 52a7a4c Compare October 18, 2024 09:31

aparcar marked this pull request as ready for review October 18, 2024 09:44

aparcar force-pushed the flat-man branch from 52a7a4c to aec1ede Compare October 21, 2024 13:28

epage reviewed Oct 22, 2024

View reviewed changes

clap_mangen/src/render.rs Outdated Show resolved Hide resolved

epage reviewed Oct 22, 2024

View reviewed changes

clap_mangen/tests/testsuite/roff.rs Show resolved Hide resolved

epage reviewed Oct 22, 2024

View reviewed changes

clap_mangen/tests/snapshots/flatten_help.roff Outdated Show resolved Hide resolved

epage reviewed Oct 22, 2024

View reviewed changes

clap_mangen/tests/testsuite/roff.rs Show resolved Hide resolved

epage reviewed Oct 22, 2024

View reviewed changes

clap_mangen/src/render.rs Outdated Show resolved Hide resolved

aparcar force-pushed the flat-man branch 2 times, most recently from 26f3ad8 to 004e815 Compare October 23, 2024 10:18

epage reviewed Oct 23, 2024

View reviewed changes

clap_mangen/tests/testsuite/roff.rs Show resolved Hide resolved

epage reviewed Oct 23, 2024

View reviewed changes

aparcar force-pushed the flat-man branch 3 times, most recently from c8d9c77 to d5c2884 Compare February 10, 2025 20:59

pksunkara requested a review from epage June 19, 2025 00:03

aparcar added 4 commits July 10, 2025 10:31

test(mangen): Add test for flatten_help

ecd76b5

This test shows that the output stays the same independent of the value of `flatten_help`. Further commits may implement `flatten_help` for `clap_mangen`. Signed-off-by: Paul Spooren <[email protected]>

test(mangen): Add all flatten related tests from builder

3829964

Add all tests from tests/builder/help.rs to mangen, too. Signed-off-by: Paul Spooren <[email protected]>

refactor(mangen): Split out usage() function

78a738b

The function prints the usage of a (sub)command. Signed-off-by: Paul Spooren <[email protected]>

epage force-pushed the flat-man branch from d5c2884 to 11d560f Compare July 10, 2025 15:34

epage reviewed Jul 10, 2025

View reviewed changes

epage requested changes Jul 10, 2025

View reviewed changes

Uh oh!

feat(mangen): Support flatten_help #5769

Are you sure you want to change the base?

feat(mangen): Support flatten_help #5769

Uh oh!

Conversation

aparcar commented Oct 7, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aparcar commented Oct 17, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aparcar commented Oct 21, 2024

--help

Man

Uh oh!

aparcar commented Oct 21, 2024

Uh oh!

Uh oh!

epage Oct 22, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

epage Oct 23, 2024

Choose a reason for hiding this comment

Uh oh!

epage Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

epage commented Jul 10, 2025

Uh oh!

epage left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aparcar commented Oct 7, 2024 •

edited

Loading

aparcar commented Oct 17, 2024 •

edited

Loading

`--help`