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, 164 insertions, 135 deletions

diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake
index 0781ea1..d734012 100644
--- a/Modules/ExternalProject.cmake
+++ b/Modules/ExternalProject.cmake
@@ -1,163 +1,192 @@
-# - Create custom targets to build projects in external trees
+#.rst:
+# ExternalProject
+# ---------------
+#
+# Create custom targets to build projects in external trees
+#
 # The 'ExternalProject_Add' function creates a custom target to drive
 # download, update/patch, configure, build, install and test steps of an
 # external project:
-#  ExternalProject_Add(<name>    # Name for custom target
-#    [DEPENDS projects...]       # Targets on which the project depends
-#    [PREFIX dir]                # Root dir for entire project
-#    [LIST_SEPARATOR sep]        # Sep to be replaced by ; in cmd lines
-#    [TMP_DIR dir]               # Directory to store temporary files
-#    [STAMP_DIR dir]             # Directory to store step timestamps
-#   #--Download step--------------
-#    [DOWNLOAD_NAME fname]       # File name to store (if not end of URL)
-#    [DOWNLOAD_DIR dir]          # Directory to store downloaded files
-#    [DOWNLOAD_COMMAND cmd...]   # Command to download source tree
-#    [CVS_REPOSITORY cvsroot]    # CVSROOT of CVS repository
-#    [CVS_MODULE mod]            # Module to checkout from CVS repo
-#    [CVS_TAG tag]               # Tag to checkout from CVS repo
-#    [SVN_REPOSITORY url]        # URL of Subversion repo
-#    [SVN_REVISION rev]          # Revision to checkout from Subversion repo
-#    [SVN_USERNAME john ]        # Username for Subversion checkout and update
-#    [SVN_PASSWORD doe ]         # Password for Subversion checkout and update
-#    [SVN_TRUST_CERT 1 ]         # Trust the Subversion server site certificate
-#    [GIT_REPOSITORY url]        # URL of git repo
-#    [GIT_TAG tag]               # Git branch name, commit id or tag
-#    [HG_REPOSITORY url]         # URL of mercurial repo
-#    [HG_TAG tag]                # Mercurial branch name, commit id or tag
-#    [URL /.../src.tgz]          # Full path or URL of source
-#    [URL_HASH ALGO=value]       # Hash of file at URL
-#    [URL_MD5 md5]               # Equivalent to URL_HASH MD5=md5
-#    [TLS_VERIFY bool]           # Should certificate for https be checked
-#    [TLS_CAINFO file]           # Path to a certificate authority file
-#    [TIMEOUT seconds]           # Time allowed for file download operations
-#   #--Update/Patch step----------
-#    [UPDATE_COMMAND cmd...]     # Source work-tree update command
-#    [PATCH_COMMAND cmd...]      # Command to patch downloaded source
-#   #--Configure step-------------
-#    [SOURCE_DIR dir]            # Source dir to be used for build
-#    [CONFIGURE_COMMAND cmd...]  # Build tree configuration command
-#    [CMAKE_COMMAND /.../cmake]  # Specify alternative cmake executable
-#    [CMAKE_GENERATOR gen]       # Specify generator for native build
-#    [CMAKE_GENERATOR_TOOLSET t] # Generator-specific toolset name
-#    [CMAKE_ARGS args...]        # Arguments to CMake command line
-#    [CMAKE_CACHE_ARGS args...]  # Initial cache arguments, of the form -Dvar:string=on
-#   #--Build step-----------------
-#    [BINARY_DIR dir]            # Specify build dir location
-#    [BUILD_COMMAND cmd...]      # Command to drive the native build
-#    [BUILD_IN_SOURCE 1]         # Use source dir for build dir
-#   #--Install step---------------
-#    [INSTALL_DIR dir]           # Installation prefix
-#    [INSTALL_COMMAND cmd...]    # Command to drive install after build
-#   #--Test step------------------
-#    [TEST_BEFORE_INSTALL 1]     # Add test step executed before install step
-#    [TEST_AFTER_INSTALL 1]      # Add test step executed after install step
-#    [TEST_COMMAND cmd...]       # Command to drive test
-#   #--Output logging-------------
-#    [LOG_DOWNLOAD 1]            # Wrap download in script to log output
-#    [LOG_UPDATE 1]              # Wrap update in script to log output
-#    [LOG_CONFIGURE 1]           # Wrap configure in script to log output
-#    [LOG_BUILD 1]               # Wrap build in script to log output
-#    [LOG_TEST 1]                # Wrap test in script to log output
-#    [LOG_INSTALL 1]             # Wrap install in script to log output
-#   #--Custom targets-------------
-#    [STEP_TARGETS st1 st2 ...]  # Generate custom targets for these steps
-#    )
+#
+# ::
+#
+#   ExternalProject_Add(<name>    # Name for custom target
+#     [DEPENDS projects...]       # Targets on which the project depends
+#     [PREFIX dir]                # Root dir for entire project
+#     [LIST_SEPARATOR sep]        # Sep to be replaced by ; in cmd lines
+#     [TMP_DIR dir]               # Directory to store temporary files
+#     [STAMP_DIR dir]             # Directory to store step timestamps
+#    #--Download step--------------
+#     [DOWNLOAD_NAME fname]       # File name to store (if not end of URL)
+#     [DOWNLOAD_DIR dir]          # Directory to store downloaded files
+#     [DOWNLOAD_COMMAND cmd...]   # Command to download source tree
+#     [CVS_REPOSITORY cvsroot]    # CVSROOT of CVS repository
+#     [CVS_MODULE mod]            # Module to checkout from CVS repo
+#     [CVS_TAG tag]               # Tag to checkout from CVS repo
+#     [SVN_REPOSITORY url]        # URL of Subversion repo
+#     [SVN_REVISION rev]          # Revision to checkout from Subversion repo
+#     [SVN_USERNAME john ]        # Username for Subversion checkout and update
+#     [SVN_PASSWORD doe ]         # Password for Subversion checkout and update
+#     [SVN_TRUST_CERT 1 ]         # Trust the Subversion server site certificate
+#     [GIT_REPOSITORY url]        # URL of git repo
+#     [GIT_TAG tag]               # Git branch name, commit id or tag
+#     [HG_REPOSITORY url]         # URL of mercurial repo
+#     [HG_TAG tag]                # Mercurial branch name, commit id or tag
+#     [URL /.../src.tgz]          # Full path or URL of source
+#     [URL_HASH ALGO=value]       # Hash of file at URL
+#     [URL_MD5 md5]               # Equivalent to URL_HASH MD5=md5
+#     [TLS_VERIFY bool]           # Should certificate for https be checked
+#     [TLS_CAINFO file]           # Path to a certificate authority file
+#     [TIMEOUT seconds]           # Time allowed for file download operations
+#    #--Update/Patch step----------
+#     [UPDATE_COMMAND cmd...]     # Source work-tree update command
+#     [PATCH_COMMAND cmd...]      # Command to patch downloaded source
+#    #--Configure step-------------
+#     [SOURCE_DIR dir]            # Source dir to be used for build
+#     [CONFIGURE_COMMAND cmd...]  # Build tree configuration command
+#     [CMAKE_COMMAND /.../cmake]  # Specify alternative cmake executable
+#     [CMAKE_GENERATOR gen]       # Specify generator for native build
+#     [CMAKE_GENERATOR_TOOLSET t] # Generator-specific toolset name
+#     [CMAKE_ARGS args...]        # Arguments to CMake command line
+#     [CMAKE_CACHE_ARGS args...]  # Initial cache arguments, of the form -Dvar:string=on
+#    #--Build step-----------------
+#     [BINARY_DIR dir]            # Specify build dir location
+#     [BUILD_COMMAND cmd...]      # Command to drive the native build
+#     [BUILD_IN_SOURCE 1]         # Use source dir for build dir
+#    #--Install step---------------
+#     [INSTALL_DIR dir]           # Installation prefix
+#     [INSTALL_COMMAND cmd...]    # Command to drive install after build
+#    #--Test step------------------
+#     [TEST_BEFORE_INSTALL 1]     # Add test step executed before install step
+#     [TEST_AFTER_INSTALL 1]      # Add test step executed after install step
+#     [TEST_COMMAND cmd...]       # Command to drive test
+#    #--Output logging-------------
+#     [LOG_DOWNLOAD 1]            # Wrap download in script to log output
+#     [LOG_UPDATE 1]              # Wrap update in script to log output
+#     [LOG_CONFIGURE 1]           # Wrap configure in script to log output
+#     [LOG_BUILD 1]               # Wrap build in script to log output
+#     [LOG_TEST 1]                # Wrap test in script to log output
+#     [LOG_INSTALL 1]             # Wrap install in script to log output
+#    #--Custom targets-------------
+#     [STEP_TARGETS st1 st2 ...]  # Generate custom targets for these steps
+#     )
+#
 # The *_DIR options specify directories for the project, with default
