Help/ctest: Improve formatting of dashboard options

We must differentiate between the `ctest -D` dashboard and `ctest -D` variable options.
2026-09-25 04:09:36 +03:00 · 2026-06-02 13:49:16 -04:00
parent bd870ef98f
commit 1bc30bd30d
64 changed files with 79 additions and 78 deletions
@@ -457,7 +457,7 @@ The options for running tests are:

 Specify the directory in which to look for tests, typically a CMake project
 build directory. If not specified, the current directory is used.
- See also :ctest-option:`--build-dir`.
+ See also :ctest-dashboard-option:`--build-dir`.

 .. option:: --test-output-size-passed <size>

@@ -856,7 +856,7 @@ Options for Dashboard Client include:

 The available ``<dashboard-options>`` are the following:

-.. _`ctest-option-D-var`:
+.. program:: ctest-dashboard

 .. option:: -D <var>:<type>=<value>, -D <var>=<value>

@@ -888,13 +888,13 @@ The available ``<dashboard-options>`` are the following:
 Specify the project source directory. When combined with
 :option:`-T Configure <ctest -T>`, this allows CTest to perform an initial
 configure step for an empty binary directory.  The binary directory defaults
- to the current working directory; use :ctest-option:`--build-dir` to specify
- a different location. The binary directory is created automatically if it
- does not yet exist.
+ to the current working directory; use :ctest-dashboard-option:`--build-dir` to
+ specify a different location. The binary directory is created automatically
+ if it does not yet exist.

 A CMake generator must also be specified. Use
- :cref:`-D CTEST_CMAKE_GENERATOR=\<gen\> <ctest-option-D-var>` to supply one, or
- set :variable:`CTEST_CONFIGURE_PRESET` to specify a
+ :option:`-D CTEST_CMAKE_GENERATOR=\<gen\> <ctest-dashboard -D>` to supply one,
+ or set :variable:`CTEST_CONFIGURE_PRESET` to specify a
 :manual:`configure preset <cmake-presets(7)>` that includes a
 :preset:`generator <configurePresets.generator>`.

@@ -906,7 +906,7 @@ The available ``<dashboard-options>`` are the following:

 Specify the project binary (build) directory. This is an alias for
 :ctest-option:`--test-dir` intended for use with
- :ctest-option:`--source-dir` when bootstrapping a build with
+ :ctest-dashboard-option:`--source-dir` when bootstrapping a build with
 :option:`-T Configure <ctest -T>`.

 .. option:: --group <group>
@@ -1043,9 +1043,9 @@ to the build tree and use one of these signatures::
  ctest -D <mode>[<step>]
  ctest -M <mode> [-T <step>]...

-The :ctest-option:`--source-dir` option additionally allows the
+The :ctest-dashboard-option:`--source-dir` option additionally allows the
 ``Configure`` step to be performed on a build tree that does not yet
-exist, in which case the :ctest-option:`--build-dir` option specifies
+exist, in which case the :ctest-dashboard-option:`--build-dir` option specifies
 where to create it::

  ctest [-M <mode>] -T Configure
@@ -133,7 +133,7 @@ Modules
 CTest
 -----

-* :manual:`ctest(1)` gained a :option:`--http-header <ctest --http-header>`
+* :manual:`ctest(1)` gained a :ctest-dashboard-option:`--http-header`
  option to add custom headers on submission to CDash.

 * :manual:`ctest(1)` gained the :option:`--tests-from-file <ctest
@@ -11,7 +11,7 @@ ctest-script-preset-arg
  :variable:`CTEST_PRESETS_FILE` variables may be used to specify preset
  arguments to the above commands in a :ref:`Dashboard Client` script or
  on the :program:`ctest` command line via the
-  :ref:`-D <ctest-option-D-var>` option.
+  :ctest-dashboard-option:`-D` option.

 * When a preset is selected for :command:`ctest_configure` or
  :command:`ctest_build`, the :variable:`CTEST_CONFIGURE_COMMAND` and
@@ -5,4 +5,4 @@ CTEST_BINARY_DIRECTORY

 Specify the CTest ``BuildDirectory`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_BUILD_COMMAND

 Specify the CTest ``MakeCommand`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_BUILD_NAME

 Specify the CTest ``BuildName`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,6 +5,6 @@ CTEST_BUILD_PRESET

 Specify the ``PRESET`` option for the :command:`ctest_build` command
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.

 See also :variable:`CTEST_PRESET` and :variable:`CTEST_PRESETS_FILE`.
@@ -5,4 +5,4 @@ CTEST_BZR_COMMAND

 Specify the CTest ``BZRCommand`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_BZR_UPDATE_OPTIONS

 Specify the CTest ``BZRUpdateOptions`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,7 +5,7 @@ CTEST_CHANGE_ID

 Specify the CTest ``ChangeId`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.

 This setting allows CTest to pass arbitrary information about this
 build up to CDash.  One use of this feature is to allow CDash to
@@ -5,4 +5,4 @@ CTEST_CHECKOUT_COMMAND

 Tell the :command:`ctest_start` command how to checkout or initialize
 the source directory in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_CONFIGURE_COMMAND

 Specify the CTest ``ConfigureCommand`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,6 +5,6 @@ CTEST_CONFIGURE_PRESET

 Specify the ``PRESET`` option for the :command:`ctest_configure` command
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.

 See also :variable:`CTEST_PRESET` and :variable:`CTEST_PRESETS_FILE`.
