Merge topic 'doc-if-basic-expressions' into release-3.22

294581a443 Help: Be more explicit about the behavior of if(<string>)
3a9695557d Help: Explicitly state that if(ENV{some_var}) is always false

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

1 files changed, 15 insertions, 4 deletions

diff --git a/Help/command/if.rst b/Help/command/if.rst
index 6ff8852..5dba13e 100644
--- a/Help/command/if.rst
+++ b/Help/command/if.rst
@@ -56,12 +56,23 @@ Basic Expressions
  ``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string,
  or ends in the suffix ``-NOTFOUND``.  Named boolean constants are
  case-insensitive.  If the argument is not one of these specific
- constants, it is treated as a variable or string and the following
- signature is used.
+ constants, it is treated as a variable or string (see `Variable Expansion`_
+ further below) and one of the following two forms applies.
 
-``if(<variable|string>)``
+``if(<variable>)``
  True if given a variable that is defined to a value that is not a false
- constant.  False otherwise.  (Note macro arguments are not variables.)
+ constant.  False otherwise, including if the variable is undefined.
+ Note that macro arguments are not variables.
+ Environment variables also cannot be tested this way, e.g.
+ ``if(ENV{some_var})`` will always evaluate to false.
+
+``if(<string>)``
+ A quoted string always evaluates to false unless:
+
+ * The string's value is one of the true constants, or
+ * Policy :policy:`CMP0054` is not set to ``NEW`` and the string's value
+   happens to be a variable name that is affected by :policy:`CMP0054`'s
+   behavior.
 
 Logic Operators
 """""""""""""""