Help: Disambiguate cmake(1) program modes in Sphinx option references

Define the entry point to each mode as an option for the `cmake`
program, but reference the options for that mode as part of stand-in
`cmake-<mode>` programs.

13 files changed, 64 insertions, 30 deletions

diff --git a/Help/command/install.rst b/Help/command/install.rst
index 45da99b..feff436 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -968,7 +968,7 @@ Generated Installation Script
 The ``install()`` command generates a file, ``cmake_install.cmake``, inside
 the build directory, which is used internally by the generated install target
 and by CPack. You can also invoke this script manually with
-:option:`cmake -P <cmake_P -P>`. This script accepts several variables:
+:option:`cmake -P`. This script accepts several variables:
 
 ``COMPONENT``
   Set this variable to install only a single CPack component as opposed to all
diff --git a/Help/envvar/DESTDIR.rst b/Help/envvar/DESTDIR.rst
index 414db12..dec8430 100644
--- a/Help/envvar/DESTDIR.rst
+++ b/Help/envvar/DESTDIR.rst
@@ -22,7 +22,7 @@ See the :variable:`CMAKE_INSTALL_PREFIX` variable to control the
 installation prefix when configuring a build tree.  Or, when using
 the :manual:`cmake(1)` command-line tool's :option:`--install <cmake --install>`
 mode, one may specify a different prefix using the
-:option:`--prefix <cmake --prefix>` option.
+:option:`--prefix <cmake--install --prefix>` option.
 
 .. note::
 
diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst
index ae075ed..2cf823a 100644
--- a/Help/generator/Ninja Multi-Config.rst
+++ b/Help/generator/Ninja Multi-Config.rst
@@ -20,8 +20,8 @@ are intended to be run with ``ninja -f build-<Config>.ninja``. A
 :variable:`CMAKE_CONFIGURATION_TYPES`.
 
 ``cmake --build . --config <Config>`` will always use ``build-<Config>.ninja``
-to build. If no :option:`--config <cmake --config>` argument is specified,
-:option:`cmake --build .<cmake --build>` will use ``build.ninja``.
+to build. If no :option:`--config <cmake--build --config>` argument is
+specified, :option:`cmake --build . <cmake --build>` will use ``build.ninja``.
 
 Each ``build-<Config>.ninja`` file contains ``<target>`` targets as well as
 ``<target>:<Config>`` targets, where ``<Config>`` is the same as the
diff --git a/Help/guide/user-interaction/index.rst b/Help/guide/user-interaction/index.rst
index 9cc5816..3355992 100644
--- a/Help/guide/user-interaction/index.rst
+++ b/Help/guide/user-interaction/index.rst
@@ -511,7 +511,7 @@ command associated with the
 the build tool configured by the user.
 
 The :option:`--build <cmake --build>` mode also accepts
-the parameter :option:`--target <cmake --target>` to
+the parameter :option:`--target <cmake--build --target>` to
 specify a particular target to build, for example a
 particular library, executable or custom target, or a
 particular special target like ``install``:
@@ -521,7 +521,7 @@ particular special target like ``install``:
   $ cmake --build . --target myexe
 
 The :option:`--build <cmake --build>` mode also accepts a
-:option:`--config <cmake --config>` parameter
+:option:`--config <cmake--build --config>` parameter
 in the case of multi-config generators to specify which
 particular configuration to build:
 
@@ -529,13 +529,13 @@ particular configuration to build:
 
   $ cmake --build . --target myexe --config Release
 
-The :option:`--config <cmake --config>` option has no
+The :option:`--config <cmake--build --config>` option has no
 effect if the generator generates a buildsystem specific
 to a configuration which is chosen when invoking cmake
 with the :variable:`CMAKE_BUILD_TYPE` variable.
 
 Some buildsystems omit details of command lines invoked
-during the build.  The :option:`-verbose <cmake --verbose>`
+during the build.  The :option:`--verbose <cmake--build --verbose>`
 flag can be used to cause those command lines to be shown:
 
 .. code-block:: console
diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst
index 93f929e..eb3e460 100644
--- a/Help/manual/cmake-presets.7.rst
+++ b/Help/manual/cmake-presets.7.rst
@@ -460,21 +460,21 @@ that may contain the following fields:
 
 ``jobs``
   An optional integer. Equivalent to passing
