X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?p=scheme.forth.jl.git;a=blobdiff_plain;f=README.md;h=52b4b6f24b36316f15b9967c61e12af5a018d56b;hp=3c4940d7350c6e5282a52c496035033abeae0e4e;hb=6c019df6b459c86bf5de4fd817db2316038935da;hpb=77a4731ae13761d4817d5cc8af5a74d7d54cb4d7

diff --git a/README.md b/README.md
index 3c4940d..52b4b6f 100644
--- a/README.md
+++ b/README.md
@@ -8,15 +8,99 @@ life as a fairly direct port of Peter Micheaux's [Bootstrap
 Scheme](https://github.com/petermichaux/bootstrap-scheme) (as described in
 [this wonderful series of blog
 posts](http://peter.michaux.ca/articles/scheme-from-scratch-introduction)) from
-C to forth, but also includes a basic mark-sweep garbage collector.
+C to forth, but also includes variadic compound function support, mark-sweep
+garbage collection, quasiquotation, and a basic (non-hygienic) macro
+system.
 
-In future, I plan to also implement a macro system and a more
-complete numerical tower to bring it closer to
+In future, I plan to also implement a more complete numerical tower to bring it closer to
 [R5RS](http://www.schemers.org/Documents/Standards/R5RS/).
 
 The goal is for the interpreter to be complete enough to be used to complete
 the majority of the exercises found in [SICP](http://sarabander.github.io/sicp/).
 
+Running the interpreter
+=======================
+
+To run this Scheme interpreter, first open Julia from the src directory contained
+in this repository.  If you've not done so already, install forth.jl using the
+following command:
+
+    julia> Pkg.clone("https://github.com/tgvaughan/forth.jl")
+
+Then, import and run the Forth system:
+
+    julia> import forth
+    julia> forth.run()
+    Welcome to forth.jl!
+
+Once Forth is running, execute the Scheme source and fire up the
+REPL using the following commands:
+
+    include scheme.4th  ok
+    scheme repl
+    Welcome to scheme.forth.jl!
+    Use Ctrl-D to exit.
+
+    >
+
+At this point you can start entering Scheme commands.  For example,
+
+    > (define (factorial n)
+        (if (= n 0)
+          1
+          (* n (factorial (- n 1)))))
+    ; ok
+    > (factorial 5)
+    ; 120
+
+Metacircular Evaluator
+======================
+
+Of course, one of the things you can do in Scheme (or of course any programming
+language, this is the fundamental thing) is implement an interpreter for
+another programming language.  The examples directory in this repository
+contains a verbatim copy of the source for the "metacircular" scheme interpreter
+from SICP. To load it, use the following command:
+
+    > (load "../examples/metacirc.scm")
+    ; ok
+
+Be prepared to wait a couple of minutes. When the interpreter finally loads, enter
+the following command to run it:
+
+    > (driver-loop)
+
+You'll then be greeted by the following prompt:
+
+    ;; M-Eval input:
+
+At this point you can start entering Scheme commands... but be prepared to wait
+a _long_ time for the result.  For instance, the following example from SICP
+defines and demonstrates a recursive list append procedure:
+
+    (define (append x y)
+       (if (null? x)
+           y
+           (cons (car x)
+                 (append (cdr x) y))))
+
+     ;;; M-Eval value:
+     ok
+
+     ;;; M-Eval input:
+     (append '(a b c) '(d e f))
+
+     ;;; M-Eval value:
+     (a b c d e f)
+
+Be prepared to wait 20 min or more for the final result to be printed.  (Given
+that at this point we have a program running in a Scheme interpreter running
+inside another Scheme interpreter which is itself running on a Forth system
+that is implemented in Julia, this should not be a surprise.)
+
+License
+=======
+
 This software is free (as in freedom) and is distributed under the terms
 of version 3 of the GNU General Public License.  A copy of this license
 is included in this repository in the file COPYING.