Merge topic 'doc-cli-xrefs' into release-3.25

3043c17039 Help: Add more CLI `:option:` references to various pages

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

11 files changed, 34 insertions, 32 deletions

diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst
index a03979d10a..3d86a2e032 100644
--- a/Help/command/build_command.rst
+++ b/Help/command/build_command.rst
@@ -24,12 +24,12 @@ options, if any.  The trailing ``-- -i`` option is added for
 :ref:`Makefile Generators` if policy :policy:`CMP0061` is not set to
 ``NEW``.
 
-When invoked, this ``cmake --build`` command line will launch the
+When invoked, this :option:`cmake --build` command line will launch the
 underlying build system tool.
 
 .. versionadded:: 3.21
-  The ``PARALLEL_LEVEL`` argument can be used to set the ``--parallel``
-  flag.
+  The ``PARALLEL_LEVEL`` argument can be used to set the
+  :option:`--parallel <cmake--build --parallel>` flag.
 
 .. code-block:: cmake
 
@@ -39,7 +39,7 @@ This second signature is deprecated, but still available for backwards
 compatibility.  Use the first signature instead.
 
 It sets the given ``<cachevariable>`` to a command-line string as
-above but without the ``--target`` option.
+above but without the :option:`--target <cmake--build --target>` option.
 The ``<makecommand>`` is ignored but should be the full path to
 devenv, nmake, make or one of the end user build tools
 for legacy invocations.
diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst
index e05df1afcd..8c81f2d526 100644
--- a/Help/command/ctest_build.rst
+++ b/Help/command/ctest_build.rst
@@ -40,8 +40,8 @@ The options are:
 ``CONFIGURATION <config>``
   Specify the build configuration (e.g. ``Debug``).  If not
   specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked.
