mv docs to wiki

documentary/9-wiki.md

@@ -0,0 +1,8 @@
+## Wiki
+
+Our Wiki contains the following pages:
+
+<kbd>🗼[Babel Modules](../../wiki/Babel-Modules)</kbd>: Talks about importing _Babel_-compiled modules from ES6 code.
+<kbd>🎭[CommonJS Compatibility](../../wiki/CommonJS-Compatibility)</kbd>: Discusses how to import _CommonJS_ modules from ES6 code.
+
+%~%

e/1.js

@@ -1,4 +1,4 @@
-import erte, { c, b } from '@a-la/fixture-babel'
+import erte, { c, b } from '../b/i'
 
 console.log(erte())
 console.log(c())

e/b.js

@@ -1,4 +1,4 @@
-import erte from '../b'
+import erte from '../b/i'
 
 console.log(erte.default())
 console.log(erte.c(''))

package.json

@@ -12,6 +12,7 @@
     "lint": "eslint .",
     "dev": "node src",
     "doc": "NODE_DEBUG=doc doc -o README.md",
+    "wiki": "DEPACK_MAX_COLUMNS=80 NODE_DEBUG=doc doc wiki -W ../depack.wiki",
     "compile": "yarn dev src/depack -c -o compile -a -p -s",
     "depack": "compile/depack.js src/depack -c -o build -a -p -s",
     "build": "yarn-s d b doc",

documentary/3-1-babel.md → wiki/Babel Modules.md

