feat(mangen): Support flatten_help #5769
Conversation
aparcar
force-pushed
the
flat-man
branch
2 times, most recently
from
4823360
to
09f42dc
Compare
clap_mangen/src/lib.rs
Outdated
| for sc in self.cmd.get_subcommands() { | ||
| render::synopsis(roff, sc); | ||
| roff.control("br", []); | ||
| } |
There was a problem hiding this comment.
There are times when you should sow the usage for the current command
See
clap/clap_builder/src/output/usage.rs
Lines 107 to 113 in d2874a5
In general, I'd recommend checking how we use flatten_help to change output
There was a problem hiding this comment.
I am not seeing a call to is_subcommand_required_set or is_args_conflicts_with_subcommands_set to handle this
There was a problem hiding this comment.
Please document in the PR description any style differences between --help and man's handling of flatten_help
There was a problem hiding this comment.
Before documenting it I want to make sure that the flatten_help implementation for --help isn't incomplete. In the picture below are subcommand details printed directly after the options without another section title, is that intended?
There was a problem hiding this comment.
In the picture below are subcommand details printed directly after the options without another section title, is that intended?
Yes, that is intentional as we don't really have a good way of rendering sub-headers at this time.
aparcar
force-pushed
the
flat-man
branch
3 times, most recently
from
3f70e85
to
c2c7c26
Compare
clap_mangen/src/render.rs
Outdated
| for (_, name, cmd) in ord_v { | ||
| let mut line = command_with_args(cmd, name); | ||
|
|
||
| if cmd.has_subcommands() && !flatten { |
There was a problem hiding this comment.
I'm quite sure you don't love this way of implementing it, do you have a cleaner idea?
There was a problem hiding this comment.
where possible, we should match how our regular usage renderer does things
There was a problem hiding this comment.
I changed the style to be less invasive, what do you think?
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]>
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`. Signed-off-by: Paul Spooren <[email protected]>
Signed-off-by: Paul Spooren <[email protected]>
|
I added a wip commit to handle |
The
flatten_helpargument combines all subcommands on a single page. Until now this wasn't supported formangen. With this command the sectionsSYNOPSISas well as(SUB)COMMANDSare changed to imitate the style ofgit 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
clapand 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