Merge branch 'readme-tweaks' into readme-improvements

README.md

@@ -1,6 +1,6 @@
 # babel-preset-env [![npm](https://img.shields.io/npm/v/babel-preset-env.svg)](https://www.npmjs.com/package/babel-preset-env) [![travis](https://img.shields.io/travis/babel/babel-preset-env/master.svg)](https://travis-ci.org/babel/babel-preset-env) [![npm-downloads](https://img.shields.io/npm/dm/babel-preset-env.svg)](https://www.npmjs.com/package/babel-preset-env)
 
-> Babel preset that automatically determines the Babel plugins you need based on your supported environments. Uses compat-table
+> A Babel preset that can automatically determine the Babel plugins and polyfills you need based on your supported environments.
 
 `npm install babel-preset-env --save-dev`
 
@@ -30,23 +30,27 @@ Check out the many options (especially `useBuiltIns` to polyfill less)!
 
 ### Determine environment support for ECMAScript features
 
-[#7](https://github.com/babel/babel-preset-env/issues/7) - Use external data such as [`compat-table`](https://github.com/kangax/compat-table) to determine browser support. (We should create PRs there when necessary)
+Use external data such as [`compat-table`](https://github.com/kangax/compat-table) to determine browser support. (We should create PRs there when necessary)
 
 ![](https://cloud.githubusercontent.com/assets/588473/19214029/58deebce-8d48-11e6-9004-ee3fbcb75d8b.png)
 
-We can periodically run [build-data.js](/scripts/build-data.js) which generates [plugins.json](/data/plugins.json).
+We can periodically run [build-data.js](https://github.com/babel/babel-preset-env/blob/master/scripts/build-data.js) which generates [plugins.json](https://github.com/babel/babel-preset-env/blob/master/data/plugins.json).
 
-### Maintain a mapping between javascript features and babel plugins
+Ref: [#7](https://github.com/babel/babel-preset-env/issues/7)
 
-> Currently located at [plugin-features.js](/data/plugin-features.js).
+### Maintain a mapping between JavaScript features and Babel plugins
+
+> Currently located at [plugin-features.js](https://github.com/babel/babel-preset-env/blob/master/data/plugin-features.js).
 
 This should be straightforward to do in most cases. There might be cases were plugins should be split up more or certain plugins aren't standalone enough (or impossible to do).
 
 ### Support all plugins in Babel that are considered `latest`
 
 > Default behavior without options is the same as `babel-preset-latest`.
 
-[#14](https://github.com/babel/babel-preset-env/issues/14) - It won't include `stage-x` plugins. env will support all plugins in what we consider the latest version of Javascript (by matching what we do in [`babel-preset-latest`](http://babeljs.io/docs/plugins/preset-latest/)).
+It won't include `stage-x` plugins. env will support all plugins in what we consider the latest version of Javascript (by matching what we do in [`babel-preset-latest`](http://babeljs.io/docs/plugins/preset-latest/)).
+
+Ref: [#14](https://github.com/babel/babel-preset-env/issues/14)
 
 ### Determine the lowest common denominator of plugins to be included in the preset
 
@@ -58,91 +62,105 @@ For example, if you are building on Node 4, arrow functions won't be converted,
 
 ### Support a `browsers` option like autoprefixer
 
-[#19](https://github.com/babel/babel-preset-env/pull/19) - Use [browserslist](https://github.com/ai/browserslist) to also queries like `> 1%, last 2 versions`.
+Use [browserslist](https://github.com/ai/browserslist) to declare supported environments by performing queries like `> 1%, last 2 versions`.
+
+Ref: [#19](https://github.com/babel/babel-preset-env/pull/19)
 
 ## Install
 
 ```sh
-$ npm install --save-dev babel-preset-env
+npm install --save-dev babel-preset-env
 ```
 
 ## Usage
 
-The default behavior without options runs all transforms (acts as [babel-preset-latest](https://babeljs.io/docs/plugins/preset-latest/)).
+The default behavior without options runs all transforms (behaves the same as [babel-preset-latest](https://babeljs.io/docs/plugins/preset-latest/)).
 
 ```js
 {
   "presets": ["env"]
 }
 ```
 
-## [Options](http://babeljs.io/docs/plugins/#pluginpresets-options)
+## Options
+
+For more information on setting options for a preset, refer to the [plugin/preset options](http://babeljs.io/docs/plugins/#plugin-preset-options) documentation.
+
+### `targets`
 
-### `targets`: `{ [string]: number }`
+`{ [string]: number }`, defaults to `{}`.
 
-Defaults to `{}`.
+Takes an object of environment versions to support.
 
-> Takes an object of environment versions to support.
-> Each target environment takes a number (you can specify a decimal like `node: 6.5`)
+Each target environment takes a number (you can also specify a minor versions like `node: 6.5`)
 
-Example environments: "chrome, opera, edge, firefox, safari, ie, ios, android, node, electron".
+Example environments: `chrome`, `opera`, `edge`, `firefox`, `safari`, `ie`, `ios`, `android`, `node`, `electron`.
 
-The data for this is currently at: [/data/plugins.json](/data/plugins.json) and being generated by [/scripts/build-data.js](/scripts/build-data.js) using https://kangax.github.io/compat-table.
+The [data](https://github.com/babel/babel-preset-env/blob/master/data/plugins.json) for this is generated by running the [build-data script](https://github.com/babel/babel-preset-env/blob/master/scripts/build-data.js) which pulls in data from [compat-table](https://kangax.github.io/compat-table).
 
-The `node` target environment supports additional options:
+### `targets.node`
 
-`node`: `number | "current" | true`
+`number | "current" | true`
 
-If you want to compile against the current node version, you can specify `"node": true` or `"node": "current"` which would be the same as `node": parseFloat(process.versions.node)`.
+If you want to compile against the current node version, you can specify `"node": true` or `"node": "current"` which would be the same as `"node": parseFloat(process.versions.node)`.
 
-### `browsers`: `Array<string> | string`
+### `targets.browsers`
 
-> A query to select browsers (ex: last 2 versions, > 5%) using [browserslist](https://github.com/ai/browserslist).  
+`Array<string> | string`
 
-> Note, browsers' results are overridden by explicit items from `targets`.
+A query to select browsers (ex: last 2 versions, > 5%) using [browserslist](https://github.com/ai/browserslist).  
 
-### `loose`: `boolean`
+Note, browsers' results are overridden by explicit items from `targets`.
 
-Defaults to `false`.
+### `loose`
+
+`boolean`, defaults to `false`.
+
 Enable "loose" transformations for any plugins in this preset that allow them.
 
-### `modules`: `"amd" | "umd" | "systemjs" | "commonjs" | false`
+### `modules`
+
+`"amd" | "umd" | "systemjs" | "commonjs" | false`, defaults to `"commonjs"`.
 
-Defaults to `"commonjs"`.
 Enable transformation of ES6 module syntax to another module type.
-Can be `false` to not transform modules.
+
+Setting this to `false` will not transform modules.
 
-### `debug:` `boolean`
+### `debug`
 
-Defaults to `false`
-`console.log` out the targets and plugins being used as well as the version specified in `/data/plugins.json`.
+`boolean`, defaults to `false`.
+
+Outputs the targets/plugins used and the version specified in [plugin data version](https://github.com/babel/babel-preset-env/blob/master/data/plugins.json) to `console.log`.
 
-### `include`: `Array<string>`
+### `include`
 
-> `whitelist` is deprecated and will be removed in the next major in favor of this.
+`Array<string>`, defaults to `[]`.
+
+> NOTE: `whitelist` is deprecated and will be removed in the next major in favor of this.
 
-Defaults to `[]`
 An array of plugins to always include.
 
-Valid options include any of the [babel plugins](/data/plugin-features.js) or [built-ins](/data/built-in-features.js) such as `transform-es2015-arrow-functions` or `map`, `set`, `object.assign`.
+Valid options include any of the [babel plugins](https://github.com/babel/babel-preset-env/blob/master/data/plugin-features.js) or [built-ins](https://github.com/babel/babel-preset-env/blob/master/data/built-in-features.js), such as `transform-es2015-arrow-functions`, `map`, `set`, or `object.assign`.
 
 > For the built-ins like `es6.typed.data-view` just put `typed.data-view`.
 
-Useful if there is a bug in a native implementation, or a combination of a non-supported feature + a supported one doesn't  work.
+This option is useful if there is a bug in a native implementation, or a combination of a non-supported feature + a supported one doesn't work.
 
 For example, Node 4 supports native classes but not spread. If `super` is used with a spread argument, then the `transform-es2015-classes` transform needs to be `include`d, as it is not possible to transpile a spread with `super` otherwise.
 
-### `exclude`: `Array<string>`
+### `exclude`
 
-Defaults to `[]`
+`Array<string>`, defaults to `[]`.
+
 An array of plugins to always exclude/remove.
+
 The possible options are the same as the `include` option.
 
-Useful for "blacklisting" a transform like `transform-regenerator` if you don't use generators and don't want to include `regeneratorRuntime` (when using `useBuiltIns`) or for using another plugin like [fast-async](https://github.com/MatAtBread/fast-async) instead of `async-to-gen`(http://babeljs.io/docs/plugins/transform-async-generator-functions/).
+This option is useful for "blacklisting" a transform like `transform-regenerator` if you don't use generators and don't want to include `regeneratorRuntime` (when using `useBuiltIns`) or for using another plugin like [fast-async](https://github.com/MatAtBread/fast-async) instead of [Babel's async-to-gen](http://babeljs.io/docs/plugins/transform-async-generator-functions/).
 
-### `useBuiltIns`: `boolean`
+### `useBuiltIns`
 
-Defaults to `false`.
+`boolean`, defaults to `false`.
 
 A way to apply `babel-preset-env` for polyfills (via "babel-polyfill").
 
@@ -153,17 +171,17 @@ A way to apply `babel-preset-env` for polyfills (via "babel-polyfill").
 npm install babel-polyfill --save
 ```
 
-This option will apply a new plugin that replaces the statement `import "babel-polyfill"` or `require("babel-polyfill")` with individual requires for `babel-polyfill` based on environment.
+This option enables a new plugin that replaces the statement `import "babel-polyfill"` or `require("babel-polyfill")` with individual requires for `babel-polyfill` based on environment.
 
-> NOTE: Only use `require("babel-polyfill");` once in your whole app. One option is to create single entry file that only contains the require statement.
+> NOTE: Only use `require("babel-polyfill");` once in your whole app. One option is to create a single entry file that only contains the require statement.
 
-In
+**In**
 
 ```js
 import "babel-polyfill";
 ```
 
-Out (different based on environment)
+**Out (different based on environment)**
 
 ```js
 import "core-js/modules/es7.string.pad-start";
@@ -173,7 +191,7 @@ import "core-js/modules/web.immediate";
 import "core-js/modules/web.dom.iterable";
 ```
 
-> This will also work for "core-js" directly (`import "core-js";`)
+This will also work for `core-js` directly (`import "core-js";`)
 
 ```
 npm install core-js --save