-  Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)`
-  command will be used, if any.
+  Otherwise the :option:`-C \<cfg\> <ctest -C>` option given to the
+  :manual:`ctest(1)` command will be used, if any.
 
 ``PARALLEL_LEVEL <parallel>``
   .. versionadded:: 3.21
@@ -54,7 +54,7 @@ The options are:
   Pass additional arguments to the underlying build command.
   If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked.
   This can, e.g., be used to trigger a parallel build using the
-  ``-j`` option of make. See the :module:`ProcessorCount` module
+  ``-j`` option of ``make``. See the :module:`ProcessorCount` module
   for an example.
 
 ``PROJECT_NAME <project-name>``
diff --git a/Help/command/set.rst b/Help/command/set.rst
index 5e05d9b5d7..90b57d23f0 100644
--- a/Help/command/set.rst
+++ b/Help/command/set.rst
@@ -83,7 +83,7 @@ option is given then the cache entry will be set to the given value.
 
 It is possible for the cache entry to exist prior to the call but
 have no type set if it was created on the :manual:`cmake(1)` command
-line by a user through the ``-D<var>=<value>`` option without
+line by a user through the :option:`-D\<var\>=\<value\> <cmake -D>` option without
 specifying a type.  In this case the ``set`` command will add the
 type.  Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
 and the ``<value>`` provided on the command line is a relative path,
diff --git a/Help/generator/Xcode.rst b/Help/generator/Xcode.rst
index a66f483250..9dd50155c1 100644
--- a/Help/generator/Xcode.rst
+++ b/Help/generator/Xcode.rst
@@ -34,7 +34,7 @@ Supported pairs are:
   See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable for allowed values.
 
   For example, to select the original build system under Xcode 12,
-  run :manual:`cmake(1)` with the option ``-T buildsystem=1``.
+  run :manual:`cmake(1)` with the option :option:`-T buildsystem=1 <cmake -T>`.
 
 Swift Support
 ^^^^^^^^^^^^^
diff --git a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst
index f9dc7cc0ed..4aef050585 100644
--- a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst
+++ b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst
@@ -63,8 +63,8 @@ Build and Run
 Make a new directory called ``Step3_build``, run the :manual:`cmake
 <cmake(1)>` executable or the :manual:`cmake-gui <cmake-gui(1)>` to
 configure the project and then build it with your chosen build tool or by
-using ``cmake --build .`` from the build directory. Here's a refresher of
-what that looks like from the command line:
+using :option:`cmake --build . <cmake --build>` from the build directory.
+Here's a refresher of what that looks like from the command line:
 
 .. code-block:: console
 
diff --git a/Help/guide/tutorial/Installing and Testing.rst b/Help/guide/tutorial/Installing and Testing.rst
index 39691928e7..fa13040aec 100644
--- a/Help/guide/tutorial/Installing and Testing.rst
+++ b/Help/guide/tutorial/Installing and Testing.rst
@@ -52,17 +52,18 @@ Make a new directory called ``Step5_build``. Run the
 :manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
 with your chosen build tool.
 
-Then, run the install step by using the ``install`` option of the
-:manual:`cmake  <cmake(1)>` command (introduced in 3.15, older versions of
-CMake must use ``make install``) from the command line. This step will
-install the appropriate header files, libraries, and executables. For example:
+Then, run the install step by using the :option:`--install <cmake --install>`
+option of the :manual:`cmake  <cmake(1)>` command (introduced in 3.15, older
+versions of CMake must use ``make install``) from the command line. This step
+will install the appropriate header files, libraries, and executables.
+For example:
 
 .. code-block:: console
 
   cmake --install .
 
-For multi-configuration tools, don't forget to use the ``--config`` argument to
-specify the configuration.
+For multi-configuration tools, don't forget to use the
+:option:`--config <cmake--build --config>` argument to specify the configuration.
 
 .. code-block:: console
 
@@ -76,9 +77,9 @@ install target from the command line like the following:
   cmake --build . --target install --config Debug
 
 The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the
-root of where the files will be installed. If using the ``cmake --install``
-command, the installation prefix can be overridden via the ``--prefix``
-argument. For example:
+root of where the files will be installed. If using the :option:`cmake --install`
+command, the installation prefix can be overridden via the
+:option:`--prefix <cmake--install --prefix>` argument. For example:
 
 .. code-block:: console
 
@@ -194,9 +195,9 @@ Build and Run
 -------------
 
 Navigate to the build directory and rebuild the application. Then, run the
-:manual:`ctest <ctest(1)>` executable: ``ctest -N`` and ``ctest -VV``. For
+``ctest`` executable: :option:`ctest -N` and :option:`ctest -VV`. For
 multi-config generators (e.g. Visual Studio), the configuration type must be
-specified with the ``-C <mode>`` flag.  For example, to run tests in Debug
+specified with the :option:`-C \<mode\> <ctest -C>` flag.  For example, to run tests in Debug
 mode use ``ctest -C Debug -VV`` from the build directory
 (not the Debug subdirectory!). Release mode would be executed from the same
 location but with a ``-C Release``. Alternatively, build the ``RUN_TESTS``
diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst
index fe81a46d13..1e691be748 100644
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -1627,12 +1627,12 @@ Resource Specification File
 ---------------------------
 
 The resource specification file is a JSON file which is passed to CTest, either
-on the :manual:`ctest(1)` command line as ``--resource-spec-file``, or as the
+on the command line as :option:`ctest --resource-spec-file`, or as the
 ``RESOURCE_SPEC_FILE`` argument of :command:`ctest_test`. If a dashboard script
 is used and ``RESOURCE_SPEC_FILE`` is not specified, the value of
 :variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script is used instead.
-If ``--resource-spec-file``, ``RESOURCE_SPEC_FILE``, and
-:variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script are not specified,
+If :option:`--resource-spec-file <ctest --resource-spec-file>`, ``RESOURCE_SPEC_FILE``,
+and :variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script are not specified,
 the value of :variable:`CTEST_RESOURCE_SPEC_FILE` in the CMake build is used
 instead. If none of these are specified, no resource spec file is used.
 
diff --git a/Help/prop_test/FIXTURES_REQUIRED.rst b/Help/prop_test/FIXTURES_REQUIRED.rst
index f85083069c..7a056012b7 100644
--- a/Help/prop_test/FIXTURES_REQUIRED.rst
+++ b/Help/prop_test/FIXTURES_REQUIRED.rst
@@ -19,10 +19,11 @@ be executed. The cleanup tests for the fixture will always be executed, even if
 some setup tests fail.
 
 When CTest is asked to execute only a subset of tests (e.g. by the use of
-regular expressions or when run with the ``--rerun-failed`` command line
-option), it will automatically add any setup or cleanup tests for fixtures
-required by any of the tests that are in the execution set. This behavior can
-be overridden with the ``-FS``, ``-FC`` and ``-FA`` command line options to
+regular expressions or when run with the :option:`--rerun-failed <ctest --rerun-failed>`
+command line option), it will automatically add any setup or cleanup tests for
+fixtures required by any of the tests that are in the execution set. This
+behavior can be overridden with the :option:`-FS <ctest -FS>`,
+:option:`-FC <ctest -FC>` and :option:`-FA <ctest -FA>` command line options to
 :manual:`ctest(1)` if desired.
 
 Since setup and cleanup tasks are also tests, they can have an ordering
diff --git a/Help/variable/CMAKE_COMMAND.rst b/Help/variable/CMAKE_COMMAND.rst
index f80b46cb57..e65ff8c497 100644
--- a/Help/variable/CMAKE_COMMAND.rst
+++ b/Help/variable/CMAKE_COMMAND.rst
@@ -4,5 +4,5 @@ CMAKE_COMMAND
 The full path to the :manual:`cmake(1)` executable.
 
 This is the full path to the CMake executable :manual:`cmake(1)` which is
-useful from custom commands that want to use the ``cmake -E`` option for
+useful from custom commands that want to use the :option:`cmake -E` option for
 portable system commands.  (e.g.  ``/usr/local/bin/cmake``)
diff --git a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst
index f77e939163..58818f40f3 100644
--- a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst
+++ b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst
@@ -13,6 +13,6 @@ This switch should be used during the initial CMake run.  Otherwise if
 the package has already been found in a previous CMake run, the
 variables which have been stored in the cache will still be there.  In
 that case it is recommended to remove the cache variables for this
-package from the cache using the cache editor or :manual:`cmake(1)` ``-U``
+package from the cache using the cache editor or :option:`cmake -U`.
 
 See also the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable.
diff --git a/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst
index 5d45fb0b68..b27a3d95a3 100644
--- a/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst
+++ b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst
@@ -25,4 +25,4 @@ CMake configures the project.
 
 ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` is only set in CMake project mode.
 It is not set when CMake is run in script mode
-(i.e. :manual:`cmake -P ... <cmake(1)>`).
+(i.e. :option:`cmake -P`).