Help: Document the CMAKE_FIND_ROOT_PATH* variables.

Add a replacement template for the variables, and link to them from
the documentation for the find_* commands.

Help/command/FIND_XXX_ROOT.txt

@@ -1,9 +1,9 @@
-The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
+The CMake variable :variable:`CMAKE_FIND_ROOT_PATH` specifies one or more
 directories to be prepended to all other search directories.  This
 effectively "re-roots" the entire search under given locations.
 Paths which are descendants of the :variable:`CMAKE_STAGING_PREFIX` are excluded
 from this re-rooting, because that variable is always a path on the host system.
-By default the CMAKE_FIND_ROOT_PATH is empty.
+By default the :variable:`CMAKE_FIND_ROOT_PATH` is empty.
 
 The :variable:`CMAKE_SYSROOT` variable can also be used to specify exactly one
 directory to use as a prefix.  Setting :variable:`CMAKE_SYSROOT` also has other
@@ -12,12 +12,12 @@ effects.  See the documentation for that variable for more.
 These variables are especially useful when cross-compiling to
 point to the root directory of the target environment and CMake will
 search there too.  By default at first the directories listed in
-CMAKE_FIND_ROOT_PATH are searched, then the :variable:`CMAKE_SYSROOT` directory is
+:variable:`CMAKE_FIND_ROOT_PATH` are searched, then the :variable:`CMAKE_SYSROOT`
-searched, and then the non-rooted directories will be
+directory is searched, and then the non-rooted directories will be
 searched.  The default behavior can be adjusted by setting
 |CMAKE_FIND_ROOT_PATH_MODE_XXX|.  This behavior can be manually
 overridden on a per-call basis.  By using CMAKE_FIND_ROOT_PATH_BOTH
 the search order will be as described above.  If
-NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be
+NO_CMAKE_FIND_ROOT_PATH is used then :variable:`CMAKE_FIND_ROOT_PATH` will not be
 used.  If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
 directories and directories below :variable:`CMAKE_STAGING_PREFIX` will be searched.

Help/command/find_file.rst

@@ -22,6 +22,6 @@ find_file
 .. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
 
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
-   CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
+   :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`
 
 .. include:: FIND_XXX.txt

Help/command/find_library.rst

@@ -22,7 +22,7 @@ find_library
 .. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
 
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
-   CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
+   :variable:`CMAKE_FIND_ROOT_PATH_MODE_LIBRARY`
 
 .. include:: FIND_XXX.txt
 

Help/command/find_package.rst

@@ -320,7 +320,7 @@ hard-coded guesses.
 .. |FIND_XXX| replace:: find_package
 .. |FIND_ARGS_XXX| replace:: <package>
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
-   CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
+   :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE`
 
 .. include:: FIND_XXX_MAC.txt
 .. include:: FIND_XXX_ROOT.txt

Help/command/find_path.rst

@@ -22,7 +22,7 @@ find_path
 .. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
 
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
-   CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
+   :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`
 
 .. include:: FIND_XXX.txt
 

Help/command/find_program.rst

@@ -20,6 +20,6 @@ find_program
 .. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_APPBUNDLE_PATH
 
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
-   CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
+   :variable:`CMAKE_FIND_ROOT_PATH_MODE_PROGRAM`
 
 .. include:: FIND_XXX.txt

Help/manual/cmake-variables.7.rst

@@ -97,8 +97,13 @@ Variables that Change Behavior
    /variable/CMAKE_SYSROOT
    /variable/CMAKE_FIND_LIBRARY_PREFIXES
    /variable/CMAKE_FIND_LIBRARY_SUFFIXES
-   /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE
    /variable/CMAKE_FIND_NO_INSTALL_PREFIX
+   /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE
+   /variable/CMAKE_FIND_ROOT_PATH
+   /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
+   /variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
+   /variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
+   /variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
    /variable/CMAKE_IGNORE_PATH
    /variable/CMAKE_INCLUDE_PATH
    /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE

Help/variable/CMAKE_FIND_ROOT_PATH.rst

@@ -0,0 +1,8 @@
+CMAKE_FIND_ROOT_PATH
+--------------------
+
+List 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`,
+:command:`find_library` etc.

Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst

@@ -0,0 +1,6 @@
+CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
+---------------------------------
+
+.. |FIND_XXX| replace:: :command:`find_file` and :command:`find_path`
+
+.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt

Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst

@@ -0,0 +1,6 @@
+CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
+---------------------------------
+
+.. |FIND_XXX| replace:: :command:`find_library`
+
+.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt

Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst

@@ -0,0 +1,6 @@
+CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
+---------------------------------
+
+.. |FIND_XXX| replace:: :command:`find_package`
+
+.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt

Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst

@@ -0,0 +1,6 @@
+CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
+---------------------------------
+
+.. |FIND_XXX| replace:: :command:`find_program`
+
+.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt

Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt

@@ -0,0 +1,8 @@
+This variable controls whether the :variable:`CMAKE_FIND_ROOT_PATH` and
+:variable:`CMAKE_SYSROOT` are used by |FIND_XXX|.
+
+If set to ``ONLY``, then only the roots in :variable:`CMAKE_FIND_ROOT_PATH`
+will be searched. If set to ``NEVER``, then the roots in
+:variable:`CMAKE_FIND_ROOT_PATH` will be ignored and only the host system
+root will be used. If set to ``BOTH``, then the host system paths and the
+paths in :variable:`CMAKE_FIND_ROOT_PATH` will be searched.