ENH: Improve documentation of cmake_policy command.

  - Add a paragraph introducing the policy mechanism
  - Explicitly introduce the CMP<NNNN>, OLD, and NEW notation
  - Note that setting policies by CMake version is preferred
  - Fix SET signature to use CMP<NNNN> notation
  - Add more details about the policy stack

Source/cmCMakePolicyCommand.h

@@ -58,7 +58,7 @@ public:
    */
   virtual const char* GetTerseDocumentation() 
     {
-    return "Manage CMake policy settings.";
+    return "Manage CMake Policy settings.";
     }
   
   /**
@@ -67,13 +67,31 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
+      "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.\n"
+      "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.\n"
       "  cmake_policy(VERSION major.minor[.patch])\n"
       "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 NEW.  "
-      "All policies introduced after the specified version will be set "
-      "to WARN, which is like OLD but also produces a warning.  "
+      "will be set to use NEW behavior.  "
+      "All policies introduced after the specified version will be reset "
+      "to use OLD behavior with a warning.  "
       "This effectively requests behavior preferred as of a given CMake "
       "version and tells newer CMake versions to warn about their new "
       "policies.  "
@@ -82,8 +100,8 @@ public:
       "In order to get compatibility features supporting versions earlier "
       "than 2.4 see documentation of policy CMP0001."
       "\n"
-      "  cmake_policy(SET <CMPNNNN> NEW)\n"
-      "  cmake_policy(SET <CMPNNNN> OLD)\n"
+      "  cmake_policy(SET CMP<NNNN> NEW)\n"
+      "  cmake_policy(SET CMP<NNNN> OLD)\n"
       "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.  "
@@ -96,8 +114,10 @@ public:
       "Each PUSH must have a matching POP.  "
       "This is useful when mixing multiple projects, subprojects, and "
       "files included from external projects that may each have been "
-      "written for a different version of CMake."
-      ;
+      "written for a different version of CMake.  "
+      "Each subdirectory entered by the project automatically pushes "
+      "a new level on the stack to isolate the subdirectories from "
+      "their parents.";
     }
   
   cmTypeMacro(cmCMakePolicyCommand, cmCommand);