Auto merge of #12841 - epage:help, r=weihanglo

fix(help):Clarify install's positional

### What does this PR try to resolve?

- That a version is accepted
- That you are selecting from the source a package which led to part of
  the confusion in #4830

I wonder if we should rename our `CRATE` value names to `PKG`/`PACKAGE`

While doing this, I decided to fix the inconsistency in how we handle value names in help.

### How should we test and review this PR?

### Additional information

Author: bors

src/bin/cargo/commands/bench.rs

@@ -12,6 +12,7 @@ pub fn cli() -> Command {
         )
         .arg(
             Arg::new("args")
+                .value_name("ARGS")
                 .help("Arguments for the bench binary")
                 .num_args(0..)
                 .last(true),

src/bin/cargo/commands/init.rs

@@ -5,7 +5,12 @@ use cargo::ops;
 pub fn cli() -> Command {
     subcommand("init")
         .about("Create a new cargo package in an existing directory")
-        .arg(Arg::new("path").action(ArgAction::Set).default_value("."))
+        .arg(
+            Arg::new("path")
+                .value_name("PATH")
+                .action(ArgAction::Set)
+                .default_value("."),
+        )
         .arg_new_opts()
         .arg_registry("Registry to use")
         .arg_quiet()

src/bin/cargo/commands/install.rs

@@ -16,7 +16,13 @@ use cargo_util::paths;
 pub fn cli() -> Command {
     subcommand("install")
         .about("Install a Rust binary. Default location is $HOME/.cargo/bin")
-        .arg(Arg::new("crate").value_parser(parse_crate).num_args(0..))
+        .arg(
+            Arg::new("crate")
+                .value_name("CRATE[@<VER>]")
+                .help("Select the package from the given source")
+                .value_parser(parse_crate)
+                .num_args(0..),
+        )
         .arg(
             opt("version", "Specify a version to install")
                 .alias("vers")

src/bin/cargo/commands/login.rs

@@ -6,7 +6,7 @@ use crate::command_prelude::*;
 pub fn cli() -> Command {
     subcommand("login")
         .about("Log in to a registry.")
-        .arg(Arg::new("token").action(ArgAction::Set))
+        .arg(Arg::new("token").value_name("TOKEN").action(ArgAction::Set))
         .arg_registry("Registry to use")
         .arg(
             Arg::new("args")

src/bin/cargo/commands/new.rs

@@ -5,7 +5,12 @@ use cargo::ops;
 pub fn cli() -> Command {
     subcommand("new")
         .about("Create a new cargo package at <path>")
-        .arg(Arg::new("path").action(ArgAction::Set).required(true))
+        .arg(
+            Arg::new("path")
+                .value_name("PATH")
+                .action(ArgAction::Set)
+                .required(true),
+        )
         .arg_new_opts()
         .arg_registry("Registry to use")
         .arg_quiet()

src/bin/cargo/commands/owner.rs

@@ -6,7 +6,7 @@ use cargo_credential::Secret;
 pub fn cli() -> Command {
     subcommand("owner")
         .about("Manage the owners of a crate on the registry")
-        .arg(Arg::new("crate").action(ArgAction::Set))
+        .arg(Arg::new("crate").value_name("CRATE").action(ArgAction::Set))
         .arg(
             multi_opt(
                 "add",

src/bin/cargo/commands/pkgid.rs

@@ -6,7 +6,7 @@ use cargo::util::print_available_packages;
 pub fn cli() -> Command {
     subcommand("pkgid")
         .about("Print a fully qualified package specification")
-        .arg(Arg::new("spec").action(ArgAction::Set))
+        .arg(Arg::new("spec").value_name("SPEC").action(ArgAction::Set))
         .arg_quiet()
         .arg_package("Argument to get the package ID specifier for")
         .arg_manifest_path()

src/bin/cargo/commands/run.rs

@@ -16,6 +16,7 @@ pub fn cli() -> Command {
         .about("Run a binary or example of the local package")
         .arg(
             Arg::new("args")
+                .value_name("ARGS")
                 .help("Arguments for the binary or example to run")
                 .value_parser(value_parser!(OsString))
                 .num_args(0..)

src/bin/cargo/commands/rustc.rs

@@ -10,6 +10,7 @@ pub fn cli() -> Command {
         .about("Compile a package, and pass extra options to the compiler")
         .arg(
             Arg::new("args")
+                .value_name("ARGS")
                 .num_args(0..)
                 .help("Extra rustc flags")
                 .trailing_var_arg(true),

src/bin/cargo/commands/rustdoc.rs

@@ -7,6 +7,7 @@ pub fn cli() -> Command {
         .about("Build a package's documentation, using specified custom flags.")
         .arg(
             Arg::new("args")
+                .value_name("ARGS")
                 .help("Extra rustdoc flags")
                 .num_args(0..)
                 .trailing_var_arg(true),