documentation on {MODULE}_CHECK_MODULE

* make the documentation appear more promimently
* link from different parts
* add some more details to the example

[[Imported from SVN: r6121]]

doc/buildsystem/buildsystem.tex

@@ -91,7 +91,7 @@ application and a \dune module.\\
 \dune modules are packages that offer a certain functionality that can
 be used by \dune applications. Therefore \dune modules offer libraries
 and/or header files. A \dune module needs to comply with certain rules
-(see \ref{guidelines}).
+(see~\ref{guidelines}).
 
 Creating a new \dune project has been covered in detail in 
 \ref{section::creating_dune_module} using \texttt{duneproject} to take
@@ -105,7 +105,7 @@ the bare minimum you have to provide in order to create a new project:
 \item \emph{Note:} an \autogen script is \emph{not} needed any more!
 \item a basic m4 file\\
   You need to provide two macros \texttt{\emph{MODULE}\_CHECKS}
-  and \texttt{\emph{MODULE}\_CHECK\_MODULE}.
+  and \texttt{\emph{MODULE}\_CHECK\_MODULE} (see~\ref{m4files}).
 \item a \configureac file\\
   Have look at the \configureac in \dunegrid for example. The most
   important part is the call to \texttt{DUNE\_CHECK\_ALL} which
@@ -257,8 +257,12 @@ A \dune module should comply with the following rules:
 \item \automake includes are located in \dunecommon. To use them, you
   will have to make a symbolic link to \texttt{dune-common/am/} (see
   \ref{am_includes}). The symlink creation should be handled by the
-  \autogen (see \ref{autogen}).
+  \autogen (see~\ref{autogen}).
 \item The \texttt{am/} directory does not get included in the tarball.
+\item Additional configure tests are located in the \texttt{m4/}
+  directory. You should at least provide the macros \texttt{\emph{MODULE}\_CHECKS}
+  and \texttt{\emph{MODULE}\_CHECK\_MODULE}, in order to setup and
+  find your module (see~\ref{m4files}).
 \item Header files that can be used by other \dune modules should be
   accessible via \verb!#include <dune/foo/bar.hh>!. In order to work
   with a freshly checkout version of your module you will usually need
@@ -1145,12 +1149,12 @@ tarball. That means it runs all necessary steps so that you can call
 \end{itemize}
 
 If needed it will also create the symbolic link to the
-\texttt{dune-common/am/} directory (see \ref{am_includes}).
+\texttt{dune-common/am/} directory (see~\ref{am_includes}).
 
 \subsection{m4 files}
 \label{m4files}
 
-\texttt{m4} files contain macros which are then composed into
+\texttt{m4/} files contain macros which are then composed into
 \configure and are run during execution of \configure.
 
 \minisec{private m4 macros}
@@ -1164,6 +1168,7 @@ in the directory \texttt{module/m4/}.
 dependencies and suggestions of this module. It is an automatically
 generated file. It is generated by \texttt{dunecontrol m4create}.
 
+\minisec{m4 module checks}
 For each dependencies of your module \texttt{\emph{MODULE}\_CHECKS}
 and \texttt{\emph{MODULE}\_CHECK\_MODULE} is called. Last
 \texttt{\emph{MODULE}\_CHECKS} is called for your module, in order to
@@ -1177,7 +1182,19 @@ written to a \texttt{m4/*.m4} file.
 Here follows an example for the module \texttt{dune-foo}:
 
 \begin{lstlisting}
+dnl -*- autoconf -*-
+# Macros needed to find dune-foo and dependent libraries. They are
+# called by the macros in ${top_src_dir}/dependencies.m4, which is
+# generated by  "dunecontrol autogen"
+
+# Additional checks needed to build dune-foo
+# This macro should be invoked by every module which depends on
+# dune-foo, as well as by dune-foo itself
 AC_DEFUN([DUNE_FOO_CHECKS])
+
+# Additional checks needed to find dune-foo
+# This macro should be invoked by every module which depends on dumux, but
+# _not_ by dune-foo itself
 AC_DEFUN([DUNE_FOO_CHECK_MODULE],[
   DUNE_CHECK_MODULES([dune-foo],        dnl module name
                      [foo/foo.hh],      dnl header file