Merge topic 'doc-markup-program-options'

a6abdf6c8f Help: Consistent options declaration -- short first, then long
f4563f05db Help: Value for `--graphviz=` option actually is mandatory
04843d743e Help: Replace a bunch of more ``--option`` to `:option:` role
09446266ee Help: Replace mentions of ``-D`` option with :option:`-D` role
b57f27b087 Help: Replace mentions of ``-T`` and ``-A`` options with role
d25b232dee Help: Replace mentions of ``-G`` option with :option:`-G` role
63940e1cab Help: Replace mentions of ``-C`` option with :option:`-C` role
183a49cbfe Help: Replace mentions of ``-S`` option with :option:`-S` role
...

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7544

18 files changed, 31 insertions, 24 deletions

diff --git a/Help/variable/CMAKE_CPACK_COMMAND.rst b/Help/variable/CMAKE_CPACK_COMMAND.rst
index 3a81d68..94f1891 100644
--- a/Help/variable/CMAKE_CPACK_COMMAND.rst
+++ b/Help/variable/CMAKE_CPACK_COMMAND.rst
@@ -6,5 +6,5 @@ CMAKE_CPACK_COMMAND
 Full path to :manual:`cpack(1)` command installed with CMake.
 
 This is the full path to the CPack executable :manual:`cpack(1)` which is
-useful from custom commands that want to use the :manual:`cmake(1)` ``-E``
+useful from custom commands that want to use the :option:`cmake -E <cmake_E -E>`
 option for portable system commands.
diff --git a/Help/variable/CMAKE_CTEST_COMMAND.rst b/Help/variable/CMAKE_CTEST_COMMAND.rst
index b2942e2..7287998 100644
--- a/Help/variable/CMAKE_CTEST_COMMAND.rst
+++ b/Help/variable/CMAKE_CTEST_COMMAND.rst
@@ -4,5 +4,5 @@ CMAKE_CTEST_COMMAND
 Full path to :manual:`ctest(1)` command installed with CMake.
 
 This is the full path to the CTest executable :manual:`ctest(1)` which is
-useful from custom commands that want to use the :manual:`cmake(1)` ``-E``
+useful from custom commands that want to use the :option:`cmake -E <cmake_E -E>`
 option for portable system commands.
diff --git a/Help/variable/CMAKE_FIND_DEBUG_MODE.rst b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst
index 8f2a82f..48b0dce 100644
--- a/Help/variable/CMAKE_FIND_DEBUG_MODE.rst
+++ b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst
@@ -13,7 +13,7 @@ error:
 * :command:`find_package`
 
 Output is designed for human consumption and not for parsing.
-Enabling this variable is equivalent to using :manual:`cmake <cmake(1)>` ``--debug-find``
+Enabling this variable is equivalent to using :option:`cmake --debug-find`
 with the added ability to enable debugging for a subset of find calls.
 
 .. code-block:: cmake
diff --git a/Help/variable/CMAKE_GENERATOR.rst b/Help/variable/CMAKE_GENERATOR.rst
index ec52cd4..0e249eb 100644
--- a/Help/variable/CMAKE_GENERATOR.rst
+++ b/Help/variable/CMAKE_GENERATOR.rst
@@ -7,6 +7,6 @@ The name of the generator that is being used to generate the build
 files.  (e.g.  ``Unix Makefiles``, ``Ninja``, etc.)
 
 The value of this variable should never be modified by project code.
-A generator may be selected via the :manual:`cmake(1)` ``-G`` option,
+A generator may be selected via the :option:`cmake -G` option,
 interactively in :manual:`cmake-gui(1)`, or via the :envvar:`CMAKE_GENERATOR`
 environment variable.
diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
index b17d83a..acb7b2e 100644
--- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
+++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
@@ -7,7 +7,7 @@ Generator-specific target platform specification provided by user.
 
 Some CMake generators support a target platform name to be given
 to the native build system to choose a compiler toolchain.
