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.

17 files changed, 196 insertions, 0 deletions

diff --git a/Help/prop_sf/ABSTRACT.rst b/Help/prop_sf/ABSTRACT.rst
new file mode 100644
index 0000000000..339d115287
--- /dev/null
+++ b/Help/prop_sf/ABSTRACT.rst
@@ -0,0 +1,9 @@
+ABSTRACT
+--------
+
+Is this source file an abstract class.
+
+A property on a source file that indicates if the source file
+represents a class that is abstract.  This only makes sense for
+languages that have a notion of an abstract class and it is only used
+by some tools that wrap classes into other languages.
diff --git a/Help/prop_sf/COMPILE_DEFINITIONS.rst b/Help/prop_sf/COMPILE_DEFINITIONS.rst
new file mode 100644
index 0000000000..334b158343
--- /dev/null
+++ b/Help/prop_sf/COMPILE_DEFINITIONS.rst
@@ -0,0 +1,39 @@
+COMPILE_DEFINITIONS
+-------------------
+
+Preprocessor definitions for compiling a source file.
+
+The COMPILE_DEFINITIONS property may be set to a semicolon-separated
+list of preprocessor definitions using the syntax VAR or VAR=value.
+Function-style definitions are not supported.  CMake will
+automatically escape the value correctly for the native build system
+(note that CMake language syntax may require escapes to specify some
+values).  This property may be set on a per-configuration basis using
+the name COMPILE_DEFINITIONS_<CONFIG> where <CONFIG> is an upper-case
+name (ex.  "COMPILE_DEFINITIONS_DEBUG").
+
+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).  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.
diff --git a/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst b/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst
new file mode 100644
index 0000000000..e695f3824a
--- /dev/null
+++ b/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst
@@ -0,0 +1,8 @@
+COMPILE_DEFINITIONS_<CONFIG>
+----------------------------
+
+Per-configuration preprocessor definitions on a source file.
+
+This is the configuration-specific version of COMPILE_DEFINITIONS.
+Note that Xcode does not support per-configuration source file flags
+so this property will be ignored by the Xcode generator.
diff --git a/Help/prop_sf/COMPILE_FLAGS.rst b/Help/prop_sf/COMPILE_FLAGS.rst
new file mode 100644
index 0000000000..daba50231f
--- /dev/null
+++ b/Help/prop_sf/COMPILE_FLAGS.rst
@@ -0,0 +1,8 @@
+COMPILE_FLAGS
+-------------
+
+Additional flags to be added when compiling this source file.
+
+These flags will be added to the list of compile flags when this
+source file builds.  Use COMPILE_DEFINITIONS to pass additional
+preprocessor definitions.
diff --git a/Help/prop_sf/EXTERNAL_OBJECT.rst b/Help/prop_sf/EXTERNAL_OBJECT.rst
new file mode 100644
index 0000000000..efa0e9bea1
--- /dev/null
+++ b/Help/prop_sf/EXTERNAL_OBJECT.rst
@@ -0,0 +1,8 @@
+EXTERNAL_OBJECT
+---------------
+
+If set to true then this is an object file.
+
+If this property is set to true then the source file is really an
+object file and should not be compiled.  It will still be linked into
+the target though.
diff --git a/Help/prop_sf/Fortran_FORMAT.rst b/Help/prop_sf/Fortran_FORMAT.rst
new file mode 100644
index 0000000000..69e34aafd7
--- /dev/null
+++ b/Help/prop_sf/Fortran_FORMAT.rst
@@ -0,0 +1,9 @@
+Fortran_FORMAT
+--------------
+
+Set to FIXED or FREE to indicate the Fortran source layout.
+
+This property tells CMake whether a given Fortran source file uses
+fixed-format or free-format.  CMake will pass the corresponding format
+flag to the compiler.  Consider using the target-wide Fortran_FORMAT
+property if all source files in a target share the same format.
diff --git a/Help/prop_sf/GENERATED.rst b/Help/prop_sf/GENERATED.rst
new file mode 100644
index 0000000000..a3aa127471
--- /dev/null
+++ b/Help/prop_sf/GENERATED.rst
@@ -0,0 +1,8 @@
+GENERATED
+---------
+
+Is this source file generated as part of the build process.
+
+If a source file is generated by the build process CMake will handle
+it differently in terms of dependency checking etc.  Otherwise having
+a non-existent source file could create problems.
diff --git a/Help/prop_sf/HEADER_FILE_ONLY.rst b/Help/prop_sf/HEADER_FILE_ONLY.rst
new file mode 100644
index 0000000000..b4fb2db22e
--- /dev/null
+++ b/Help/prop_sf/HEADER_FILE_ONLY.rst
@@ -0,0 +1,9 @@
+HEADER_FILE_ONLY
+----------------
+
+Is this source file only a header file.
+
+A property on a source file that indicates if the source file is a
+header file with no associated implementation.  This is set
+automatically based on the file extension and is used by CMake to
+determine if certain dependency information should be computed.
diff --git a/Help/prop_sf/KEEP_EXTENSION.rst b/Help/prop_sf/KEEP_EXTENSION.rst
new file mode 100644
index 0000000000..d6167e5a9a
--- /dev/null
+++ b/Help/prop_sf/KEEP_EXTENSION.rst
@@ -0,0 +1,9 @@
+KEEP_EXTENSION
+--------------
+
+Make the output file have the same extension as the source file.
+
+If this property is set then the file extension of the output file
+will be the same as that of the source file.  Normally the output file
+extension is computed based on the language of the source file, for
+example .cxx will go to a .o extension.
diff --git a/Help/prop_sf/LABELS.rst b/Help/prop_sf/LABELS.rst
new file mode 100644
index 0000000000..e1c10696a5
--- /dev/null
+++ b/Help/prop_sf/LABELS.rst
@@ -0,0 +1,8 @@
+LABELS
+------
+
+Specify a list of text labels associated with a source file.
+
+This property has meaning only when the source file is listed in a
+target whose LABELS property is also set.  No other semantics are
+currently specified.
diff --git a/Help/prop_sf/LANGUAGE.rst b/Help/prop_sf/LANGUAGE.rst
new file mode 100644
index 0000000000..97bfa20f46
--- /dev/null
+++ b/Help/prop_sf/LANGUAGE.rst
@@ -0,0 +1,10 @@
+LANGUAGE
+--------
+
+What programming language is the file.
+
+A property that can be set to indicate what programming language the
+source file is.  If it is not set the language is determined based on
+the file extension.  Typical values are CXX C etc.  Setting this
+property for a file means this file will be compiled.  Do not set this
+for headers or files that should not be compiled.
diff --git a/Help/prop_sf/LOCATION.rst b/Help/prop_sf/LOCATION.rst
new file mode 100644
index 0000000000..252d680240
--- /dev/null
+++ b/Help/prop_sf/LOCATION.rst
@@ -0,0 +1,7 @@
+LOCATION
+--------
+
+The full path to a source file.
+
+A read only property on a SOURCE FILE that contains the full path to
+the source file.
diff --git a/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst b/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst
new file mode 100644
index 0000000000..27f292961f
--- /dev/null
+++ b/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst
@@ -0,0 +1,19 @@
+MACOSX_PACKAGE_LOCATION
+-----------------------
+
+Place a source file inside a Mac OS X bundle, CFBundle, or framework.
+
+Executable targets with the MACOSX_BUNDLE property set are built as
+Mac OS X application bundles on Apple platforms.  Shared library
+targets with the FRAMEWORK property set are built as Mac OS X
+frameworks on Apple platforms.  Module library targets with the BUNDLE
+property set are built as Mac OS X CFBundle bundles on Apple
+platforms.  Source files listed in the target with this property set
+will be copied to a directory inside the bundle or framework content
+folder specified by the property value.  For bundles the content
+folder is "<name>.app/Contents".  For frameworks the content folder is
+"<name>.framework/Versions/<version>".  For cfbundles the content
+folder is "<name>.bundle/Contents" (unless the extension is changed).
+See the PUBLIC_HEADER, PRIVATE_HEADER, and RESOURCE target properties
+for specifying files meant for Headers, PrivateHeaders, or Resources
+directories.
diff --git a/Help/prop_sf/OBJECT_DEPENDS.rst b/Help/prop_sf/OBJECT_DEPENDS.rst
new file mode 100644
index 0000000000..18022de23b
--- /dev/null
+++ b/Help/prop_sf/OBJECT_DEPENDS.rst
@@ -0,0 +1,18 @@
+OBJECT_DEPENDS
+--------------
+
+Additional files on which a compiled object file depends.
+
+Specifies a semicolon-separated list of full-paths to files on which
+any object files compiled from this source file depend.  An object
+file will be recompiled if any of the named files is newer than it.
+
+This property need not be used to specify the dependency of a source
+file on a generated header file that it includes.  Although the
+property was originally introduced for this purpose, it is no longer
+necessary.  If the generated header file is created by a custom
+command in the same target as the source file, the automatic
+dependency scanning process will recognize the dependency.  If the
+generated header file is created by another target, an inter-target
+dependency should be created with the add_dependencies command (if one
+does not already exist due to linking relationships).
diff --git a/Help/prop_sf/OBJECT_OUTPUTS.rst b/Help/prop_sf/OBJECT_OUTPUTS.rst
new file mode 100644
index 0000000000..6a28553740
--- /dev/null
+++ b/Help/prop_sf/OBJECT_OUTPUTS.rst
@@ -0,0 +1,9 @@
+OBJECT_OUTPUTS
+--------------
+
+Additional outputs for a Makefile rule.
+
+Additional outputs created by compilation of this source file.  If any
+of these outputs is missing the object will be recompiled.  This is
+supported only on Makefile generators and will be ignored on other
+generators.
diff --git a/Help/prop_sf/SYMBOLIC.rst b/Help/prop_sf/SYMBOLIC.rst
new file mode 100644
index 0000000000..c7d0b2603c
--- /dev/null
+++ b/Help/prop_sf/SYMBOLIC.rst
@@ -0,0 +1,8 @@
+SYMBOLIC
+--------
+
+Is this just a name for a rule.
+
+If SYMBOLIC (boolean) is set to true the build system will be informed
+that the source file is not actually created on disk but instead used
+as a symbolic name for a build rule.
diff --git a/Help/prop_sf/WRAP_EXCLUDE.rst b/Help/prop_sf/WRAP_EXCLUDE.rst
new file mode 100644
index 0000000000..2c79f72a2e
--- /dev/null
+++ b/Help/prop_sf/WRAP_EXCLUDE.rst
@@ -0,0 +1,10 @@
+WRAP_EXCLUDE
+------------
+
+Exclude this source file from any code wrapping techniques.
+
+Some packages can wrap source files into alternate languages to
+provide additional functionality.  For example, C++ code can be
+wrapped into Java or Python etc using SWIG etc.  If WRAP_EXCLUDE is
+set to true (1 etc) that indicates that this source file should not be
+wrapped.