Help: Document explicitly that policy OLD behavior is deprecated

The most likely documentation page a project author will read in
response to a policy warning is the page for the policy itself.
Add to every policy documentation page a note explicitly stating
that the OLD behavior is deprecated.  Also mention this in the
cmake_policy() command documentation that explains how to set a
policy to OLD.

Suggested-by: Fraser Hutchison <[email protected]>

Help/command/cmake_policy.rst

@@ -53,6 +53,8 @@ policy warning by setting the policy state to ``OLD``.  Alternatively
 one may fix the project to work with the new behavior and set the
 policy state to ``NEW``.
 
+.. include:: ../policy/DEPRECATED.txt
+
 Checking Policy Settings
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

Help/manual/cmake-policies.7.rst

@@ -20,11 +20,11 @@ for a policy, also avoiding the warning.  Each policy can also be set to
 either ``NEW`` or ``OLD`` behavior explicitly on the command line with the
 :variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable.
 
-Note that policies are not reliable feature toggles.  A policy should
-almost never be set to ``OLD``, except to silence warnings in an otherwise
-frozen or stable codebase, or temporarily as part of a larger migration
-path. The ``OLD`` behavior of each policy is undesirable and will be
-replaced with an error condition in a future release.
+A policy is a deprecation mechanism and not a reliable feature toggle.
+A policy should almost never be set to ``OLD``, except to silence warnings
+in an otherwise frozen or stable codebase, or temporarily as part of a
+larger migration path. The ``OLD`` behavior of each policy is undesirable
+and will be replaced with an error condition in a future release.
 
 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

Help/policy/CMP0000.rst

@@ -28,3 +28,5 @@ a warning.  An included file may set CMP0000 explicitly to affect how
 this policy is enforced for the main CMakeLists.txt file.
 
 This policy was introduced in CMake version 2.6.0.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0001.rst

@@ -17,3 +17,5 @@ below.
 This policy was introduced in CMake version 2.6.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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0002.rst

@@ -24,3 +24,5 @@ property ALLOW_DUPLICATE_CUSTOM_TARGETS with a Makefiles generator).
 This policy was introduced in CMake version 2.6.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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0003.rst

@@ -100,3 +100,5 @@ when setting the policy once will probably fix all targets.
 This policy was introduced in CMake version 2.6.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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0004.rst

@@ -21,3 +21,5 @@ target is created by an add_executable or add_library command.
 This policy was introduced in CMake version 2.6.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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0005.rst

@@ -22,3 +22,5 @@ limitations of the escaping implementation.
 This policy was introduced in CMake version 2.6.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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0006.rst

@@ -20,3 +20,5 @@ without a BUNDLE DESTINATION.
 This policy was introduced in CMake version 2.6.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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0007.rst

@@ -13,3 +13,5 @@ empty elements in a list.
 This policy was introduced in CMake version 2.6.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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0008.rst

@@ -30,3 +30,5 @@ pass it directly to the native build tool unchanged.
 This policy was introduced in CMake version 2.6.1.  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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0009.rst

@@ -17,3 +17,5 @@ as an additional argument to the FILE command.
 This policy was introduced in CMake version 2.6.2.  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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0010.rst

@@ -16,3 +16,5 @@ and is treated as always being ``NEW``.
 This policy was introduced in CMake version 2.6.3.  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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0011.rst

@@ -20,3 +20,5 @@ cmake_policy PUSH and POP.
 This policy was introduced in CMake version 2.6.3.  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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0012.rst

@@ -23,3 +23,5 @@ dereferencing variables with such names.
 This policy was introduced in CMake version 2.8.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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0013.rst

@@ -17,3 +17,5 @@ with an error.
 This policy was introduced in CMake version 2.8.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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0014.rst

@@ -13,3 +13,5 @@ behavior for this policy is to report an error.
 This policy was introduced in CMake version 2.8.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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0015.rst

@@ -15,3 +15,5 @@ paths by appending the relative path to CMAKE_CURRENT_SOURCE_DIR.
 This policy was introduced in CMake version 2.8.1.  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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0016.rst

@@ -11,3 +11,5 @@ in this case.
 This policy was introduced in CMake version 2.8.3.  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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0017.rst

@@ -17,3 +17,5 @@ from the CMake modules directory.
 This policy was introduced in CMake version 2.8.4.  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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0018.rst

@@ -30,3 +30,5 @@ honor the POSITION_INDEPENDENT_CODE target property.
 This policy was introduced in CMake version 2.8.9.  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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0019.rst

@@ -18,3 +18,5 @@ the values untouched.
 This policy was introduced in CMake version 2.8.11.  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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0020.rst

@@ -23,3 +23,5 @@ automatically when they link to QtCore IMPORTED target.
 This policy was introduced in CMake version 2.8.11.  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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0021.rst

@@ -16,3 +16,5 @@ relative path.
 This policy was introduced in CMake version 2.8.12.  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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0022.rst

@@ -35,3 +35,5 @@ property for in-build targets, and ignore the old properties matching
 This policy was introduced in CMake version 2.8.12.  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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0023.rst

@@ -31,3 +31,5 @@ signatures.
 This policy was introduced in CMake version 2.8.12.  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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0024.rst

@@ -20,3 +20,5 @@ allow including the result of an export() command.
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0025.rst

@@ -25,3 +25,5 @@ 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0026.rst

@@ -24,3 +24,5 @@ not to allow reading the LOCATION properties from build-targets.
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0027.rst

