clap-rs
Unclear how to handle subcommands with `clap_man`
Please complete the following tasks
- [X] I have searched the discussions
- [X] 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
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.
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,.
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
@gibfahn for cargo-nextest I tried that approach but encountered https://github.com/clap-rs/clap/issues/3869 unfortunately.
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.
