docs: updated scripts docs in using-npm section

- A continuation of @seanhealy's work

PR-URL: https://github.com/npm/cli/pull/729
Credit: @
Close: #729
Reviewed-by: @Darcy Clarke

1 files changed, 71 insertions, 104 deletions

diff --git a/docs/content/using-npm/scripts.md b/docs/content/using-npm/scripts.md
index d464a7f92..7de73077b 100644
--- a/docs/content/using-npm/scripts.md
+++ b/docs/content/using-npm/scripts.md
@@ -10,130 +10,64 @@ description: How npm handles the "scripts" field
 
 ### Description
 
-The `"scripts"` property of of your `package.json` file supports a number of built-in scripts and their preset life cycle events as well as arbitrary scripts which can be executed by running `npm run <stage>`. *Pre* and *post* commands with matching names will be run for those as well (e.g. `premyscript`, `myscript`,
-`postmyscript`). Scripts from dependencies can be run with `npm explore
-<pkg> -- npm run <stage>`.
-
-* `prepublish` (_as of npm@5, `prepublish` is deprecated. Use `prepare` for
-    build steps and `prepublishOnly` for upload-only._):
-  * Runs BEFORE the package is packed and published, as well as on local `npm
-  install` without any arguments. (See below)
-* `prepare`:
-  * Runs both BEFORE the package is packed and published, and on local
-    `npm install` without any arguments (See below). This is run AFTER
-    `prepublish`, but BEFORE `prepublishOnly`.
-  * If a package being installed through git contains a `prepare` script, its
-    `dependencies` and `devDependencies` will be installed, and the prepare
-    script will be run, before the package is packaged and installed.
-* `prepublishOnly`:
-  * Runs BEFORE the package is prepared and packed, ONLY on `npm publish`.
-    (See below.)
-* `prepack`:
-  * Runs BEFORE a tarball is packed (on `npm pack`, `npm publish`, and when
-    installing git dependencies)
-* `postpack`:
-  * Runs AFTER the tarball has been generated and moved to its final destination.
-* `publish`, `postpublish`:
-  * Runs AFTER the package is published.
-* `preinstall`:
-  * Runs BEFORE the package is installed
-* `install`, `postinstall`:
-  * Runs AFTER the package is installed.
-* `preuninstall`, `uninstall`:
-  * Runs BEFORE the package is uninstalled.
-* `postuninstall`:
-  * Runs AFTER the package is uninstalled.
-* `preversion`:
-  * Runs BEFORE bumping the package version.
-* `version`:
-  * Runs AFTER bumping the package version, but BEFORE commit.
-* `postversion`:
-  * Runs AFTER bumping the package version, and AFTER commit.
-* `pretest`, `test`, `posttest`:
-  * Run by the `npm test` command.
-* `prestop`, `stop`, `poststop`:
-  * Run by the `npm stop` command.
-* `prestart`, `start`, `poststart`:
-  * Run by the `npm start` command.
-* `prerestart`, `restart`, `postrestart`:
-  * Run by the `npm restart` command. Note: `npm restart` will run the
-  stop and start scripts if no `restart` script is provided.
-* `preshrinkwrap`, `shrinkwrap`, `postshrinkwrap`:
-  * Run by the `npm shrinkwrap` command.
-
-Additionally, arbitrary scripts can be executed by running
-`npm run-script <stage>`. *Pre* and *post* commands with matching names will
-be run for those as well (e.g. `premyscript`, `myscript`, `postmyscript`).
-Scripts from dependencies can be run with
-`npm explore <pkg> -- npm run <stage>`.
-
-### Life Cycle
-
-npm commands such as `npm install` and `npm publish` will fire life cycle
-hooks as specified in your `package.json` file. These hooks are as follows
-for each command.
+The `"scripts"` property of of your `package.json` file supports a number of built-in scripts and their preset life cycle events as well as arbitrary scripts. These all can be executed by running `npm run-script <stage>` or `npm run <stage>` for short. *Pre* and *post* commands with matching names will be run for those as well (e.g. `premyscript`, `myscript`, `postmyscript`). Scripts from dependencies can be run with `npm explore <pkg> -- npm run <stage>`.
 
-#### [`npm publish`](/cli-commands/npm-publish)
+### Pre & Post Scripts
 
-* `prepublishOnly`
-* `prepare`
+To create "pre" or "post" scripts for any scripts defined in the `"scripts"` section of the `package.json`, simply create another script *with a matching name* and add "pre" or "post" to the beginning of them.
 
-#### [`npm pack`](/cli-commands/npm-pack)
+```json
+{
+  "scripts": {
+    "precompress": "{{ executes BEFORE the `compress` script }}",
+    "compress": "{{ run command to compress files }}",
+    "postcompress": "{{ executes AFTER `compress` script }}"
+  }
+}
+```
 
-* `prepack`
+### Life Cycle Scripts
 
-#### [`npm install`](/cli-commands/npm-install)
+There are some special life cycle scripts that happen only in certain situations. These scripts happen in addtion to the "pre" and "post" script.
+* `prepare`, `prepublish`, `prepublishOnly`, `prepack`, `postpack`
 