-# directories computed as follows.
-# If the PREFIX option is given to ExternalProject_Add() or the EP_PREFIX
-# directory property is set, then an external project is built and installed
-# under the specified prefix:
-#   TMP_DIR      = <prefix>/tmp
-#   STAMP_DIR    = <prefix>/src/<name>-stamp
-#   DOWNLOAD_DIR = <prefix>/src
-#   SOURCE_DIR   = <prefix>/src/<name>
-#   BINARY_DIR   = <prefix>/src/<name>-build
-#   INSTALL_DIR  = <prefix>
-# Otherwise, if the EP_BASE directory property is set then components
-# of an external project are stored under the specified base:
-#   TMP_DIR      = <base>/tmp/<name>
-#   STAMP_DIR    = <base>/Stamp/<name>
-#   DOWNLOAD_DIR = <base>/Download/<name>
-#   SOURCE_DIR   = <base>/Source/<name>
-#   BINARY_DIR   = <base>/Build/<name>
-#   INSTALL_DIR  = <base>/Install/<name>
-# If no PREFIX, EP_PREFIX, or EP_BASE is specified then the default
-# is to set PREFIX to "<name>-prefix".
-# Relative paths are interpreted with respect to the build directory
-# corresponding to the source directory in which ExternalProject_Add is
-# invoked.
+# directories computed as follows.  If the PREFIX option is given to
+# ExternalProject_Add() or the EP_PREFIX directory property is set, then
+# an external project is built and installed under the specified prefix:
+#
+# ::
+#
+#    TMP_DIR      = <prefix>/tmp
+#    STAMP_DIR    = <prefix>/src/<name>-stamp
+#    DOWNLOAD_DIR = <prefix>/src
+#    SOURCE_DIR   = <prefix>/src/<name>
+#    BINARY_DIR   = <prefix>/src/<name>-build
+#    INSTALL_DIR  = <prefix>
+#
+# Otherwise, if the EP_BASE directory property is set then components of
+# an external project are stored under the specified base:
+#
+# ::
+#
+#    TMP_DIR      = <base>/tmp/<name>
+#    STAMP_DIR    = <base>/Stamp/<name>
+#    DOWNLOAD_DIR = <base>/Download/<name>
+#    SOURCE_DIR   = <base>/Source/<name>
+#    BINARY_DIR   = <base>/Build/<name>
+#    INSTALL_DIR  = <base>/Install/<name>
+#
+# If no PREFIX, EP_PREFIX, or EP_BASE is specified then the default is
+# to set PREFIX to "<name>-prefix".  Relative paths are interpreted with
+# respect to the build directory corresponding to the source directory
+# in which ExternalProject_Add is invoked.
 #
 # If SOURCE_DIR is explicitly set to an existing directory the project
