Finished documentation

diff --git a/jonesforth.S b/jonesforth.S
index 2fb8515..710bf28 100644 (file)
--- a/jonesforth.S
+++ b/jonesforth.S
@@ -107,6 +107,14 @@
        strings (or rather it used to, but the developers removed it!) so I've abused the syntax
        slightly to make things readable.  Ignore these warnings.
 
        strings (or rather it used to, but the developers removed it!) so I've abused the syntax
        slightly to make things readable.  Ignore these warnings.
 

+       If you want to run your own FORTH programs you can do:
+
+       ./jonesforth < myprog.f
+
+       If you want to load your own FORTH code and then continue reading user commands, you can do:
+
+       cat myfunctions.f - | ./jonesforth
+

        ASSEMBLER ----------------------------------------------------------------------
 
        (You can just skip to the next section -- you don't need to be able to read assembler to
        ASSEMBLER ----------------------------------------------------------------------
 
        (You can just skip to the next section -- you don't need to be able to read assembler to


@@ -1660,6 +1668,8 @@ _HIDDEN:
        NEXT
 
 /*
        NEXT
 
 /*

+       PRINTING STRINGS ----------------------------------------------------------------------
+

        LITSTRING and EMITSTRING are primitives used to implement the ." operator (which is
        written in FORTH).  See the definition of that operator below.
 */
        LITSTRING and EMITSTRING are primitives used to implement the ." operator (which is
        written in FORTH).  See the definition of that operator below.
 */


@@ -1677,12 +1687,18 @@ _HIDDEN:
        mov $1,%ebx             // 1st param: stdout
        pop %ecx                // 2nd param: address of string
        pop %edx                // 3rd param: length of string
        mov $1,%ebx             // 1st param: stdout
        pop %ecx                // 2nd param: address of string
        pop %edx                // 3rd param: length of string

-

        mov $__NR_write,%eax    // write syscall
        int $0x80
        mov $__NR_write,%eax    // write syscall
        int $0x80

-

        NEXT
 
        NEXT
 

+/*
+       COLD START AND INTERPRETER ----------------------------------------------------------------------
+
+       COLD is the first FORTH function called, almost immediately after the FORTH system "boots".
+
+       INTERPRETER is the FORTH interpreter ("toploop", "toplevel" or REPL might be a more accurate
+       description).
+*/

 
 
        // COLD must not return (ie. must not call EXIT).
 
 
        // COLD must not return (ie. must not call EXIT).


@@ -1756,6 +1772,15 @@ _HIDDEN:
 interpret_is_lit:
        .int 0                  // Flag used to record if reading a literal
 
 interpret_is_lit:
        .int 0                  // Flag used to record if reading a literal
 

+/*
+       ODDS AND ENDS ----------------------------------------------------------------------
+
+       CHAR puts the ASCII code of the first character of the following word on the stack.  For example
+       CHAR A puts 65 on the stack.
+
+       SYSEXIT pops the status off the stack and exits the process (using Linux exit syscall).
+*/
+

        defcode "CHAR",4,,CHAR
        call _WORD              // Returns %ecx = length, %edi = pointer to word.
        xor %eax,%eax
        defcode "CHAR",4,,CHAR
        call _WORD              // Returns %ecx = length, %edi = pointer to word.
        xor %eax,%eax


@@ -1769,13 +1794,38 @@ interpret_is_lit:
        mov $__NR_exit,%eax
        int $0x80
 
        mov $__NR_exit,%eax
        int $0x80
 

-/*----------------------------------------------------------------------
- * Input buffer & initial input.
- */
+/*
+       START OF FORTH CODE ----------------------------------------------------------------------
+
+       We've now reached the stage where the FORTH system is running and self-hosting.  All further
+       words can be written as FORTH itself, including words like IF, THEN, .", etc which in most
+       languages would be considered rather fundamental.
+
+       As a kind of trick, I prefill the input buffer with the initial FORTH code.  Once this code
+       has run (when we get to the "OK" prompt), this input buffer is reused for reading user input.
+
+       Some notes about the code:
+
+       \ (backslash) is the FORTH way to start a comment which goes up to the next newline.  However
+       because this is a C-style string, I have to escape the backslash, which is why they appear as
+       \\ comment.
+
+       Similarly, any backslashes in the code are doubled, and " becomes \" (eg. the definition of ."
+       is written as : .\" ... ;)
+
+       I use indenting to show structure.  The amount of whitespace has no meaning to FORTH however
+       except that you must use at least one whitespace character between words, and words themselves
+       cannot contain whitespace.
+
+       FORTH is case-sensitive.  Use capslock!
+
+       Enjoy!
+*/
+

        .data
        .align 4096
 buffer:
        .data
        .align 4096
 buffer:

-       // XXX gives 'Warning: unterminated string; newline inserted' messages which you can ignore
+       // Multi-line constant gives 'Warning: unterminated string; newline inserted' messages which you can ignore

        .ascii "\
 \\ Define some character constants
 : '\\n'   10 ;
        .ascii "\
 \\ Define some character constants
 : '\\n'   10 ;


@@ -2004,3 +2054,5 @@ currkey:
        .int buffer
 bufftop:
        .int _initbufftop
        .int buffer
 bufftop:
        .int _initbufftop

+
+/* END OF jonesforth.S */