Update README, misc cleanups

1 files changed, 75 insertions, 8 deletions

diff --git a/README.md b/README.md
index dd99d84..2536f35 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,90 @@
-Cratera Compiler
-================
+The Cratera Programming Language
+================================
 
-This repo contains the Cratera to Lua compiler, as well as support components for the Cratera to Lua compiler, namely a pure-Lua Lua tokenizer and a table-based parser thing.
+Cratera is a language very similar to Lua, (in fact it's a fork of Lua's syntax) and as such most of the Lua manual applies to it, with the following differences.
 
-The Cratera Programming Language
---------------------------------
+Trait method call syntax
+------------------------
 
-Cratera is a language very similar to Lua, and as such most of the Lua manual applies to it. Additionally, it supports the following syntax sugar, called "traits":
+Cratera adds the following syntax on top of Lua, called a "trait method call":
 
-    mytable:[mytrait].myfunction(myargument)
+    mytable:[MyTrait].myfunction(myargument)
 
 which is equivalent to:
 
-    mytable[mytrait].myfunction(mytable, myargument)
+    mytable[MyTrait].myfunction(mytable, myargument)
 
 This syntax sugar is similar to the "methods" syntax sugar ([Lua 5.3 §3.4.10](http://www.lua.org/manual/5.3/manual.html#3.4.10),
 [Lua 5.2 §3.4.9](http://www.lua.org/manual/5.2/manual.html#3.4.9), [Lua 5.1 §2.5.8](http://www.lua.org/manual/5.1/manual.html#2.5.8)),
 and, indeed, `mytable` is only evaluated once.
 
+Traits
+------
+
+(TODO)
+
+Module layout
+-------------
+
+Cratera uses a module system that integrates with Lua's, effectively making Cratera modules interchangeable with Lua modules. However, the file layout is a bit different, particularly for submodules.
+
+For starters, Cratera module filenames end in `.cratera`, so the call:
+
+    local mymodule = require "mymodule"
+
+will look for the file `mymodule.cratera`. But when requiring a submodule, the call:
+
+    local submodule = require "mymodule.submodule"
+
+will look for the file `mymodule.cratera.d/submodule.cratera`. This uses the old UNIX convention of stuffing subfiles of a file `filename` into a directory `filename.d`, for example `profile.d` or `ld.so.conf.d`.
+
+Finally, the Cratera path can be set independently of the Lua path, with the environment variable `CRATERA_PATH` or the Cratera global `craterapath`.
+
+Lua interoperability
+--------------------
+
+### Bootstrapping
+
+Cratera can be bootstrapped from Lua by `require "cratera.bootstrap"`, this initializes the Cratera module system and the Cratera standard library. From here, it's possible to `require` Cratera modules or `load` Cratera scripts:
+
+    local cratera = require "cratera.bootstrap"
+    local cratera_module = require "cratera_module"
+    -- N.B. cratera.loadfile for Cratera scripts, loadfile for regular Lua scripts
+    return cratera.loadfile("myscript.cratera")(...)
+
+However, the provided bootstrap module may not be suitable for all Lua environments. The user is encouraged to bring their own bootstrap.
+
+### Using Lua from Cratera
+
+You can access Lua globals from Cratera using the `lua` table (including `lua.load` - the Lua load function). By default, the Cratera global environment also proxies over to the Lua environment, with a few overrides worth highlighting:
+
+- In Cratera, `load` and `loadfile` refer to the Cratera loader, and by default also set the environment of the loaded function to the Cratera environment.
+- Cratera does not expose `dofile` and `dostring` functions, their slots are set to `false`.
+- `_VERSION` refers to the Cratera version.
+
+### Using Cratera traits from Lua
+
+Since Cratera is simple syntax sugar on top of Lua, it is possible (tho not recommended) to use Cratera traits from plain Lua, by simply hand-coding the desugaring oneself.
+
+    local cratera_obj, CrateraTrait = ...
+    cratera_obj[CrateraTrait].func(cratera_obj)
+
+Building Cratera
+================
+
+Cratera needs to know a few things about the system before it can be used, so the `build.sh` script attempts to provide those things. Most importantly, it needs to know what Lua interpreter to use for the Cratera interpreter, as well as the default Cratera module path.
+
+You can get an overview of these settings and more by running `./build.sh help`. You can override these settings, for example to set a different Lua interpreter, `LUA_INTERPRETER=luajit ./build.sh [command]`.
+
+To build Cratera, run `./build.sh` or `./build.sh build`.
+
+Cratera Compiler
+================
+
+(FIXME clean this up)
+
+The files in `src/cratera/` include the Cratera to Lua compiler, as well as support components for the Cratera to Lua compiler, namely a pure-Lua Lua tokenizer and a table-based parser thing.
+
 Usage
 -----