Merge topic 'doc-cmake-cli-options'

0224576995 Help: Replace `cmake -P` option mentions w/ Sphinx role
1b94770f27 Help: Insert link to `cmake --toolchain` option
2c54cd871a Help: Turn items of presets manual page into description list
e2198fd9dc Help: Format `-Werror`/`-Wno-error` in the way it can be referenced
a6070b480f Help: Use placeholder instead of listing choices in option lines
8ba20cb56f Help: Simplify `cmake --log-level` option definition
146e4e6bad Help: Split `ctest` options into groups like `cmake` man page has
4c1008d739 Help: Use `:option:` role to reference `ctest` options
...

Acked-by: Kitware Robot <[email protected]>
Merge-request: !7554

Help/manual/OPTIONS_BUILD.txt

@@ -109,20 +109,6 @@
  Enable warnings that are meant for the author of the ``CMakeLists.txt``
  files. By default this will also turn on deprecation warnings.
 
-.. option:: -Werror=dev
-
- Make developer warnings errors.
-
- Make warnings that are meant for the author of the ``CMakeLists.txt`` files
- errors. By default this will also turn on deprecated warnings as errors.
-
-.. option:: -Wno-error=dev
-
- Make developer warnings not errors.
-
- Make warnings that are meant for the author of the ``CMakeLists.txt`` files not
- errors. By default this will also turn off deprecated warnings as errors.
-
 .. option:: -Wdeprecated
 
  Enable deprecated functionality warnings.
@@ -137,16 +123,30 @@
  Suppress warnings for usage of deprecated functionality, that are meant
  for the author of the ``CMakeLists.txt`` files.
 
-.. option:: -Werror=deprecated
+.. option:: -Werror=<what>
+
+ Treat CMake warnings as errors. ``<what>`` must be one of the following:
+
+ ``dev``
+   Make developer warnings errors.
+
+   Make warnings that are meant for the author of the ``CMakeLists.txt`` files
+   errors. By default this will also turn on deprecated warnings as errors.
+
+ ``deprecated``
+  Make deprecated macro and function warnings errors.
 
- Make deprecated macro and function warnings errors.
+  Make warnings for usage of deprecated macros and functions, that are meant
+  for the author of the ``CMakeLists.txt`` files, errors.
 
- Make warnings for usage of deprecated macros and functions, that are meant
- for the author of the ``CMakeLists.txt`` files, errors.
+.. option:: -Wno-error=<what>
 
-.. option:: -Wno-error=deprecated
+ Do not treat CMake warnings as errors. ``<what>`` must be one of the following:
 
- Make deprecated macro and function warnings not errors.
+ ``dev``
+  Make warnings that are meant for the author of the ``CMakeLists.txt`` files not
+  errors. By default this will also turn off deprecated warnings as errors.
 
- Make warnings for usage of deprecated macros and functions, that are meant
- for the author of the ``CMakeLists.txt`` files, not errors.
+ ``deprecated``
+  Make warnings for usage of deprecated macros and functions, that are meant
+  for the author of the ``CMakeLists.txt`` files, not errors.

Help/manual/OPTIONS_HELP.txt

@@ -1,33 +1,31 @@
-.. |file| replace:: The help is printed to a named <f>ile if given.
+.. |file| replace:: The output is printed to a named ``<file>`` if given.
 
-.. option:: --help, -help, -usage, -h, -H, /?
+.. option:: -version [<file>], --version [<file>], /V [<file>]
 
- Print usage information and exit.
-
- Usage describes the basic command line interface and its options.
+ Show program name/version banner and exit.
+ |file|
 
-.. option:: --version, -version, /V [<f>]
+.. option:: -h, -H, --help, -help, -usage, /?
 
- Show program name/version banner and exit.
+ Print usage information and exit.
 
- If a file is specified, the version is written into it.
- |file|
+ Usage describes the basic command line interface and its options.
 
-.. option:: --help-full [<f>]
+.. option:: --help-full [<file>]
 
  Print all help manuals and exit.
 
  All manuals are printed in a human-readable text format.
  |file|
 
-.. option:: --help-manual <man> [<f>]
+.. option:: --help-manual <man> [<file>]
 
  Print one help manual and exit.
 
  The specified manual is printed in a human-readable text format.
  |file|
 
-.. option:: --help-manual-list [<f>]
+.. option:: --help-manual-list [<file>]
 
  List help manuals available and exit.
 
@@ -35,7 +33,7 @@
  using the ``--help-manual`` option followed by a manual name.
  |file|
 
-.. option:: --help-command <cmd> [<f>]
+.. option:: --help-command <cmd> [<file>]
 
  Print help for one command and exit.
 
@@ -43,7 +41,7 @@
  printed in a human-readable text format.
  |file|
 
-.. option:: --help-command-list [<f>]
+.. option:: --help-command-list [<file>]
 
  List commands with help available and exit.
 
@@ -51,7 +49,7 @@
  using the ``--help-command`` option followed by a command name.
  |file|
 
-.. option:: --help-commands [<f>]
+.. option:: --help-commands [<file>]
 
  Print cmake-commands manual and exit.
 
@@ -59,7 +57,7 @@
  human-readable text format.
  |file|
 
-.. option:: --help-module <mod> [<f>]
+.. option:: --help-module <mod> [<file>]
 
  Print help for one module and exit.
 
@@ -67,7 +65,7 @@
  in a human-readable text format.
  |file|
 
-.. option:: --help-module-list [<f>]
+.. option:: --help-module-list [<file>]
 
  List modules with help available and exit.
 
@@ -75,7 +73,7 @@
  using the ``--help-module`` option followed by a module name.
  |file|
 
-.. option:: --help-modules [<f>]
+.. option:: --help-modules [<file>]
 
  Print cmake-modules manual and exit.
 
@@ -83,7 +81,7 @@
  text format.
  |file|
 
-.. option:: --help-policy <cmp> [<f>]
+.. option:: --help-policy <cmp> [<file>]
 
  Print help for one policy and exit.
 
@@ -91,7 +89,7 @@
  printed in a human-readable text format.
  |file|
 
-.. option:: --help-policy-list [<f>]
+.. option:: --help-policy-list [<file>]
 
  List policies with help available and exit.
 
@@ -99,7 +97,7 @@
  using the ``--help-policy`` option followed by a policy name.
  |file|
 
-.. option:: --help-policies [<f>]
+.. option:: --help-policies [<file>]
 
  Print cmake-policies manual and exit.
 
@@ -107,7 +105,7 @@
  human-readable text format.
  |file|
 
-.. option:: --help-property <prop> [<f>]
+.. option:: --help-property <prop> [<file>]
 
  Print help for one property and exit.
 
@@ -115,7 +113,7 @@
  printed in a human-readable text format.
  |file|
 
-.. option:: --help-property-list [<f>]
+.. option:: --help-property-list [<file>]
 
  List properties with help available and exit.
 
@@ -123,7 +121,7 @@
  using the ``--help-property`` option followed by a property name.
  |file|
 
-.. option:: --help-properties [<f>]
+.. option:: --help-properties [<file>]
 
  Print cmake-properties manual and exit.
 
@@ -131,7 +129,7 @@
  human-readable text format.
  |file|
 
-.. option:: --help-variable <var> [<f>]
+.. option:: --help-variable <var> [<file>]
 
  Print help for one variable and exit.
 
@@ -139,7 +137,7 @@
  printed in a human-readable text format.
  |file|
 
