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 add 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

@@ -101,6 +101,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-deprecate.md

@@ -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

@@ -26,9 +26,8 @@ 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.
 
 For example, running `npm explain glob` within npm's source tree will show:
 
@@ -110,6 +109,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

@@ -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
@@ -82,8 +82,8 @@ test-workspaces-fund@1.0.0
 
 Whether or not to output JSON data, rather than the normal output.
 
-* In `npm pkg set` it enables parsing set values with JSON.parse() before
-  saving them to your `package.json`.
+* In `npm pkg set` it enables parsing set values with JSON.parse()
+  before saving them to your `package.json`.
 
 Not supported by all npm commands.
 
@@ -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

@@ -284,6 +284,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.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

@@ -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

@@ -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

@@ -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

@@ -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)

docs/content/commands/npm-publish.md

@@ -11,7 +11,16 @@ description: Publish a package
 <!-- see lib/commands/publish.js -->
 
 ```bash
-npm publish [<folder>]
+npm publish [<@scope>/]<pkg>
+npm publish [<@scope>/]<pkg>@<tag>
+npm publish [<@scope>/]<pkg>@<version>
+npm publish [<@scope>/]<pkg>@<version range>
+npm publish <alias>@npm:<name>
+npm publish <folder>
+npm publish <tarball file>
+npm publish <tarball url>
+npm publish <git:// url>
+npm publish <github username>/<github project>
 ```
 
 <!-- automatically generated, do not edit manually -->
@@ -23,42 +32,26 @@ npm publish [<folder>]
 
 Publishes a package to the registry so that it can be installed by name.
 
-By default npm will publish to the public registry. This can be overridden
-by specifying a different default registry or using a
-[`scope`](/using-npm/scope) in the name (see
+By default npm will publish to the public registry. This can be
+overridden by specifying a different default registry or using a
+[`scope`](/using-npm/scope) in the name, combined with a
+scope-configured registry (see
 [`package.json`](/configuring-npm/package-json)).
 
-* `<folder>`: A folder containing a package.json file
 
-* `<tarball>`: A url or file path to a gzipped tar archive containing a
-  single folder with a package.json file inside.
+A `package` is interpreted the same way as other commands (like `npm
+installl` and can be:
 
-* `[--tag <tag>]`: Registers the published package with the given tag, such
-  that `npm install <name>@<tag>` will install this version.  By default,
-  `npm publish` updates and `npm install` installs the `latest` tag. See
-  [`npm-dist-tag`](npm-dist-tag) for details about tags.
-
-* `[--access <public|restricted>]`: Tells the registry whether this package
-  should be published as public or restricted. Only applies to scoped
-  packages, which default to `restricted`.  If you don't have a paid
-  account, you must publish with `--access public` to publish scoped
-  packages.
-
-* `[--otp <otpcode>]`: If you have two-factor authentication enabled in
-  `auth-and-writes` mode then you can provide a code from your
-  authenticator with this. If you don't include this and you're running
-  from a TTY then you'll be prompted.
-
-* `[--dry-run]`: As of `npm@6`, does everything publish would do except
-  actually publishing to the registry. Reports the details of what would
-  have been published.
-
-* `[--workspaces]`: Enables workspace context while publishing. All
-  workspace packages will be published.
-
-* `[--workspace]`: Enables workspaces context and limits results to only
-  those specified by this config item.  Only the packages in the
-  workspaces given will be published.
+* a) a folder containing a program described by a
+  [`package.json`](/configuring-npm/package-json) file
+* b) a gzipped tarball containing (a)
+* c) a url that resolves to (b)
+* d) a `<name>@<version>` that is published on the registry (see
+  [`registry`](/using-npm/registry)) with (c)
+* e) a `<name>@<tag>` (see [`npm dist-tag`](/commands/npm-dist-tag)) that
+  points to (d)
+* f) a `<name>` that has a "latest" tag satisfying (e)
+* g) a `<git remote url>` that resolves to (a)
 
 The publish will fail if the package name and version combination already
 exists in the specified registry.
@@ -247,6 +240,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm-packlist package](http://npm.im/npm-packlist)
 * [npm registry](/using-npm/registry)
 * [npm scope](/using-npm/scope)

docs/content/commands/npm-rebuild.md

@@ -29,9 +29,8 @@ C++ addons with the new binary.  It is also useful when installing with
 `--ignore-scripts` and `--no-bin-links`, to explicitly choose which
 packages to build and/or link bins.
 
-If one or more package names (and optionally version ranges) are provided,
-then only packages with a name and version matching one of the specifiers
-will be rebuilt.
+If one or more package specs are provided, then only packages with a
+name and version matching one of the specifiers will be rebuilt.
 
 ### Configuration
 
@@ -178,4 +177,5 @@ symlink. This option has no effect on workspaces.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm install](/commands/npm-install)

docs/content/commands/npm-star.md

@@ -87,6 +87,7 @@ password, npm will prompt on the command line for one.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm unstar](/commands/npm-unstar)
 * [npm stars](/commands/npm-stars)
 * [npm view](/commands/npm-view)

docs/content/commands/npm-unpublish.md

@@ -146,6 +146,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm deprecate](/commands/npm-deprecate)
 * [npm publish](/commands/npm-publish)
 * [npm registry](/using-npm/registry)

docs/content/commands/npm-view.md

@@ -203,6 +203,7 @@ the field name.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm search](/commands/npm-search)
 * [npm registry](/using-npm/registry)
 * [npm config](/commands/npm-config)

docs/content/using-npm/config.md

@@ -1518,7 +1518,7 @@ npm init --scope=@foo --yes
 * 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 -->