Help: Improve wording and structure related to preset includes

Encourage placing preset includes near the beginning of a preset
file and ensure the example shows that usage. Move the prose
discussing includes to its own section to improve discoverability
and break up paragraphs to make each main point harder to miss.

Also clarify ${sourceDir} to remove any ambiguity with regard to
its meaning in included files.

Issue: #23214

5 files changed, 80 insertions, 43 deletions

diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst
index 69d0543..4620984 100644
--- a/Help/manual/cmake-presets.7.rst
+++ b/Help/manual/cmake-presets.7.rst
@@ -19,28 +19,16 @@ supports files included with the ``include`` field.
 
 ``CMakePresets.json`` and ``CMakeUserPresets.json`` live in the project's root
 directory. They both have exactly the same format, and both are optional
-(though at least one must be present if ``--preset`` is specified.)
-``CMakePresets.json`` is meant to save project-wide builds, while
-``CMakeUserPresets.json`` is meant for developers to save their own local
-builds. ``CMakePresets.json`` may be checked into a version control system, and
-``CMakeUserPresets.json`` should NOT be checked in. For example, if a project
-is using Git, ``CMakePresets.json`` may be tracked, and
+(though at least one must be present if ``--preset`` is specified).
+``CMakePresets.json`` is meant to specify project-wide build details, while
+``CMakeUserPresets.json`` is meant for developers to specify their own local
+build details.
+
+``CMakePresets.json`` may be checked into a version control system, and
+``CMakeUserPresets.json`` should NOT be checked in. For example, if a
+project is using Git, ``CMakePresets.json`` may be tracked, and
 ``CMakeUserPresets.json`` should be added to the ``.gitignore``.
 
-``CMakePresets.json`` and ``CMakeUserPresets.json`` can include other files
-with the ``include`` field in file version ``4`` and later. Files included by
-these files can also include other files. If a preset file contains presets
-that inherit from presets in another file, the file must include the other file
-either directly or indirectly. Include cycles are not allowed among files (if
-``a.json`` includes ``b.json``, ``b.json`` cannot include ``a.json``). However,
-a file may be included multiple times from the same file or from different
-files. If ``CMakePresets.json`` and ``CMakeUserPresets.json`` are both present,
-``CMakeUserPresets.json`` implicitly includes ``CMakePresets.json``, even with
-no ``include`` field, in all versions of the format. Files directly or
-indirectly included from ``CMakePresets.json`` should be guaranteed to be
-provided by the project. ``CMakeUserPresets.json`` may include files from
-anywhere.
-
 Format
 ======
 
@@ -73,6 +61,13 @@ The root object recognizes the following fields:
 
     An optional integer representing the patch version.
 
+``include``
+
+  An optional array of strings representing files to include. If the filenames
+  are not absolute, they are considered relative to the current file.
+  This is allowed in preset files specifying version ``4`` or above.
+  See `Includes`_ for discussion of the constraints on included files.
+
 ``vendor``
 
   An optional map containing vendor-specific information. CMake does not
@@ -97,11 +92,25 @@ The root object recognizes the following fields:
   An optional array of `Test Preset`_ objects.
   This is allowed in preset files specifying version ``2`` or above.
 
-``include``
+Includes
+^^^^^^^^
 
-  An optional array of strings representing files to include. If the filenames
-  are not absolute, they are considered relative to the current file.
-  This is allowed in preset files specifying version ``4`` or above.
+``CMakePresets.json`` and ``CMakeUserPresets.json`` can include other files
+with the ``include`` field in file version ``4`` and later. Files included
+by these files can also include other files. If ``CMakePresets.json`` and
+``CMakeUserPresets.json`` are both present, ``CMakeUserPresets.json``
+implicitly includes ``CMakePresets.json``, even with no ``include`` field,
+in all versions of the format.
+
+If a preset file contains presets that inherit from presets in another file,
+the file must include the other file either directly or indirectly.
+Include cycles are not allowed among files. If ``a.json`` includes
+``b.json``, ``b.json`` cannot include ``a.json``. However, a file may be
+included multiple times from the same file or from different files.
+
+Files directly or indirectly included from ``CMakePresets.json`` should be
+guaranteed to be provided by the project. ``CMakeUserPresets.json`` may
+include files from anywhere.
 
 Configure Preset
 ^^^^^^^^^^^^^^^^
@@ -129,16 +138,20 @@ that may contain the following fields:
 ``inherits``
 
   An optional array of strings representing the names of presets to inherit
-  from. The preset will inherit all of the fields from the ``inherits``
+  from. This field can also be a string, which is equivalent to an array
+  containing one string.
+
+  The preset will inherit all of the fields from the ``inherits``
   presets by default (except ``name``, ``hidden``, ``inherits``,
   ``description``, and ``displayName``), but can override them as
   desired. If multiple ``inherits`` presets provide conflicting values for
   the same field, the earlier preset in the ``inherits`` list will be
-  preferred. Presets in ``CMakePresets.json`` may not inherit from presets
-  in ``CMakeUserPresets.json``.
+  preferred.
 
