From 8c8bec0701586c2a0169ef5f601683e61837e901 Mon Sep 17 00:00:00 2001
From: Toru Nagashima <star.ctor@gmail.com>
Date: Sat, 26 Aug 2017 15:35:04 +0900
Subject: [PATCH] Docs: update docs

---
 README.md           | 39 +++++++++++++++++++--------------------
 docs/node-api.md    |  2 +-
 docs/npm-run-all.md | 41 +++++++++++------------------------------
 docs/run-p.md       | 31 ++++++++-----------------------
 docs/run-s.md       | 31 ++++++++-----------------------
 5 files changed, 47 insertions(+), 97 deletions(-)

diff --git a/README.md b/README.md
index e61dfb9..68fd0a8 100644
--- a/README.md
+++ b/README.md
@@ -12,15 +12,14 @@
 
 A CLI tool to run multiple npm-scripts in parallel or sequential.
 
-```
-$ npm-run-all clean lint build:*
-```
+## ⤴️ Motivation
 
-```
-$ npm-run-all --parallel watch:*
-```
+- **Simplify.** The official `npm run-script` command cannot run multiple scripts, so if we want to run multiple scripts, it's redundant a bit. Let's shorten it by glob-like patterns.<br>
+  Before: `npm run clean && npm run build:css && npm run build:js && npm run build:html`<br>
+  After: `npm-run-all clean build:*`
+- **Cross platform.** We sometimes use `&` to run multiple command in parallel, but `cmd.exe` (`npm run-script` uses it by default) does not support the `&`. Half of Node.js users is using it on Windows, so the use of `&` might block contributions. `npm-run-all --parallel` works well on Windows as well.
 
-## Installation
+## 💿 Installation
 
 ```bash
 $ npm install npm-run-all --save-dev
@@ -29,9 +28,10 @@ $ yarn add npm-run-all --dev
 ```
 
 - It requires `Node@>=4`.
-- The `npm-run-all` package introduces 3 CLI commands: `npm-run-all`, `run-s`, and `run-p`.
 
-## CLI Commands
+## 📖 Usage
+
+### CLI Commands
 
 This `npm-run-all` package provides 3 CLI commands.
 
@@ -46,22 +46,23 @@ Both [run-s] and [run-p] are shorthand commands.
 [run-s] is for sequential, [run-p] is for parallel.
 We can make simple plans with those commands.
 
-### Yarn Compatibility
+#### Yarn Compatibility
+
+If a script is invoked with Yarn, `npm-run-all` will correctly use Yarn to execute the plan's child scripts.
 
-If a script is invoked with Yarn, npm-run-all will correctly use Yarn to execute the plan's child scripts.
-## Node API
+### Node API
 
 This `npm-run-all` package provides Node API.
 
 - [Node API]
 
-## Changelog
+## 📰 Changelog
 
 - https://github.com/mysticatea/npm-run-all/releases
 
-## Contributing
+## 🍻 Contributing
 
-Thank you for contributing!
+Welcome♡
 
 ### Bug Reports or Feature Requests
 
@@ -73,18 +74,16 @@ Please use GitHub Pull Requests.
 
 I'm not familiar with English, so I especially thank you for documents' corrections.
 
-### Feature Implementing
+### Implementing
 
 Please use GitHub Pull Requests.
 
 There are some npm-scripts to help developments.
