Merge pull request #31 from css-modules/readme

review

Author: mightyaleksey

README.md

@@ -1,67 +1,83 @@
 css-modules-require-hook
 ========================
 
-Automatically compiles a CSS Module to a low-level interchange format called ICSS or [Interoperable CSS](https://github.com/css-modules/icss).
+The require hook compiles [CSS Modules](https://github.com/css-modules/css-modules) in runtime. This is similar to Babel's [babel/register](https://babeljs.io/docs/usage/require/).
 
-One of the ways you can compile [CSS Modules](https://github.com/css-modules/css-modules) to the ICSS format is through the require hook. The require hook will bind itself to node's require and automatically compile files on the fly. This is similar to Babel's [babel/register](https://babeljs.io/docs/usage/require/).
+## What is CSS Modules
 
-## Requirements
+A **CSS Module** is a CSS file in which all class names and animation names are scoped locally by default. Learn more in the article [CSS Modules - Welcome to the Future](http://glenmaddern.com/articles/css-modules) by Glen Maddern.
 
-To use this tool we require postcss and few plugins to be installed on your project. See the list below:
+## Features
 
-- `"postcss": "4.x"`
-- `"postcss-modules-extract-imports": "0.x"`
-- `"postcss-modules-local-by-default": "0.x"`
-- `"postcss-modules-scope": "0.x"`
-
-## Install
-
-```bash
-$ npm i css-modules-require-hook
-```
+Compiling in runtime, [universal](https://medium.com/@mjackson/universal-javascript-4761051b7ae9) usage.
 
 ## Usage
 
-```javascript
-require('css-modules-require-hook');
-```
+### Requirements
 
-## Available options
+To use this tool we require [Node.js v0.12.x](https://github.com/nodejs/node) (or higher) and several modules to be installed.
 
-Providing additional options allows you to get advanced experience. See the variants below.
+- [postcss](https://github.com/postcss/postcss) version 4 or higher
+- [postcss-modules-extract-imports](https://github.com/css-modules/postcss-modules-extract-imports)
+- [postcss-modules-local-by-default](https://github.com/css-modules/postcss-modules-local-by-default)
+- [postcss-modules-scope](https://github.com/css-modules/postcss-modules-scope)
 
-```javascript
-var hook = require('css-modules-require-hook');
-hook({ /* options */ });
-```
+### Installation
 
-### `rootDir` option
+```bash
+$ npm i css-modules-require-hook
+```
 
-Aliases are `root`, `d`.
+### Tuning (options)
 
-Absolute path to your project's root directory. This is optional but providing it will result in better generated classnames. It can be obligatory, if you run require hook and build tools, like [css-modulesify](https://github.com/css-modules/css-modulesify) from different working directories.
+ * `function` **createImportedName** — short alias for the [postcss-modules-extract-imports](https://github.com/css-modules/postcss-modules-extract-imports) plugin's `createImportedName` option.
+ * `function` **generateScopedName** — short alias for the [postcss-modules-scope](https://github.com/css-modules/postcss-modules-scope) plugin's option. Helps you to specify the custom way to build generic names for the class selectors.
+ * `function` **processCss** — in rare cases you may want to get compiled styles in runtime, so providing this option helps.
+ * `string`   **rootDir** — absolute path to the project directory. Providing this will result in better generated class names. It can be obligatory, if you run require hook and build tools (like [css-modulesify](https://github.com/css-modules/css-modulesify)) from different working directories.
+ * `string`   **to** — provides `to` option to the [LazyResult instance](https://github.com/postcss/postcss/blob/master/docs/api.md#processorprocesscss-opts).
+ * `array`    **use** — custom subset of postcss plugins.
 
-### `use` option
+### Examples
 
-Alias is `u`.
+Basically you need to require this plugin before other requires for your styles will occur.
+For example:
 
-Custom list of plugins. This is optional but helps you to extend list of basic [postcss](https://github.com/postcss/postcss) plugins. Also helps to specify options for particular plugins.
+*icon.css*
+```css
+.icon
+{
+  composes: fa fa-hand-peace-o from 'font-awesome/css/font-awesome.css';
+}
+```
 
-### `createImportedName` option
+*server.js*
+```javascript
+require('css-modules-require-hook');
 
-Alias for the `createImportedName` option from the [postcss-modules-extract-imports](https://github.com/css-modules/postcss-modules-extract-imports) plugin. This is optional. Won't work if you `use` option.
+var styles = require('./icon.css');
+var html = '<i class="' + styles.icon + '"></i>';
+// send it somehow :)
+```
 
-### `generateScopedName` option
+You'll get:
 
-Custom function to generate class names. This is optional. Alias for the `generateScopedName` option from the [postcss-modules-scope](https://github.com/css-modules/postcss-modules-scope) plugin. Won't work if you `use` option.
+```html
+<i class="_icon_font-awesome-css-font-awesome__fa _icon_font-awesome-css-font-awesome__fa-hand-peace-o"></i>'
+```
 
-### `mode` option
+In rare cases you may want to tune the require hook for better experience.
 
-Alias for the `mode` option from the [postcss-modules-local-by-default](https://github.com/css-modules/postcss-modules-local-by-default) plugin. This is optional. Won't work if you `use` option.
+```javascript
+var hook = require('css-modules-require-hook');
+var path = require('path');
 
-## Examples
+hook({
+  // setting root to the parent directory
+  rootDir: path.join(__dirname, '..')
+});
+```
 
-If you want to add custom functionality, for example [CSS Next](http://cssnext.io/setup/#as-a-postcss-plugin) plugin, you should provide the `use` option.
+If you want to add any postcss plugins to the pipeline - you should use the `use` option.
 
 ```javascript
 var hook = require('css-modules-require-hook');