`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!
Experimenting with treating clap-derive and clap one and the same from
the release process perspective. The completion generators are a bit
more independent.
This is carried over from the clap_derive examples. Looking over the
other examples, I feel like they are covered by other examples or by the
derive reference. We should call out deny missing docs though.
This creates distinct tutorial examples from complex feature examples
(more how-tos). Both sets are getting builder / derive versions (at
least the critical ones).
In #27, we removed some default features. When doing so, some places
weren't updated but `doc` feature covered it ... except it was only
partially updated. This makes sure we test all the features.
Too many times people have to disable default features. Let's try to
have a more minimal out of box experience.
- `derive`: people are already used to adding this feature for serde
- `cargo`: not needed for derive
- `env`: most probably don't use this
- `unicode`: most CLIs are probably ASCII. We should do a debug warn
about this though
BREAKING CHANGE: `derive`, `cargo`, `env`, and `unicode` are no longer
on by default.
This ports our example testing over to [trycmd](https://docs.rs/) so
we can:
- More thoroughly test our examples
- Provide always-up-to-date example usage
The old way of testing automatically picked up examples. This new way
requires we have a `.md` file that uses the example in some way.
Notes:
- Moved overall example description to the `.md` file
- I added cross-linking between related examples
- `14_groups` had a redundant paragraph (twice talked about "one and
only one"