-.. option:: --help-variable-list [<f>]
+.. option:: --help-variable-list [<file>]
 
  List variables with help available and exit.
 
@@ -147,7 +145,7 @@
  using the ``--help-variable`` option followed by a variable name.
  |file|
 
-.. option:: --help-variables [<f>]
+.. option:: --help-variables [<file>]
 
  Print cmake-variables manual and exit.
 

Help/manual/ccmake.1.rst

@@ -8,7 +8,7 @@ Synopsis
 
 .. parsed-literal::
 
- ccmake [<options>] {<path-to-source> | <path-to-existing-build>}
+ ccmake [<options>] <path-to-source | path-to-existing-build>
 
 Description
 ===========

Help/manual/cmake-gui.1.rst

@@ -9,7 +9,7 @@ Synopsis
 .. parsed-literal::
 
  cmake-gui [<options>]
- cmake-gui [<options>] {<path-to-source> | <path-to-existing-build>}
+ cmake-gui [<options>] <path-to-source | path-to-existing-build>
  cmake-gui [<options>] -S <path-to-source> -B <path-to-build>
  cmake-gui [<options>] --browse-manual
 

Help/manual/cmake-presets.7.rst

@@ -40,7 +40,6 @@ The files are a JSON document with an object as the root:
 The root object recognizes the following fields:
 
 ``version``
-
   A required integer representing the version of the JSON schema.
   The supported versions are:
 
@@ -60,31 +59,25 @@ The root object recognizes the following fields:
     .. versionadded:: 3.24
 
 ``cmakeMinimumRequired``
-
   An optional object representing the minimum version of CMake needed to
   build this project. This object consists of the following fields:
 
   ``major``
-
     An optional integer representing the major version.
 
   ``minor``
-
     An optional integer representing the minor version.
 
   ``patch``
-
     An optional integer representing the patch version.
 
 ``include``
-
   An optional array of strings representing files to include. If the filenames
   are not absolute, they are considered relative to the current file.
   This is allowed in preset files specifying version ``4`` or above.
   See `Includes`_ for discussion of the constraints on included files.
 
 ``vendor``
-
   An optional map containing vendor-specific information. CMake does not
   interpret the contents of this field except to verify that it is a map if
   it does exist. However, the keys should be a vendor-specific domain name
@@ -93,17 +86,14 @@ The root object recognizes the following fields:
   desired by the vendor, though will typically be a map.
 
 ``configurePresets``
-
   An optional array of `Configure Preset`_ objects.
   This is allowed in preset files specifying version ``1`` or above.
 
 ``buildPresets``
-
   An optional array of `Build Preset`_ objects.
   This is allowed in preset files specifying version ``2`` or above.
 
 ``testPresets``
-
   An optional array of `Test Preset`_ objects.
   This is allowed in preset files specifying version ``2`` or above.
 
@@ -134,7 +124,6 @@ Each entry of the ``configurePresets`` array is a JSON object
 that may contain the following fields:
 
 ``name``
-
   A required string representing the machine-friendly name of the preset.
   This identifier is used in the :ref:`cmake --preset <CMake Options>` option.
   There must not be two configure presets in the union of ``CMakePresets.json``
@@ -142,7 +131,6 @@ that may contain the following fields:
   However, a configure preset may have the same name as a build or test preset.
 
 ``hidden``
-
   An optional boolean specifying whether or not a preset should be hidden.
   If a preset is hidden, it cannot be used in the ``--preset=`` argument,
   will not show up in the :manual:`CMake GUI <cmake-gui(1)>`, and does not
@@ -151,7 +139,6 @@ that may contain the following fields:
   other presets to inherit via the ``inherits`` field.
 
 ``inherits``
-
   An optional array of strings representing the names of presets to inherit
   from. This field can also be a string, which is equivalent to an array
   containing one string.
@@ -169,12 +156,10 @@ that may contain the following fields:
   ``CMakeUserPresets.json``.
 
 ``condition``
-
   An optional `Condition`_ object. This is allowed in preset files specifying
   version ``3`` or above.
 
 ``vendor``
-
   An optional map containing vendor-specific information. CMake does not
   interpret the contents of this field except to verify that it is a map
   if it does exist. However, it should follow the same conventions as the
@@ -183,15 +168,12 @@ that may contain the following fields:
   when appropriate.
 
 ``displayName``
-
   An optional string with a human-friendly name of the preset.
 
 ``description``
-
   An optional string with a human-friendly description of the preset.
 
 ``generator``
-
   An optional string representing the generator to use for the preset. If
   ``generator`` is not specified, it must be inherited from the
   ``inherits`` preset (unless this preset is ``hidden``). In version ``3``
@@ -203,27 +185,22 @@ that may contain the following fields:
   in the generator name. Use the ``architecture`` field instead.
 
 ``architecture``, ``toolset``
-
   Optional fields representing the platform and toolset, respectively, for
   generators that support them. Each may be either a string or an object
   with the following fields:
 
   ``value``
-
     An optional string representing the value.
 
   ``strategy``
-
     An optional string telling CMake how to handle the ``architecture`` or
     ``toolset`` field. Valid values are:
 
     ``"set"``
-
       Set the respective value. This will result in an error for generators
       that do not support the respective field.
 
     ``"external"``
-
       Do not set the value, even if the generator supports it. This is
       useful if, for example, a preset uses the Ninja generator, and an IDE
       knows how to set up the Visual C++ environment from the
@@ -232,7 +209,6 @@ that may contain the following fields:
       before invoking CMake.
 
 ``toolchainFile``
-
   An optional string representing the path to the toolchain file.
   This field supports `macro expansion`_. If a relative path is specified,
   it is calculated relative to the build directory, and if not found,
@@ -241,7 +217,6 @@ that may contain the following fields:
   specifying version ``3`` or above.
 
 ``binaryDir``
-
   An optional string representing the path to the output binary directory.
   This field supports `macro expansion`_. If a relative path is specified,
   it is calculated relative to the source directory. If ``binaryDir`` is not
@@ -250,20 +225,17 @@ that may contain the following fields:
   omitted.
 
 ``installDir``
-
   An optional string representing the path to the installation directory.
   This field supports `macro expansion`_. If a relative path is specified,
   it is calculated relative to the source directory. This is allowed in
   preset files specifying version ``3`` or above.
 
 ``cmakeExecutable``
-
   An optional string representing the path to the CMake executable to use
   for this preset. This is reserved for use by IDEs, and is not used by
   CMake itself. IDEs that use this field should expand any macros in it.
 
 ``cacheVariables``
-
   An optional map of cache variables. The key is the variable name (which
   may not be an empty string), and the value is either ``null``, a boolean
   (which is equivalent to a value of ``"TRUE"`` or ``"FALSE"`` and a type
@@ -271,11 +243,9 @@ that may contain the following fields:
   supports `macro expansion`_), or an object with the following fields:
 
   ``type``
-
     An optional string representing the type of the variable.
 
   ``value``
-
     A required string or boolean representing the value of the variable.
     A boolean is equivalent to ``"TRUE"`` or ``"FALSE"``. This field
     supports `macro expansion`_.
@@ -288,7 +258,6 @@ that may contain the following fields:
   a value was inherited from another preset.
 
 ``environment``
-
   An optional map of environment variables. The key is the variable name
   (which may not be an empty string), and the value is either ``null`` or
   a string representing the value of the variable. Each variable is set
@@ -306,18 +275,15 @@ that may contain the following fields:
   a value was inherited from another preset.
 
 ``warnings``
-
   An optional object specifying the warnings to enable. The object may
   contain the following fields:
 
   ``dev``
