update readme about building the syntax tests

Author: leafo

spec/README.md

@@ -1,6 +1,8 @@
 
 # MoonScript spec guide
 
+## Testing the right code
+
 Because MoonScript is written in MoonScript, and MoonScript specs are written
 in MoonScript, you need to be aware of which copy of MoonScript is actually
 executing the specs.
@@ -19,9 +21,14 @@ MoonScript available in the load path:
 When developing you want to make ensure the tests are executing your changes in
 the current directory, and not testing the system install.
 
-Code running in Busted will have the system install take precedence over the
-loaded version. That means that if you `require "moonscript.base"` for a test,
-you won't get the local copy.
+Busted itself is MoonScript aware, so it means it should have a functional
+MoonScript compiler in order to load the `.moon` test files. This should be the
+system install. After booting your specs though, you would like to use the
+current directory version of MoonScript to the test
+
+Because by default Busted will have the system install take precedence over the
+loaded version, running `require "moonscript.base"` within a test you won't get
+the working directory version of the code that you should be testing.
 
 The `with_dev` spec helper will ensure that any require calls within the spec
 that ask for MoonScript modules. `with_dev` calls a setup and teardown that
@@ -40,7 +47,33 @@ describe "moonscript.base", ->
     moonscript.load "print 12"
 ```
 
-
-`with_dev`'s require function will load the `.lua` files in the local
-directory, not the `moon` ones. You're responsible for compiling them first
+Note that `with_dev`'s `require` function will not use the MoonLoader, it will
+only load the `.lua` files in the working directory directory, not the `moon`
+ones. This means you must compile the working directory version of MoonScript
 before running the tests.
+
+There is a make task to conveniently do all of this:
+
+```
+make test
+```
+
+## Building syntax tests
+
+The test suite has a series of *syntax* tests (`spec/lang_spec.moon`) that
+consist of a bunch of `.moon` files and their expected output. These files
+should capture a large range of syntax that can be verified to have the correct
+output when you make changes to the language.
+
+If you are adding new syntax, or changing the expected output, then these tests
+will fail until you rebuild the expected outputs. You can do this by running
+the syntax test suite with the `BUILD` environment variable set.
+
+There is a make task to conveniently do this:
+
+```
+make build_test_outputs
+```
+
+
+