Rewrite the introduction to the RT element.

diff --git a/include/deal.II/fe/fe_raviart_thomas.h b/include/deal.II/fe/fe_raviart_thomas.h
index ea5371ad59de864fa505f6e47ac6dfe126e0149a..ec55acc86039e9513d12f15a6344e546bc0edef5 100644 (file)
--- a/include/deal.II/fe/fe_raviart_thomas.h
+++ b/include/deal.II/fe/fe_raviart_thomas.h
@@ -35,13 +35,43 @@ DEAL_II_NAMESPACE_OPEN
 /*@{*/
 
 /**
- * Implementation of Raviart-Thomas (RT) elements, conforming with the space
- * H<sup>div</sup>. These elements generate vector fields with normal
- * components continuous between mesh cells.
+ * Implementation of Raviart-Thomas (RT) elements. The Raviart-Thomas space
+ * is designed to solve problems in which the solution only lives in the
+ * space
+ * $H^\text{div}=\{ {\mathbf u} \in L_2: \text{div}\, {\mathbf u} \in L_2\}$,
+ * rather than in the more commonly used space
+ * $H^1=\{ u \in L_2: \nabla u \in L_2\}$. In other words, the solution must
+ * be a vector field whose divergence is square integrable, but for which the
+ * gradient may not be square integrable. The typical application for this
+ * space (and these elements) is to the mixed formulation of the Laplace
+ * equation and related situations, see for example step-20. The defining
+ * characteristic of functions in $H^\text{div}$ is that they are in
+ * general discontinuous -- but that if you draw a line in 2d (or a
+ * surface in 3d), then the <i>normal</i> component of the vector
+ * field must be continuous across the line (or surface) even though
+ * the tangential component may not be. As a consequence, the
+ * Raviart-Thomas element is constructed in such a way that (i) it is
+ * @ref vector_valued "vector-valued", (ii) the shape functions are
+ * discontinuous, but (iii) the normal component of the vector field
+ * represented by each shape function is continuous across the faces
+ * of cells.
  *
- * We follow the usual definition of the degree of RT elements, which denotes
- * the polynomial degree of the largest complete polynomial subspace contained
- * in the RT space. Then, approximation order of the function itself is
+ * Other properties of the Raviart-Thomas element are that (i) it is
+ * @ref GlossPrimitive "not a primitive element"; (ii) the shape functions
+ * are defined so that certain integrals over the faces are either zero
+ * or one, rather than the common case of certain point values being
+ * either zero or one. (There is, however, the FE_RaviartThomasNodal
+ * element that uses point values.)
+ *
+ * We follow the commonly used -- though confusing -- definition of the "degree"
+ * of RT elements. Specifically, the "degree" of the element denotes
+ * the polynomial degree of the <i>largest complete polynomial subspace</i>
+ * contained in the finite element space, even if the space may contain shape
+ * functions of higher polynomial degree. The lowest order element is
+ * consequently FE_RaviartThomas(0), i.e., the Raviart-Thomas element "of
+ * degree zero", even though the functions of this space are in general
+ * polynomials of degree one in each variable. This choice of "degree"
+ * implies that the approximation order of the function itself is
  * <i>degree+1</i>, as with usual polynomial spaces. The numbering so chosen
  * implies the sequence
  * @f[
@@ -53,15 +83,10 @@ DEAL_II_NAMESPACE_OPEN
  *   \stackrel{\text{div}}{\rightarrow}
  *   DGQ_{k}
  * @f]
- * The lowest order element is consequently FE_RaviartThomas(0).
  *
  * This class is not implemented for the codimension one case (<tt>spacedim !=
  * dim</tt>).
  *
- * @todo Even if this element is implemented for two and three space
- * dimensions, the definition of the node values relies on consistently
- * oriented faces in 3D. Therefore, care should be taken on complicated
- * meshes.
  *
  * <h3>Interpolation</h3>
  *