From f0e60ea867f8ac96fd855754b9f71329d36f7e52 Mon Sep 17 00:00:00 2001
From: scivision <scivision@users.noreply.github.com>
Date: Fri, 17 Feb 2023 09:53:05 -0500
Subject: Help: cmake (1): put modern configure signature first

recommend compact, most robust signature first. So many people are
still using the multi-step pre-3.13 way of initializing a build.
Rather than simply

  cmake -Bbuild

which is one step instead of 3 just to configure a new project.
---
 Help/manual/ccmake.1.rst    |  1 +
 Help/manual/cmake-gui.1.rst |  2 +-
 Help/manual/cmake.1.rst     | 36 ++++++++++++++++++------------------
 3 files changed, 20 insertions(+), 19 deletions(-)

diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst
index a09857b..5b118d1 100644
--- a/Help/manual/ccmake.1.rst
+++ b/Help/manual/ccmake.1.rst
@@ -8,6 +8,7 @@ Synopsis
 
 .. parsed-literal::
 
+ ccmake [<options>] -B <path-to-build> [-S <path-to-source>]
  ccmake [<options>] <path-to-source | path-to-existing-build>
 
 Description
diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst
index 367b0a7..26083ca 100644
--- a/Help/manual/cmake-gui.1.rst
+++ b/Help/manual/cmake-gui.1.rst
@@ -9,8 +9,8 @@ Synopsis
 .. parsed-literal::
 
  cmake-gui [<options>]
+ cmake-gui [<options>] -B <path-to-build> [-S <path-to-source>]
  cmake-gui [<options>] <path-to-source | path-to-existing-build>
- cmake-gui [<options>] -S <path-to-source> -B <path-to-build>
  cmake-gui [<options>] --browse-manual [<filename>]
 
 Description
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index a107c66..1ea7626 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -9,8 +9,8 @@ Synopsis
 .. parsed-literal::
 
  `Generate a Project Buildsystem`_
+  cmake [<options>] -B <path-to-build> [-S <path-to-source>]
   cmake [<options>] <path-to-source | path-to-existing-build>
-  cmake [<options>] -S <path-to-source> -B <path-to-build>
 
  `Build a Project`_
   cmake --build <dir> [<options>] [-- <build-tool-options>]
@@ -116,6 +116,20 @@ Generate a Project Buildsystem
 Run CMake with one of the following command signatures to specify the
 source and build trees and generate a buildsystem:
 
+``cmake [<options>] -B <path-to-build> [-S <path-to-source>]``
+
+  .. versionadded:: 3.13
+
+  Uses ``<path-to-build>`` as the build tree and ``<path-to-source>``
+  as the source tree.  The specified paths may be absolute or relative
+  to the current working directory.  The source tree must contain a
+  ``CMakeLists.txt`` file.  The build tree will be created automatically
+  if it does not already exist.  For example:
+
+  .. code-block:: console
+
+    $ cmake -S src -B build
+
 ``cmake [<options>] <path-to-source>``
   Uses the current working directory as the build tree, and
   ``<path-to-source>`` as the source tree.  The specified path may
@@ -141,20 +155,6 @@ source and build trees and generate a buildsystem:
     $ cd build
     $ cmake .
 
-``cmake [<options>] -S <path-to-source> -B <path-to-build>``
-
-  .. versionadded:: 3.13
-
-  Uses ``<path-to-build>`` as the build tree and ``<path-to-source>``
-  as the source tree.  The specified paths may be absolute or relative
-  to the current working directory.  The source tree must contain a
-  ``CMakeLists.txt`` file.  The build tree will be created automatically
-  if it does not already exist.  For example:
-
-  .. code-block:: console
-
-    $ cmake -S src -B build
-
 In all cases the ``<options>`` may be zero or more of the `Options`_ below.
 
 The above styles for specifying the source and build trees may be mixed.
@@ -167,14 +167,14 @@ the current working directory (cwd) is used for the other.  For example:
 ============================== ============ ===========
  Command Line                   Source Dir   Build Dir
 ============================== ============ ===========
+ ``cmake -B build``             `cwd`        ``build``
+ ``cmake -B build src``         ``src``      ``build``
+ ``cmake -B build -S src``      ``src``      ``build``
  ``cmake src``                  ``src``      `cwd`
  ``cmake build`` (existing)     `loaded`     ``build``
  ``cmake -S src``               ``src``      `cwd`
  ``cmake -S src build``         ``src``      ``build``
  ``cmake -S src -B build``      ``src``      ``build``
- ``cmake -B build``             `cwd`        ``build``
- ``cmake -B build src``         ``src``      ``build``
- ``cmake -B build -S src``      ``src``      ``build``
 ============================== ============ ===========
 
 .. versionchanged:: 3.23
-- 
cgit v0.12


From 6f354a6d573104260b3bc801f7e9a527404280cb Mon Sep 17 00:00:00 2001
From: scivision <scivision@users.noreply.github.com>
Date: Fri, 17 Feb 2023 10:10:05 -0500
Subject: Help: ctest(1): emphasize the --test-dir option

it seems few people know of this option
and needlessly add extra shell commands to change directory.
---
 Help/manual/ctest.1.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst
index 5e82faa..994ae47 100644
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -11,7 +11,7 @@ Synopsis
 .. parsed-literal::
 
  `Run Tests`_
-  ctest [<options>]
+  ctest [<options>] [--test-dir <path-to-build>]
 
  `Build and Test Mode`_
   ctest --build-and-test <path-to-source> <path-to-build>
@@ -354,7 +354,8 @@ Run Tests
 
 .. option:: --test-dir <dir>
 
- Specify the directory in which to look for tests.
+ Specify the directory in which to look for tests, typically a CMake project
+ build directory. If not specified, the current directory is used.
 
 .. option:: --test-output-size-passed <size>
 
-- 
cgit v0.12