Help: Add section heading for configure presets in cmake-presets(7)

Cross-reference it from the main `configurePresets` field.
This removes an extra layer of indentation and makes the
section linkable.

1 files changed, 154 insertions, 149 deletions

diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst
index 1d990a1086..d60f372ef2 100644
--- a/Help/manual/cmake-presets.7.rst
+++ b/Help/manual/cmake-presets.7.rst
@@ -69,221 +69,226 @@ The root object recognizes the following fields:
 
 ``configurePresets``
 
-  An optional array of configure preset objects. Each preset may contain the
-  following fields:
+  An optional array of `Configure Preset`_ objects.
+
+Configure Preset
+^^^^^^^^^^^^^^^^
+
+Each entry of the ``configurePresets`` array is a JSON object
+that may contain the following fields:
 
-  ``name``
+``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
-    ``CMakeUserPresets.json`` in the same directory with the same 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
+  ``CMakeUserPresets.json`` in the same directory with the same name.
 
-  ``hidden``
+``hidden``
 
-    An optional boolean specifying whether or not a preset should be hidden.
-    If a preset is hidden, it cannot be used in the ``--preset=`` argument,
-    will not show up in the :manual:`CMake GUI <cmake-gui(1)>`, and does not
-    have to have a valid ``generator`` or ``binaryDir``, even from
-    inheritance. ``hidden`` presets are intended to be used as a base for
-    other presets to inherit via the ``inherits`` field.
+  An optional boolean specifying whether or not a preset should be hidden.
+  If a preset is hidden, it cannot be used in the ``--preset=`` argument,
+  will not show up in the :manual:`CMake GUI <cmake-gui(1)>`, and does not
+  have to have a valid ``generator`` or ``binaryDir``, even from
+  inheritance. ``hidden`` presets are intended to be used as a base for
+  other presets to inherit via the ``inherits`` field.
 
-  ``inherits``
+``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``
-    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``.
+  An optional array of strings representing the names of presets to inherit
+  from. 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``.
 
-    This field can also be a string, which is equivalent to an array
-    containing one string.
+  This field can also be a string, which is equivalent to an array
+  containing one string.
 
-  ``vendor``
+``vendor``
 
-    An optional map containing vendor-specific information. CMake does not
-    interpret the contents of this field except to verify that it is a map
-    if it does exist. However, it should follow the same conventions as the
-    root-level ``vendor`` field. If vendors use their own per-preset
-    ``vendor`` field, they should implement inheritance in a sensible manner
-    when appropriate.
+  An optional map containing vendor-specific information. CMake does not
+  interpret the contents of this field except to verify that it is a map
+  if it does exist. However, it should follow the same conventions as the
+  root-level ``vendor`` field. If vendors use their own per-preset
+  ``vendor`` field, they should implement inheritance in a sensible manner
+  when appropriate.
 
-  ``displayName``
+``displayName``
 
-    An optional string with a human-friendly name of the preset.
+  An optional string with a human-friendly name of the preset.
 
-  ``description``
+``description``
 
-    An optional string with a human-friendly description of the preset.
+  An optional string with a human-friendly description of the preset.
 
-  ``generator``
+``generator``
 
-    An optional string representing the generator to use for the preset. If
-    ``generator`` is not specified, it must be inherited from the
-    ``inherits`` preset (unless this preset is ``hidden``).
+  An optional string representing the generator to use for the preset. If
+  ``generator`` is not specified, it must be inherited from the
+  ``inherits`` preset (unless this preset is ``hidden``).
 
-    Note that for Visual Studio generators, unlike in the command line ``-G``
-    argument, you cannot include the platform name in the generator name. Use
-    the ``architecture`` field instead.
+  Note that for Visual Studio generators, unlike in the command line ``-G``
+  argument, you cannot include the platform name in the generator name. Use
+  the ``architecture`` field instead.
 
-  ``architecture``
-  ``toolset``
+``architecture``
+``toolset``
 
-    Optional fields representing the platform and toolset, respectively, for
-    generators that support them. Each may be either a string or an object
-    with the following fields:
+  Optional fields representing the platform and toolset, respectively, for
+  generators that support them. Each may be either a string or an object
+  with the following fields:
 
-    ``value``
+  ``value``
 
-      An optional string representing the value.
+    An optional string representing the value.
 
-    ``strategy``
+  ``strategy``
 
-      An optional string telling CMake how to handle the ``architecture`` or
-      ``toolset`` field. Valid values are:
+    An optional string telling CMake how to handle the ``architecture`` or
+    ``toolset`` field. Valid values are:
 
-      ``"set"``
+    ``"set"``
 
-        Set the respective value. This will result in an error for generators
-        that do not support the respective field.
+      Set the respective value. This will result in an error for generators
+      that do not support the respective field.
 
