Add -r, --recursive flags to help command

[SUPERCILEX]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Clap Version

master

Describe your use case

./binary help -r will print the help of every subcommand recursively. This fixes #3934 and kind of acts like a man page.

[epage]

Know of any precedence in any applications?

How would you expect the output from the commands to be delineated? Just concatenating one output after another? Dividers?

In what way would this act like a man page? Most man pages I've seen are either like git or git stash and don't blindly include all subcommands. Having it be driven by the definition of the command, rather than the user, is being tracked in #1334.

I'll be upfront that I lean more in favor of #1334 rather than this. Another element is I have been considering trying to allow arguments to be ignored so you can insert a help anywhere and it will then render the relevant help. An example of where that would be relevant is command chaining.

[SUPERCILEX]

Know of any precedence in any applications?

The Ocaml one looks like this: https://github.com/facebook/infer/blob/main/sledge/sledge-help.txt

How would you expect the output from the commands to be delineated? Just concatenating one output after another? Dividers?

====== path to sub command ====== seems reasonable, but I don't have any real preference here.

In what way would this act like a man page?

I mean it in the sense that you get all the information at once.

I'll be upfront that I lean more in favor of #1334 rather than this.

I'm not sure these two ideas are mutually exclusive. This one is nicer in the sense that you don't force users to see the entire CLI unless they want to.

An example of where that would be relevant is #2222 (comment).

This workflow appears to be centered around appending --help to an existing subcommand which doesn't seem related to the help subcommand.

[epage]

At least in a text document, the OCaml version looks hard to read. The dividers don't really stand out for the different levels of the document and that requires a lot of scrolling / scanning to find the appropriate section. I feel like if we did this, it would be blocked on #4201 to ensure we had a good experience for the users. Yes, users can manually pipe but then they lose all styling and have to go through extra hoops (env variables for clap, flags to less) for it to work

In what way would this act like a man page?

I mean it in the sense that you get all the information at once.

As I said, most man pages I've looked at don't show you everything at once. cargo splits it up by subcommand. git mostly does except in cases like git stash.

This workflow appears to be centered around appending --help to an existing subcommand which doesn't seem related to the help subcommand.

You can just as easily substitute help in that discussion as --help.

[SUPERCILEX]

text document [...] looks hard to read

Right, and I don't think that's a solvable problem since you have to render things in your head. For output in a terminal, maybe colors could be used or the font size could be changed? (not sure if that's a thing)

Pagination sounds reasonable.

most man pages I've looked at don't show you everything at once

Bad example then, no need to fixate on it.

You can just as easily substitute help in that discussion as --help.

You're thinking some command help? That's very odd to me. Why break convention instead of having people type some command --help?

[epage]

You're thinking some command help? That's very odd to me. Why break convention instead of having people type some command --help?

Whats odd about it? Its supported today.

[SUPERCILEX]

Hmmm, I don't think we're talking about the same thing. some help command is supported, but how could some command help be supported when command can take arguments?

[epage]

some command help is supported if it takes subcommands. The issue I linked to is about a new Command::chain that, when enabled, will cause all subcommands to effectively have their sibling subcommands as subsubcommands, so if enabled for some, then some command help would list all subcommands of some.

[SUPERCILEX]

Gotya, didn't know that was a thing. Then I'm not sure how these features could interact. Maybe the recursive flag could only work for the root help, but that still might conflict.

[epage]

FYI #5206 is up for closing out #1334. While not ideal, this could be abused for golden state testing to have the test force enable it recursively and then render the help. This will lose help heading information, long abouts for subcommands, and maybe one or two other things.