From 062c909017a5018e23925ae50348680c388c6beb Mon Sep 17 00:00:00 2001
From: Mattias Hansson <mattias@techserio.com>
Date: Fri, 21 Nov 2025 17:04:11 +0100
Subject: [PATCH] Updated #DEFINE doc to reflect current behavior.

---
 syntax.md | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/syntax.md b/syntax.md
index 842b95e..90c4015 100644
--- a/syntax.md
+++ b/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
 
 ---