-If the user specifies a platform name (e.g. via the :manual:`cmake(1)` ``-A``
+If the user specifies a platform name (e.g. via the :option:`cmake -A`
 option or via the :envvar:`CMAKE_GENERATOR_PLATFORM` environment variable)
 the value will be available in this variable.
 
diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst
index 45f2d32..4855477 100644
--- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst
+++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst
@@ -5,7 +5,7 @@ Native build system toolset specification provided by user.
 
 Some CMake generators support a toolset specification to tell the
 native build system how to choose a compiler.  If the user specifies
-a toolset (e.g. via the :manual:`cmake(1)` ``-T`` option or via
+a toolset (e.g. via the :option:`cmake -T` option or via
 the :envvar:`CMAKE_GENERATOR_TOOLSET` environment variable) the value
 will be available in this variable.
 
diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst
index 6d42ea8..1636739 100644
--- a/Help/variable/CMAKE_INSTALL_PREFIX.rst
+++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst
@@ -27,8 +27,9 @@ first :command:`project` invocation.
 
 The ``CMAKE_INSTALL_PREFIX`` may be defined when configuring a build tree
 to set its installation prefix.  Or, when using the :manual:`cmake(1)`
-command-line tool's ``--install`` mode, one may specify a different prefix
-using the ``--prefix`` option:
+command-line tool's :option:`--install <cmake --install>` mode, one may
+specify a different prefix using the :option:`--prefix <cmake --prefix>`
+option:
 
 .. code-block:: shell
 
diff --git a/Help/variable/CMAKE_LANG_COMPILER.rst b/Help/variable/CMAKE_LANG_COMPILER.rst
index e694b33..db8f4e1 100644
--- a/Help/variable/CMAKE_LANG_COMPILER.rst
+++ b/Help/variable/CMAKE_LANG_COMPILER.rst
@@ -14,7 +14,8 @@ This variable can be set by the user during the first time a build tree is confi
 If a non-full path value is supplied then CMake will resolve the full path of
 the compiler.
 
-The variable could be set in a user supplied toolchain file or via `-D` on the command line.
+The variable could be set in a user supplied toolchain file or via
+:option:`-D <cmake -D>` on the command line.
 
 .. note::
   Options that are required to make the compiler work correctly can be included
diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst
index a3c8b7c..9769c7a 100644
--- a/Help/variable/CMAKE_MAKE_PROGRAM.rst
+++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst
@@ -59,6 +59,6 @@ to configure the project:
   variable, changing the value has undefined behavior.
 
 The ``CMAKE_MAKE_PROGRAM`` variable is set for use by project code.
-The value is also used by the :manual:`cmake(1)` ``--build`` and
-:manual:`ctest(1)` ``--build-and-test`` tools to launch the native
+The value is also used by the :option:`cmake --build` and
+:option:`ctest --build-and-test` tools to launch the native
 build process.
diff --git a/Help/variable/CMAKE_MESSAGE_CONTEXT.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst
index 41ace43..7274b7b 100644
--- a/Help/variable/CMAKE_MESSAGE_CONTEXT.rst
+++ b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst
@@ -3,7 +3,7 @@ CMAKE_MESSAGE_CONTEXT
 
 .. versionadded:: 3.17
 
-When enabled by the :manual:`cmake <cmake(1)>` ``--log-context`` command line
+When enabled by the :option:`cmake --log-context` command line
 option or the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable, the
 :command:`message` command converts the ``CMAKE_MESSAGE_CONTEXT`` list into a
 dot-separated string surrounded by square brackets and prepends it to each line
diff --git a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst
index 54ea6a4..4539c90 100644
--- a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst
+++ b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst
@@ -5,8 +5,9 @@ CMAKE_MESSAGE_LOG_LEVEL
 
 When set, this variable specifies the logging level used by the
 :command:`message` command.  Valid values are the same as those for the
-``--log-level`` command line option of the :manual:`cmake(1)` program.
-If this variable is set and the ``--log-level`` command line option is
+:option:`--log-level <cmake --log-level>` command line option of the
+:manual:`cmake(1)` program.  If this variable is set and the
+:option:`--log-level <cmake --log-level>` command line option is
 given, the command line option takes precedence.
 
 The main advantage to using this variable is to make a log level persist
diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst
index 9dce760..f844105 100644
--- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst
+++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst
@@ -42,5 +42,8 @@ only for the policies that do not warn by default:
 This variable should not be set by a project in CMake code.  Project
 developers running CMake may set this variable in their cache to
 enable the warning (e.g. ``-DCMAKE_POLICY_WARNING_CMP<NNNN>=ON``).
-Alternatively, running :manual:`cmake(1)` with the ``--debug-output``,
-``--trace``, or ``--trace-expand`` option will also enable the warning.
+Alternatively, running :manual:`cmake(1)` with the
+:option:`--debug-output <cmake --debug-output>`,
+:option:`--trace <cmake --trace>`, or
+:option:`--trace-expand <cmake --trace-expand>` option will also
+enable the warning.
diff --git a/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst b/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst
index 981af60..104f4ac 100644
--- a/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst
+++ b/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst
@@ -1,9 +1,9 @@
 CMAKE_SCRIPT_MODE_FILE
 ----------------------
 
-Full path to the :manual:`cmake(1)` ``-P`` script file currently being
+Full path to the :option:`cmake -P <cmake_P -P>` script file currently being
 processed.
 
-When run in :manual:`cmake(1)` ``-P`` script mode, CMake sets this variable to
+When run in :option:`cmake -P <cmake_P -P>` script mode, CMake sets this variable to
 the full path of the script file.  When run to configure a ``CMakeLists.txt``
 file, this variable is not set.
diff --git a/Help/variable/CMAKE_WARN_DEPRECATED.rst b/Help/variable/CMAKE_WARN_DEPRECATED.rst
index 4a224fa..c7b6159 100644
--- a/Help/variable/CMAKE_WARN_DEPRECATED.rst
+++ b/Help/variable/CMAKE_WARN_DEPRECATED.rst
@@ -7,4 +7,5 @@ If not ``FALSE``, use of deprecated functionality will issue warnings.
 If this variable is not set, CMake behaves as if it were set to ``TRUE``.
 
 When running :manual:`cmake(1)`, this option can be enabled with the
-``-Wdeprecated`` option, or disabled with the ``-Wno-deprecated`` option.
+:option:`-Wdeprecated <cmake -Wdeprecated>` option, or disabled with the
+:option:`-Wno-deprecated <cmake -Wno-deprecated>` option.
diff --git a/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst b/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst
index 210da52..6d72d14 100644
--- a/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst
+++ b/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst
@@ -5,5 +5,5 @@ Xcode compiler selection.
 
 :generator:`Xcode` supports selection of a compiler from one of the installed
 toolsets.  CMake provides the name of the chosen toolset in this
-variable, if any is explicitly selected (e.g.  via the :manual:`cmake(1)`
-``-T`` option).
+variable, if any is explicitly selected (e.g.  via the :option:`cmake -T`
+option).
diff --git a/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst
index 1c070b8..9bd50db 100644
--- a/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst
+++ b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst
@@ -3,7 +3,7 @@ CPACK_CUSTOM_INSTALL_VARIABLES
 
 .. versionadded:: 3.21
 
-CPack variables (set via e.g. ``cpack -D``, ``CPackConfig.cmake`` or
+CPack variables (set via e.g. :option:`cpack -D`, ``CPackConfig.cmake`` or
 :variable:`CPACK_PROJECT_CONFIG_FILE` scripts) are not directly visible in
 installation scripts.  Instead, one can pass a list of ``varName=value``
 pairs in the ``CPACK_CUSTOM_INSTALL_VARIABLES`` variable.  At install time,
diff --git a/Help/variable/CTEST_CONFIGURATION_TYPE.rst b/Help/variable/CTEST_CONFIGURATION_TYPE.rst
index 392845e..932f81d 100644
--- a/Help/variable/CTEST_CONFIGURATION_TYPE.rst
+++ b/Help/variable/CTEST_CONFIGURATION_TYPE.rst
@@ -6,5 +6,5 @@ CTEST_CONFIGURATION_TYPE
 Specify the CTest ``DefaultCTestConfigurationType`` setting
 in a :manual:`ctest(1)` dashboard client script.
 
-If the configuration type is set via ``-C <cfg>`` from the command line
+If the configuration type is set via :option:`-C \<cfg\> <ctest -C>` from the command line
 then this variable is populated accordingly.
diff --git a/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst
index 32c85ad..8cb6eaa 100644
--- a/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst
+++ b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst
@@ -4,4 +4,4 @@ CTEST_RUN_CURRENT_SCRIPT
 .. versionadded:: 3.11
 
 Setting this to 0 prevents :manual:`ctest(1)` from being run again when it
-reaches the end of a script run by calling ``ctest -S``.
+reaches the end of a script run by calling :option:`ctest -S`.