From e1edc1b69d345455dbf53e2887b88021973dae87 Mon Sep 17 00:00:00 2001
From: Stefano Brilli <stefanobrilli@gmail.com>
Date: Wed, 17 Jun 2015 01:01:55 +0200
Subject: [PATCH] Promote use of postcss functions

---
 README.md | 44 +++++++++++++++++++++++++++++++++-----------
 1 file changed, 33 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 2a6cc714..2c2e8537 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,9 @@ module.exports = {
             }
         ]
     },
-    postcss: [autoprefixer, csswring]
+    postcss: function {
+        return [autoprefixer, csswring];
+    }
 }
 ```
 
@@ -44,6 +46,20 @@ var css = require('./file.css');
 // => CSS after Autoprefixer and CSSWring
 ```
 
+Note that the context of this function
+
+```js
+module.exports = {
+    ...
+    postcss: function {
+        return [autoprefixer, csswring];
+    }
+}
+```
+
+will be set to the [webpack loader-context](http://webpack.github.io/docs/loaders.html#loader-context).
+If there is the need, this will let you access to webpack loaders API.
+
 ## Plugins Packs
 
 If you want to process different styles by different PostCSS plugins you can
@@ -63,18 +79,24 @@ module.exports = {
             }
         ]
     },
-    postcss: {
-        defaults: [autoprefixer, csswring],
-        cleaner:  [autoprefixer({ browsers: [] })]
+    postcss: function () {
+        return {
+            defaults: [autoprefixer, csswring],
+            cleaner:  [autoprefixer({ browsers: [] })]
+        };
     }
 }
 ```
 
-## Plugins Function
+## Integration with postcss-import
+
+When using [postcss-import](https://github.com/postcss/postcss-import) plugin, you may want to tell webpack about
+dependencies coming from your `@import` directives.
+For example: in watch mode, to enable recompile on change.
 
-If you need to link any of the postcss plugins to the webpack context, you can
-define a function that returns your plugins. The function is executed with the
-same context provided to postcss-loader, allowing access to webpack loader API
+Since the function in postcss section is executed with the [webpack loader-context](http://webpack.github.io/docs/loaders.html#loader-context),
+we can use the postcss-import callback [onImport](https://github.com/postcss/postcss-import#onimport) to tell webpack what files
+need to be watched.
 
 ```js
 var cssimport = require('postcss-import');
@@ -90,12 +112,12 @@ module.exports = {
         ]
     },
     postcss: function () {
-        // The context of this function is the same provided to postcss-loader
-        // see: http://webpack.github.io/docs/loaders.html
+        // The context of this function is the webpack loader-context
+        // see: http://webpack.github.io/docs/loaders.html#loader-context
 
         return [
             cssimport({
-                // see postcss-import docs to learn about onImport param
+                // see postcss-import docs to learn about onImport callback
                 // https://github.com/postcss/postcss-import
 
                 onImport: function (files) {