Convert builtin help to reStructuredText source files

Run the convert-help.bash script to convert documentation:

 ./convert-help.bash "/path/to/CMake-build/bin"

Then remove it.

1 files changed, 78 insertions, 0 deletions

diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst
new file mode 100644
index 0000000..46db8d3
--- /dev/null
+++ b/Help/command/cmake_policy.rst
@@ -0,0 +1,78 @@
+cmake_policy
+------------
+
+Manage CMake Policy settings.
+
+As CMake evolves it is sometimes necessary to change existing behavior
+in order to fix bugs or improve implementations of existing features.
+The CMake Policy mechanism is designed to help keep existing projects
+building as new versions of CMake introduce changes in behavior.  Each
+new policy (behavioral change) is given an identifier of the form
+"CMP<NNNN>" where "<NNNN>" is an integer index.  Documentation
+associated with each policy describes the OLD and NEW behavior and the
+reason the policy was introduced.  Projects may set each policy to
+select the desired behavior.  When CMake needs to know which behavior
+to use it checks for a setting specified by the project.  If no
+setting is available the OLD behavior is assumed and a warning is
+produced requesting that the policy be set.
+
+The cmake_policy command is used to set policies to OLD or NEW
+behavior.  While setting policies individually is supported, we
+encourage projects to set policies based on CMake versions.
+
+::
+
+  cmake_policy(VERSION major.minor[.patch[.tweak]])
+
+Specify that the current CMake list file is written for the given
+version of CMake.  All policies introduced in the specified version or
+earlier will be set to use NEW behavior.  All policies introduced
+after the specified version will be unset (unless variable
+CMAKE_POLICY_DEFAULT_CMP<NNNN> sets a default).  This effectively
+requests behavior preferred as of a given CMake version and tells
+newer CMake versions to warn about their new policies.  The policy
+version specified must be at least 2.4 or the command will report an
+error.  In order to get compatibility features supporting versions
+earlier than 2.4 see documentation of policy CMP0001.
+
+::
+
+  cmake_policy(SET CMP<NNNN> NEW)
+  cmake_policy(SET CMP<NNNN> OLD)
+
+Tell CMake to use the OLD or NEW behavior for a given policy.
+Projects depending on the old behavior of a given policy may silence a
+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.
+
+::
+
+  cmake_policy(GET CMP<NNNN> <variable>)
+
+Check whether a given policy is set to OLD or NEW behavior.  The
+output variable value will be "OLD" or "NEW" if the policy is set, and
+empty otherwise.
+
+CMake keeps policy settings on a stack, so changes made by the
+cmake_policy command affect only the top of the stack.  A new entry on
+the policy stack is managed automatically for each subdirectory to
+protect its parents and siblings.  CMake also manages a new entry for
+scripts loaded by include() and find_package() commands except when
+invoked with the NO_POLICY_SCOPE option (see also policy CMP0011).
+The cmake_policy command provides an interface to manage custom
+entries on the policy stack:
+
+::
+
+  cmake_policy(PUSH)
+  cmake_policy(POP)
+
+Each PUSH must have a matching POP to erase any changes.  This is
+useful to make temporary changes to policy settings.
+
+Functions and macros record policy settings when they are created and
+use the pre-record policies when they are invoked.  If the function or
+macro implementation sets policies, the changes automatically
+propagate up through callers until they reach the closest nested
+policy stack entry.