-Those work on Windows, Mac, or Linux (by the way, I'm developping `npm-run-all` on Windows).
 
 - **npm test** - Run tests and collect coverage.
-- **npm run build** - Make `lib` directory from `src` directory.
-- **npm run clean** - Delete directories (folders) which are created by other commands.
+- **npm run clean** - Delete temporary files.
 - **npm run lint** - Run ESLint.
-- **npm run watch** - Run tests (not collect coverage) when each file was modified.
+- **npm run watch** - Run tests (not collect coverage) on every file change.
 
 [npm-run-all]: docs/npm-run-all.md
 [run-s]: docs/run-s.md
diff --git a/docs/node-api.md b/docs/node-api.md
index 9e6ffe0..44f9bf6 100644
--- a/docs/node-api.md
+++ b/docs/node-api.md
@@ -5,7 +5,7 @@
 
 A Node module to run given npm-scripts in parallel or sequential.
 
-```
+```js
 const runAll = require("npm-run-all");
 
 runAll(["clean", "lint", "build:*"], {parallel: false})
diff --git a/docs/npm-run-all.md b/docs/npm-run-all.md
index dbf75da..f8e32d7 100644
--- a/docs/npm-run-all.md
+++ b/docs/npm-run-all.md
@@ -3,25 +3,6 @@
 
 # `npm-run-all` command
 
-A CLI command to run given npm-scripts in parallel or sequential.
-
-```
-> npm-run-all clean lint build:*
-
-> npm-run-all --parallel watch:*
-```
-
-## Installation
-
-```
-> npm install -g npm-run-all
-```
-
-- Requires `Node@>=0.10` and `npm@>=2`
-- The `npm-run-all` package introduces 3 CLI commands: `npm-run-all`, `run-s`, and `run-p`.
-
-## Usage
-
 ```
 Usage:
     $ npm-run-all [--help | -h | --version | -v]
@@ -88,7 +69,7 @@ On the other hand, this `npm-run-all` command runs multiple scripts in parallel
 ### Run scripts sequentially
 
 ```
-npm-run-all clean lint build
+$ npm-run-all clean lint build
 ```
 
 This is same as `npm run clean && npm run lint && npm run build`.
@@ -99,7 +80,7 @@ If `--continue-on-error` option is given, this behavior will be disabled.
 ### Run scripts in parallel
 
 ```
-npm-run-all --parallel lint build
+$ npm-run-all --parallel lint build
 ```
 
 This is similar to `npm run lint & npm run build`.
@@ -112,19 +93,19 @@ If `--continue-on-error` option is given, this behavior will be disabled.
 ### Run a mix of sequential and parallel scripts
 
 ```
-npm-run-all clean lint --parallel watch:html watch:js
+$ npm-run-all clean lint --parallel watch:html watch:js
 ```
 
 1. First, this runs `clean` and `lint` sequentially / serially.
 2. Next, runs `watch:html` and `watch:js` in parallel.
 
 ```
-npm-run-all a b --parallel c d --sequential e f --parallel g h i
+$ npm-run-all a b --parallel c d --sequential e f --parallel g h i
 ```
 or
 
 ```
-npm-run-all a b --parallel c d --serial e f --parallel g h i
+$ npm-run-all a b --parallel c d --serial e f --parallel g h i
 ```
 
 1. First, runs `a` and `b` sequentially / serially.
@@ -138,14 +119,14 @@ We can use [glob]-like patterns to specify npm-scripts.
 The difference is one -- the separator is `:` instead of `/`.
 
 ```
-> npm-run-all --parallel watch:*
+$ npm-run-all --parallel watch:*
 ```
 
 In this case, runs sub scripts of `watch`. For example: `watch:html`, `watch:js`.
 But, doesn't run sub-sub scripts. For example: `watch:js:index`.
 
 ```
-> npm-run-all --parallel watch:**
+$ npm-run-all --parallel watch:**
 ```
 
 If we use a globstar `**`, runs both sub scripts and sub-sub scripts.
@@ -158,8 +139,8 @@ We can enclose a script name or a pattern in quotes to use arguments.
 The following 2 commands are similar.
 
 ```
-> npm-run-all --parallel "build:* -- --watch"
-> npm run build:aaa -- --watch & npm run build:bbb -- --watch
+$ npm-run-all --parallel "build:* -- --watch"
+$ npm run build:aaa -- --watch & npm run build:bbb -- --watch
 ```
 
 When we use a pattern, arguments are forwarded to every matched script.
@@ -169,7 +150,7 @@ When we use a pattern, arguments are forwarded to every matched script.
 We can use placeholders to give the arguments preceded by `--` to scripts.
 
 ```
-> npm-run-all build "start-server -- --port {1}" -- 8080
+$ npm-run-all build "start-server -- --port {1}" -- 8080
 ```
 
 This is useful to pass through arguments from `npm run` command.
@@ -183,7 +164,7 @@ This is useful to pass through arguments from `npm run` command.
 ```
 
 ```
-> npm run start 8080
+$ npm run start 8080
 
 > example@0.0.0 start /path/to/package.json
 > npm-run-all build "start-server -- --port {1}" -- "8080"
diff --git a/docs/run-p.md b/docs/run-p.md
index 46e92e9..b6ed297 100644
--- a/docs/run-p.md
+++ b/docs/run-p.md
@@ -6,21 +6,6 @@
 A CLI command to run given npm-scripts in parallel.
 This command is the shorthand of `npm-run-all -p`.
 
-```
-> run-p watch:*
-```
-
-## Installation
-
-```
-> npm install -g npm-run-all
-```
-
-- Requires `Node@>=0.10` and `npm@>=2`
-- The `npm-run-all` package introduces 3 CLI commands: `npm-run-all`, `run-s`, and `run-p`.
-
-## Usage
-
 ```
 Usage:
     $ run-p [--help | -h | --version | -v]
@@ -85,8 +70,8 @@ The following 2 commands are similar.
 The `run-p` command is shorter and **available on Windows**.
 
 ```
-> run-p lint build
-> npm run lint & npm run build
+$ run-p lint build
+$ npm run lint & npm run build
 ```
 
 **Note1:** If a script exited with a non-zero code, the other scripts and those descendant processes are killed with `SIGTERM` (On Windows, with `taskkill.exe /F /T`).
@@ -100,14 +85,14 @@ We can use [glob]-like patterns to specify npm-scripts.
 The difference is one -- the separator is `:` instead of `/`.
 
 ```
-> run-p watch:*
+$ run-p watch:*
 ```
 
 In this case, runs sub scripts of `watch`. For example: `watch:html`, `watch:js`.
 But, doesn't run sub-sub scripts. For example: `watch:js:index`.
 
 ```
-> run-p watch:**
+$ run-p watch:**
 ```
 
 If we use a globstar `**`, runs both sub scripts and sub-sub scripts.
@@ -120,8 +105,8 @@ We can enclose a script name or a pattern in quotes to use arguments.
 The following 2 commands are similar.
 
 ```
-> run-p "build:* -- --watch"
-> npm run build:aaa -- --watch & npm run build:bbb -- --watch
+$ run-p "build:* -- --watch"
+$ npm run build:aaa -- --watch & npm run build:bbb -- --watch
 ```
 
 When we use a pattern, arguments are forwarded to every matched script.
@@ -131,7 +116,7 @@ When we use a pattern, arguments are forwarded to every matched script.
 We can use placeholders to give the arguments preceded by `--` to scripts.
 
 ```
-> run-p "start-server -- --port {1}" -- 8080
+$ run-p "start-server -- --port {1}" -- 8080
 ```
 
 This is useful to pass through arguments from `npm run` command.
@@ -145,7 +130,7 @@ This is useful to pass through arguments from `npm run` command.
 ```
 
 ```
-> npm run start 8080
+$ npm run start 8080
 
 > example@0.0.0 start /path/to/package.json
 > run-p "start-server -- --port {1}" -- "8080"
diff --git a/docs/run-s.md b/docs/run-s.md
index ce698bb..cf62681 100644
--- a/docs/run-s.md
+++ b/docs/run-s.md
@@ -6,21 +6,6 @@
 A CLI command to run given npm-scripts sequentially.
 This command is the shorthand of `npm-run-all -s`.
 
-```
-> run-s lint build:* test
-```
-
-## Installation
-
-```
-> npm install -g npm-run-all
-```
-
-- Requires `Node@>=0.10` and `npm@>=2`
-- The `npm-run-all` package introduces 3 CLI commands: `npm-run-all`, `run-s`, and `run-p`.
-
-## Usage
-
 ```
 Usage:
     $ run-s [--help | -h | --version | -v]
@@ -79,8 +64,8 @@ The following 2 commands are the same.
 The `run-s` command is shorter.
 
 ```
-> run-s clean lint build
-> npm run clean && npm run lint && npm run build
+$ run-s clean lint build
+$ npm run clean && npm run lint && npm run build
 ```
 
 **Note:** If a script exited with a non-zero code, the following scripts are not run.
@@ -91,14 +76,14 @@ We can use [glob]-like patterns to specify npm-scripts.
 The difference is one -- the separator is `:` instead of `/`.
 
 ```
-> run-s build:*
+$ run-s build:*
 ```
 
 In this case, runs sub scripts of `build`. For example: `build:html`, `build:js`.
 But, doesn't run sub-sub scripts. For example: `build:js:index`.
 
 ```
-> run-s build:**
+$ run-s build:**
 ```
 
 If we use a globstar `**`, runs both sub scripts and sub-sub scripts.
@@ -111,8 +96,8 @@ We can enclose a script name or a pattern in quotes to use arguments.
 The following 2 commands are the same.
 
 ```
-> run-s start:server "delay 3000" start:client
-> npm run start:server && npm run delay 3000 && npm run start:client
+$ run-s start:server "delay 3000" start:client
+$ npm run start:server && npm run delay 3000 && npm run start:client
 ```
 
 When we use a pattern, arguments are forwarded to every matched script.
@@ -122,7 +107,7 @@ When we use a pattern, arguments are forwarded to every matched script.
 We can use placeholders to give the arguments preceded by `--` to scripts.
 
 ```
-> run-s build "start-server -- --port {1}" -- 8080
+$ run-s build "start-server -- --port {1}" -- 8080
 ```
 
 This is useful to pass through arguments from `npm run` command.
@@ -136,7 +121,7 @@ This is useful to pass through arguments from `npm run` command.
 ```
 
 ```
-> npm run start 8080
+$ npm run start 8080
 
 > example@0.0.0 start /path/to/package.json
 > run-s build "start-server -- --port {1}" -- "8080"
-- 
GitLab