Merge topic 'doc-policy-max'

7323fbd65e Help: Be more explicit about what `...<policy_max>` does not mean

Acked-by: Kitware Robot <[email protected]>
Merge-request: !11438

Help/command/cmake_minimum_required.rst

@@ -22,8 +22,8 @@ The optional ``<policy_max>`` version, if specified, must be at least the
 ``<min>`` version and sets the `Policy Version`_.
 If the running version of CMake is older than 3.12, the extra ``...``
 dots will be seen as version component separators, resulting in the
-``...<max>`` part being ignored and preserving the pre-3.12 behavior
-of basing policies on ``<min>``.
+``...<policy_max>`` part being ignored and preserving the pre-3.12
+behavior of basing policies on ``<min>``.
 
 This command will set the value of the
 :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable to ``<min>``.
@@ -53,11 +53,12 @@ with an error instead of just a warning.
 Policy Version
 ^^^^^^^^^^^^^^
 
-``cmake_minimum_required(VERSION <min>[...<max>])`` implicitly invokes
+``cmake_minimum_required(VERSION <min>[...<policy_max>])`` implicitly
+invokes
 
 .. code-block:: cmake
 
-  cmake_policy(VERSION <min>[...<max>])
+  cmake_policy(VERSION <min>[...<policy_max>])
 
 .. include:: include/POLICY_VERSION.rst
 

Help/command/cmake_policy.rst

@@ -24,20 +24,21 @@ The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
 behavior.  While setting policies individually is supported, we
 encourage projects to set policies based on CMake versions:
 
-.. signature:: cmake_policy(VERSION <min>[...<max>])
+.. signature:: cmake_policy(VERSION <min>[...<policy_max>])
   :target: VERSION
 
 .. versionadded:: 3.12
-  The optional ``<max>`` version.
-
-``<min>`` and the optional ``<max>`` are each CMake versions of the form
-``major.minor[.patch[.tweak]]``, and the ``...`` is literal.  The ``<min>``
-version must be at least ``2.4`` and at most the running version of CMake.
-The ``<max>`` version, if specified, must be at least the ``<min>`` version
-but may exceed the running version of CMake.  If the running version of
-CMake is older than 3.12, the extra ``...`` dots will be seen as version
-component separators, resulting in the ``...<max>`` part being ignored and
-preserving the pre-3.12 behavior of basing policies on ``<min>``.
+  The optional ``<policy_max>`` version.
+
+``<min>`` and the optional ``<policy_max>`` are each CMake versions of the
+form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal.
+The ``<min>`` version must be at least ``2.4`` and at most the running
+version of CMake.  The ``<policy_max>`` version, if specified, must be at
+least the ``<min>`` version but may exceed the running version of CMake.
+If the running version of CMake is older than 3.12, the extra ``...``
+dots will be seen as version component separators, resulting in the
+``...<policy_max>`` part being ignored and preserving the pre-3.12 behavior
+of basing policies on ``<min>``.
 
 .. include:: include/POLICY_VERSION.rst
 

Help/command/include/DEPRECATED_POLICY_VERSIONS.rst

@@ -3,7 +3,7 @@
   Compatibility with versions of CMake older than 3.5 is removed.
   Calls to :command:`cmake_minimum_required(VERSION)` or
   :command:`cmake_policy(VERSION)` that do not specify at least
-  3.5 as their policy version (optionally via ``...<max>``)
+  3.5 as their policy version (optionally via ``...<policy_max>``)
   will produce an error in CMake 4.0 and above.
 
 .. versionchanged:: 3.31
@@ -11,7 +11,7 @@
   Compatibility with versions of CMake older than 3.10 is deprecated.
   Calls to :command:`cmake_minimum_required(VERSION)` or
   :command:`cmake_policy(VERSION)` that do not specify at least
-  3.10 as their policy version (optionally via ``...<max>``)
+  3.10 as their policy version (optionally via ``...<policy_max>``)
   will produce a deprecation warning in CMake 3.31 and above.
 
 .. versionchanged:: 3.27
@@ -19,7 +19,7 @@
   Compatibility with versions of CMake older than 3.5 is deprecated.
   Calls to :command:`cmake_minimum_required(VERSION)` or
   :command:`cmake_policy(VERSION)` that do not specify at least
-  3.5 as their policy version (optionally via ``...<max>``)
+  3.5 as their policy version (optionally via ``...<policy_max>``)
   will produce a deprecation warning in CMake 3.27 and above.
 
 .. versionchanged:: 3.19
@@ -27,5 +27,5 @@
   Compatibility with versions of CMake older than 2.8.12 is deprecated.
   Calls to :command:`cmake_minimum_required(VERSION)` or
   :command:`cmake_policy(VERSION)` that do not specify at least
-  2.8.12 as their policy version (optionally via ``...<max>``)
+  2.8.12 as their policy version (optionally via ``...<policy_max>``)
   will produce a deprecation warning in CMake 3.19 and above.

Help/command/include/POLICY_VERSION.rst

@@ -1,7 +1,7 @@
 This specifies that the current CMake code is written for the given range of
-CMake versions, ``<min>[...<max>]``. It sets the "policy version" to:
+CMake versions, ``<min>[...<policy_max>]``. It sets the "policy version" to:
 
-* the range's ``<max>`` version, if specified, or to
+* the range's ``<policy_max>`` version, if specified, or to
 * the ``<min>`` version, or to
 * the value of the :variable:`CMAKE_POLICY_VERSION_MINIMUM` variable
   if it is higher than the other two versions.
@@ -14,3 +14,9 @@ All policies introduced in later versions will be unset (unless the
 :variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable sets a default).
 This effectively requests behavior preferred as of a given CMake
 version and tells newer CMake versions to warn about their new policies.
+
+.. note::
+
+  ``...<policy_max>`` does *not* signify that later CMake versions are
+  forbidden.  It merely specifies the highest CMake version for which
+  the project or module has been actively updated and maintained.

Help/dev/maint.rst

@@ -302,7 +302,7 @@ Update ``Source/CMakeVersion.cmake`` to set the version to
   set(CMake_VERSION_PATCH $date)
   #set(CMake_VERSION_RC 0)
 
-Update ``Help/manual/cmake-policies.7.rst`` to set the ``...<max>``
+Update ``Help/manual/cmake-policies.7.rst`` to set the ``...<policy_max>``
 example to ``...$major.$minor``:
 
 .. code-block:: cmake

Help/manual/cmake-policies.7.rst

@@ -38,7 +38,7 @@ For example:
 
   cmake_minimum_required(VERSION 3.10...4.2)
 
-This uses the ``<min>...<max>`` syntax to enable the ``NEW`` behaviors
+This uses the ``<min>...<policy_max>`` syntax to enable the ``NEW`` behaviors
 of policies introduced in CMake 4.2 and earlier while only requiring a
 minimum version of CMake 3.10.  The project is expected to work with
 both the ``OLD`` and ``NEW`` behaviors of policies introduced between