Merge topic 'doc-cmake-E-subcommand-suboptions' into release-3.25

26020fdaae Help: Reference options of sub-commands in some older release notes (>= 3.20)
c3ec1b7411 Help: Replace the ref `cmake --workflow --preset` with `option` role
a0349eb13f Help: Make cmake(1) sub-command options look like other options

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

6 files changed, 99 insertions, 52 deletions

diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 9384524327..3dc6d6972d 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -812,12 +812,19 @@ Available commands are:
 
   Concatenate files and print on the standard output.
 
-  .. versionadded:: 3.24
+  .. program:: cmake-E_cat
+
+  .. option:: --
+
+    .. versionadded:: 3.24
+
     Added support for the double dash argument ``--``. This basic implementation
     of ``cat`` does not support any options, so using a option starting with
     ``-`` will result in an error. Use ``--`` to indicate the end of options, in
     case a file starts with ``-``.
 
+.. program:: cmake-E
+
 .. option:: chdir <dir> <cmd> [<arg>...]
 
   Change the current working directory and run a command.
@@ -828,9 +835,15 @@ Available commands are:
   then returns ``0``, if not it returns ``1``.  In case of invalid
   arguments, it returns 2.
 
-  .. versionadded:: 3.14
-    The ``--ignore-eol`` option implies line-wise comparison and ignores
-    LF/CRLF differences.
+  .. program:: cmake-E_compare_files
+
+  .. option:: --ignore-eol
+
+    .. versionadded:: 3.14
+
+    The option implies line-wise comparison and ignores LF/CRLF differences.
+
+.. program:: cmake-E
 
 .. option:: copy <file>... <destination>
 
@@ -901,13 +914,18 @@ Available commands are:
 
   Run command in a modified environment. Options are:
 
-  ``NAME=VALUE``
+  .. program:: cmake-E_env
+
+  .. option:: NAME=VALUE
+
     Replaces the current value of ``NAME`` with ``VALUE``.
 
-  ``--unset=NAME``
+  .. option:: --unset=NAME
+
     Unsets the current value of ``NAME``.
 
-  ``--modify ENVIRONMENT_MODIFICATION``
+  .. option:: --modify ENVIRONMENT_MODIFICATION
+
     .. versionadded:: 3.25
 
     Apply a single :prop_test:`ENVIRONMENT_MODIFICATION` operation to the
@@ -919,11 +937,16 @@ Available commands are:
     when ``cmake`` launched (or unsets it), not to the most recent
     ``NAME=VALUE`` option.
 
-  .. versionadded:: 3.24
+  .. option:: --
+
+    .. versionadded:: 3.24
+
     Added support for the double dash argument ``--``. Use ``--`` to stop
     interpreting options/environment variables and treat the next argument as
     the command, even if it start with ``-`` or contains a ``=``.
 
+.. program:: cmake-E
+
 .. option:: environment
 
   Display the current environment variables.
@@ -1054,11 +1077,15 @@ Available commands are:
 
   Create or extract a tar or zip archive.  Options are:
 
-  ``c``
+  .. program:: cmake-E_tar
+
+  .. option:: c
+
     Create a new archive containing the specified files.
     If used, the ``<pathname>...`` argument is mandatory.
 
-  ``x``
+  .. option:: x
+
     Extract to disk from the archive.
 
     .. versionadded:: 3.15
@@ -1067,33 +1094,40 @@ Available commands are:
       When extracting selected files or directories, you must provide their exact
       names including the path, as printed by list (``-t``).
 
-  ``t``
+  .. option:: t
+
     List archive contents.
 
     .. versionadded:: 3.15
       The ``<pathname>...`` argument could be used to list only selected files
       or directories.
 
-  ``v``
+  .. option:: v
+
     Produce verbose output.
 
-  ``z``
+  .. option:: z
+
     Compress the resulting archive with gzip.
 
-  ``j``
+  .. option:: j
+
     Compress the resulting archive with bzip2.
 
-  ``J``
+  .. option:: J
+
     .. versionadded:: 3.1
 
     Compress the resulting archive with XZ.
 
-  ``--zstd``
+  .. option:: --zstd
+
     .. versionadded:: 3.15
 
     Compress the resulting archive with Zstandard.
 
-  ``--files-from=<file>``
+  .. option:: --files-from=<file>
+
     .. versionadded:: 3.1
 
     Read file names from the given file, one per line.
@@ -1101,25 +1135,29 @@ Available commands are:
     except for ``--add-file=<name>`` to add files whose
     names start in ``-``.
 