-
     An optional boolean. Equivalent to passing :option:`-Wdev <cmake -Wdev>`
     or :option:`-Wno-dev <cmake -Wno-dev>` on the command line. This may not
     be set to ``false`` if ``errors.dev`` is set to ``true``.
 
   ``deprecated``
-
     An optional boolean. Equivalent to passing
     :option:`-Wdeprecated <cmake -Wdeprecated>` or
     :option:`-Wno-deprecated <cmake -Wno-deprecated>` on the command line.
@@ -325,58 +291,50 @@ that may contain the following fields:
     ``true``.
 
   ``uninitialized``
-
     An optional boolean. Setting this to ``true`` is equivalent to passing
     :option:`--warn-uninitialized <cmake --warn-uninitialized>` on the command
     line.
 
   ``unusedCli``
-
     An optional boolean. Setting this to ``false`` is equivalent to passing
     :option:`--no-warn-unused-cli <cmake --no-warn-unused-cli>` on the command
     line.
 
   ``systemVars``
-
     An optional boolean. Setting this to ``true`` is equivalent to passing
     :option:`--check-system-vars <cmake --check-system-vars>` on the command
     line.
 
 ``errors``
-
   An optional object specifying the errors to enable. The object may
   contain the following fields:
 
   ``dev``
-
-    An optional boolean. Equivalent to passing ``-Werror=dev`` or
-    ``-Wno-error=dev`` on the command line. This may not be set to ``true``
-    if ``warnings.dev`` is set to ``false``.
+    An optional boolean. Equivalent to passing :option:`-Werror=dev <cmake -Werror>`
+    or :option:`-Wno-error=dev <cmake -Werror>` on the command line.
+    This may not be set to ``true`` if ``warnings.dev`` is set to ``false``.
 
   ``deprecated``
-
-    An optional boolean. Equivalent to passing ``-Werror=deprecated`` or
-    ``-Wno-error=deprecated`` on the command line. This may not be set to
-    ``true`` if ``warnings.deprecated`` is set to ``false``.
+    An optional boolean. Equivalent to passing
+    :option:`-Werror=deprecated <cmake -Werror>` or
+    :option:`-Wno-error=deprecated <cmake -Werror>` on the command line.
+    This may not be set to ``true`` if ``warnings.deprecated`` is set to
+    ``false``.
 
 ``debug``
-
   An optional object specifying debug options. The object may contain the
   following fields:
 
   ``output``
-
     An optional boolean. Setting this to ``true`` is equivalent to passing
     :option:`--debug-output <cmake --debug-output>` on the command line.
 
   ``tryCompile``
-
     An optional boolean. Setting this to ``true`` is equivalent to passing
     :option:`--debug-trycompile <cmake --debug-trycompile>` on the command
     line.
 
   ``find``
-
     An optional boolean. Setting this to ``true`` is equivalent to passing
     :option:`--debug-find <cmake --debug-find>` on the command line.
 
@@ -387,7 +345,6 @@ Each entry of the ``buildPresets`` array is a JSON object
 that may contain the following fields:
 
 ``name``
-
   A required string representing the machine-friendly name of the preset.
   This identifier is used in the
   :ref:`cmake --build --preset <Build Tool Mode>` option.
@@ -396,7 +353,6 @@ that may contain the following fields:
   However, a build preset may have the same name as a configure or test preset.
 
 ``hidden``
-
   An optional boolean specifying whether or not a preset should be hidden.
   If a preset is hidden, it cannot be used in the
   :option:`--preset <cmake --preset>` argument
@@ -405,7 +361,6 @@ that may contain the following fields:
   other presets to inherit via the ``inherits`` field.
 
 ``inherits``
-
   An optional array of strings representing the names of presets to inherit
   from. This field can also be a string, which is equivalent to an array
   containing one string.
@@ -423,12 +378,10 @@ that may contain the following fields:
   ``CMakeUserPresets.json``.
 
 ``condition``
-
   An optional `Condition`_ object. This is allowed in preset files specifying
   version ``3`` or above.
 
 ``vendor``
-
   An optional map containing vendor-specific information. CMake does not
   interpret the contents of this field except to verify that it is a map
   if it does exist. However, it should follow the same conventions as the
@@ -437,15 +390,12 @@ that may contain the following fields:
   when appropriate.
 
 ``displayName``
-
   An optional string with a human-friendly name of the preset.
 
 ``description``
-
   An optional string with a human-friendly description of the preset.
 
 ``environment``
-
   An optional map of environment variables. The key is the variable name
   (which may not be an empty string), and the value is either ``null`` or
   a string representing the value of the variable. Each variable is set
@@ -476,7 +426,6 @@ that may contain the following fields:
     project.
 
 ``configurePreset``
