ENH: Clarify VERBATIM option documentation

The previous wording of the VERBATIM option documentation in the
add_custom_command and add_custom_target commands was confusing.  It
could be interpreted as the opposite of what the option means (no
escaping instead of escaping).  This clarifies the documentation to
explicitly state that it escapes.

2 files changed, 12 insertions, 11 deletions

diff --git a/Source/cmAddCustomCommandCommand.h b/Source/cmAddCustomCommandCommand.h
index 8add970..e750ebf 100644
--- a/Source/cmAddCustomCommandCommand.h
+++ b/Source/cmAddCustomCommandCommand.h
@@ -123,14 +123,15 @@ public:
       "options are currently ignored when APPEND is given, "
       "but may be used in the future."
       "\n"
-      "If VERBATIM is given then all the arguments to the commands will be "
-      "passed exactly as specified no matter the build tool used. "
+      "If VERBATIM is given then all arguments to the commands will be "
+      "escaped properly for the build tool so that the invoked command "
+      "receives each argument unchanged.  "
       "Note that one level of escapes is still used by the CMake language "
-      "processor before ADD_CUSTOM_TARGET even sees the arguments. "
+      "processor before add_custom_command even sees the arguments. "
       "Use of VERBATIM is recommended as it enables correct behavior. "
-      "When VERBATIM is not given the behavior is platform specific. "
-      "In the future VERBATIM may be enabled by default. The only reason "
-      "it is an option is to preserve compatibility with older CMake code.\n"
+      "When VERBATIM is not given the behavior is platform specific because "
+      "there is no protection of tool-specific special characters."
+      "\n"
       "If the output of the custom command is not actually "
       "created as a file on disk it should be marked as SYMBOLIC with "
       "SET_SOURCE_FILES_PROPERTIES.\n"
diff --git a/Source/cmAddCustomTargetCommand.h b/Source/cmAddCustomTargetCommand.h
index c4895c0..71b60e6 100644
--- a/Source/cmAddCustomTargetCommand.h
+++ b/Source/cmAddCustomTargetCommand.h
@@ -89,14 +89,14 @@ public:
       "Dependencies listed with the DEPENDS argument may reference files "
       "and outputs of custom commands created with add_custom_command() in "
       "the same directory (CMakeLists.txt file).\n"
-      "If VERBATIM is given then all the arguments to the commands will be "
-      "passed exactly as specified no matter the build tool used. "
+      "If VERBATIM is given then all arguments to the commands will be "
+      "escaped properly for the build tool so that the invoked command "
+      "receives each argument unchanged.  "
       "Note that one level of escapes is still used by the CMake language "
       "processor before add_custom_target even sees the arguments. "
       "Use of VERBATIM is recommended as it enables correct behavior. "
-      "When VERBATIM is not given the behavior is platform specific. "
-      "In the future VERBATIM may be enabled by default. The only reason "
-      "it is an option is to preserve compatibility with older CMake code."
+      "When VERBATIM is not given the behavior is platform specific because "
+      "there is no protection of tool-specific special characters."
       "\n"
       "The SOURCES option specifies additional source files to be included "
       "in the custom target.  "