-  :option:`--parallel <cmake --parallel>` or ``-j`` on the command line.
+  :option:`--parallel <cmake--build --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.
+  :option:`--target <cmake--build --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.
+  An optional string. Equivalent to passing
+  :option:`--config <cmake--build --config>` on the command line.
 
 ``cleanFirst``
   An optional bool. If true, equivalent to passing
-  :option:`--clean-first <cmake --clean-first>` on the command line.
+  :option:`--clean-first <cmake--build --clean-first>` on the command line.
 
 ``resolvePackageReferences``
   An optional string that specifies the package resolve mode. This is
@@ -498,7 +498,7 @@ that may contain the following fields:
   .. note::
 
     The command line parameter
-    :option:`--resolve-package-references <cmake --resolve-package-references>`
+    :option:`--resolve-package-references <cmake--build --resolve-package-references>`
     will take priority over this setting. If the command line parameter is not
     provided and this setting is not specified, an environment-specific cache
     variable will be evaluated to decide, if package restoration should be
@@ -512,7 +512,7 @@ that may contain the following fields:
 
 ``verbose``
   An optional bool. If true, equivalent to passing
-  :option:`--verbose <cmake --verbose>` on the command line.
+  :option:`--verbose <cmake--build --verbose>` on the command line.
 
 ``nativeToolOptions``
   An optional array of strings. Equivalent to passing options after ``--``
@@ -981,6 +981,8 @@ fields:
 ``vendorName``
   An optional string representing the vendor name.
 
+.. _`Workflow Preset`:
+
 Workflow Preset
 ^^^^^^^^^^^^^^^
 
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 868dac4..d22317e 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -516,6 +516,8 @@ Options
 Build a Project
 ===============
 
+.. program:: cmake
+
 CMake provides a command-line signature to build an already-generated
 project binary tree:
 
@@ -532,6 +534,8 @@ following options:
   Project binary directory to be built.  This is required (unless a preset
   is specified) and must be first.
 
+.. program:: cmake--build
+
 .. option:: --preset <preset>, --preset=<preset>
 
   Use a build preset to specify build options. The project binary directory
@@ -567,7 +571,7 @@ following options:
 .. option:: --clean-first
 
   Build target ``clean`` first, then build.
-  (To clean only, use :option:`--target clean <cmake --target>`.)
+  (To clean only, use :option:`--target clean <cmake--build --target>`.)
 
 .. option:: --resolve-package-references=<value>
 
@@ -616,6 +620,8 @@ Run :option:`cmake --build` with no options for quick help.
 Install a Project
 =================
 
+.. program:: cmake
+
 CMake provides a command-line signature to install an already-generated
 project binary tree:
 
@@ -631,6 +637,8 @@ The options are:
 
   Project binary directory to install. This is required and must be first.
 
+.. program:: cmake--install
+
 .. option:: --config <cfg>
 
   For multi-configuration generators, choose configuration ``<cfg>``.
@@ -662,6 +670,8 @@ Run :option:`cmake --install` with no options for quick help.
 Open a Project
 ==============
 
+.. program:: cmake
+
 .. code-block:: shell
 
   cmake --open <dir>
@@ -675,16 +685,20 @@ supported by some generators.
 Run a Script
 ============
 
-.. program:: cmake_P
+.. program:: cmake
 
 .. code-block:: shell
 
   cmake [-D <var>=<value>]... -P <cmake-script-file> [-- <unparsed-options>...]
 
+.. program:: cmake-P
+
 .. option:: -D <var>=<value>
 
  Define a variable for script mode.
 
+.. program:: cmake
+
 .. option:: -P <cmake-script-file>
 
  Process the given cmake file as a script written in the CMake
@@ -702,7 +716,7 @@ script (including the ``--`` itself).
 Run a Command-Line Tool
 =======================
 
-.. program:: cmake_E
+.. program:: cmake
 
 CMake provides builtin command-line tools through the signature
 
@@ -714,6 +728,8 @@ CMake provides builtin command-line tools through the signature
 
   Run ``cmake -E`` or ``cmake -E help`` for a summary of commands.
 
