Merge topic 'doc-if-IS_ABSOLUTE' into release-3.20

6234afdff4 Help: Document special cases for if(IS_ABSOLUTE)
789307b02f Help: Behavior of file(TO_NATIVE_PATH) depends on the host platform

Acked-by: Kitware Robot <[email protected]>
Merge-request: !6016

Help/command/file.rst

@@ -922,7 +922,8 @@ system search path like ``$ENV{PATH}``.  A search path will be converted
 to a cmake-style list separated by ``;`` characters.
 
 The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native
-path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere).
+path with platform-specific slashes (``\`` on Windows hosts and ``/``
+elsewhere).
 
 Always use double quotes around the ``<path>`` to be sure it is treated
 as a single argument to this command.

Help/command/if.rst

@@ -153,7 +153,16 @@ File Operations
  only for full paths.
 
 ``if(IS_ABSOLUTE path)``
- True if the given path is an absolute path.
+ True if the given path is an absolute path.  Note the following special
+ cases:
+
+ * An empty ``path`` evaluates to false.
+ * On Windows hosts, any ``path`` that begins with a drive letter and colon
+   (e.g. ``C:``), a forward slash or a backslash will evaluate to true.
+   This means a path like ``C:no\base\dir`` will evaluate to true, even
+   though the non-drive part of the path is relative.
+ * On non-Windows hosts, any ``path`` that begins with a tilde (``~``)
+   evaluates to true.
 
 Comparisons
 """""""""""