Merge topic 'doc-hard-preprocessor-characters'

c64d138 Document COMPILE_DEFINITIONS known limitations (#11660, #11712)
668ce6b Combine duplicate COMPILE_DEFINITIONS disclaimer

5 files changed, 41 insertions, 25 deletions

diff --git a/Source/CMakeLists.txt b/Source/CMakeLists.txt
index f183eb4..7722c19 100644
--- a/Source/CMakeLists.txt
+++ b/Source/CMakeLists.txt
@@ -158,6 +158,7 @@ SET(SRCS
   cmDocumentationFormatterText.cxx
   cmDocumentationFormatterUsage.cxx
   cmDocumentationSection.cxx
+  cmDocumentCompileDefinitions.h
   cmDocumentGeneratorExpressions.h
   cmDocumentVariables.cxx
   cmDynamicLoader.cxx
diff --git a/Source/cmDocumentCompileDefinitions.h b/Source/cmDocumentCompileDefinitions.h
new file mode 100644
index 0000000..ef3b3e7
--- /dev/null
+++ b/Source/cmDocumentCompileDefinitions.h
@@ -0,0 +1,34 @@
+/*============================================================================
+  CMake - Cross Platform Makefile Generator
+  Copyright 2000-2011 Kitware, Inc., Insight Software Consortium
+
+  Distributed under the OSI-approved BSD License (the "License");
+  see accompanying file Copyright.txt for details.
+
+  This software is distributed WITHOUT ANY WARRANTY; without even the
+  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the License for more information.
+============================================================================*/
+#ifndef cmDocumentCompileDefinitions_h
+#define cmDocumentCompileDefinitions_h
+
+#define CM_DOCUMENT_COMPILE_DEFINITIONS_DISCLAIMER \
+  "Disclaimer: Most native build tools have poor support for escaping " \
+  "certain values.  CMake has work-arounds for many cases but some "    \
+  "values may just not be possible to pass correctly.  If a value "     \
+  "does not seem to be escaped correctly, do not attempt to "           \
+  "work-around the problem by adding escape sequences to the value.  "  \
+  "Your work-around may break in a future version of CMake that "       \
+  "has improved escape support.  Instead consider defining the macro "  \
+  "in a (configured) header file.  Then report the limitation.  "       \
+  "Known limitations include:\n"                                        \
+  "  #          - broken almost everywhere\n"                           \
+  "  ;          - broken in VS IDE and Borland Makefiles\n"             \
+  "  ,          - broken in VS IDE\n"                                   \
+  "  %          - broken in some cases in NMake\n"                      \
+  "  & |        - broken in some cases on MinGW\n"                      \
+  "  ^ < > \\\"   - broken in most Make tools on Windows\n"             \
+  "CMake does not reject these values outright because they do work "   \
+  "in some cases.  Use with caution.  "
+
+#endif
diff --git a/Source/cmMakefile.cxx b/Source/cmMakefile.cxx
index 53f4c3c..41d36dc 100644
--- a/Source/cmMakefile.cxx
+++ b/Source/cmMakefile.cxx
@@ -22,6 +22,7 @@
 #include "cmFunctionBlocker.h"
 #include "cmListFileCache.h"
 #include "cmCommandArgumentParserHelper.h"
+#include "cmDocumentCompileDefinitions.h"
 #include "cmTest.h"
 #ifdef CMAKE_BUILD_WITH_CMAKE
 #  include "cmVariableWatch.h"
@@ -3492,14 +3493,7 @@ void cmMakefile::DefineProperties(cmake *cm)
      "are not supported by the native build tool.  "
      "The VS6 IDE does not support definition values with spaces "
      "(but NMake does).\n"
-     "Dislaimer: Most native build tools have poor support for escaping "
-     "certain values.  CMake has work-arounds for many cases but some "
-     "values may just not be possible to pass correctly.  If a value "
-     "does not seem to be escaped correctly, do not attempt to "
-     "work-around the problem by adding escape sequences to the value.  "
-     "Your work-around may break in a future version of CMake that "
-     "has improved escape support.  Instead consider defining the macro "
-     "in a (configured) header file.  Then report the limitation.");
+     CM_DOCUMENT_COMPILE_DEFINITIONS_DISCLAIMER);
 
   cm->DefineProperty
     ("COMPILE_DEFINITIONS_<CONFIG>", cmProperty::DIRECTORY,
diff --git a/Source/cmSourceFile.cxx b/Source/cmSourceFile.cxx
index 26328cf..84b728e 100644
--- a/Source/cmSourceFile.cxx
+++ b/Source/cmSourceFile.cxx
@@ -16,6 +16,7 @@
 #include "cmMakefile.h"
 #include "cmSystemTools.h"
 #include "cmake.h"
+#include "cmDocumentCompileDefinitions.h"
 
 //----------------------------------------------------------------------------
 cmSourceFile::cmSourceFile(cmMakefile* mf, const char* name):
@@ -411,15 +412,7 @@ void cmSourceFile::DefineProperties(cmake *cm)
      "The VS6 IDE does not support definition values with spaces "
      "(but NMake does).  Xcode does not support per-configuration "
      "definitions on source files.\n"
-     "Disclaimer: Most native build tools have poor support for escaping "
-     "certain values.  CMake has work-arounds for many cases but some "
-     "values may just not be possible to pass correctly.  If a value "
-     "does not seem to be escaped correctly, do not attempt to "
-     "work-around the problem by adding escape sequences to the value.  "
-     "Your work-around may break in a future version of CMake that "
-     "has improved escape support.  Instead consider defining the macro "
-     "in a (configured) header file.  Then report the limitation.");
-
+     CM_DOCUMENT_COMPILE_DEFINITIONS_DISCLAIMER);
 
   cm->DefineProperty
     ("COMPILE_DEFINITIONS_<CONFIG>", cmProperty::SOURCE_FILE,
diff --git a/Source/cmTarget.cxx b/Source/cmTarget.cxx
index 52574e2..72efce3 100644
--- a/Source/cmTarget.cxx
+++ b/Source/cmTarget.cxx
@@ -16,6 +16,7 @@
 #include "cmLocalGenerator.h"
 #include "cmGlobalGenerator.h"
 #include "cmComputeLinkInformation.h"
+#include "cmDocumentCompileDefinitions.h"
 #include "cmListFileCache.h"
 #include "cmGeneratorExpression.h"
 #include <cmsys/RegularExpression.hxx>
@@ -146,14 +147,7 @@ void cmTarget::DefineProperties(cmake *cm)
      "are not supported by the native build tool.  "
      "The VS6 IDE does not support definition values with spaces "
      "(but NMake does).\n"
-     "Dislaimer: Most native build tools have poor support for escaping "
-     "certain values.  CMake has work-arounds for many cases but some "
-     "values may just not be possible to pass correctly.  If a value "
-     "does not seem to be escaped correctly, do not attempt to "
-     "work-around the problem by adding escape sequences to the value.  "
-     "Your work-around may break in a future version of CMake that "
-     "has improved escape support.  Instead consider defining the macro "
-     "in a (configured) header file.  Then report the limitation.");
+     CM_DOCUMENT_COMPILE_DEFINITIONS_DISCLAIMER);
 
   cm->DefineProperty
     ("COMPILE_DEFINITIONS_<CONFIG>", cmProperty::TARGET,