@@ -1,50 +1,66 @@
-### Using Babel-Compiled CommonJS
-
 <!-- Having to write `default` and `default.named` is only half the trouble. Things get really rough when we want to reference packages that were compiled with _Babel_. If we actually follow the standard set by _GCC_ where the the _CommonJS_ only has a default export, we run into interesting developments when trying to use _Babel_-compiled modules. See the examples below. -->
 
 <!-- therefore it's a good idea to ping the package owners to publish the `module` property of their packages pointing to the `src` folder where the code is written as ES6 modules. -->
  <!-- This is a great step forward to move _JavaScript_ language forward because `import`/`export` is what should be used instead of `require`. -->
 
 <!-- Otherwise, modules can be compiled with [`alamode`](https://github.com/a-la/alamode) which the compiler can understand. There are cases such as using `export from` compiled with ÀLaMode which GCC does not accept, therefore it is always the best to fork a package and make sure that it exports the `module` field in its _package.json_. -->
+Since _Compiler_`v20190709`, the modules imports from _Babel_ have been working semi-correctly, because although it is possible to compile a _Babel_-transpiled module with _Closure Compiler_, the compatibility between the two is not ensured for default exports.
 
-<table>
-<tr>
-<th>Source (<a href="https://github.com/a-la/fixture-babel/blob/master/src/index.js">@a-la/fixture-babel</a>)</th><th>Babel-<a href="https://github.com/a-la/fixture-babel/blob/master/build/index.js">compiled</a></th>
-</tr>
-<tr>
-<td>
+<!-- - [x] Can import named exports.
+- [ ] Can import default export. -->
+
+_The following source code is used in the example on this page._
 
-<!-- <details>
-<summary></summary> -->
+<table>
+<tr><th>Source (<a href="https://github.com/a-la/fixture-babel/blob/master/src/index.js">@a-la/fixture-babel</a>)</th></tr>
+<!-- block-start -->
+<tr><td>
 
 %EXAMPLE: node_modules/@a-la/fixture-babel/src%
-<!-- </details> -->
-</td>
-<td>
+</td></tr>
+<!-- /block-end -->
+<!-- block-start -->
+<tr><th>Babel-<a href="https://github.com/a-la/fixture-babel/blob/master/build/index.js">compiled</a></th></tr>
+<tr><td>
 
 <details>
 <summary>Show Code</summary>
 
 %EXAMPLE: node_modules/@a-la/fixture-babel/build%
 </details>
-</td>
-</tr>
+</td></tr>
+<!-- /block-end -->
 </table>
 
-Since _Compiler_`v20190709`, the modules imports from _Babel_ have been working semi-correctly, because the default import is not compatible with the way that the default object is exported (see below).
  <!-- as seen by the examples below. -->
 <!-- Because _Babel_ sets the `default` property on the `export` property (along with the `_esModule` flag so that other Babel-compiled packages can import it after the run-time evaluation from `_interopRequire`). What is actually happening now, is that to access the default export, we need to say `default.default`, and all named exports, `default.default.named`. -->
 
-_The script to import Babel-compiled modules in Closure Compiler is now:_
+Because of how [CommonJS Compatibility](CommonJS-Compatibility) is implemented, all _RequireJS_ modules will only make accessible a single default object, without named exports.
+
+<table>
+<tr><th colspan="2">
+<em>The script to import Babel-compiled modules in ES6 Code is now:</em>
+</th></tr>
+<!-- block-start -->
+<tr><td>
+
+%EXAMPLE: e/b, ../b/i => @fixture/babel%
+</td>
+<td>
 
-%EXAMPLE: e/b, ../b => @fixture/babel%
+- ✅ Do import a single default object.
+- ⛔️ Do NOT import named exports.
+</td></tr>
+</table>
+
+Although it's impossible to use such code with _Babel_ runtime, the code above can be compiled using _Google Closure Compiler_.
 
 <table>
-<tr><th colspan="2"><em>Command & Generated JS</em></th></tr>
+<tr><th colspan="2"><em>Command & Warnings</em></th></tr>
 <!-- block-start -->
 <tr><td colspan="2">
 
-%FORKERR src/depack example/babel -c -a -p --process_common_js_modules%
+%FORKERR-fs src/depack e/b -c -a -p --process_common_js_modules%
 </td></tr>
 <tr><td colspan="2"><md2html>
 
@@ -65,7 +81,7 @@ The command generates some warnings, but no errors.
 </td></tr>
 <tr><td colspan="2"><md2html>
 
-_Trying to execute the output produces the correct result. OK, but what happens when we actually try to execute such program with `@babel/register`? This is needed for testing and development.
+Trying to execute the output produces the correct result. OK, but what happens when we actually try to execute such program with `@babel/register`? This is needed for testing and development.
 
 </md2html></td></tr>
 <!-- /block-end -->
@@ -82,9 +98,9 @@ console.log(_build.default.default());
 TypeError: _build.default.default is not a function
     at Object.<anonymous> (erte/erte.js:3:13)
     at Module._compile (module.js:653:30)
-    at Module._compile (node_modules/pirates/lib/index.js:99:24)
+    at Module._compile (pirates/index.js:99:24)
     at Module._extensions..js (module.js:664:10)
-    at Object.newLoader [as .js] (node_modules/pirates/lib/index.js:104:7)
+    at Object.newLoader [as .js] (pirates/index.js:104:7)
     at Module.load (module.js:566:32)
     at tryModuleLoad (module.js:506:12)
     at Function.Module._load (module.js:498:3)
@@ -94,24 +110,24 @@ TypeError: _build.default.default is not a function
 </td><td>
 
 **Conclusion**
-- [ ] no ide support
-- [ ] no development environment
-- [ ] default.default
+- [ ] No IDE support, e.g., VS Code does not infer `.default` property.
+- [ ] No development environment, because _Babel_-runtime will throw on trying to access the `.default` property.
 
 </td></tr>
 <tr><td colspan="2"><md2html>
 
-Because of referring to the default import as .default, the compatibility with _Babel_ is broken. It's better to use <a href="https://github.com/a-la/alamode/">_ÀLaMode_</a> which is compatible with Closure Compiler.
+Because of referring to the default import as `.default`, the compatibility with _Babel_ is broken for default imports. Therefore, it's better to use <a href="https://github.com/a-la/alamode/">_ÀLaMode_</a> for transpilation which is compatible with Closure Compiler.
 
 </md2html></td></tr>
 <!-- /block-end -->
 </table>
 
 ---
 
-> [Importing `{ named }` modules](t) on Babel-compiled modules is not supported because they are still _require.js_ modules! The example below demonstrates what happens:
+To see what happens when trying to import `{ named }` exports, refer to the example below.
+<!-- [Importing `{ named }` modules](t) on Babel-compiled modules is not supported because they are still _require.js_ modules! The example below demonstrates what happens: -->
 
-%EXAMPLE: e/1, @a-la/fixture-babel => @fixture/babel%
+%EXAMPLE: e/1, ../b/i => @fixture/babel%
 
 <table>
 <tr><th><em>Command & Generated JS</em></th></tr>
@@ -134,19 +150,18 @@ Because of referring to the default import as .default, the compatibility with _
 <tr><td><md2html>
 **stdout**
 
-`<EMPTY>`
+`&lt;EMPTY&gt;`
 
-The named import syntax on _CommonJS_ modules is not supported unless there is an ECMA6 version of the script which will be detected by static analysis in the `module` field of the _package.json_ file. Therefore it's good idea to publish the module also with the build for the compiler to include the source code of the package in another package being built.
 </md2html></td></tr>
 <!-- /block-end -->
 </table>
 
+The named import syntax on _CommonJS_ modules is not supported unless there is an ECMA6 version of the script which will be detected by static analysis in the `module` field of the _package.json_ file. Thus it's a good idea to publish the module also with the build for the compiler to include the source code of the package in another package being built.
+
 
 <!-- _Trying to execute the output:_
 
 %FORKERR example/babel-normal-output% -->
 
 
 <!-- Not working and not going to, because hey, we need to make sure that the CommonJS only exports a single `default` module don't we, Node.JS? But presto it works with _Babel_! -->
-
-%~%

documentary/3-0-commonjs.md → wiki/CommonJS Compatibility.md

@@ -1,6 +1,4 @@
-## CommonJS Compatibility
-
-Depack works best with ES6 modules. All new code should be written with `import/export` statements because it's the standard that takes the implementations away from hacking assignments to `module.exports` which people used to use in a variety of possibly imaginable ways, e.g.,
+Depack works best with _ES6_ modules. All new code should be written with `import/export` statements because it's the standard that takes the implementations away from hacking assignments to `module.exports` which people used to use in a variety of possibly imaginable ways, e.g.,
 
 <details>
 <summary><md2html>Show `lazyProperty` use from `depd`</md2html></summary>

wiki/_Footer.md

@@ -0,0 +1,3 @@
+%~ -1%
+
+<depack-footer/>