-
   An optional string specifying the name of a configure preset to
   associate with this build preset. If ``configurePreset`` is not
   specified, it must be inherited from the inherits preset (unless this
@@ -485,36 +434,30 @@ that may contain the following fields:
   configuration did.
 
 ``inheritConfigureEnvironment``
-
   An optional boolean that defaults to true. If true, the environment
   variables from the associated configure preset are inherited after all
   inherited build preset environments, but before environment variables
   explicitly specified in this build preset.
 
 ``jobs``
-
   An optional integer. Equivalent to passing
   :option:`--parallel <cmake --parallel>` or ``-j`` on the command line.
 
 ``targets``
-
   An optional string or array of strings. Equivalent to passing
   :option:`--target <cmake --target>` or ``-t`` on the command line.
   Vendors may ignore the targets property or hide build presets that
   explicitly specify targets. This field supports macro expansion.
 
 ``configuration``
-
   An optional string. Equivalent to passing :option:`--config <cmake --config>`
   on the command line.
 
 ``cleanFirst``
-
   An optional bool. If true, equivalent to passing
   :option:`--clean-first <cmake --clean-first>` on the command line.
 
 ``resolvePackageReferences``
-
   An optional string that specifies the package resolve mode. This is
   allowed in preset files specifying version ``4`` or above.
 
@@ -524,16 +467,13 @@ that may contain the following fields:
   package references, this option does nothing. Valid values are:
 
   ``on``
-
     Causes package references to be resolved before attempting a build.
 
   ``off``
-
     Package references will not be resolved. Note that this may cause
     errors in some build environments, such as .NET SDK style projects.
 
   ``only``
-
     Only resolve package references, but do not perform a build.
 
   .. note::
@@ -552,12 +492,10 @@ that may contain the following fields:
     done from within a configure preset.
 
 ``verbose``
-
   An optional bool. If true, equivalent to passing
   :option:`--verbose <cmake --verbose>` on the command line.
 
 ``nativeToolOptions``
-
   An optional array of strings. Equivalent to passing options after ``--``
   on the command line. The array values support macro expansion.
 
@@ -568,15 +506,13 @@ Each entry of the ``testPresets`` array is a JSON object
 that may contain the following fields:
 
 ``name``
-
   A required string representing the machine-friendly name of the preset.
-  This identifier is used in the :ref:`ctest --preset <CTest Options>` option.
+  This identifier is used in the :option:`ctest --preset` option.
   There must not be two test presets in the union of ``CMakePresets.json``
   and ``CMakeUserPresets.json`` in the same directory with the same name.
   However, a test preset may have the same name as a configure or build preset.
 
 ``hidden``
-
   An optional boolean specifying whether or not a preset should be hidden.
   If a preset is hidden, it cannot be used in the
   :option:`--preset <ctest --preset>` argument
@@ -585,7 +521,6 @@ that may contain the following fields:
   other presets to inherit via the ``inherits`` field.
 
 ``inherits``
-
   An optional array of strings representing the names of presets to inherit
   from. This field can also be a string, which is equivalent to an array
   containing one string.
@@ -603,12 +538,10 @@ that may contain the following fields:
   ``CMakeUserPresets.json``.
 
 ``condition``
-
   An optional `Condition`_ object. This is allowed in preset files specifying
   version ``3`` or above.
 
 ``vendor``
-
   An optional map containing vendor-specific information. CMake does not
   interpret the contents of this field except to verify that it is a map
   if it does exist. However, it should follow the same conventions as the
@@ -617,15 +550,12 @@ that may contain the following fields:
   when appropriate.
 
 ``displayName``
-
   An optional string with a human-friendly name of the preset.
 
 ``description``
-
   An optional string with a human-friendly description of the preset.
 
 ``environment``
-
   An optional map of environment variables. The key is the variable name
   (which may not be an empty string), and the value is either ``null`` or
   a string representing the value of the variable. Each variable is set
@@ -643,7 +573,6 @@ that may contain the following fields:
   even if a value was inherited from another preset.
 
 ``configurePreset``
-
   An optional string specifying the name of a configure preset to
   associate with this test preset. If ``configurePreset`` is not
   specified, it must be inherited from the inherits preset (unless this
@@ -652,103 +581,85 @@ that may contain the following fields:
   configuration did and build did.
 
 ``inheritConfigureEnvironment``
-
   An optional boolean that defaults to true. If true, the environment
   variables from the associated configure preset are inherited after all
   inherited test preset environments, but before environment variables
   explicitly specified in this test preset.
 
 ``configuration``
-
   An optional string. Equivalent to passing
   :option:`--build-config <ctest --build-config>` on the command line.
 
 ``overwriteConfigurationFile``
-
   An optional array of configuration options to overwrite options
   specified in the CTest configuration file. Equivalent to passing
   :option:`--overwrite <ctest --overwrite>` for each value in the array.
   The array values support macro expansion.
 
 ``output``
-
   An optional object specifying output options. The object may contain the
   following fields.
 
   ``shortProgress``
-
     An optional bool. If true, equivalent to passing
     :option:`--progress <ctest --progress>` on the command line.
 
   ``verbosity``
-
     An optional string specifying verbosity level. Must be one of the
     following:
 
     ``default``
-
       Equivalent to passing no verbosity flags on the command line.
 
     ``verbose``
-
       Equivalent to passing :option:`--verbose <ctest --verbose>` on
       the command line.
 
     ``extra``
-
       Equivalent to passing :option:`--extra-verbose <ctest --extra-verbose>`
       on the command line.
 
   ``debug``
-
     An optional bool. If true, equivalent to passing
     :option:`--debug <ctest --debug>` on the command line.
 
   ``outputOnFailure``
-
     An optional bool. If true, equivalent to passing
     :option:`--output-on-failure <ctest --output-on-failure>` on the command
     line.
 
   ``quiet``
-
     An optional bool. If true, equivalent to passing
     :option:`--quiet <ctest --quiet>` on the command line.
 
   ``outputLogFile``
-
     An optional string specifying a path to a log file. Equivalent to
     passing :option:`--output-log <ctest --output-log>` on the command line.
     This field supports macro expansion.
 
   ``labelSummary``
-
     An optional bool. If false, equivalent to passing
     :option:`--no-label-summary <ctest --no-label-summary>` on the command
     line.
 
   ``subprojectSummary``
-
     An optional bool. If false, equivalent to passing
     :option:`--no-subproject-summary <ctest --no-subproject-summary>`
     on the command line.
 
   ``maxPassedTestOutputSize``
-
     An optional integer specifying the maximum output for passed tests in
     bytes. Equivalent to passing
     :option:`--test-output-size-passed <ctest --test-output-size-passed>`
     on the command line.
 
   ``maxFailedTestOutputSize``
-
     An optional integer specifying the maximum output for failed tests in
     bytes. Equivalent to passing
     :option:`--test-output-size-failed <ctest --test-output-size-failed>`
     on the command line.
 
   ``testOutputTruncation``
-
     An optional string specifying the test output truncation mode. Equivalent
     to passing
     :option:`--test-output-truncation <ctest --test-output-truncation>` on
@@ -756,42 +667,34 @@ that may contain the following fields:
     ``5`` or above.
 
   ``maxTestNameWidth``
-
     An optional integer specifying the maximum width of a test name to
     output. Equivalent to passing :option:`--max-width <ctest --max-width>`
     on the command line.
 
 ``filter``
-
   An optional object specifying how to filter the tests to run. The object
   may contain the following fields.
 
   ``include``
-
     An optional object specifying which tests to include. The object may
     contain the following fields.
 
     ``name``
-
       An optional string specifying a regex for test names. Equivalent to
       passing :option:`--tests-regex <ctest --tests-regex>` on the command
       line. This field supports macro expansion. CMake regex syntax is
       described under :ref:`string(REGEX) <Regex Specification>`.
 
-
     ``label``
-
       An optional string specifying a regex for test labels. Equivalent to
       passing :option:`--label-regex <ctest --label-regex>` on the command
       line. This field supports macro expansion.
 
     ``useUnion``
-
       An optional bool. Equivalent to passing :option:`--union <ctest --union>`
       on the command line.
 
     ``index``
-
       An optional object specifying tests to include by test index. The
       object may contain the following fields. Can also be an optional
       string specifying a file with the command line syntax for
@@ -799,99 +702,81 @@ that may contain the following fields:
       If specified as a string, this field supports macro expansion.
 
       ``start``
-
         An optional integer specifying a test index to start testing at.
 
       ``end``
-
         An optional integer specifying a test index to stop testing at.
 
       ``stride``
-
         An optional integer specifying the increment.
 
       ``specificTests``
-
         An optional array of integers specifying specific test indices to
         run.
 
   ``exclude``
-
     An optional object specifying which tests to exclude. The object may
     contain the following fields.
 
     ``name``
-
       An optional string specifying a regex for test names. Equivalent to
       passing :option:`--exclude-regex <ctest --exclude-regex>` on the
       command line. This field supports macro expansion.
 
     ``label``
-
       An optional string specifying a regex for test labels. Equivalent to
       passing :option:`--label-exclude <ctest --label-exclude>` on the
       command line. This field supports macro expansion.
 
     ``fixtures``
-
       An optional object specifying which fixtures to exclude from adding
       tests. The object may contain the following fields.
 
       ``any``
-
         An optional string specifying a regex for text fixtures to exclude
         from adding any tests. Equivalent to
         :option:`--fixture-exclude-any <ctest --fixture-exclude-any>` on
         the command line. This field supports macro expansion.
 
       ``setup``
-
         An optional string specifying a regex for text fixtures to exclude
         from adding setup tests. Equivalent to
         :option:`--fixture-exclude-setup <ctest --fixture-exclude-setup>`
         on the command line. This field supports macro expansion.
 
       ``cleanup``
-
         An optional string specifying a regex for text fixtures to exclude
         from adding cleanup tests. Equivalent to
         :option:`--fixture-exclude-cleanup <ctest --fixture-exclude-cleanup>`
         on the command line. This field supports macro expansion.
 
 ``execution``
-
   An optional object specifying options for test execution. The object may
   contain the following fields.
 
   ``stopOnFailure``
-
     An optional bool. If true, equivalent to passing
     :option:`--stop-on-failure <ctest --stop-on-failure>` on the command
     line.
 
   ``enableFailover``
-
     An optional bool. If true, equivalent to passing :option:`-F <ctest -F>`
     on the command line.
 
   ``jobs``
-
     An optional integer. Equivalent to passing
     :option:`--parallel <ctest --parallel>` on the command line.
 
   ``resourceSpecFile``
-
     An optional string. Equivalent to passing
     :option:`--resource-spec-file <ctest --resource-spec-file>` on
     the command line. This field supports macro expansion.
 
   ``testLoad``
-
     An optional integer. Equivalent to passing
     :option:`--test-load <ctest --test-load>` on the command line.
 
   ``showOnly``
-
     An optional string. Equivalent to passing
     :option:`--show-only <ctest --show-only>` on the
     command line. The string must be one of the following values:
@@ -901,13 +786,11 @@ that may contain the following fields:
     ``json-v1``
 
   ``repeat``
-
     An optional object specifying how to repeat tests. Equivalent to
     passing :option:`--repeat <ctest --repeat>` on the command line.
     The object must have the following fields.
 
     ``mode``
-
       A required string. Must be one of the following values:
 
       ``until-fail``
@@ -917,11 +800,9 @@ that may contain the following fields:
       ``after-timeout``
 
     ``count``
-
       A required integer.
 
   ``interactiveDebugging``
-
     An optional bool. If true, equivalent to passing
     :option:`--interactive-debug-mode 1 <ctest --interactive-debug-mode>`
     on the command line. If false, equivalent to passing
@@ -929,32 +810,26 @@ that may contain the following fields:
     on the command line.
 
   ``scheduleRandom``
-
     An optional bool. If true, equivalent to passing
     :option:`--schedule-random <ctest --schedule-random>` on the command
     line.
 
   ``timeout``
-
     An optional integer. Equivalent to passing
     :option:`--timeout <ctest --timeout>` on the command line.
 
   ``noTestsAction``
-
     An optional string specifying the behavior if no tests are found. Must
     be one of the following values:
 
     ``default``
-
       Equivalent to not passing any value on the command line.
 
     ``error``
-
       Equivalent to passing :option:`--no-tests=error <ctest --no-tests>`
       on the command line.
 
     ``ignore``
-
       Equivalent to passing :option:`--no-tests=ignore <ctest --no-tests>`
       on the command line.
 
@@ -972,65 +847,53 @@ a ``not``, ``anyOf``, or ``allOf`` condition) may not be ``null``. If it is an
 object, it has the following fields:
 
 ``type``
-
   A required string with one of the following values:
 
   ``"const"``
-
     Indicates that the condition is constant. This is equivalent to using a
     boolean in place of the object. The condition object will have the
     following additional fields:
 
     ``value``
-
       A required boolean which provides a constant value for the condition's
       evaluation.
 
   ``"equals"``
 
   ``"notEquals"``
-
     Indicates that the condition compares two strings to see if they are equal
     (or not equal). The condition object will have the following additional
     fields:
 
     ``lhs``
-
       First string to compare. This field supports macro expansion.
 
     ``rhs``
-
       Second string to compare. This field supports macro expansion.
 
   ``"inList"``
 
   ``"notInList"``
-
     Indicates that the condition searches for a string in a list of strings.
     The condition object will have the following additional fields:
 
     ``string``
-
       A required string to search for. This field supports macro expansion.
 
     ``list``
-
       A required list of strings to search. This field supports macro
       expansion, and uses short-circuit evaluation.
 
   ``"matches"``
 
   ``"notMatches"``
-
     Indicates that the condition searches for a regular expression in a string.
     The condition object will have the following additional fields:
 
     ``string``
-
       A required string to search. This field supports macro expansion.
 
     ``regex``
-
       A required regular expression to search for. This field supports macro
       expansion.
 
@@ -1042,17 +905,14 @@ object, it has the following fields:
     conditions. The condition object will have the following additional fields:
 
     ``conditions``
-
       A required array of condition objects. These conditions use short-circuit
       evaluation.
 
   ``"not"``
-
     Indicates that the condition is an inversion of another condition. The
     condition object will have the following additional fields:
 
     ``condition``
-
       A required condition object.
 
 Macro Expansion
@@ -1074,46 +934,37 @@ interpreted as a literal dollar sign.
 Recognized macros include:
 
 ``${sourceDir}``
-
   Path to the project source directory (i.e. the same as
   :variable:`CMAKE_SOURCE_DIR`).
 
 ``${sourceParentDir}``
-
   Path to the project source directory's parent directory.
 
 ``${sourceDirName}``
-
   The last filename component of ``${sourceDir}``. For example, if
   ``${sourceDir}`` is ``/path/to/source``, this would be ``source``.
 
 ``${presetName}``
-
   Name specified in the preset's ``name`` field.
 
 ``${generator}``
-
   Generator specified in the preset's ``generator`` field. For build and
   test presets, this will evaluate to the generator specified by
   ``configurePreset``.
 
 ``${hostSystemName}``
-
   The name of the host operating system. Contains the same value as
   :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files
   specifying version ``3`` or above.
 
 ``${fileDir}``
-
   Path to the directory containing the preset file which contains the macro.
   This is allowed in preset files specifying version ``4`` or above.
 
 ``${dollar}``
-
   A literal dollar sign (``$``).
 
 ``${pathListSep}``
-
   Native character for separating lists of paths, such as ``:`` or ``;``.
 
   For example, by setting ``PATH`` to
@@ -1124,7 +975,6 @@ Recognized macros include:
   This is allowed in preset files specifying version ``5`` or above.
 
 ``$env{<variable-name>}``
-
   Environment variable with name ``<variable-name>``. The variable name may
   not be an empty string. If the variable is defined in the ``environment``
   field, that value is used instead of the value from the parent environment.
@@ -1137,7 +987,6 @@ Recognized macros include:
   the casing of environment variable names consistent.
 
 ``$penv{<variable-name>}``
-
   Similar to ``$env{<variable-name>}``, except that the value only comes from
   the parent environment, and never from the ``environment`` field. This
   allows you to prepend or append values to existing environment variables.
@@ -1147,7 +996,6 @@ Recognized macros include:
   references.
 
 ``$vendor{<macro-name>}``
-
   An extension point for vendors to insert their own macros. CMake will not
   be able to use presets which have a ``$vendor{<macro-name>}`` macro, and
   effectively ignores such presets. However, it will still be able to use

Help/manual/cmake-toolchains.7.rst

@@ -96,7 +96,8 @@ Cross Compiling
 ===============
 
 If :manual:`cmake(1)` is invoked with the command line parameter
-``--toolchain path/to/file`` or ``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the
+:option:`--toolchain path/to/file <cmake --toolchain>` or
+:option:`-DCMAKE_TOOLCHAIN_FILE=path/to/file <cmake -D>`, the
 file will be loaded early to set values for the compilers.
 The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is
 cross-compiling.

Help/manual/cmake.1.rst

@@ -9,8 +9,7 @@ Synopsis
 .. parsed-literal::
 
  `Generate a Project Buildsystem`_
-  cmake [<options>] <path-to-source>
-  cmake [<options>] <path-to-existing-build>
+  cmake [<options>] <path-to-source | path-to-existing-build>
   cmake [<options>] -S <path-to-source> -B <path-to-build>
 
  `Build a Project`_
@@ -23,7 +22,7 @@ Synopsis
   cmake --open <dir>
 
  `Run a Script`_
-  cmake [{-D <var>=<value>}...] -P <cmake-script-file>
+  cmake [-D <var>=<value>]... -P <cmake-script-file>
 
  `Run a Command-Line Tool`_
   cmake -E <command> [<options>]
@@ -243,12 +242,13 @@ Options
  from the top of a binary tree for a CMake project it will dump
  additional information such as the cache, log files etc.
 
-.. option:: --log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>
+.. option:: --log-level=<level>
 
- Set the log level.
+ Set the log ``<level>``.
 
  The :command:`message` command will only output messages of the specified
- log level or higher.  The default log level is ``STATUS``.
+ log level or higher.  The valid log levels are ``ERROR``, ``WARNING``,
+ ``NOTICE``, ``STATUS`` (default), ``VERBOSE``, ``DEBUG``, or ``TRACE``.
 
  To make a log level persist between CMake runs, set
  :variable:`CMAKE_MESSAGE_LOG_LEVEL` as a cache variable instead.
@@ -497,10 +497,12 @@ Options
  a variable called ``MYVAR`` to ``1``, but the user sets it to ``2`` with a
  ``-D`` argument, the value ``2`` is preferred.
 
-.. option:: --list-presets, --list-presets=<[configure | build | test | all]>
+.. option:: --list-presets[=<type>]
 
- Lists the available presets. If no option is specified only configure presets
- will be listed. The current working directory must contain CMake preset files.
+ Lists the available presets of the specified ``<type>``.  Valid values for
+ ``<type>`` are ``configure``, ``build``, ``test``, or ``all``.  If ``<type>``
+ is omitted, ``configure`` is assumed.  The current working directory must
+ contain CMake preset files.
 
 .. _`Build Tool Mode`:
 
@@ -546,7 +548,7 @@ following options:
   Some native build tools always build in parallel.  The use of ``<jobs>``
   value of ``1`` can be used to limit to a single job.
 
-.. option:: --target <tgt>..., -t <tgt>...
+.. option:: -t <tgt>..., --target <tgt>...
 
   Build ``<tgt>`` instead of the default target.  Multiple targets may be
   given, separated by spaces.
@@ -560,14 +562,15 @@ following options:
   Build target ``clean`` first, then build.
   (To clean only, use :option:`--target clean <cmake --target>`.)
 
-.. option:: --resolve-package-references=<on|off|only>
+.. option:: --resolve-package-references=<value>
 
   .. versionadded:: 3.23
 
   Resolve remote package references from external package managers (e.g. NuGet)
-  before build. When set to ``on`` (default), packages will be restored before
-  building a target. When set to ``only``, the packages will be restored, but no
-  build will be performed. When set to ``off``, no packages will be restored.
+  before build. When ``<value>`` is set to ``on`` (default), packages will be
+  restored before building a target.  When ``<value>`` is set to ``only``, the
+  packages will be restored, but no build will be performed.  When
+  ``<value>`` is set to ``off``, no packages will be restored.
 
   If the target does not define any package references, this option does nothing.
 
@@ -669,7 +672,7 @@ Run a Script
 
 .. code-block:: shell
 
-  cmake [{-D <var>=<value>}...] -P <cmake-script-file> [-- <unparsed-options>...]
+  cmake [-D <var>=<value>]... -P <cmake-script-file> [-- <unparsed-options>...]
 
 .. option:: -D <var>=<value>
 

Help/manual/cpack.1.rst

@@ -73,7 +73,7 @@ Options
   details.  By default, ``CPackConfig.cmake`` in the current directory will
   be used.
 
-.. option:: --verbose, -V
+.. option:: -V, --verbose
 
   Run ``cpack`` with verbose output.  This can be used to show more details
   from the package generation tools and is suitable for project developers.

Help/manual/ctest.1.rst

@@ -10,12 +10,24 @@ Synopsis
 
 .. parsed-literal::
 
- ctest [<options>]
- ctest --build-and-test <path-to-source> <path-to-build>
-       --build-generator <generator> [<options>...]
-       [--build-options <opts>...] [--test-command <command> [<args>...]]
- ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>}
-       [-- <dashboard-options>...]
+ `Run Tests`_
+  ctest [<options>]
+
+ `Build and Test Mode`_
+  ctest --build-and-test <path-to-source> <path-to-build>
+        --build-generator <generator> [<options>...]
+       [--build-options <opts>...]
+       [--test-command <command> [<args>...]]
+
+ `Dashboard Client`_
+  ctest -D <dashboard>         [-- <dashboard-options>...]
+  ctest -M <model> -T <action> [-- <dashboard-options>...]
+  ctest -S <script>            [-- <dashboard-options>...]
+  ctest -SP <script>           [-- <dashboard-options>...]
+
+ `View Help`_
+  ctest --help[-<topic>]
+
 
 Description
 ===========
