Some notes on ES6 adoption and work-arounds

modules/pdp11/README.md

@@ -60,8 +60,25 @@ or generate both versions and use a loader that detects the browser's capabiliti
 Caveats
 -------
 
+### Shared modules
+
+All PCjs machines rely on shared modules that are normally stored in [/shared/lib](/shared/lib/).  However, until
+ALL the machines have been converted to use ES6 classes, shared code must now exist in two flavors:
+[/shared/lib](/shared/lib/) and [/shared/es6](/shared/es6/).
+
+Once all the other machines have been converted to use ES6 classes, the shared ES6 code will be folded back into
+[/shared/lib](/shared/lib/), and the temporary ES6 folder will go away.  Obviously, there is incentive for me to do
+this sooner rather than later, since in the interim, I must make any changes to shared code in both places.
+
+There's also a less obvious problem: if you load a web page that attempts to load two or more PCjs machines, one of
+which uses [/shared/lib](/shared/lib/) and another of which uses [/shared/es6](/shared/es6/), at least one of them will
+fail to start, because the two sets of shared code cannot coexist.  Well, they *could* have coexisted if I had been
+willing to change the names of all the shared global objects (like **Component**), but I wasn't. 
+
+### *import* and *export*
+
 With regard to *import* and *export* statements, the main reason I use them is to inform my development environment
-(WebStorm) about each file's dependencies, thereby preventing inspection warnings.  Ultimately, I plan to make PDPjs
+(WebStorm) about each file's dependencies, thereby preventing inspection warnings.  And ultimately, I plan to make PDPjs
 run as a Node application, so explicitly declaring all imports and exports will be required, but for now, it's just
 a web application, so strictly speaking, they're not required.
 

modules/shared/es6/README.md

@@ -0,0 +1,28 @@
+Shared Sources
+===
+
+This folder contains a mix of shared code, with some files used only by Node (server) modules,
+some used only by Browser (client) modules, and others used by both.
+
+At the moment, only a few files are completely agnostic; eg: [strlib.js](strlib.js) and [usrlib.js](usrlib.js).
+One give-away is that neither contain references to any globals (although references to each other
+would be fine).
+
+**netlib.js** is appropriate only for Node modules, because it contains code that relies on Node's
+global *Buffer* object, as indicated by:
+
+	/* global Buffer: false */
+
+[weblib.js](weblib.js) is appropriate only for client modules, because it contains code that relies on the
+browser's global *window* object, as indicated by:
+
+	/* global window: true */
+
+We declare *window* modifiable (true) so that [defines.js](defines.js) can set *global.window* to *false*
+when running within Node, allowing any other code to test the existence of *window* with a simple:
+
+	if (window) {...}
+	
+instead of:
+
+	if (typeof window !== "undefined") {...}

modules/shared/lib/README.md

@@ -1,4 +1,4 @@
-Shared Sources
+Shared (ES6) Sources
 ===
 
 This folder contains a mix of shared code, with some files used only by Node (server) modules,