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 <mail@aparcar.org>

Add all tests from tests/builder/help.rs to mangen, too. Signed-off-by: Paul Spooren <mail@aparcar.org>

The function prints the usage of a (sub)command. Signed-off-by: Paul Spooren <mail@aparcar.org>

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 <mail@aparcar.org>

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