+.. program:: cmake-E
+
 Available commands are:
 
 .. option:: capabilities
@@ -1169,6 +1185,8 @@ The following ``cmake -E`` commands are available only on Windows:
 Run the Find-Package Tool
 =========================
 
+.. program:: cmake--find-package
+
 CMake provides a pkg-config like helper for Makefile-based projects:
 
 .. code-block:: shell
@@ -1189,9 +1207,23 @@ autoconf-based projects (via ``share/aclocal/cmake.m4``).
 Run a Workflow Preset
 =====================
 
+.. program:: cmake
+
 :manual:`CMake Presets <cmake-presets(7)>` provides a way to execute multiple
 build steps in order:
 
+.. code-block:: shell
+
+  cmake --workflow [<options>]
+
+The options are:
+
+.. option:: --workflow
+
+  Select a :ref:`Workflow Preset` using one of the following options.
+
+.. program:: cmake--workflow
+
 .. option:: --preset <preset>, --preset=<preset>
 
   Use a workflow preset to specify a workflow. The project binary directory
@@ -1207,6 +1239,8 @@ build steps in order:
 View Help
 =========
 
+.. program:: cmake
+
 To print selected pages from the CMake documentation, use
 
 .. code-block:: shell
@@ -1215,8 +1249,6 @@ To print selected pages from the CMake documentation, use
 
 with one of the following options:
 
-.. program:: cmake
-
 .. include:: OPTIONS_HELP.txt
 
 To view the presets available for a project, use
diff --git a/Help/release/dev/cmake-E-env-modify.rst b/Help/release/dev/cmake-E-env-modify.rst
index ea4a622..08f1fb5 100644
--- a/Help/release/dev/cmake-E-env-modify.rst
+++ b/Help/release/dev/cmake-E-env-modify.rst
@@ -1,5 +1,5 @@
 cmake-E-env-modify
 ------------------
 
-* A new ``--modify`` flag was added to :option:`cmake -E env <cmake_E env>` to support :prop_test:`ENVIRONMENT_MODIFICATION`
-  operations.
+* A new ``--modify`` flag was added to :option:`cmake -E env <cmake-E env>` to
+  support :prop_test:`ENVIRONMENT_MODIFICATION` operations.
diff --git a/Help/variable/CMAKE_BINARY_DIR.rst b/Help/variable/CMAKE_BINARY_DIR.rst
index f9c7689..e601eb8 100644
--- a/Help/variable/CMAKE_BINARY_DIR.rst
+++ b/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 :option:`-P <cmake_P -P>` script mode, CMake sets the variables
+When run in :option:`cmake -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.
diff --git a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst
index 6f82dcc..15f81d2 100644
--- a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst
+++ b/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 :option:`-P <cmake_P -P>` script mode, CMake sets the variables
+When run in :option:`cmake -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.
diff --git a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst
index 0678f99..5b86026 100644
--- a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst
+++ b/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 :option:`-P <cmake_P -P>` script mode, CMake sets the variables
+When run in :option:`cmake -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.
diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst
index 1636739..c76727e 100644
--- a/Help/variable/CMAKE_INSTALL_PREFIX.rst
+++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst
@@ -27,8 +27,8 @@ 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 :option:`--install <cmake --install>` mode, one may
-specify a different prefix using the :option:`--prefix <cmake --prefix>`
+command-line tool's :option:`--install <cmake --install>` mode, one may specify
+a different prefix using the :option:`--prefix <cmake--install --prefix>`
 option:
 
 .. code-block:: shell
diff --git a/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst b/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst
index 104f4ac..313fb4e 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 :option:`cmake -P <cmake_P -P>` script file currently being
+Full path to the :option:`cmake -P` script file currently being
 processed.
 
-When run in :option:`cmake -P <cmake_P -P>` script mode, CMake sets this variable to
+When run in :option:`cmake -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_SOURCE_DIR.rst b/Help/variable/CMAKE_SOURCE_DIR.rst
index 32e6e90..7210f75 100644
--- a/Help/variable/CMAKE_SOURCE_DIR.rst
+++ b/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 :option:`-P <cmake_P -P>` script mode, CMake sets the variables
+When run in :option:`cmake -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.