Improved commands reference

commands.md

@@ -1,5 +1,47 @@
 # Compiler Commands Reference
 
+## Index
+
+- [ADD](#add) - Adds two values
+- [AND](#and) - Bitwise AND operation
+- [BREAK](#break) - Exits current loop
+- [BYTE](#byte) - Declares 8-bit variable or constant
+- [CALL](#call) - Calls function with parameters
+- [CASE](#case) - Case branch in SWITCH statement
+- [DEC](#dec) - Decrements variable or memory location
+- [DEFAULT](#default) - Default branch in SWITCH statement
+- [ELSE](#else) - Alternative branch in IF statement
+- [ENDIF](#endif) - Terminates IF block
+- [ENDSWITCH](#endswitch) - Terminates SWITCH block
+- [FEND](#fend) - Ends function definition
+- [FOR](#for) - Loop with automatic counter increment
+- [FUNC](#func) - Defines function with parameters
+- [GOSUB](#gosub) - Calls subroutine with register passing
+- [GOTO](#goto) - Unconditional jump to label
+- [IF](#if) - Conditional execution
+- [INC](#inc) - Increments variable or memory location
+- [LABEL](#label) - Creates named assembly label
+- [LET](#let) - Assigns value to variable
+- [NEXT](#next) - Terminates FOR loop
+- [OR](#or) - Bitwise OR operation
+- [ORIGIN](#origin) - Sets assembly origin address
+- [PEEK](#peek) - Reads byte from memory
+- [PEEKW](#peekw) - Reads word from memory
+- [POINTER](#pointer) - Sets pointer to address
+- [POKE](#poke) - Writes byte to memory
+- [POKEW](#pokew) - Writes word to memory
+- [SUBEND](#subend) - Returns from subroutine
+- [SHIFTL](#shiftl) - Logical shift left
+- [SHIFTR](#shiftr) - Logical shift right
+- [SUBTR](#subtr) - Subtracts values
+- [SWITCH](#switch) - Multi-way branching
+- [WEND](#wend) - Terminates WHILE loop
+- [WHILE](#while) - Loop while condition true
+- [WORD](#word) - Declares 16-bit variable or constant
+- [XOR](#xor) - Bitwise XOR operation
+
+---
+
 ## ADD
 
 Adds two values and stores result in destination.
@@ -46,13 +88,18 @@ BREAK
 ```
 
 **Examples:**
+
 ```
+// BREAK in FOR loop
 FOR i = 0 TO 100
     IF i = 50
         BREAK
     ENDIF
 NEXT
+```
 
+```
+// BREAK in WHILE loop
 WHILE counter < 1000
     counter++
     IF error
@@ -117,10 +164,7 @@ process("hello",42,myvar)
 
 Defines a case branch within SWITCH statement.
 
-**Syntax:**
+See [SWITCH](#switch) for syntax and examples.
-```
-See SWITCH
-```
 
 ---
 
@@ -136,11 +180,21 @@ DECREMENT <target>
 ```
 
 **Examples:**
+
 ```
+// Modern: decrement variables
 counter--
 lives--
 index--
+```
+
+```
+// Alternative: decrement memory location
 DEC $D020
+```
+
+```
+// Legacy: DECREMENT form
 DECREMENT screenColor
 ```
 
@@ -150,10 +204,7 @@ DECREMENT screenColor
 
 Defines the default branch in SWITCH statement.
 
-**Syntax:**
+See [SWITCH](#switch) for syntax and examples.
-```
-See SWITCH
-```
 
 ---
 
@@ -161,10 +212,7 @@ See SWITCH
 
 Alternative branch in IF statement.
 
-**Syntax:**
+See [IF](#if) for syntax and examples.
-```
-See IF
-```
 
 ---
 
@@ -172,10 +220,7 @@ See IF
 
 Terminates IF block.
 
-**Syntax:**
+See [IF](#if) for syntax and examples.
-```
-See IF
-```
 
 ---
 
@@ -183,10 +228,7 @@ See IF
 
 Terminates SWITCH block.
 
-**Syntax:**
+See [SWITCH](#switch) for syntax and examples.
-```
-See SWITCH
-```
 
 ---
 
@@ -194,10 +236,7 @@ See SWITCH
 
 Ends a function definition.
 
-**Syntax:**
+See [FUNC](#func) for syntax and examples.
-```
-See FUNC
-```
 
 ---
 
@@ -211,11 +250,16 @@ FOR <iterator> = <start_value> TO <end_value>
 ```
 
 **Examples:**
+
 ```
+// FOR loop with literal values
 FOR i = 0 TO 10
     screen = i
 NEXT
+```
 
+```
+// FOR loop with variables
 FOR counter = start TO finish
     process(counter)
 NEXT
@@ -247,28 +291,37 @@ FUNC name ( in:x out:y io:z )          # direction with pre-declared (legacy)
 ```
 
 **Examples:**
+
 ```
 // Modern: self-contained function with local parameters
 FUNC add({BYTE a} {BYTE b} out:{BYTE result})
     result = a + b
 FEND
+```
 
+```
 // Modern: with direction modifiers  
 FUNC process(in:{BYTE input} out:{BYTE output})
     output = input + 1
 FEND
+```
 
+```
 // Modern: io parameter (read-write)
 FUNC increment(io:{BYTE counter})
     counter = counter + 1
 FEND
+```
 
+```
 // Modern: absolute address parameter
 FUNC read_byte({BYTE data @ $fa})
     BYTE temp
     temp = data  // Reads from $fa
 FEND
+```
 
+```
 // Legacy: uses global variables directly
 BYTE x
 BYTE y
@@ -336,17 +389,25 @@ IF <param1> [<operator> <param2>]
 Operators: `=` `==` `<>` `!=` `>` `<` `>=` `<=`
 
 **Examples:**
+
 ```
+// Simple IF statement
 IF count == 10
     result = 1
 ENDIF
+```
 
+```
+// IF with ELSE branch
 IF value > threshold
     process(value)
 ELSE
     skip(value)
 ENDIF
+```
 
+```
+// IF-ELSE with actions
 IF x < 100
     x++
 ELSE
@@ -368,11 +429,21 @@ INCREMENT <target>
 ```
 
 **Examples:**
+
 ```
+// Modern: increment variables
 counter++
 index++
 frameCount++
+```
+
+```
+// Alternative: increment memory location
 INC $D020
+```
+
+```
+// Legacy: INCREMENT form
 INCREMENT screenColor
 ```
 
@@ -421,10 +492,7 @@ value = 100+50
 
 Loop terminator for FOR.
 
-**Syntax:**
+See [FOR](#for) for syntax and examples.
-```
-See FOR
-```
 
 ---
 
@@ -499,19 +567,27 @@ For operating with offsets the address parameter must be an absolute WORD variab
 ```
 
 **Examples:**
+
 ```
+// Read from absolute address
 reset_addr = PEEKW $FFFE
+```
 
+```
+// Read with offset (requires WORD variable in zero page)
 WORD buffer @ $fd
-offset_val = PEEKW buff_ptr[10]
+offset_val = PEEKW buffer[10]
+```
 
+```
+// Read through pointer
 WORD pointer
 val = PEEKW pointer
 ```
 
 ---
 
-## POINT
+## POINTER
 
 Sets pointer variable to address of target.
 
@@ -586,11 +662,16 @@ EXIT
 ```
 
 **Examples:**
+
 ```
+// Simple subroutine with SUBEND
 LABEL subroutine
     counter = counter + 1
     SUBEND
+```
 
+```
+// Subroutine with early EXIT
 LABEL checkValue
     IF value = 0
         EXIT
@@ -625,10 +706,20 @@ SHIFTL <source> << <amount> -> <dest>
 - WORD→BYTE conversion truncates low byte only
 
 **Examples:**
+
 ```
+// Modern: assignment form
 result = value << 3
+```
+
+```
+// Alternative: arrow form
+SHIFTL flags << 2 -> masked
+```
+
+```
+// Legacy: verbose form
 SHIFTL mask BY bits GIVING shifted
-SHIFTR flags >> 2 -> masked
 ```
 
 ---
@@ -657,12 +748,22 @@ SHIFTR <source> >> <amount> -> <dest>
 - WORD→BYTE conversion truncates low byte only
 
 **Examples:**
+
 ```
+// Modern: assignment form
 mask = flags >> 2
-SHIFTR value BY shift GIVING result
+```
+
+```
+// Alternative: arrow form
 SHIFTR data >> 4 -> nibble
 ```
 
+```
+// Legacy: verbose form
+SHIFTR value BY shift GIVING result
+```
+
 ---
 
 ## SUBTR
@@ -712,6 +813,7 @@ ENDSWITCH
 - Nested SWITCH statements are supported
 
 **Examples:**
+
 ```
 // Basic switch with default
 SWITCH status
@@ -722,7 +824,9 @@ SWITCH status
   DEFAULT
     result = 0
 ENDSWITCH
+```
 
+```
 // Switch with constants
 BYTE CONST MAX = 100
 SWITCH value
@@ -731,7 +835,9 @@ SWITCH value
   CASE 50
     halfway = 1
 ENDSWITCH
+```
 
+```
 // WORD switch
 WORD big_val
 SWITCH big_val
@@ -742,7 +848,9 @@ SWITCH big_val
   DEFAULT
     mode = 0
 ENDSWITCH
+```
 
+```
 // Nested switch
 SWITCH outer
   CASE 1
@@ -757,7 +865,9 @@ SWITCH outer
   DEFAULT
     result = 0
 ENDSWITCH
+```
 
+```
 // Using variables in CASE
 BYTE threshold1
 BYTE threshold2
@@ -779,10 +889,7 @@ ENDSWITCH
 
 Terminates WHILE loop.
 
-**Syntax:**
+See [WHILE](#while) for syntax and examples.
-```
-See WHILE
-```
 
 ---
 
@@ -800,17 +907,25 @@ WHILE <param1> [<operator> <param2>]
 Operators: `=` `==` `<>` `!=` `>` `<` `>=` `<=`
 
 **Examples:**
+
 ```
+// WHILE with numeric comparison
 WHILE counter < 100
     counter++
     result = result + counter
 WEND
+```
 
+```
+// WHILE with boolean condition
 WHILE running
     processFrame
     checkInput
 WEND
+```
 
+```
+// WHILE with inequality
 WHILE x != y
     x++
 WEND