[doc] Add Readme and improve doxygen docs

This now uses Readme.md as main page and removes the separate
mainpage.md and adds a little bit more documentation.

Readme.md

+<!-- vi: set ft=mkd ts=8 sw=2 et sts=2: -->
+# The Dune-Fufem module
+
+## Scope of the module
+[Dune-fufem][] is a discretization module for the [dune framework][dune]
+that is strongly relies on the [dune-functions][] module. The latter provides
+interfaces and implementations of global finite element bases and grid functions.
+[Dune-fufem][] tries to follows the design principles of [dune-functions][]
+as close as possible, adding what is needed to implement finite element discretizations.
+In particular this includes
+
+* utilities for defining [local assemblers](@ref FormsUserInterface) of variational problems,
+* utilities for handling [constraints](@ref Constraints) such as essential
+* implementations of global assemblers and linear algebra backends,
+  boundary or hanging node constraints,
+* and the [BoundaryPatch](@ref BoundaryPatch) class for handling of grid boundaries.
+
+Notice that, for historical reasons, [dune-fufem][] contains a lot
+of arcane code that does not follow the modern design principles
+mentioned above. As a rule of thumb, this applies to most code that
+was _not_ yet cleaned up and moved to the namespace @ref Dune::Fufem.
+
+### Form language for defining local assemblers
+Inspired by the [Fenics project][fenics] and its UFL language
+dune-fufem provides a language for defining linear and bilinear
+forms to be assembled. This language does not rely on code generation
+and all expressions are pure C++. It is designed to integrate well
+with the global basis and grid function interfaces of the [dune-functions][]
+module. For example, a Taylor-Hood discretization of the Stokes problem
+can be written as:
+
+```cpp
+using namespace Dune::Indices;
+using namespace Dune::Functions::BasisFactory;
+using namespace Dune::Fufem::Forms;
+
+// Create Taylor-Hood basis and give names to its velocity and pressure components
+auto basis = makeBasis(gridView, composite(power<dim>(lagrange<2>()), lagrange<1>()));
+auto velocityBasis = subspaceBasis(basis, _0);
+auto pressureBasis = subspaceBasis(basis, _1);
+
+// Define trial and test functions
+auto u = trialFunction(velocityBasis);
+auto p = trialFunction(pressureBasis);
+
+auto q = testFunction(pressureBasis);
+auto v = testFunction(velocityBasis);
+
+// Define bilinear form of the Stokes problem
+auto a = integrate( dot(grad(u), grad(v)) - div(u)*q - div(v)*p );
+```
+
+For more details refer to the @ref FormsUserInterface section.
+
+### Utilities for handling affine constraints
+Affine constraints are used to restrict discretizations to affine subspaces
+of finite element spaces. This is e.g. needed to define essential boundary
+conditions like Dirichlet constraints and hanging node constraints that
+identify a conforming subspace in case of a non-conforming grid.
+As a deliberate design decision, such constraints are not part
+of the global basis interface in [dune-functions][] but should
+be handled separately. To this end [dune-fufem][] provides
+the @ref Dune::Fufem::AffineConstraints class and utility functions
+for setting up the constraints. For example, given a global basis
+on a nonconforming grid with hanging nodes,
+a @ref BoundaryPatch describingof the Dirichlet boundary,
+and a function providing the Dirichlet values,
+the corresponding constraints can be computed using:
+
+```cpp
+
+using namespace Dune::Fufem;
+
+// Create constraints object
+auto constraints = makeAffineConstraints(basis);
+
+// Compute hanging node constraints
+computeContinuityConstraints(constraints, basis);
+
+// Compute Dirichlet constraints
+computeBoundaryConstraints(constraints, basis, dirichletValues, dirichletPatch);
+```
+
+### Handling of boundary patches
+@todo Please doc me!
+
+### Global assemblers
+@todo Please doc me!
+
+## Documentation
+
+### Class documentation
+The module contains a class documentation which can be build using [doxygen].
+After the module has been build, you can build the documentation using
+`make doc`.
+
+### Manual
+There is also a work in progress document describing the module.
+Like the class documentation this is build on `make doc`.
+
+### Examples
+Several example applications demonstrate how to use the module. These
+example applications are contained in the `examples/` directory and
+build when building the module. The definition of local assemblers
+is also described in detail in the manual (see above)
+for several examples.
+
+## Using dune-fufem and licensing
+@todo Please doc me!
+
+
+## Building dune-fufem
+
+### Dependencies
+Dune-fufem depends on the dune [core modules][core]
+
+* [dune-common](https://gitlab.dune-project.org/core/dune-common) for common infrastructure code,
+* [dune-geometry](https://gitlab.dune-project.org/core/dune-geometry) for reference elements and quadrature rules,
+* [dune-grid](https://gitlab.dune-project.org/core/dune-grid) for the definition and implementations of the grid interface,
+* [dune-localfunctions](https://gitlab.dune-project.org/core/dune-localfunctions) for local shape functions,
+* [dune-istl](https://gitlab.dune-project.org/core/dune-istl) providing linear algebra classes and iterative solvers,
+
+and the extension modules
+
+* [dune-uggrid](https://gitlab.dune-project.org/staging/dune-uggrid) as an implementation of an unstructured grid in 2d and 3d,
+* [dune-typetree](https://gitlab.dune-project.org/staging/dune-typetree) providing utilities for multi-type structures,
+* [dune-functions](https://gitlab.dune-project.org/staging/dune-functions) providing global bases and function interfaces,
+* [dune-vtk](https://gitlab.dune-project.org/extensions/dune-vtk) providing extended support for writing in the Paraview format,
+* [dune-matrix-vector](https://gitlab.dune-project.org/fufem/dune-matrix-vector) containing some generic matrix-vector operations.
+
+All of them are available using git under the above given links.
+
+
+The versioning of [dune-fufem][] follows the scheme used in the [core modules][core].
+I.e. version x.y of [dune-fufem][] will depend on version x.y of its dependency
+modules. Analogously, the _master_ branch will depend on the _master_ branch of these modules.
+There is a limited support for using the _master_ of [dune-fufem][] with the most
+recent release of its dependencies. E.g. the development version 2.11-git provided
+by the _master_ branch of dune-fufem can be used with version 2.10 of the core modules
+(and other dependencies).
+However, some features will be disabled in this setting.
+
+Unless explicitly stated otherwise for a specific version,
+dune-fufem supports/requires the same build tools (compilers, cmake)
+as the corresponding version of the core modules.
+
+### Building the module
+Dune-fufem integrates into the cmake-based dune build system.
+Hence it can be build (like any other module) using the `dunecontrol` script
+provided by the core modules. For details on how to use this build system
+and how to specify build options have a look at the documentation in the
+dune-common module.
+
+
+[dune]: https://dune-project.org
+[core]: https://dune-project.org/groups/core
+[dune-typetree]: https://gitlab.dune-project.org/staging/dune-typetree
+[dune-functions]: https://gitlab.dune-project.org/staging/dune-functions
+[dune-uggrid]: https://gitlab.dune-project.org/staging/dune-uggrid
+[dune-fufem]: https://gitlab.dune-project.org/fufem/dune-fufem
+[dune-vtk]: https://gitlab.dune-project.org/extensions/dune-vtk
+[dune-matrix-vector]: https://gitlab.dune-project.org/fufem/dune-matrix-vector
+[dune docs]: https://dune-project.org/doxygen
+[doxygen]: http://www.stack.nl/~dimitri/doxygen/
+[fenics]: https://fenicsproject.org

doc/doxygen/Doxylocal

 INPUT                  += @top_srcdir@/dune/fufem \
-                          @top_srcdir@/doc/doxygen/mainpage.md \
+                          @top_srcdir@/Readme.md \
                           @top_srcdir@/doc/doxygen/modules.md
 
-USE_MDFILE_AS_MAINPAGE = @top_srcdir@/doc/doxygen/mainpage.md
+USE_MDFILE_AS_MAINPAGE = @top_srcdir@/Readme.md
 
 EXCLUDE                += 
 EXAMPLE_PATH           +=

doc/doxygen/mainpage.md

-<!-- vi: set ft=mkd ts=8 sw=2 et sts=2: -->
-# The Dune-Fufem module
-
-## Scope of the module
-@todo Please doc me!
-
-### Handling of boundary patches
-@todo Please doc me!
-
-### Global assemblers
-@todo Please doc me!
-
-### Form language for defining local assemblers
-@todo Please doc me!
-
-For more details refer to the @ref FormsUserInterface section.
-
-## Documentation
-
-### Class documentation
-The module contains a class documentation which can be build using [doxygen].
-After the module has been build, you can build the documentation using
-`make doc`.
-
-### Manual
-There is also a work in progress document describing the module.
-Like the class documentation this is build on `make doc`.
-
-### Examples
-Several example applications demonstrate how to use the module. These
-example applications are contained in the `examples/` directory and
-build when building the module. The definition of local assemblers
-is also described in detail in the manual (see above)
-for several examples.
-
-## Using dune-fufem and licensing
-@todo Please doc me!
-
-
-## Building dune-fufem
-
-### Dependencies
-Dune-fufem depends on the dune [core modules][core] and the
-extension modules
-[dune-typetree][dune-typetree],
-[dune-function][dune-functions],
-[dune-uggrid][dune-uggrid],
-[dune-vtk][dune-vtk], and
-[dune-matrix-vector][dune-matrix-vector].
-All of them are available using git:
-
-* https://gitlab.dune-project.org/core/dune-common
-* https://gitlab.dune-project.org/core/dune-geometry
-* https://gitlab.dune-project.org/core/dune-grid
-* https://gitlab.dune-project.org/core/dune-istl
-* https://gitlab.dune-project.org/core/dune-localfunctions
-* https://gitlab.dune-project.org/staging/dune-typetree
-* https://gitlab.dune-project.org/staging/dune-functions
-* https://gitlab.dune-project.org/staging/dune-uggrid
-* https://gitlab.dune-project.org/extensions/dune-vtk
-* https://gitlab.dune-project.org/fufem/dune-matrix-vector
-
-The versioning of dune-fufem follows the scheme used in the core modules.
-I.e. version x.y of dune-fufem will depend on version x.y of its dependency
-modules. Analogously, the _master_ branch will depend on the _master_ branch of these modules.
-
-Unless explicitly stated otherwise for a specific version,
-dune-fufem supports/requires the same build tools (compilers, cmake)
-as the corresponding version of the core modules.
-
-### Building the module
-Dune-fufem integrates into the cmake-based dune build system.
-Hence it can be build (like any other module) using the `dunecontrol` script
-provided by the core modules. For details on how to use this build system
-and how to specify build options have a look at the documentation in the
-dune-common module.
-
-
-[core]: https://dune-project.org/groups/core
-[dune-typetree]: https://gitlab.dune-project.org/staging/dune-typetree
-[dune-functions]: https://gitlab.dune-project.org/staging/dune-functions
-[dune-uggrid]: https://gitlab.dune-project.org/staging/dune-uggrid
-[dune-vtk]: https://gitlab.dune-project.org/extensions/dune-vtk
-[dune-matrix-vector]: https://gitlab.dune-project.org/fufem/dune-matrix-vector
-[dune docs]: https://dune-project.org/doxygen
-[doxygen]: http://www.stack.nl/~dimitri/doxygen/

doc/doxygen/modules.md

 <!-- -*- tab-width: 4; indent-tabs-mode: nil -*- -->
-# Modules
 
 @defgroup Fufem Fufem
 @brief A discretization module based on dune-function
@@ -16,6 +15,11 @@
 @ingroup Fufem
 @brief  A framework for the convenient definition of linear and bilinear forms
 
+Please refer to the @ref FormsUserInterface for the documentation of the
+usage of the framework. @ref FormsDetail contains the documentation
+of some low level implementation details.
+
+
 @defgroup FormsUserInterface Form language (user interface)
 @ingroup Forms
 @brief User interface for defining linear and bilinear forms