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

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