Merge topic 'doc-presets'

47ab2d4d2e Help: Clarify role of binaryDir inheritance in cmake-presets(7)
0e3c361f77 Help: Link to tool-specific preset arguments from cmake-presets(7)
dd6165fbd4 Help: Mention version 2 in cmake-presets(7)
cdbd1ae64b Utilities/Sphinx: Avoid converting -- to an en-dash

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

2 files changed, 20 insertions, 12 deletions

diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst
index 49eb157..e3815b6 100644
--- a/Help/manual/cmake-presets.7.rst
+++ b/Help/manual/cmake-presets.7.rst
@@ -38,8 +38,8 @@ The root object recognizes the following fields:
 
 ``version``
 
-  A required integer representing the version of the JSON schema. Currently,
-  the only supported version is 1.
+  A required integer representing the version of the JSON schema.
+  The supported versions are ``1`` and ``2``.
 
 ``cmakeMinimumRequired``
 
@@ -70,14 +70,17 @@ The root object recognizes the following fields:
 ``configurePresets``
 
   An optional array of `Configure Preset`_ objects.
+  This is allowed in preset files specifying version 1 or above.
 
 ``buildPresets``
 
   An optional array of `Build Preset`_ objects.
+  This is allowed in preset files specifying version 2 or above.
 
 ``testPresets``
 
   An optional array of `Test Preset`_ objects.
+  This is allowed in preset files specifying version 2 or above.
 
 Configure Preset
 ^^^^^^^^^^^^^^^^
@@ -88,8 +91,8 @@ that may contain the following fields:
 ``name``
 
   A required string representing the machine-friendly name of the preset.
-  This identifier is used in the ``--preset`` argument. There must not be
-  two presets in the union of ``CMakePresets.json`` and
+  This identifier is used in the :ref:`cmake --preset <CMake Options>` option.
+  There must not be two presets in the union of ``CMakePresets.json`` and
   ``CMakeUserPresets.json`` in the same directory with the same name.
 
 ``hidden``
@@ -306,8 +309,9 @@ that may contain the following fields:
 ``name``
 
   A required string representing the machine-friendly name of the preset.
-  This identifier is used in the ``--preset`` argument. There must not be
-  two presets (configure, build, or test) in the union of
+  This identifier is used in the
+  :ref:`cmake --build --preset <Build Tool Mode>` option.
+  There must not be two presets (configure, build, or test) in the union of
   ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same
   directory with the same name.
 
@@ -373,8 +377,9 @@ that may contain the following fields:
   An optional string specifying the name of a configure preset to
   associate with this build preset. If ``configurePreset`` is not
   specified, it must be inherited from the inherits preset (unless this
-  preset is hidden). The build tree directory is inferred from the
-  configure preset.
+  preset is hidden). The build directory is inferred from the configure
+  preset, so the build will take place in the same ``binaryDir`` that the
+  configuration did.
 
 ``inheritConfigureEnvironment``
 
@@ -424,8 +429,8 @@ that may contain the following fields:
 ``name``
 
   A required string representing the machine-friendly name of the preset.
-  This identifier is used in the ``--preset`` argument. There must not be
-  two presets (configure, build, or test) in the union of
+  This identifier is used in the :ref:`ctest --preset <CTest Options>` option.
+  There must not be two presets (configure, build, or test) in the union of
   ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same
   directory with the same name.
 
@@ -491,8 +496,9 @@ that may contain the following fields:
   An optional string specifying the name of a configure preset to
   associate with this test preset. If ``configurePreset`` is not
   specified, it must be inherited from the inherits preset (unless this
-  preset is hidden). The build tree directory is inferred from the
-  configure preset.
+  preset is hidden). The build directory is inferred from the configure
+  preset, so tests will run in the same ``binaryDir`` that the
+  configuration did and build did.
 
 ``inheritConfigureEnvironment``
 
diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst
index 43157b6..0a3614f 100644
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -25,6 +25,8 @@ CMake-generated build trees created for projects that use the
 :command:`enable_testing` and :command:`add_test` commands have testing support.
 This program will run the tests and report results.
 
+.. _`CTest Options`:
+
 Options
 =======