-  ``--format=<format>``
+  .. option:: --format=<format>
+
     .. versionadded:: 3.3
 
     Specify the format of the archive to be created.
     Supported formats are: ``7zip``, ``gnutar``, ``pax``,
     ``paxr`` (restricted pax, default), and ``zip``.
 
-  ``--mtime=<date>``
+  .. option:: --mtime=<date>
+
     .. versionadded:: 3.1
 
     Specify modification time recorded in tarball entries.
 
-  ``--touch``
+  .. option:: --touch
+
     .. versionadded:: 3.24
 
     Use current local timestamp instead of extracting file timestamps
     from the archive.
 
-  ``--``
+  .. option:: --
+
     .. versionadded:: 3.1
 
     Stop interpreting options and treat all remaining arguments
@@ -1134,6 +1172,8 @@ Available commands are:
     ``tar`` tool. The command now also parses all flags, and if an invalid flag
     was provided, a warning is issued.
 
+.. program:: cmake-E
+
 .. option:: time <command> [<args>...]
 
   Run command and display elapsed time.
diff --git a/Help/release/3.20.rst b/Help/release/3.20.rst
index 42e95beec4..71f47c4fe0 100644
--- a/Help/release/3.20.rst
+++ b/Help/release/3.20.rst
@@ -217,8 +217,8 @@ Autogen
 CTest
 -----
 
-* :manual:`ctest(1)` gained a ``--test-dir`` option to specify the directory
-  in which to look for tests.
+* :manual:`ctest(1)` gained a :option:`--test-dir <ctest --test-dir>`
+  option to specify the directory in which to look for tests.
 
 CPack
 -----
diff --git a/Help/release/3.21.rst b/Help/release/3.21.rst
index 462d2be815..91c3768e66 100644
--- a/Help/release/3.21.rst
+++ b/Help/release/3.21.rst
@@ -49,15 +49,15 @@ Languages
 Command-Line
 ------------
 
-* :manual:`cmake(1)` gained the ``--install-prefix <dir>``
+* :manual:`cmake(1)` gained the :option:`--install-prefix <cmake --install-prefix>`
   command-line option to specify the location of the install prefix.
 
-* :manual:`cmake(1)` gained the ``--toolchain <path/to/file>``
+* :manual:`cmake(1)` gained the :option:`--toolchain <cmake --toolchain>`
   command-line option to specify a toolchain file.
 
-* :manual:`cmake(1)` ``-E capabilities`` output, for some generators,
-  may now contain a ``supportedPlatforms`` field listing platforms
-  known to be supported in :variable:`CMAKE_GENERATOR_PLATFORM`.
+* :manual:`cmake(1)` :option:`-E capabilities <cmake-E capabilities>` output,
+  for some generators, may now contain a ``supportedPlatforms`` field listing
+  platforms known to be supported in :variable:`CMAKE_GENERATOR_PLATFORM`.
 
 * Messages printed to a terminal now may be colored by message type.
 
@@ -208,8 +208,8 @@ CTest
   :prop_test:`ATTACHED_FILES_ON_FAIL` test properties.
   See :ref:`Additional Test Measurements` for more information.
 
-* :manual:`ctest(1)` gained a ``--output-junit`` option to write test results
-  to a JUnit XML file.
+* :manual:`ctest(1)` gained a :option:`--output-junit <ctest --output-junit>`
+  option to write test results to a JUnit XML file.
 
 * The :command:`ctest_build` command gained a ``PARALLEL_LEVEL`` option.
 
diff --git a/Help/release/3.23.rst b/Help/release/3.23.rst
index 209be45a64..064616b220 100644
--- a/Help/release/3.23.rst
+++ b/Help/release/3.23.rst
@@ -43,19 +43,22 @@ Generators
 Command-Line
 ------------
 
-* The :manual:`cmake(1)` ``--build`` command, when used with
+* The :manual:`cmake(1)` :option:`--build <cmake --build>` command, when used with
   :ref:`Visual Studio Generators` on projects that set the
   :prop_tgt:`VS_PACKAGE_REFERENCES` target property, now automatically
   restores package references from NuGet.  The cache variable
   :variable:`CMAKE_VS_NUGET_PACKAGE_RESTORE` may be set to toggle this behavior
-  in a build tree.  Use the ``--resolve-package-references=<on|off|only>``
+  in a build tree.  Use the
+  :option:`--resolve-package-references <cmake--build --resolve-package-references>`
   command-line option to control the behavior on one invocation.
 
