From 0683591c6c8c64a11201c98f56773fe8f38711ab Mon Sep 17 00:00:00 2001
From: Sebastian McKenzie <sebmck@gmail.com>
Date: Sun, 19 Oct 2014 17:49:09 +1100
Subject: [PATCH] add new module formatters documentation

---
 MODULES.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md  | 33 +++++--------------
 2 files changed, 102 insertions(+), 25 deletions(-)
 create mode 100644 MODULES.md

diff --git a/MODULES.md b/MODULES.md
new file mode 100644
index 0000000000..e1f04f092c
--- /dev/null
+++ b/MODULES.md
@@ -0,0 +1,94 @@
+# Modules
+
+## Usage
+
+### CLI
+
+    $ 6to5 --modules common script.js
+
+### Node
+
+```javascript
+var to5 = require("6to5");
+to5.transform('import "foo";', { modules: "common" });
+```
+
+## Formats
+
+### Common (Default)
+
+```javascript
+import "foo"; // require("foo");
+
+import foo from "foo"; // var foo = require("foo").default;
+import * as foo from "foo"; // var foo = require("foo");
+
+import {bar} from "foo"; // var bar = require("foo").bar;
+import {foo as bar} from "foo"; // var bar = require("foo").foo;
+
+export {test}; // exports.test = test;
+export var test = 5; // var test = 5; exports.test = test;
+
+export default test; // exports.default = test;
+```
+
+### AMD
+
+**In**
+
+```javascript
+import foo from "foo";
+
+export function bar() {
+  return foo("foobar");
+}
+```
+
+**Out**
+
+```javascript
+define(["foo"], function (_foo) {
+  var exports = {};
+  exports.bar = bar;
+
+  var foo = _foo.default;
+
+  function bar() {
+    return foo("foobar");
+  }
+
+  return exports;
+});
+```
+
+### UMD
+
+**In**
+
+```javascript
+import foo from "foo";
+
+export function bar() {
+  return foo("foobar");
+}
+```
+
+**Out**
+
+```javascript
+(function (factory) {
+  if (typeof define === "function" && define.amd) {
+    define(["exports", "foo"], factory);
+  } else if (typeof exports !== "undefined") {
+    factory(exports, require("foo"));
+  }
+})(function (exports) {
+  exports.bar = bar;
+
+  var foo = _foo.default;
+
+  function bar() {
+    return foo("foobar");
+  }
+});
+```
diff --git a/README.md b/README.md
index 45c25a4aa5..42f3b86621 100644
--- a/README.md
+++ b/README.md
@@ -154,6 +154,11 @@ to5.transformFile("filename.js", options, function (err, result) {
   // Run `6to5 --help` to see a full list of transformers.
   whitelist: [],
 
+  // Module formatter to use
+  // Run `6to5 --help` to see a full list of module formatters.
+  // Default: "common"
+  modules: "common",
+
   // If truthy, adds a `map` property to returned output.
   // If set to "inline", a comment with a sourceMappingURL directive is added to
   // the bottom of the returned code.
@@ -224,32 +229,10 @@ To test 6to5 in your browser run:
 
 And open `test/browser.html` in your browser if it doesn't open automatically.
 
-## Modules
+## [Modules](MODULES.md)
 
-6to5 modules compile straight to CommonJS, because of this various liberties are
-taken into account to make their usage easier.
-
-```javascript
-import "foo"; // require("foo");
-
-import foo from "foo"; // var foo = require("foo").default;
-import * as foo from "foo"; // var foo = require("foo");
-
-import {bar} from "foo"; // var bar = require("foo").bar;
-import {foo as bar} from "foo"; // var bar = require("foo").foo;
-
-export {test}; // exports.test = test;
-export var test = 5; // var test = 5; exports.test = test;
-
-export default test; // exports.default = test;
-```
-
-If you'd like to disable this behaviour and use the more ES6-like
-[es6-module-transpiler](https://github.com/esnext/es6-module-transpiler) you can
-use the following:
-
-    $ 6to5 script.js -o script-compiled.js --blacklist modules
-    $ compile-modules convert script-compiled.js -o script-compiled.js
+See [Modules - Common](MODULES.md#common) for the default module formatting.
+Alternatively see [Modules](MODULES.md) for all other supported module formatting types.
 
 ## Caveats