1 files changed, 45 insertions, 11 deletions
diff --git a/Help/command/macro.rst b/Help/command/macro.rst
index aa16352..258dc50 100644
--- a/Help/command/macro.rst
+++ b/Help/command/macro.rst
@@ -15,19 +15,53 @@ Define a macro named <name> that takes arguments named arg1 arg2 arg3
 (...).  Commands listed after macro, but before the matching endmacro,
 are not invoked until the macro is invoked.  When it is invoked, the
 commands recorded in the macro are first modified by replacing formal
-parameters (${arg1}) with the arguments passed, and then invoked as
+parameters (``${arg1}``) with the arguments passed, and then invoked as
 normal commands.  In addition to referencing the formal parameters you
-can reference the values ${ARGC} which will be set to the number of
-arguments passed into the function as well as ${ARGV0} ${ARGV1}
-${ARGV2} ...  which will have the actual values of the arguments
+can reference the values ``${ARGC}`` which will be set to the number of
+arguments passed into the function as well as ``${ARGV0}`` ``${ARGV1}``
+``${ARGV2}`` ...  which will have the actual values of the arguments
 passed in.  This facilitates creating macros with optional arguments.
-Additionally ${ARGV} holds the list of all arguments given to the
-macro and ${ARGN} holds the list of arguments past the last expected
-argument.  Note that the parameters to a macro and values such as ARGN
-are not variables in the usual CMake sense.  They are string
-replacements much like the C preprocessor would do with a macro.  If
-you want true CMake variables and/or better CMake scope control you
-should look at the function command.
+Additionally ``${ARGV}`` holds the list of all arguments given to the
+macro and ``${ARGN}`` holds the list of arguments past the last expected
+argument.
 
 See the cmake_policy() command documentation for the behavior of
 policies inside macros.
+
+Macro Argument Caveats
+^^^^^^^^^^^^^^^^^^^^^^
+
+Note that the parameters to a macro and values such as ``ARGN`` are
+not variables in the usual CMake sense.  They are string
+replacements much like the C preprocessor would do with a macro.
+Therefore you will NOT be able to use commands like::
+
+ if(ARGV1) # ARGV1 is not a variable
+ foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
+
+In the first case you can use ``if(${ARGV1})``, in the second case, you can
+use ``foreach(loop_var ${ARGN})`` but this will skip empty arguments.
+If you need to include them, you can use::
+
+ set(list_var "${ARGN}")
+ foreach(loop_var IN LISTS list_var)
+
+Note that if you have a variable with the same name in the scope from
+which the macro is called, using unreferenced names will use the
+existing variable instead of the arguments. For example::
+
+ macro(_BAR)
+   foreach(arg IN LISTS ARGN)
+     [...]
+   endforeach()
+ endmacro()
+
+ function(_FOO)
+   _bar(x y z)
+ endfunction()
+
+ _foo(a b c)
+
+Will loop over ``a;b;c`` and not over ``x;y;z`` as one might be expecting.
+If you want true CMake variables and/or better CMake scope control you
+should look at the function command.