docs: consolidate docs and help for package spec (#5048)

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.

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 `my-thing@1.0.0-beta.0` 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 @@ test-workspaces-fund@1.0.0
     `-- bar@2.0.0
 ```
 
-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
 ```

docs/content/commands/npm-link.md

@@ -11,8 +11,7 @@ description: Symlink a package folder
 <!-- see lib/commands/link.js -->
 
 ```bash
-npm link (in package dir)
-npm link [<@scope>/]<pkg>[@<version>]
+npm link [<package-spec>]
 
 alias: ln
 ```
@@ -29,11 +28,11 @@ test iteratively without having to continually rebuild.
 
 Package linking is a two-step process.
 
-First, `npm link` in a package folder will create a symlink in the global
-folder `{prefix}/lib/node_modules/<package>` that links to the package
-where the `npm link` command was executed. It will also link any bins in
-the package to `{prefix}/bin/{name}`.  Note that `npm link` uses the global
-prefix (see `npm prefix -g` for its value).
+First, `npm link` in a package folder with no arguments will create a
+symlink in the global folder `{prefix}/lib/node_modules/<package>` that
+links to the package where the `npm link` command was executed. It will
+also link any bins in the package to `{prefix}/bin/{name}`.  Note that
+`npm link` uses the global prefix (see `npm prefix -g` for its value).
 
 Next, in some other location, `npm link package-name` will create a
 symbolic link from globally-installed `package-name` to `node_modules/` of
@@ -399,6 +398,7 @@ symlink. This option has no effect on workspaces.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm developers](/using-npm/developers)
 * [package.json](/configuring-npm/package-json)
 * [npm install](/commands/npm-install)

docs/content/commands/npm-ls.md

@@ -11,7 +11,7 @@ description: List installed packages
 <!-- see lib/commands/ls.js -->
 
 ```bash
-npm ls [[<@scope>/]<pkg> ...]
+npm ls <package-spec>
 
 alias: list
 ```
@@ -301,6 +301,7 @@ symlink. This option has no effect on workspaces.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm explain](/commands/npm-explain)
 * [npm config](/commands/npm-config)
 * [npmrc](/configuring-npm/npmrc)

docs/content/commands/npm-outdated.md

@@ -11,7 +11,7 @@ description: Check for outdated packages
 <!-- see lib/commands/outdated.js -->
 
 ```bash
-npm outdated [[<@scope>/]<pkg> ...]
+npm outdated [<package-spec> ...]
 ```
 
 <!-- automatically generated, do not edit manually -->
@@ -192,6 +192,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm update](/commands/npm-update)
 * [npm dist-tag](/commands/npm-dist-tag)
 * [npm registry](/using-npm/registry)

docs/content/commands/npm-owner.md

@@ -11,9 +11,9 @@ description: Manage package owners
 <!-- see lib/commands/owner.js -->
 
 ```bash
-npm owner add <user> [<@scope>/]<pkg>
-npm owner rm <user> [<@scope>/]<pkg>
-npm owner ls [<@scope>/]<pkg>
+npm owner add <user> <package-spec>
+npm owner rm <user> <package-spec>
+npm owner ls <package-spec>
 
 alias: author
 ```
@@ -123,6 +123,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm profile](/commands/npm-profile)
 * [npm publish](/commands/npm-publish)
 * [npm registry](/using-npm/registry)

docs/content/commands/npm-pack.md

@@ -11,7 +11,7 @@ description: Create a tarball from a package
 <!-- see lib/commands/pack.js -->
 
 ```bash
-npm pack [[<@scope>/]<pkg>...]
+npm pack <package-spec>
 ```
 
 <!-- automatically generated, do not edit manually -->
@@ -144,6 +144,7 @@ If no arguments are supplied, then npm packs the current package folder.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm-packlist package](http://npm.im/npm-packlist)
 * [npm cache](/commands/npm-cache)
 * [npm publish](/commands/npm-publish)