@@ -25,14 +37,13 @@ CMake-generated build trees created for projects that use the
 :command:`enable_testing` and :command:`add_test` commands have testing support.
 This program will run the tests and report results.
 
-.. _`CTest Options`:
+.. _`Run Tests`:
 
-Options
-=======
+Run Tests
+=========
 
 .. program:: ctest
 
-
 .. option:: --preset <preset>, --preset=<preset>
 
  Use a test preset to specify test options. The project binary directory
@@ -76,6 +87,7 @@ Options
  displayed.  This option will show all test output.
 
 .. option:: -VV, --extra-verbose
+
  Enable more verbose output from tests.
 
  Test output is normally suppressed and only summary information is
@@ -138,6 +150,7 @@ Options
  ``TestLoad`` option of the `CTest Test Step`_.
 
 .. option:: -Q, --quiet
+
  Make CTest quiet.
 
  This option will suppress all the output.  The output log file will
@@ -237,73 +250,6 @@ Options
  Same as :option:`-FA <ctest -FA>` except only matching cleanup tests are
  excluded.
 
-.. option:: -D <dashboard>, --dashboard <dashboard>
-
- Execute dashboard test.
-
- This option tells CTest to act as a CDash client and perform a
- dashboard test.  All tests are ``<Mode><Test>``, where ``<Mode>`` can be
- ``Experimental``, ``Nightly``, and ``Continuous``, and ``<Test>`` can be
- ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``,
- ``Coverage``, and ``Submit``.
-
- See `Dashboard Client`_.
-
-.. option:: -D <var>:<type>=<value>
-
- Define a variable for script mode.
-
- Pass in variable values on the command line.  Use in conjunction
- with :option:`-S <ctest -S>` to pass variable values to a dashboard script.
- Parsing ``-D`` arguments as variable values is only attempted if the value
- following ``-D`` does not match any of the known dashboard types.
-
-.. option:: -M <model>, --test-model <model>
-
- Sets the model for a dashboard.
-
- This option tells CTest to act as a CDash client where the ``<model>``
- can be ``Experimental``, ``Nightly``, and ``Continuous``.
- Combining ``-M`` and :option:`-T <ctest -T>` is similar to
- :option:`-D <ctest -D>`.
-
- See `Dashboard Client`_.
-
-.. option:: -T <action>, --test-action <action>
-
- Sets the dashboard action to perform.
-
- This option tells CTest to act as a CDash client and perform some
- action such as ``start``, ``build``, ``test`` etc. See
- `Dashboard Client Steps`_ for the full list of actions.
- Combining :option:`-M <ctest -M>` and ``-T`` is similar to
- :option:`-D <ctest -D>`.
-
- See `Dashboard Client`_.
-
-.. option:: -S <script>, --script <script>
-
- Execute a dashboard for a configuration.
-
- This option tells CTest to load in a configuration script which sets
- a number of parameters such as the binary and source directories.
- Then CTest will do what is required to create and run a dashboard.
- This option basically sets up a dashboard and then runs :option:`ctest -D`
- with the appropriate options.
-
- See `Dashboard Client`_.
-
-.. option:: -SP <script>, --script-new-process <script>
-
- Execute a dashboard for a configuration.
-
- This option does the same operations as :option:`-S <ctest -S>` but it
- will do them in a separate process.  This is primarily useful in cases
- where the script may modify the environment and you do not want the modified
- environment to impact other :option:`-S <ctest -S>` scripts.
-
- See `Dashboard Client`_.
-
 .. option:: -I [Start,End,Stride,test#,test#|Test file], --tests-information
 
  Run a specific number of tests by number.
@@ -400,13 +346,9 @@ Options
 
  See `Label and Subproject Summary`_.
 
-.. option:: --build-and-test
-
- See `Build and Test Mode`_.
-
 .. option:: --test-dir <dir>
 
-Specify the directory in which to look for tests.
+ Specify the directory in which to look for tests.
 
 .. option:: --test-output-size-passed <size>
 
@@ -477,15 +419,22 @@ Specify the directory in which to look for tests.
  This option will not run any tests, it will simply print the list of
  all labels associated with the test set.
 
-.. option:: --no-tests=<[error|ignore]>
+.. option:: --no-tests=<action>
 
- Regard no tests found either as error or ignore it.
+ Regard no tests found either as error (when ``<action>`` is set to
+ ``error``) or ignore it (when ``<action>`` is set to ``ignore``).
 
  If no tests were found, the default behavior of CTest is to always log an
  error message but to return an error code in script mode only.  This option
  unifies the behavior of CTest by either returning an error code if no tests
  were found or by ignoring it.
 
+View Help
+=========
+
+To print version details or selected pages from the CMake documentation,
+use one of the following options:
+
 .. include:: OPTIONS_HELP.txt
 
 .. _`Label Matching`:
@@ -595,6 +544,10 @@ 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:
 
+.. option:: --build-and-test
+
+ Switch into the build and test mode.
+
 .. option:: --build-target
 
  Specify a specific target to build.  The option can be given multiple times
@@ -682,11 +635,78 @@ 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>...]
+  ctest -D <dashboard>         [-- <dashboard-options>...]
+  ctest -M <model> -T <action> [-- <dashboard-options>...]
+  ctest -S <script>            [-- <dashboard-options>...]
+  ctest -SP <script>           [-- <dashboard-options>...]
 
 Options for Dashboard Client include:
 
