While `clap` depends on `clap_derive`, `clap_derive` inherently has a
dependency on `clap` because it generates code assuming at least a
specific clap version. If a new `clap_derive` is used with an old
`clap`, it'll generate code that won't compile.
We've kept things loose because of
- Bad experiences with overly constrained version reqs
- To not force new `clap` versions to release `clap_derive`.
- People should have a lock file anyways
The downsides:
- `cargo install` does not use `Cargo.lock` by default, required
`--locked`
- If we want people to not skip non-patch releases when upgrading, we
need it to not be a pain
`-h` (short help) still shows the same.
This gates it behind an `unstable-v4` feature flag to avoid disrupting users who set the help without knowing where all it shows up (particularly derive users where `ArgEnum` is automatically extracting the help).
Fixes#3312
I have access to the `clap-man` name but we use `clap_*`. Rather than
people getting mixed up on which is supposed to use, we went with a
different name.
This is an initial implementation with plenty of room to grow, including
- Allowing pulling out a subset of the generated man page for greater customization
- Subcommand handling
- Extra sections
- Consolidate argument formatter after #2914Fixes#552
This just affects how it's rendered; rather than attempting to highlight
these blocks as a shell script, they'll get highlighted as console
output.
See the rendered versions for a better comparison.
`clap_generate` originally intended to be "generate anything". With
`fig`, we already broke one part out. With #3174's man support, we are
also looking at keeping it separate:
- More freedom to iterate on the API
- Uniqueness (and potential weight) of its dependencies
- man generation is normally more for distribution while completions are
a mix of being distributed with the app or the app generating the
completions (which will be exacerbated if we move most completion
parsing logic to be in Rust)
So `clap_generate` is having a lot more limited of a role than the
original name conveys. I worry the generic name will be a hindrance to
people discovering and using it (yes, documentation can help but there
are limits).
I hesitated because we are on the verge of releasing 3.0. However, doing
it even later will be even more disruptive because more people will be
using it (crates.io lists ~70 people using `clap_generate`).
To ease things, we are still releasing `clap_generate` as a wrapper
around `clap_complete`.
