This way, the docs get much more readable.

It is outdated.

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.

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.

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

- add question concerning configure options
- add question concerning disabling options
- mention deletion of CMakeCache.txt

Update CXXFLAG question.
More proof reading and line wrapping.

- Get rid of \\ at end of paragraphs
- Fix various misspellings
- add some convenience macros
- add myself as co-author
- break long lines which were modified anyway

This document gathers some beginners question about the CMake
build system. It is built during make doc and made available
on the website through the doc installation.

"Makefile.in", "*.o", etc. need only be listed in the toplevel .gitignore, the
rules are applied recursively.

Test programs etc. should be listed as "/program" in their directory's
.gitignore, so they are not accidentially ignored in a lower level directory.

Skip LATEX_USABLE guard for buildsystem.pdf as the check is incorporated into dune_add_latex_document.

[[Imported from SVN: r7404]]

The tarballs already contain the generated pdf files. No CMake 
will detect whether the pdf are contained in the source tree.
If that is the case they will not be generated and installed directly.

[[Imported from SVN: r7380]]

[[Imported from SVN: r7366]]

Revision 6654
.-----------------
Merge sync to keep track with the trunk.

Thanks for renaming files and targets. Always a pleasure to mimic this manually.


[[Imported from SVN: r7365]]

[[Imported from SVN: r7126]]

[[Imported from SVN: r7124]]

[[Imported from SVN: r7079]]

[[Imported from SVN: r6988]]

[[Imported from SVN: r6872]]

[[Imported from SVN: r6832]]

[[Imported from SVN: r6794]]

[[Imported from SVN: r6770]]

In particular, the search gets faster _because of_ the use of ls,
not _despite_ of it.

[[Imported from SVN: r6769]]

[[Imported from SVN: r6762]]

[[Imported from SVN: r6686]]

[[Imported from SVN: r6656]]