+.. option:: -D <dashboard>, --dashboard <dashboard>
+
+ Execute dashboard test.
+
+ This option tells CTest to act as a CDash client and perform a
+ dashboard test.  All tests are ``<Mode><Test>``, where ``<Mode>`` can be
+ ``Experimental``, ``Nightly``, and ``Continuous``, and ``<Test>`` can be
+ ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``,
+ ``Coverage``, and ``Submit``.
+
+ If ``<dashboard>`` is not one of the recognized ``<Mode><Test>`` values,
+ this will be treated as a variable definition instead (see the
+ :ref:`dashboard-options <Dashboard Options>` further below).
+
+.. option:: -M <model>, --test-model <model>
+
+ Sets the model for a dashboard.
+
+ This option tells CTest to act as a CDash client where the ``<model>``
+ can be ``Experimental``, ``Nightly``, and ``Continuous``.
+ Combining ``-M`` and :option:`-T <ctest -T>` is similar to
+ :option:`-D <ctest -D>`.
+
+.. option:: -T <action>, --test-action <action>
+
+ Sets the dashboard action to perform.
+
+ This option tells CTest to act as a CDash client and perform some
+ action such as ``start``, ``build``, ``test`` etc. See
+ `Dashboard Client Steps`_ for the full list of actions.
+ Combining :option:`-M <ctest -M>` and ``-T`` is similar to
+ :option:`-D <ctest -D>`.
+
+.. option:: -S <script>, --script <script>
+
+ Execute a dashboard for a configuration.
+
+ This option tells CTest to load in a configuration script which sets
+ a number of parameters such as the binary and source directories.
+ Then CTest will do what is required to create and run a dashboard.
+ This option basically sets up a dashboard and then runs :option:`ctest -D`
+ with the appropriate options.
+
+.. option:: -SP <script>, --script-new-process <script>
+
+ Execute a dashboard for a configuration.
+
+ This option does the same operations as :option:`-S <ctest -S>` but it
+ will do them in a separate process.  This is primarily useful in cases
+ where the script may modify the environment and you do not want the modified
+ environment to impact other :option:`-S <ctest -S>` scripts.
+
+.. _`Dashboard Options`:
+
+The available ``<dashboard-options>`` are the following:
+
+.. option:: -D <var>:<type>=<value>
+
+ Define a variable for script mode.
+
+ Pass in variable values on the command line.  Use in conjunction
+ with :option:`-S <ctest -S>` to pass variable values to a dashboard script.
+ Parsing ``-D`` arguments as variable values is only attempted if the value
+ following ``-D`` does not match any of the known dashboard types.
+
 .. option:: --group <group>
 
  Specify what group you'd like to submit results to
