--- /dev/null
+# Project Overview
+
+Fifth is a self-hosted hobby operating system built around a
+Forth-inspired programming language. It runs on a custom 32-bit
+stack-based virtual CPU, emulated on x86 DOS real mode. The system
+integrates a kernel (compiler + interpreter), a virtual machine
+emulator, device drivers, graphics libraries, a filesystem, a text
+editor, and a graphics editor.
+
+# Key Conventions and Warnings
+
+1. *Do NOT edit =.html= files.* They are generated from =.org= files.
+ Always edit the =.org= source instead.
+
+2. *Files under =imageFile/f/= appear as plain text in the repo but
+ use FSCII encoding internally.* The files checked into git are
+ human-readable source representations. The actual disk image
+ (=disk.raw=) uses FSCII encoding. The conversion tools
+ (=src25th.bas=, =5th2src.bas=) handle translation. When editing
+ Fifth source files in =imageFile/f/=, write standard ASCII text —
+ the build tools handle FSCII conversion.
+
+3. *Two different assembly languages exist in this project:*
+ - =kernel/core.asm= and =kernel/define.inc= use the *virtual CPU's
+ own instruction set* (NOT x86). See the "Virtual CPU Instruction
+ Set" section below.
+ - =emulator/emulator.asm= and its =.inc= files are *x86 real-mode
+ DOS assembly* for FASM (Flat Assembler).
+
+4. *Binary files* (=.raw=, =.com=, =.dat=, =FNT_SYSTEM=,
+ =I01_MCARROW=, =core.raw=, =emulator.com=) are compiled outputs
+ or binary data — do not edit them directly.
+
+5. The project uses *spaces in directory names* (e.g.,
+ ="floppy image/"=). Always quote paths in shell commands.
+
+6. *Numbers in Fifth source are hexadecimal by default*, not decimal.
+ For example, =FF= means 255, =400= means 1024, =3B= means 59.
+ The language has a =d.= word for decimal display but all literals
+ in source code are hex.
+
+# Documentation
+- =doc/index.org= — Project overview, installation, architecture.
+- =doc/language.org= — Complete Fifth language reference (all
+ commands, stack effects, examples).
+- =doc/virtual machine.org= — Virtual CPU architecture.
+- =doc/5TH_ET.txt= — Example Fifth source (text editor).
+
+
+# Components — Detailed File Map
+
+## Kernel (Virtual CPU assembly — NOT x86)
+| File | Description |
+|---------------------|------------------------------------------------|
+| =kernel/core.asm= | Main kernel: compiler, interpreter, core words |
+| =kernel/define.inc= | Virtual CPU opcode macro definitions (FASM) |
+| =kernel/font.asm= | 8×8 bitmap font data (256 characters) |
+| =kernel/core.raw= | Compiled kernel binary (do not edit) |
+
+## Emulator (x86 real-mode FASM assembly)
+| File | Description |
+|-------------------------|--------------------------------------------|
+| =emulator/emulator.asm= | Main emulator: instruction dispatch loop |
+| =emulator/system.inc= | XMS allocation, protected mode, A20 gate |
+| =emulator/vidput.inc= | Image-to-image blit (opaque) |
+| =emulator/tvidput.inc= | Image-to-image blit (transparent, FF=skip) |
+| =emulator/charput.inc= | Character glyph rendering to image buffer |
+| =emulator/kbdrive.inc= | Keyboard interrupt handler + ring buffer |
+| =emulator/compile.sh= | Build script (runs =fasm emulator.asm=) |
+| =emulator/emulator.com= | Compiled DOS COM binary (do not edit) |
+
+
+## High-Level Boot Code (Fifth language)
+| File | Description |
+|-----------------------------|-------------------------------------------------------------------|
+| =imageFile/f/5th_boot= | Core language: compiler, strings, dynamic memory, filesystem, FAT |
+| =imageFile/f/5TH_AUTORUN= | Startup script: loads drivers, shows logo, enters REPL |
+| =imageFile/f/5TH_QUICKPATH= | Shortcut path definitions for navigation |
+
+## Applications (Fifth language)
+| File | Description |
+|-------------------------|--------------------------------------------|
+| =imageFile/f/5th_et= | Full-screen text editor (ET command) |
+| =imageFile/f/5th_eg= | Graphics editor (gedit/geditnew commands) |
+| =imageFile/f/5th_logo= | Draws the Fifth logo on screen at startup |
+| =imageFile/f/5th_demo= | Demo programs (graphics test, mouse test) |
+
+## Libraries (Fifth language, in =imageFile/f/lib/=)
+| File | Description |
+|--------------------|---------------------------------------------------------------|
+| =5th_gfx= | Core graphics: screen buffer, palette, text output, scrolling |
+| =5th_gfx2= | Extended graphics: lines, boxes, flood fill, flip |
+| =5th_trig= | Trigonometry: sin/cos lookup table |
+| =5TH_DRVKBD= | Keyboard driver: scan code reading, layout loading |
+| =5TH_DRVMOUSE= | Mouse driver: position tracking, click regions |
+| =5TH_KBD_US= | US QWERTY keyboard layout scan code → FSCII table |
+| =5TH_KBD_USDVORAK= | US Dvorak keyboard layout table |
+| =5TH_UICMD= | Command-line UI: =words=, =cmdline=, =fs.=, =bye= |
+
+## Help/Data Files
+| File | Description |
+|-------------------------|----------------------|
+| =imageFile/f/txt_help= | General help text |
+| =imageFile/f/txt_et= | Text editor help |
+| =imageFile/f/txt_eg= | Graphics editor help |
+
+## Binary Assets (do not edit)
+| File | Description |
+|----------------------------|--------------------------|
+| =imageFile/f/FNT_SYSTEM= | System font binary |
+| =imageFile/f/I01_MCARROW= | Mouse cursor arrow image |
+
+# Tools (QuickBASIC / FreeBASIC)
+
+| File | Purpose |
+|----------------------|--------------------------------------------------|
+| =tools/5th2src.bas= | Convert FSCII file → readable =.src= text file |
+| =tools/src25th.bas= | Convert readable =.src= text → FSCII =.5th= file |
+| =tools/fsimport.bas= | Import a host file into =disk.raw= virtual disk |
+| =tools/editor.bas= | Source code editor utility |
+| =tools/font.dat= | Font data used by editor tool |
+
+## FSCII ↔ Source Conversion Details
+
+=5th2src.bas= converts: byte 0–9 → ASCII "0"–"9", byte 10–15 →
+ASCII "A"–"F", byte 255 → space, byte 253 → tab, byte 254 → newline.
+Everything else passes through as-is.
+
+=src25th.bas= does the reverse: tries to interpret words as hex
+numbers (converting ASCII "0"–"9" → bytes 0–9, "A"–"F" → bytes
+10–15), space → byte 255, tab → byte 253, newline → byte 254.
+
+# Building & Running
+
+## Compile the Emulator
+
+ cd emulator && bash compile.sh
+
+Requires FASM (Flat Assembler). Produces =emulator.com= (DOS COM).
+
+## Run Under QEMU
+
+ bash "floppy image/run under qemu.sh"
+
+## Mount/Unmount Floppy Image
+
+ bash "floppy image/image mount.sh"
+ bash "floppy image/image umount.sh"
+++ /dev/null
-#+TITLE: AGENTS — Fifth Operating System Project Guide
-#+AUTHOR: Guide for AI coding assistants (Aider, etc.)
-
-* Project Overview
-
-Fifth is a self-hosted hobby operating system built around a
-Forth-inspired programming language. It runs on a custom 32-bit
-stack-based virtual CPU, emulated on x86 DOS real mode. The system
-integrates a kernel (compiler + interpreter), a virtual machine
-emulator, device drivers, graphics libraries, a filesystem, a text
-editor, and a graphics editor.
-
-* Key Conventions and Warnings
-
-** CRITICAL — Read Before Making Any Changes
-
-1. *Do NOT edit =.html= files.* They are generated from =.org= files.
- Always edit the =.org= source instead.
-
-2. *Files under =imageFile/f/= appear as plain text in the repo but
- use FSCII encoding internally.* The files checked into git are
- human-readable source representations. The actual disk image
- (=disk.raw=) uses FSCII encoding. The conversion tools
- (=src25th.bas=, =5th2src.bas=) handle translation. When editing
- Fifth source files in =imageFile/f/=, write standard ASCII text —
- the build tools handle FSCII conversion.
-
-3. *Two different assembly languages exist in this project:*
- - =kernel/core.asm= and =kernel/define.inc= use the *virtual CPU's
- own instruction set* (NOT x86). See the "Virtual CPU Instruction
- Set" section below.
- - =emulator/emulator.asm= and its =.inc= files are *x86 real-mode
- DOS assembly* for FASM (Flat Assembler).
-
-4. *Binary files* (=.raw=, =.com=, =.dat=, =FNT_SYSTEM=,
- =I01_MCARROW=, =core.raw=, =emulator.com=) are compiled outputs
- or binary data — do not edit them directly.
-
-5. The project uses *spaces in directory names* (e.g.,
- ="floppy image/"=). Always quote paths in shell commands.
-
-6. *Numbers in Fifth source are hexadecimal by default*, not decimal.
- For example, =FF= means 255, =400= means 1024, =3B= means 59.
- The language has a =d.= word for decimal display but all literals
- in source code are hex.
-
-** Documentation
-- =doc/index.org= — Project overview, installation, architecture.
-- =doc/language.org= — Complete Fifth language reference (all
- commands, stack effects, examples).
-- =doc/virtual machine.org= — Virtual CPU architecture.
-- =doc/5TH_ET.txt= — Example Fifth source (text editor).
-
-* FSCII Character Encoding
-
-Fifth uses FSCII (Fifth Standard Code for Information Interchange)
-instead of ASCII. Key differences:
-
-| Dec | Hex | FSCII Function |
-|------+-----+---------------------------------------------|
-| 0–15 | 0–F | Hex digit characters (not control codes!) |
-| 252 | FC | Backspace |
-| 253 | FD | Tabulator (TAB) |
-| 254 | FE | Carriage return (newline) |
-| 255 | FF | Space |
-| else | | Same as ASCII (letters, punctuation, etc.) |
-
-This means: ASCII space (32) is NOT space in FSCII. The character "0"
-(ASCII 48) is an ordinary letter, not the number zero. Hex digits 0–F
-are represented by byte values 0–15.
-
-* Virtual CPU Instruction Set
-
-The virtual CPU is stack-based with two stacks: a data stack (=edi=
-register in emulator) and a return stack (=resp=). Instructions are
-single-byte opcodes, some followed by a 32-bit argument.
-
-Opcodes defined in =kernel/define.inc= and dispatched in
-=emulator/emulator.asm=:
-
-| Opcode | Mnemonic | Args | Stack Effect | Description |
-|--------+----------+--------+---------------------------+-----------------------------------|
-| 0 | xnop | | ( -- ) | No operation |
-| 1 | xhalt | | | Halt / exit |
-| 2 | kbd@ | | ( -- scancode ) | Read keyboard scancode |
-| 3 | xnum | 32-bit | ( -- n ) | Push literal number |
-| 4 | xjmp | 32-bit | | Unconditional jump |
-| 5 | xcall | 32-bit | | Call subroutine (push return) |
-| 6 | xinc | | ( n -- n+1 ) | Increment TOS |
-| 7 | xdec | | ( n -- n-1 ) | Decrement TOS |
-| 8 | xdup | | ( n -- n n ) | Duplicate TOS |
-| 9 | xdrop | | ( n -- ) | Drop TOS |
-| 10 | xif | 32-bit | ( flag -- ) | Jump if flag = 0 |
-| 11 | xret | | | Return from subroutine |
-| 12 | xc@ | | ( addr -- byte ) | Fetch byte from memory |
-| 13 | xc! | | ( byte addr -- ) | Store byte to memory |
-| 14 | xpush | | ( n -- ) R:( -- n ) | Move TOS to return stack |
-| 15 | xpop | | ( -- n ) R:( n -- ) | Move from return stack to TOS |
-| 17 | xrot | | ( a b c -- b c a ) | Rotate top 3 (note: non-standard) |
-| 18 | xdisk@ | | ( sector mem -- ) | Load 1024 bytes from disk |
-| 19 | xdisk! | | ( mem sector -- ) | Save 1024 bytes to disk |
-| 20 | x@ | | ( addr -- n ) | Fetch 32-bit from memory |
-| 21 | x! | | ( n addr -- ) | Store 32-bit to memory |
-| 22 | xover | | ( a b -- a b a ) | Copy second to top |
-| 23 | xswap | | ( a b -- b a ) | Swap top two |
-| 24 | xplus | | ( a b -- a+b ) | Add |
-| 25 | xminus | | ( a b -- a-b ) | Subtract |
-| 26 | xmul | | ( a b -- a*b ) | Multiply (signed) |
-| 27 | xdiv | | ( a b -- a/b ) | Divide (signed) |
-| 28 | xcmpg | | ( a b -- flag ) | Greater than |
-| 29 | xcmpl | | ( a b -- flag ) | Less than |
-| 30 | xnot | | ( n -- ~n ) | Bitwise NOT |
-| 31 | xi | | ( -- n ) | Copy return stack TOS |
-| 32 | xcprt@ | | ( port -- byte ) | Read I/O port |
-| 33 | xcprt! | | ( byte port -- ) | Write I/O port |
-| 34 | xi2 | | ( -- n ) | Copy return stack 2nd |
-| 35 | xi3 | | ( -- n ) | Copy return stack 3rd |
-| 36 | xshl | | ( n count -- n<<count ) | Shift left |
-| 37 | xshr | | ( n count -- n>>count ) | Shift right |
-| 38 | lor | | ( a b -- a OR b ) | Bitwise OR |
-| 39 | lxor | | ( a b -- a XOR b ) | Bitwise XOR |
-| 40 | xvidmap | | ( addr -- ) | Map image buffer to VESA video |
-| 41 | xmouse@ | | ( -- btns dy dx ) | Read mouse state |
-| 42 | xvidput | | ( src dst x y -- ) | Blit image to image |
-| 43 | xcmove | | ( src dst count -- ) | Copy memory bytes |
-| 44 | xcfill | | ( byte addr count -- ) | Fill memory with byte |
-| 45 | xtvidput | | ( src dst x y -- ) | Transparent blit (FF=transparent) |
-| 46 | xdep | | ( -- depth ) | Data stack depth |
-| 47 | xcharput | | ( fg bg font dst x y -- ) | Render character glyph |
-
-* Fifth Language Quick Reference
-
-Fifth is Forth-like: postfix notation, stack-based, words separated by
-spaces. Key syntax patterns found in the source code:
-
-** Defining Words
-#+begin_example
-: name ... ; \ Define a new word (subroutine)
-:i name ... ; \ Define immediate word (runs at compile time)
-var name \ Define a 32-bit variable (initialized to 0)
-N vari name \ Define a variable initialized to N
-N const name \ Define a constant
-create name N alloc \ Allocate N bytes of data space
-str content" name \ Define a string constant
-Dstr content" name \ Define a dynamic string constant
-#+end_example
-
-** Control Flow
-#+begin_example
-if ... then \ Conditional
-if ... else ... then \ Conditional with else
-N do ... loop \ Count down from N-1 to 0 (i = counter)
-low high for ... loop \ Count up from low to high-1 (i = counter)
-until ... loop \ Repeat until "done" is called
-#+end_example
-
-** Stack Manipulation
-#+begin_example
-dup drop swap over rot 2dup 2drop nip
-push pop \ Move to/from return stack
-i i2 i3 \ Copy from return stack (loop counters)
-#+end_example
-
-** Memory
-#+begin_example
-@ ! \ 32-bit fetch/store
-c@ c! \ 8-bit fetch/store
-cmove \ Block copy ( src dst count -- )
-cfill \ Block fill ( byte addr count -- )
-#+end_example
-
-** Comments
-#+begin_example
-\ single line comment (to end of line)
-( comment until closing paren )
-.( visible message ) \ Print at compile time
-#+end_example
-
-** Important Idioms in the Codebase
-#+begin_example
-rh name \ Remove word "name" from dictionary (hide it)
- \ Used extensively to keep namespace clean
-modulechk \ Load a module if not already loaded
-include \ Execute code from a file
-D> word \ Parse next word into default dynamic string
-D" string" \ Parse string into default dynamic string
-#+end_example
-
-* Disk Layout and Filesystem
-
-Constants from =5th_boot=:
-
-| Symbol | Hex Value | Description |
-|----------+---------------------------------+--------------------------------------------------|
-| fsroot | 24*400 | Root directory location (sector 24h × 1024) |
-| fsfatbeg | 25 | FAT starts at sector 25h |
-| fsfatsiz | 4000 | FAT size (4000h entries) |
-| fsdata | fsfatbeg + fsfatsiz*4/400 + 1 | Data area start sector |
-
-Sector size is 1024 bytes (=400h=). FAT entry values:
-- =-2= — last sector of a file chain
-- =-1= — free/unused sector
-- =0+= — pointer to next sector
-
-File directory entry (32 bytes):
-| Offset | Size | Content |
-|--------+------+-------------------------------------------------|
-| 0 | 4 | Extension (4-byte FSCII, e.g. "list", "5th_") |
-| 4 | 16 | Filename (padded with FF/spaces) |
-| 20 | 4 | First block address (FAT chain start) |
-| 24 | 4 | File size in bytes |
-
-Special extensions: ="free"= marks deleted entries, ="list"= marks
-directories (subdirectories).
-
-* Memory Map
-
-| Address | Size | Description |
-|----------+---------+----------------------------------------|
-| 0 | ~4096 | Kernel (core.raw) |
-| 1500000h | ~32000 | High-level Fifth boot code (5th_boot) |
-| 200000h | varies | Core startup messages area |
-| 5200000h | | End of dynamic memory space |
-
-Dynamic memory is managed by the =dynal=/=dynde=/=dynp=/=dyns= words
-defined in =5th_boot=. Up to =100h= (256) dynamic blocks.
-
-* Boot Sequence (detailed)
-
-1. Emulator (=emulator.com=) starts, allocates XMS, sets VESA 640×480
- 8-bit mode, loads first 1024 bytes of =disk.raw= into virtual
- memory at address 0.
-2. Kernel (=core.asm=) executes: loads remaining kernel sectors, then
- loads high-level boot code (=5th_boot=) at address =1500000h=.
-3. =5th_boot= defines the compiler, interpreter, all core words
- (arithmetic, stack ops, strings, dynamic memory, filesystem),
- then runs =include= on =5TH_AUTORUN=.
-4. =5TH_AUTORUN= loads graphics library (=5th_gfx=), displays logo
- (=5th_logo=), loads keyboard driver (=5TH_DRVKBD=), loads command
- line UI (=5TH_UICMD=), sets up quick paths, and enters interactive
- mode.
-
-* Components — Detailed File Map
-
-** Kernel (Virtual CPU assembly — NOT x86)
-| File | Description |
-|---------------------+------------------------------------------------|
-| =kernel/core.asm= | Main kernel: compiler, interpreter, core words |
-| =kernel/define.inc= | Virtual CPU opcode macro definitions (FASM) |
-| =kernel/font.asm= | 8×8 bitmap font data (256 characters) |
-| =kernel/core.raw= | Compiled kernel binary (do not edit) |
-
-** Emulator (x86 real-mode FASM assembly)
-| File | Description |
-|-------------------------+--------------------------------------------|
-| =emulator/emulator.asm= | Main emulator: instruction dispatch loop |
-| =emulator/system.inc= | XMS allocation, protected mode, A20 gate |
-| =emulator/vidput.inc= | Image-to-image blit (opaque) |
-| =emulator/tvidput.inc= | Image-to-image blit (transparent, FF=skip) |
-| =emulator/charput.inc= | Character glyph rendering to image buffer |
-| =emulator/kbdrive.inc= | Keyboard interrupt handler + ring buffer |
-| =emulator/compile.sh= | Build script (runs =fasm emulator.asm=) |
-| =emulator/emulator.com= | Compiled DOS COM binary (do not edit) |
-
-** High-Level Boot Code (Fifth language)
-| File | Description |
-|-----------------------------+-------------------------------------------------------------------|
-| =imageFile/f/5th_boot= | Core language: compiler, strings, dynamic memory, filesystem, FAT |
-| =imageFile/f/5TH_AUTORUN= | Startup script: loads drivers, shows logo, enters REPL |
-| =imageFile/f/5TH_QUICKPATH= | Shortcut path definitions for navigation |
-
-** Applications (Fifth language)
-| File | Description |
-|-------------------------+--------------------------------------------|
-| =imageFile/f/5th_et= | Full-screen text editor (ET command) |
-| =imageFile/f/5th_eg= | Graphics editor (gedit/geditnew commands) |
-| =imageFile/f/5th_logo= | Draws the Fifth logo on screen at startup |
-| =imageFile/f/5th_demo= | Demo programs (graphics test, mouse test) |
-
-** Libraries (Fifth language, in =imageFile/f/lib/=)
-| File | Description |
-|--------------------+---------------------------------------------------------------|
-| =5th_gfx= | Core graphics: screen buffer, palette, text output, scrolling |
-| =5th_gfx2= | Extended graphics: lines, boxes, flood fill, flip |
-| =5th_trig= | Trigonometry: sin/cos lookup table |
-| =5TH_DRVKBD= | Keyboard driver: scan code reading, layout loading |
-| =5TH_DRVMOUSE= | Mouse driver: position tracking, click regions |
-| =5TH_KBD_US= | US QWERTY keyboard layout scan code → FSCII table |
-| =5TH_KBD_USDVORAK= | US Dvorak keyboard layout table |
-| =5TH_UICMD= | Command-line UI: =words=, =cmdline=, =fs.=, =bye= |
-
-** Help/Data Files
-| File | Description |
-|-------------------------+----------------------|
-| =imageFile/f/txt_help= | General help text |
-| =imageFile/f/txt_et= | Text editor help |
-| =imageFile/f/txt_eg= | Graphics editor help |
-
-** Binary Assets (do not edit)
-| File | Description |
-|----------------------------+--------------------------|
-| =imageFile/f/FNT_SYSTEM= | System font binary |
-| =imageFile/f/I01_MCARROW= | Mouse cursor arrow image |
-
-* Tools (QuickBASIC / FreeBASIC)
-
-| File | Purpose |
-|----------------------+--------------------------------------------------|
-| =tools/5th2src.bas= | Convert FSCII file → readable =.src= text file |
-| =tools/src25th.bas= | Convert readable =.src= text → FSCII =.5th= file |
-| =tools/fsimport.bas= | Import a host file into =disk.raw= virtual disk |
-| =tools/editor.bas= | Source code editor utility |
-| =tools/font.dat= | Font data used by editor tool |
-
-** FSCII ↔ Source Conversion Details
-
-=5th2src.bas= converts: byte 0–9 → ASCII "0"–"9", byte 10–15 →
-ASCII "A"–"F", byte 255 → space, byte 253 → tab, byte 254 → newline.
-Everything else passes through as-is.
-
-=src25th.bas= does the reverse: tries to interpret words as hex
-numbers (converting ASCII "0"–"9" → bytes 0–9, "A"–"F" → bytes
-10–15), space → byte 255, tab → byte 253, newline → byte 254.
-
-* Building & Running
-
-** Compile the Emulator
-#+begin_src bash
-cd emulator && bash compile.sh
-#+end_src
-Requires FASM (Flat Assembler). Produces =emulator.com= (DOS COM).
-
-** Run Under QEMU
-#+begin_src bash
-bash "floppy image/run under qemu.sh"
-#+end_src
-
-** Mount/Unmount Floppy Image
-#+begin_src bash
-bash "floppy image/image mount.sh"
-bash "floppy image/image umount.sh"
-#+end_src
-
-* Graphics System Details
-
-The screen is a 640×480 (=280h= × =1E0h=) 8-bit indexed color image
-buffer, allocated as a dynamic memory block.
-
-Image buffer format:
-| Offset | Size | Content |
-|--------+------+-------------------------------|
-| 0 | 4 | X size (width) |
-| 4 | 4 | Y size (height) |
-| 8 | X*Y | Pixel data (1 byte per pixel) |
-
-Color is calculated with =calccol ( b g r -- c )= which maps RGB
-(0–255 each) to a 6×6×6 color cube (216 colors). The palette is set
-up by =setupal= in =5th_gfx=.
-
-Text output uses an 8×8 pixel font. Cursor position is tracked by
-=curx= and =cury= variables. The =emit= word is vectored — initially
-it writes to the core message area, then =5th_gfx= redirects it to
-graphical text rendering via =(emit2=.
-
-* In-RAM commands dictionary structure
-
-Each dictionary entry is 24 bytes:
-
-| Offset | Size | Content |
-|--------+------+-------------------------------------------|
-| 0 | 4 | Link to previous entry (0=last, -1=empty) |
-| 4 | 15 | Name string (padded) |
-| 19 | 1 | Type: 0=data, 1=subroutine, 2=immediate |
-| 20 | 4 | Entry data (address of code/data) |
-
-The dictionary is a linked list searched backwards from =lp= (last
-pointer). Up to ~1000 entries fit in the 24000-byte dictionary space.
-
-Type behavior when referenced:
-- Type 0 (data): compiles a =xnum= instruction with the address
-- Type 1 (subroutine): compiles an =xcall= instruction
-- Type 2 (immediate): executes immediately even during compilation
-
-* Keyboard System
-
-Scan codes from the hardware keyboard are buffered by =kbdrive.inc=.
-The Fifth keyboard driver (=5TH_DRVKBD=) provides:
-
-- =KBD_@= — read raw scan code
-- =KBD_SC2FSCII= — convert scan code to FSCII using layout table
-- =KBD_F@= — read FSCII key (with shift/alt modifiers: +100h/+200h)
-- =KBD_FW@= — blocking read (waits for keypress)
-
-Special key codes (FSK — Fifth Standard Keycodes):
-| Code | Key |
-|-------+-----------|
-| 400h | ESC |
-| 401h+ | F1, F2... |
-| 410h | Up |
-| 411h | Right |
-| 412h | Down |
-| 413h | Left |
-| 414h | Insert |
-| 415h | Delete |
-| 416h | Home |
-| 417h | End |
-| 418h | Page Up |
-| 419h | Page Down |
-| FCh | Backspace |
-| FDh | Tab |
-| FEh | Enter |
-| FFh | Space |
-
-* Common Patterns in Fifth Source Code
-
-** Module Loading Guard
-#+begin_example
-D> \listF\listLIB\5TH_GFX modulechk
-#+end_example
-Loads the module only if not already loaded (checks dictionary).
-
-** Variable Cleanup with =rh=
-#+begin_example
-var tmp1 var tmp2
-: myword ... ; rh tmp1 rh tmp2
-#+end_example
-=rh= (remove head) hides temporary variables from the dictionary
-after they're no longer needed externally. The variables still exist
-in memory but can't be found by name.
-
-** Dynamic String Lifecycle
-#+begin_example
-myvar Dv \ allocate dynamic string, store handle in myvar
-... \ use the string
-myvar Df \ deallocate it
-#+end_example
-
-** Vectored Execution (Deferred Words)
-#+begin_example
-defer cmdline \ create forward reference
-...
-' (cmdline ' cmdline is \ point it to actual implementation
-#+end_example
-
-** File Operations
-#+begin_example
-D" \listF\myfile" fsDloadnew \ load file → new dynamic block
-dup dynp \ get pointer to data
-swap dynde \ deallocate when done
-#+end_example
projects / fifth.git / commitdiff