doc: move usage documention out of the system

README.md

@@ -23,14 +23,11 @@ tools.
 
 ## Getting started
 
-Usage documentation is in-system, so access to documentation requires you to
+Documentation is in text files in `doc/`. Begin with `intro.txt`.
-run Collapse OS. Fortunately, building and running Collapse OS on a POSIX
-environment is easy.
 
+Collapse OS can run on any POSIX platform and builds easily.
 See `/cvm/README.md` for instructions.
 
-Then, run `0 LIST` for an introduction, follow instructions from there.
-
 Alternatively, there's also [Michael Schierl's JS Collapse OS emulator][jsemul]
 which is awesome and allows you to run Collapse OS from your browser, but it
 isn't always up to date. The "Javascript Forth" version is especially awesome:
@@ -42,6 +39,7 @@ it's not a z80 emulator, but a *javascript port of Collapse OS*!
          source code is located. Everything else is peripheral.
 * `cvm`: A C implementation of Collapse OS, allowing it to run natively on any
          POSIX platform.
+* `doc`: Documentation.
 * `recipes`: collection of recipes that assemble Collapse OS on a specific
              machine.
 * `tools`: Tools for working with Collapse OS from "modern" environments. For

blk/001

@@ -1,6 +1,6 @@
 MASTER INDEX
 
-  3 Usage                      30 Dictionary
+ 30 Dictionary
  70 Implementation notes      100 Block editor
 120 Visual Editor             150 Extra words
 200 Z80 assembler             260 Cross compilation

blk/003

@@ -1,16 +0,0 @@
-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
-implementation. The recommended introductory book is Starting
-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
-
- 5 Number literals              6 Compilation vs meta-comp.
- 8 Interpreter I/O             11 Signed-ness
-17 DOES>                       18 Disk blocks
-                                                        (cont.)

blk/004

@@ -1,2 +0,0 @@
-21 How blocks are organized    22 Addressed devices
-23 Branching

blk/005

@@ -1,11 +0,0 @@
-Number literals
-
-Traditional Forth often uses HEX/DEC switches to go from deci-
-mal to hexadecimal parsing. Collapse OS parses literals in a
-way that is closer to C.
-
-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/006

@@ -1,14 +0,0 @@
-Compilation vs meta-compilation
-
-Compilation vs meta-compilation. When you compile a word with
-"[COMPILE] foo", it's straightforward: It writes the address
-of word foo to HERE.
-
-When you *meta* compile, it's a bit more mind blowing. It
-fetches the address of the word specified by the caller, then
-writes that number as a literal, followed by a reference to
-",".
-
-Example: ": foo [COMPILE] bar;" is the equivalent of ": foo bar
-;" if bar is not an immediate. However, ": foo COMPILE bar ;"
-is the equivalent of ": foo ['] bar , ;". Got it?

blk/008

@@ -1,16 +0,0 @@
-Interpreter I/O
-
-The INTERPRET loop, the heart of Collapse OS, feeds itself
-from the C< word, which yields a character every time it is
-called. If no character is available to interpret, it blocks.
-
-During normal operations, C< is simply a buffered layer over
-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 a time.
-
-Both C< and KEY can be overridden by setting an alternate
-routine at the proper RAM offset (see B80). For example, C<
-overrides are used during LOAD so that input comes from
-disk blocks instead of keyboard.                        (cont.)

blk/009

@@ -1,6 +0,0 @@
-KEY overrides can be used to, for example, temporarily give
-prompt control to a RS-232 device instead of the keyboard.
-
-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.

blk/011

@@ -1,9 +0,0 @@
-Signed-ness
-
-For simplicity purposes, numbers are generally considered
-unsigned. For convenience, decimal parsing and formatting
-support the "-" prefix, but under the hood, it's all unsigned.
-
-This leads to some oddities. For example, "-1 0 <" is false.
-To compare whether something is negative, use the "0<" word
-which is the equivalent to "0x7fff >".

blk/017