@@ -5,7 +5,7 @@ CTEST_COVERAGE_COMMAND

 Specify the CTest ``CoverageCommand`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.

 Cobertura
 '''''''''
@@ -5,4 +5,4 @@ CTEST_COVERAGE_EXTRA_FLAGS

 Specify the CTest ``CoverageExtraFlags`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -9,4 +9,4 @@ CTEST_CURL_OPTIONS

 Specify the CTest ``CurlOptions`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_CVS_COMMAND

 Specify the CTest ``CVSCommand`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_CVS_UPDATE_OPTIONS

 Specify the CTest ``CVSUpdateOptions`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_DROP_LOCATION

 Specify the CTest ``DropLocation`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_DROP_METHOD

 Specify the CTest ``DropMethod`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_DROP_SITE

 Specify the CTest ``DropSite`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_DROP_SITE_PASSWORD

 Specify the CTest ``DropSitePassword`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_DROP_SITE_USER

 Specify the CTest ``DropSiteUser`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -3,4 +3,4 @@ CTEST_EXTRA_SUBMIT_FILES

 Specify files for :command:`ctest_submit(PARTS ExtraFiles)` to submit
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_GIT_COMMAND

 Specify the CTest ``GITCommand`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_GIT_INIT_SUBMODULES

 Specify the CTest ``GITInitSubmodules`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_GIT_UPDATE_CUSTOM

 Specify the CTest ``GITUpdateCustom`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_GIT_UPDATE_OPTIONS

 Specify the CTest ``GITUpdateOptions`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_HG_COMMAND

 Specify the CTest ``HGCommand`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_HG_UPDATE_OPTIONS

 Specify the CTest ``HGUpdateOptions`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_LABELS_FOR_SUBPROJECTS

 Specify the CTest ``LabelsForSubprojects`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_MEMORYCHECK_COMMAND

 Specify the CTest ``MemoryCheckCommand`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_MEMORYCHECK_COMMAND_OPTIONS

 Specify the CTest ``MemoryCheckCommandOptions`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,7 +5,7 @@ CTEST_MEMORYCHECK_SANITIZER_OPTIONS

 Specify the CTest ``MemoryCheckSanitizerOptions`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.

 CTest prepends correct sanitizer options ``*_OPTIONS``
 environment variable to executed command. CTests adds
@@ -5,4 +5,4 @@ CTEST_MEMORYCHECK_SUPPRESSIONS_FILE

 Specify the CTest ``MemoryCheckSuppressionFile`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,7 +5,7 @@ CTEST_MEMORYCHECK_TYPE

 Specify the CTest ``MemoryCheckType`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
 Valid values are ``Valgrind``, ``Purify``, ``BoundsChecker``, ``DrMemory``,
 ``CudaSanitizer``, ``ThreadSanitizer``, ``AddressSanitizer``, ``LeakSanitizer``,
 ``MemorySanitizer`` and ``UndefinedBehaviorSanitizer``.
@@ -5,7 +5,7 @@ CTEST_NIGHTLY_START_TIME

 Specify the CTest ``NightlyStartTime`` setting in a :manual:`ctest(1)`
 :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.

 Note that this variable must always be set for a nightly build in a
 dashboard script. It is needed so that nightly builds can be properly grouped
@@ -3,4 +3,4 @@ CTEST_NOTES_FILES

 Specify files for :command:`ctest_submit(PARTS Notes)` to submit
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_P4_CLIENT

 Specify the CTest ``P4Client`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_P4_COMMAND

 Specify the CTest ``P4Command`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_P4_OPTIONS

 Specify the CTest ``P4Options`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_P4_UPDATE_OPTIONS

 Specify the CTest ``P4UpdateOptions`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,7 +5,7 @@ CTEST_PRESET

 Specify a preset name to use for all relevant :manual:`ctest(1)`
 :ref:`Dashboard Client` steps in a dashboard script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.

 This variable sets the ``PRESET`` option for :command:`ctest_configure`,
 :command:`ctest_build`, :command:`ctest_test`, and :command:`ctest_memcheck`
@@ -5,7 +5,7 @@ CTEST_PRESETS_FILE

 Specify the ``PRESETS_FILE`` option for all relevant :manual:`ctest(1)`
 :ref:`Dashboard Client` step commands in a dashboard script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.

 This variable sets the ``PRESETS_FILE`` option for
 :command:`ctest_configure`, :command:`ctest_build`, :command:`ctest_test`,
