Update the documentation of the Rannacher Turek element.

diff --git a/include/deal.II/fe/fe_rannacher_turek.h b/include/deal.II/fe/fe_rannacher_turek.h
index c862bd5bc2ab04d994988f921929f6bdc00f926a..0522a280f9c289a035337f2e367c9f8ee2e28c27 100644 (file)
--- a/include/deal.II/fe/fe_rannacher_turek.h
+++ b/include/deal.II/fe/fe_rannacher_turek.h
@@ -29,24 +29,48 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * Implementation of Rannacher-Turek elements. Functions generated by this
- * element will be discontinuous, but their jump along faces is mean value
- * free.
+ * Implementation of the Rannacher-Turek element. This element is used
+ * to generate a stable pair of function spaces for the Stokes
+ * equation without having to increase the polynomial degree of the
+ * velocity space as much as one would do for the stable Taylor-Hood
+ * element which uses the $Q_2^d\times Q_1$ pair for velocity and
+ * pressure. That said, like many other non-conforming elements, it
+ * can also be used for the discretization of the Laplace
+ * equation. The element was first described in R. Rannacher and
+ * S. Turek: "Simple non-conforming quadrilateral Stokes element",
+ * Numerical Methods for Partial Differential Equations, vol. 8,
+ * pp. 97-112, 1992.
  *
- * Implemented only in dimension 2, lowest order, without hanging nodes and
+ * The shape functions generated by this element are in general
+ * discontinuous, and consequently the element is not $H^1$ conforming
+ * (i.e., it is a "non-conforming" element). However, the shape
+ * functions are constructed in such a way that the jump along faces
+ * has mean value zero, and consequently there is <i>some</i> sort of
+ * conformity in the element: a conforming element would have a
+ * pointwise zero jump, a completely discontinuous element like the
+ * FE_DGQ elements can have entirely arbitrary values for the jump
+ * across a face, and the current element is somewhere in the middle
+ * because its jump is nonzero but at least has mean value zero.
+ *
+ * The element is currently implemented only in dimension 2, for the
+ * lowest polynomial order, and without hanging nodes and
  * restriction/prolongation.
  *
+ *
  * <h3>Interpolation</h3>
  *
- * <h4>Node values</h4> The
- * @ref GlossNodes "node values"
- * are moments on faces.
+ * <h4>Node values</h4>
+ *
+ * The @ref GlossNodes "node values" are moments on faces.
+ *
+ * <h4>Generalized support points</h4>
  *
- * <h4>Generalized support points</h4> To calculate the node values, we are
- * using a QGauss rule on each face. By default, we are using a two point rule
- * to integrate Rannacher-Turek functions exactly. But in order to be able to
+ * To calculate the node values, we are using a QGauss rule on each
+ * face. By default, we are using a two point rule to integrate
+ * Rannacher-Turek functions exactly. But in order to be able to
  * interpolate other functions with sufficient accuracy, the number of
- * quadrature points used on a face can be adjusted in the constructor.
+ * quadrature points used on a face can be adjusted in the
+ * constructor.
  *
  * @ingroup fe
  * @author Patrick Esser