@@ -810,7 +830,7 @@ Run the ``ctest`` command with the current working directory set
 to the build tree and use one of these signatures::
 
   ctest -D <mode>[<step>]
-  ctest -M <mode> [ -T <step> ]...
+  ctest -M <mode> [-T <step>]...
 
 The ``<mode>`` must be one of the above `Dashboard Client Modes`_,
 and each ``<step>`` must be one of the above `Dashboard Client Steps`_.

Help/prop_test/LABELS.rst

@@ -4,7 +4,7 @@ LABELS
 Specify a list of text labels associated with a test.  The labels are
 reported in both the ``ctest`` output summary and in dashboard submissions.
 They can also be used to filter the set of tests to be executed (see the
-``ctest -L`` and ``ctest -LE`` :ref:`CTest Options`).
+:option:`ctest -L` and :option:`ctest -LE` options).
 
 See :ref:`Additional Labels` for adding labels to a test dynamically during
 test execution.

Help/variable/CMAKE_BINARY_DIR.rst

@@ -7,7 +7,7 @@ This is the full path to the top level of the current CMake build
 tree.  For an in-source build, this would be the same as
 :variable:`CMAKE_SOURCE_DIR`.
 
-When run in -P script mode, CMake sets the variables
+When run in :option:`-P <cmake_P -P>` script mode, CMake sets the variables
 :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`,
 :variable:`CMAKE_CURRENT_BINARY_DIR` and
 :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory.

Help/variable/CMAKE_CURRENT_BINARY_DIR.rst

@@ -9,7 +9,7 @@ create a binary directory in the build tree, and as it is being
 processed this variable will be set.  For in-source builds this is the
 current source directory being processed.
 
-When run in -P script mode, CMake sets the variables
+When run in :option:`-P <cmake_P -P>` script mode, CMake sets the variables
 :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`,
 :variable:`CMAKE_CURRENT_BINARY_DIR` and
 :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory.

Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst

@@ -6,7 +6,7 @@ The path to the source directory currently being processed.
 This is the full path to the source directory that is currently being
 processed by cmake.
 
