Merge topic 'policies-generic-docs'

6d50d01 Help: Add introduction section to cmake-policies manual

1 files changed, 20 insertions, 0 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 658620f..4fcc90b 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -5,6 +5,26 @@ cmake-policies(7)
 
    .. contents::
 
+Introduction
+============
+
+Policies in CMake are used to preserve backward compatible behavior
+across multiple releases.  When a new policy is introduced, newer CMake
+versions will begin to warn about the backward compatible behavior.  It
+is possible to disable the warning by explicitly requesting the OLD, or
+backward compatible behavior using the :command:`cmake_policy` command.
+It is also possible to request NEW, or non-backward compatible behavior
+for a policy, also avoiding the warning.
+
+The :command:`cmake_minimum_required` command does more than report an
+error if a too-old version of CMake is used to build a project.  It
+also sets all policies introduced in that CMake version or earlier to
+NEW behavior.
+
+The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
+to determine whether to report an error on use of deprecated macros or
+functions.
+
 All Policies
 ============