doc: lint README.md

Fixes grammar, removes extra lines and spaces, etc. Also removes a few
references to `node-waf`, which was removed ~6 years ago now. Happy to
add back if people still need that information.

PR-URL: #1498
Reviewed-By: Vse Mozhet Byt <[email protected]>
Reviewed-By: Richard Lau <[email protected]>

Author: maclover7

README.md

@@ -1,28 +1,21 @@
-node-gyp
-=========
-## Node.js native addon build tool
+# `node-gyp` - Node.js native addon build tool
 
 `node-gyp` is a cross-platform command-line tool written in Node.js for compiling
-native addon modules for Node.js.  It bundles the [gyp](https://gyp.gsrc.io)
+native addon modules for Node.js. It bundles the [gyp](https://gyp.gsrc.io)
 project used by the Chromium team and takes away the pain of dealing with the
-various differences in build platforms. It is the replacement to the `node-waf`
-program which is removed for node `v0.8`. If you have a native addon for node that
-still has a `wscript` file, then you should definitely add a `binding.gyp` file
-to support the latest versions of node.
+various differences in build platforms.
 
-Multiple target versions of node are supported (i.e. `0.8`, ..., `4`, `5`, `6`,
-etc.), regardless of what version of node is actually installed on your system
+Multiple target versions of Node.js are supported (i.e. `0.8`, ..., `4`, `5`, `6`,
+etc.), regardless of what version of Node.js is actually installed on your system
 (`node-gyp` downloads the necessary development files or headers for the target version).
 
 ## Features
 
  * Easy to use, consistent interface
  * Same commands to build your module on every platform
- * Supports multiple target versions of Node
+ * Supports multiple target versions of Node.js
 
-
-Installation
-------------
+## Installation
 
 You can install with `npm`:
 
@@ -80,16 +73,15 @@ version `node-gyp` uses by setting the '--python' variable:
 $ node-gyp --python /path/to/python2.7
 ```
 
-If `node-gyp` is called by way of `npm` *and* you have multiple versions of
+If `node-gyp` is called by way of `npm`, *and* you have multiple versions of
 Python installed, then you can set `npm`'s 'python' config key to the appropriate
 value:
 
 ``` bash
 $ npm config set python /path/to/executable/python2.7
 ```
 
-How to Use
-----------
+## How to Use
 
 To compile your native addon, first go to its root directory:
 
@@ -110,33 +102,30 @@ needs to be added (not needed when run by npm as configured above):
 $ node-gyp configure --msvs_version=2015
 ```
 
-__Note__: The `configure` step looks for the `binding.gyp` file in the current
-directory to process. See below for instructions on creating the `binding.gyp` file.
+__Note__: The `configure` step looks for a `binding.gyp` file in the current
+directory to process. See below for instructions on creating a `binding.gyp` file.
 
 Now you will have either a `Makefile` (on Unix platforms) or a `vcxproj` file
-(on Windows) in the `build/` directory. Next invoke the `build` command:
+(on Windows) in the `build/` directory. Next, invoke the `build` command:
 
 ``` bash
 $ node-gyp build
 ```
 
 Now you have your compiled `.node` bindings file! The compiled bindings end up
-in `build/Debug/` or `build/Release/`, depending on the build mode. At this point
-you can require the `.node` file with Node and run your tests!
+in `build/Debug/` or `build/Release/`, depending on the build mode. At this point,
+you can require the `.node` file with Node.js and run your tests!
 
 __Note:__ To create a _Debug_ build of the bindings file, pass the `--debug` (or
-`-d`) switch when running either the `configure`, `build` or `rebuild` command.
-
+`-d`) switch when running either the `configure`, `build` or `rebuild` commands.
 
-The "binding.gyp" file
-----------------------
+## The `binding.gyp` file
 
-Previously when node had `node-waf` you had to write a `wscript` file. The
-replacement for that is the `binding.gyp` file, which describes the configuration
-to build your module in a JSON-like format. This file gets placed in the root of
-your package, alongside the `package.json` file.
+A `binding.gyp` file describes the configuration to build your module, in a
+JSON-like format. This file gets placed in the root of your package, alongside
+`package.json`.
 
-A barebones `gyp` file appropriate for building a node addon looks like:
+A barebones `gyp` file appropriate for building a Node.js addon could look like:
 
 ``` python
 {
@@ -158,8 +147,7 @@ Some additional resources for addons and writing `gyp` files:
  * [*"binding.gyp" files out in the wild* wiki page](https://github.com/nodejs/node-gyp/wiki/%22binding.gyp%22-files-out-in-the-wild)
 
 
-Commands
---------
+## Commands
 
 `node-gyp` responds to the following commands:
 
@@ -170,86 +158,74 @@ Commands
 | `clean`       | Removes the `build` directory if it exists
 | `configure`   | Generates project build files for the current platform
 | `rebuild`     | Runs `clean`, `configure` and `build` all in a row
-| `install`     | Installs node header files for the given version
-| `list`        | Lists the currently installed node header versions
-| `remove`      | Removes the node header files for the given version
+| `install`     | Installs Node.js header files for the given version
+| `list`        | Lists the currently installed Node.js header versions
+| `remove`      | Removes the Node.js header files for the given version
 
 
-Command Options
---------
+## Command Options
 
 `node-gyp` accepts the following command options:
 
 | **Command**                       | **Description**
 |:----------------------------------|:------------------------------------------
-| `-j n`, `--jobs n`                | Run make in parallel
-| `--target=v6.2.1`                 | Node version to build for (default=process.version)
+| `-j n`, `--jobs n`                | Run `make` in parallel
+| `--target=v6.2.1`                 | Node.js version to build for (default is `process.version`)
 | `--silly`, `--loglevel=silly`     | Log all progress to console
 | `--verbose`, `--loglevel=verbose` | Log most progress to console
 | `--silent`, `--loglevel=silent`   | Don't log anything to console
-| `debug`, `--debug`                | Make Debug build (default=Release)
+| `debug`, `--debug`                | Make Debug build (default is `Release`)
 | `--release`, `--no-debug`         | Make Release build
 | `-C $dir`, `--directory=$dir`     | Run command in different directory
-| `--make=$make`                    | Override make command (e.g. gmake)
+| `--make=$make`                    | Override `make` command (e.g. `gmake`)
 | `--thin=yes`                      | Enable thin static libraries
 | `--arch=$arch`                    | Set target architecture (e.g. ia32)
 | `--tarball=$path`                 | Get headers from a local tarball
-| `--devdir=$path`                  | SDK download directory (default=~/.node-gyp)
+| `--devdir=$path`                  | SDK download directory (default is `~/.node-gyp`)
 | `--ensure`                        | Don't reinstall headers if already present
 | `--dist-url=$url`                 | Download header tarball from custom URL
 | `--proxy=$url`                    | Set HTTP proxy for downloading header tarball
 | `--cafile=$cafile`                | Override default CA chain (to download tarball)
 | `--nodedir=$path`                 | Set the path to the node source code
-| `--python=$path`                  | Set path to the python (2) binary
-| `--msvs_version=$version`         | Set Visual Studio version (win)
-| `--solution=$solution`            | Set Visual Studio Solution version (win)
-
-
-Configuration
---------
-
-__`node-gyp` responds to environment variables or `npm` configuration__
-1. Environment variables take the form `npm_config_OPTION_NAME` for any of the 
- options listed above (dashes in option names should be replaced by underscores).
- These work also when `node-gyp` is invoked directly:  
- `$ export npm_config_devdir=/tmp/.gyp`  
- or on Windows  
- `> set npm_config_devdir=c:\temp\.gyp`  
-2. As `npm` configuration, variables take the form `OPTION_NAME`.
- This way only works when `node-gyp` is executed by `npm`:  
- `$ npm config set [--global] devdir /tmp/.gyp`  
- `$ npm i buffertools`
- 
-
-
-License
--------
-
-(The MIT License)
-
-Copyright (c) 2012 Nathan Rajlich <[email protected]>
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-'Software'), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-
-[python-v2.7.10]: https://www.python.org/downloads/release/python-2710/
-[msvc2013]: https://www.microsoft.com/en-gb/download/details.aspx?id=44914
-[win7sdk]: https://www.microsoft.com/en-us/download/details.aspx?id=8279
-[compiler update for the Windows SDK 7.1]: https://www.microsoft.com/en-us/download/details.aspx?id=4422
+| `--python=$path`                  | Set path to the Python 2 binary
+| `--msvs_version=$version`         | Set Visual Studio version (Windows only)
+| `--solution=$solution`            | Set Visual Studio Solution version (Windows only)
+
+## Configuration
+
+### Environment variables
+
+Use the form `npm_config_OPTION_NAME` for any of the command options listed
+above (dashes in option names should be replaced by underscores).
+
+For example, to set `devdir` equal to `/tmp/.gyp`, you would:
+
+Run this on Unix:
+
+```bash
+$ export npm_config_devdir=/tmp/.gyp
+```
+
+Or this on Windows:
+
+```console
+> set npm_config_devdir=c:\temp\.gyp
+```
+
+### `npm` configuration
+
+Use the form `OPTION_NAME` for any of the command options listed above.
+
+For example, to set `devdir` equal to `/tmp/.gyp`, you would run:
+
+```bash
+$ npm config set [--global] devdir /tmp/.gyp
+```
+
+**Note:** Configuration set via `npm` will only be used when `node-gyp`
+is run via `npm`, not when `node-gyp` is run directly.
+
+## License
+
+`node-gyp` is available under the MIT license. See the [LICENSE
+file](LICENSE) for details.