From 5c4bbaabf41f8ad7b60659daeb2743906499cac2 Mon Sep 17 00:00:00 2001 From: Virgil Dupras Date: Sat, 15 Aug 2020 19:40:36 -0400 Subject: [PATCH] doc: move usage documention out of the system --- README.md | 8 ++-- blk/001 | 2 +- blk/003 | 16 -------- blk/004 | 2 - blk/005 | 11 ------ blk/006 | 14 ------- blk/008 | 16 -------- blk/009 | 6 --- blk/011 | 9 ----- blk/017 | 15 -------- blk/018 | 16 -------- blk/019 | 16 -------- blk/020 | 8 ---- blk/021 | 13 ------- blk/022 | 6 --- blk/023 | 11 ------ doc/usage.txt | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 17 files changed, 119 insertions(+), 165 deletions(-) delete mode 100644 blk/003 delete mode 100644 blk/004 delete mode 100644 blk/005 delete mode 100644 blk/006 delete mode 100644 blk/008 delete mode 100644 blk/009 delete mode 100644 blk/011 delete mode 100644 blk/017 delete mode 100644 blk/018 delete mode 100644 blk/019 delete mode 100644 blk/020 delete mode 100644 blk/021 delete mode 100644 blk/022 delete mode 100644 blk/023 create mode 100644 doc/usage.txt diff --git a/README.md b/README.md index ab2ca4d..d07eebd 100644 --- a/README.md +++ b/README.md @@ -23,14 +23,11 @@ tools. ## Getting started -Usage documentation is in-system, so access to documentation requires you to -run Collapse OS. Fortunately, building and running Collapse OS on a POSIX -environment is easy. +Documentation is in text files in `doc/`. Begin with `intro.txt`. +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 diff --git a/blk/001 b/blk/001 index 5e258be..cb6f6c4 100644 --- a/blk/001 +++ b/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 diff --git a/blk/003 b/blk/003 deleted file mode 100644 index 34e6f54..0000000 --- a/blk/003 +++ /dev/null @@ -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.) diff --git a/blk/004 b/blk/004 deleted file mode 100644 index b50a1e8..0000000 --- a/blk/004 +++ /dev/null @@ -1,2 +0,0 @@ -21 How blocks are organized 22 Addressed devices -23 Branching diff --git a/blk/005 b/blk/005 deleted file mode 100644 index 7633603..0000000 --- a/blk/005 +++ /dev/null @@ -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. diff --git a/blk/006 b/blk/006 deleted file mode 100644 index b56c956..0000000 --- a/blk/006 +++ /dev/null @@ -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? diff --git a/blk/008 b/blk/008 deleted file mode 100644 index bb6b702..0000000 --- a/blk/008 +++ /dev/null @@ -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.) diff --git a/blk/009 b/blk/009 deleted file mode 100644 index a4b2d82..0000000 --- a/blk/009 +++ /dev/null @@ -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. diff --git a/blk/011 b/blk/011 deleted file mode 100644 index 71d8a77..0000000 --- a/blk/011 +++ /dev/null @@ -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 >". diff --git a/blk/017 b/blk/017 deleted file mode 100644 index db24a29..0000000 --- a/blk/017 +++ /dev/null @@ -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> @ ;" diff --git a/blk/018 b/blk/018 deleted file mode 100644 index c2b7f3f..0000000 --- a/blk/018 +++ /dev/null @@ -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.) diff --git a/blk/019 b/blk/019 deleted file mode 100644 index a2f0863..0000000 --- a/blk/019 +++ /dev/null @@ -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.) diff --git a/blk/020 b/blk/020 deleted file mode 100644 index 07197dc..0000000 --- a/blk/020 +++ /dev/null @@ -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. diff --git a/blk/021 b/blk/021 deleted file mode 100644 index 460d38f..0000000 --- a/blk/021 +++ /dev/null @@ -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. diff --git a/blk/022 b/blk/022 deleted file mode 100644 index 11984ed..0000000 --- a/blk/022 +++ /dev/null @@ -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!. diff --git a/blk/023 b/blk/023 deleted file mode 100644 index de7059b..0000000 --- a/blk/023 +++ /dev/null @@ -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. diff --git a/doc/usage.txt b/doc/usage.txt new file mode 100644 index 0000000..35f577a --- /dev/null +++ b/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.