Simplify / shorten / reorganize cargo generate's help text.

[alilleybrinker]

Currently, the help text for cargo generate is quite large, both vertically (there are many flags) and horizontally (the descriptions for the flags are quite long).

On my own system I have:

Click to view the help text.

cargo, make me a project

Usage: 

Arguments:
  [AUTO_PATH]
          Auto attempt to use as either `--git` or `--favorite`. If either is specified explicitly, use as subfolder

  [SUBFOLDER]
          Specifies a subfolder within the template repository to be used as the actual template

Options:
      --test
          Expand $CWD as a template, then run `cargo test` on the expansion (set $CARGO_GENERATE_TEST_CMD to override test command).
          
          Any arguments given after the `--test` argument, will be used as arguments for the test command.

  -g, --git <GIT>
          Git repository to clone template from. Can be a URL (like `https://github.com/rust-cli/cli-template`), a path (relative or absolute), or an `owner/repo` abbreviated GitHub URL (like `rust-cli/cli-template`).
          
          Note that cargo generate will first attempt to interpret the `owner/repo` form as a relative path and only try a GitHub URL if the local path doesn't exist.

  -b, --branch <BRANCH>
          Branch to use when installing from git

  -t, --tag <TAG>
          Tag to use when installing from git

  -p, --path <PATH>
          Local path to copy the template from. Can not be specified together with --git

      --favorite <FAVORITE>
          Generate a favorite template as defined in the config. In case the favorite is undefined, use in place of the `--git` option, otherwise specifies the subfolder

      --list-favorites
          List defined favorite templates from the config

  -n, --name <NAME>
          Directory to create / project name; if the name isn't in kebab-case, it will be converted to kebab-case unless `--force` is given

  -f, --force
          Don't convert the project name to kebab-case before creating the directory. Note that cargo generate won't overwrite an existing directory, even if `--force` is given

  -v, --verbose
          Enables more verbose output

      --template-values-file <TEMPLATE_VALUES_FILE>
          Pass template values through a file Values should be in the format `key=value`, one per line

  -s, --silent
          If silent mode is set all variables will be extracted from the template_values_file. If a value is missing the project generation will fail

  -c, --config <CONFIG>
          Use specific configuration file. Defaults to $CARGO_HOME/cargo-generate or $HOME/.cargo/cargo-generate

      --vcs <VCS>
          Specify the VCS used to initialize the generated template

      --lib
          Populates template variable `crate_type` with value `"lib"`

      --bin
          Populates a template variable `crate_type` with value `"bin"`

  -i, --identity <SSH_IDENTITY>
          Use a different ssh identity

  -d, --define <DEFINE>
          Define a value for use during template expansion

      --init
          Generate the template directly into the current dir. No subfolder will be created and no vcs is initialized

      --destination <DESTINATION>
          Generate the template directly at the given path

      --force-git-init
          Will enforce a fresh git init on the generated project

  -a, --allow-commands
          Allows running system commands without being prompted. Warning: Setting this flag will enable the template to run arbitrary system commands without user confirmation. Use at your own risk and be sure to review the template code beforehand

  -o, --overwrite
          Allow the template to overwrite existing files in the destination

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

This is 90 lines long, and the widest line is 249 characters long. The end result is that it becomes fairly unwieldy to read in a terminal.

Relatedly, the flags don't appear to be grouped in a clear schema, nor are any exclusive relationships between flags made clear from the help text. There's a tension here of course between wanting to be as explanatory as possible in the help text, while also wanting to be brief.

All that said, I think some of the following changes would be good, and if there's agreement / interest from the project, I'm happy to take a crack at them!

• Grouping flags together to indicate exclusivity or shared purpose. For example, exclusive flags which specify the source of the template to be used for generation could be grouped together in the help text.
• Rewriting descriptions for flags to, where possible, be shorter. Otherwise applying hard line wraps to limit the help text width and avoid overflow, or even investigating options for implementing "correct" overflow (proper left alignment) based on calculated width of the terminal at the time of output.
• Making grammar and punctuation usage correct and consistent across descriptions.
• Offering a help subcommand or --help <flag_name> variant to provide a greater amount of detail on specific flags, and including a reference to this expanded-help option in the normal help text.

Happy to also consider other options! All in all I really like cargo-generate and I think some work on this help UI could make the experience of using it even better!