Help: Factor out find_* command duplication

These documents were represented in the builtin documentation using a
common starting point with placeholders substituted by each command.
Convert them back to this approach using the reStructuredText include
directive and substitutions to avoid duplication.

1 files changed, 101 insertions, 0 deletions

diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt
new file mode 100644
index 0000000..5889e90
--- /dev/null
+++ b/Help/command/FIND_XXX.txt
@@ -0,0 +1,101 @@
+A short-hand signature is:
+
+.. parsed-literal::
+
+   |FIND_XXX| (<VAR> name1 [path1 path2 ...])
+
+The general signature is:
+
+.. parsed-literal::
+
+   |FIND_XXX| (
+             <VAR>
+             name | |NAMES|
+             [HINTS path1 [path2 ... ENV var]]
+             [PATHS path1 [path2 ... ENV var]]
+             [PATH_SUFFIXES suffix1 [suffix2 ...]]
+             [DOC "cache documentation string"]
+             [NO_DEFAULT_PATH]
+             [NO_CMAKE_ENVIRONMENT_PATH]
+             [NO_CMAKE_PATH]
+             [NO_SYSTEM_ENVIRONMENT_PATH]
+             [NO_CMAKE_SYSTEM_PATH]
+             [CMAKE_FIND_ROOT_PATH_BOTH |
+              ONLY_CMAKE_FIND_ROOT_PATH |
+              NO_CMAKE_FIND_ROOT_PATH]
+            )
+
+This command is used to find a |SEARCH_XXX_DESC|.
+A cache entry named by ``<VAR>`` is created to store the result
+of this command.
+If the |SEARCH_XXX| is found the result is stored in the variable
+and the search will not be repeated unless the variable is cleared.
+If nothing is found, the result will be
+``<VAR>-NOTFOUND``, and the search will be attempted again the
+next time |FIND_XXX| is invoked with the same variable.
+The name of the |SEARCH_XXX| that
+is searched for is specified by the names listed
+after the NAMES argument.   Additional search locations
+can be specified after the PATHS argument.  If ENV var is
+found in the HINTS or PATHS section the environment variable var
+will be read and converted from a system environment variable to
+a cmake style list of paths.  For example ENV PATH would be a way
+to list the system path variable. The argument
+after DOC will be used for the documentation string in
+the cache.
+PATH_SUFFIXES specifies additional subdirectories to check below
+each search path.
+
+If NO_DEFAULT_PATH is specified, then no additional paths are
+added to the search.
+If NO_DEFAULT_PATH is not specified, the search process is as follows:
+
+.. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
+   <prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_PREFIX_PATH
+
+.. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
+   <prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
+
+1. Search paths specified in cmake-specific cache variables.
+   These are intended to be used on the command line with a -DVAR=value.
+   This can be skipped if NO_CMAKE_PATH is passed.
+
+   * |CMAKE_PREFIX_PATH_XXX|
+   * |CMAKE_XXX_PATH|
+   * |CMAKE_XXX_MAC_PATH|
+
+2. Search paths specified in cmake-specific environment variables.
+   These are intended to be set in the user's shell configuration.
+   This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.
+
+   * |CMAKE_PREFIX_PATH_XXX|
+   * |CMAKE_XXX_PATH|
+   * |CMAKE_XXX_MAC_PATH|
+
+3. Search the paths specified by the HINTS option.
+   These should be paths computed by system introspection, such as a
+   hint provided by the location of another item already found.
+   Hard-coded guesses should be specified with the PATHS option.
+
+4. Search the standard system environment variables.
+   This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
+
+   * |SYSTEM_ENVIRONMENT_PATH_XXX|
+
+5. Search cmake variables defined in the Platform files
+   for the current system.  This can be skipped if NO_CMAKE_SYSTEM_PATH
+   is passed.
+
+   * |CMAKE_SYSTEM_PREFIX_PATH_XXX|
+   * |CMAKE_SYSTEM_XXX_PATH|
+   * |CMAKE_SYSTEM_XXX_MAC_PATH|
+
+6. Search the paths specified by the PATHS option
+   or in the short-hand version of the command.
+   These are typically hard-coded guesses.
+
+.. |FIND_ARGS_XXX| replace:: <VAR> NAMES name
+
+.. include:: FIND_XXX_MAC.txt
+.. include:: FIND_XXX_ROOT.txt
+.. include:: FIND_XXX_ORDER.txt