update documentation

doc/config.md

@@ -7,6 +7,7 @@ closest `.esformatter` file and use that as a setting unless you specify
 You also have the option to put your `esformatter` settings inside the
 `package.json` file under the `esformatter` property.
 
+
 ## property names
 
 Most of the property names are based on the [babel-eslint node
@@ -18,19 +19,25 @@ that we recognize, even if we don't list them in all the places the config
 probably use the same ids on all the settings (`indent`, `lineBreak` and
 `whiteSpace`), don't get intimidated by the names!
 
+
 ## root
 
 Settings from multiple files will be merged until it finds a config file that
-contains the property `"root": true`; that makes it easy to define exceptions
-to the project rules without needing to copy all the shared properties. - for
-an example see test files inside the `"test/compare/rc"` folder.
+contains the property `"root": true`; that makes it easy to define exceptions to
+the project/global rules without needing to copy all the shared properties.
+For an example see test files inside the `"test/compare/rc"` folder.
 
 ```js
 {
   "root": true
 }
 ```
 
+protip: set `"esformatter": {"root": true}` inside the project `package.json`
+(or `.esformatter` file ) to avoid conflicts between contributor settings (it
+will avoid loading the global user config).
+
+
 ## indent
 
 Indent is responsible for whitespace at the front of each line. `indent.value`
@@ -140,7 +147,7 @@ is not followed by a line break.
 ## pipe
 
 Since we don't expect everyone to write plugins that only works with
-esformatter we decided to encourage the usage of standalone CLI tools.
+esformatter we decided to support the usage of standalone CLI tools.
 
 ```js
 {
@@ -170,6 +177,10 @@ locally installed executables inside the `node_modules` folder. If it can't
 find a local executable it will fallback to global commands. (this allows you
 to install `devDependencies` that are only used by a single project)
 
+PS: piped commands are usually *slower* than esformatter plugins because they
+usually require parsing the file another time and spawning new processes isn't
+cheap. But it might still be a good way to reuse existing scripts.
+
 
 ## plugins
 
@@ -187,6 +198,23 @@ For detailed information about plugins structure and API see
 [plugins.md](./plugins.md)
 
 
+## extends
+
+Extends allows users to share presets easily.
+
+```js
+{
+  "extends": [
+    "preset:foobar", // load "esformatter-preset-foobar" from "./node_modules"
+    "./lorem_ipsum.json" // load relative config file
+  ]
+}
+```
+
+Read the [presets.md](./presets.md) file for info on how to write reusable
+configs.
+
+
 ---
 
 

doc/plugins.md

@@ -41,11 +41,12 @@ The plugin methods are executed in the following order: `setOptions` > `stringBe
 
 **IMPORTANT:** If you need to edit the structure of the AST (add/remove nodes,
 change the order of elements) we recommend you to write it as a standalone CLI
-tool whenever possible and use the [pipe](./config.md#pipe) option instead of writting a plugin
-(eg. [strip-debug](https://www.npmjs.com/package/strip-debug)). Plugins should
-ideally only add/remove/edit the `WhiteSpace`, `Indent`, `LineBreak` and
-`Comment` tokens, otherwise you might have conflicts with other plugins and
-esformatter itself.
+tool whenever possible (eg.
+[strip-debug](https://www.npmjs.com/package/strip-debug)) and use the
+[pipe](./config.md#pipe) option or implement it using
+`stringBefore`/`stringAfter`. Plugins should ideally only add/remove/edit the
+`WhiteSpace`, `Indent`, `LineBreak` and `Comment` tokens, otherwise you might
+have conflicts with other plugins and esformatter itself.
 
 **protip:** You can use
 [rocambole-token](https://github.com/millermedeiros/rocambole-token) and
@@ -82,8 +83,9 @@ plugin.stringBefore = function(str) {
 ```
 
 PS: you should only really use this method if you need to store some state
-during `stringBefore` to be used by your other methods; otherwise favor the
-[pipe](./config.md#pipe) option.
+during `stringBefore` to be used by your other methods or if you need to
+change the program structure (eg. add/remove nodes/semi-colons, anything that
+would generate a different AST structure)
 
 ### stringAfter(outputString):String
 
@@ -99,8 +101,10 @@ plugin.stringAfter = function(str) {
 ```
 
 PS: you should only really use this method if you need to recover from some of
-the changes you introduced by the other plugin methods; otherwise favor the
-[pipe](./config.md#pipe) option.
+the changes introduced by the other plugin methods or esformatter itself; favor
+`stringBefore` to reduce conflicts with other plugins (eg. if you introduce
+a single quote and the `esformatter-quotes` plugin should convert all quotes to
+double quotes)
 
 ### tokenBefore(token)
 
@@ -197,6 +201,6 @@ It's very important to note that adding/removing/reordering `nodes` might cause
 undesired side effects on other plugins (`rocambole.moonwalk` and
 `rocambole.walk` might not work as expected and/or you might forget some
 `node.[start|end]Token` and/or `token.[next|prev]` and break other plugins). So
-if you need to edit the tree structure please use the `stringAfter` method or
-  write a standalone CLI tool that can be used on the [pipe](./config.md#pipe)
-  setting.
+if you need to edit the tree structure please use the `stringBefore` and
+`stringAfter` methods or write a standalone CLI tool that can be used on the
+[pipe](./config.md#pipe) setting.