Updated all the READMEs for VVhitespace.

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..d0ef628
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# Overview #
+
+Welcome to the VVhitespace language. This repository provides two main tools.
+
+A compiler, `vvc`, accepts human-readable VVhitespace source code and translates
+it to true VVhitespace code. VVhitespace code is represented with the *whitespace
+characters* `[tTvVsSnN]` corresponding to `[Tab]`, `[Vtab]`, `[Space]`,
+`[Newline]`, respectively. The first character on a line which is not from this
+set begins a comment which ends with the line. See the standard library for
+examples in this style.
+
+An interpreter, `vvi`, accepts true VVhitespace files as generated by `vvc` and
+executes them according to the rules in `reference.md`.
+
+
+# Instructions #
+
+To build the VVhitespace software, simply run `make` in the top level directory.
+This will produce two binaries, `vvc` for compiling human-readable
+pseudo-vvhitespace into true vvhitespace, and `vvi` for interpreting/executing
+vvhitespace programs.
+
+Use these two programs to build and run your VVS programs:
+
+    vvc -i your_code.pvvs -o output_file.vvs
+    vvi -i output_file.vvs
+
+
+# Examples #
+
+The `examples/` folder contains examples with Makefiles. Simply `cd` into an
+example and `make run` to build and execute it. Don't forget to build `vvc`
+and `vvi` first! More details can be found in `examples/README.md`.
+
+
+# Standard Library #
+
+A standard library provides a few convenience functions. More details can be found
+in `stdlib/README.md`. A working example can be found in `examples/hello-stdlib`.

diff --git a/examples/README.md b/examples/README.md
new file mode 100644 (file)
index 0000000..0c415b4
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,13 @@
+# Overview #
+
+This folder contains example VVhitespace programs.
+
+Each program can be built and run by executing `make run` in the example
+sub-directory.
+
+Running `make clean` in a specific example sub-directory will clean up all
+build-related files for that example. Executing the same command in the
+top-level `examples/` directory will clean up every example.
+
+Before running any examples, first run `make` in the top-level VVhitespace
+folder to build `vvc` and `vvi`.

diff --git a/stdlib/README.md b/stdlib/README.md
index 2639a41..e56080f 100644 (file)
--- a/stdlib/README.md
+++ b/stdlib/README.md
@@ -1,5 +1,14 @@
+# Overview #
+
+This folder contains a library of useful functions written in VVhitespace.
+Standard include guards are used with `cpp` to include the stdlib in user
+programs. For an example, see `examples/hello-stdlib`.
+

 # Reservations #
 
 # Reservations #
 

+Since all labels share a global namespace, the standard library makes the
+following reservations:
+

 ## Label ##
 
     00000000 0xxxxxxx - reserved for stdlib function entry points
 ## Label ##
 
     00000000 0xxxxxxx - reserved for stdlib function entry points


@@ -27,3 +36,4 @@ private label space associated with it, formed as follows:
 
     00001000 xxxxxxxx - for use by 1000
     00001001 xxxxxxxx - for use by 1001
 
     00001000 xxxxxxxx - for use by 1000
     00001001 xxxxxxxx - for use by 1001

+    ...etc

diff --git a/tests/README.md b/tests/README.md
new file mode 100644 (file)
index 0000000..ba26732
--- /dev/null
+++ b/tests/README.md
@@ -0,0 +1 @@
+This folder contains tests for `vvi` that are called from `vv_test.py`.