-# will be built from it.
-# Otherwise a download step must be specified using one of the
-# DOWNLOAD_COMMAND, CVS_*, SVN_*, or URL options.
-# The URL option may refer locally to a directory or source tarball,
-# or refer to a remote tarball (e.g. http://.../src.tgz).
+# will be built from it.  Otherwise a download step must be specified
+# using one of the DOWNLOAD_COMMAND, CVS_*, SVN_*, or URL options.  The
+# URL option may refer locally to a directory or source tarball, or
+# refer to a remote tarball (e.g.  http://.../src.tgz).
+#
+# The 'ExternalProject_Add_Step' function adds a custom step to an
+# external project:
 #
-# The 'ExternalProject_Add_Step' function adds a custom step to an external
-# project:
-#  ExternalProject_Add_Step(<name> <step> # Names of project and custom step
-#    [COMMAND cmd...]        # Command line invoked by this step
-#    [COMMENT "text..."]     # Text printed when step executes
-#    [DEPENDEES steps...]    # Steps on which this step depends
-#    [DEPENDERS steps...]    # Steps that depend on this step
-#    [DEPENDS files...]      # Files on which this step depends
-#    [ALWAYS 1]              # No stamp file, step always runs
-#    [WORKING_DIRECTORY dir] # Working directory for command
-#    [LOG 1]                 # Wrap step in script to log output
-#    )
-# The command line, comment, and working directory of every standard
-# and custom step is processed to replace tokens
-# <SOURCE_DIR>,
-# <BINARY_DIR>,
-# <INSTALL_DIR>,
-# and <TMP_DIR>
-# with corresponding property values.
+# ::
+#
+#   ExternalProject_Add_Step(<name> <step> # Names of project and custom step
+#     [COMMAND cmd...]        # Command line invoked by this step
+#     [COMMENT "text..."]     # Text printed when step executes
+#     [DEPENDEES steps...]    # Steps on which this step depends
+#     [DEPENDERS steps...]    # Steps that depend on this step
+#     [DEPENDS files...]      # Files on which this step depends
+#     [ALWAYS 1]              # No stamp file, step always runs
+#     [WORKING_DIRECTORY dir] # Working directory for command
+#     [LOG 1]                 # Wrap step in script to log output
+#     )
+#
+# The command line, comment, and working directory of every standard and
+# custom step is processed to replace tokens <SOURCE_DIR>, <BINARY_DIR>,
+# <INSTALL_DIR>, and <TMP_DIR> with corresponding property values.
 #
 # Any builtin step that specifies a "<step>_COMMAND cmd..." or custom
 # step that specifies a "COMMAND cmd..." may specify additional command