@@ -1,15 +0,0 @@
-DOES>
-
-Used inside a colon definition that itself uses CREATE, DOES>
-transforms that newly created word into a "does cell", that is,
-a regular cell (when called, puts the cell's addr on PS), but
-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> @ ;"

blk/018

@@ -1,16 +0,0 @@
-Disk blocks
-
-Disk blocks are Collapse OS' main access to permanent storage.
-The system is exceedingly simple: blocks are contiguous 
-chunks of 1024 bytes each living on some permanent media such
-as floppy disks or SD cards. They are mostly used for text,
-either informational or source code, which is organized into
-16 lines of 64 characters each.
-
-Blocks are referred to by number, 0-indexed. They are read
-through BLK@ and written through BLK!. When a block is read,
-its 1024 bytes content is copied to an in-memory buffer
-starting at BLK( and ending at BLK). Those read/write
-operations are often implicit. For example, LIST calls BLK@.
-
-                                                        (cont.)

blk/019

@@ -1,16 +0,0 @@
-When a word modifies the buffer, it sets the buffer as dirty
-by calling BLK!!. BLK@ checks, before it reads its buffer,
-whether the current buffer is dirty and implicitly calls BLK!
-when it is.
-
-The index of the block currently in memory is kept in BLK>.
-
-Many blocks contain code. That code can be interpreted through
-LOAD. Programs stored in blocks frequently have "loader blocks"
-that take care of loading all blocks relevant to the program.
-
-Blocks spanning multiple disks are tricky. If your media isn't
-large enough to hold all Collapse OS blocks in one unit, you'll
-have to make it span multiple disks. Block reference in
-informational texts aren't a problem: When you swap your disk,
-you mentally adjust the block number you fetch.         (cont.)

blk/020

@@ -1,8 +0,0 @@
-However, absolute LOAD operations in Collapse OS aren't aware
-of disk spanning and will not work properly in your spanned
-system.
-
-Although the usage of absolute LOAD calls are minimally used
-(relative LOADs are preferred), they are sometimes unavoidable.
-When you span Collapse OS over multiple disks, don't forget to
-adjust those absolute LOADs.

blk/021

@@ -1,13 +0,0 @@
-How blocks are organized
-
-Organization of contiguous blocks is an ongoing challenge and
-Collapse OS' blocks are never as tidy as they should, but we
-try to strive towards a few goals:
-
-1. Block 0 contains documentation discovery core keys to the
-   uninitiated.
-2. First section (up to B100) is usage documentation.
-3. B100-B200 are for runtime usage utilities
-4. B200-B500 are for bootstrapping
-5. The rest is for recipes.
-6. I'm not sure yet how I'll organize multiple arches.

blk/022

@@ -1,6 +0,0 @@
-Addressed devices
-
-A@ and A! are the indirect versions of C@ and C!. Their target
-word is controlled through A@* and A!* and by default point to
-C@ and C*. There is also a AMOVE word that is the same as MOVE
-but using A@ and A!.

blk/023

@@ -1,11 +0,0 @@
-Branching
-
-Branching in Collapse OS is limited to 8-bit. This represents
-64 word references forward or backward. While this might seem
-a bit tight at first, having this limit saves us a non-
-negligible amount of resource usage.
-
-The reasoning behind this intentional limit is that huge
-branches are generally a indicator that a logic ought to be
-simplified. So here's one more constraint for you to help you
-towards simplicity.

doc/usage.txt

@@ -0,0 +1,115 @@
+# Collapse OS usage guide
+
+If you already know Forth, start here. Otherwise, read primer
+first.
+
+We begin with a few oddities in Collapse OS compared to tradi-
+tional forths, then cover higher level operations.
+
+# Signed-ness
+
+For simplicity purposes, numbers are generally considered
+unsigned. For convenience, decimal parsing and formatting
+support the "-" prefix, but under the hood, it's all unsigned.
+
+This leads to some oddities. For example, "-1 0 <" is false.
+To compare whether something is negative, use the "0<" word
+which is the equivalent to "0x7fff >".
+
+# Branching
+
+Branching in Collapse OS is limited to 8-bit. This represents
+64 word references forward or backward. While this might seem
+a bit tight at first, having this limit saves us a non-
+negligible amount of resource usage.
+
+The reasoning behind this intentional limit is that huge
+branches are generally a indicator that a logic ought to be
+simplified. So here's one more constraint for you to help you
+towards simplicity.
+
+# Interpreter I/O
+
+The INTERPRET loop, the heart of Collapse OS, feeds itself
+from the C< word, which yields a character every time it is
+called. If no character is available to interpret, it blocks.
+
+During normal operations, C< is simply a buffered layer over
+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 a time.
+
+Both C< and KEY can be overridden by setting an alternate
+routine at the proper RAM offset (see B80). For example, C<
+overrides are used during LOAD so that input comes from
+disk blocks instead of keyboard.
+
+KEY overrides can be used to, for example, temporarily give
+prompt control to a RS-232 device instead of the keyboard.
+
+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.
+
+# Addressed devices
+
+A@ and A! are the indirect versions of C@ and C!. Their target
+word is controlled through A@* and A!* and by default point to
+C@ and C*. There is also a AMOVE word that is the same as MOVE
+but using A@ and A!.
+
+# Disk blocks
+
+Disk blocks are Collapse OS' main access to permanent storage.
+The system is exceedingly simple: blocks are contiguous 
+chunks of 1024 bytes each living on some permanent media such
+as floppy disks or SD cards. They are mostly used for text,
+either informational or source code, which is organized into
+16 lines of 64 characters each.
+
+Blocks are referred to by number, 0-indexed. They are read
+through BLK@ and written through BLK!. When a block is read,
+its 1024 bytes content is copied to an in-memory buffer
+starting at BLK( and ending at BLK). Those read/write
+operations are often implicit. For example, LIST calls BLK@.
+
+When a word modifies the buffer, it sets the buffer as dirty
+by calling BLK!!. BLK@ checks, before it reads its buffer,
+whether the current buffer is dirty and implicitly calls BLK!
+when it is.
+
+The index of the block currently in memory is kept in BLK>.
+
+Many blocks contain code. That code can be interpreted through
+LOAD. Programs stored in blocks frequently have "loader blocks"
+that take care of loading all blocks relevant to the program.
+
+Blocks spanning multiple disks are tricky. If your media isn't
+large enough to hold all Collapse OS blocks in one unit, you'll
+have to make it span multiple disks. Block reference in
+informational texts aren't a problem: When you swap your disk,
+you mentally adjust the block number you fetch.
+
+However, absolute LOAD operations in Collapse OS aren't aware
+of disk spanning and will not work properly in your spanned
+system.
+
+Although the usage of absolute LOAD calls are minimally used
+(relative LOADs are preferred), they are sometimes unavoidable.
+When you span Collapse OS over multiple disks, don't forget to
+adjust those absolute LOADs.
+
+# How blocks are organized
+
+Organization of contiguous blocks is an ongoing challenge and
+Collapse OS' blocks are never as tidy as they should, but we
+try to strive towards a few goals:
+
+1. Block 0 contains documentation discovery core keys to the
+   uninitiated.
+2. First section (up to B100) is usage documentation.
+3. B100-B200 are for runtime usage utilities
+4. B200-B500 are for bootstrapping
+5. The rest is for recipes.
+6. I'm not sure yet how I'll organize multiple arches.