-* `preinstall`
-  * Run BEFORE the package is installed
-* `install`, `postinstall`
-  * Run AFTER the package is installed.
+**prepare** (since `npm@4.0.0`)
+* Runs BEFORE the package is packed
+* Runs BEFORE the package is published
+* Runs on local `npm install` without any arguments
+* Run AFTER `prepublish`, but BEFORE `prepublishOnly`
+* NOTE: If a package being installed through git contains a `prepare` script, its `dependencies` and `devDependencies` will be installed, and the prepare script will be run, before the package is packaged and installed.
 
-Also triggers
+**prepublish** (DEPRECATED)
+* Same as `prepare`
 
-* `prepublish` (when on local)
-* `prepare` (when on local)
+**prepublishOnly**
+* Runs BEFORE the package is prepared and packed, ONLY on `npm publish`.
 
-#### `start`
+**prepack**
+* Runs BEFORE a tarball is packed (on "`npm pack`", "`npm publish`", and when installing a git dependencies).
+* NOTE: "`npm run pack`" is NOT the same as "`npm pack`". "`npm run pack`" is an arbitrary user defined script name, where as, "`npm pack`" is a CLI defined command.
 
-`npm run start` has an `npm start` shorthand.
+**postpack**
+* Runs AFTER the tarball has been generated and moved to its final destination.
 
-* `prestart`
-* `start`
-* `poststart`
+#### Prepare and Prepublish
 
-#### Prepublish and Prepare
+**Deprecation Note: prepublish**
 
-#### Deprecation Note
+Since `npm@1.1.71`, the npm CLI has run the `prepublish` script for both `npm publish` and `npm install`, because it's a convenient way to prepare a package for use (some common use cases are described in the section below).  It has also turned out to be, in practice, [very confusing](https://github.com/npm/npm/issues/10074).  As of `npm@4.0.0`, a new event has been introduced, `prepare`, that preserves this existing behavior. A _new_ event, `prepublishOnly` has been added as a transitional strategy to allow users to avoid the confusing behavior of existing npm versions and only run on `npm publish` (for instance, running the tests one last time to ensure they're in good shape).
 
-Since `npm@1.1.71`, the npm CLI has run the `prepublish` script for both `npm
-publish` and `npm install`, because it's a convenient way to prepare a package
-for use (some common use cases are described in the section below).  It has
-also turned out to be, in practice, [very
-confusing](https://github.com/npm/npm/issues/10074).  As of `npm@4.0.0`, a new
-event has been introduced, `prepare`, that preserves this existing behavior. A
-_new_ event, `prepublishOnly` has been added as a transitional strategy to
-allow users to avoid the confusing behavior of existing npm versions and only
-run on `npm publish` (for instance, running the tests one last time to ensure
-they're in good shape).
+See <https://github.com/npm/npm/issues/10074> for a much lengthier justification, with further reading, for this change.
 
-See <https://github.com/npm/npm/issues/10074> for a much lengthier
-justification, with further reading, for this change.
+**Use Cases**
 
-#### Use Cases
-
-If you need to perform operations on your package before it is used, in a way
-that is not dependent on the operating system or architecture of the
-target system, use a `prepublish` script.  This includes
-tasks such as:
+If you need to perform operations on your package before it is used, in a way that is not dependent on the operating system or architecture of the target system, use a `prepublish` script. This includes tasks such as:
 
 * Compiling CoffeeScript source code into JavaScript.
 * Creating minified versions of JavaScript source code.
 * Fetching remote resources that your package will use.
 
-The advantage of doing these things at `prepublish` time is that they can be done once, in a
-single place, thus reducing complexity and variability.
-Additionally, this means that:
+The advantage of doing these things at `prepublish` time is that they can be done once, in a single place, thus reducing complexity and variability. Additionally, this means that:
 
 * You can depend on `coffee-script` as a `devDependency`, and thus
   your users don't need to have it installed.
@@ -142,8 +76,41 @@ Additionally, this means that:
 * You don't need to rely on your users having `curl` or `wget` or
   other system tools on the target machines.
 
-### Default Values
+### Life Cycle Operation Order
+
+#### [`npm publish`](/cli-commands/npm-publish)
+
+* `prepublishOnly`
+* `prepare`
+* `prepublish`
+* `publish`
+* `postpublish`
+
+#### [`npm pack`](/cli-commands/npm-pack)
+
+* `prepack`
+* `postpack`
+
+#### [`npm install`](/cli-commands/npm-install)
+
+* `preinstall`
+* `install`
+* `postinstall`
+
+Also triggers
 
+* `prepublish` (when on local)
+* `prepare` (when on local)
+
+#### [`npm start`](/cli-commands/npm-start)
+
+`npm run start` has an `npm start` shorthand.
+
+* `prestart`
+* `start`
+* `poststart`
+
+### Default Values
 npm will default some script values based on package contents.
 
 * `"start": "node server.js"`: