Add rationale and flow docs

Author: tmcw

README.md

@@ -20,6 +20,10 @@ Shortcuts for wasm
 
 ## [Introduction](doc/intro.md)
 
+## [Flow](doc/flow.md)
+
+## [Rationale](doc/rationale.md)
+
 ## [Planning](doc/planning.md)
 
 ## Contributing & open source

doc/flow.txt

@@ -0,0 +1,39 @@
+ 
+     ┌─────────────────┐               
+  ┌──│   wah source    │               
+  │  └─────────────────┘               
+  │   is parsed as                     
+  │  ┌───────────────────────────────┐ 
+  ├──│edn (extensible data notation) │ 
+  │  └───────────────────────────────┘ 
+  │   by the                           
+  │  ┌───────────────┐                 
+  ├──│ wah compiler  │────────────┐    
+  │  └───────────────┘            │    
+  │   written in                  │    
+  │  ┌──────────┐                 │    
+  ├──│ clojure  │                 │    
+  │  └──────────┘                 │    
+  │   which runs in the           │    
+  │  ┌──────────────────────┐     │    
+  └─▶│ Java Virtual Machine │     │    
+     └──────────────────────┘     │    
+                                  │    
+                                  │    
+      generates                   │    
+     ┌─────────────────────────┐  │    
+  ┌──│ WebAssembly Text (WAST) │◀─┘    
+  │  └─────────────────────────┘       
+  │   is compiled by                   
+  │  ┌─────────────────────────────┐   
+  ├──│      wabt (wast2wasm)       │   
+  │  └─────────────────────────────┘   
+  │   into                             
+  │  ┌─────────────────────────────┐   
+  └─▶│  WebAssembly Binary (wasm)  │──┐
+     └─────────────────────────────┘  │
+                                      │
+      and links with                  │
+     ┌─────────────────────────────┐  │
+     │         JavaScript          │◀─┘
+     └─────────────────────────────┘   

doc/intro.md

@@ -39,6 +39,9 @@ and
 (%0 + %1)
 ```
 
+See [the rationale explanation](./rationale.md) for more details about why this
+might be useful and why I built it.
+
 ## The stack
 
 The complete flow of using wah is:
@@ -48,6 +51,8 @@ The complete flow of using wah is:
 * Compile WAST to WASM using [wabt](https://github.com/webassembly/wabt)'s `wast2wasm`
 * Load and run in a browser using the instantiation code like:
 
+See [the flow diagram](./flow.txt) for a graphical explanation.
+
 ```js
 fetch('./output.wasm').then(response =>
   response.arrayBuffer()

doc/rationale.md

@@ -0,0 +1,24 @@
+# Why wah?
+
+Well, WebAssembly text isn't _designed_ to be written from scratch, but it's
+still writable, and really isn't that bad. wah makes WebAssembly text just
+a little more humane, so that people with a need for extreme simplicity and
+low-level access can get it.
+
+WebAssembly will definitely, primarily, be a compilation target for things
+like emscripten. But why not have some low-level mathematical code written in,
+and purely written in, WebAssembly?
+
+# Why is the compiler implemented in Clojure?
+
+Clojure _looks_ a lot like WebAssembly text format because they both use S-Expressions,
+but, obviously, WebAssembly text format is not a lisp and has very little else
+in common. The compiler is implemented in Clojure because of Clojure's excellent
+support for the [edn format](https://github.com/edn-format/edn), which fortunately
+is a superset of WebAssembly text syntax. Clojure is also a very nice, functional
+language with efficient and direct ways of expressing the kind of data-transformation
+logic required for wah.
+
+# Could it be implemented in ClojureScript?
+
+Sure! It might even already work in ClojureScript, I just haven't tried yet. PRs welcome!