ExternalProject: Convert docs to a bracket comment

Use a bracket comment to hold the documentation instead of a block of
line comments.  This will make further updates easier.  Also fix the
logic that parses options out of the documentation to be aware of the
new layout.

Modules/ExternalProject.cmake

@@ -1,187 +1,188 @@
-#.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:
-#
-# .. code-block:: cmake
-#
-#  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
-#    [EXCLUDE_FROM_ALL 1]        # The "all" target does not depend on this
-#   #--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
-#    [DOWNLOAD_NO_PROGRESS 1]    # Disable download progress reports
-#    [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 -r<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
-#    [GIT_SUBMODULES modules...] # Git submodules that shall be updated, all if empty
-#    [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_PLATFORM p] # Generator-specific platform name
-#    [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
-#    [BUILD_ALWAYS 1]            # No stamp file, build step always runs
-#   #--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.
-#
-# 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``).
-#
-# The ``ExternalProject_Add_Step`` function adds a custom step to an
-# external project:
-#
-# .. code-block:: cmake
-#
-#  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
-#    [EXCLUDE_FROM_MAIN 1]   # Main target does not depend on this step
-#    [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 ...
-#
-# 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.
-#
-# 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_Add``.
-#
-# 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 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.
-#
-# 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.txt``
-# file::
-#
-#  set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test)
+#[=======================================================================[.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:
+
+.. code-block:: cmake
+
+ 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
+   [EXCLUDE_FROM_ALL 1]        # The "all" target does not depend on this
+  #--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
+   [DOWNLOAD_NO_PROGRESS 1]    # Disable download progress reports
+   [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 -r<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
+   [GIT_SUBMODULES modules...] # Git submodules that shall be updated, all if empty
+   [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_PLATFORM p] # Generator-specific platform name
+   [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
+   [BUILD_ALWAYS 1]            # No stamp file, build step always runs
+  #--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.
+
+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``).
+
+The ``ExternalProject_Add_Step`` function adds a custom step to an
+external project:
+
+.. code-block:: cmake
+
+ 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
+   [EXCLUDE_FROM_MAIN 1]   # Main target does not depend on this step
+   [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 ...
+
+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.
+
+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_Add``.
+
+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 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.
+
+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.txt``
+file::
+
+ set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test)
+#]=======================================================================]
 
 #=============================================================================
 # Copyright 2008-2013 Kitware, Inc.
@@ -200,9 +201,9 @@
 math(EXPR _ep_documentation_line_count "${CMAKE_CURRENT_LIST_LINE} - 16")
 file(STRINGS "${CMAKE_CURRENT_LIST_FILE}" lines
      LIMIT_COUNT ${_ep_documentation_line_count}
-     REGEX "^#  (  \\[[A-Z0-9_]+ [^]]*\\] +#.*$|[A-Za-z0-9_]+\\()")
+     REGEX "^ (  \\[[A-Z0-9_]+ [^]]*\\] +#.*$|[A-Za-z0-9_]+\\()")
 foreach(line IN LISTS lines)
-  if("${line}" MATCHES "^#  ([A-Za-z0-9_]+)\\(")
+  if("${line}" MATCHES "^ ([A-Za-z0-9_]+)\\(")
     if(_ep_func)
       set(_ep_keywords_${_ep_func} "${_ep_keywords_${_ep_func}})$")
     endif()
@@ -211,7 +212,7 @@ foreach(line IN LISTS lines)
     set(_ep_keywords_${_ep_func} "^(")
     set(_ep_keyword_sep)
   else()
-    string(REGEX REPLACE "^#    \\[([A-Z0-9_]+) .*" "\\1" _ep_key "${line}")
+    string(REGEX REPLACE "^   \\[([A-Z0-9_]+) .*" "\\1" _ep_key "${line}")
     #message("  keyword [${_ep_key}]")
     set(_ep_keywords_${_ep_func}
       "${_ep_keywords_${_ep_func}}${_ep_keyword_sep}${_ep_key}")