Revamp usage guide a bit

blk/003

@@ -2,15 +2,15 @@ Collapse OS usage guide
 
 This document is not meant to be an introduction to Forth, but
 to instruct the user about the peculiarities of this Forth
-implemenation. Be sure to refer to dictionary for a word
+implementation. The recommended introductory book is Starting
-reference.
+Forth by Leo Brodie. This is the reference that was used to
+build this implementation and many of the conventions described
+in this book are followed in Collapse OS. Be sure to refer to
+the dictionary (B30) for a word reference.
 
 Contents
 
- 4 DOES>                        6 Compilation vs meta-comp.
+ 4 Number literals              6 Compilation vs meta-comp.
- 8 I/O                         14 Addressed devices         
+ 8 Interpreter I/O             11 Signed-ness
-18 Signed-ness
+14 Addressed devices         
-
-
-
 

blk/004

@@ -1,16 +1,11 @@
-DOES>
+Number literals
 
-Used inside a colon definition that itself uses CREATE, DOES>
+Traditional Forth often use HEX/DEC switches to go from decimal
-transforms that newly created word into a "does cell", that is,
+to hexadecimal parsing. Collapse OS parses literals in a way
-a regular cell ( when called, puts the cell's addr on PS), but
+that is closer to C.
-right after that, it executes words that appear after the
-DOES>.
-
-"does cells" always allocate 4 bytes (2 for the cell, 2 for the
-DOES> link) and there is no need for ALLOT in colon definition.
-
-At compile time, colon definition stops processing words when
-reaching the DOES>.
-
-Example: ": CONSTANT CREATE HERE @ ! DOES> @ ;"
 
+Straight numbers are decimals, numbers starting with "0x"
+are hexadecimals (example "0x12ef"), "0b" prefixes indicate
+binary (example "0b1010"), char literals are single characters
+surrounded by ' (example 'X'). Char literals can't be used for
+whitespaces.

blk/008

@@ -1,16 +1,16 @@
-I/O
+Interpreter I/O
 
-A little word about inputs. There are two kind of inputs:
+The INTERPRET loop, the heart of Collapse OS, feeds itself
-direct and buffered.  As a general rule, we read line in a
+from the C< word, which yields a character every time it is
-buffer, then feed words in it to the interpreter. That's what
+called. If no character is available to interpret, it blocks.
-"WORD" does. If it's at the End Of Line, it blocks and wait
-until another line is entered.
 
-KEY input, however, is direct. Regardless of the input buffer's
+During normal operations, C< is simply a buffered layer over
-state, KEY will return the next typed key.
+KEY, which has the same behavior (but unbuffered). Before
+yielding any character, the C< routine fetches a whole line
+from KEY, puts it in a buffer, then yields the buffered line,
+one character at once.
 
-PARSING AND BOOTSTRAP: Parsing number literal is a very "core"
+Both C< and KEY can be overridden by setting an alternate
-activity of Forth, and therefore generally seen as having to be
+routine at the proper RAM offset (see B80). For example, C<
-implemented in native code.  However, Collapse OS' Forth
+overrides are used during LOAD so that input comes from
-supports many kinds of literals: decimal, hex, char, binary.
+disk blocks instead of keyboard.                        (cont.)
-This incurs a significant complexity penalty.           (cont.)

blk/009

@@ -1,16 +1,6 @@
-(cont.) What if we could implement those parsing routines in
+KEY overrides can be used to, for example, temporarily give
-Forth? "But it's a core routine!" you say. Yes, but here's the
+prompt control to a RS-232 device instead of the keyboard.
-deal: at its native core, only decimal parsing is supported. It
-lives in the "(parsed)" word. The interpreter's main loop is
-initially set to simply call that word.
-
-However, in core.fs, "(parsex)", "(parsec)" and "(parseb)" are
-implemented, in Forth, then "(parse)", which goes through them
-all is defined. Then, "(parsef)", which is the variable in
-which the interpreter's word pointer is set, is updated to that
-new "(parse)" word.
-
-This way, we have a full-featured (and extensible) parsing with
-a tiny native core.
-
 
+Interpreter output is unbuffered and only has EMIT. This
+word can also be overriden, mostly as a companion to the
+raison d'etre of your KEY override.