-* The :manual:`cmake(1)` command line tool gained a ``--debug-find-pkg=``
+* The :manual:`cmake(1)` command line tool gained a
+  :option:`--debug-find-pkg <cmake --debug-find-pkg>`
   option to enable debug messages under specific :command:`find_package`
   calls.
 
-* The :manual:`cmake(1)` command line tool gained a ``--debug-find-var=``
+* The :manual:`cmake(1)` command line tool gained a
+  :option:`--debug-find-var <cmake --debug-find-var>`
   option to enable debug messages for ``find_*`` calls that use specific
   result variables.
 
diff --git a/Help/release/3.24.rst b/Help/release/3.24.rst
index 3857c5d269..1d331d5812 100644
--- a/Help/release/3.24.rst
+++ b/Help/release/3.24.rst
@@ -34,25 +34,28 @@ Generators
 Command-Line
 ------------
 
-* :manual:`cmake(1)` gained the ``--fresh`` command-line option to remove
-  any existing ``CMakeCache.txt`` file and associated ``CMakeFiles/``
+* :manual:`cmake(1)` gained the :option:`--fresh <cmake --fresh>` command-line
+  option to remove any existing ``CMakeCache.txt`` file and associated ``CMakeFiles/``
   directory, when configuring a build tree, thus starting a new configuration
   as if the build tree were freshly created.
 
-* :manual:`cmake(1)` gained the ``--compile-no-warning-as-error`` command-line
-  option which causes the effects of the :prop_tgt:`COMPILE_WARNING_AS_ERROR`
-  target property and :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable
-  to be ignored.
+* :manual:`cmake(1)` gained the
+  :option:`--compile-no-warning-as-error <cmake --compile-no-warning-as-error>`
+  command-line option which causes the effects of the
+  :prop_tgt:`COMPILE_WARNING_AS_ERROR` target property and
+  :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable to be ignored.
 
-* The :manual:`cmake(1)` ``--trace=json-v1`` trace format gained fields
-  ``global_frame`` and ``line_end``.
+* The :manual:`cmake(1)` :option:`--trace=json-v1 <cmake --trace>` trace
+  format gained fields ``global_frame`` and ``line_end``.
 
-* The :manual:`cmake(1)` ``-E`` commands ``cat`` and ``env`` learned to respect
-  a double dash (``--``) argument that acts as a delimiter indicating the end of
-  options. Any following arguments are treated as operands/positional arguments,
-  even if they begin with a dash ``-`` character.
+* The :manual:`cmake(1)` :option:`-E <cmake -E>` commands :option:`cat <cmake-E cat>`
+  and :option:`env <cmake-E env>` learned to respect a double dash
+  (:option:`-- <cmake-E_env -->`) argument that acts as a delimiter indicating
+  the end of options. Any following arguments are treated as operands/positional
+  arguments, even if they begin with a dash ``-`` character.
 
-* The :manual:`cmake(1)` ``-E tar`` command gained the ``--touch`` option
+* The :manual:`cmake(1)` :option:`-E tar <cmake-E tar>` command gained the
+  :option:`--touch <cmake-E_tar --touch>` option
   to keep the current local timestamp instead of extracting file timestamps
   from the archive.
 
@@ -289,9 +292,10 @@ Generator Expressions
 CTest
 -----
 
-* :manual:`ctest(1)` gained a ``--test-output-truncation`` option (and
-  corresponding :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable) to
-  specify the truncation mode once the maximum test output size has been
+* :manual:`ctest(1)` gained a
+  :option:`--test-output-truncation <ctest --test-output-truncation>` option
+  (and corresponding :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable)
+  to specify the truncation mode once the maximum test output size has been
   reached. Possible values are ``tail`` (default), ``middle`` or ``head``.
 
 CPack
diff --git a/Help/release/3.25.rst b/Help/release/3.25.rst
index 2250dd413a..9c1d96b0eb 100644
--- a/Help/release/3.25.rst
+++ b/Help/release/3.25.rst
@@ -38,8 +38,8 @@ Languages
 Command-Line
 ------------
 
-* A :ref:`cmake --workflow --preset <Workflow Mode>` mode was added
-  to drive sequences of configure, build, test, and package operations
+* A :option:`cmake --workflow --preset <cmake--workflow --preset>` mode was
+  added to drive sequences of configure, build, test, and package operations
   through a single command.
 
 * The :option:`cmake -E capabilities <cmake-E capabilities>` command