docs: consolidate docs and help for package spec

Many of our commands parse their args via
[npm-package-arg](https://npm.im/npm-package-arg), which is a good
standard way of parsing a "package" argument.  However the docs
surrounding these args are not very consistent.  This can lead to
confusion in commands such as `npm publish` where the behavior is
slightly different than in the past due to this.

This adds a new help command `npm help package-spec` that describes what
this argument is, and can be, and also updates all the commands that
interpret their args this with to refer to them as `<package-spec>`.  It
also adds a link to the new help page on their docs pages.

Author: wraithgar

docs/content/commands/npm-cache.md

@@ -11,11 +11,7 @@ description: Manipulates packages cache
 <!-- see lib/commands/cache.js -->
 
 ```bash
-npm cache add <tarball file>
-npm cache add <folder>
-npm cache add <tarball url>
-npm cache add <git url>
-npm cache add <name>@<version>
+npm cache add <package-spec>
 npm cache clean [<key>]
 npm cache ls [<name>@<version>]
 npm cache verify
@@ -101,6 +97,7 @@ cache`](/commands/npm-cache)
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm folders](/configuring-npm/folders)
 * [npm config](/commands/npm-config)
 * [npmrc](/configuring-npm/npmrc)

docs/content/commands/npm-ci.md

@@ -133,7 +133,7 @@ will *not* run any pre- or post-scripts.
 * Type: null or String
 
 The shell to use for scripts run with the `npm exec`, `npm run` and `npm
-init <pkg>` commands.
+init <package-spec>` commands.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->

docs/content/commands/npm-deprecate.md

@@ -11,7 +11,7 @@ description: Deprecate a version of a package
 <!-- see lib/commands/deprecate.js -->
 
 ```bash
-npm deprecate <pkg>[@<version>] <message>
+npm deprecate <package-spec> <message>
 ```
 
 <!-- automatically generated, do not edit manually -->
@@ -45,8 +45,8 @@ In this case, a version `[email protected]` will also be deprecated.
 You must be the package owner to deprecate something.  See the `owner` and
 `adduser` help topics.
 
-To un-deprecate a package, specify an empty string (`""`) for the `message` 
-argument. Note that you must use double quotes with no space between them to 
+To un-deprecate a package, specify an empty string (`""`) for the `message`
+argument. Note that you must use double quotes with no space between them to
 format an empty string.
 
 ### Configuration
@@ -82,6 +82,7 @@ password, npm will prompt on the command line for one.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm publish](/commands/npm-publish)
 * [npm registry](/using-npm/registry)
 * [npm owner](/commands/npm-owner)

docs/content/commands/npm-dist-tag.md

@@ -11,9 +11,9 @@ description: Modify package distribution tags
 <!-- see lib/commands/dist-tag.js -->
 
 ```bash
-npm dist-tag add <pkg>@<version> [<tag>]
-npm dist-tag rm <pkg> <tag>
-npm dist-tag ls [<pkg>]
+npm dist-tag add <package-spec (with version)> [<tag>]
+npm dist-tag rm <package-spec> <tag>
+npm dist-tag ls [<package-spec>]
 
 alias: dist-tags
 ```
@@ -27,11 +27,11 @@ alias: dist-tags
 
 Add, remove, and enumerate distribution tags on a package:
 
-* add: Tags the specified version of the package with the specified tag, or
-  the `--tag` config if not specified. If you have two-factor
-  authentication on auth-and-writes then you’ll need to include a one-time
-  password on the command line with `--otp <one-time password>`, or at the
-  OTP prompt.
+* add: Tags the specified version of the package with the specified tag,
+  or the `--tag` config if not specified. If you have two-factor
+  authentication on auth-and-writes then you’ll need to include a
+  one-time password on the command line with
+  `--otp <one-time password>`, or at the OTP prompt.
 
 * rm: Clear a tag that is no longer in use from the package. If you have
   two-factor authentication on auth-and-writes then you’ll need to include
@@ -168,6 +168,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm publish](/commands/npm-publish)
 * [npm install](/commands/npm-install)
 * [npm dedupe](/commands/npm-dedupe)

docs/content/commands/npm-explain.md

@@ -11,7 +11,7 @@ description: Explain installed packages
 <!-- see lib/commands/explain.js -->
 
 ```bash
-npm explain <folder | specifier>
+npm explain <package-spec>
 
 alias: why
 ```
@@ -26,9 +26,10 @@ alias: why
 This command will print the chain of dependencies causing a given package
 to be installed in the current project.
 
-Positional arguments can be either folders within `node_modules`, or
-`name@version-range` specifiers, which will select the dependency
-relationships to explain.
+If one or more package specs are provided, then only packages matching
+one of the specifiers will have their relationships explained.
+
+The package spec can also refer to a folder within `./node_modules`
 
 For example, running `npm explain glob` within npm's source tree will show:
 
@@ -110,6 +111,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm config](/commands/npm-config)
 * [npmrc](/configuring-npm/npmrc)
 * [npm folders](/configuring-npm/folders)

docs/content/commands/npm-fund.md

@@ -11,7 +11,7 @@ description: Retrieve funding information
 <!-- see lib/commands/fund.js -->
 
 ```bash
