Help: Clarify behavior of path-based equality conditions

The docs for if(PATH_EQUAL) did not mention the component-wise
nature of the checks. It also claimed no normalization was
performed, but multiple separators are effectively collapsed
(part of normalization). Improve the wording to clarify both of
these points.

Also update the corresponding description of cmake_path(COMPARE),
which had the same inaccuracy.

Fixes: #23758

2 files changed, 15 insertions, 9 deletions

diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst
index 6fd3cf6..eb7da07 100644
--- a/Help/command/cmake_path.rst
+++ b/Help/command/cmake_path.rst
@@ -482,8 +482,9 @@ are :ref:`normalized <Normalization>` before the check.
   cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)
 
 Compares the lexical representations of two paths provided as string literals.
-No normalization is performed on either path.  Equality is determined
-according to the following pseudo-code logic:
+No normalization is performed on either path, except multiple consecutive
+directory separators are effectively collapsed into a single separator.
+Equality is determined according to the following pseudo-code logic:
 
 ::
 
diff --git a/Help/command/if.rst b/Help/command/if.rst
index c096725..301cdce 100644
--- a/Help/command/if.rst
+++ b/Help/command/if.rst
@@ -320,13 +320,18 @@ Path Comparisons
 .. _PATH_EQUAL:
 
 ``if(<variable|string> PATH_EQUAL <variable|string>)``
- .. versionadded:: 3.24
-  Compares the lexical representations of two paths provided as string
-  literals or variables. No normalization is performed on either path.
-
-  Lexical comparison has the advantage over string comparison to have a
-  knowledge of the structure of the path. So, the following comparison is
-  ``TRUE`` using ``PATH_EQUAL`` operator, but ``FALSE`` with ``STREQUAL``:
+  .. versionadded:: 3.24
+
+  Compares the two paths component-by-component.  Only if every component of
+  both paths match will the two paths compare equal.  Multiple path separators
+  are effectively collapsed into a single separator, but note that backslashes
+  are not converted to forward slashes.  No other
+  :ref:`path normalization <Normalization>` is performed.
+
+  Component-wise comparison is superior to string-based comparison due to the
+  handling of multiple path separators.  In the following example, the
+  expression evaluates to true using ``PATH_EQUAL``, but false with
+  ``STREQUAL``:
 
   .. code-block:: cmake