Added new section "Time savings using dunecontrol" in buildsystem.tex describing update,

exec, module/only, resume/skipfirst and configure caching.
Clarified paragraph about Extra-Suggests.

[[Imported from SVN: r6584]]

doc/buildsystem/buildsystem.tex

@@ -1347,8 +1347,9 @@ their values are separated by colon. Possible parameters are
   other modules, but can offer further functionality if one or more of
   the suggested modules are found.
 \item \texttt{Extra-Suggests} {\em (optional)} takes a space separated 
-  list of optional external modules. These are only for users to mention
-  recommended suggestions.
+  list of optional external modules which do not use \dunecontrol. These
+  are only for users to mention recommended suggestions and have 
+  informational meaning only.
 \end{itemize}
 
 The command section lets you overload the default implementation
@@ -1437,6 +1438,67 @@ Now, your project is prepared to build the subdirectory
 \texttt{my\_pdelab\_application} if and only if your machine has a successfully
 installed \texttt{dune-pdelab}.
 
+\subsection{Time savings using \dunecontrol}
+
+\dunecontrol can help working with a growing stack of depending \dune modules and
+might save you time.
+
+\minisec{Narrow down \dune modules to apply actions to}
+Often you don't want to let \dunecontrol apply actions for every module but only 
+the one you are working on.
+
+With the flag \texttt{--only=dune-foo} in
+\begin{lstlisting}[language=make]
+./dune-common/bin/dunecontrol --module=dune-foo --opts=config.opts configure
+\end{lstlisting}
+only the module \texttt{dune-foo} will be configured by \dunecontrol.
+
+Using the flag \texttt{--current} below a module's root directory \dunecontrol 
+applies actions only for this module.
+
+To apply the actions to a module and all modules it depends on, set the flag 
+\texttt{--module=dune-foo}.
+
+\minisec{Updates from revision control systems}
+If modules are kept in a revision control system you need to stay up to
+date and download the newest versions for your modules. The command \texttt{update}
+as in
+\begin{lstlisting}[language=make]
+./dune-common/bin/dunecontrol update
+\end{lstlisting}
+makes \dunecontrol to update every module. Currently supported and automatically detected 
+revision control systems are the Concurrent Versions System (CVS), Apache 
+Subversion (SVN) and Git.
+
+\minisec{Execute commands for every module}
+The \dunecontrol command \texttt{exec} allows to execute commands in the root
+directory of every module. For example the 
+statement
+\begin{lstlisting}[language=make,showstringspaces=false]
+./dune-common/bin/dunecontrol exec "svn log -l10"
+\end{lstlisting}
+shows the last ten Subversion commit messages for all modules. If a module is 
+not under Subversion version control the command execution fails and \dunecontrol 
+stops.
+
+\minisec{Resume build after error}
+\dunecontrol stops whenever an error occurs. But you can resume from the module which
+failed. To enable this feature, you have to specify the path of a resume file in the 
+variable \texttt{RESUME\_FILE} of your options file and use the flag \texttt{--resume}.
+If \dunecontrol fails it saves the name of the failing module in the specified file.
+On the next run it recognizes the failed run and resumes from the failed module on.
+
+\dunecontrol skips the first module -- the one with the error in the last run -- after
+resuming if the flag \texttt{--skipfirst} is given together with \texttt{--resume}.
+
+\minisec{Use configure caching}
+\configure is run for every module thus many tests are unnecessarily run multiple times.
+You can use \autoconf's ability to cache test results. If you add 
+\texttt{--cache-file=/tmp/dune-config.cache} to the \texttt{CONFIUGURE\_FLAGS} of
+you options file the \configure  cache is created. Be aware that the file persists 
+between \dunecontrol runs. If you encounter any problems, you want to change the 
+configuration or to rerun all checks, the cache file should be removed manually.
+
 \section{Further documentation}
 
 \minisec{automake \& Makefile.am}