Improve onboarding

asm/compiler.asm

@@ -1,4 +1,4 @@
-; C, , ; IMMEDIATE [ ] STATE : HEADER LIT LITC COMPILE, LITERAL HERE DODOES
+; C, , [ ] ; IMMEDIATE STATE LATESTXT : HEADER LIT LITC COMPILE, LITERAL HERE DODOES
 
 curr_word_no_tail_call_elimination
     !byte 1

asm/core.asm

@@ -1,5 +1,5 @@
-; DROP SWAP DUP ?DUP NIP OVER 2DUP 1+ 1- + = 0= AND ! @ C! C@ COUNT > < MAX MIN TUCK
-; >R R> R@ BL PICK DEPTH WITHIN FILL BASE 2*
+; DROP SWAP DUP ?DUP NIP OVER 2DUP 1+ 1- + = 0= AND ! @ C! C@ COUNT
+; < > MAX MIN TUCK >R R> R@ BL PICK DEPTH WITHIN FILL BASE 2* ROT
 
     +BACKLINK "drop", 4 | F_IMMEDIATE
 DROP

asm/disk.asm

@@ -1,4 +1,4 @@
-; DEVICE LOADB SAVEB INCLUDED
+; DEVICE RDERR LOADB SAVEB INCLUDED
 
 READST = $ffb7
 SETLFS = $ffba

asm/durexforth.asm

@@ -1,57 +1,95 @@
+; PUSHYA 0 1 START MSB LSB LATEST
+
 ; ACME assembler
 
 !cpu 6510
 !to "durexforth.prg", cbm	; set output file and format
+!ct pet
 
-* = $801
-
-!byte $b, $08, $a, 0, $9E, $32, $30, $36, $31, 0, 0, 0 ; basic header
-
-;; Word flags
-F_IMMEDIATE = $80
-; When set, calls to the word will not be subject to tail call elimination.
-; I.e., "jsr WORD + rts" will not be replaced by "jmp WORD".
-F_NO_TAIL_CALL_ELIMINATION = $40
-STRLEN_MASK = $1f
+; Opcodes.
+OP_JMP = $4c
+OP_JSR = $20
+OP_RTS = $60
+OP_INX = $e8
 
-TIB = $200
+; CHROUT keys.
+K_RETURN = $d
+K_CLRSCR = $93
+K_SPACE = ' '
 
-; Zeropage
+; Addresses.
+LSB = $3b ; low-byte stack placed in [3 .. $3a]
+MSB = $73 ; high-byte stack placed in [$3b .. $72]
+W = $8b ; rnd seed        \  Temporary work area
+W2 = $8d ; rnd seed        ) available for words.
+W3 = $9e ; tape error log /  Each two bytes.
+TIB = $200 ; text input buffer
+PROGRAM_BASE = $801
+;HERE_POSITION = $801 + assembled program (defined below)
+WORDLIST_BASE = $9fff
+PUTCHR = $ffd2 ; kernal CHROUT routine
+
+; Parameter Stack
+; ---------------
 
-; Parameter stack
 ; The x register contains the current stack depth.
 ; It is initially 0 and decrements when items are pushed.
 ; The parameter stack is placed in zeropage to save space.
 ; (E.g. lda $FF,x takes less space than lda $FFFF,x)
 ; We use a split stack that store low-byte and high-byte
 ; in separate ranges on the zeropage, so that popping and
 ; pushing gets faster (only one inx/dex operation).
+
 X_INIT = 0
-MSB = $73 ; high-byte stack placed in [$3b .. $72]
-LSB = $3b ; low-byte stack placed in [3 .. $3a]
 
-W = $8b ; rnd seed
-W2 = $8d ; rnd seed
-W3 = $9e ; tape error log
+; Dictionary
+; ----------
 
-OP_JMP = $4c
-OP_JSR = $20
-OP_RTS = $60
-OP_INX = $e8
+; Grows backwards from WORDLIST_BASE. Each entry has one
+; byte of flag bits + name length, followed by the bytes of
+; the word's name, and a two-byte "execution token," the
+; address of its code. The address of a dictionary entry is
+; called the word's "name token."
 
-PUTCHR = $ffd2 ; put char
+STRLEN_MASK = $1f
+F_IMMEDIATE = $80 ; interpret the word even in compiler STATE
+F_NO_TAIL_CALL_ELIMINATION = $40
+; Exempt this word from tail call elimination i.e.
+; "jsr WORD + rts" will not be replaced by "jmp WORD".
 