-      ``"external"``
+    ``"external"``
 
-        Do not set the value, even if the generator supports it. This is
-        useful if, for example, a preset uses the Ninja generator, and an IDE
-        knows how to set up the Visual C++ environment from the
-        ``architecture`` and ``toolset`` fields. In that case, CMake will
-        ignore the field, but the IDE can use them to set up the environment
-        before invoking CMake.
+      Do not set the value, even if the generator supports it. This is
+      useful if, for example, a preset uses the Ninja generator, and an IDE
+      knows how to set up the Visual C++ environment from the
+      ``architecture`` and ``toolset`` fields. In that case, CMake will
+      ignore the field, but the IDE can use them to set up the environment
+      before invoking CMake.
 
-  ``binaryDir``
+``binaryDir``
 
-    An optional string representing the path to the output binary directory.
-    This field supports `macro expansion`_. If a relative path is specified,
-    it is calculated relative to the source directory. If ``binaryDir`` is not
-    specified, it must be inherited from the ``inherits`` preset (unless this
-    preset is ``hidden``).
+  An optional string representing the path to the output binary directory.
+  This field supports `macro expansion`_. If a relative path is specified,
+  it is calculated relative to the source directory. If ``binaryDir`` is not
+  specified, it must be inherited from the ``inherits`` preset (unless this
+  preset is ``hidden``).
 
-  ``cmakeExecutable``
+``cmakeExecutable``
 
-    An optional string representing the path to the CMake executable to use
-    for this preset. This is reserved for use by IDEs, and is not used by
-    CMake itself. IDEs that use this field should expand any macros in it.
+  An optional string representing the path to the CMake executable to use
+  for this preset. This is reserved for use by IDEs, and is not used by
+  CMake itself. IDEs that use this field should expand any macros in it.
 
-  ``cacheVariables``
+``cacheVariables``
 
-    An optional map of cache variables. The key is the variable name (which
-    may not be an empty string), and the value is either ``null``, a boolean
-    (which is equivalent to a value of ``"TRUE"`` or ``"FALSE"`` and a type
-    of ``BOOL``), a string representing the value of the variable (which
-    supports `macro expansion`_), or an object with the following fields:
+  An optional map of cache variables. The key is the variable name (which
+  may not be an empty string), and the value is either ``null``, a boolean
+  (which is equivalent to a value of ``"TRUE"`` or ``"FALSE"`` and a type
+  of ``BOOL``), a string representing the value of the variable (which
+  supports `macro expansion`_), or an object with the following fields:
 
-    ``type``
+  ``type``
 
-      An optional string representing the type of the variable.
+    An optional string representing the type of the variable.
 
-    ``value``
+  ``value``
 
-      A required string or boolean representing the value of the variable.
-      A boolean is equivalent to ``"TRUE"`` or ``"FALSE"``. This field
-      supports `macro expansion`_.
+    A required string or boolean representing the value of the variable.
+    A boolean is equivalent to ``"TRUE"`` or ``"FALSE"``. This field
+    supports `macro expansion`_.
 
-    Cache variables are inherited through the ``inherits`` field, and the
-    preset's variables will be the union of its own ``cacheVariables`` and
-    the ``cacheVariables`` from all its parents. If multiple presets in this
-    union define the same variable, the standard rules of ``inherits`` are
-    applied. Setting a variable to ``null`` causes it to not be set, even if
-    a value was inherited from another preset.
+  Cache variables are inherited through the ``inherits`` field, and the
+  preset's variables will be the union of its own ``cacheVariables`` and
+  the ``cacheVariables`` from all its parents. If multiple presets in this
+  union define the same variable, the standard rules of ``inherits`` are
+  applied. Setting a variable to ``null`` causes it to not be set, even if
+  a value was inherited from another preset.
 
-  ``environment``
+``environment``
 
