Merge topic 'doc-set-no-values'

512f64289a Help: Clarify that set(VAR) unsets VAR

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !8362

3 files changed, 21 insertions, 12 deletions

diff --git a/Help/command/UNSET_NOTE.txt b/Help/command/UNSET_NOTE.txt
new file mode 100644
index 0000000..8dc9125
--- /dev/null
+++ b/Help/command/UNSET_NOTE.txt
@@ -0,0 +1,9 @@
+.. note::
+
+  When evaluating :ref:`Variable References` of the form ``${VAR}``, CMake
+  first searches for a normal variable with that name.  If no such normal
+  variable exists, CMake will then search for a cache entry with that name.
+  Because of this, **unsetting a normal variable can expose a cache variable
+  that was previously hidden**.  To force a variable reference of the form
+  ``${VAR}`` to return an empty string, use ``set(<variable> "")``, which
+  clears the normal variable but leaves it defined.
diff --git a/Help/command/set.rst b/Help/command/set.rst
index ee677c9..aeb88b3 100644
--- a/Help/command/set.rst
+++ b/Help/command/set.rst
@@ -8,9 +8,8 @@ and cache entries.
 
 Signatures of this command that specify a ``<value>...`` placeholder
 expect zero or more arguments.  Multiple arguments will be joined as
-a :ref:`semicolon-separated list <CMake Language Lists>` to form the actual variable
-value to be set.  Zero arguments will cause normal variables to be
-unset.  See the :command:`unset` command to unset variables explicitly.
+a :ref:`semicolon-separated list <CMake Language Lists>` to form the
+actual variable value to be set.
 
 Set Normal Variable
 ^^^^^^^^^^^^^^^^^^^
@@ -19,7 +18,11 @@ Set Normal Variable
   set(<variable> <value>... [PARENT_SCOPE])
   :target: normal
 
-  Sets the given ``<variable>`` in the current function or directory scope.
+  Set or unset ``<variable>`` in the current function or directory scope:
+
+  * If at least one ``<value>...`` is given, set the variable to that value.
+  * If no value is given, unset the variable.  This is equivalent to
+    :command:`unset(<variable>) <unset>`.
 
   If the ``PARENT_SCOPE`` option is given the variable will be set in
   the scope above the current scope.  Each new directory or :command:`function`
@@ -34,6 +37,8 @@ Set Normal Variable
   can be used as an alternate method to the :command:`set(PARENT_SCOPE)`
   and :command:`unset(PARENT_SCOPE)` commands to update the parent scope.
 
+.. include:: UNSET_NOTE.txt
+
 Set Cache Entry
 ^^^^^^^^^^^^^^^
 
diff --git a/Help/command/unset.rst b/Help/command/unset.rst
index 1cd1398..522be89 100644
--- a/Help/command/unset.rst
+++ b/Help/command/unset.rst
@@ -12,19 +12,14 @@ Unset Normal Variable or Cache Entry
 
 Removes a normal variable from the current scope, causing it
 to become undefined.  If ``CACHE`` is present, then a cache variable
-is removed instead of a normal variable.  Note that when evaluating
-:ref:`Variable References` of the form ``${VAR}``, CMake first searches
-for a normal variable with that name.  If no such normal variable exists,
-CMake will then search for a cache entry with that name.  Because of this
-unsetting a normal variable can expose a cache variable that was previously
-hidden.  To force a variable reference of the form ``${VAR}`` to return an
-empty string, use ``set(<variable> "")``, which clears the normal variable
-but leaves it defined.
+is removed instead of a normal variable.
 
 If ``PARENT_SCOPE`` is present then the variable is removed from the scope
 above the current scope.  See the same option in the :command:`set` command
 for further details.
 
+.. include:: UNSET_NOTE.txt
+
 Unset Environment Variable
 ^^^^^^^^^^^^^^^^^^^^^^^^^^