From 9d3aa95ca4c20d9eb47e8a588c9279c6f37bb4a9 Mon Sep 17 00:00:00 2001
From: Betsy McPhail <betsy.mcphail@kitware.com>
Date: Wed, 8 Nov 2017 12:18:56 -0500
Subject: [PATCH] Help: Divide ctest(1) manual options into sections

---
 Help/manual/ctest.1.rst | 207 +++++++++++++++++++++++-----------------
 1 file changed, 117 insertions(+), 90 deletions(-)

diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst
index d586e222a6..0a6b1dd347 100644
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -3,12 +3,18 @@
 ctest(1)
 ********
 
+.. contents::
+
 Synopsis
 ========
 
 .. parsed-literal::
 
  ctest [<options>]
+ ctest <path-to-source> <path-to-build> --build-generator <generator>
+       [<options>...] [-- <build-options>...] [--test-command <test>]
+ ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>)
+       [-- <dashboard-options>...]
 
 Description
 ===========
@@ -142,6 +148,8 @@ Options
  Experimental, Nightly, and Continuous, and Test can be Start,
  Update, Configure, Build, Test, Coverage, and Submit.
 
+ See `Dashboard Client`_.
+
 ``-D <var>:<type>=<value>``
  Define a variable for script mode.
 
@@ -157,6 +165,8 @@ Options
  can be ``Experimental``, ``Nightly``, and ``Continuous``.
  Combining ``-M`` and ``-T`` is similar to ``-D``.
 
+ See `Dashboard Client`_.
+
 ``-T <action>, --test-action <action>``
  Sets the dashboard action to perform.
 
@@ -165,13 +175,7 @@ Options
  `Dashboard Client Steps`_ for the full list of actions.
  Combining ``-M`` and ``-T`` is similar to ``-D``.
 
-``--track <track>``
- Specify the track to submit dashboard to
-
- Submit dashboard to specified track instead of default one.  By
- default, the dashboard is submitted to Nightly, Experimental, or
- Continuous track, but by specifying this option, the track can be
- arbitrary.
+ See `Dashboard Client`_.
 
 ``-S <script>, --script <script>``
  Execute a dashboard for a configuration.
@@ -182,6 +186,8 @@ Options
  This option basically sets up a dashboard and then runs ``ctest -D``
  with the appropriate options.
 
+ See `Dashboard Client`_.
+
 ``-SP <script>, --script-new-process <script>``
  Execute a dashboard for a configuration.
 
@@ -190,11 +196,7 @@ Options
  script may modify the environment and you do not want the modified
  environment to impact other ``-S`` scripts.
 
