ctest_start: read model from TAG file

This change reworks ctest_start() so that simply calling
ctest_start(APPEND) will read all the information from the TAG file.
On top of that, it relaxes the argument parsing for ctest_start() to
allow greater flexibility in the argument ordering, and the documentation
for ctest_start() has been cleaned up.

1 files changed, 73 insertions, 16 deletions

diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst
index 63db32f..6db9a48 100644
--- a/Help/command/ctest_start.rst
+++ b/Help/command/ctest_start.rst
@@ -5,21 +5,78 @@ Starts the testing for a given model
 
 ::
 
-  ctest_start(Model [TRACK <track>] [APPEND] [source [binary]] [QUIET])
+  ctest_start(<model> [<source> [<binary>]] [TRACK <track>] [QUIET])
+
+  ctest_start([<model> [<source> [<binary>]]] [TRACK <track>] APPEND [QUIET])
 
 Starts the testing for a given model.  The command should be called
-after the binary directory is initialized.  If the 'source' and
-'binary' directory are not specified, it reads the
-:variable:`CTEST_SOURCE_DIRECTORY` and :variable:`CTEST_BINARY_DIRECTORY`.
-If the track is
-specified, the submissions will go to the specified track.  If APPEND
-is used, the existing TAG is used rather than creating a new one based
-on the current time stamp.  If ``QUIET`` is used, CTest will suppress any
-non-error messages that it otherwise would have printed to the console.
-
-If the :variable:`CTEST_CHECKOUT_COMMAND` variable
-(or the :variable:`CTEST_CVS_CHECKOUT` variable)
-is set, its content is treated as command-line.  The command is
-invoked with the current working directory set to the parent of the source
-directory, even if the source directory already exists.  This can be used
-to create the source tree from a version control repository.
+after the binary directory is initialized.
+
+The parameters are as follows:
+
+``<model>``
+  Set the dashboard model. Must be one of ``Experimental``, ``Continuous``, or
+  ``Nightly``. This parameter is required unless ``APPEND`` is specified.
+
+``<source>``
+  Set the source directory. If not specified, the value of
+  :variable:`CTEST_SOURCE_DIRECTORY` is used instead.
+
+``<binary>``
+  Set the binary directory. If not specified, the value of
+  :variable:`CTEST_BINARY_DIRECTORY` is used instead.
+
+``TRACK <track>``
+  If ``TRACK`` is used, the submissions will go to the specified track on the
+  CDash server. If no ``TRACK`` is specified, the name of the model is used by
+  default.
+
+``APPEND``
+  If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new
+  one based on the current time stamp. If you use ``APPEND``, you can omit the
+  ``<model>`` and ``TRACK <track>`` parameters, because they will be read from
+  the generated ``TAG`` file. For example:
+
+  .. code-block:: cmake
+
+    ctest_start(Experimental TRACK TrackExperimental)
+
+  Later, in another ``ctest -S`` script:
+
+  .. code-block:: cmake
+
+    ctest_start(APPEND)
+
+  When the second script runs ``ctest_start(APPEND)``, it will read the
+  ``Experimental`` model and ``TrackExperimental`` track from the ``TAG`` file
+  generated by the first ``ctest_start()`` command. Please note that if you
+  call ``ctest_start(APPEND)`` and specify a different model or track than
+  in the first ``ctest_start()`` command, a warning will be issued, and the
+  new model and track will be used.
+
+``QUIET``
+  If ``QUIET`` is used, CTest will suppress any non-error messages that it
+  otherwise would have printed to the console.
+
+The parameters for ``ctest_start()`` can be issued in any order, with the
+exception that ``<model>``, ``<source>``, and ``<binary>`` have to appear
+in that order with respect to each other. The following are all valid and
+equivalent:
+
+.. code-block:: cmake
+
+  ctest_start(Experimental path/to/source path/to/binary TRACK SomeTrack QUIET APPEND)
+
+  ctest_start(TRACK SomeTrack Experimental QUIET path/to/source APPEND path/to/binary)
+
+  ctest_start(APPEND QUIET Experimental path/to/source TRACK SomeTrack path/to/binary)
+
+However, for the sake of readability, it is recommended that you order your
+parameters in the order listed at the top of this page.
+
+If the :variable:`CTEST_CHECKOUT_COMMAND` variable (or the
+:variable:`CTEST_CVS_CHECKOUT` variable) is set, its content is treated as
+command-line.  The command is invoked with the current working directory set
+to the parent of the source directory, even if the source directory already
+exists.  This can be used to create the source tree from a version control
+repository.