Help: Clarify behavior of search ignore-related variables

Not all the behaviors of CMake variables for ignoring search
locations by find_...() commands were fully documented.
Add the missing effects, clarify the wording and restructure the
way the details are assembled to reduce duplication.

Also improve the cross-referencing to ensure all the related
variables are more discoverable.

Issue: #20878

11 files changed, 98 insertions, 51 deletions

diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt
index 5b63e1c..ee6c1cc 100644
--- a/Help/command/FIND_XXX.txt
+++ b/Help/command/FIND_XXX.txt
@@ -170,6 +170,11 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    or in the short-hand version of the command.
    These are typically hard-coded guesses.
 
+The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`,
+:variable:`CMAKE_SYSTEM_IGNORE_PATH` and
+:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some
+of the above locations to be ignored.
+
 .. versionadded:: 3.16
   Added ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable
   various search locations.
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index 1a79a8a..5acefad 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -363,6 +363,11 @@ enabled.
 9. Search paths specified by the ``PATHS`` option.  These are typically
    hard-coded guesses.
 
+The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`,
+:variable:`CMAKE_SYSTEM_IGNORE_PATH` and
+:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some
+of the above locations to be ignored.
+
 .. versionadded:: 3.16
    Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable
    various search locations.
diff --git a/Help/variable/CMAKE_IGNORE_PATH.rst b/Help/variable/CMAKE_IGNORE_PATH.rst
index 4bca34b..4b2bd8a 100644
--- a/Help/variable/CMAKE_IGNORE_PATH.rst
+++ b/Help/variable/CMAKE_IGNORE_PATH.rst
@@ -1,18 +1,18 @@
 CMAKE_IGNORE_PATH
 -----------------
 
-:ref:`Semicolon-separated list <CMake Language Lists>` of directories to be *ignored* by
-the :command:`find_program`, :command:`find_library`, :command:`find_file`,
-and :command:`find_path` commands.  This is useful in cross-compiling
-environments where some system directories contain incompatible but
-possibly linkable libraries.  For example, on cross-compiled cluster
-environments, this allows a user to ignore directories containing
-libraries meant for the front-end machine.
+.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_IGNORE_PATH``
+.. |CMAKE_IGNORE_PREFIX_VAR| replace:: :variable:`CMAKE_IGNORE_PREFIX_PATH`
 
-By default this is empty; it is intended to be set by the project.
-Note that ``CMAKE_IGNORE_PATH`` takes a list of directory names, *not*
-a list of prefixes.  To ignore paths under prefixes (``bin``, ``include``,
-``lib``, etc.), specify them explicitly.
+.. include:: IGNORE_SEARCH_PATH.txt
+.. include:: IGNORE_SEARCH_LOCATIONS.txt
+.. include:: IGNORE_SEARCH_NONSYSTEM.txt
 