-``-A <file>, --add-notes <file>``
- Add a notes file with submission.
-
- This option tells ctest to include a notes file when submitting
- dashboard.
+ See `Dashboard Client`_.
 
 ``-I [Start,End,Stride,test#,test#|Test file], --tests-information``
  Run a specific number of tests by number.
@@ -250,32 +252,88 @@ Options
  label associated with the tests run.  If there are no labels on the
  tests, nothing extra is printed.
 
- ``--no-subproject-summary``
+``--no-subproject-summary``
  Disable timing summary information for subprojects.
 
  This option tells ctest not to print summary information for each
  subproject associated with the tests run.  If there are no subprojects on the
  tests, nothing extra is printed.
 
-``--build-and-test <path-to-source> <path-to-build>``
- Configure, build and run a test.
+``--build-and-test``
+See `Build and Test Mode`_.
 
- This option tells ctest to configure (i.e.  run cmake on), build,
- and or execute a test.  The configure and test steps are optional.
- The arguments to this command line are the source and binary
- directories.
- The ``--build-generator`` option *must* be provided to use
- ``--build-and-test``.  If ``--test-command`` is specified then that will be
- run after the build is complete.  Other options that affect this
- mode are ``--build-target``, ``--build-nocmake``, ``--build-run-dir``,
- ``--build-two-config``, ``--build-exe-dir``,
- ``--build-project``, ``--build-noclean`` and ``--build-options``.
+``--test-output-size-passed <size>``
+ Limit the output for passed tests to ``<size>`` bytes.
+
+``--test-output-size-failed <size>``
+ Limit the output for failed tests to ``<size>`` bytes.
+
+``--overwrite``
+ Overwrite CTest configuration option.
+
+ By default ctest uses configuration options from configuration file.
+ This option will overwrite the configuration option.
+
+``--force-new-ctest-process``
+ Run child CTest instances as new processes.
+
+ By default CTest will run child CTest instances within the same
+ process.  If this behavior is not desired, this argument will
+ enforce new processes for child CTest processes.
+
+``--schedule-random``
+ Use a random order for scheduling tests.
+
+ This option will run the tests in a random order.  It is commonly
+ used to detect implicit dependencies in a test suite.
+
+``--submit-index``
+ Legacy option for old Dart2 dashboard server feature.
+ Do not use.
+
+``--timeout <seconds>``
+ Set a global timeout on all tests.
+
+ This option will set a global timeout on all tests that do not
+ already have a timeout set on them.
+
+``--stop-time <time>``
+ Set a time at which all tests should stop running.
+
+ Set a real time of day at which all tests should timeout.  Example:
+ ``7:00:00 -0400``.  Any time format understood by the curl date parser
+ is accepted.  Local time is assumed if no timezone is specified.
+
+``--print-labels``
+ Print all available test labels.
+
+ This option will not run any tests, it will simply print the list of
+ all labels associated with the test set.
+
+.. include:: OPTIONS_HELP.txt
+
+.. _`Build and Test Mode`:
+
+Build and Test Mode
+===================
+
+CTest provides a command-line signature to to configure (i.e.  run cmake on),
+build, and or execute a test::
+
+  ctest --build-and-test <path-to-source> <path-to-build>
+        --build-generator <generator> [<options>...] [-- <build-options>...]
+        [--test-command <test>]
+
+The configure and test steps are optional. The arguments to this command line
+are the source and binary directories. The ``--build-generator`` option *must*
+be provided to use ``--build-and-test``.  If ``--test-command`` is specified
+then that will be run after the build is complete.  Other options that affect
+this mode include:
 
 ``--build-target``
  Specify a specific target to build.
 
- This option goes with the ``--build-and-test`` option, if left out the
- ``all`` target is built.
+ If left out the ``all`` target is built.
 
 ``--build-nocmake``
  Run the build without running cmake first.
@@ -324,61 +382,48 @@ Options
 ``--test-command``
  The test to run with the ``--build-and-test`` option.
 
-``--test-output-size-passed <size>``
- Limit the output for passed tests to ``<size>`` bytes.
-
-``--test-output-size-failed <size>``
- Limit the output for failed tests to ``<size>`` bytes.
-
 ``--test-timeout``
- The time limit in seconds, internal use only.
+ The time limit in seconds
+
+.. _`Dashboard Client`:
+
+Dashboard Client
+================
+
+CTest can operate as a client for the `CDash`_ software quality dashboard
+application.  As a dashboard client, CTest performs a sequence of steps
+to configure, build, and test software, and then submits the results to
+a `CDash`_ server. The command-line signature used to submit to `CDash`_ is::
+
+  ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>)
+        [-- <dashboard-options>...]
+
+Options for Dashboard Client include:
+
+``--track <track>``
+ Specify the track to submit dashboard to
+
+ Submit dashboard to specified track instead of default one.  By
+ default, the dashboard is submitted to Nightly, Experimental, or
+ Continuous track, but by specifying this option, the track can be
+ arbitrary.
+
+``-A <file>, --add-notes <file>``
+ Add a notes file with submission.
+
+ This option tells ctest to include a notes file when submitting
+ dashboard.
 
 ``--tomorrow-tag``
  Nightly or experimental starts with next day tag.
 
  This is useful if the build will not finish in one day.
 
-``--overwrite``
- Overwrite CTest configuration option.
-
- By default ctest uses configuration options from configuration file.
- This option will overwrite the configuration option.
-
 ``--extra-submit <file>[;<file>]``
  Submit extra files to the dashboard.
 
  This option will submit extra files to the dashboard.
 
-``--force-new-ctest-process``
- Run child CTest instances as new processes.
-
- By default CTest will run child CTest instances within the same
- process.  If this behavior is not desired, this argument will
- enforce new processes for child CTest processes.
-
-``--schedule-random``
- Use a random order for scheduling tests.
-
- This option will run the tests in a random order.  It is commonly
- used to detect implicit dependencies in a test suite.
-
-``--submit-index``
- Legacy option for old Dart2 dashboard server feature.
- Do not use.
-
-``--timeout <seconds>``
- Set a global timeout on all tests.
-
- This option will set a global timeout on all tests that do not
- already have a timeout set on them.
-
-``--stop-time <time>``
- Set a time at which all tests should stop running.
-
- Set a real time of day at which all tests should timeout.  Example:
- ``7:00:00 -0400``.  Any time format understood by the curl date parser
- is accepted.  Local time is assumed if no timezone is specified.
-
 ``--http1.0``
  Submit using HTTP 1.0.
 
@@ -392,26 +437,6 @@ Options
  this to maintain compatibility with an older version of CDash which
  doesn't support compressed test output.
 
-``--print-labels``
- Print all available test labels.
-
- This option will not run any tests, it will simply print the list of
- all labels associated with the test set.
-
-.. include:: OPTIONS_HELP.txt
-
-.. _`Dashboard Client`:
-
-Dashboard Client
-================
-
-CTest can operate as a client for the `CDash`_ software quality dashboard
-application.  As a dashboard client, CTest performs a sequence of steps
-to configure, build, and test software, and then submits the results to
-a `CDash`_ server.
-
-.. _`CDash`: http://cdash.org/
-
 Dashboard Client Steps
 ----------------------
 
@@ -1075,3 +1100,5 @@ See Also
 ========
 
 .. include:: LINKS.txt
+
+.. _`CDash`: http://cdash.org/