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, 441 insertions, 0 deletions

diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
new file mode 100644
index 0000000..1147ab8
--- /dev/null
+++ b/Help/manual/cmake.1.rst
@@ -0,0 +1,441 @@
+cmake(1)
+********
+
+::
+
+  cmake - Cross-Platform Makefile Generator.
+
+::
+
+  cmake [options] <path-to-source>
+  cmake [options] <path-to-existing-build>
+
+The "cmake" executable is the CMake command-line interface.  It may be
+used to configure projects in scripts.  Project configuration settings
+may be specified on the command line with the -D option.  The -i
+option will cause cmake to interactively prompt for such settings.
+
+CMake is a cross-platform build system generator.  Projects specify
+their build process with platform-independent CMake listfiles included
+in each directory of a source tree with the name CMakeLists.txt.
+Users build a project by using CMake to generate a build system for a
+native tool on their platform.
+
+
+* ``-C <initial-cache>``: Pre-load a script to populate the cache.
+
+  When cmake is first run in an empty build tree, it creates a
+  CMakeCache.txt file and populates it with customizable settings for
+  the project.  This option may be used to specify a file from which
+  to load cache entries before the first pass through the project's
+  cmake listfiles.  The loaded entries take priority over the
+  project's default values.  The given file should be a CMake script
+  containing SET commands that use the CACHE option, not a
+  cache-format file.
+
+* ``-D <var>:<type>=<value>``: Create a cmake cache entry.
+
+  When cmake is first run in an empty build tree, it creates a
+  CMakeCache.txt file and populates it with customizable settings for
+  the project.  This option may be used to specify a setting that
+  takes priority over the project's default value.  The option may be
+  repeated for as many cache entries as desired.
+
+* ``-U <globbing_expr>``: Remove matching entries from CMake cache.
+
+  This option may be used to remove one or more variables from the
+  CMakeCache.txt file, globbing expressions using * and ? are
+  supported.  The option may be repeated for as many cache entries as
+  desired.
+
+  Use with care, you can make your CMakeCache.txt non-working.
+
+* ``-G <generator-name>``: Specify a build system generator.
+
+  CMake may support multiple native build systems on certain
+  platforms.  A generator is responsible for generating a particular
+  build system.  Possible generator names are specified in the
+  Generators section.
+
+* ``-T <toolset-name>``: Specify toolset name if supported by generator.
+
+  Some CMake generators support a toolset name to be given to the
+  native build system to choose a compiler.  This is supported only on
+  specific generators:
+
+  ::
+
+    Visual Studio >= 10
+    Xcode >= 3.0
+
+  See native build system documentation for allowed toolset names.
+
+* ``-Wno-dev``: Suppress developer warnings.
+
+  Suppress warnings that are meant for the author of the
+  CMakeLists.txt files.
+
+* ``-Wdev``: Enable developer warnings.
+
+  Enable warnings that are meant for the author of the CMakeLists.txt
+  files.
+
+* ``-E``: CMake command mode.
+
+  For true platform independence, CMake provides a list of commands
+  that can be used on all systems.  Run with -E help for the usage
+  information.  Commands available are: chdir, compare_files, copy,
+  copy_directory, copy_if_different, echo, echo_append, environment,
+  make_directory, md5sum, remove, remove_directory, rename, tar, time,
+  touch, touch_nocreate.  In addition, some platform specific commands
+  are available.  On Windows: comspec, delete_regv, write_regv.  On
+  UNIX: create_symlink.
+
+* ``-i``: Run in wizard mode.
+
+  Wizard mode runs cmake interactively without a GUI.  The user is
+  prompted to answer questions about the project configuration.  The
+  answers are used to set cmake cache values.
+
+* ``-L[A][H]``: List non-advanced cached variables.
+
+  List cache variables will run CMake and list all the variables from
+  the CMake cache that are not marked as INTERNAL or ADVANCED.  This
+  will effectively display current CMake settings, which can then be
+  changed with -D option.  Changing some of the variables may result
+  in more variables being created.  If A is specified, then it will
+  display also advanced variables.  If H is specified, it will also
+  display help for each variable.
+
+* ``--build <dir>``: Build a CMake-generated project binary tree.
+
+  This abstracts a native build tool's command-line interface with the
+  following options:
+
+  ::
+
+    <dir>          = Project binary directory to be built.
+    --target <tgt> = Build <tgt> instead of default targets.
+    --config <cfg> = For multi-configuration tools, choose <cfg>.
+    --clean-first  = Build target 'clean' first, then build.
+                     (To clean only, use --target 'clean'.)
+    --use-stderr   = Don't merge stdout/stderr output and pass the
+                     original stdout/stderr handles to the native
+                     tool so it can use the capabilities of the
+                     calling terminal (e.g. colored output).
+    --             = Pass remaining options to the native tool.
+
+  Run cmake --build with no options for quick help.
+
+* ``-N``: View mode only.
+
+  Only load the cache.  Do not actually run configure and generate
+  steps.
+
+* ``-P <file>``: Process script mode.
+
+  Process the given cmake file as a script written in the CMake
+  language.  No configure or generate step is performed and the cache
+  is not modified.  If variables are defined using -D, this must be
+  done before the -P argument.
+
+* ``--find-package``: Run in pkg-config like mode.
+
+  Search a package using find_package() and print the resulting flags
+  to stdout.  This can be used to use cmake instead of pkg-config to
+  find installed libraries in plain Makefile-based projects or in
+  autoconf-based projects (via share/aclocal/cmake.m4).
+
+* ``--graphviz=[file]``: Generate graphviz of dependencies, see CMakeGraphVizOptions.cmake for more.
+
+  Generate a graphviz input file that will contain all the library and
+  executable dependencies in the project.  See the documentation for
+  CMakeGraphVizOptions.cmake for more details.
+
+* ``--system-information [file]``: Dump information about this system.
+
+  Dump a wide range of information about the current system.  If run
+  from the top of a binary tree for a CMake project it will dump
+  additional information such as the cache, log files etc.
+
+* ``--debug-trycompile``: Do not delete the try_compile build tree. Only useful on one try_compile at a time.
+
+  Do not delete the files and directories created for try_compile
+  calls.  This is useful in debugging failed try_compiles.  It may
+  however change the results of the try-compiles as old junk from a
+  previous try-compile may cause a different test to either pass or
+  fail incorrectly.  This option is best used for one try-compile at a
+  time, and only when debugging.
+
+* ``--debug-output``: Put cmake in a debug mode.
+
+  Print extra stuff during the cmake run like stack traces with
+  message(send_error ) calls.
+
+* ``--trace``: Put cmake in trace mode.
+
+  Print a trace of all calls made and from where with
+  message(send_error ) calls.
+
+* ``--warn-uninitialized``: Warn about uninitialized values.
+
+  Print a warning when an uninitialized variable is used.
+
+* ``--warn-unused-vars``: Warn about unused variables.
+
+  Find variables that are declared or set, but not used.
+
+* ``--no-warn-unused-cli``: Don't warn about command line options.
+
+  Don't find variables that are declared on the command line, but not
+  used.
+
+* ``--check-system-vars``: Find problems with variable usage in system files.
+
+  Normally, unused and uninitialized variables are searched for only
+  in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR.  This flag tells CMake to
+  warn about other files as well.
+
+* ``--help-command cmd [file]``: Print help for a single command and exit.
+
+  Full documentation specific to the given command is displayed.  If a
+  file is specified, the documentation is written into and the output
+  format is determined depending on the filename suffix.  Supported
+  are man page, HTML, DocBook and plain text.
+
+* ``--help-command-list [file]``: List available listfile commands and exit.
+
+  The list contains all commands for which help may be obtained by
+  using the --help-command argument followed by a command name.  If a
+  file is specified, the documentation is written into and the output
+  format is determined depending on the filename suffix.  Supported
+  are man page, HTML, DocBook and plain text.
+
+* ``--help-commands [file]``: Print help for all commands and exit.
+
+  Full documentation specific for all current commands is displayed.If
+  a file is specified, the documentation is written into and the
+  output format is determined depending on the filename suffix.
+  Supported are man page, HTML, DocBook and plain text.
+
+* ``--help-compatcommands [file]``: Print help for compatibility commands.
+
+  Full documentation specific for all compatibility commands is
+  displayed.If a file is specified, the documentation is written into
+  and the output format is determined depending on the filename
+  suffix.  Supported are man page, HTML, DocBook and plain text.
+
+* ``--help-module module [file]``: Print help for a single module and exit.
+
+  Full documentation specific to the given module is displayed.If a
+  file is specified, the documentation is written into and the output
+  format is determined depending on the filename suffix.  Supported
+  are man page, HTML, DocBook and plain text.
+
+* ``--help-module-list [file]``: List available modules and exit.
+
+  The list contains all modules for which help may be obtained by
+  using the --help-module argument followed by a module name.  If a
+  file is specified, the documentation is written into and the output
+  format is determined depending on the filename suffix.  Supported
+  are man page, HTML, DocBook and plain text.
+
+* ``--help-modules [file]``: Print help for all modules and exit.
+
+  Full documentation for all modules is displayed.  If a file is
+  specified, the documentation is written into and the output format
+  is determined depending on the filename suffix.  Supported are man
+  page, HTML, DocBook and plain text.
+
+* ``--help-custom-modules [file]``: Print help for all custom modules and exit.
+
+  Full documentation for all custom modules is displayed.  If a file
+  is specified, the documentation is written into and the output
+  format is determined depending on the filename suffix.  Supported
+  are man page, HTML, DocBook and plain text.
+
+* ``--help-policy cmp [file]``: Print help for a single policy and exit.
+
+  Full documentation specific to the given policy is displayed.If a
+  file is specified, the documentation is written into and the output
+  format is determined depending on the filename suffix.  Supported
+  are man page, HTML, DocBook and plain text.
+
+* ``--help-policy-list [file]``: List available policies and exit.
+
+  The list contains all policies for which help may be obtained by
+  using the --help-policy argument followed by a policy name.  If a
+  file is specified, the documentation is written into and the output
+  format is determined depending on the filename suffix.  Supported
+  are man page, HTML, DocBook and plain text.
+
+* ``--help-policies [file]``: Print help for all policies and exit.
+
+  Full documentation for all policies is displayed.If a file is
+  specified, the documentation is written into and the output format
+  is determined depending on the filename suffix.  Supported are man
+  page, HTML, DocBook and plain text.
+
+* ``--help-property prop [file]``: Print help for a single property and exit.
+
+  Full documentation specific to the given property is displayed.If a
+  file is specified, the documentation is written into and the output
+  format is determined depending on the filename suffix.  Supported
+  are man page, HTML, DocBook and plain text.
+
+* ``--help-property-list [file]``: List available properties and exit.
+
+  The list contains all properties for which help may be obtained by
+  using the --help-property argument followed by a property name.  If
+  a file is specified, the help is written into it.If a file is
+  specified, the documentation is written into and the output format
+  is determined depending on the filename suffix.  Supported are man
+  page, HTML, DocBook and plain text.
+
+* ``--help-properties [file]``: Print help for all properties and exit.
+
+  Full documentation for all properties is displayed.If a file is
+  specified, the documentation is written into and the output format
+  is determined depending on the filename suffix.  Supported are man
+  page, HTML, DocBook and plain text.
+
+* ``--help-variable var [file]``: Print help for a single variable and exit.
+
+  Full documentation specific to the given variable is displayed.If a
+  file is specified, the documentation is written into and the output
+  format is determined depending on the filename suffix.  Supported
+  are man page, HTML, DocBook and plain text.
+
+* ``--help-variable-list [file]``: List documented variables and exit.
+
+  The list contains all variables for which help may be obtained by
+  using the --help-variable argument followed by a variable name.  If
+  a file is specified, the help is written into it.If a file is
+  specified, the documentation is written into and the output format
+  is determined depending on the filename suffix.  Supported are man
+  page, HTML, DocBook and plain text.
+
+* ``--help-variables [file]``: Print help for all variables and exit.
+
+  Full documentation for all variables is displayed.If a file is
+  specified, the documentation is written into and the output format
+  is determined depending on the filename suffix.  Supported are man
+  page, HTML, DocBook and plain text.
+
+* ``--copyright [file]``: Print the CMake copyright and exit.
+
+  If a file is specified, the copyright is written into it.
+
+* ``--help,-help,-usage,-h,-H,/?``: Print usage information and exit.
+
+  Usage describes the basic command line interface and its options.
+
+* ``--help-full [file]``: Print full help and exit.
+
+  Full help displays most of the documentation provided by the UNIX
+  man page.  It is provided for use on non-UNIX platforms, but is also
+  convenient if the man page is not installed.  If a file is
+  specified, the help is written into it.
+
+* ``--help-html [file]``: Print full help in HTML format.
+
+  This option is used by CMake authors to help produce web pages.  If
+  a file is specified, the help is written into it.
+
+* ``--help-man [file]``: Print full help as a UNIX man page and exit.
+
+  This option is used by the cmake build to generate the UNIX man
+  page.  If a file is specified, the help is written into it.
+
+* ``--version,-version,/V [file]``: Show program name/version banner and exit.
+
+  If a file is specified, the version is written into it.
+The following generators are available on this platform:
+
+::
+
+  CMake Properties - Properties supported by CMake, the Cross-Platform Makefile Generator.
+
+This is the documentation for the properties supported by CMake.
+Properties can have different scopes.  They can either be assigned to
+a source file, a directory, a target or globally to CMake.  By
+modifying the values of properties the behaviour of the build system
+can be customized.
+
+::
+
+  CMake Compatibility Listfile Commands - Obsolete commands supported by CMake for compatibility.
+
+This is the documentation for now obsolete listfile commands from
+previous CMake versions, which are still supported for compatibility
+reasons.  You should instead use the newer, faster and shinier new
+commands.  ;-)
+
+The following modules are provided with CMake.  They can be used with
+INCLUDE(ModuleName).
+
+::
+
+  CMake Modules - Modules coming with CMake, the Cross-Platform Makefile Generator.
+
+This is the documentation for the modules and scripts coming with
+CMake.  Using these modules you can check the computer system for
+installed software packages, features of the compiler and the
+existence of headers to name just a few.
+
+variables defined by cmake, that give information about the project,
+and cmake
+
+Copyright 2000-2012 Kitware, Inc., Insight Software Consortium.  All
+rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+Neither the names of Kitware, Inc., the Insight Software Consortium,
+nor the names of their contributors may be used to endorse or promote
+products derived from this software without specific prior written
+permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The following resources are available to get help using CMake:
+
+
+* ``Home Page``: http://www.cmake.org
+
+  The primary starting point for learning about CMake.
+
+* ``Frequently Asked Questions``: http://www.cmake.org/Wiki/CMake_FAQ
+
+  A Wiki is provided containing answers to frequently asked questions.
+
+* ``Online Documentation``: http://www.cmake.org/HTML/Documentation.html
+
+  Links to available documentation may be found on this web page.
+
+* ``Mailing List``: http://www.cmake.org/HTML/MailingLists.html
+
+  For help and discussion about using cmake, a mailing list is
+  provided at cmake@cmake.org.  The list is member-post-only but one
+  may sign up on the CMake web page.  Please first read the full
+  documentation at http://www.cmake.org before posting questions to
+  the list.