-See also the :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_LIBRARY_PATH`,
-:variable:`CMAKE_INCLUDE_PATH`, and :variable:`CMAKE_PROGRAM_PATH` variables.
+See also the following variables:
+
+- :variable:`CMAKE_IGNORE_PREFIX_PATH`
+- :variable:`CMAKE_SYSTEM_IGNORE_PATH`
+- :variable:`CMAKE_PREFIX_PATH`
+- :variable:`CMAKE_LIBRARY_PATH`
+- :variable:`CMAKE_INCLUDE_PATH`
+- :variable:`CMAKE_PROGRAM_PATH`
diff --git a/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst b/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst
index 317c771..b81cc57 100644
--- a/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst
+++ b/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst
@@ -3,17 +3,18 @@ CMAKE_IGNORE_PREFIX_PATH
 
 .. versionadded:: 3.23
 
-:ref:`Semicolon-separated list <CMake Language Lists>` of prefixes to be
-*ignored* by the :command:`find_program`, :command:`find_library`,
-:command:`find_file`, :command:`find_path`, and :command:`find_package`
-commands.  This is useful in cross-compiling environments where some
-system directories contain incompatible but possibly linkable libraries.
-For example, on cross-compiled cluster environments, this allows a user
-to ignore directories containing libraries meant for the front-end machine.
+.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_IGNORE_PREFIX_PATH``
+.. |CMAKE_IGNORE_NONPREFIX_VAR| replace:: :variable:`CMAKE_IGNORE_PATH`
 
-By default this is empty; it is intended to be set by the project and/or
-the end user.  Note that ``CMAKE_IGNORE_PREFIX_PATH`` takes a list of
-prefixes, *not* a list of directory names.
+.. include:: IGNORE_SEARCH_PREFIX.txt
+.. include:: IGNORE_SEARCH_LOCATIONS.txt
+.. include:: IGNORE_SEARCH_NONSYSTEM.txt
 
-See also the :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_LIBRARY_PATH`,
-:variable:`CMAKE_INCLUDE_PATH`, and :variable:`CMAKE_PROGRAM_PATH` variables.
+See also the following variables:
+
+- :variable:`CMAKE_IGNORE_PATH`
+- :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH`
+- :variable:`CMAKE_PREFIX_PATH`
+- :variable:`CMAKE_LIBRARY_PATH`
+- :variable:`CMAKE_INCLUDE_PATH`
+- :variable:`CMAKE_PROGRAM_PATH`
diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst
index 6afbd33..a6d8016 100644
--- a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst
+++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst
@@ -1,18 +1,18 @@
 CMAKE_SYSTEM_IGNORE_PATH
 ------------------------
 
-:ref:`Semicolon-separated list <CMake Language Lists>` of directories to be *ignored* by
-the :command:`find_program`, :command:`find_library`, :command:`find_file`,
-and :command:`find_path` commands.  This is useful in cross-compiling
-environments where some system directories contain incompatible but
-possibly linkable libraries.  For example, on cross-compiled cluster
-environments, this allows a user to ignore directories containing
-libraries meant for the front-end machine.
+.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_SYSTEM_IGNORE_PATH``
+.. |CMAKE_IGNORE_PREFIX_VAR| replace:: :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH`
+.. |CMAKE_IGNORE_NONSYSTEM_VAR| replace:: :variable:`CMAKE_IGNORE_PATH`
 
-By default this contains a list of directories containing incompatible
-binaries for the host system.  See the :variable:`CMAKE_IGNORE_PATH` variable
-that is intended to be set by the project.
+.. include:: IGNORE_SEARCH_PATH.txt
+.. include:: IGNORE_SEARCH_LOCATIONS.txt
+.. include:: IGNORE_SEARCH_SYSTEM.txt
 
-See also the :variable:`CMAKE_SYSTEM_PREFIX_PATH`,
-:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_INCLUDE_PATH`,
-and :variable:`CMAKE_SYSTEM_PROGRAM_PATH` variables.
+See also the following variables:
+
+- :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH`
+- :variable:`CMAKE_SYSTEM_PREFIX_PATH`
+- :variable:`CMAKE_SYSTEM_LIBRARY_PATH`
+- :variable:`CMAKE_SYSTEM_INCLUDE_PATH`
+- :variable:`CMAKE_SYSTEM_PROGRAM_PATH`
diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst
index ce52f5a..48a2994 100644
--- a/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst
+++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst
@@ -3,18 +3,18 @@ CMAKE_SYSTEM_IGNORE_PREFIX_PATH
 
 .. versionadded:: 3.23
 
-:ref:`Semicolon-separated list <CMake Language Lists>` of prefixes to be
-*ignored* by the :command:`find_program`, :command:`find_library`,
-:command:`find_file`, :command:`find_path`, and :command:`find_package`
-commands.  This is useful in cross-compiling environments where some
-system directories contain incompatible but possibly linkable libraries.
-For example, on cross-compiled cluster environments, this allows a user
-to ignore directories containing libraries meant for the front-end machine.
+.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_SYSTEM_IGNORE_PREFIX_PATH``
+.. |CMAKE_IGNORE_NONPREFIX_VAR| replace:: :variable:`CMAKE_SYSTEM_IGNORE_PATH`
+.. |CMAKE_IGNORE_NONSYSTEM_VAR| replace:: :variable:`CMAKE_IGNORE_PREFIX_PATH`
 
-By default this contains a list of directories containing incompatible
-binaries for the host system.  See the :variable:`CMAKE_IGNORE_PREFIX_PATH`
-variable that is intended to be set by the project and/or the end user.
+.. include:: IGNORE_SEARCH_PREFIX.txt
+.. include:: IGNORE_SEARCH_LOCATIONS.txt
+.. include:: IGNORE_SEARCH_SYSTEM.txt
 
