ExternalProject: Format module documentation

Manually revise the .rst format of the documentation.  Use inline
literal quotes appropriately in paragraph text.  Move the :: literal
block openers to the end of the preceding paragraphs.  Convert the
command signature documentation and examples to cmake code-block
directives.

1 files changed, 59 insertions, 70 deletions

diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake
index 84fa613..63f1180 100644
--- a/Modules/ExternalProject.cmake
+++ b/Modules/ExternalProject.cmake
@@ -4,11 +4,11 @@
 #
 # Create custom targets to build projects in external trees
 #
-# The 'ExternalProject_Add' function creates a custom target to drive
+# 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
@@ -72,46 +72,42 @@
 #    )
 #
 # 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:
+# 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>
 #
-#    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::
 #
-# 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.
 #
-#    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
+# 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).
+# 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
+# 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
@@ -125,51 +121,45 @@
 #    )
 #
 # 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.
+# 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:
+# 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 ...
 #
-#   ... BUILD_COMMAND make COMMAND echo done ...
-#
-# specifies to run "make" and then "echo done" during the build step.
+# 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:
+# 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 [...]]])
+#  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'.
+# ``ExternalProject_Add``.
 #
-# The 'ExternalProject_Add_StepTargets' function generates custom
-# targets for the steps listed:
+# The ``ExternalProject_Add_StepTargets`` function generates custom
+# targets for the steps listed::
 #
-# ::
+#  ExternalProject_Add_StepTargets(<name> [step1 [step2 [...]]])
 #
-#   ExternalProject_Add_StepTargets(<name> [step1 [step2 [...]]])
-#
-#
-#
-# If STEP_TARGETS is set then ExternalProject_Add_StepTargets is
+# 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.
+# ``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.
+# 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
@@ -181,15 +171,14 @@
 # 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 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)
+#  set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test)
 
 #=============================================================================
-# Copyright 2008-2012 Kitware, Inc.
+# Copyright 2008-2013 Kitware, Inc.
 #
 # Distributed under the OSI-approved BSD License (the "License");
 # see accompanying file Copyright.txt for details.