-npm fund [[<@scope>/]<pkg>]
+npm fund [<package-spec>]
 ```
 
 <!-- automatically generated, do not edit manually -->
@@ -23,22 +23,22 @@ npm fund [[<@scope>/]<pkg>]
 
 This command retrieves information on how to fund the dependencies of a
 given project. If no package name is provided, it will list all
-dependencies that are looking for funding in a tree structure, listing the
-type of funding and the url to visit. If a package name is provided then it
-tries to open its funding url using the `--browser` config param; if there
-are multiple funding sources for the package, the user will be instructed
-to pass the `--which` option to disambiguate.
+dependencies that are looking for funding in a tree structure, listing
+the type of funding and the url to visit. If a package name is provided
+then it tries to open its funding url using the `--browser` config
+param; if there are multiple funding sources for the package, the user
+will be instructed to pass the `--which` option to disambiguate.
 
 The list will avoid duplicated entries and will stack all packages that
-share the same url as a single entry. Thus, the list does not have the same
-shape of the output from `npm ls`.
+share the same url as a single entry. Thus, the list does not have the
+same shape of the output from `npm ls`.
 
 #### Example
 
 ### Workspaces support
 
-It's possible to filter the results to only include a single workspace and its
-dependencies using the `workspace` config option.
+It's possible to filter the results to only include a single workspace
+and its dependencies using the `workspace` config option.
 
 #### Example:
 
@@ -58,8 +58,8 @@ [email protected]
     `-- [email protected]
 ```
 
-And here is an example of the expected result when filtering only by
-a specific workspace `a` in the same project:
+And here is an example of the expected result when filtering only by a
+specific workspace `a` in the same project:
 
 ```bash
 $ npm fund -w a
@@ -156,6 +156,7 @@ If there are multiple funding sources, which 1-indexed source URL to open.
 
 ## See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm install](/commands/npm-install)
 * [npm docs](/commands/npm-docs)
 * [npm ls](/commands/npm-ls)

docs/content/commands/npm-init.md

@@ -11,9 +11,8 @@ description: Create a package.json file
 <!-- see lib/commands/init.js -->
 
 ```bash
-npm init [--force|-f|--yes|-y|--scope]
+npm init <package-spec> (same as `npx <package-spec>)
 npm init <@scope> (same as `npx <@scope>/create`)
-npm init [<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`)
 
 aliases: create, innit
 ```
@@ -204,6 +203,39 @@ mistakes, unnecessary performance degradation, and malicious input.
 If you don't have a clear idea of what you want to do, it is strongly
 recommended that you do not use this option!
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
+#### `scope`
+
+* Default: the scope of the current project, if any, or ""
+* Type: String
+
+Associate an operation with a scope for a scoped registry.
+
+Useful when logging in to or out of a private registry:
+
+```
+# log in, linking the scope to the custom registry
+npm login --scope=@mycorp --registry=https://registry.mycorp.com
+
+# log out, removing the link and the auth token
+npm logout --scope=@mycorp
+```
+
+This will cause `@mycorp` to be mapped to the registry for future
+installation of packages specified according to the pattern
+`@mycorp/package`.
+
+This will also cause `npm init` to create a scoped package.
+
+```
+# accept all defaults, and create a package named "@foo/whatever",
+# instead of just named "whatever"
+npm init --scope=@foo --yes
+```
+
+
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
@@ -284,6 +316,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [init-package-json module](http://npm.im/init-package-json)
 * [package.json](/configuring-npm/package-json)
 * [npm version](/commands/npm-version)

docs/content/commands/npm-install-ci-test.md

@@ -79,7 +79,7 @@ will *not* run any pre- or post-scripts.
 * Type: null or String
 
 The shell to use for scripts run with the `npm exec`, `npm run` and `npm
-init <pkg>` commands.
+init <package-spec>` commands.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->

docs/content/commands/npm-install-test.md

@@ -11,16 +11,7 @@ description: Install package(s) and run tests
 <!-- see lib/commands/install-test.js -->
 
 ```bash
-npm install-test [<@scope>/]<pkg>
-npm install-test [<@scope>/]<pkg>@<tag>
-npm install-test [<@scope>/]<pkg>@<version>
-npm install-test [<@scope>/]<pkg>@<version range>
-npm install-test <alias>@npm:<name>
-npm install-test <folder>
-npm install-test <tarball file>
-npm install-test <tarball url>
-npm install-test <git:// url>
-npm install-test <github username>/<github project>
+npm install-test [<package-spec> ...]
 
 alias: it
 ```

docs/content/commands/npm-install.md

@@ -11,16 +11,7 @@ description: Install a package
 <!-- see lib/commands/install.js -->
 
 ```bash
-npm install [<@scope>/]<pkg>
-npm install [<@scope>/]<pkg>@<tag>
-npm install [<@scope>/]<pkg>@<version>
-npm install [<@scope>/]<pkg>@<version range>
-npm install <alias>@npm:<name>
-npm install <folder>
-npm install <tarball file>
-npm install <tarball url>
-npm install <git:// url>
-npm install <github username>/<github project>
+npm install [<package-spec> ...]
 
 aliases: add, i, in, ins, inst, insta, instal, isnt, isnta, isntal, isntall
 ```