X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?p=forth.jl.git;a=blobdiff_plain;f=README.md;h=a6e0645b2a34c19dcd6b0b5fa86dc14107186679;hp=e19732d2c579804831b8d8e4b1a9ae7ee2f0e507;hb=43cd7e6d8968a85ee9250033080268caafef5a47;hpb=717723c8ac4f859a15af053b1e7f3057887c3c06

diff --git a/README.md b/README.md
index e19732d..a6e0645 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,20 @@
 # forth.jl
 
-A hobby implementation of a FORTH-like system atop the Julia scientific
-computing language.  It will almost certainly never be useful for any purpose
-besides, that which it has already fulfilled: forcing me to think quite
-carefully about how forth works. 
+A hobby implementation of a forth system atop the Julia scientific computing
+language.  It will almost certainly never be useful for any purpose besides
+that which it has already fulfilled: forcing me to think quite carefully about
+how forth works. 
 
 This package owes a massive debt to the existence of the literate programming
-project [JonesForth] (https://rwmj.wordpress.com/2010/08/07/jonesforth-git-repository/),
+project [JonesForth](https://rwmj.wordpress.com/2010/08/07/jonesforth-git-repository/),
 which was an amazing read. To a large degree my package is simply a port of
 that project from x86 assembly + forth to julia + forth, although the mapping
 is in a few places non-trivial due to the fact that julia is a high level
-language.  A huge proportion (say 80%) of the library code in src/lib.4th is
-directly copied from JonesForth.  (The fact that it was possible to reuse this
-code was satisfying in its own right!) I've added some additional core
-definitions and modified some of the others to be a little bit closer to the
-behaviour of ANS forth (or at least FORTH 83).
+language.  During the bootstrapping process, a huge proportion (say 80%) of the
+library code in src/lib.4th was directly copied from JonesForth.  (The fact
+that it was possible to reuse this code was satisfying in its own right!) Since
+that time I've added a significant number of core definitions and modified some
+of the others with the eventual aim of F83 compliance (discussed below).
 
 There's quite a lot to say about the implementation, especially due to its
 high-level grounding, but that will have to wait for another time.
@@ -26,6 +26,9 @@ install it, you will therefore need to use the following command:
 
     julia> Pkg.clone("https://github.com/tgvaughan/forth.jl")
 
+Currently, forth.jl **requires** Julia 0.6. (Incompatabilities exist between
+0.6 and previous versions of julia, particularly the handling of [world age](https://github.com/JuliaLang/julia/pull/17057).)
+
 ## Usage
 
 To start the interpreter/compiler running, simply enter the following at
@@ -37,23 +40,14 @@ the julia prompt:
 The first thing the interpreter will do is compile the core definitions in
 the library file.  Once this is complete you can start entering forth commands:
 
-    : star 42 emit ;
-     ok
-    star
-    * ok
-
-Notice that unlike other forths, forth.jl echos a newline after reading each
-line of standard input.  This is an unfortunate side-effect of the way that
-I've implemented the primitive word KEY.  Hopefully I'll be able to fix this
-in future.
+    : star 42 emit ;  ok
+    star * ok
 
 There's an example Mandelbrot Set drawing program included in the examples
-directory.  To run it, you'll have to locate this directory on your system (its
-location depends on what OS you happen to be using and how julia is installed).
-Once found, use the "INCLUDE" word to compile its definitions. For example, on
-my system I can run the example in this way:
+directory.  To run it, use the `INCLUDE-LIB` word to open the file and compile its
+definitions:
 
-    include /home/tim/.julia/v0.4/forth/examples/mandelbrot.4th
+    include-lib ../examples/mandelbrot.4th
     Enter 'mandel' to draw the Mandelbrot Set. ok
     mandel
                                                                                 *                   
@@ -87,6 +81,41 @@ my system I can run the example in this way:
                                                                            **                       
     ok
 
+(`INCLUDE-LIB` is exactly like INCLUDE, but includes files relative to thte
+platform-dependent forth.jl src/ directory.) To exit, enter ^D on a blank line
+or use the `BYE` word.
+
+## FORTH-83 Compliance
+
+One of my goals has been to have forth.jl contain as much of the
+[F83 required word set](http://forth.sourceforge.net/standard/fst83/fst83-12.htm) 
+as makes sense given the underlying VM. (Actually, my main goal goes a bit
+beyond this: I want to forth.jl to be, with a couple of exceptions, compatible
+with the description of forth contained in the second edition of Leo Brodie's
+book "Starting Forth".)  I'm fairly happy with my progress so far.  Of the
+131 required F83 words, only 20 remain unimplemented.  These words fall into
+two categories: those I may possibly implement at some point, and those that I
+do not intend to ever implement for reasons of obsolescence or incompatibility
+with the design of the VM.
+
+### F83 Words that may be implemented someday
+
+    # #> #S -TRAILING <#
+
+These words all have to do with number to string conversion, something I've
+not been interested in enough yet to get on top of.
+
+### F83 Words that won't be implemented
+
+    D+ D< DNEGATE U< UM* UM/MOD BLOCK BUFFER FLUSH
+    SAVE-BUFFERS UPDATE BLK HOLD LOAD FORTH-83
+
+These words don't make sense to implement.  The double-length integer words are
+useless because the smallest unit of memory in our VM is a full 64 bit
+integer.  For the same reason, there's no point in dealing with unsigned values
+just to gain access to another bit.  The block I/O words don't make sense because
+we have access to a filesystem via the OS.
+
 ## License
 
 This package is free software and is distributed under version 3.0 of the GNU