-K_RETURN = $d
-K_CLRSCR = $93
-K_SPACE = ' '
+* = WORDLIST_BASE
+
+!byte 0 ; zero name length signals end of dictionary.
+
+!set __LATEST = WORDLIST_BASE
+!macro BACKLINK .name , .namesize {
+    !set __LATEST = __LATEST - 3 - len(.name)
+    !set .xt = *
+    * = __LATEST
+    !byte .namesize
+    !text .name
+    !word .xt
+    * = .xt
+}
 
-; PLACEHOLDER_ADDRESS instances are overwritten using self-modifying code.
-; It must end in 00 for situations where the Y register is used as the LSB of the address.
+; Program Space
+; -------------
+
+; Main assembly starts at PROGRAM_BASE, then the assembled
+; compiler begins writing at HERE_POSITION, to which we
+; assemble a startup routine that we're okay with being
+; overwritten.
+
+; PLACEHOLDER_ADDRESSes are assembled into the instruction
+; stream then self-modified by the running program. Low
+; byte must be 0 for situations where the Y register is
+; used instead.
 PLACEHOLDER_ADDRESS = $1200
 
-!ct pet
+* = PROGRAM_BASE
 
-; -------- program start
+!byte $b, $08, $a, 0, $9E, $32, $30, $36, $31, 0, 0, 0
+; basic header, and program entry:
 
     tsx
     stx INIT_S
@@ -67,33 +105,7 @@ PLACEHOLDER_ADDRESS = $1200
 _START = * + 1
     jsr load_base
 
-; ----------- macros
-
-!set WORDLIST_BASE = $9fff
-!set __LATEST = WORDLIST_BASE
-
-!set BACK = *
-* = __LATEST
-!byte 0
-* = BACK
-
-!macro BACKLINK .name , .namesize {
-    !set __LATEST = __LATEST - 3 - len(.name)
-    !set .xt = *
-    * = __LATEST
-    !byte .namesize
-    !text .name
-	!word .xt
-    * = .xt
-}
-
-!macro VALUE .word {
-    lda	#<.word
-    ldy	#>.word
-    jmp pushya
-}
-
-; ---------- words
+    ; begin word definitions
 
     +BACKLINK "pushya", 6
 pushya
@@ -108,6 +120,12 @@ ZERO
     tay
     jmp pushya
 
+!macro VALUE .word {
+    lda	#<.word
+    ldy	#>.word
+    jmp pushya
+}
+
     +BACKLINK "1", 1
 ONE
     +VALUE 1

asm/interpreter.asm

@@ -1,4 +1,5 @@
-; QUIT INTERPRET FIND FIND-NAME >CFA PARSE-NAME WORD EXECUTE EVALUATE ' ABORT /STRING
+; QUIT EXECUTE INTERPRET NOTFOUND ' FIND FIND-NAME >XT
+; PARSE-NAME WORD EVALUATE ABORT /STRING DOWORDS
 
 restore_handler
     pha             ; save a
@@ -89,7 +90,7 @@ close_all_logical_files:
     tax
     dex
     bne -
-    
+
     pla
     tax
     rts

asm/io.asm

@@ -1,4 +1,4 @@
-; TYPE EMIT PAGE KEY? KEY REFILL SOURCE SOURCE-ID >IN GETC CHAR
+; EMIT PAGE RVS CR TYPE KEY? KEY REFILL SOURCE SOURCE-ID >IN GETC CHAR IOABORT
 
     +BACKLINK "emit", 4
 EMIT

asm/math.asm

@@ -1,8 +1,8 @@
+; U< - UM* UM/MOD M+ INVERT NEGATE ABS * DNEGATE M* 0< S>D FM/MOD /MOD UD/MOD
+
 ; UM/MOD by Garth Wilson
 ; http://6502.org/source/integers/ummodfix/ummodfix.htm
 
-; U< - UM* UM/MOD M+ INVERT NEGATE ABS * DNEGATE M* 0< S>D FM/MOD /MOD UD/MOD
-
     +BACKLINK "u<", 2
 U_LESS
     ldy #0

asm/move.asm

@@ -1,3 +1,5 @@
+; MOVE
+
 ; routines adapted from cc65
 ; original by Ullrich von Bassewitz, Christian Krueger, Greg King