Help: Move CMakePresets.json documentation into a separate file

4 files changed, 353 insertions, 329 deletions

diff --git a/Help/guide/user-interaction/index.rst b/Help/guide/user-interaction/index.rst
index 4bde0be..9e9f2a5 100644
--- a/Help/guide/user-interaction/index.rst
+++ b/Help/guide/user-interaction/index.rst
@@ -421,7 +421,7 @@ presets can set the build directory, generator, cache
 variables, environment variables, and other command-line
 options. All of these options can be overridden by the
 user. The full details of the ``CMakePresets.json`` format
-are listed in the :manual:`cmake(1)` manual.
+are listed in the :manual:`cmake-presets(7)` manual.
 
 Using presets on the command-line
 ---------------------------------
diff --git a/Help/index.rst b/Help/index.rst
index 6d87f71..fdbf847 100644
--- a/Help/index.rst
+++ b/Help/index.rst
@@ -66,6 +66,7 @@ Reference Manuals
    /manual/cmake-modules.7
    /manual/cmake-packages.7
    /manual/cmake-policies.7
+   /manual/cmake-presets.7
    /manual/cmake-properties.7
    /manual/cmake-qt.7
    /manual/cmake-server.7
diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst
new file mode 100644
index 0000000..2c0aa48
--- /dev/null
+++ b/Help/manual/cmake-presets.7.rst
@@ -0,0 +1,347 @@
+.. cmake-manual-description: CMakePresets.json
+
+cmake-presets(7)
+****************
+
+.. only:: html
+
+   .. contents::
+
+Introduction
+============
+
+One problem that CMake users often face is sharing settings with other people
+for common ways to configure a project. This may be done to support CI builds,
+or for users who frequently use the same build. CMake supports two files,
+``CMakePresets.json`` and ``CMakeUserPresets.json``, that allow users to
+specify common configure options and share them with others.
+
+``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
+``CMakeUserPresets.json`` should be added to the ``.gitignore``.
+
+Format
+======
+
+  The files are a JSON document with an object as the root:
+
+  .. literalinclude:: presets/example.json
+    :language: json
+
+  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.
+
+  ``cmakeMinimumRequired``
+
+    An optional object representing the minimum version of CMake needed to
+    build this project. This object consists of the following fields:
+
+    ``major``
+
+      An optional integer representing the major version.
+
+    ``minor``
+
+      An optional integer representing the minor version.
+
+    ``patch``
+
+      An optional integer representing the patch version.
+
+  ``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, the keys should be a vendor-specific domain name
+    followed by a ``/``-separated path. For example, the Example IDE 1.0 could
+    use ``example.com/ExampleIDE/1.0``. The value of each field can be anything
+    desired by the vendor, though will typically be a map. For example:
+
+    .. code-block:: json
+
+      {
+        "version": 1,
+        "vendor": {
+          "example.com/ExampleIDE/1.0": {
+            "autoFormat": true
+          }
+        },
+        "configurePresets": []
+      }
+
+  ``configurePresets``
+
+    An optional array of configure preset objects. Each preset 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
+      ``CMakeUserPresets.json`` in the same directory with the same name.
+
+    ``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.
+
+    ``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 ``longDescription``), 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.
+
+    ``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.
+
+    ``displayName``
+
+      An optional string with a human-friendly name of the preset.
+
+    ``description``
+
+      An optional string with a human-friendly description of the preset.
+
+    ``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``).
+
+      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``
+
+      An optional string representing the platform name to use for Visual
+      Studio generators.
+
+    ``toolset``
+
+      An optional string representing the toolset name to use for Visual Studio
+      generators.
+
+    ``cmakeGeneratorConfig``
+
+      An optional string telling CMake how to handle the ``architecture`` and
+      ``toolset`` fields. Valid values are:
+
+      ``"default"``
+
+        Set the platform and toolset using the ``architecture`` and ``toolset``
+        fields respectively. On non-Visual Studio generators, this will result
+        in an error if ``architecture`` or ``toolset`` are set.
+
+      ``"ignore"``
+
+        Do not set the platform or toolset at all, even on Visual Studio
+        generators. 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 ``architecture`` and ``toolset``, but the IDE can use them
+        to set up the environment before invoking CMake.
+
+    ``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``).
+
+    ``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.
+
+    ``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 string
+      representing the value of the variable (which supports macro expansion),
+      or an object with the following fields:
+
+      ``type``
+
+        An optional string representing the type of the variable.
+
+      ``value``
+
+        A required string representing the value of the variable. 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.
+
+    ``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}``.)
+
+      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``
+
+      An optional object specifying warnings. The object may contain the
+      following fields:
+
+      ``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``.
+
+      ``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``.
+
+      ``uninitialized``
+
+        An optional boolean. Setting this to ``true`` is equivalent to passing
+        ``--warn-uninitialized`` on the command line.
+
+      ``unusedVars``
+
+        An optional boolean. Setting this to ``false`` is equivalent to passing
+        ``--no-warn-unused-cli`` on the command line.
+
+      ``systemVars``
+
+        An optional boolean. Setting this to ``true`` is equivalent to passing
+        ``--check-system-vars`` on the command line.
+
+    ``errors``
+
+      An optional object specifying errors. The object may contain the
+      following fields:
+
+      ``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``.
+
+      ``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``.
+
+  As mentioned above, some fields support macro expansion. Macros are
+  recognized in the form ``$<macro-namespace>{<macro-name>}``. All macros are
+  evaluated in the context of the preset being used, even if the macro is in a
+  field that was inherited from another preset. For example, if the ``Base``
+  preset sets variable ``PRESET_NAME`` to ``${presetName}``, and the
+  ``Derived`` preset inherits from ``Base``, ``PRESET_NAME`` will be set to
+  ``Derived``.
+
+  It is an error to not put a closing brace at the end of a macro name. For
+  example, ``${sourceDir`` is invalid. A dollar sign (``$``) followed by
+  anything other than a left curly brace (``{``) with a possible namespace is
+  interpreted as a literal dollar sign.
+
+  Recognized macros include:
+
+  ``${sourceDir}``
+
+    Path to the project source directory.
+
+  ``${sourceParentDir}``
+
+    Path to the project source directory's parent directory.
+
+  ``${presetName}``
+
+    Name specified in the preset's ``name`` field.
+
+  ``${generator}``
+
+    Generator specified in the preset's ``generator`` field.
+
+  ``${dollar}``
+
+    A literal dollar sign (``$``).
+
+  ``$env{<variable-name>}``
+
+    Environment variable with name ``<variable-name>``. The variable name may
+    not be an empty string. If the variable is defined in the ``environment``
+    field, that value is used instead of the value from the parent environment.
+    If the environment variable is not defined, this evaluates as an empty
+    string.
+
+    Note that while Windows environment variable names are case-insensitive,
+    variable names within a preset are still case-sensitive. This may lead to
+    unexpected results when using inconsistent casing. For best results, keep
+    the casing of environment variable names consistent.
+
+  ``$penv{<variable-name>}``
+
+    Similar to ``$env{<variable-name>}``, except that the value only comes from
+    the parent environment, and never from the ``environment`` field. This
+    allows you to prepend or append values to existing environment variables.
+    For example, setting ``PATH`` to ``/path/to/ninja/bin:$penv{PATH}`` will
+    prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This
+    is needed because ``$env{<variable-name>}`` does not allow circular
+    references.
+
+  ``$vendor{<macro-name>}``
+
+    An extension point for vendors to insert their own macros. CMake will not
+    be able to use presets which have a ``$vendor{<macro-name>}`` macro, and
+    effectively ignores such presets. However, it will still be able to use
+    other presets from the same file.
+
+    CMake does not make any attempt to interpret ``$vendor{<macro-name>}``
+    macros. However, to avoid name collisions, IDE vendors should prefix
+    ``<macro-name>`` with a very short (preferably <= 4 characters) vendor
+    identifier prefix, followed by a ``.``, followed by the macro name. For
+    example, the Example IDE could have ``$vendor{xide.ideInstallDir}``.
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index b8a1b42..5452c79 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -150,21 +150,14 @@ source and build trees and generate a buildsystem:
     $ cmake -S src -B build
 
 ``cmake [<options>] -S <path-to-source> --preset=<preset-name>``
-  Uses ``<path-to-source>`` as the source tree and reads a preset from
+  Uses ``<path-to-source>`` as the source tree and reads a
+  :manual:`preset <cmake-presets(7)>` from
   ``<path-to-source>/CMakePresets.json`` and
   ``<path-to-source>/CMakeUserPresets.json``. The preset specifies the
   generator and the build directory, and optionally a list of variables and
   other arguments to pass to CMake. The :manual:`CMake GUI <cmake-gui(1)>` can
-  also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files.
-
-  ``CMakePresets.json`` and ``CMakeUserPresets.json`` 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 ``CMakeUserPresets.json`` should be added to the ``.gitignore``.
+  also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For
+  full details on these files, see :manual:`cmake-presets(7)`.
 
   The presets are read before all other command line options. The options
   specified by the preset (variables, generator, etc.) can all be overridden by
@@ -172,323 +165,6 @@ source and build trees and generate a buildsystem:
   a variable called ``MYVAR`` to ``1``, but the user sets it to ``2`` with a
   ``-D`` argument, the value ``2`` is preferred.
 
-  The files are a JSON document with an object as the root:
-
-  .. literalinclude:: presets/example.json
-    :language: json
-
-  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.
-
-  ``cmakeMinimumRequired``
-
-    An optional object representing the minimum version of CMake needed to
-    build this project. This object consists of the following fields:
-
-    ``major``
-
-      An optional integer representing the major version.
-
-    ``minor``
-
-      An optional integer representing the minor version.
-
-    ``patch``
-
-      An optional integer representing the patch version.
-
-  ``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, the keys should be a vendor-specific domain name
-    followed by a ``/``-separated path. For example, the Example IDE 1.0 could
-    use ``example.com/ExampleIDE/1.0``. The value of each field can be anything
-    desired by the vendor, though will typically be a map. For example:
-
-    .. code-block:: json
-
-      {
-        "version": 1,
-        "vendor": {
-          "example.com/ExampleIDE/1.0": {
-            "autoFormat": true
-          }
-        },
-        "configurePresets": []
-      }
-
-  ``configurePresets``
-
-    An optional array of configure preset objects. Each preset 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
-      ``CMakeUserPresets.json`` in the same directory with the same name.
-
-    ``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.
-
-    ``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 ``longDescription``), 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.
-
-    ``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.
-
-    ``displayName``
-
-      An optional string with a human-friendly name of the preset.
-
-    ``description``
-
-      An optional string with a human-friendly description of the preset.
-
-    ``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``).
-
-      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``
-
-      An optional string representing the platform name to use for Visual
-      Studio generators.
-
-    ``toolset``
-
-      An optional string representing the toolset name to use for Visual Studio
-      generators.
-
-    ``cmakeGeneratorConfig``
-
-      An optional string telling CMake how to handle the ``architecture`` and
-      ``toolset`` fields. Valid values are:
-
-      ``"default"``
-
-        Set the platform and toolset using the ``architecture`` and ``toolset``
-        fields respectively. On non-Visual Studio generators, this will result
-        in an error if ``architecture`` or ``toolset`` are set.
-
-      ``"ignore"``
-
-        Do not set the platform or toolset at all, even on Visual Studio
-        generators. 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 ``architecture`` and ``toolset``, but the IDE can use them
-        to set up the environment before invoking CMake.
-
-    ``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``).
-
-    ``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.
-
-    ``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 string
-      representing the value of the variable (which supports macro expansion),
-      or an object with the following fields:
-
-      ``type``
-
-        An optional string representing the type of the variable.
-
-      ``value``
-
-        A required string representing the value of the variable. 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.
-
-    ``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}``.)
-
-      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``
-
-      An optional object specifying warnings. The object may contain the
-      following fields:
-
-      ``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``.
-
-      ``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``.
-
-      ``uninitialized``
-
-        An optional boolean. Setting this to ``true`` is equivalent to passing
-        ``--warn-uninitialized`` on the command line.
-
-      ``unusedVars``
-
-        An optional boolean. Setting this to ``false`` is equivalent to passing
-        ``--no-warn-unused-cli`` on the command line.
-
-      ``systemVars``
-
-        An optional boolean. Setting this to ``true`` is equivalent to passing
-        ``--check-system-vars`` on the command line.
-
-    ``errors``
-
-      An optional object specifying errors. The object may contain the
-      following fields:
-
-      ``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``.
-
-      ``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``.
-
-  As mentioned above, some fields support macro expansion. Macros are
-  recognized in the form ``$<macro-namespace>{<macro-name>}``. All macros are
-  evaluated in the context of the preset being used, even if the macro is in a
-  field that was inherited from another preset. For example, if the ``Base``
-  preset sets variable ``PRESET_NAME`` to ``${presetName}``, and the
-  ``Derived`` preset inherits from ``Base``, ``PRESET_NAME`` will be set to
-  ``Derived``.
-
-  It is an error to not put a closing brace at the end of a macro name. For
-  example, ``${sourceDir`` is invalid. A dollar sign (``$``) followed by
-  anything other than a left curly brace (``{``) with a possible namespace is
-  interpreted as a literal dollar sign.
-
-  Recognized macros include:
-
-  ``${sourceDir}``
-
-    Path to the project source directory.
-
-  ``${sourceParentDir}``
-
-    Path to the project source directory's parent directory.
-
-  ``${presetName}``
-
-    Name specified in the preset's ``name`` field.
-
-  ``${generator}``
-
-    Generator specified in the preset's ``generator`` field.
-
-  ``${dollar}``
-
-    A literal dollar sign (``$``).
-
-  ``$env{<variable-name>}``
-
-    Environment variable with name ``<variable-name>``. The variable name may
-    not be an empty string. If the variable is defined in the ``environment``
-    field, that value is used instead of the value from the parent environment.
-    If the environment variable is not defined, this evaluates as an empty
-    string.
-
-    Note that while Windows environment variable names are case-insensitive,
-    variable names within a preset are still case-sensitive. This may lead to
-    unexpected results when using inconsistent casing. For best results, keep
-    the casing of environment variable names consistent.
-
-  ``$penv{<variable-name>}``
-
-    Similar to ``$env{<variable-name>}``, except that the value only comes from
-    the parent environment, and never from the ``environment`` field. This
-    allows you to prepend or append values to existing environment variables.
-    For example, setting ``PATH`` to ``/path/to/ninja/bin:$penv{PATH}`` will
-    prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This
-    is needed because ``$env{<variable-name>}`` does not allow circular
-    references.
-
-  ``$vendor{<macro-name>}``
-
-    An extension point for vendors to insert their own macros. CMake will not
-    be able to use presets which have a ``$vendor{<macro-name>}`` macro, and
-    effectively ignores such presets. However, it will still be able to use
-    other presets from the same file.
-
-    CMake does not make any attempt to interpret ``$vendor{<macro-name>}``
-    macros. However, to avoid name collisions, IDE vendors should prefix
-    ``<macro-name>`` with a very short (preferably <= 4 characters) vendor
-    identifier prefix, followed by a ``.``, followed by the macro name. For
-    example, the Example IDE could have ``$vendor{xide.ideInstallDir}``.
-
 In all cases the ``<options>`` may be zero or more of the `Options`_ below.
 
 After generating a buildsystem one may use the corresponding native