-    An optional map of environment variables. The key is the variable name
-    (which may not be an empty string), and the value is either ``null`` or
-    a string representing the value of the variable. Each variable is set
-    regardless of whether or not a value was given to it by the process's
-    environment. This field supports `macro expansion`_, and environment
-    variables in this map may reference each other, and may be listed in any
-    order, as long as such references do not cause a cycle (for example,
-    if ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
+  An optional map of environment variables. The key is the variable name
+  (which may not be an empty string), and the value is either ``null`` or
+  a string representing the value of the variable. Each variable is set
+  regardless of whether or not a value was given to it by the process's
+  environment. This field supports `macro expansion`_, and environment
+  variables in this map may reference each other, and may be listed in any
+  order, as long as such references do not cause a cycle (for example,
+  if ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
 
-    Environment variables are inherited through the ``inherits`` field, and
-    the preset's environment will be the union of its own ``environment`` and
-    the ``environment`` from all its parents. If multiple presets in this
-    union define the same variable, the standard rules of ``inherits`` are
-    applied. Setting a variable to ``null`` causes it to not be set, even if
-    a value was inherited from another preset.
+  Environment variables are inherited through the ``inherits`` field, and
+  the preset's environment will be the union of its own ``environment`` and
+  the ``environment`` from all its parents. If multiple presets in this
+  union define the same variable, the standard rules of ``inherits`` are
+  applied. Setting a variable to ``null`` causes it to not be set, even if
+  a value was inherited from another preset.
 
-  ``warnings``
+``warnings``
 
-    An optional object specifying the warnings to enable. The object may
-    contain the following fields:
+  An optional object specifying the warnings to enable. The object may
+  contain the following fields:
 
-    ``dev``
+  ``dev``
 
-      An optional boolean. Equivalent to passing ``-Wdev`` or ``-Wno-dev``
-      on the command line. This may not be set to ``false`` if ``errors.dev``
-      is set to ``true``.
+    An optional boolean. Equivalent to passing ``-Wdev`` or ``-Wno-dev``
+    on the command line. This may not be set to ``false`` if ``errors.dev``
+    is set to ``true``.
 
-    ``deprecated``
+  ``deprecated``
 
-      An optional boolean. Equivalent to passing ``-Wdeprecated`` or
-      ``-Wno-deprecated`` on the command line. This may not be set to
-      ``false`` if ``errors.deprecated`` is set to ``true``.
+    An optional boolean. Equivalent to passing ``-Wdeprecated`` or
+    ``-Wno-deprecated`` on the command line. This may not be set to
+    ``false`` if ``errors.deprecated`` is set to ``true``.
 
-    ``uninitialized``
+  ``uninitialized``
 
-      An optional boolean. Setting this to ``true`` is equivalent to passing
-      ``--warn-uninitialized`` on the command line.
+    An optional boolean. Setting this to ``true`` is equivalent to passing
+    ``--warn-uninitialized`` on the command line.
 
-    ``unusedCli``
+  ``unusedCli``
 
-      An optional boolean. Setting this to ``false`` is equivalent to passing
-      ``--no-warn-unused-cli`` on the command line.
+    An optional boolean. Setting this to ``false`` is equivalent to passing
+    ``--no-warn-unused-cli`` on the command line.
 
-    ``systemVars``
+  ``systemVars``
 
-      An optional boolean. Setting this to ``true`` is equivalent to passing
-      ``--check-system-vars`` on the command line.
+    An optional boolean. Setting this to ``true`` is equivalent to passing
+    ``--check-system-vars`` on the command line.
 
-  ``errors``
+``errors``
 
-    An optional object specifying the errors to enable. The object may
-    contain the following fields:
+  An optional object specifying the errors to enable. The object may
+  contain the following fields:
 
-    ``dev``
+  ``dev``
 
-      An optional boolean. Equivalent to passing ``-Werror=dev`` or
-      ``-Wno-error=dev`` on the command line. This may not be set to ``true``
-      if ``warnings.dev`` is set to ``false``.
+    An optional boolean. Equivalent to passing ``-Werror=dev`` or
+    ``-Wno-error=dev`` on the command line. This may not be set to ``true``
+    if ``warnings.dev`` is set to ``false``.
 
-    ``deprecated``
+  ``deprecated``
 
-      An optional boolean. Equivalent to passing ``-Werror=deprecated`` or
-      ``-Wno-error=deprecated`` on the command line. This may not be set to
-      ``true`` if ``warnings.deprecated`` is set to ``false``.
+    An optional boolean. Equivalent to passing ``-Werror=deprecated`` or
+    ``-Wno-error=deprecated`` on the command line. This may not be set to
+    ``true`` if ``warnings.deprecated`` is set to ``false``.
 
-  ``debug``
+``debug``
 
-    An optional object specifying debug options. The object may contain the
-    following fields:
+  An optional object specifying debug options. The object may contain the
+  following fields:
 
-    ``output``
+  ``output``
 
-      An optional boolean. Setting this to ``true`` is equivalent to passing
-      ``--debug-output`` on the command line.
+    An optional boolean. Setting this to ``true`` is equivalent to passing
+    ``--debug-output`` on the command line.
 
-    ``tryCompile``
+  ``tryCompile``
 
-      An optional boolean. Setting this to ``true`` is equivalent to passing
-      ``--debug-trycompile`` on the command line.
+    An optional boolean. Setting this to ``true`` is equivalent to passing
+    ``--debug-trycompile`` on the command line.
 
-    ``find``
+  ``find``
 
-      An optional boolean. Setting this to ``true`` is equivalent to passing
-      ``--debug-find`` on the command line.
+    An optional boolean. Setting this to ``true`` is equivalent to passing
+    ``--debug-find`` on the command line.
 
 Macro Expansion
 ^^^^^^^^^^^^^^^