cmake_minimum_required: Optionally set policies with version range

Teach `cmake_minimum_required` and `cmake_policy(VERSION)` to support a
version range of the form `<min>[...<max>]`.  Define this to mean that
version `<min>` is required, but known policies up to those introduced
by `<max>` will be set to `NEW`.  This will allow projects to easily
specify a range of versions for which they have been updated.

1 files changed, 20 insertions, 14 deletions

diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst
index 9535bf3..7c02190 100644
--- a/Help/command/cmake_minimum_required.rst
+++ b/Help/command/cmake_minimum_required.rst
@@ -4,11 +4,15 @@ cmake_minimum_required
 Set the minimum required version of cmake for a project and
 update `Policy Settings`_ to match the version given::
 
-  cmake_minimum_required(VERSION major.minor[.patch[.tweak]]
-                         [FATAL_ERROR])
+  cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
 
-If the current version of CMake is lower than that required it will
-stop processing the project and report an error.
+``<min>`` and the optional ``<max>`` are each CMake versions of the form
+``major.minor[.patch[.tweak]]``, and the ``...`` is literal.
+
+If the running version of CMake is lower than the ``<min>`` required
+version it will stop processing the project and report an error.
+The optional ``<max>`` version, if specified, must be at least the
+``<min>`` version and affects policy settings as described below.
 
 The ``FATAL_ERROR`` option is accepted but ignored by CMake 2.6 and
 higher.  It should be specified so CMake versions 2.4 and lower fail
@@ -30,21 +34,23 @@ Policy Settings
 
 The ``cmake_minimum_required(VERSION)`` command implicitly invokes the
 :command:`cmake_policy(VERSION)` command to specify that the current
-project code is written for the given version of CMake.
-All policies introduced in the specified version or earlier will be
-set to use NEW behavior.  All policies introduced after the specified
-version will be unset.  This effectively requests behavior preferred
+project code is written for the given range of CMake versions.
+All policies known to the running version of CMake and introduced
+in the ``<min>`` (or ``<max>``, if specified) version or earlier will
+be set to use ``NEW`` behavior.  All policies introduced in later
+versions will be unset.  This effectively requests behavior preferred
 as of a given CMake version and tells newer CMake versions to warn
 about their new policies.
 
-When a version higher than 2.4 is specified the command implicitly
-invokes::
+When a ``<min>`` version higher than 2.4 is specified the command
+implicitly invokes::
 
-  cmake_policy(VERSION major[.minor[.patch[.tweak]]])
+  cmake_policy(VERSION <min>[...<max>])
 
-which sets the cmake policy version level to the version specified.
-When version 2.4 or lower is given the command implicitly invokes::
+which sets CMake policies based on the range of versions specified.
+When a ``<min>`` version 2.4 or lower is given the command implicitly
+invokes::
 
-  cmake_policy(VERSION 2.4)
+  cmake_policy(VERSION 2.4[...<max>])
 
 which enables compatibility features for CMake 2.4 and lower.