Merge topic 'doc-policy-default'

69b70968bd Help: Suggest CMAKE_POLICY_DEFAULT_CMP0126 in CMP0126 docs
5b1c24255f Help: Suggest CMAKE_POLICY_DEFAULT_CMP0077 in CMP0077 docs
c44636a89b Help: Document more use cases for CMAKE_POLICY_DEFAULT_CMPNNNN

Acked-by: Kitware Robot <[email protected]>
Merge-request: !6756

Help/policy/CMP0077.rst

@@ -53,6 +53,8 @@ between the two policies.
 This policy was introduced in CMake version 3.13.  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.
+explicitly within a project.  Use the :variable:`CMAKE_POLICY_DEFAULT_CMP0077
+<CMAKE_POLICY_DEFAULT_CMP\<NNNN\>>` variable to set the policy for
+a third-party project in a subdirectory without modifying it.
 
 .. include:: DEPRECATED.txt

Help/policy/CMP0126.rst

@@ -22,7 +22,10 @@ will *not* set the cache variable if a non-cache variable of the same name
 already exists and :policy:`CMP0077` is set to ``NEW``.
 
 Policy ``CMP0126`` was introduced in CMake version 3.21. Use the
-:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly
+within a project.  Use the :variable:`CMAKE_POLICY_DEFAULT_CMP0126
+<CMAKE_POLICY_DEFAULT_CMP\<NNNN\>>` variable to set the policy for
+a third-party project in a subdirectory without modifying it.
 Unlike many policies, CMake version |release| does *not* warn when the policy
 is not set and simply uses ``OLD`` behavior.  See documentation of the
 :variable:`CMAKE_POLICY_WARNING_CMP0126 <CMAKE_POLICY_WARNING_CMP<NNNN>>`

Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst

@@ -9,9 +9,16 @@ the given version unset.  Set ``CMAKE_POLICY_DEFAULT_CMP<NNNN>`` to ``OLD``
 or ``NEW`` to specify the default for policy ``CMP<NNNN>``, where ``<NNNN>``
 is the policy number.
 
-This variable should not be set by a project in CMake code; use
-:command:`cmake_policy(SET)` instead.  Users running CMake may set this
-variable in the cache (e.g. ``-DCMAKE_POLICY_DEFAULT_CMP<NNNN>=<OLD|NEW>``)
-to set a policy not otherwise set by the project.  Set to ``OLD`` to quiet a
-policy warning while using old behavior or to ``NEW`` to try building the
-project with new behavior.
+This variable should not be set by a project in CMake code as a way to
+set its own policies; use :command:`cmake_policy(SET)` instead.  This
+variable is meant to externally set policies for which a project has
+not itself been updated:
+
+* Users running CMake may set this variable in the cache
+  (e.g. ``-DCMAKE_POLICY_DEFAULT_CMP<NNNN>=<OLD|NEW>``).  Set it to ``OLD``
+  to quiet a policy warning while using old behavior or to ``NEW`` to
+  try building the project with new behavior.
+
+* Projects may set this variable before a call to :command:`add_subdirectory`
+  that adds a third-party project in order to set its policies without
+  modifying third-party code.