@@ -5,7 +5,7 @@ CTEST_RESOURCE_SPEC_FILE

 Specify the CTest ``ResourceSpecFile`` setting in a :manual:`ctest(1)`
 :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.

 This can also be used to specify the resource spec file from a CMake build. If
 no ``RESOURCE_SPEC_FILE`` is passed to :command:`ctest_test`, and
@@ -5,4 +5,4 @@ CTEST_SITE

 Specify the CTest ``Site`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_SOURCE_DIRECTORY

 Specify the CTest ``SourceDirectory`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_SUBMIT_INACTIVITY_TIMEOUT

 Specify the CTest ``SubmitInactivityTimeout`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_SUBMIT_URL

 Specify the CTest ``SubmitURL`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_SVN_COMMAND

 Specify the CTest ``SVNCommand`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_SVN_OPTIONS

 Specify the CTest ``SVNOptions`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_SVN_UPDATE_OPTIONS

 Specify the CTest ``SVNUpdateOptions`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_TEST_COVERAGE_TOOL

 Specify the CTest :ref:`CoverageTool <ctest-CoverageTool>` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,6 +5,6 @@ CTEST_TEST_LOAD

 Specify the ``TestLoad`` setting in the :ref:`CTest Test Step`
 of a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.  This sets the
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.  This sets the
 default value for the ``TEST_LOAD`` option of the :command:`ctest_test`
 command.
@@ -6,6 +6,6 @@ CTEST_TEST_PRESET
 Specify the ``PRESET`` option for the :command:`ctest_test` and
 :command:`ctest_memcheck` commands in a :manual:`ctest(1)`
 :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.

 See also :variable:`CTEST_PRESET` and :variable:`CTEST_PRESETS_FILE`.
@@ -5,4 +5,4 @@ CTEST_TEST_TIMEOUT

 Specify the CTest ``TimeOut`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -6,7 +6,7 @@ CTEST_TLS_VERIFY
 Specify the CTest ``TLSVerify`` setting in a :manual:`ctest(1)`
 :ref:`Dashboard Client` script or in project ``CMakeLists.txt`` code
 before including the :module:`CTest` module, or on the :program:`ctest`
-command line via the :ref:`-D <ctest-option-D-var>` option.  The value is a boolean
+command line via the :ctest-dashboard-option:`-D` option.  The value is a boolean
 indicating whether to  verify the server certificate when submitting
 to a dashboard via ``https://`` URLs.

@@ -6,7 +6,7 @@ CTEST_TLS_VERSION
 Specify the CTest ``TLSVersion`` setting in a :manual:`ctest(1)`
 :ref:`Dashboard Client` script or in project ``CMakeLists.txt`` code
 before including the :module:`CTest` module, or on the :program:`ctest`
-command line via the :ref:`-D <ctest-option-D-var>` option.  The value is a minimum
+command line via the :ctest-dashboard-option:`-D` option.  The value is a minimum
 TLS version allowed when submitting to a dashboard via ``https://`` URLs.

 The value may be one of:
@@ -5,4 +5,4 @@ CTEST_UPDATE_COMMAND

 Specify the CTest ``UpdateCommand`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_UPDATE_OPTIONS

 Specify the CTest ``UpdateOptions`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_UPDATE_VERSION_ONLY

 Specify the CTest :ref:`UpdateVersionOnly <UpdateVersionOnly>` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_UPDATE_VERSION_OVERRIDE

 Specify the CTest :ref:`UpdateVersionOverride <UpdateVersionOverride>` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -5,4 +5,4 @@ CTEST_USE_LAUNCHERS

 Specify the CTest ``UseLaunchers`` setting
 in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
-or on the :program:`ctest` command line via the :ref:`-D <ctest-option-D-var>` option.
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
@@ -806,12 +806,13 @@ class CMakeDomain(Domain):
        'preset':     CMakeXRefRole(lowercase=True, warn_dangling=True),
        # Roles for program-specific command-line options without the program
        # name (which add the name to form the ref).
-        'cmake-option':          CMakeOptionXRefRole('cmake'),
-        'cmake-build-option':    CMakeOptionXRefRole('cmake--build'),
-        'cmake-install-option':  CMakeOptionXRefRole('cmake--install'),
-        'cmake-workflow-option': CMakeOptionXRefRole('cmake--workflow'),
-        'cpack-option':          CMakeOptionXRefRole('cpack'),
-        'ctest-option':          CMakeOptionXRefRole('ctest'),
+        'cmake-option':           CMakeOptionXRefRole('cmake'),
+        'cmake-build-option':     CMakeOptionXRefRole('cmake--build'),
+        'cmake-install-option':   CMakeOptionXRefRole('cmake--install'),
+        'cmake-workflow-option':  CMakeOptionXRefRole('cmake--workflow'),
+        'cpack-option':           CMakeOptionXRefRole('cpack'),
+        'ctest-dashboard-option': CMakeOptionXRefRole('ctest-dashboard'),
+        'ctest-option':           CMakeOptionXRefRole('ctest'),
    }
    initial_data = {
        'objects': {},  # fullname -> ObjectEntry