We aim to document the entire relevant user API. Some functions
from CMake are not worth wrapping, so we need to add them to our
documentation.

Broken/missing references, wrong directives etc.

We do not want one such documentation per module, but instead
we would allow people to use it from their module and get a
documentation generated from all the dependent modules. This
needs some changes to the machine.

This includes the following workflow:

* The cmake module path is globbed for any modules matching *.cmake
* The opening comment is parsed for the following rst directives:
  cmake_function, cmake_module, cmake_variables
* From those, a browsable documentation is generated.

To run properly, a python interpreter and sphinx are needed.

Use ALLOW_CXXFLAGS_OVERWRITE instead.

Drop support for std=c++0x.

When using NO_DEFAULT_PATH the lib and include subdirectories will
not be searched by default by find_path and pt-scotch will not be
found outside of the standard path. This commit adds them and now
locally installed versions may supersede the system ones.

Without it linking will fail when using static libraries due
to missing symbols.

The add_doxygen_target macro now takes optional parameters:
TARGET [name] : overwrite the target appendix, default is the module name
DEPENDS [list] : add a list of further dependencies for doxygen.
                               This list might include mainpage.txt
OUTPUT [name] : change the name of the output target; necessary if you don't generate html.

We follow the advice of upstream and use only empty endif() and
else() statements in new code. The removal of the optional argument
is only in generated scripts.

Add missing files, remove ancient buildsystem stuff and stuff where it is
unclear where it comes from.

Some downstream modules like pdelab and dumux already abandoned the
current bahaviour of building tests on make test. The testing infrastructure
does throw them error messages during make test though. This commi introduces
the switch DUNE_DISABLE_TEST_MAGIC which may be set by downstream modules
to disable the magic. To see how to switch a downstream module, see:

http://conan2.iwr.uni-heidelberg.de/git/pdelab/dune-pdelab/commit/dc5ef4b39f5be5690457f0bbfe008b1f45d5fd98

This has to be done as each module puts dune-common_MODULE_PATH into
CMAKE_MODULE_PATH to find the DUNE's cmake macros. This should be removed
when building the complete CMAKE_MODULE_PATH module path (in reverse order
of the dependency). Unfortunately, the conditional to check whether
the variable dune-common_MODULE_PATH is set was incorrect. This commit fixes
this.

I hope that this fixes FS 1686
https://dune-project.org/flyspray/index.php?do=details&task_id=1686

Please merge to the release

Commit 4878943f actuall did change
the default behavior, it effectifly disabled LaTex for some users.
To disable LaTeX pass -DCMAKE_DISABLE_FIND_PACKAGE_LATEX=TRUE

Otherwise it collides with the config.h.cmake for in-source builds.
The generated file is called config_collected.h.cmake.
Thanks to Robert for the heads-up.

Setting a policy must be guarded as older CMake version do not
know about the policy.

CMake >= 2.8.12 can optionally use @rpath to embed dynamic linker paths
into shared libraries on OS X. This greatly improves reliability with
libraries in non-standard locations and should definitely be turned on
by default.

script. This feature is disabled by default and can be enabled by
-DALLOW_CXXFLAGS_OVERWRITE=ON.

All the functionality in DuneEnableAllPackages.cmake is now contained in
functions instead of macros. Update the documentation to reflect that.

State the minimum required version of CMake in the documentation for
dune_enable_all_packages() and dune_target_enable_all_packages().

dune_enable_all_packages has to update the compiler options, but the
command compile_options only exists in CMake 2.8.12+. So we add a hard
requirement for that CMake version to the function.

I only ever intended this feature to work for CMake >= 2.8.12, so this
doesn't really change anything, except for giving the users a more
useful diagnostic.

Minimum required CMake version is 2.8.12 and not 2.9.12.

The duncontrol / dune.module mechanism allowes to overload the run_* commands, which
are executed in order to setup/build/etc. a module. This patch fixes a bug in the cmake
parsing of the dune.module file. Somehow cmake tried to interpret the content of the
dune.module as cmake code. We now use a different strategy to parse the file and avoid
storing the content in a temporary variable.

>> please backport to 2.4

BOOST_FOUND seems to be no longer known, use
HAVE_DUNE_BOOST instead.

Affected are older CMake versions 2.8.6 to 2.8.9 maybe even,
newer versions.

dune_library_add_sources() verifies the library name against the
contents of DUNE_ENABLE_ALL_PACKAGES_MODULE_LIBRARIES. I accidentally
broke this by converting dune_enable_all_packages (which defines the
variable) from a macro to a function, which removed the variable from
global scope.

This patch fixes the problem by explicitly exporting the variable to the
parent scope, making it available to dune_library_add_sources() again.

We have to call add_definitions() in a loop because add_definitions() is
kind of broken: even though it is supposed to be *the* function for
adding compile definitions, it does not prepend "-D" (as opposed to
target_compile_definitions(), which does). Well, whatever...

Thanks for spotting that, Dominic!

We do not really support this combination of C++11 features, and the
only time it should occur is when the user has a recent Intel Compiler
and an outdated GCC (which the Intel Compiler uses for the C++ standard
library). In that case, we emit a helpful error message at configuration
time.