-# lines using the form "COMMAND cmd...".  At build time the commands will
-# be executed in order and aborted if any one fails.  For example:
-#  ... BUILD_COMMAND make COMMAND echo done ...
+# lines using the form "COMMAND cmd...".  At build time the commands
+# will be executed in order and aborted if any one fails.  For example:
+#
+# ::
+#
+#   ... BUILD_COMMAND make COMMAND echo done ...
+#
 # specifies to run "make" and then "echo done" during the build step.
-# Whether the current working directory is preserved between commands
-# is not defined.  Behavior of shell operators like "&&" is not defined.
+# Whether the current working directory is preserved between commands is
+# not defined.  Behavior of shell operators like "&&" is not defined.
 #
 # The 'ExternalProject_Get_Property' function retrieves external project
 # target properties:
-#  ExternalProject_Get_Property(<name> [prop1 [prop2 [...]]])
-# It stores property values in variables of the same name.
-# Property names correspond to the keyword argument names of
+#
+# ::
+#
+#   ExternalProject_Get_Property(<name> [prop1 [prop2 [...]]])
+#
+# It stores property values in variables of the same name.  Property
+# names correspond to the keyword argument names of
 # 'ExternalProject_Add'.
 #
-# The 'ExternalProject_Add_StepTargets' function generates custom targets for
-# the steps listed:
-#  ExternalProject_Add_StepTargets(<name> [step1 [step2 [...]]])
+# The 'ExternalProject_Add_StepTargets' function generates custom
+# targets for the steps listed:
+#
+# ::
+#
+#   ExternalProject_Add_StepTargets(<name> [step1 [step2 [...]]])
 #
-# If STEP_TARGETS is set then ExternalProject_Add_StepTargets is automatically
-# called at the end of matching calls to ExternalProject_Add_Step. Pass
-# STEP_TARGETS explicitly to individual ExternalProject_Add calls, or
-# implicitly to all ExternalProject_Add calls by setting the directory property
-# EP_STEP_TARGETS.
+#
+#
+# If STEP_TARGETS is set then ExternalProject_Add_StepTargets is
+# automatically called at the end of matching calls to
+# ExternalProject_Add_Step.  Pass STEP_TARGETS explicitly to individual
+# ExternalProject_Add calls, or implicitly to all ExternalProject_Add
+# calls by setting the directory property EP_STEP_TARGETS.
 #
 # If STEP_TARGETS is not set, clients may still manually call
 # ExternalProject_Add_StepTargets after calling ExternalProject_Add or
 # ExternalProject_Add_Step.
 #
 # This functionality is provided to make it easy to drive the steps
-# independently of each other by specifying targets on build command lines.
-# For example, you may be submitting to a sub-project based dashboard, where
-# you want to drive the configure portion of the build, then submit to the
-# dashboard, followed by the build portion, followed by tests. If you invoke
-# a custom target that depends on a step halfway through the step dependency
-# chain, then all the previous steps will also run to ensure everything is
-# up to date.
+# independently of each other by specifying targets on build command
+# lines.  For example, you may be submitting to a sub-project based
+# dashboard, where you want to drive the configure portion of the build,
+# then submit to the dashboard, followed by the build portion, followed
+# by tests.  If you invoke a custom target that depends on a step
+# halfway through the step dependency chain, then all the previous steps
+# will also run to ensure everything is up to date.
+#
+# For example, to drive configure, build and test steps independently
+# for each ExternalProject_Add call in your project, write the following
+# line prior to any ExternalProject_Add calls in your CMakeLists file:
 #
-# For example, to drive configure, build and test steps independently for each
-# ExternalProject_Add call in your project, write the following line prior to
-# any ExternalProject_Add calls in your CMakeLists file:
+# ::
 #
-#   set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test)
+#    set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test)
 
 #=============================================================================
 # Copyright 2008-2012 Kitware, Inc.