4 files changed, 57 insertions, 27 deletions
diff --git a/Help/command/function.rst b/Help/command/function.rst
index 7b10381..53ba754 100644
--- a/Help/command/function.rst
+++ b/Help/command/function.rst
@@ -23,6 +23,9 @@ details.
 See the :command:`cmake_policy()` command documentation for the behavior
 of policies inside functions.
 
+See the :command:`macro()` command documentation for differences
+between CMake functions and macros.
+
 Invocation
 ^^^^^^^^^^
 
diff --git a/Help/command/macro.rst b/Help/command/macro.rst
index e15e206..42a99fc 100644
--- a/Help/command/macro.rst
+++ b/Help/command/macro.rst
@@ -21,6 +21,9 @@ argument of the opening ``macro`` command.
 See the :command:`cmake_policy()` command documentation for the behavior
 of policies inside macros.
 
+See the :ref:`Macro vs Function` section below for differences
+between CMake macros and :command:`functions <function>`.
+
 Invocation
 ^^^^^^^^^^
 
@@ -65,13 +68,36 @@ behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only
 way to ensure that ``${ARGV#}`` was passed to the function as an extra
 argument.
 
+.. _`Macro vs Function`:
+
+Macro vs Function
+^^^^^^^^^^^^^^^^^
+
+The ``macro`` command is very similar to the :command:`function` command.
+Nonetheless, there are a few important differences.
+
+In a function, ``ARGC``, ``ARGC`` and ``ARGV0``, ``ARGV1``, ... are
+true variables in the usual CMake sense.  In a macro, they are not.
+They are string replacements much like the C preprocessor would do
+with a macro.  This has a number of consequences, as explained in
+the :ref:`Argument Caveats` section below.
+
+Another difference between macros and functions is the control flow.
+A function is executed by transfering control from the calling
+statement to the function body.  A macro is executed as if the macro
+body were pasted in place of the calling statement.  This has for
+consequence that a :command:`return()` in a macro body does not
+just terminate execution of the macro; rather, control is returned
+from the scope of the macro call.  To avoid confusion, it is recommended
+to avoid :command:`return()` in macros altogether.
+
+.. _`Argument Caveats`:
+
 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
+Since ``ARGC``, ``ARGC``, ``ARGV0`` etc are not variables,
+you will NOT be able to use commands like
 
 .. code-block:: cmake
 
@@ -80,12 +106,11 @@ Therefore you will NOT be able to use commands like
  if(ARGC GREATER 2) # ARGC 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 and third case, the proper way to check if an optional
-variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``.
-In the last case, you can use ``foreach(loop_var ${ARGN})`` but this
-will skip empty arguments.
-If you need to include them, you can use
+In the first case, you can use ``if(${ARGV1})``.  In the second and
+third case, the proper way to check if an optional variable was
+passed to the macro is to use ``if(${ARGC} GREATER 2)``.  In the
+last case, you can use ``foreach(loop_var ${ARGN})`` but this will
+skip empty arguments.  If you need to include them, you can use
 
 .. code-block:: cmake
 
@@ -98,18 +123,18 @@ existing variable instead of the arguments. For example:
 
 .. code-block:: cmake
 
- macro(_BAR)
+ macro(bar)
    foreach(arg IN LISTS ARGN)
      <commands>
    endforeach()
  endmacro()
 
- function(_FOO)
-   _bar(x y z)
+ function(foo)
+   bar(x y z)
  endfunction()
 
- _foo(a b c)
+ foo(a b c)
 
-Will loop over ``a;b;c`` and not over ``x;y;z`` as one might be expecting.
+Will loop over ``a;b;c`` and not over ``x;y;z`` as one might have expected.
 If you want true CMake variables and/or better CMake scope control you
 should look at the function command.
diff --git a/Help/prop_tgt/WIN32_EXECUTABLE.rst b/Help/prop_tgt/WIN32_EXECUTABLE.rst
index 336d5f7..060d166 100644
--- a/Help/prop_tgt/WIN32_EXECUTABLE.rst
+++ b/Help/prop_tgt/WIN32_EXECUTABLE.rst
@@ -5,8 +5,9 @@ Build an executable with a WinMain entry point on windows.
 
 When this property is set to true the executable when linked on
 Windows will be created with a WinMain() entry point instead of just
-main().  This makes it a GUI executable instead of a console
-application.  See the CMAKE_MFC_FLAG variable documentation to
-configure use of MFC for WinMain executables.  This property is
-initialized by the value of the variable CMAKE_WIN32_EXECUTABLE if it
-is set when a target is created.
+main().  This makes it a GUI executable instead of a console application.
+See the :variable:`CMAKE_MFC_FLAG` variable documentation to
+configure use of the Microsoft Foundation Classes (MFC) for WinMain
+executables.  This property is initialized by the value of the
+:variable:`CMAKE_WIN32_EXECUTABLE` variable if it is set when
+a target is created.
diff --git a/Help/variable/CMAKE_MFC_FLAG.rst b/Help/variable/CMAKE_MFC_FLAG.rst
index 5a392bf..2c4d1c5 100644
--- a/Help/variable/CMAKE_MFC_FLAG.rst
+++ b/Help/variable/CMAKE_MFC_FLAG.rst
@@ -1,15 +1,16 @@
 CMAKE_MFC_FLAG
 --------------
 
-Tell cmake to use MFC for an executable or dll.
+Use the MFC library for an executable or dll.
 
-This can be set in a ``CMakeLists.txt`` file and will enable MFC in the
-application.  It should be set to ``1`` for the static MFC library, and ``2``
-for the shared MFC library.  This is used in Visual Studio
-project files.  The CMakeSetup dialog used MFC and the ``CMakeLists.txt``
-looks like this:
+Enables the use of the Microsoft Foundation Classes (MFC).
+It should be set to ``1`` for the static MFC library, and
+``2`` for the shared MFC library.  This is used in Visual Studio
+project files.
 
-::
+Usage example:
+
+.. code-block:: cmake
 
   add_definitions(-D_AFXDLL)
   set(CMAKE_MFC_FLAG 2)