Help: Revise CMAKE_*_PATH and CMAKE_SYSTEM_*_PATH variable docs (#15631)

Improve reStructuredText formatting and cross-references.  Specify
explicitly that each variable may be set to a ;-list of multiple values.

14 files changed, 88 insertions, 97 deletions

diff --git a/Help/variable/CMAKE_APPBUNDLE_PATH.rst b/Help/variable/CMAKE_APPBUNDLE_PATH.rst
index 469b316..2bc79ac 100644
--- a/Help/variable/CMAKE_APPBUNDLE_PATH.rst
+++ b/Help/variable/CMAKE_APPBUNDLE_PATH.rst
@@ -1,5 +1,6 @@
 CMAKE_APPBUNDLE_PATH
 --------------------
 
-Search path for OS X application bundles used by the :command:`find_program`,
-and :command:`find_package` commands.
+:ref:`;-list <CMake Language Lists>` of directories specifying a search path
+for OS X application bundles used by the :command:`find_program`, and
+:command:`find_package` commands.
diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_ROOT_PATH.rst
index 67948f7..ccf5234 100644
--- a/Help/variable/CMAKE_FIND_ROOT_PATH.rst
+++ b/Help/variable/CMAKE_FIND_ROOT_PATH.rst
@@ -1,7 +1,7 @@
 CMAKE_FIND_ROOT_PATH
 --------------------
 
-List of root paths to search on the filesystem.
+:ref:`;-list <CMake Language Lists>` of root paths to search on the filesystem.
 
 This variable is most useful when cross-compiling. CMake uses the paths in
 this list as alternative roots to find filesystem items with :command:`find_package`,
diff --git a/Help/variable/CMAKE_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_FRAMEWORK_PATH.rst
index f1bc75e..5ff08e6 100644
--- a/Help/variable/CMAKE_FRAMEWORK_PATH.rst
+++ b/Help/variable/CMAKE_FRAMEWORK_PATH.rst
@@ -1,6 +1,7 @@
 CMAKE_FRAMEWORK_PATH
 --------------------
 
-Search path for OS X frameworks used by the :command:`find_library`,
+:ref:`;-list <CMake Language Lists>` of directories specifying a search path
+for OS X frameworks used by the :command:`find_library`,
 :command:`find_package`, :command:`find_path`, and :command:`find_file`
 commands.
diff --git a/Help/variable/CMAKE_IGNORE_PATH.rst b/Help/variable/CMAKE_IGNORE_PATH.rst
index a818f74..92f3770 100644
--- a/Help/variable/CMAKE_IGNORE_PATH.rst
+++ b/Help/variable/CMAKE_IGNORE_PATH.rst
@@ -1,17 +1,18 @@
 CMAKE_IGNORE_PATH
 -----------------
 
-Path to be ignored by FIND_XXX() commands.
+:ref:`;-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.
 
-Specifies directories to be ignored by searches in FIND_XXX()
-commands.  This is useful in cross-compiled 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 that modules like FindX11 (and others) would
-normally search.  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.  If you want to ignore paths under
-prefixes (bin, include, lib, etc.), you'll need to specify them
-explicitly.  See also CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH,
-CMAKE_INCLUDE_PATH, CMAKE_PROGRAM_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.
+
+See also the :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_LIBRARY_PATH`,
+:variable:`CMAKE_INCLUDE_PATH`, and :variable:`CMAKE_PROGRAM_PATH` variables.
diff --git a/Help/variable/CMAKE_INCLUDE_PATH.rst b/Help/variable/CMAKE_INCLUDE_PATH.rst
index 360b403..e4e7f2c 100644
--- a/Help/variable/CMAKE_INCLUDE_PATH.rst
+++ b/Help/variable/CMAKE_INCLUDE_PATH.rst
@@ -1,10 +1,7 @@
 CMAKE_INCLUDE_PATH
 ------------------
 
-Path used for searching by FIND_FILE() and FIND_PATH().
-
-Specifies a path which will be used both by FIND_FILE() and
-FIND_PATH().  Both commands will check each of the contained
-directories for the existence of the file which is currently searched.
-By default it is empty, it is intended to be set by the project.  See
-also CMAKE_SYSTEM_INCLUDE_PATH, CMAKE_PREFIX_PATH.
+:ref:`;-list <CMake Language Lists>` of directories specifying a search path
+for the :command:`find_file` and :command:`find_path` commands.  By default it
+is empty, it is intended to be set by the project.  See also
+:variable:`CMAKE_SYSTEM_INCLUDE_PATH` and :variable:`CMAKE_PREFIX_PATH`.
diff --git a/Help/variable/CMAKE_LIBRARY_PATH.rst b/Help/variable/CMAKE_LIBRARY_PATH.rst
index e77dd34..b1770dc 100644
--- a/Help/variable/CMAKE_LIBRARY_PATH.rst
+++ b/Help/variable/CMAKE_LIBRARY_PATH.rst
@@ -1,10 +1,7 @@
 CMAKE_LIBRARY_PATH
 ------------------
 
-Path used for searching by FIND_LIBRARY().
-
-Specifies a path which will be used by FIND_LIBRARY().  FIND_LIBRARY()
-will check each of the contained directories for the existence of the
-library which is currently searched.  By default it is empty, it is
+:ref:`;-list <CMake Language Lists>` of directories specifying a search path
+for the :command:`find_library` command.  By default it is empty, it is
 intended to be set by the project.  See also
-CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_PREFIX_PATH.
+:variable:`CMAKE_SYSTEM_LIBRARY_PATH` and :variable:`CMAKE_PREFIX_PATH`.
diff --git a/Help/variable/CMAKE_MODULE_PATH.rst b/Help/variable/CMAKE_MODULE_PATH.rst
index a2dde45..5ea7cbb 100644
--- a/Help/variable/CMAKE_MODULE_PATH.rst
+++ b/Help/variable/CMAKE_MODULE_PATH.rst
@@ -1,8 +1,7 @@
 CMAKE_MODULE_PATH
 -----------------
 
-List of directories to search for CMake modules.
-
-Commands like include() and find_package() search for files in
-directories listed by this variable before checking the default
-modules that come with CMake.
+:ref:`;-list <CMake Language Lists>` of directories specifying a search path
+for CMake modules to be loaded by the the :command:`include` or
+:command:`find_package` commands before checking the default modules that come
+with CMake.  By default it is empty, it is intended to be set by the project.
diff --git a/Help/variable/CMAKE_PREFIX_PATH.rst b/Help/variable/CMAKE_PREFIX_PATH.rst
index 4c21d5e..c2a4a60 100644
--- a/Help/variable/CMAKE_PREFIX_PATH.rst
+++ b/Help/variable/CMAKE_PREFIX_PATH.rst
@@ -1,13 +1,15 @@
 CMAKE_PREFIX_PATH
 -----------------
 
-Path used for searching by FIND_XXX(), with appropriate suffixes added.
+:ref:`;-list <CMake Language Lists>` of directories specifying installation
+*prefixes* to be searched by the :command:`find_package`,
+:command:`find_program`, :command:`find_library`, :command:`find_file`, and
+:command:`find_path` commands.  Each command will add appropriate
+subdirectories (like ``bin``, ``lib``, or ``include``) as specified in its own
+documentation.
 
-Specifies a path which will be used by the FIND_XXX() commands.  It
-contains the "base" directories, the FIND_XXX() commands append
-appropriate subdirectories to the base directories.  So FIND_PROGRAM()
-adds /bin to each of the directories in the path, FIND_LIBRARY()
-appends /lib to each of the directories, and FIND_PATH() and
-FIND_FILE() append /include .  By default it is empty, it is intended
-to be set by the project.  See also CMAKE_SYSTEM_PREFIX_PATH,
-CMAKE_INCLUDE_PATH, CMAKE_LIBRARY_PATH, CMAKE_PROGRAM_PATH.
+By default this is empty.  It is intended to be set by the project.
+
+See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`, :variable:`CMAKE_INCLUDE_PATH`,
+:variable:`CMAKE_LIBRARY_PATH`, :variable:`CMAKE_PROGRAM_PATH`, and
+:variable:`CMAKE_IGNORE_PATH`.
diff --git a/Help/variable/CMAKE_PROGRAM_PATH.rst b/Help/variable/CMAKE_PROGRAM_PATH.rst
index 02c5e02..799e119 100644
--- a/Help/variable/CMAKE_PROGRAM_PATH.rst
+++ b/Help/variable/CMAKE_PROGRAM_PATH.rst
@@ -1,10 +1,7 @@
 CMAKE_PROGRAM_PATH
 ------------------
 
-Path used for searching by FIND_PROGRAM().
-
-Specifies a path which will be used by FIND_PROGRAM().  FIND_PROGRAM()
-will check each of the contained directories for the existence of the
-program which is currently searched.  By default it is empty, it is
+:ref:`;-list <CMake Language Lists>` of directories specifying a search path
+for the :command:`find_program` command.  By default it is empty, it is
 intended to be set by the project.  See also
-CMAKE_SYSTEM_PROGRAM_PATH, CMAKE_PREFIX_PATH.
+:variable:`CMAKE_SYSTEM_PROGRAM_PATH` and :variable:`CMAKE_PREFIX_PATH`.
diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst
index 9e6b195..4ad7e33 100644
--- a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst
+++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst
@@ -1,15 +1,18 @@
 CMAKE_SYSTEM_IGNORE_PATH
 ------------------------
 
-Path to be ignored by FIND_XXX() commands.
+:ref:`;-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.
 
-Specifies directories to be ignored by searches in FIND_XXX()
-commands.  This is useful in cross-compiled 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 that modules like FindX11 (and others) would
-normally search.  By default this contains a list of directories
-containing incompatible binaries for the host system.  See also
-CMAKE_SYSTEM_PREFIX_PATH, CMAKE_SYSTEM_LIBRARY_PATH,
-CMAKE_SYSTEM_INCLUDE_PATH, and CMAKE_SYSTEM_PROGRAM_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.
+
+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.
diff --git a/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst
index 1734185..2c14345 100644
--- a/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst
+++ b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst
@@ -1,11 +1,8 @@
 CMAKE_SYSTEM_INCLUDE_PATH
 -------------------------
 
-Path used for searching by FIND_FILE() and FIND_PATH().
-
-Specifies a path which will be used both by FIND_FILE() and
-FIND_PATH().  Both commands will check each of the contained
-directories for the existence of the file which is currently searched.
-By default it contains the standard directories for the current
-system.  It is NOT intended to be modified by the project, use
-CMAKE_INCLUDE_PATH for this.  See also CMAKE_SYSTEM_PREFIX_PATH.
+:ref:`;-list <CMake Language Lists>` of directories specifying a search path
+for the :command:`find_file` and :command:`find_path` commands.  By default
+this contains the standard directories for the current system.  It is *not*
+intended to be modified by the project; use :variable:`CMAKE_INCLUDE_PATH` for
+this.  See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`.
diff --git a/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst
index 4778646..3969cb9 100644
--- a/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst
+++ b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst
@@ -1,11 +1,8 @@
 CMAKE_SYSTEM_LIBRARY_PATH
 -------------------------
 
-Path used for searching by FIND_LIBRARY().
-
-Specifies a path which will be used by FIND_LIBRARY().  FIND_LIBRARY()
-will check each of the contained directories for the existence of the
-library which is currently searched.  By default it contains the
-standard directories for the current system.  It is NOT intended to be
-modified by the project, use CMAKE_LIBRARY_PATH for this.  See also
-CMAKE_SYSTEM_PREFIX_PATH.
+:ref:`;-list <CMake Language Lists>` of directories specifying a search path
+for the :command:`find_library` command.  By default this contains the
+standard directories for the current system.  It is *not* intended to be
+modified by the project; use :variable:`CMAKE_LIBRARY_PATH` for this.
+See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`.
diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
index 537eaba..e74dfad 100644
--- a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
+++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
@@ -1,16 +1,18 @@
 CMAKE_SYSTEM_PREFIX_PATH
 ------------------------
 
-Path used for searching by FIND_XXX(), with appropriate suffixes added.
+:ref:`;-list <CMake Language Lists>` of directories specifying installation
+*prefixes* to be searched by the :command:`find_package`,
+:command:`find_program`, :command:`find_library`, :command:`find_file`, and
+:command:`find_path` commands.  Each command will add appropriate
+subdirectories (like ``bin``, ``lib``, or ``include``) as specified in its own
+documentation.
 
-Specifies a path which will be used by the FIND_XXX() commands.  It
-contains the "base" directories, the FIND_XXX() commands append
-appropriate subdirectories to the base directories.  So FIND_PROGRAM()
-adds /bin to each of the directories in the path, FIND_LIBRARY()
-appends /lib to each of the directories, and FIND_PATH() and
-FIND_FILE() append /include .  By default this contains the standard
-directories for the current system, the CMAKE_INSTALL_PREFIX and
-the :variable:`CMAKE_STAGING_PREFIX`.  It is NOT intended to be modified by
-the project, use CMAKE_PREFIX_PATH for this.  See also CMAKE_SYSTEM_INCLUDE_PATH,
-CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_SYSTEM_PROGRAM_PATH, and
-CMAKE_SYSTEM_IGNORE_PATH.
+By default this contains the standard directories for the current system, the
+:variable:`CMAKE_INSTALL_PREFIX`, and the :variable:`CMAKE_STAGING_PREFIX`.
+It is *not* intended to be modified by the project; use
+:variable:`CMAKE_PREFIX_PATH` for this.
+
+See also :variable:`CMAKE_SYSTEM_INCLUDE_PATH`,
+:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_PROGRAM_PATH`,
+and :variable:`CMAKE_SYSTEM_IGNORE_PATH`.
diff --git a/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst
index e1fad63..cf1b83e 100644
--- a/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst
+++ b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst
@@ -1,11 +1,8 @@
 CMAKE_SYSTEM_PROGRAM_PATH
 -------------------------
 
-Path used for searching by FIND_PROGRAM().
-
-Specifies a path which will be used by FIND_PROGRAM().  FIND_PROGRAM()
-will check each of the contained directories for the existence of the
-program which is currently searched.  By default it contains the
-standard directories for the current system.  It is NOT intended to be
-modified by the project, use CMAKE_PROGRAM_PATH for this.  See also
-CMAKE_SYSTEM_PREFIX_PATH.
+:ref:`;-list <CMake Language Lists>` of directories specifying a search path
+for the :command:`find_program` command.  By default this contains the
+standard directories for the current system.  It is *not* intended to be
+modified by the project; use :variable:`CMAKE_PROGRAM_PATH` for this.
+See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`.