This adds a new `Cargo.toml` feature named `deprecated` that opts
controls whether deprecation warnings show up. This is starting off as
non-default though that may change (see below).
Benefits
- Allows a staged rollout so a smaller subset of users see new
deprecations and can report their experience with them before everyone
sees them. For example, this reduces the number of people who have to
deal with #3822.
- This allows people to defer responding to each new batch of
deprecations and instead do it at once. This means we should
reconsider #3616.
The one risk is people who don't follow blog posts and guides having a
harder time upgrading to the next breaking release without the warnings
on by default. For these users, we reserve the right to make the
`deprecated` feature `default`. This is most likely to happen in a
minor release that is released in conjunction with the next major
release (e.g. when releasing 4.0.0, we release a 3.3.0 that enables
deprecations by default). By using a feature, users can still disable
this if they want.
Thanks @joshtriplett for the idea
Though this is changing an API item we export, we do not consider this a
breaking change because
- This was an implementation detail of the macros and people shouldn't be using it directly
- The `macro_rules` macro is coupled to `clap` because they are in the
same crate
- The derive macro is coupled to `clap` because `clap` declares a
`=x.y.z` dependency on `clap_derive
Fixes#3828
This is mostly about avoiding criterion's build times when just
developing clap itself.
I'm assuming the derive test changed because criterion's clap v2 isn't
in the dependency tree anymore.
`multicall` allows you to have one binary expose itself as multiple
programs, like busybox does. This also works well for user clap for
parsing REPLs.
Fixes#2861
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`.
Confirmed this works with [`argfile`](https://docs.rs/argfile/latest/argfile/)
And then running in clap
```
$ RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features
```
They now show up!
