Merge topic 'doc-configure_file-cmakedefine01'

c13f75982f Help: Clarify configure_file #cmakedefine01 syntax and behavior

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Michael Hirsch <michael@scivision.dev>
Merge-request: !5909

1 files changed, 24 insertions, 2 deletions

diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst
index 63ea84d..8f082e8 100644
--- a/Help/command/configure_file.rst
+++ b/Help/command/configure_file.rst
@@ -36,8 +36,30 @@ or
 depending on whether ``VAR`` is set in CMake to any value not considered
 a false constant by the :command:`if` command.  The "..." content on the
 line after the variable name, if any, is processed as above.
-Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with
-either ``#define VAR 1`` or ``#define VAR 0`` similarly.
+
+Unlike lines of the form ``#cmakedefine VAR ...``, in lines of the form
+``#cmakedefine01 VAR``, ``VAR`` itself will expand to ``VAR 0`` or ``VAR 1``
+rather than being assigned the value ``...``. Therefore, input lines of the form
+
+.. code-block:: c
+
+  #cmakedefine01 VAR
+
+will be replaced with either
+
+.. code-block:: c
+
+  #define VAR 0
+
+or
+
+.. code-block:: c
+
+  #define VAR 1
+
+Input lines of the form ``#cmakedefine01 VAR ...`` will expand
+as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 0``,
+which may lead to undefined behavior.
 
 .. versionadded:: 3.10
   The result lines (with the exception of the ``#undef`` comments) can be