Merge branch 'revise-compiler-id-policies' into release

1 files changed, 20 insertions, 14 deletions

diff --git a/Help/policy/CMP0025.rst b/Help/policy/CMP0025.rst
index f3b39e3..8d19edf 100644
--- a/Help/policy/CMP0025.rst
+++ b/Help/policy/CMP0025.rst
@@ -1,21 +1,27 @@
 CMP0025
 -------
 
-Compiler id for Apple Clang is now AppleClang.
+Compiler id for Apple Clang is now ``AppleClang``.
 
-CMake >= 3.0 recognize that Apple Clang is a different compiler
+CMake 3.0 and above recognize that Apple Clang is a different compiler
 than upstream Clang and that they have different version numbers.
-CMake now prefers to present this to projects by setting
-CMAKE_<LANG>_COMPILER_ID to "AppleClang" instead of "Clang".  However,
-existing projects may assume the compiler id for Apple Clang is just
-"Clang" as it was in CMake < 3.0.  Therefore this policy determines
-for Apple Clang which compiler id to report in
-CMAKE_<LANG>_COMPILER_ID after <LANG> is enabled by the project() or
-enable_language() command.
+CMake now prefers to present this to projects by setting the
+:variable:`CMAKE_<LANG>_COMPILER_ID` variable to ``AppleClang`` instead
+of ``Clang``.  However, existing projects may assume the compiler id for
+Apple Clang is just ``Clang`` as it was in CMake versions prior to 3.0.
+Therefore this policy determines for Apple Clang which compiler id to
+report in the :variable:`CMAKE_<LANG>_COMPILER_ID` variable after
+language ``<LANG>`` is enabled by the :command:`project` or
+:command:`enable_language` command.  The policy must be set prior
+to the invocation of either command.
 
-The OLD behavior for this policy is to use compiler id "Clang".  The
-NEW behavior for this policy is to use compiler id "AppleClang".
+The OLD behavior for this policy is to use compiler id ``Clang``.  The
+NEW behavior for this policy is to use compiler id ``AppleClang``.
 
-This policy was introduced in CMake version 3.0.  CMake version
-|release| warns when the policy is not set and uses OLD behavior.  Use
-the cmake_policy command to set it to OLD or NEW explicitly.
+This policy was introduced in CMake version 3.0.  Use the
+:command:`cmake_policy` command to set this policy to OLD or NEW explicitly.
+Unlike most policies, CMake version |release| does *not* warn
+by default when this policy is not set and simply uses OLD behavior.
+See documentation of the
+:variable:`CMAKE_POLICY_WARNING_CMP0025 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
+variable to control the warning.