Working on compatibility with julia 0.7

[forth.jl.git] / README.md

diff --git a/README.md b/README.md
index e0c9767..a6e0645 100644 (file)
--- a/README.md
+++ b/README.md
@@ -6,15 +6,15 @@ 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
 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
 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 with the eventual aim of F83
-compliance (discussed below).
+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.
 
 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")
 
 
     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
 ## Usage
 
 To start the interpreter/compiler running, simply enter the following at


@@ -41,12 +44,10 @@ the library file.  Once this is complete you can start entering forth commands:
     star * ok
 
 There's an example Mandelbrot Set drawing program included in the examples
     star * ok
 
 There's an example Mandelbrot Set drawing program included in the examples

-directory.  To run it, use the `INCLUDE` word to open the file and compile its
-definitions.  Although the exact location of the examples directory in your
-filesystem is platform dependent, `INCLUDE` includes the forth.jl src/ directory
-in its search path so the following should always work:
+directory.  To run it, use the `INCLUDE-LIB` word to open the file and compile its
+definitions:

 
 

-    include ../examples/mandelbrot.4th
+    include-lib ../examples/mandelbrot.4th

     Enter 'mandel' to draw the Mandelbrot Set. ok
     mandel
                                                                                 *                   
     Enter 'mandel' to draw the Mandelbrot Set. ok
     mandel
                                                                                 *                   


@@ -80,27 +81,22 @@ in its search path so the following should always work:
                                                                            **                       
     ok
 
                                                                            **                       
     ok
 

-To exit, enter ^D on a blank line or use the `BYE` word.
+(`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
 
 ## 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 be able to, with a couple of exceptions, be compatible
+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
 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 26 remain unimplemented.  These words fall into
-three categories: those I intend to implement in the near future, 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 to be implemented soon
-
-    PAD ABORT" CMOVE> VOCABULARY DEFINITIONS FORTH
-
-User-defined vocabularies aren't in there yet but this should be easy to solve.
-`PAD`, `ABORT` and `CMOVE>` are simple oversights.
+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
 
 
 ### F83 Words that may be implemented someday
 


@@ -115,7 +111,7 @@ not been interested in enough yet to get on top of.
     SAVE-BUFFERS UPDATE BLK HOLD LOAD FORTH-83
 
 These words don't make sense to implement.  The double-length integer words are
     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
+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.
 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.