Help: Clarify 'cmake --build' signature alternatives

Documentation added by

* commit 4f4f2028b8 (Help: Add documentation for buildPresets and
                     testPresets, 2021-01-13, v3.20.0-rc1~51^2~7)
* commit 676ecf0d37 (cmake-presets: Add build and test presets,
                     2020-12-14, v3.20.0-rc1~51^2~6)

used square brackets in the `cmake --build` signature to indicate
non-optional alternatives, which is not a typical convention.
A common convention is to use parentheses instead, but in this
case it is probably clearer to list the two signatures separately.

Fixes: #22413

Help/manual/cmake.1.rst

@@ -408,7 +408,8 @@ project binary tree:
 
 .. code-block:: shell
 
-  cmake --build [<dir> | --preset <preset>] [<options>] [-- <build-tool-options>]
+  cmake --build <dir>             [<options>] [-- <build-tool-options>]
+  cmake --build --preset <preset> [<options>] [-- <build-tool-options>]
 
 This abstracts a native build tool's command-line interface with the
 following options:

Source/cmakemain.cxx

@@ -600,7 +600,10 @@ int do_build(int ac, char const* const* av)
   if (dir.empty() && presetName.empty() && !listPresets) {
     /* clang-format off */
     std::cerr <<
-      "Usage: cmake --build [<dir> | --preset <preset>] [options] [-- [native-options]]\n"
+      "Usage: cmake --build <dir>            "
+      " [options] [-- [native-options]]\n"
+      "       cmake --build --preset <preset>"
+      " [options] [-- [native-options]]\n"
       "Options:\n"
       "  <dir>          = Project binary directory to be built.\n"
       "  --preset <preset>, --preset=<preset>\n"

Tests/RunCMake/CommandLine/BuildDir--build--parallel-bad-number-stderr.txt

@@ -1,3 +1,3 @@
 ^'--parallel' invalid number '12ab' given\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build--parallel-large-stderr.txt

@@ -1,3 +1,3 @@
 ^The <jobs> value is too large\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build--parallel-no-space-bad-number-stderr.txt

@@ -1,3 +1,3 @@
 ^'--parallel' invalid number '12ab' given\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build--parallel-zero-stderr.txt

@@ -1,3 +1,3 @@
 ^The <jobs> value requires a positive integer argument\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build-jobs-bad-number-stderr.txt

@@ -1,3 +1,3 @@
 ^'-j' invalid number '12ab' given\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build-jobs-large-stderr.txt

@@ -1,3 +1,3 @@
 ^The <jobs> value is too large\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build-jobs-no-space-bad-number-stderr.txt

@@ -1,3 +1,3 @@
 ^'-j' invalid number '12ab' given\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build-jobs-zero-stderr.txt

@@ -1,3 +1,3 @@
 ^The <jobs> value requires a positive integer argument\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-first-stderr.txt

@@ -1,2 +1,2 @@
 ^Error: Building 'clean' and other targets together is not supported\.
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-second-stderr.txt

@@ -1,2 +1,2 @@
 ^Error: Building 'clean' and other targets together is not supported\.
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/build-no-dir-stderr.txt

@@ -1 +1 @@
-^Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+^Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/build-unknown-command-long-stderr.txt

@@ -1,2 +1,2 @@
 ^Unknown argument --invalid-command
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/build-unknown-command-partial-match-stderr.txt

@@ -1,2 +1,2 @@
 ^Unknown argument --targetinvalid
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/build-unknown-command-short-stderr.txt

@@ -1,2 +1,2 @@
 ^Unknown argument -invalid-command
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]