Fork out Web and NonWeb documents.

Author: jfbastien

HighLevelGoals.md

@@ -14,7 +14,8 @@
     * continue to iteratively specify [additional features](FutureFeatures.md),
       prioritized by feedback and experience, including support for languages
       other than C/C++.
-3. Design to execute within and integrate well with the *existing* Web platform:
+3. Design to execute within and integrate well with the *existing*
+   [Web platform](Web.md):
     * maintain the versionless, [feature-tested](FeatureTest.md) and
       [backwards-compatible](BinaryEncoding.md#backwards-compatibility)
       evolution story of the Web;
@@ -25,8 +26,7 @@
       to JavaScript; and
     * define a human-editable text format that is convertible to and from the
       binary format, supporting View Source functionality.
-4. Design to support [non-browser environments](MVP.md#non-browser-embedding)
-   as well.
+4. Design to support [non-browser embeddings](NonWeb.md) as well.
 5. Make a great platform:
     * build an [LLVM backend](https://github.com/WebAssembly/llvm) and
       accompanying [clang port](https://github.com/WebAssembly/clang);

MVP.md

@@ -9,9 +9,10 @@ post-MVP features doc](EssentialPostMVPFeatures.md).
 This document explains the contents of the MVP at a high-level. There are also
 separate docs with more precise descriptions of:
 
- * the [polyfill to JavaScript](Polyfill.md)
- * the [AST semantics](AstSemantics.md) 
- * the [binary encoding](BinaryEncoding.md)
+ * [Polyfill to JavaScript](Polyfill.md);
+ * [AST semantics](AstSemantics.md);
+ * [Binary encoding](BinaryEncoding.md);
+ * Implementation [in the browser](Web.md) and [outside the browser](NonWeb.md).
 
 **Note**: This content is still in flux and open for discussion.
 
@@ -36,6 +37,12 @@ separate docs with more precise descriptions of:
     importing, though.
 * When compiling from C++, imports would be generated for unresolved `extern`
  functions and calls to those `extern` functions would call the import.
+* Host environments can define builtin modules that are implemented natively but
+  can otherwise be imported like [other modules](MVP.md#Modules). As examples:
+  * A WebAssembly shell might define a builtin `stdio` library with an export
+    `puts`.
+  * In the browser, the WebIDL support mentioned in
+    [future features](FutureFeatures.md).
 * **TODO**: there is more to discuss here concerning APIs.
 
 ## Module structure
@@ -44,10 +51,10 @@ separate docs with more precise descriptions of:
   their type and byte-length.
  * Sections with unknown types would be skipped without error. 
  * Standardized section types:
-  * module import section (see [Module imports](MVP.md#module-imports) below);
+  * module import section;
   * globals section (constants, signatures, variables);
-  * code section (see [Code section](MVP.md#code-section) below);
-  * heap initialization section (see [Heap](MVP.md#heap) below).
+  * code section;
+  * heap initialization section.
 
 ## Code section
 
@@ -93,38 +100,6 @@ isomorphic to the [binary format](BinaryEncoding.md).
  * See the [AST Semantics heap section](AstSemantics.md#accessing-the-heap) for
    more details.
 
-## Non-browser embedding
-
-* Host environments can define builtin modules that are implemented natively but
-   can otherwise be imported like
-   [other modules](MVP.md#code-loading-and-imports). As examples:
-  * A WebAssembly shell might define a builtin `stdio` library with an export
-    `puts`.
-  * In the browser, the WebIDL support mentioned in
-    [future features](FutureFeatures.md).
- * Where there is overlap between the browser and popular non-browser
-   environments, a shared spec could be proposed, but this would be separate
-   from the WebAssembly spec.
-  * A symmetric example in JavaScript would be the
-    [Loader](http://whatwg.github.io/loader) spec, intended to be implemented by
-    both browsers and node.js.
- * However, one might find a fair amount of variance between the browser and
-   other environments on core APIs like network and file I/O.
- * To allow writing portable POSIX-like code (that ran in both browser and other
-   environments), the WebAssembly community would develop a shared repository of
-   WebAssembly code that mapped between a POSIX-like interface and the host's
-   builtin modules using compile-time `#ifdef`s or, after
-   [dynamic linking](FutureFeatures.md#dynamic-linking) was added, client-side
-   dynamic feature testing.
-  * A symmetric example in JavaScript would be the
-    [ES6 Module Loader polyfill](https://github.com/ModuleLoader/es6-module-loader)
-    library.
- * The WebAssembly spec would thus not try to define any large portable
-   libc-like library.
-  * However, certain features that are core to WebAssembly semantics that are
-    found in native libc *would* be part of the core WebAssembly spec as either
-    primitive opcodes or a special builtin module (e.g., `sbrk`, `mmap`).
-
 ## Security
 
 WebAssembly MVP will be no looser from a security point-of-view than if the

NonWeb.md

@@ -0,0 +1,25 @@
+# Non-Browser Embeddings
+
+WebAssembly is designed to run primarily [within a browser](Web.md). It is
+nonetheless desirable to be able to execute it inside standalone shells for
+testing and as a host environment for untrusted code (e.g. in a datacenter). It
+may even be desirable to execute WebAssembly embedded within larger programs.
+
+Non-browser environments may have access to different APIs, which
+[feature testing](FeatureTest.md) and
+[dynamic linking](FutureFeatures.md#dynamic-linking) will make discoverable and
+usable.
+  
+Where there is overlap between the browser and popular non-browser environments,
+a shared spec could be proposed, but this would be separate from the WebAssembly
+spec. A symmetric example in JavaScript would be the
+[Loader](http://whatwg.github.io/loader) spec, intended to be implemented by
+both browsers and node.js. This situation is expected to be first encountered
+with POSIX features such as file I/O. In that respect, WebAssembly would err
+towards standardizing existing practice through libraries, and let developers
+choose which libraries to use.
+
+The WebAssembly spec will not try to define any large portable libc-like
+library. However, certain features that are core to WebAssembly semantics that
+are found in native libc *would* be part of the core WebAssembly spec as either
+primitive opcodes or a special builtin module (e.g., `sbrk`, `mmap`).

Polyfill.md

@@ -21,30 +21,9 @@ as well as to convert [asm.js](http://asmjs.org) into WebAssembly (useful
 for existing applications), is in the [polyfill repo](https://github.com/WebAssembly/polyfill).
 We also leave open the possibility of multiple polyfills existing to meet different developers' needs.
 
-## Implementation Details
-
 An **effective** polyfill should reuse much of the Web platform's existing
-capabilities.
-
-We've identified interesting polyfill implementation approaches which help
-convince us that the design, especially that of the MVP, are sensible:
-
-* A [module](MVP.md#Modules) can be loaded in the same way as an ES6 module
-  (`import` statements, `Reflect` API, `Worker` constructor, etc) and the result
-  is reflected to JS as an ES6 module object.
-  * Exports are the ES6 module object exports.
-  * An import first passes the module name to the
-    [module loader pipeline](http://whatwg.github.io/loader) and resulting ES6
-    module (which could be implemented in JS or WebAssembly) is queried for the
-    export name.
-  * There is no special case for when one WebAssembly module imports another:
-    they have separate [heaps](MVP.md#heap) and pointers cannot be passed
-    between the two. Module imports encapsulate the importer and importee.
-  * To synchronously call into JavaScript from C++, the C++ code would declare
-    and call an undefined `extern` function and the target JavaScript function
-    would be given the (mangled) name of the `extern` and put inside the
-    imported ES6 module.
-
+capabilities, as detailed in the browser embedding
+[implementation details](Web.md#Implementation-Details).
 
 ## Polyfill Deviations
 

Web.md

@@ -0,0 +1,28 @@
+# Browser Embedding
+
+WebAssembly is [originally](MVP.md) targetted at being embedded in browsers as
+an integral part of the Web platform.
+
+A key part of operating on the web is supporting
+[feature testing](FeatureTest.md).
+
+# Implementation Details
+
+We've identified interesting implementation approaches which help convince us
+that the design, especially that of the [MVP](MVP.md), are sensible:
+
+* A [module](MVP.md#Modules) can be loaded in the same way as an ES6 module
+  (`import` statements, `Reflect` API, `Worker` constructor, etc) and the result
+  is reflected to JS as an ES6 module object.
+  * Exports are the ES6 module object exports.
+  * An import first passes the module name to the
+    [module loader pipeline](http://whatwg.github.io/loader) and resulting ES6
+    module (which could be implemented in JS or WebAssembly) is queried for the
+    export name.
+  * There is no special case for when one WebAssembly module imports another:
+    they have separate [heaps](MVP.md#heap) and pointers cannot be passed
+    between the two. Module imports encapsulate the importer and importee.
+  * To synchronously call into JavaScript from C++, the C++ code would declare
+    and call an undefined `extern` function and the target JavaScript function
+    would be given the (mangled) name of the `extern` and put inside the
+    imported ES6 module.