From 97e8650d7bd213e5fde721a0f7d71b63ac238370 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 4 Oct 2013 15:34:11 -0400 Subject: [PATCH] Help: Factor out COMPILE_DEFINITIONS disclaimer duplication The COMPILE_DEFINITIONS escaping disclaimer was represented in builtin documentation using a preprocessor macro. Factor the duplicate content out into a separate .txt file and include it in each document with the reStructuredText include directive. --- .../COMPILE_DEFINITIONS_DISCLAIMER.txt | 18 ++++++++++++++++ Help/prop_dir/COMPILE_DEFINITIONS.rst | 21 +------------------ Help/prop_sf/COMPILE_DEFINITIONS.rst | 21 +------------------ Help/prop_tgt/COMPILE_DEFINITIONS.rst | 21 +------------------ 4 files changed, 21 insertions(+), 60 deletions(-) create mode 100644 Help/include/COMPILE_DEFINITIONS_DISCLAIMER.txt diff --git a/Help/include/COMPILE_DEFINITIONS_DISCLAIMER.txt b/Help/include/COMPILE_DEFINITIONS_DISCLAIMER.txt new file mode 100644 index 000000000..6797d0e2b --- /dev/null +++ b/Help/include/COMPILE_DEFINITIONS_DISCLAIMER.txt @@ -0,0 +1,18 @@ +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:: + + # - broken almost everywhere + ; - broken in VS IDE 7.0 and Borland Makefiles + , - broken in VS IDE + % - broken in some cases in NMake + & | - broken in some cases on MinGW + ^ < > \" - broken in most Make tools on Windows + +CMake does not reject these values outright because they do work in +some cases. Use with caution. diff --git a/Help/prop_dir/COMPILE_DEFINITIONS.rst b/Help/prop_dir/COMPILE_DEFINITIONS.rst index bc5f754d6..290d61208 100644 --- a/Help/prop_dir/COMPILE_DEFINITIONS.rst +++ b/Help/prop_dir/COMPILE_DEFINITIONS.rst @@ -17,23 +17,4 @@ CMake will automatically drop some definitions that are not supported by the native build tool. The VS6 IDE does not support definition values with spaces (but NMake does). -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: - -:: - - # - broken almost everywhere - ; - broken in VS IDE 7.0 and Borland Makefiles - , - broken in VS IDE - % - broken in some cases in NMake - & | - broken in some cases on MinGW - ^ < > \" - broken in most Make tools on Windows - -CMake does not reject these values outright because they do work in -some cases. Use with caution. +.. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt diff --git a/Help/prop_sf/COMPILE_DEFINITIONS.rst b/Help/prop_sf/COMPILE_DEFINITIONS.rst index 334b15834..7f7e7c795 100644 --- a/Help/prop_sf/COMPILE_DEFINITIONS.rst +++ b/Help/prop_sf/COMPILE_DEFINITIONS.rst @@ -17,23 +17,4 @@ by the native build tool. The VS6 IDE does not support definition values with spaces (but NMake does). Xcode does not support per-configuration definitions on source files. -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: - -:: - - # - broken almost everywhere - ; - broken in VS IDE 7.0 and Borland Makefiles - , - broken in VS IDE - % - broken in some cases in NMake - & | - broken in some cases on MinGW - ^ < > \" - broken in most Make tools on Windows - -CMake does not reject these values outright because they do work in -some cases. Use with caution. +.. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt diff --git a/Help/prop_tgt/COMPILE_DEFINITIONS.rst b/Help/prop_tgt/COMPILE_DEFINITIONS.rst index dabc0224c..b6999fcaa 100644 --- a/Help/prop_tgt/COMPILE_DEFINITIONS.rst +++ b/Help/prop_tgt/COMPILE_DEFINITIONS.rst @@ -92,23 +92,4 @@ Expressions with an implicit 'this' target: $ = The value of the property prop on the target on which the generator expression is evaluated. -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: - -:: - - # - broken almost everywhere - ; - broken in VS IDE 7.0 and Borland Makefiles - , - broken in VS IDE - % - broken in some cases in NMake - & | - broken in some cases on MinGW - ^ < > \" - broken in most Make tools on Windows - -CMake does not reject these values outright because they do work in -some cases. Use with caution. +.. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt