Convert builtin help to reStructuredText source files

Run the convert-help.bash script to convert documentation:

 ./convert-help.bash "/path/to/CMake-build/bin"

Then remove it.

1 files changed, 406 insertions, 0 deletions

diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
new file mode 100644
index 0000000..27d0ac7
--- /dev/null
+++ b/Help/command/find_package.rst
@@ -0,0 +1,406 @@
+find_package
+------------
+
+Load settings for an external project.
+
+::
+
+  find_package(<package> [version] [EXACT] [QUIET] [MODULE]
+               [REQUIRED] [[COMPONENTS] [components...]]
+               [OPTIONAL_COMPONENTS components...]
+               [NO_POLICY_SCOPE])
+
+Finds and loads settings from an external project.  <package>_FOUND
+will be set to indicate whether the package was found.  When the
+package is found package-specific information is provided through
+variables and imported targets documented by the package itself.  The
+QUIET option disables messages if the package cannot be found.  The
+MODULE option disables the second signature documented below.  The
+REQUIRED option stops processing with an error message if the package
+cannot be found.
+
+A package-specific list of required components may be listed after the
+COMPONENTS option (or after the REQUIRED option if present).
+Additional optional components may be listed after
+OPTIONAL_COMPONENTS.  Available components and their influence on
+whether a package is considered to be found are defined by the target
+package.
+
+The [version] argument requests a version with which the package found
+should be compatible (format is major[.minor[.patch[.tweak]]]).  The
+EXACT option requests that the version be matched exactly.  If no
+[version] and/or component list is given to a recursive invocation
+inside a find-module, the corresponding arguments are forwarded
+automatically from the outer call (including the EXACT flag for
+[version]).  Version support is currently provided only on a
+package-by-package basis (details below).
+
+User code should generally look for packages using the above simple
+signature.  The remainder of this command documentation specifies the
+full command signature and details of the search process.  Project
+maintainers wishing to provide a package to be found by this command
+are encouraged to read on.
+
+The command has two modes by which it searches for packages: "Module"
+mode and "Config" mode.  Module mode is available when the command is
+invoked with the above reduced signature.  CMake searches for a file
+called "Find<package>.cmake" in the CMAKE_MODULE_PATH followed by the
+CMake installation.  If the file is found, it is read and processed by
+CMake.  It is responsible for finding the package, checking the
+version, and producing any needed messages.  Many find-modules provide
+limited or no support for versioning; check the module documentation.
+If no module is found and the MODULE option is not given the command
+proceeds to Config mode.
+
+The complete Config mode command signature is:
+
+::
+
+  find_package(<package> [version] [EXACT] [QUIET]
+               [REQUIRED] [[COMPONENTS] [components...]]
+               [CONFIG|NO_MODULE]
+               [NO_POLICY_SCOPE]
+               [NAMES name1 [name2 ...]]
+               [CONFIGS config1 [config2 ...]]
+               [HINTS path1 [path2 ... ]]
+               [PATHS path1 [path2 ... ]]
+               [PATH_SUFFIXES suffix1 [suffix2 ...]]
+               [NO_DEFAULT_PATH]
+               [NO_CMAKE_ENVIRONMENT_PATH]
+               [NO_CMAKE_PATH]
+               [NO_SYSTEM_ENVIRONMENT_PATH]
+               [NO_CMAKE_PACKAGE_REGISTRY]
+               [NO_CMAKE_BUILDS_PATH]
+               [NO_CMAKE_SYSTEM_PATH]
+               [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
+               [CMAKE_FIND_ROOT_PATH_BOTH |
+                ONLY_CMAKE_FIND_ROOT_PATH |
+                NO_CMAKE_FIND_ROOT_PATH])
+
+The CONFIG option may be used to skip Module mode explicitly and
+switch to Config mode.  It is synonymous to using NO_MODULE.  Config
+mode is also implied by use of options not specified in the reduced
+signature.
+
+Config mode attempts to locate a configuration file provided by the
+package to be found.  A cache entry called <package>_DIR is created to
+hold the directory containing the file.  By default the command
+searches for a package with the name <package>.  If the NAMES option
+is given the names following it are used instead of <package>.  The
+command searches for a file called "<name>Config.cmake" or
+"<lower-case-name>-config.cmake" for each name specified.  A
+replacement set of possible configuration file names may be given
+using the CONFIGS option.  The search procedure is specified below.
+Once found, the configuration file is read and processed by CMake.
+Since the file is provided by the package it already knows the
+location of package contents.  The full path to the configuration file
+is stored in the cmake variable <package>_CONFIG.
+
+All configuration files which have been considered by CMake while
+searching for an installation of the package with an appropriate
+version are stored in the cmake variable <package>_CONSIDERED_CONFIGS,
+the associated versions in <package>_CONSIDERED_VERSIONS.
+
+If the package configuration file cannot be found CMake will generate
+an error describing the problem unless the QUIET argument is
+specified.  If REQUIRED is specified and the package is not found a
+fatal error is generated and the configure step stops executing.  If
+<package>_DIR has been set to a directory not containing a
+configuration file CMake will ignore it and search from scratch.
+
+When the [version] argument is given Config mode will only find a
+version of the package that claims compatibility with the requested
+version (format is major[.minor[.patch[.tweak]]]).  If the EXACT
+option is given only a version of the package claiming an exact match
+of the requested version may be found.  CMake does not establish any
+convention for the meaning of version numbers.  Package version
+numbers are checked by "version" files provided by the packages
+themselves.  For a candidate package configuration file
+"<config-file>.cmake" the corresponding version file is located next
+to it and named either "<config-file>-version.cmake" or
+"<config-file>Version.cmake".  If no such version file is available
+then the configuration file is assumed to not be compatible with any
+requested version.  A basic version file containing generic version
+matching code can be created using the macro
+write_basic_package_version_file(), see its documentation for more
+details.  When a version file is found it is loaded to check the
+requested version number.  The version file is loaded in a nested
+scope in which the following variables have been defined:
+
+::
+
+  PACKAGE_FIND_NAME          = the <package> name
+  PACKAGE_FIND_VERSION       = full requested version string
+  PACKAGE_FIND_VERSION_MAJOR = major version if requested, else 0
+  PACKAGE_FIND_VERSION_MINOR = minor version if requested, else 0
+  PACKAGE_FIND_VERSION_PATCH = patch version if requested, else 0
+  PACKAGE_FIND_VERSION_TWEAK = tweak version if requested, else 0
+  PACKAGE_FIND_VERSION_COUNT = number of version components, 0 to 4
+
+The version file checks whether it satisfies the requested version and
+sets these variables:
+
+::
+
+  PACKAGE_VERSION            = full provided version string
+  PACKAGE_VERSION_EXACT      = true if version is exact match
+  PACKAGE_VERSION_COMPATIBLE = true if version is compatible
+  PACKAGE_VERSION_UNSUITABLE = true if unsuitable as any version
+
+These variables are checked by the find_package command to determine
+whether the configuration file provides an acceptable version.  They
+are not available after the find_package call returns.  If the version
+is acceptable the following variables are set:
+
+::
+
+  <package>_VERSION       = full provided version string
+  <package>_VERSION_MAJOR = major version if provided, else 0
+  <package>_VERSION_MINOR = minor version if provided, else 0
+  <package>_VERSION_PATCH = patch version if provided, else 0
+  <package>_VERSION_TWEAK = tweak version if provided, else 0
+  <package>_VERSION_COUNT = number of version components, 0 to 4
+
+and the corresponding package configuration file is loaded.  When
+multiple package configuration files are available whose version files
+claim compatibility with the version requested it is unspecified which
+one is chosen.  No attempt is made to choose a highest or closest
+version number.
+
+Config mode provides an elaborate interface and search procedure.
+Much of the interface is provided for completeness and for use
+internally by find-modules loaded by Module mode.  Most user code
+should simply call
+
+::
+
+  find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
+
+in order to find a package.  Package maintainers providing CMake
+package configuration files are encouraged to name and install them
+such that the procedure outlined below will find them without
+requiring use of additional options.
+
+CMake constructs a set of possible installation prefixes for the
+package.  Under each prefix several directories are searched for a
+configuration file.  The tables below show the directories searched.
+Each entry is meant for installation trees following Windows (W), UNIX
+(U), or Apple (A) conventions.
+
+::
+
+  <prefix>/                                               (W)
+  <prefix>/(cmake|CMake)/                                 (W)
+  <prefix>/<name>*/                                       (W)
+  <prefix>/<name>*/(cmake|CMake)/                         (W)
+  <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/          (U)
+  <prefix>/(lib/<arch>|lib|share)/<name>*/                (U)
+  <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/  (U)
+
+On systems supporting OS X Frameworks and Application Bundles the
+following directories are searched for frameworks or bundles
+containing a configuration file:
+
+::
+
+  <prefix>/<name>.framework/Resources/                    (A)
+  <prefix>/<name>.framework/Resources/CMake/              (A)
+  <prefix>/<name>.framework/Versions/*/Resources/         (A)
+  <prefix>/<name>.framework/Versions/*/Resources/CMake/   (A)
+  <prefix>/<name>.app/Contents/Resources/                 (A)
+  <prefix>/<name>.app/Contents/Resources/CMake/           (A)
+
+In all cases the <name> is treated as case-insensitive and corresponds
+to any of the names specified (<package> or names given by NAMES).
+Paths with lib/<arch> are enabled if CMAKE_LIBRARY_ARCHITECTURE is
+set.  If PATH_SUFFIXES is specified the suffixes are appended to each
+(W) or (U) directory entry one-by-one.
+
+This set of directories is intended to work in cooperation with
+projects that provide configuration files in their installation trees.
+Directories above marked with (W) are intended for installations on
+Windows where the prefix may point at the top of an application's
+installation directory.  Those marked with (U) are intended for
+installations on UNIX platforms where the prefix is shared by multiple
+packages.  This is merely a convention, so all (W) and (U) directories
+are still searched on all platforms.  Directories marked with (A) are
+intended for installations on Apple platforms.  The cmake variables
+CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE determine the order of
+preference as specified below.
+
+The set of installation prefixes is constructed using the following
+steps.  If NO_DEFAULT_PATH is specified all NO_* options are enabled.
+
+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
+   CMAKE_FRAMEWORK_PATH
+   CMAKE_APPBUNDLE_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.
+
+::
+
+   <package>_DIR
+   CMAKE_PREFIX_PATH
+   CMAKE_FRAMEWORK_PATH
+   CMAKE_APPBUNDLE_PATH
+
+3.  Search 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 passed.  Path entries ending
+in "/bin" or "/sbin" are automatically converted to their parent
+directories.
+
+::
+
+   PATH
+
+5.  Search project build trees recently configured in a CMake GUI.
+This can be skipped if NO_CMAKE_BUILDS_PATH is passed.  It is intended
+for the case when a user is building multiple dependent projects one
+after another.
+
+6.  Search paths stored in the CMake user package registry.  This can
+be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed.  On Windows a
+<package> may appear under registry key
+
+::
+
+  HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package>
+
+as a REG_SZ value, with arbitrary name, that specifies the directory
+containing the package configuration file.  On UNIX platforms a
+<package> may appear under the directory
+
+::
+
+  ~/.cmake/packages/<package>
+
+as a file, with arbitrary name, whose content specifies the directory
+containing the package configuration file.  See the export(PACKAGE)
+command to create user package registry entries for project build
+trees.
+
+7.  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
+   CMAKE_SYSTEM_FRAMEWORK_PATH
+   CMAKE_SYSTEM_APPBUNDLE_PATH
+
+8.  Search paths stored in the CMake system package registry.  This
+can be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed.  On
+Windows a <package> may appear under registry key
+
+::
+
+  HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>
+
+as a REG_SZ value, with arbitrary name, that specifies the directory
+containing the package configuration file.  There is no system package
+registry on non-Windows platforms.
+
+9.  Search paths specified by the PATHS option.  These are typically
+hard-coded guesses.
+
+On Darwin or systems supporting OS X Frameworks, the cmake variable
+CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
+
+::
+
+   "FIRST"  - Try to find frameworks before standard
+              libraries or headers. This is the default on Darwin.
+   "LAST"   - Try to find frameworks after standard
+              libraries or headers.
+   "ONLY"   - Only try to find frameworks.
+   "NEVER" - Never try to find frameworks.
+
+On Darwin or systems supporting OS X Application Bundles, the cmake
+variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
+following:
+
+::
+
+   "FIRST"  - Try to find application bundles before standard
+              programs. This is the default on Darwin.
+   "LAST"   - Try to find application bundles after standard
+              programs.
+   "ONLY"   - Only try to find application bundles.
+   "NEVER" - Never try to find application bundles.
+
+The CMake 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.  By
+default it is empty.  It is 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 and then the non-rooted directories will be
+searched.  The default behavior can be adjusted by setting
+CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.  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
+used.  If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
+directories will be searched.
+
+The default search order is designed to be most-specific to
+least-specific for common use cases.  Projects may override the order
+by simply calling the command multiple times and using the NO_*
+options:
+
+::
+
+   find_package(<package> PATHS paths... NO_DEFAULT_PATH)
+   find_package(<package>)
+
+Once one of the calls succeeds the result variable will be set and
+stored in the cache so that no call will search again.
+
+Every non-REQUIRED find_package() call can be disabled by setting the
+variable CMAKE_DISABLE_FIND_PACKAGE_<package> to TRUE.  See the
+documentation for the CMAKE_DISABLE_FIND_PACKAGE_<package> variable
+for more information.
+
+When loading a find module or package configuration file find_package
+defines variables to provide information about the call arguments (and
+restores their original state before returning):
+
+::
+
+ <package>_FIND_REQUIRED      = true if REQUIRED option was given
+ <package>_FIND_QUIETLY       = true if QUIET option was given
+ <package>_FIND_VERSION       = full requested version string
+ <package>_FIND_VERSION_MAJOR = major version if requested, else 0
+ <package>_FIND_VERSION_MINOR = minor version if requested, else 0
+ <package>_FIND_VERSION_PATCH = patch version if requested, else 0
+ <package>_FIND_VERSION_TWEAK = tweak version if requested, else 0
+ <package>_FIND_VERSION_COUNT = number of version components, 0 to 4
+ <package>_FIND_VERSION_EXACT = true if EXACT option was given
+ <package>_FIND_COMPONENTS    = list of requested components
+ <package>_FIND_REQUIRED_<c>  = true if component <c> is required
+                                false if component <c> is optional
+
+In Module mode the loaded find module is responsible to honor the
+request detailed by these variables; see the find module for details.
+In Config mode find_package handles REQUIRED, QUIET, and version
+options automatically but leaves it to the package configuration file
+to handle components in a way that makes sense for the package.  The
+package configuration file may set <package>_FOUND to false to tell
+find_package that component requirements are not satisfied.
+
+See the cmake_policy() command documentation for discussion of the
+NO_POLICY_SCOPE option.