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

16 files changed, 20 insertions, 16 deletions

diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 2d639b6..e23ddd8 100644
--- a/Help/manual/cmake.1.rst
+++ b/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:
diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx
index d83183f..1725375 100644
--- a/Source/cmakemain.cxx
+++ b/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"
diff --git a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-bad-number-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build--parallel-bad-number-stderr.txt
index 16f8be8..96de4d1 100644
--- a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-bad-number-stderr.txt
+++ b/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\]\]
diff --git a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-large-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build--parallel-large-stderr.txt
index e7b9aaa..0bb806f 100644
--- a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-large-stderr.txt
+++ b/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\]\]
diff --git a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-no-space-bad-number-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build--parallel-no-space-bad-number-stderr.txt
index 16f8be8..96de4d1 100644
--- a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-no-space-bad-number-stderr.txt
+++ b/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\]\]
diff --git a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-zero-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build--parallel-zero-stderr.txt
index d1241f4..b965d4a 100644
--- a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-zero-stderr.txt
+++ b/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\]\]
diff --git a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-bad-number-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build-jobs-bad-number-stderr.txt
index d52b165..97e90ec 100644
--- a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-bad-number-stderr.txt
+++ b/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\]\]
diff --git a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-large-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build-jobs-large-stderr.txt
index e7b9aaa..0bb806f 100644
--- a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-large-stderr.txt
+++ b/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\]\]
diff --git a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-no-space-bad-number-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build-jobs-no-space-bad-number-stderr.txt
index d52b165..97e90ec 100644
--- a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-no-space-bad-number-stderr.txt
+++ b/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\]\]
diff --git a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-zero-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build-jobs-zero-stderr.txt
index d1241f4..b965d4a 100644
--- a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-zero-stderr.txt
+++ b/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\]\]
diff --git a/Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-first-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-first-stderr.txt
index 2dd9bc4..c15fdba 100644
--- a/Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-first-stderr.txt
+++ b/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\]\]
diff --git a/Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-second-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-second-stderr.txt
index 2dd9bc4..c15fdba 100644
--- a/Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-second-stderr.txt
+++ b/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\]\]
diff --git a/Tests/RunCMake/CommandLine/build-no-dir-stderr.txt b/Tests/RunCMake/CommandLine/build-no-dir-stderr.txt
index 9b4d26b..4811bea 100644
--- a/Tests/RunCMake/CommandLine/build-no-dir-stderr.txt
+++ b/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\]\]
diff --git a/Tests/RunCMake/CommandLine/build-unknown-command-long-stderr.txt b/Tests/RunCMake/CommandLine/build-unknown-command-long-stderr.txt
index c8f1a03..559e4b6 100644
--- a/Tests/RunCMake/CommandLine/build-unknown-command-long-stderr.txt
+++ b/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\]\]
diff --git a/Tests/RunCMake/CommandLine/build-unknown-command-partial-match-stderr.txt b/Tests/RunCMake/CommandLine/build-unknown-command-partial-match-stderr.txt
index e4ad6b2..1f44c4e 100644
--- a/Tests/RunCMake/CommandLine/build-unknown-command-partial-match-stderr.txt
+++ b/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\]\]
diff --git a/Tests/RunCMake/CommandLine/build-unknown-command-short-stderr.txt b/Tests/RunCMake/CommandLine/build-unknown-command-short-stderr.txt
index a6cfece..4f5ba55 100644
--- a/Tests/RunCMake/CommandLine/build-unknown-command-short-stderr.txt
+++ b/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\]\]