docs(readme): discuss API trade offs

Fixes #3329

Author: epage

Cargo.toml

@@ -51,7 +51,7 @@ pre-release-replacements = [
   {file="CHANGELOG.md", search="ReleaseDate", replace="{{date}}", min=1},
   {file="CHANGELOG.md", search="<!-- next-header -->", replace="<!-- next-header -->\n## [Unreleased] - ReleaseDate\n", exactly=1},
   {file="CHANGELOG.md", search="<!-- next-url -->", replace="<!-- next-url -->\n[Unreleased]: https://github.com/clap-rs/clap/compare/{{tag_name}}...HEAD", exactly=1},
-  {file="README.md", search="github.com/clap-rs/clap/blob/[^/]+/", replace="github.com/clap-rs/clap/blob/{{tag_name}}/", exactly=10, prerelease = true},
+  {file="README.md", search="github.com/clap-rs/clap/blob/[^/]+/", replace="github.com/clap-rs/clap/blob/{{tag_name}}/", exactly=12, prerelease = true},
   {file="README.md", search="version = \"[a-z0-9\\.-]+\"", replace="version = \"{{version}}\"", exactly=1, prerelease = true},
   {file="src/derive.rs", search="github.com/clap-rs/clap/blob/[^/]+/", replace="github.com/clap-rs/clap/blob/{{tag_name}}/", exactly=4, prerelease = true},
 ]

README.md

@@ -33,7 +33,7 @@ Create your command-line parser, with all of the bells and whistles, declarative
 
 This uses our
 [Derive API](https://github.com/clap-rs/clap/blob/v3.0.10/examples/derive_ref/README.md)
-which provides access to the Builder API as attributes on a `struct`:
+which provides access to the [Builder API](https://docs.rs/clap) as attributes on a `struct`:
 
 <!-- Copied from examples/demo.{rs,md} -->
 ```rust,no_run
@@ -102,6 +102,20 @@ get.  Check out the
 [argparse-benchmarks](https://github.com/rust-cli/argparse-benchmarks-rs) for
 CLI parsers optimized for other use cases.
 
+### Selecting an API
+
+Why use the declarative [Derive API](https://github.com/clap-rs/clap/blob/v3.0.10/examples/tutorial_derive/README.md):
+- Easier to read, write, and modify
+- Easier to keep the argument declaration and reading of argument in sync
+- Easier to reuse, e.g. [clap-verbosity-flag](https://crates.io/crates/clap-verbosity-flag)
+
+Why use the procedural [Builder API](https://github.com/clap-rs/clap/blob/v3.0.10/examples/tutorial_builder/README.md):
+- Faster compile times if you aren't already using other procedural macros
+- More flexible, e.g. you can look up how many times an argument showed up,
+  what its values were, and what were the indexes of those values.  The Derive
+  API can only report presence, number of occurrences, or values but no indices
+  or combinations of data.
+
 ### Related Projects
 
 - [wild](https://crates.io/crates/wild) for supporting wildcards (`*`) on Windows like you do Linux