Unclear how to handle subcommands with clap_man

[epage]

Please complete the following tasks

• I have searched the discussions
• I have searched the existing issues

Rust Version

rustc 1.57.0 (f1edd0429 2021-11-29)

Clap Version

v3.0.6

Minimal reproducible code

TBD

Steps to reproduce the bug with the above code

TBD

Actual Behaviour

We show a list of subcommand man apges

Expected Behaviour

TBD

Additional Context

Split out of #3174

#1334 is relevant

Debug Output

No response

[sondr3]

For some design "inspiration" on how to lay it out, cabal (cargo for Haskell) has everything in a single, gigantic document while cargo and git lists the available subcommands and where to find them. I highly prefer the latter approach, but it shouldn't be too hard to support both.

[epage]

In general, clap behaves more like most of git. The linked issue (#1334) is about offering it to work more like git stash's subcommands.

Its also something we'd want to have an example for to help show how to go about it and to verify we have the full experience worked out,.

[gibfahn]

Wanted to link the only example I've found (maybe I missed an obvious one) of a way to handle subcommand man page generation:

https://github.com/CKingX/ddrescue_error_mapping/blob/05899edbe60c0ee6cfdda70aa6379161d2fb1390/build.rs#L20-L38

[sunshowers]

@gibfahn for cargo-nextest I tried that approach but encountered #3869 unfortunately.

[nihaals]

It would be nice if there was a way to switch between referencing pages for subcommands and including them in the same page (as either an argument to Man::render() or a different method) so you could switch between the two approaches (like cabal and git as mentioned above), as in some contexts having a single page might fit better. It would also provide an immediate workaround for #3603 where a different API wouldn't need to be worked on yet.