1
0
mirror of https://github.com/hsoft/collapseos.git synced 2024-12-25 04:58:05 +11:00

doc: move usage documention out of the system

This commit is contained in:
Virgil Dupras 2020-08-15 19:40:36 -04:00
parent a3a83ae49b
commit 5c4bbaabf4
17 changed files with 119 additions and 165 deletions

View File

@ -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

View File

@ -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

16
blk/003
View File

@ -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.)

View File

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

11
blk/005
View File

@ -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.

14
blk/006
View File

@ -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?

16
blk/008
View File

@ -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.)

View File

@ -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.

View File

@ -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 >".

15
blk/017
View File

@ -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> @ ;"

16
blk/018
View File

@ -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.)

16
blk/019
View File

@ -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.)

View File

@ -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.

13
blk/021
View File

@ -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.

View File

@ -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!.

11
blk/023
View File

@ -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.

115
doc/usage.txt Normal file
View File

@ -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.