21 files changed, 155 insertions, 51 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.
diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst
index b51b951..6a8dd62 100644
--- a/Help/command/cmake_policy.rst
+++ b/Help/command/cmake_policy.rst
@@ -24,17 +24,22 @@ 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::
 
-  cmake_policy(VERSION major.minor[.patch[.tweak]])
-
-Specify that the current CMake 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 (unless the
+  cmake_policy(VERSION <min>[...<max>])
+
+``<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.
+
+This specifies that the current CMake 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 (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.
-The policy version specified must be at least 2.4 or the command will
-report an error.
 
 Note that the :command:`cmake_minimum_required(VERSION)`
 command implicitly calls ``cmake_policy(VERSION)`` too.
diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst
index 873c6ca..da2631c 100644
--- a/Help/command/define_property.rst
+++ b/Help/command/define_property.rst
@@ -34,10 +34,24 @@ actual scope needs to be given; only the kind of scope is important.
 The required ``PROPERTY`` option is immediately followed by the name of
 the property being defined.
 
-If the ``INHERITED`` option then the :command:`get_property` command will
-chain up to the next higher scope when the requested property is not set
-in the scope given to the command. ``DIRECTORY`` scope chains to
-``GLOBAL``. ``TARGET``, ``SOURCE``, and ``TEST`` chain to ``DIRECTORY``.
+If the ``INHERITED`` option is given, then the :command:`get_property` command
+will chain up to the next higher scope when the requested property is not set
+in the scope given to the command.
+
+* ``DIRECTORY`` scope chains to its parent directory's scope, continuing the
+  walk up parent directories until a directory has the property set or there
+  are no more parents.  If still not found at the top level directory, it
+  chains to the ``GLOBAL`` scope.
+* ``TARGET``, ``SOURCE`` and ``TEST`` properties chain to ``DIRECTORY`` scope,
+  including further chaining up the directories, etc. as needed.
+
+Note that this scope chaining behavior only applies to calls to
+:command:`get_property`, :command:`get_directory_property`,
+:command:`get_target_property`, :command:`get_source_file_property` and
+:command:`get_test_property`.  There is no inheriting behavior when *setting*
+properties, so using ``APPEND`` or ``APPEND_STRING`` with the
+:command:`set_property` command will not consider inherited values when working
+out the contents to append to.
 
 The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be
 associated with the property as its brief and full documentation.
diff --git a/Help/command/get_directory_property.rst b/Help/command/get_directory_property.rst
index e50abe0..bf8349c 100644
--- a/Help/command/get_directory_property.rst
+++ b/Help/command/get_directory_property.rst
@@ -7,11 +7,16 @@ Get a property of ``DIRECTORY`` scope.
 
   get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
 
-Store a property of directory scope in the named variable.  If the
-property is not defined the empty-string is returned.  The ``DIRECTORY``
-argument specifies another directory from which to retrieve the
-property value.  The specified directory must have already been
-traversed by CMake.
+Store a property of directory scope in the named ``<variable>``.
+The ``DIRECTORY`` argument specifies another directory from which
+to retrieve the property value instead of the current directory.
+The specified directory must have already been traversed by CMake.
+
+If the property is not defined for the nominated directory scope,
+an empty string is returned.  In the case of ``INHERITED`` properties,
+if the property is not found for the nominated directory scope,
+the search will chain to a parent scope as described for the
+:command:`define_property` command.
 
 ::
 
diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst
index 632ece6..8b85f7d 100644
--- a/Help/command/get_property.rst
+++ b/Help/command/get_property.rst
@@ -50,7 +50,10 @@ be one of the following:
 
 The required ``PROPERTY`` option is immediately followed by the name of
 the property to get.  If the property is not set an empty value is
-returned.  If the ``SET`` option is given the variable is set to a boolean
+returned, although some properties support inheriting from a parent scope
+if defined to behave that way (see :command:`define_property`).
+
+If the ``SET`` option is given the variable is set to a boolean
 value indicating whether the property has been set.  If the ``DEFINED``
 option is given the variable is set to a boolean value indicating
 whether the property has been defined such as with the
diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst
index 3e975c2..648ecbd 100644
--- a/Help/command/get_source_file_property.rst
+++ b/Help/command/get_source_file_property.rst
@@ -8,9 +8,15 @@ Get a property for a source file.
   get_source_file_property(VAR file property)
 
 Get a property from a source file.  The value of the property is
-stored in the variable ``VAR``.  If the property is not found, ``VAR``
-will be set to "NOTFOUND".  Use :command:`set_source_files_properties`
-to set property values.  Source file properties usually control how the
-file is built. One property that is always there is :prop_sf:`LOCATION`
+stored in the variable ``VAR``.  If the source property is not found, the
+behavior depends on whether it has been defined to be an ``INHERITED`` property
+or not (see :command:`define_property`).  Non-inherited properties will set
+``VAR`` to "NOTFOUND", whereas inheritied properties will search the relevent
+parent scope as described for the :command:`define_property` command and
+if still unable to find the property, ``VAR`` will be set to an empty string.
+
+Use :command:`set_source_files_properties` to set property values.  Source
+file properties usually control how the file is built. One property that is
+always there is :prop_sf:`LOCATION`.
 
 See also the more general :command:`get_property` command.
diff --git a/Help/command/get_target_property.rst b/Help/command/get_target_property.rst
index 2a72c3a..3d159dc 100644
--- a/Help/command/get_target_property.rst
+++ b/Help/command/get_target_property.rst
@@ -8,8 +8,15 @@ Get a property from a target.
   get_target_property(VAR target property)
 
 Get a property from a target.  The value of the property is stored in
-the variable ``VAR``.  If the property is not found, ``VAR`` will be set to
-"NOTFOUND".  Use :command:`set_target_properties` to set property values.
+the variable ``VAR``.  If the target property is not found, the behavior
+depends on whether it has been defined to be an ``INHERITED`` property
+or not (see :command:`define_property`).  Non-inherited properties will
+set ``VAR`` to "NOTFOUND", whereas inheritied properties will search the
+relevent parent scope as described for the :command:`define_property`
+command and if still unable to find the property, ``VAR`` will be set to
+an empty string.
+
+Use :command:`set_target_properties` to set target property values.
 Properties are usually used to control how a target is built, but some
 query the target instead.  This command can get properties for any
 target so far created.  The targets do not need to be in the current
diff --git a/Help/command/get_test_property.rst b/Help/command/get_test_property.rst
index e359f4b..703efdc 100644
--- a/Help/command/get_test_property.rst
+++ b/Help/command/get_test_property.rst
@@ -8,8 +8,14 @@ Get a property of the test.
   get_test_property(test property VAR)
 
 Get a property from the test.  The value of the property is stored in
-the variable ``VAR``.  If the test or property is not found, ``VAR`` will
-be set to "NOTFOUND".  For a list of standard properties you can type
-``cmake --help-property-list``.
+the variable ``VAR``.  If the test property is not found, the behavior
+depends on whether it has been defined to be an ``INHERITED`` property
+or not (see :command:`define_property`).  Non-inherited properties will
+set ``VAR`` to "NOTFOUND", whereas inheritied properties will search the
+relevent parent scope as described for the :command:`define_property`
+command and if still unable to find the property, ``VAR`` will be set to
+an empty string.
+
+For a list of standard properties you can type ``cmake --help-property-list``.
 
 See also the more general :command:`get_property` command.
diff --git a/Help/command/list.rst b/Help/command/list.rst
index 3c092bd..6218a2a 100644
--- a/Help/command/list.rst
+++ b/Help/command/list.rst
@@ -65,6 +65,18 @@ Returns a string joining all list's elements using the glue string.
 To join multiple strings, which are not part of a list, use ``JOIN`` operator
 from :command:`string` command.
 
+SUBLIST
+"""""""
+
+::
+
+  list(SUBLIST <list> <begin> <length> <output variable>)
+
+Returns a sublist of the given list.
+If ``<length>`` is 0, an empty list will be returned.
+If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then
+the remaining elements of the list starting at ``<begin>`` will be returned.
+
 Search
 ^^^^^^
 
diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst
index 5ed788e..c89e1ce 100644
--- a/Help/command/set_property.rst
+++ b/Help/command/set_property.rst
@@ -59,11 +59,17 @@ be one of the following:
 
 The required ``PROPERTY`` option is immediately followed by the name of
 the property to set.  Remaining arguments are used to compose the
-property value in the form of a semicolon-separated list.  If the
-``APPEND`` option is given the list is appended to any existing property
-value.  If the ``APPEND_STRING`` option is given the string is append to any
-existing property value as string, i.e.  it results in a longer string
-and not a list of strings.
+property value in the form of a semicolon-separated list.
+
+If the ``APPEND`` option is given the list is appended to any existing
+property value.  If the ``APPEND_STRING`` option is given the string is
+appended to any existing property value as string, i.e. it results in a
+longer string and not a list of strings.  When using ``APPEND`` or
+``APPEND_STRING`` with a property defined to support ``INHERITED``
+behavior (see :command:`define_property`), no inheriting occurs when
+finding the initial value to append to.  If the property is not already
+directly set in the nominated scope, the command will behave as though
+``APPEND`` or ``APPEND_STRING`` had not been given.
 
 See the :manual:`cmake-properties(7)` manual for a list of properties
 in each scope.
diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst
index 3709e7a..a740117 100644
--- a/Help/command/target_compile_definitions.rst
+++ b/Help/command/target_compile_definitions.rst
@@ -27,3 +27,13 @@ Arguments to ``target_compile_definitions`` may use "generator expressions"
 with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
+
+Any leading ``-D`` on an item will be removed.  Empty items are ignored.
+For example, the following are all equivalent:
+
+.. code-block:: cmake
+
+  target_compile_definitions(foo PUBLIC FOO)
+  target_compile_definitions(foo PUBLIC -DFOO)  # -D removed
+  target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
+  target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst
index 0124395..e9495c6 100644
--- a/Help/manual/cmake-compile-features.7.rst
+++ b/Help/manual/cmake-compile-features.7.rst
@@ -335,7 +335,7 @@ versions specified for each:
 * ``Clang``: Clang compiler versions 2.9 through 3.4.
 * ``GNU``: GNU compiler versions 4.4 through 5.0.
 * ``MSVC``: Microsoft Visual Studio versions 2010 through 2017.
-* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.5.
+* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.6.
 * ``Intel``: Intel compiler versions 12.1 through 17.0.
 
 CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>`
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index 41fe90c..32e8cfc 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -644,6 +644,8 @@ Documentation`_ section above.
 
 
 
+.. _`CMake Developer Standard Variable Names`:
+
 Standard Variable Names
 ^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst
index 694bae5..070c6ed 100644
--- a/Help/manual/cmake-modules.7.rst
+++ b/Help/manual/cmake-modules.7.rst
@@ -196,6 +196,9 @@ All Modules
    /module/FindPostgreSQL
    /module/FindProducer
    /module/FindProtobuf
+   /module/FindPython
+   /module/FindPython2
+   /module/FindPython3
    /module/FindPythonInterp
    /module/FindPythonLibs
    /module/FindQt3
diff --git a/Help/module/FindPython.rst b/Help/module/FindPython.rst
new file mode 100644
index 0000000..057a350
--- /dev/null
+++ b/Help/module/FindPython.rst
@@ -0,0 +1 @@
+.. cmake-module:: ../../Modules/FindPython.cmake
diff --git a/Help/module/FindPython2.rst b/Help/module/FindPython2.rst
new file mode 100644
index 0000000..1696bed
--- /dev/null
+++ b/Help/module/FindPython2.rst
@@ -0,0 +1 @@
+.. cmake-module:: ../../Modules/FindPython2.cmake
diff --git a/Help/module/FindPython3.rst b/Help/module/FindPython3.rst
new file mode 100644
index 0000000..e530ab8
--- /dev/null
+++ b/Help/module/FindPython3.rst
@@ -0,0 +1 @@
+.. cmake-module:: ../../Modules/FindPython3.cmake
diff --git a/Help/release/dev/FindPython-new-implementation.rst b/Help/release/dev/FindPython-new-implementation.rst
new file mode 100644
index 0000000..22051d0
--- /dev/null
+++ b/Help/release/dev/FindPython-new-implementation.rst
@@ -0,0 +1,5 @@
+FindPython(2|3)
+---------------
+
+* The new :module:`FindPython3` and :module:`FindPython2` modules, as well as
+  :module:`FindPython`, provide a new way to locate python environments.
diff --git a/Help/release/dev/list-sublist.rst b/Help/release/dev/list-sublist.rst
new file mode 100644
index 0000000..7ad225b
--- /dev/null
+++ b/Help/release/dev/list-sublist.rst
@@ -0,0 +1,5 @@
+list-sublist
+------------
+
+* The :command:`list` command learned a ``SUBLIST`` sub-command
+  to get a sublist of the list.
diff --git a/Help/release/dev/policy-version-range.rst b/Help/release/dev/policy-version-range.rst
new file mode 100644
index 0000000..b2d1f17
--- /dev/null
+++ b/Help/release/dev/policy-version-range.rst
@@ -0,0 +1,8 @@
+policy-version-range
+--------------------
+
+* The :command:`cmake_minimum_required` and :command:`cmake_policy(VERSION)`
+  commands now accept a version range using the form ``<min>[...<max>]``.
+  The ``<min>`` version is required but policies are set based on the
+  ``<max>`` version.  This allows projects to specify a range of versions
+  for which they have been updated and avoid explicit policy settings.
diff --git a/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst
index 5a51634..f466468 100644
--- a/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst
+++ b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst
@@ -1,7 +1,5 @@
 CMAKE_MINIMUM_REQUIRED_VERSION
 ------------------------------
 
-Version specified to :command:`cmake_minimum_required` command
-
-Variable containing the ``VERSION`` component specified in the
-:command:`cmake_minimum_required` command.
+The ``<min>`` version of CMake given to the most recent call to the
+:command:`cmake_minimum_required(VERSION)` command.