-When run in -P script mode, CMake sets the variables
+When run in :option:`-P <cmake_P -P>` script mode, CMake sets the variables
 :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`,
 :variable:`CMAKE_CURRENT_BINARY_DIR` and
 :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory.

Help/variable/CMAKE_SOURCE_DIR.rst

@@ -7,7 +7,7 @@ This is the full path to the top level of the current CMake source
 tree.  For an in-source build, this would be the same as
 :variable:`CMAKE_BINARY_DIR`.
 
-When run in ``-P`` script mode, CMake sets the variables
+When run in :option:`-P <cmake_P -P>` script mode, CMake sets the variables
 :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`,
 :variable:`CMAKE_CURRENT_BINARY_DIR` and
 :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory.

Source/CPack/cpack.cxx

@@ -50,7 +50,7 @@ const char* cmDocumentationOptions[][2] = {
   { "-C <Configuration>", "Specify the project configuration" },
   { "-D <var>=<value>", "Set a CPack variable." },
   { "--config <configFile>", "Specify the config file." },
-  { "--verbose,-V", "Enable verbose output" },
+  { "-V,--verbose", "Enable verbose output" },
   { "--trace", "Put underlying cmake scripts in trace mode." },
   { "--trace-expand", "Put underlying cmake scripts in expanded trace mode." },
   { "--debug", "Enable debug output (for CPack developers)" },

Source/cmDocumentation.cxx

@@ -17,30 +17,32 @@
 #include "cmVersion.h"
 
 static const char* cmDocumentationStandardOptions[][2] = {
-  { "--help,-help,-usage,-h,-H,/?", "Print usage information and exit." },
-  { "--version,-version,/V [<f>]", "Print version number and exit." },
-  { "--help-full [<f>]", "Print all help manuals and exit." },
-  { "--help-manual <man> [<f>]", "Print one help manual and exit." },
-  { "--help-manual-list [<f>]", "List help manuals available and exit." },
-  { "--help-command <cmd> [<f>]", "Print help for one command and exit." },
-  { "--help-command-list [<f>]",
+  { "-h,-H,--help,-help,-usage,/?", "Print usage information and exit." },
+  { "--version,-version,/V [<file>]", "Print version number and exit." },
+  { "--help-full [<file>]", "Print all help manuals and exit." },
+  { "--help-manual <man> [<file>]", "Print one help manual and exit." },
+  { "--help-manual-list [<file>]", "List help manuals available and exit." },
+  { "--help-command <cmd> [<file>]", "Print help for one command and exit." },
+  { "--help-command-list [<file>]",
     "List commands with help available and exit." },
-  { "--help-commands [<f>]", "Print cmake-commands manual and exit." },
-  { "--help-module <mod> [<f>]", "Print help for one module and exit." },
-  { "--help-module-list [<f>]", "List modules with help available and exit." },
-  { "--help-modules [<f>]", "Print cmake-modules manual and exit." },
-  { "--help-policy <cmp> [<f>]", "Print help for one policy and exit." },
-  { "--help-policy-list [<f>]",
+  { "--help-commands [<file>]", "Print cmake-commands manual and exit." },
+  { "--help-module <mod> [<file>]", "Print help for one module and exit." },
+  { "--help-module-list [<file>]",
+    "List modules with help available and exit." },
+  { "--help-modules [<file>]", "Print cmake-modules manual and exit." },
+  { "--help-policy <cmp> [<file>]", "Print help for one policy and exit." },
+  { "--help-policy-list [<file>]",
     "List policies with help available and exit." },
-  { "--help-policies [<f>]", "Print cmake-policies manual and exit." },
-  { "--help-property <prop> [<f>]", "Print help for one property and exit." },
-  { "--help-property-list [<f>]",
+  { "--help-policies [<file>]", "Print cmake-policies manual and exit." },
+  { "--help-property <prop> [<file>]",
+    "Print help for one property and exit." },
+  { "--help-property-list [<file>]",
     "List properties with help available and exit." },
-  { "--help-properties [<f>]", "Print cmake-properties manual and exit." },
-  { "--help-variable var [<f>]", "Print help for one variable and exit." },
-  { "--help-variable-list [<f>]",
+  { "--help-properties [<file>]", "Print cmake-properties manual and exit." },
+  { "--help-variable var [<file>]", "Print help for one variable and exit." },
+  { "--help-variable-list [<file>]",
     "List variables with help available and exit." },
-  { "--help-variables [<f>]", "Print cmake-variables manual and exit." },
+  { "--help-variables [<file>]", "Print cmake-variables manual and exit." },
   { nullptr, nullptr }
 };
 

Source/cmakemain.cxx

@@ -71,7 +71,7 @@ const char* cmDocumentationUsageNote[][2] = {
 const char* cmDocumentationOptions[][2] = {
   CMAKE_STANDARD_OPTIONS_TABLE,
   { "--preset <preset>,--preset=<preset>", "Specify a configure preset." },
-  { "--list-presets", "List available presets." },
+  { "--list-presets[=<type>]", "List available presets." },
   { "-E", "CMake command mode." },
   { "-L[A][H]", "List non-advanced cached variables." },
   { "--fresh",
@@ -83,8 +83,8 @@ const char* cmDocumentationOptions[][2] = {
   { "-P <file>", "Process script mode." },
   { "--find-package", "Legacy pkg-config like mode.  Do not use." },
   { "--graphviz=<file>",
-    "Generate graphviz of dependencies, see "
-    "CMakeGraphVizOptions.cmake for more." },
+    "Generate graphviz of dependencies, see CMakeGraphVizOptions.cmake for "
+    "more." },
   { "--system-information [file]", "Dump information about this system." },
   { "--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>",
     "Set the verbosity of messages from CMake files. "
@@ -109,8 +109,7 @@ const char* cmDocumentationOptions[][2] = {
   { "--warn-uninitialized", "Warn about uninitialized values." },
   { "--no-warn-unused-cli", "Don't warn about command line options." },
   { "--check-system-vars",
-    "Find problems with variable usage in system "
-    "files." },
+    "Find problems with variable usage in system files." },
   { "--compile-no-warning-as-error",
     "Ignore COMPILE_WARNING_AS_ERROR property and "
     "CMAKE_COMPILE_WARNING_AS_ERROR variable." },
@@ -616,7 +615,7 @@ int do_build(int ac, char const* const* av)
       "  <dir>          = Project binary directory to be built.\n"
       "  --preset <preset>, --preset=<preset>\n"
       "                 = Specify a build preset.\n"
-      "  --list-presets\n"
+      "  --list-presets[=<type>]\n"
       "                 = List available build presets.\n"
       "  --parallel [<jobs>], -j [<jobs>]\n"
       "                 = Build in parallel using the given number of jobs. \n"
@@ -627,14 +626,14 @@ int do_build(int ac, char const* const* av)
       "                   specifies a default parallel level when this "
       "option\n"
       "                   is not given.\n"
-      "  --target <tgt>..., -t <tgt>... \n"
+      "  -t <tgt>..., --target <tgt>...\n"
       "                 = Build <tgt> instead of default targets.\n"
       "  --config <cfg> = For multi-configuration tools, choose <cfg>.\n"
       "  --clean-first  = Build target 'clean' first, then build.\n"
       "                   (To clean only, use --target 'clean'.)\n"
       "  --resolve-package-references={on|only|off}\n"
       "                 = Restore/resolve package references during build.\n"
-      "  --verbose, -v  = Enable verbose output - if supported - including\n"
+      "  -v, --verbose  = Enable verbose output - if supported - including\n"
       "                   the build commands to be executed. \n"
       "  --             = Pass remaining options to the native tool.\n"
       ;