From 6c490ba16c067740d89cafe6d57e5f3e2d12745b Mon Sep 17 00:00:00 2001
From: uz <uz@b7a2c559-68d2-44c3-8de9-860c34a00d81>
Date: Fri, 13 Jan 2012 15:58:17 +0000
Subject: [PATCH] Add some warnings about using .DEFINE.

git-svn-id: svn://svn.cc65.org/cc65/trunk@5397 b7a2c559-68d2-44c3-8de9-860c34a00d81
---
 doc/ca65.sgml | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/doc/ca65.sgml b/doc/ca65.sgml
index 8dc71c4df..6db459ee1 100644
--- a/doc/ca65.sgml
+++ b/doc/ca65.sgml
@@ -823,13 +823,19 @@ convenient in some situations, so it's your decision.
 
 <sect1>Using macros to define labels and constants<p>
 
-While there are drawbacks with this approach, it may be handy in some
-situations. Using <tt><ref id=".DEFINE" name=".DEFINE"></tt>, it is
-possible to define symbols or constants that may be used elsewhere. Since
-the macro facility works on a very low level, there is no scoping. On the
-other side, you may also define string constants this way (this is not
+While there are drawbacks with this approach, it may be handy in a few rare
+situations. Using <tt><ref id=".DEFINE" name=".DEFINE"></tt>, it is possible
+to define symbols or constants that may be used elsewhere. One of the
+advantages is that you can use it to define string constants (this is not
 possible with the other symbol types).
 
+Please note: <tt/.DEFINE/ style macros do token replacements on a low level,
+so the names do not adhere to scoping, diagnostics may be misleading, there
+are no symbols to look up in the map file, and there is no debug info.
+Especially the first problem in the list can lead to very nasty programming
+errors. Because of these problems, the general advice is, <bf/NOT/ do use
+<tt/.DEFINE/ if you don't have to.
+
 Example:
 
 <tscreen><verb>
@@ -2247,6 +2253,11 @@ Here's a list of all control commands and a description, what they do:
   Start a define style macro definition. The command is followed by an
   identifier (the macro name) and optionally by a list of formal arguments
   in braces.
+
+  Please note that <tt/.DEFINE/ shares most disadvantages with its C
+  counterpart, so the general advice is, <bf/NOT/ do use <tt/.DEFINE/ if you
+  don't have to.
+
   See also the <tt><ref id=".UNDEFINE" name=".UNDEFINE"></tt> command and
   section <ref id="macros" name="Macros">.
 
-- 
2.39.5