Updated #DEFINE doc to reflect current behavior.

syntax.md

@@ -37,11 +37,27 @@ Defines a text substitution macro.
 ```
 
 **Examples:**
+
 ```
 #DEFINE MAX_SPEED = 10
-#DEFINE SCREEN = $0400
+#DEFINE HELLO = GOODBYE // Will replace the text HELLO in all source with GOODBYE (except ASM and SCRIPT blocks)
+#DEFINE HELLO2 = GOOOOOODBYE // Longest match wins. If HELLO2 is encountered this will be the match not the HELLO define above 
+#DEFINE SCREEN = $$0400 // Notice $$, see below.
 #DEFINE OFFSET = 255
-#DEFINE BASE+DELTA = $D000+32
+```
+
+Note: Replacements are not recursive. Once a match is found, it's replaced, and processing starts after the replacement.
+
+**Special Characters in Values:**
+
+Define values support `$` escape sequences for special characters:
+- `$XX` (two hex digits) = character with code XX
+- `$$` = literal `$` character
+```
+#DEFINE SPACE = $20          // space character
+#DEFINE NEWLINE = $0D        // carriage return
+#DEFINE TAB = $09            // tab character
+#DEFINE HEXADDR = $$D020     // stores "$D020" as text
 ```
 
 **Notes:**
@@ -49,6 +65,8 @@ Defines a text substitution macro.
 - Value can contain previously defined macros
 - Macros are expanded in source lines
 - Case sensitive
+- `$` escapes are processed when the define is created, not when used
+- For most purposes, use `WORD CONST` instead of preprocessor defines to define constant named values
 
 ---