docs: fix opcode table errors, kbd@ byte-store semantics, drop TODOs

- virtual machine.org: correct divide stack effect (n1 n2 -- n1/n2,
  was inverted as n2/n1), fix subtract wording (subtract top item from
  second), document comparison truth convention (-1 = true, 0 = false,
  signed) — clears all 4 dangling TODO markers from the opcode table.
- opcodes_00_09.org: document that kbd@ writes only the low byte of
  the pushed cell (upper bytes are stale stack memory), note the host
  DOS/BIOS keyboard-buffer drain side effect, clarify num advances IP
  5 bytes total, state that drop leaves the value in memory, and add
  the XMS unlock/free step to the halt cleanup list.

diff --git a/Documentation/opcodes_00_09.org b/Documentation/opcodes_00_09.org
index ddc530e..7610959 100644 (file)
--- a/Documentation/opcodes_00_09.org
+++ b/Documentation/opcodes_00_09.org
@@ -105,7 +105,8 @@ to exit the Fifth environment. When executed, the emulator:
 1. Restores text video mode (mode 3)
 2. Closes the virtual disk file handle
 3. Restores the original keyboard interrupt handler
-4. Returns control to DOS
+4. Unlocks and frees the XMS extended-memory block
+5. Returns control to DOS
 
 ** When to Use
 
@@ -142,6 +143,11 @@ Reads a keyboard scancode from the internal ring buffer and pushes it
 onto the data stack. This is a non-blocking operation: if no key is
 pending, it pushes 0 immediately.
 
+Only the low byte of the pushed stack cell is written; the upper three
+bytes keep whatever the stack memory previously held. Read the result
+with =c@=-style byte semantics (e.g. mask with =FF and=) before
+comparing as a full 32-bit value.
+
 ** Scan Code Behavior
 
 The keyboard hardware generates scan codes for every key event:
@@ -187,8 +193,10 @@ Basic key reading:
 
 ** Return Values
 
-- Returns =0= if no key is available in the buffer
-- Returns scancode (1-255) when a key event is pending
+- The low byte of the result is =0= if no key is available in the
+  buffer, or the scancode (1-255) when a key event is pending
+- The upper three bytes of the stack cell are undefined (leftover stack
+  memory)
 - Each call consumes one scancode from the buffer
 
 ** Important Notes
@@ -197,6 +205,9 @@ Basic key reading:
 - Use a keyboard layout file (like =5TH_KBD_US=) to translate scan
   codes to FSCII characters
 - The buffer holds 128 scan codes; older codes are overwritten if full
+- After reading, one key is also drained from the host DOS/BIOS
+  keyboard buffer, so keys pressed during emulation do not bleed into
+  the DOS prompt after exit
 
 * 3: num (Push Literal Number)
 :PROPERTIES:
@@ -216,7 +227,8 @@ Basic key reading:
 
 Pushes a 32-bit literal value onto the data stack. The value is encoded
 directly in the instruction stream immediately after the opcode byte.
-After execution, the instruction pointer advances by 4 bytes.
+After execution, the instruction pointer has advanced 4 bytes past the
+literal (5 bytes total including the opcode byte).
 
 ** Bytecode Format
 
@@ -576,8 +588,9 @@ drop            ; now consume it
 
 ** Description
 
-Removes and discards the value from the top of the data stack. The
-value is completely lost.
+Removes and discards the value from the top of the data stack. Only the
+stack pointer moves — the value remains in memory above the new stack
+top but is no longer reachable as a stack item.
 
 ** When to Use
 
@@ -623,6 +636,7 @@ then
 ** Important Notes
 
 - Reduces stack depth by 1
-- The value is completely lost; ensure you don't need it
+- The dropped value stays in memory above the new stack top but is
+  unreachable; ensure you don't need it
 - Often paired with =dup= for testing values without consuming them
 - For discarding two values, use =2drop= (defined in high-level Fifth)

diff --git a/Documentation/virtual machine.org b/Documentation/virtual machine.org
index 4078fc4..fddabf3 100644 (file)
--- a/Documentation/virtual machine.org
+++ b/Documentation/virtual machine.org
@@ -137,11 +137,11 @@ in FIFTH programming language):
 | 22 | [[file:opcodes_20_29.org::#opcode-over][over]]     | n1 n2 -- n1 n2 n1     | Duplicate second item on data stack                      |                                                                     |
 | 23 | [[file:opcodes_20_29.org::#opcode-swap][swap]]     | n1 n2 -- n2 n1        | Swap top two items on data stack                         |                                                                     |
 | 24 | [[file:opcodes_20_29.org::#opcode-add][+]]        | n1 n2 -- n1+n2        | Add top two items on data stack                          |                                                                     |
-| 25 | [[file:opcodes_20_29.org::#opcode-sub][-]]        | n1 n2 -- n1-n2        | Subtract second item from top item on data stack         | TODO: verify argument order                                         |
+| 25 | [[file:opcodes_20_29.org::#opcode-sub][-]]        | n1 n2 -- n1-n2        | Subtract top item from second item on data stack         |                                                                     |
 | 26 | [[file:opcodes_20_29.org::#opcode-mul][*]]        | n1 n2 -- n1*n2        | Multiply top two items on data stack                     |                                                                     |
-| 27 | [[file:opcodes_20_29.org::#opcode-div][/]]        | n1 n2 -- n2/n1        | Divide top item by second item on data stack             | TODO: verify argument order                                         |
-| 28 | [[file:opcodes_20_29.org::#opcode-gt][>]]        | n1 n2 -- result       | Compare n1 > n2 (returns true, false otherwise)          | TODO: document, what true and false means                           |
-| 29 | [[file:opcodes_20_29.org::#opcode-lt][<]]        | n1 n2 -- result       | Compare n1 < n2 (returns true, false otherwise)          | TODO: document, what true and false means                           |
+| 27 | [[file:opcodes_20_29.org::#opcode-div][/]]        | n1 n2 -- n1/n2        | Divide second item by top item on data stack             |                                                                     |
+| 28 | [[file:opcodes_20_29.org::#opcode-gt][>]]        | n1 n2 -- flag         | Signed compare n1 > n2; -1 = true, 0 = false             |                                                                     |
+| 29 | [[file:opcodes_20_29.org::#opcode-lt][<]]        | n1 n2 -- flag         | Signed compare n1 < n2; -1 = true, 0 = false             |                                                                     |
 | 30 | [[file:opcodes_30_39.org::#opcode-not][not]]      | n -- ~n               | Bitwise NOT on top of data stack                         |                                                                     |
 | 31 | [[file:opcodes_30_39.org::#opcode-i][i]]        | -- n                  | Push top of return stack to data stack                   |                                                                     |
 | 32 | [[file:opcodes_30_39.org::#opcode-cprt-read][cprt@]]    | port -- byte          | Read byte from hardware I/O port                         |                                                                     |