@@ -23,3 +23,5 @@ conditionally linked IMPORTED target does not exist.
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0028.rst

@@ -21,3 +21,5 @@ double-colons but is not an IMPORTED target or an ALIAS target.
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0029.rst

@@ -8,3 +8,5 @@ but was kept in CMake for compatibility for a long time.
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0030.rst

@@ -9,3 +9,5 @@ not used it in years.
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0031.rst

@@ -11,3 +11,5 @@ the CMake process.  It has been mostly superseded by the
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0032.rst

@@ -11,3 +11,5 @@ functionality is better achieved through dedicated outside tools.
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0033.rst

@@ -12,3 +12,5 @@ The functionality has been superseded by the :command:`export` and
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0034.rst

@@ -9,3 +9,5 @@ generate other files.  This approach has long been replaced by
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0035.rst

@@ -8,3 +8,5 @@ logic.  It has long been replaced by the :command:`if` command.
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0036.rst

@@ -10,3 +10,5 @@ and :variable:`CMAKE_<LANG>_COMPILER` variables.
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0037.rst

@@ -24,3 +24,5 @@ if an add_* command is used with an invalid target name.
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0038.rst

@@ -14,3 +14,5 @@ report an error if a target attempts to link to itself.
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0039.rst

@@ -15,3 +15,5 @@ utility target.
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0040.rst

@@ -14,3 +14,5 @@ if the target referenced in :command:`add_custom_command` is unknown.
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0041.rst

@@ -23,3 +23,5 @@ relative.
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0042.rst

@@ -17,3 +17,5 @@ variables.
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0043.rst

@@ -43,3 +43,5 @@ of the :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property .
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0044.rst

@@ -17,3 +17,5 @@ the ``<LANG>_COMPILER_ID`` expression.
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0045.rst

@@ -15,3 +15,5 @@ non-existent target.
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0046.rst

@@ -15,3 +15,5 @@ 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0047.rst

@@ -26,3 +26,5 @@ by default when this policy is not set and simply uses OLD behavior.
 See documentation of the
 :variable:`CMAKE_POLICY_WARNING_CMP0047 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
 variable to control the warning.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0048.rst

@@ -20,3 +20,5 @@ 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0049.rst

@@ -21,3 +21,5 @@ 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0050.rst

@@ -16,3 +16,5 @@ 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0051.rst

@@ -22,3 +22,5 @@ This policy was introduced in CMake version 3.1.
 CMake version |release| warns when the policy is not set and uses
 ``OLD`` behavior.  Use the :command:`cmake_policy` command to set it
 to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0052.rst

@@ -22,3 +22,5 @@ This policy was introduced in CMake version 3.1.
 CMake version |release| warns when the policy is not set and uses
 ``OLD`` behavior.  Use the :command:`cmake_policy` command to set it
 to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0053.rst

@@ -42,3 +42,5 @@ This policy was introduced in CMake version 3.1.
 CMake version |release| warns when the policy is not set and uses
 ``OLD`` behavior.  Use the :command:`cmake_policy` command to set
 it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0054.rst

@@ -48,3 +48,5 @@ This policy was introduced in CMake version 3.1.
 CMake version |release| warns when the policy is not set and uses
 ``OLD`` behavior.  Use the :command:`cmake_policy` command to set
 it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0055.rst

@@ -15,3 +15,5 @@ This policy was introduced in CMake version 3.2.
 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.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0056.rst

@@ -30,3 +30,5 @@ 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_CMP0056 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
 variable to control the warning.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0057.rst

@@ -12,3 +12,5 @@ This policy was introduced in CMake version 3.3.
 CMake version |release| warns when the policy is not set and uses
 ``OLD`` behavior.  Use the :command:`cmake_policy` command to set
 it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0058.rst

@@ -106,3 +106,5 @@ out-of-source build trees if the policy is not set and then uses
 the policy to ``OLD`` or ``NEW`` explicitly.  The policy setting
 must be in scope at the end of the top-level ``CMakeLists.txt``
 file of the project and has global effect.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0059.rst

@@ -15,3 +15,5 @@ This policy was introduced in CMake version 3.3.
 CMake version |release| warns when the policy is not set and uses
 ``OLD`` behavior.  Use the :command:`cmake_policy` command to set
 it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0060.rst

@@ -61,3 +61,5 @@ 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_CMP0060 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
 variable to control the warning.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0061.rst

@@ -22,3 +22,5 @@ add ``-i``.
 This policy was introduced in CMake version 3.3.  Unlike most policies,
 CMake version |release| does *not* warn when this policy is not set and
 simply uses OLD behavior.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0062.rst

@@ -25,3 +25,5 @@ This policy was introduced in CMake version 3.3.  CMake version
 |release| warns when the policy is not set and uses ``OLD`` behavior.  Use
 the :command:`cmake_policy()` command to set it to ``OLD`` or ``NEW``
 explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0063.rst

@@ -24,3 +24,5 @@ This policy was introduced in CMake version 3.3.  CMake version
 |release| warns when the policy is not set and uses ``OLD`` behavior.  Use
 the :command:`cmake_policy()` command to set it to ``OLD`` or ``NEW``
 explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/DEPRECATED.txt

@@ -0,0 +1,4 @@
+.. note::
+  The ``OLD`` behavior of a policy is
+  :manual:`deprecated by definition <cmake-policies(7)>`
+  and may be removed in a future version of CMake.