Merge topic 'doc-version-components'

52e7beb6 Help: Expand documentation of CMAKE_VERSION and related variables

5 files changed, 50 insertions, 20 deletions

diff --git a/Help/variable/CMAKE_MAJOR_VERSION.rst b/Help/variable/CMAKE_MAJOR_VERSION.rst
index 7dd24e5..079ad70 100644
--- a/Help/variable/CMAKE_MAJOR_VERSION.rst
+++ b/Help/variable/CMAKE_MAJOR_VERSION.rst
@@ -1,6 +1,5 @@
 CMAKE_MAJOR_VERSION
 -------------------
 
-The Major version of cmake (i.e. the 2 in 2.X.X)
-
-This specifies the major version of the CMake executable being run.
+First version number component of the :variable:`CMAKE_VERSION`
+variable.
diff --git a/Help/variable/CMAKE_MINOR_VERSION.rst b/Help/variable/CMAKE_MINOR_VERSION.rst
index bbc1073..f67cfb9 100644
--- a/Help/variable/CMAKE_MINOR_VERSION.rst
+++ b/Help/variable/CMAKE_MINOR_VERSION.rst
@@ -1,6 +1,5 @@
 CMAKE_MINOR_VERSION
 -------------------
 
-The Minor version of cmake (i.e. the 4 in X.4.X).
-
-This specifies the minor version of the CMake executable being run.
+Second version number component of the :variable:`CMAKE_VERSION`
+variable.
diff --git a/Help/variable/CMAKE_PATCH_VERSION.rst b/Help/variable/CMAKE_PATCH_VERSION.rst
index fe68bf2..991ae76 100644
--- a/Help/variable/CMAKE_PATCH_VERSION.rst
+++ b/Help/variable/CMAKE_PATCH_VERSION.rst
@@ -1,6 +1,5 @@
 CMAKE_PATCH_VERSION
 -------------------
 
-The patch version of cmake (i.e. the 3 in X.X.3).
-
-This specifies the patch version of the CMake executable being run.
+Third version number component of the :variable:`CMAKE_VERSION`
+variable.
diff --git a/Help/variable/CMAKE_TWEAK_VERSION.rst b/Help/variable/CMAKE_TWEAK_VERSION.rst
index 56270aa..a2c8f35 100644
--- a/Help/variable/CMAKE_TWEAK_VERSION.rst
+++ b/Help/variable/CMAKE_TWEAK_VERSION.rst
@@ -1,8 +1,5 @@
 CMAKE_TWEAK_VERSION
 -------------------
 
-The tweak version of cmake (i.e. the 1 in X.X.X.1).
-
-This specifies the tweak version of the CMake executable being run.
-Releases use tweak < 20000000 and development versions use the date
-format CCYYMMDD for the tweak level.
+Fourth version number component of the :variable:`CMAKE_VERSION`
+variable.
diff --git a/Help/variable/CMAKE_VERSION.rst b/Help/variable/CMAKE_VERSION.rst
index 4ccc491..6184f08 100644
--- a/Help/variable/CMAKE_VERSION.rst
+++ b/Help/variable/CMAKE_VERSION.rst
@@ -1,10 +1,46 @@
 CMAKE_VERSION
 -------------
 
-The full version of cmake in major.minor.patch[.tweak[-id]] format.
+The CMake version string as up to four non-negative integer components
+separated by ``.`` and possibly followed by ``-`` and other information.
+The first three components represent the feature level and the fourth
+component represents either a bug-fix level or development date.
 
-This specifies the full version of the CMake executable being run.
-This variable is defined by versions 2.6.3 and higher.  See variables
-CMAKE_MAJOR_VERSION, CMAKE_MINOR_VERSION, CMAKE_PATCH_VERSION, and
-CMAKE_TWEAK_VERSION for individual version components.  The [-id]
-component appears in non-release versions and may be arbitrary text.
+Release versions and release candidate versions of CMake use the format::
+
+  <major>.<minor>.<patch>[.<tweak>][-rc<n>]
+
+where the ``<tweak>`` component is less than ``20000000``.  Development
+versions of CMake use the format::
+
+  <major>.<minor>.<patch>.<date>[-<id>]
+
+where the ``<date>`` component is of format ``CCYYMMDD`` and ``<id>``
+may contain arbitrary text.  This represents development as of a
+particular date following the ``<major>.<minor>.<patch>`` feature
+release.
+
+Individual component values are also available in variables:
+
+* :variable:`CMAKE_MAJOR_VERSION`
+* :variable:`CMAKE_MINOR_VERSION`
+* :variable:`CMAKE_PATCH_VERSION`
+* :variable:`CMAKE_TWEAK_VERSION`
+
+Use the :command:`if` command ``VERSION_LESS``, ``VERSION_EQUAL``, or
+``VERSION_GREATER`` operators to compare version string values against
+``CMAKE_VERSION`` using a component-wise test.  Version component
+values may be 10 or larger so do not attempt to compare version
+strings as floating-point numbers.
+
+.. note::
+
+  CMake versions prior to 2.8.2 used three components for the
+  feature level and had no bug-fix component.  Release versions
+  used an even-valued second component, i.e.
+  ``<major>.<even-minor>.<patch>[-rc<n>]``.  Development versions
+  used an odd-valued second component with the development date as
+  the third component, i.e. ``<major>.<odd-minor>.<date>``.
+
+  The ``CMAKE_VERSION`` variable is defined by CMake 2.6.3 and higher.
+  Earlier versions defined only the individual component variables.