#77 Clarify project documentation

README.md

@@ -14,7 +14,7 @@ Current travis-ci build status: [![Build Status](https://travis-ci.org/mirkosert
 
 ## Compiling strategies
 
-The JVM Bytecode is parsed and transformed into an [intermediate representation](IR.md). This intermediate representation is passed thru 
+The JVM Bytecode is parsed and transformed into an [intermediate representation](manual/IR.md). This intermediate representation is passed thru 
 optimizer stages and sent to a backend implementation for target code generation.
 
 The *JavaScript* backend transforms the intermediate representation into JavaScript.
@@ -26,7 +26,7 @@ existing programs running on the JVM to utilize the vast power of modern GPUs.
 
 ## Demos
 
-![Demo screenshot](docassets/jbox2ddemo.png)
+![Demo screenshot](manual/docassets/jbox2ddemo.png)
 
  Demo                                            |                                   
 -------------------------------------------------|
@@ -67,11 +67,11 @@ The interesting part is the `Kernel` class. At runtime, the JVM bytecode is tran
 heavily parallel on the GPU. Writing OpenCL Kernels in Java keeps developer productivity up and allows to write efficient 
 algorithms that can transparently executed on the `GPU`.
 
-Details about OpenCL and its usage with Bytecoder are documented [here](OPENCL.md).
+Details about OpenCL and its usage with Bytecoder are documented [here](manual/OPENCL.md).
 
 ## Java to Target Platform Interop
 
-Details about this are documented [here](INTEROP.md).
+Details about this are documented [here](manual/INTEROP.md).
 
 ## Unit testing
 
@@ -94,7 +94,7 @@ public class SimpleMathTest {
 }
 ```
 
-Is compiled to JavaScript and WebAssembly and executed using a Selenium Chrome driver. This test runner also supports comparison of original Java code and its cross compiled counterpart. This mechanism is the core tool to test the compiler and the Classlib.
+is compiled to JavaScript and WebAssembly and executed using a Selenium Chrome driver. This test runner also supports comparison of original Java code and its cross compiled counterpart. This mechanism is the core tool to test the compiler and the Classlib.
 
 Bytecoder relies for WebAssembly unit testing on the WABT toolchain. Compilation is done by invoking the JS version of 
 the WABT tools using Selenium and Chrome. To make everything working, you have to add `CHROMEDRIVER_BINARY` 
@@ -184,6 +184,6 @@ one implementation available.
 *JVM Bytecode* relies on the garbage collection mechanism provided by the Java Runtime. WebAssembly has currently no GC support in version 1.0.
 
 The WebAssembly backend must include garbage collection runtime code for memory management. The first implementation of such a GC will be a Mark-And-Sweep based.
-Details about WebAssembly are documented [here](WASM.md) 
+Details about WebAssembly are documented [here](manual/WASM.md) 
 
 The JavaScript backend relies on JavaScript garbage collection provided by the browser.

INTEROP.md → manual/INTEROP.md

@@ -4,6 +4,38 @@ Programs do now live on their own, they need to communicate with their environme
 This communication can be tricky if done on multiple environments. Bytecoder supports
 JavaScript, WebAssembly and OpenCL as target platforms. How does this wok?
 
+## OpaqueReferenceTypes API
+
+Bytecoder allows transparent usage of APIs not implemented by Bytecoder itself. Such APIs are
+provided by the host environment, for instance the DOM API or interaction with the browser window.
+Bytecoder support such APIs by so called OpaqueReferenceTypes. For every external API, a new OpaqueRecerenceType
+in form of a JVM interface class needs to be created. Bytecoder already comes with implementations for the
+browser window and the DOM.
+
+See the following example, which demonstrates calls from Bytecoder to the HTML Canvas API:
+
+```
+Window window = Window.window();
+Document document = window.document();
+final HTMLCanvasElement theCanvas = document.getElementById("benchmark-canvas");
+CanvasRenderingContext2D renderingContext2D = theCanvas.getContext("2d");
+
+renderingContext2D.moveTo(10, 10);
+renderingContext2D.lineTo(20, 20);
+```
+
+Bytecoder also supports event listeners, as seen in the following example:
+
+```
+final HTMLElement button = document.getElementById("button");
+button.addEventListener("click", new Callback<ClickEvent>() {
+    @Override
+    public void run(ClickEvent aValue) {
+        button.style().setProperty("disabled", "true");
+    }
+});
+```
+
 ## Importing functionality from the host environment
 
 Using host environment functionality is quite common. This can be either simply

IR.md → manual/IR.md

@@ -1,7 +1,7 @@
 # Intermediate representation
 
 The Bytecoder internal intermediate representation is basically a directed graph. The key idea behind this is described 
-[in this paper](core/src/main/java/de/mirkosertic/bytecoder/graph/c2-ir95-150110.pdf).
+[in this paper](../core/src/main/java/de/mirkosertic/bytecoder/graph/c2-ir95-150110.pdf).
 
 Given this Java source code:
 
@@ -28,7 +28,7 @@ The following graph shows the further optimized version of the previous loop:
 
 ![Intermediate representation graph optimized](docassets/ir_loopexample_optimized.svg) 
 
-Part of the compiler optimization is the [relooper step](core/src/main/java/de/mirkosertic/bytecoder/relooper/paper.pdf).
+Part of the compiler optimization is the [relooper step](../core/src/main/java/de/mirkosertic/bytecoder/relooper/paper.pdf).
 Relooping tries to recover high level control flow constructs from the intermediate representation. This step eliminates
 the needs of GOTO statements and thus allows generation of more natural source code, which in turn can be easier read
 and optimized by Web Browsers or other tools.