-  This field can also be a string, which is equivalent to an array
-  containing one string.
+  A preset can only inherit from another preset that is defined in the
+  same file or in one of the files it includes (directly or indirectly).
+  Presets in ``CMakePresets.json`` may not inherit from presets in
+  ``CMakeUserPresets.json``.
 
 ``condition``
 
@@ -371,17 +384,21 @@ that may contain the following fields:
 
 ``inherits``
 
-  An optional array of strings representing the names of presets to
-  inherit from. The preset will inherit all of the fields from the
+  An optional array of strings representing the names of presets to inherit
+  from. This field can also be a string, which is equivalent to an array
+  containing one string.
+
+  The preset will inherit all of the fields from the
   ``inherits`` presets by default (except ``name``, ``hidden``,
   ``inherits``, ``description``, and ``displayName``), but can override
   them as desired. If multiple ``inherits`` presets provide conflicting
   values for the same field, the earlier preset in the ``inherits`` list
-  will be preferred. Presets in ``CMakePresets.json`` may not inherit from
-  presets in ``CMakeUserPresets.json``.
+  will be preferred.
 
-  This field can also be a string, which is equivalent to an array
-  containing one string.
+  A preset can only inherit from another preset that is defined in the
+  same file or in one of the files it includes (directly or indirectly).
+  Presets in ``CMakePresets.json`` may not inherit from presets in
+  ``CMakeUserPresets.json``.
 
 ``condition``
 
@@ -544,17 +561,21 @@ that may contain the following fields:
 
 ``inherits``
 
-  An optional array of strings representing the names of presets to
-  inherit from. The preset will inherit all of the fields from the
+  An optional array of strings representing the names of presets to inherit
+  from. This field can also be a string, which is equivalent to an array
+  containing one string.
+
+  The preset will inherit all of the fields from the
   ``inherits`` presets by default (except ``name``, ``hidden``,
   ``inherits``, ``description``, and ``displayName``), but can override
   them as desired. If multiple ``inherits`` presets provide conflicting
   values for the same field, the earlier preset in the ``inherits`` list
-  will be preferred. Presets in ``CMakePresets.json`` may not inherit from
-  presets in ``CMakeUserPresets.json``.
+  will be preferred.
 
-  This field can also be a string, which is equivalent to an array
-  containing one string.
+  A preset can only inherit from another preset that is defined in the
+  same file or in one of the files it includes (directly or indirectly).
+  Presets in ``CMakePresets.json`` may not inherit from presets in
+  ``CMakeUserPresets.json``.
 
 ``condition``
 
@@ -1004,7 +1025,8 @@ Recognized macros include:
 
 ``${sourceDir}``
 
-  Path to the project source directory.
+  Path to the project source directory (i.e. the same as
+  :variable:`CMAKE_SOURCE_DIR`).
 
 ``${sourceParentDir}``
 
diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json
index a7ec10e..873c4ad 100644
--- a/Help/manual/presets/example.json
+++ b/Help/manual/presets/example.json
@@ -2,9 +2,13 @@
   "version": 4,
   "cmakeMinimumRequired": {
     "major": 3,
-    "minor": 21,
+    "minor": 23,
     "patch": 0
   },
+  "include": [
+    "otherThings.json",
+    "moreThings.json"
+  ],
   "configurePresets": [
     {
       "name": "default",
diff --git a/Tests/RunCMake/CMakePresets/RunCMakeTest.cmake b/Tests/RunCMake/CMakePresets/RunCMakeTest.cmake
index 51e786e..955cf53 100644
--- a/Tests/RunCMake/CMakePresets/RunCMakeTest.cmake
+++ b/Tests/RunCMake/CMakePresets/RunCMakeTest.cmake
@@ -372,4 +372,9 @@ if(CMAKE_HOST_WIN32)
 endif()
 file(WRITE "${RunCMake_BINARY_DIR}/example.json.in" "${_example}")
 set(CMakePresets_FILE "${RunCMake_BINARY_DIR}/example.json.in")
+set(CMakePresets_EXTRA_FILES
+  "${RunCMake_SOURCE_DIR}/otherThings.json.in"
+  "${RunCMake_SOURCE_DIR}/moreThings.json.in"
+)
 run_cmake_presets(DocumentationExample --preset=default)
+unset(CMakePresets_EXTRA_FILES)
diff --git a/Tests/RunCMake/CMakePresets/moreThings.json.in b/Tests/RunCMake/CMakePresets/moreThings.json.in
new file mode 100644
index 0000000..61a2092
--- /dev/null
+++ b/Tests/RunCMake/CMakePresets/moreThings.json.in
@@ -0,0 +1,3 @@
+{
+  "version": 1
+}
diff --git a/Tests/RunCMake/CMakePresets/otherThings.json.in b/Tests/RunCMake/CMakePresets/otherThings.json.in
new file mode 100644
index 0000000..61a2092
--- /dev/null
+++ b/Tests/RunCMake/CMakePresets/otherThings.json.in
@@ -0,0 +1,3 @@
+{
+  "version": 1
+}