-See also the :variable:`CMAKE_SYSTEM_PREFIX_PATH`,
-:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_INCLUDE_PATH`,
-and :variable:`CMAKE_SYSTEM_PROGRAM_PATH` variables.
+See also the following variables:
+
+- :variable:`CMAKE_SYSTEM_IGNORE_PATH`
+- :variable:`CMAKE_SYSTEM_PREFIX_PATH`
+- :variable:`CMAKE_SYSTEM_LIBRARY_PATH`
+- :variable:`CMAKE_SYSTEM_INCLUDE_PATH`
+- :variable:`CMAKE_SYSTEM_PROGRAM_PATH`
diff --git a/Help/variable/IGNORE_SEARCH_LOCATIONS.txt b/Help/variable/IGNORE_SEARCH_LOCATIONS.txt
new file mode 100644
index 0000000..a98f359
--- /dev/null
+++ b/Help/variable/IGNORE_SEARCH_LOCATIONS.txt
@@ -0,0 +1,4 @@
+Ignoring search locations can be useful in cross-compiling environments where
+some system directories contain incompatible but possibly linkable libraries.
+For example, on cross-compiled cluster environments, this allows a user to
+ignore directories containing libraries meant for the front-end machine.
diff --git a/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt b/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt
new file mode 100644
index 0000000..a32a189
--- /dev/null
+++ b/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt
@@ -0,0 +1,2 @@
+By default, |CMAKE_IGNORE_VAR| is empty. It is intended to be set by the
+project or the end user.
diff --git a/Help/variable/IGNORE_SEARCH_PATH.txt b/Help/variable/IGNORE_SEARCH_PATH.txt
new file mode 100644
index 0000000..0811e02
--- /dev/null
+++ b/Help/variable/IGNORE_SEARCH_PATH.txt
@@ -0,0 +1,19 @@
+:ref:`Semicolon-separated list <CMake Language Lists>` of directories
+to be ignored by the various ``find...()`` commands.
+
+For :command:`find_program`, :command:`find_library`, :command:`find_file`,
+and :command:`find_path`, any file found in one of the listed directories
+will be ignored. The listed directories do not apply recursively, so any
+subdirectories to be ignored must also be explicitly listed.
+|CMAKE_IGNORE_VAR| does not affect the search *prefixes* used by these
+four commands. To ignore individual paths under a search prefix
+(e.g. ``bin``, ``include``, ``lib``, etc.), each path must be listed in
+|CMAKE_IGNORE_VAR| as a full absolute path. |CMAKE_IGNORE_PREFIX_VAR|
+provides a more appropriate way to ignore a whole search prefix.
+
+:command:`find_package` is also affected by |CMAKE_IGNORE_VAR|, but only
+for *Config mode* searches. Any ``<Name>Config.cmake`` or
+``<name>-config.cmake`` file found in one of the specified directories
+will be ignored. In addition, any search *prefix* found in |CMAKE_IGNORE_VAR|
+will be skipped for backward compatibility reasons, but new code should
+prefer to use |CMAKE_IGNORE_PREFIX_VAR| to ignore prefixes instead.
diff --git a/Help/variable/IGNORE_SEARCH_PREFIX.txt b/Help/variable/IGNORE_SEARCH_PREFIX.txt
new file mode 100644
index 0000000..f5ec3dc
--- /dev/null
+++ b/Help/variable/IGNORE_SEARCH_PREFIX.txt
@@ -0,0 +1,6 @@
+:ref:`Semicolon-separated list <CMake Language Lists>` of search *prefixes*
+to be ignored by the :command:`find_program`, :command:`find_library`,
+:command:`find_file`, and :command:`find_path` commands.
+The prefixes are also ignored by the *Config mode* of the
+:command:`find_package` command (*Module mode* is unaffected).
+To ignore specific directories instead, see |CMAKE_IGNORE_NONPREFIX_VAR|.
diff --git a/Help/variable/IGNORE_SEARCH_SYSTEM.txt b/Help/variable/IGNORE_SEARCH_SYSTEM.txt
new file mode 100644
index 0000000..78b285d6
--- /dev/null
+++ b/Help/variable/IGNORE_SEARCH_SYSTEM.txt
@@ -0,0 +1,5 @@
+|CMAKE_IGNORE_VAR| is populated by CMake as part of its platform
+and toolchain setup. Its purpose is to ignore locations containing
+incompatible binaries meant for the host rather than the target platform.
+The project or end user should not modify this variable, they should use
+|CMAKE_IGNORE_NONSYSTEM_VAR| instead.