expanding macro examples, trying to adhere to style guidelines

diff --git a/doc/ca65.sgml b/doc/ca65.sgml
index 74e08198538738e763d9207879095fcc62d325c3..d0a3d80e7148dc6bcfc84fcbbc5bf6580fef1663 100644 (file)
--- a/doc/ca65.sgml
+++ b/doc/ca65.sgml
@@ -4286,7 +4286,8 @@ different:
        The common practice of wrapping C macros in parentheses may cause
        unintended problems here, such as accidentally implying an
        indirect addressing mode. While the definition of a macro requires
-       parentheses around its argument list, when invoked they should not be included.
+       parentheses around its argument list, when invoked they should not be
+       included.
 
 </itemize>
 
@@ -4320,18 +4321,44 @@ Macros with parameters may also be useful:
         DEBUG   "Assembling include file #3"
 </verb></tscreen>
 
-Note that, while formal parameters have to be placed in braces,
-the actual parameters used when invoking the macro should not use braces.
-The invoked parameters are separated by commas only, if parentheses are
-used by accident they will become part of the replaced token:
+Note that, while formal parameters have to be placed in parentheses,
+the actual argument used when invoking the macro should not be.
+The invoked arguments are separated by commas only, if parentheses are
+used by accident they will become part of the replaced token.
+
+If you wish to have an expression follow the macro invocation, the
+last parameter can be enclosed in curly braces {} to indicate the end of that
+argument.
+
+Examples:
 
 <tscreen><verb>
 .define COMBINE(ta,tb,tc) ta+tb*10+tc*100
 
-        COMBINE 5,6,7     ; 5+6*10+7*100 = 765 correct
-        COMBINE(5,6,7)    ; (5+6*10+7)*100 = 7200 incorrect!
+.word COMBINE 5,6,7      ; 5+6*10+7*100 = 765
+.word COMBINE(5,6,7)     ; (5+6*10+7)*100 = 7200 ; incorrect use of parentheses
+.word COMBINE 5,6,7+1    ; 5+6*10+7+1*100 = 172
+.word COMBINE 5,6,{7}+1  ; 5+6*10+7*100+1 = 766 ; {} encloses the argument
+.word COMBINE 5,6-2,7    ; 5+6-2*10+7*100 = 691
+.word COMBINE 5,(6-2),7  ; 5+(6-2)*10+7*100 = 745
+.word COMBINE 5,6,7+COMBINE 0,1,2    ; 5+6*10+7+0+1*10+2*100*100 = 20082
+.word COMBINE 5,6,{7}+COMBINE 0,1,2  ; 5+6*10+7*100+0+1*10+2*100 = 975
+</verb></tscreen>
+
+With C macros it is common to enclose the results in parentheses to
+prevent unintended interactions with the text of the arguments, but
+additional care must be taken in this assembly context where parentheses
+may alter the meaning of a statement. In particular, indirect addressing modes
+may be accidentally implied:
+
+<tscreen><verb>
+.define DUO(ta,tb) (ta+(tb*10))
+
+        lda DUO(5,4), Y         ; LDA (indirect), Y
+        lda 0+DUO(5,4), Y       ; LDA absolute indexed, Y
 </verb></tscreen>
 
+
 <sect1>Characters in macros<p>
 
 When using the <ref id="option-t" name="-t"> option, characters are translated