From 1dddbe739c31c1a26038006481ac7e337ca7f3ea Mon Sep 17 00:00:00 2001
From: Guido Kanschat <dr.guido.kanschat@gmail.com>
Date: Sun, 11 Jan 2004 12:31:57 +0000
Subject: [PATCH] changes for Doxygen

git-svn-id: https://svn.dealii.org/trunk@8305 0785d39b-7218-0410-832d-ea1e28bc413d
---
 deal.II/deal.II/include/numerics/vectors.h    | 251 +++++-----
 deal.II/lac/include/lac/block_vector.h        | 185 ++++----
 deal.II/lac/include/lac/full_matrix.h         | 167 ++++---
 deal.II/lac/include/lac/precondition.h        | 100 ++--
 deal.II/lac/include/lac/shifted_matrix.h      |  17 +-
 .../lac/include/lac/sparse_decomposition.h    | 144 +++---
 deal.II/lac/include/lac/sparse_direct.h       | 213 +++++----
 deal.II/lac/include/lac/sparse_matrix.h       | 439 ++++++++++--------
 deal.II/lac/include/lac/sparsity_pattern.h    | 422 +++++++++--------
 9 files changed, 996 insertions(+), 942 deletions(-)

diff --git a/deal.II/deal.II/include/numerics/vectors.h b/deal.II/deal.II/include/numerics/vectors.h
index b2bb7379c1..8eca6dce51 100644
--- a/deal.II/deal.II/include/numerics/vectors.h
+++ b/deal.II/deal.II/include/numerics/vectors.h
@@ -2,7 +2,7 @@
 //    $Id$
 //    Version: $Name$
 //
-//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 by the deal.II authors
+//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004 by the deal.II authors
 //
 //    This file is subject to QPL and may not be  distributed
 //    without copyright and license information. Please refer
@@ -34,36 +34,36 @@ template <int dim> class DoFHandler;
 class ConstraintMatrix;
 
 
-
+//TODO: Move documentation of functions to the functions!
+//TODO: (Re)move the basic course on Sobolev spaces
 
 /**
- * Provide a class which offers some operations on vectors. Amoung these are
- * assemblage of standard vectors, integration of the difference of a
- * finite element solution and a continuous function,
- * interpolations and projections of continuous functions to the finite
- * element space and other operations.
+ * Provide a class which offers some operations on vectors. Amoung
+ * these are assembling of standard vectors, integration of the
+ * difference of a finite element solution and a continuous function,
+ * interpolations and projections of continuous functions to the
+ * finite element space and other operations.
  *
- * There exist two versions of almost each function. One with a
- * @ref{Mapping} argument and one without. If a code uses a mapping
- * different from @ref{MappingQ1} the functions @em{with} mapping
- * argument should be used. Code that uses only @ref{MappingQ1} may
- * also use the functions @em{without} @ref{Mapping} argument. Each of
- * these latter functions create a @ref{MappingQ1} object and just
- * call the respective functions with that object as mapping
- * argument. The functions without @ref{Mapping} argument still exist
- * to ensure backward compatibility. Nevertheless it is advised to
- * change the user's codes to store a specific @ref{Mapping} object
- * and to use the functions that take this @p{Mapping} object as
- * argument. This gives the possibility to easily extend the user
- * codes to work also on mappings of higher degree, this just by
- * exchanging @ref{MappingQ1} by, for example, a @ref{MappingQ} or
- * another @ref{Mapping} object of interest.
+ * @note There exist two versions of almost each function. One with a
+ * Mapping argument and one without. If a code uses a mapping
+ * different from MappingQ1 the functions <b>with</b> mapping argument
+ * should be used. Code that uses only MappingQ1 may also use the
+ * functions without Mapping argument. Each of these latter functions
+ * create a MappingQ1 object and just call the respective functions
+ * with that object as mapping argument. The functions without Mapping
+ * argument still exist to ensure backward compatibility. Nevertheless
+ * it is advised to change the user's codes to store a specific
+ * Mapping object and to use the functions that take this Mapping
+ * object as argument. This gives the possibility to easily extend the
+ * user codes to work also on mappings of higher degree, this just by
+ * exchanging MappingQ1 by, for example, a MappingQ or another Mapping
+ * object of interest.
  *
- * @sect3{Description of operations}
+ * @section VectorTools1 Description of operations
  *
  * This collection of methods offers the following operations:
- * @begin{itemize}
- * @item Interpolation: assign each degree of freedom in the vector to be
+ * <ul>
+ * <li> Interpolation: assign each degree of freedom in the vector to be
  *   the value of the function given as argument. This is identical to
  *   saying that the resulting finite element function (which is
  *   isomorphic to the output vector) has exact function values in all
@@ -85,7 +85,7 @@ class ConstraintMatrix;
  *   given function may be, taking into account that a virtual function has
  *   to be called.
  *
- * @item Projection: compute the $L_2$-projection of the given function onto
+ * <li> Projection: compute the <i>L<sup>2</sup></i>-projection of the given function onto
  *   the finite element space. This is done through the solution of the
  *   linear system of equations $M v = f$ where $M$ is the mass matrix
  *   $m_{ij} = \int_\Omega \phi_i(x) \phi_j(x) dx$ and
@@ -94,44 +94,47 @@ class ConstraintMatrix;
  *
  *   In order to get proper results, it may necessary to treat
  *   boundary conditions right. Below are listed some cases where this
- *   may be needed.  If needed, this is done by $L_2$-projection of
+ *   may be needed.  If needed, this is done by <i>L<sup>2</sup></i>-projection of
  *   the trace of the given function onto the finite element space
  *   restricted to the boundary of the domain, then taking this
  *   information and using it to eliminate the boundary nodes from the
  *   mass matrix of the whole domain, using the
- *   @ref{MatrixTools}@p{::apply_boundary_values} function. The
- *   projection of the trace of the function to the boundary is done
- *   with the @ref{VectorTools}@p{::project_boundary_values} (see
- *   below) function, which is called with a map of boundary functions
- *   (@ref{FunctioMap}@p{::FunctionMap}) in which all boundary
- *   indicators from zero to 254 (255 is used for other purposes, see
- *   the @ref{Triangulation} class documentation) point to the
- *   function to be projected. The projection to the boundary takes
- *   place using a second quadrature formula on the boundary given to
- *   the @p{project} function. The first quadrature formula is used to
- *   compute the right hand side and for numerical quadrature of the
- *   mass matrix.
+ *   MatrixTools::apply_boundary_values() function. The projection of
+ *   the trace of the function to the boundary is done with the
+ *   VectorTools::project_boundary_values() (see below) function,
+ *   which is called with a map of boundary functions FunctioMap in
+ *   which all boundary indicators from zero to 254 (255 is used for
+ *   other purposes, see the Triangulation class documentation) point
+ *   to the function to be projected. The projection to the boundary
+ *   takes place using a second quadrature formula on the boundary
+ *   given to the project() function. The first quadrature formula is
+ *   used to compute the right hand side and for numerical quadrature
+ *   of the mass matrix.
  *
- *   The projection of the boundary values first, then eliminating them from
- *   the global system of equations is not needed usually. It may be necessary
- *   if you want to enforce special restrictions on the boundary values of the
- *   projected function, for example in time dependent problems: you may want
- *   to project the initial values but need consistency with the boundary
- *   values for later times. Since the latter are projected onto the boundary
- *   in each time step, it is necessary that we also project the boundary
- *   values of the initial values, before projecting them to the whole domain.
+ *   The projection of the boundary values first, then eliminating
+ *   them from the global system of equations is not needed
+ *   usually. It may be necessary if you want to enforce special
+ *   restrictions on the boundary values of the projected function,
+ *   for example in time dependent problems: you may want to project
+ *   the initial values but need consistency with the boundary values
+ *   for later times. Since the latter are projected onto the boundary
+ *   in each time step, it is necessary that we also project the
+ *   boundary values of the initial values, before projecting them to
+ *   the whole domain.
  *
- *   Obviously, the results of the two schemes for projection are different.
- *   Usually, when projecting to the boundary first, the $L_2$-norm of the
- *   difference between original function and projection over the whole domain
- *   will be larger (factors of five have been observed) while the $L_2$-norm
- *   of the error integrated over the boundary should of course be less. The
- *   reverse should also hold if no projection to the boundary is performed.
+ *   Obviously, the results of the two schemes for projection are
+ *   different.  Usually, when projecting to the boundary first, the
+ *   <i>L<sup>2</sup></i>-norm of the difference between original
+ *   function and projection over the whole domain will be larger
+ *   (factors of five have been observed) while the
+ *   <i>L<sup>2</sup></i>-norm of the error integrated over the
+ *   boundary should of course be less. The reverse should also hold
+ *   if no projection to the boundary is performed.
  *
- *   The selection whether the projection to the boundary first is needed is
- *   done with the @p{project_to_boundary_first} flag passed to the function.
- *   If @p{false} is given, the additional quadrature formula for faces is
- *   ignored.
+ *   The selection whether the projection to the boundary first is
+ *   needed is done with the <tt>project_to_boundary_first</tt> flag
+ *   passed to the function.  If @p{false} is given, the additional
+ *   quadrature formula for faces is ignored.
  *
  *   You should be aware of the fact that if no projection to the boundary
  *   is requested, a function with zero boundary values may not have zero
@@ -201,7 +204,7 @@ class ConstraintMatrix;
  *   The @p{project_boundary_values} function acts similar to the
  *   @p{interpolate_boundary_values} function, apart from the fact that it does
  *   not get the nodal values of boundary nodes by interpolation but rather
- *   through the $L_2$-projection of the trace of the function to the boundary.
+ *   through the <i>L<sup>2</sup></i>-projection of the trace of the function to the boundary.
  *
  *   The projection takes place on all boundary parts with boundary
  *   indicators listed in the map (@ref{FunctioMap}@p{::FunctionMap})
@@ -258,13 +261,14 @@ class ConstraintMatrix;
  *   use of the wrong quadrature formula may show a significantly wrong result
  *   and care should be taken to chose the right formula.
  *
- *   The $H_1$ seminorm is the $L_2$ norm of the gradient of the
- *   difference. The square of the full $H_1$ norm is the sum of the
- *   square of seminorm and the square of the $L_2$ norm.
+ *   The <i>H<sup>1</sup></i> seminorm is the <i>L<sup>2</sup></i>
+ *   norm of the gradient of the difference. The square of the full
+ *   <i>H<sup>1</sup></i> norm is the sum of the square of seminorm
+ *   and the square of the <i>L<sup>2</sup></i> norm.
  * 
- *   To get the @em{global} $L_1$ error, you have to sum up the
+ *   To get the global <i>L<sup>1</sup></i> error, you have to sum up the
  *   entries in @p{difference}, e.g. using
- *   @ref{Vector}@p{<double>::l1_norm} function.  For the global $L_2$
+ *   @ref{Vector}@p{<double>::l1_norm} function.  For the global <i>L<sup>2</sup></i>
  *   difference, you have to sum up the squares of the entries and
  *   take the root of the sum, e.g. using
  *   @ref{Vector}@p{<double>::l2_norm}.  These two operations
@@ -276,8 +280,8 @@ class ConstraintMatrix;
  *   To get the $L_\infty$ norm, take the maximum of the vector elements, e.g.
  *   using the @ref{Vector}@p{<double>::linfty_norm} function.
  *
- *   For the global $H_1$ norm and seminorm, the same rule applies as for the
- *   $L_2$ norm: compute the $l_2$ norm of the cell error vector.
+ *   For the global <i>H<sup>1</sup></i> norm and seminorm, the same rule applies as for the
+ *   <i>L<sup>2</sup></i> norm: compute the $l_2$ norm of the cell error vector.
  * @end{itemize}
  *
  * All functions use the finite element given to the @ref{DoFHandler} object the last
@@ -294,67 +298,68 @@ class VectorTools
 				     /**
 				      *  Denote which norm/integral is
 				      *  to be computed by the
-				      *  @p{integrate_difference}
+				      *  integrate_difference()
 				      *  function of this class. The
 				      *  following possibilities are
 				      *  implemented:
-				      *  @begin{itemize}
-				      * @item @p{mean}: the function
-				      *    or difference of functions
-				      *    is integrated on each cell.
-				      *  @item @p{L1_norm}: the
-				      *  absolute value of the
-				      *  function is integrated.
-				      * @item @p{L2_norm}: the square
-				      * of the function is integrated
-				      * and the the square root of the
-				      * result is computed on each
-				      * cell.
-				      * @item @p{Lp_norm}: the
-				      * absolute value to the pth
-				      * power is integrated and the
-				      * pth root is computed on each
-				      * cell. The exponent @p{p} is
-				      * the last parameter of the
-				      * function.
-				      *  @item @p{Linfty_norm}: the
-				      *  maximum absolute value of the
-				      *  function.
-				      * @item @p{H1_seminorm}: the
-				      *    square of the function
-				      *    gradient is integrated on
-				      *    each cell; afterwards the
-				      *    root is taken of this
-				      *    value.
-				      * @item @p{W1p_seminorm}: this
-				      * is the @p{Lp_norm} of the
-				      * gradient.
-				      * @item @p{H1_norm}: the square
-				      *    of the function plus the
-				      *    square of the function
-				      *    gradient is integrated on
-				      *    each cell; afterwards the
-				      *    root is taken of
-				      *    this. I.e. the square of
-				      *    this norm is the square of
-				      *    the @p{L2_norm} plus the
-				      *    square of the
-				      *    @p{H1_seminorm}.
-				      *  @end{itemize}
-				      * @item @p{W1p_norm}: like
-				      * @p{H1_norm}, but for
-				      * @p{Lp_norm} instead of
-				      * @p{L2_norm}
 				     */
     enum NormType {
+					   /**
+					    * The function or
+					    * difference of functions
+					    * is integrated on each
+					    * cell.
+					    */
 	  mean,
+					   /**
+					    * The absolute value of
+					    * the function is
+					    * integrated.
+					    */
 	  L1_norm,
+					   /**
+					    * The square of the
+					    * function is integrated
+					    * and the the square root
+					    * of the result is
+					    * computed on each cell.
+					    */
 	  L2_norm,
+					   /**
+					    * The maximum absolute
+					    * value of the function.
+					    */
 	  Linfty_norm,
+					   /**
+					    * #L2_norm of the gradient.
+					    */
 	  H1_seminorm,
+					   /**
+					    * The square of this norm
+					    * is the square of the
+					    * #L2_norm plus the square
+					    * of the #H1_seminorm.
+					    */
 	  H1_norm,
+					   /**
+					    * The absolute value to
+					    * the <i>p</i>th power is
+					    * integrated and the pth
+					    * root is computed on each
+					    * cell. The exponent
+					    * <i>p</i> is the last
+					    * parameter of the
+					    * function.
+					    */
 	  Lp_norm,
+					   /**
+					    * #Lp_norm of the gradient.
+					    */
 	  W1p_seminorm,
+					   /**
+					    * same as #H1_norm for
+					    * <i>L<sup>p</sup></i>.
+					    */
 	  W1p_norm
     };
     
@@ -387,8 +392,8 @@ class VectorTools
     
 				     /**
 				      * Calls the @p{interpolate}
-				      * function, see above, with
-				      * @p{mapping=MappingQ1<dim>()}.
+				      * function above with
+				      * <tt>mapping=MappingQ1@<dim>@()</tt>.
 				      */
     template <int dim, class VECTOR>
     static void interpolate (const DoFHandler<dim> &dof,
@@ -489,7 +494,7 @@ class VectorTools
 				     /**
 				      * Calls the @p{project}
 				      * function, see above, with
-				      * @p{mapping=MappingQ1<dim>()}.
+				      * @p{mapping=MappingQ1@<dim@>()}.
 				      */
     template <int dim>
     static void project (const DoFHandler<dim>    &dof,
@@ -520,7 +525,7 @@ class VectorTools
 				     /**
 				      * Calls the @p{create_right_hand_side}
 				      * function, see above, with
-				      * @p{mapping=MappingQ1<dim>()}.
+				      * @p{mapping=MappingQ1@<dim@>()}.
 				      */
     template <int dim>
     static void create_right_hand_side (const DoFHandler<dim> &dof,
@@ -564,7 +569,7 @@ class VectorTools
 				      * Calls the
 				      * @p{create_boundary_right_hand_side}
 				      * function, see above, with
-				      * @p{mapping=MappingQ1<dim>()}.
+				      * @p{mapping=MappingQ1@<dim@>()}.
 				      */
     template <int dim>
     static void create_boundary_right_hand_side (const DoFHandler<dim>   &dof,
@@ -695,7 +700,7 @@ class VectorTools
 				      * Calls the other
 				      * @p{interpolate_boundary_values}
 				      * function, see above, with
-				      * @p{mapping=MappingQ1<dim>()}.
+				      * @p{mapping=MappingQ1@<dim@>()}.
 				      */
     template <int dim>
     static void interpolate_boundary_values (const DoFHandler<dim>         &dof,
@@ -708,7 +713,7 @@ class VectorTools
 				      * Calls the other
 				      * @p{interpolate_boundary_values}
 				      * function, see above, with
-				      * @p{mapping=MappingQ1<dim>()}.
+				      * @p{mapping=MappingQ1@<dim@>()}.
 				      */
     template <int dim>
     static void interpolate_boundary_values (const DoFHandler<dim>         &dof,
@@ -760,7 +765,7 @@ class VectorTools
 				     /**
 				      * Calls the @p{project_boundary_values}
 				      * function, see above, with
-				      * @p{mapping=MappingQ1<dim>()}.
+				      * @p{mapping=MappingQ1@<dim@>()}.
 				      */
     template <int dim>
     static void project_boundary_values (const DoFHandler<dim>    &dof,
@@ -827,7 +832,7 @@ class VectorTools
 				     /**
 				      * Calls the @p{integrate_difference}
 				      * function, see above, with
-				      * @p{mapping=MappingQ1<dim>()}.
+				      * @p{mapping=MappingQ1@<dim@>()}.
 				      */
     template <int dim, class InVector, class OutVector>
     static void integrate_difference (const DoFHandler<dim> &dof,
@@ -924,7 +929,7 @@ class VectorTools
 				     /**
 				      * Calls the @p{compute_mean_value}
 				      * function, see above, with
-				      * @p{mapping=MappingQ1<dim>()}.
+				      * @p{mapping=MappingQ1@<dim@>()}.
 				      */
     template <int dim, class InVector>
     static double compute_mean_value (const DoFHandler<dim> &dof,
diff --git a/deal.II/lac/include/lac/block_vector.h b/deal.II/lac/include/lac/block_vector.h
index 26c063f82e..834d51bfcd 100644
--- a/deal.II/lac/include/lac/block_vector.h
+++ b/deal.II/lac/include/lac/block_vector.h
@@ -2,7 +2,7 @@
 //    $Id$
 //    Version: $Name$
 //
-//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 by the deal.II authors
+//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004 by the deal.II authors
 //
 //    This file is subject to QPL and may not be  distributed
 //    without copyright and license information. Please refer
@@ -103,7 +103,7 @@ namespace internal
                                       * of other classes.
                                       *
                                       * This is for the use of
-                                      * @p{const_iterator}s.
+                                      * const_iterator.
                                       */
     template <typename number>
     struct Types<number,true>
@@ -112,7 +112,7 @@ namespace internal
                                           * Type of the vector
                                           * underlying the block vector
                                           * used in
-                                          * @p{const_iterators}. There,
+                                          * const_iterator. There,
                                           * the vector must be
                                           * constant.
                                           */
@@ -121,7 +121,7 @@ namespace internal
                                          /**
                                           * Type of the block vector
                                           * used in
-                                          * @p{const_iterator}s. There,
+                                          * const_iterator. There,
                                           * the block vector must be
                                           * constant.
                                           */
@@ -142,8 +142,8 @@ namespace internal
                                       * class for block vectors. Since
                                       * we do not want to have two
                                       * classes for non-const
-                                      * @p{iterator}s and
-                                      * @p{const_iterator}s, we take a
+                                      * iterator and
+                                      * const_iterator, we take a
                                       * second template argument which
                                       * denotes whether the vector we
                                       * point into is a constant object
@@ -255,11 +255,11 @@ namespace internal
                                           * the element pointed to.
                                           *
                                           * Depending on the value of
-                                          * the @p{constness} template
+                                          * the <tt>constness</tt> template
                                           * argument of this class,
                                           * the first argument of this
                                           * constructor is either is a
-                                          * @p{const} or non-@p{const}
+                                          * const or non-const
                                           * reference.
                                           */
         Iterator (BlockVectorType    &parent,
@@ -307,20 +307,20 @@ namespace internal
                                          /**
                                           * Dereferencing operator. If
                                           * the template argument
-                                          * @p{constness} is @p{true},
+                                          * <tt>constness</tt> is <tt>true</tt>,
                                           * then no writing to the
                                           * result is possible, making
-                                          * this a @p{const_iterator}.
+                                          * this a const_iterator.
                                           */
         reference operator * () const;
 
                                          /**
                                           * Dereferencing operator. If
                                           * the template argument
-                                          * @p{constness} is @p{true},
+                                          * <tt>constness</tt> is <tt>true</tt>,
                                           * then no writing to the
                                           * result is possible, making
-                                          * this a @p{const_iterator}.
+                                          * this a const_iterator.
                                           */ 
         pointer operator -> () const;
 
@@ -333,18 +333,17 @@ namespace internal
         reference operator [] (const difference_type d) const;
       
                                          /**
-                                          * Prefix @p{++} operator:
-                                          * @p{++i}. This operator
+                                          * Prefix increment operator. This operator
                                           * advances the iterator to
                                           * the next element and
                                           * returns a reference to
-                                          * @p{*this}.
+                                          * <tt>*this</tt>.
                                           */
         Iterator & operator ++ ();
 
                                          /**
-                                          * Postfix @p{++} operator:
-                                          * @p{i++}. This operator
+                                          * Postfix increment
+                                          * operator. This operator
                                           * advances the iterator to
                                           * the next element and
                                           * returns a copy of the old
@@ -353,18 +352,17 @@ namespace internal
         Iterator operator ++ (int);
 
                                          /**
-                                          * Prefix @p{--} operator:
-                                          * @p{--i}. This operator
+                                          * Prefix decrement operator. This operator
                                           * retracts the iterator to
                                           * the previous element and
                                           * returns a reference to
-                                          * @p{*this}.
+                                          * <tt>*this</tt>.
                                           */
         Iterator & operator -- ();
 
                                          /**
-                                          * Postfix @p{--} operator:
-                                          * @p{i--}. This operator
+                                          * Postfix decrement
+                                          * operator. This operator
                                           * retracts the iterator to
                                           * the previous element and
                                           * returns a copy of the old
@@ -493,14 +491,14 @@ namespace internal
         Iterator operator - (const difference_type &d) const;
 
                                          /**
-                                          * Move the iterator @p{d}
+                                          * Move the iterator <tt>d</tt>
                                           * elements forward at once,
                                           * and return the result.
                                           */
         Iterator & operator += (const difference_type &d);
 
                                          /**
-                                          * Move the iterator @p{d}
+                                          * Move the iterator <tt>d</tt>
                                           * elements backward at once,
                                           * and return the result.
                                           */
@@ -521,10 +519,10 @@ namespace internal
                                           * vector object to which
                                           * this iterator
                                           * points. Depending on the
-                                          * value of the @p{constness}
+                                          * value of the <tt>constness</tt>
                                           * template argument of this
-                                          * class, this is a @p{const}
-                                          * or non-@p{const} pointer.
+                                          * class, this is a <tt>const</tt>
+                                          * or non-<tt>const</tt> pointer.
                                           */
         BlockVectorType *parent;
 
@@ -601,41 +599,33 @@ namespace internal
  * A vector composed of several blocks each representing a vector of
  * its own.
  *
- * The @p{BlockVector} is a collection of normal LAC-@ref{Vector}s. Each of
+ * The BlockVector is a collection of normal LAC-@ref{Vector}s. Each of
  * the vectors inside can have a different size. The special case of a
  * block vector with constant block size is supported by constructor
- * and @p{reinit} functions.
+ * and reinit() functions.
  *
- * The functionality of @p{BlockVector} includes everything a
- * @p{Vector} can do, plus the access to a single @p{Vector} inside
- * the @p{BlockVector} by @p{block(i)}. It also has a complete random
- * access iterator, just as the LAC-@ref{Vector} class or the standard
- * C++ library template @p{std::vector}. Therefore, all algorithms
- * working on iterators also work with objects of this class.
+ * The functionality of BlockVector includes everything a Vector can
+ * do, plus the access to a single Vector inside the BlockVector by
+ * block(i). It also has a complete random access iterator, just as
+ * the LAC Vector class or the standard C++ library template
+ * <tt>std::vector</tt>. Therefore, all algorithms working on
+ * iterators also work with objects of this class.
  *
  *
- * @sect3{Accessing individual blocks, and resizing vectors}
+ * @section BlockVectorAccess Accessing individual blocks, and resizing vectors
  *
  * Apart from using this object as a whole, you can use each block
- * separately as a @ref{Vector}, using the @p{block} function.  There
+ * separately as a Vector, using the block() function.  There
  * is a single caveat: if you have changed the size of one of several
- * block, you must call the function @ref{collect_sizes} of the block
+ * block, you must call the function collect_sizes() of the block
  * vector to update its internal structures.
  *
- * Warning: If you change the sizes of single blocks without calling
- * @ref{collect_sizes}, results may be unpredictable. The debug
- * version does not check consistency here for performance reasons!
- * 
- * @sect3{On template instantiations}
+ * @attention Warning: If you change the sizes of single blocks
+ * without calling collect_sizes(), results may be unpredictable. The
+ * debug version does not check consistency here for performance
+ * reasons!
  *
- * Member functions of this class are either implemented in this file
- * or in a file of the same name with suffix ``.templates.h''. For the
- * most common combinations of the template parameters, instantiations
- * of this class are provided in a file with suffix ``.cc'' in the
- * ``source'' directory. If you need an instantiation that is not
- * listed there, you have to include this file along with the
- * corresponding ``.templates.h'' file and instantiate the respective
- * class yourself.
+ * @ref Instantiations: some (<tt>@<float@> @<double@></tt>)
  *
  * @author Wolfgang Bangerth, Guido Kanschat, 1999, 2000, 2001, 2002
  */
@@ -646,10 +636,12 @@ class BlockVector
 				     /*
 				      * Declare standard types used in
 				      * all containers. These types
-				      * parallel those in the @p{C++}
-				      * standard libraries
-				      * @p{vector<...>} class. This
-				      * includes iterator types.
+				      * parallel those in the
+				      * <tt>C++</tt> standard
+				      * libraries
+				      * <tt>std::vector<...></tt>
+				      * class. This includes iterator
+				      * types.
 				      */
     typedef Number                  value_type;
     typedef value_type             *pointer;
@@ -667,12 +659,12 @@ class BlockVector
 				      *  any arguments, it generates
 				      *  an objetct with no
 				      *  blocks. Given one argument,
-				      *  it initializes @p{num_blocks}
+				      *  it initializes <tt>num_blocks</tt>
 				      *  blocks, but these blocks have
 				      *  size zero. The third variant
 				      *  finally initializes all
 				      *  blocks to the same size
-				      *  @p{block_size}.
+				      *  <tt>block_size</tt>.
 				      *
 				      *  Confer the other constructor
 				      *  further down if you intend to
@@ -698,7 +690,7 @@ class BlockVector
 // 				      * Copy constructor taking a BlockVector of
 // 				      * another data type. This will fail if
 // 				      * there is no conversion path from
-// 				      * @p{OtherNumber} to @p{Number}. Note that
+// 				      * <tt>OtherNumber</tt> to <tt>Number</tt>. Note that
 // 				      * you may lose accuracy when copying
 // 				      * to a BlockVector with data elements with
 // 				      * less accuracy.
@@ -709,16 +701,16 @@ class BlockVector
     
 				     /**
 				      * Constructor. Set the number of
-				      * blocks to @p{n.size()} and
+				      * blocks to <tt>n.size()</tt> and
 				      * initialize each block with
-				      * @p{n[i]} zero elements.
+				      * <tt>n[i]</tt> zero elements.
 				      */
     BlockVector (const std::vector<unsigned int> &n);
 
 				     /**
 				      * Constructor. Set the number of
 				      * blocks to
-				      * @p{n.size()}. Initialize the
+				      * <tt>n.size()</tt>. Initialize the
 				      * vector with the elements
 				      * pointed to by the range of
 				      * iterators given as second and
@@ -727,7 +719,7 @@ class BlockVector
 				      * constructor is in complete
 				      * analogy to the respective
 				      * constructor of the
-				      * @p{std::vector} class, but the
+				      * <tt>std::vector</tt> class, but the
 				      * first argument is needed in
 				      * order to know how to subdivide
 				      * the block vector into
@@ -745,10 +737,10 @@ class BlockVector
 
 				     /**
 				      * Reinitialize the BlockVector to
-				      * contain @p{num_blocks} blocks of
-				      * size @p{block_size} each.
+				      * contain <tt>num_blocks</tt> blocks of
+				      * size <tt>block_size</tt> each.
 				      *
-				      * If @p{fast==false}, the vector
+				      * If <tt>fast==false</tt>, the vector
 				      * is filled with zeros.
 				      */
     void reinit (const unsigned int num_blocks,
@@ -758,14 +750,14 @@ class BlockVector
 				     /**
 				      * Reinitialize the BlockVector
 				      * such that it contains
-				      * @p{N.size()} blocks. Each
+				      * <tt>N.size()</tt> blocks. Each
 				      * Block is reinitialized to
-				      * dimension @p{N[i]}.
+				      * dimension <tt>N[i]</tt>.
 				      *
 				      * If the number of blocks is the
 				      * same as before this function
 				      * was called, all vectors remain
-				      * the same and @p{reinit} is
+				      * the same and reinit() is
 				      * called for each vector. While
 				      * reinitailizing a usual vector
 				      * can consume a lot of time,
@@ -773,18 +765,18 @@ class BlockVector
 				      * has a potential to slow down a
 				      * program considerably.
 				      *
-				      * If @p{fast==false}, the vector
+				      * If <tt>fast==false</tt>, the vector
 				      * is filled with zeros.
 				      *
 				      * Note that you must call this
-				      * (or the other @p{reinit}
+				      * (or the other reinit()
 				      * functions) function, rather
-				      * than calling the @p{reinit}
+				      * than calling the reinit()
 				      * functions of an individual
 				      * block, to allow the block
 				      * vector to update its caches of
 				      * vector sizes. If you call
-				      * @p{reinit} of one of the
+				      * reinit() of one of the
 				      * blocks, then subsequent
 				      * actions of this object may
 				      * yield unpredictable results
@@ -796,24 +788,24 @@ class BlockVector
     
 				     /**
 				      * Change the dimension to that
-				      * of the vector @p{V}. The same
+				      * of the vector <tt>V</tt>. The same
 				      * applies as for the other
-				      * @p{reinit} function.
+				      * reinit() function.
 				      *
-				      * The elements of @p{V} are not
+				      * The elements of <tt>V</tt> are not
 				      * copied, i.e.  this function is
-				      * the same as calling @p{reinit
-				      * (V.size(), fast)}.
+				      * the same as calling <tt>reinit
+				      * (V.size(), fast)</tt>.
 				      *
 				      * Note that you must call this
-				      * (or the other @p{reinit}
+				      * (or the other reinit()
 				      * functions) function, rather
-				      * than calling the @p{reinit}
+				      * than calling the reinit()
 				      * functions of an individual
 				      * block, to allow the block
 				      * vector to update its caches of
 				      * vector sizes. If you call
-				      * @p{reinit} of one of the
+				      * reinit() of one of the
 				      * blocks, then subsequent
 				      * actions of this object may
 				      * yield unpredictable results
@@ -826,10 +818,10 @@ class BlockVector
     
 				     /**
 				      * Set all entries to zero. Equivalent to
-				      * @p{v = 0}, but more obvious and faster.
+				      * <tt>v = 0</tt>, but more obvious and faster.
 				      * Note that this function does not change
 				      * the size of the vector, unlike the
-				      * STL's @p{vector<>::clear} function.
+				      * STL's <tt>vector<>::clear</tt> function.
 				      */
     void clear ();
 
@@ -849,7 +841,7 @@ class BlockVector
 				     /**
 				      * Swap the contents of this
 				      * vector and the other vector
-				      * @p{v}. One could do this
+				      * <tt>v</tt>. One could do this
 				      * operation with a temporary
 				      * variable and copying over the
 				      * data elements, but this
@@ -869,11 +861,11 @@ class BlockVector
 				      * exchanged, too.
 				      *
 				      * This function is analog to the
-				      * the @p{swap} function of all C++
+				      * the swap() function of all C++
 				      * standard containers. Also,
 				      * there is a global function
-				      * @p{swap(u,v)} that simply calls
-				      * @p{u.swap(v)}, again in analogy
+				      * swap(u,v) that simply calls
+				      * <tt>u.swap(v)</tt>, again in analogy
 				      * to standard functions.
 				      */
     void swap (BlockVector<Number> &v);
@@ -1026,29 +1018,29 @@ class BlockVector
 				     //@{
 				     /**
 				      * Addition operator.
-				      * Fast equivalent to @p{U.add(1, V)}.
+				      * Fast equivalent to <tt>U.add(1, V)</tt>.
 				      */
     BlockVector<Number> &
     operator += (const BlockVector<Number> &V);
 
     				     /**
 				      * Subtraction operator.
-				      * Fast equivalent to @p{U.add(-1, V)}.
+				      * Fast equivalent to <tt>U.add(-1, V)</tt>.
 				      */
     BlockVector<Number> &
     operator -= (const BlockVector<Number> &V);
 
 				     /**
 				      * $U(0-DIM)+=s$.
-				      * Addition of @p{s} to all components. Note
-				      * that @p{s} is a scalar and not a vector.
+				      * Addition of <tt>s</tt> to all components. Note
+				      * that <tt>s</tt> is a scalar and not a vector.
 				      */
     void add (const Number s);
     
 				     /**
 				      * U+=V.
 				      * Simple vector addition, equal to the
-				      * @p{operator +=}.
+				      * <tt>operator +=</tt>.
 				      */
     void add (const BlockVector<Number>& V);
     
@@ -1101,8 +1093,8 @@ class BlockVector
 				      * This function is deprecated
 				      * and will be removed in a
 				      * future version. Use
-				      * @p{operator *=} and
-				      * @p{operator /=} instead.
+				      * <tt>operator *=</tt> and
+				      * <tt>operator /=</tt> instead.
 				      */
     void scale (const Number factor);
     
@@ -1123,7 +1115,7 @@ class BlockVector
 				     /**
 				      * Multiply each element of this
 				      * vector by the corresponding
-				      * element of @p{v}.
+				      * element of <tt>v</tt>.
 				      */
     template<typename Number2>
     void scale (const BlockVector<Number2>& v);
@@ -1220,7 +1212,7 @@ class BlockVector
 				     /**
 				      * The number of blocks. This
 				      * number is redundant to
-				      * @p{components.size()} and stored
+				      * <tt>components.size()</tt> and stored
 				      * here for convenience.
 				      */
     unsigned int num_blocks;
@@ -1852,10 +1844,11 @@ namespace internal
  */
 
 /**
- * Global function @p{swap} which overloads the default implementation
+ * Global function which overloads the default implementation
  * of the C++ standard library which uses a temporary object. The
  * function simply exchanges the data of the two vectors.
  *
+ * @relates BlockVector
  * @author Wolfgang Bangerth, 2000
  */
 template <typename Number>
diff --git a/deal.II/lac/include/lac/full_matrix.h b/deal.II/lac/include/lac/full_matrix.h
index 3276f2bb97..a5edc80fa9 100644
--- a/deal.II/lac/include/lac/full_matrix.h
+++ b/deal.II/lac/include/lac/full_matrix.h
@@ -2,7 +2,7 @@
 //    $Id$
 //    Version: $Name$
 //
-//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 by the deal.II authors
+//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004 by the deal.II authors
 //
 //    This file is subject to QPL and may not be  distributed
 //    without copyright and license information. Please refer
@@ -36,31 +36,21 @@ template<typename number> class Vector;
  *
  * Implementation of a classical rectangular scheme of numbers. The
  * data type of the entries is provided in the template argument
- * @p{number}.  The interface is quite fat and in fact has grown every
+ * <tt>number</tt>.  The interface is quite fat and in fact has grown every
  * time a new feature was needed. So, a lot of functions are provided.
  *
  * Since the instantiation of this template is quite an effort,
  * standard versions are precompiled into the library. These include
- * all combinations of @p{float} and @p{double} for matrices and
+ * all combinations of <tt>float</tt> and <tt>double</tt> for matrices and
  * vectors. If you need more data types, the implementation of
- * non-inline functions is in @p{fullmatrix.templates.h}. Driver files
+ * non-inline functions is in <tt>fullmatrix.templates.h</tt>. Driver files
  * are in the source tree.
  *
  * Internal calculations are usually done with the accuracy of the
  * vector argument to functions. If there is no argument with a number
  * type, the matrix number type is used.
  *
- *
- * @sect2{On template instantiations}
- *
- * Member functions of this class are either implemented in this file
- * or in a file of the same name with suffix ``.templates.h''. For the
- * most common combinations of the template parameters, instantiations
- * of this class are provided in a file with suffix ``.cc'' in the
- * ``source'' directory. If you need an instantiation that is not
- * listed there, you have to include this file along with the
- * corresponding ``.templates.h'' file and instantiate the respective
- * class yourself.
+ * @ref Instantiations: some (<tt>@<float@> @<double@></tt>)
  *
  * @author Guido Kanschat, Franz-Theo Suttmeier, Wolfgang Bangerth, 1993-2001
  */
@@ -170,7 +160,7 @@ class FullMatrix : public Table<2,number>
                                           */
 	bool operator == (const const_iterator&) const;
                                          /**
-                                          * Inverse of @p{==}.
+                                          * Inverse of <tt>==</tt>.
                                           */
 	bool operator != (const const_iterator&) const;
 
@@ -196,13 +186,13 @@ class FullMatrix : public Table<2,number>
 				     /**
 				      * Constructor. Initialize the
 				      * matrix as a square matrix with
-				      * dimension @p{n}.
+				      * dimension <tt>n</tt>.
 				      *
 				      * In order to avoid the implicit
 				      * conversion of integers and
 				      * other types to a matrix, this
 				      * constructor is declared
-				      * @p{explicit}.
+				      * <tt>explicit</tt>.
 				      *
 				      * By default, no memory is
 				      * allocated.
@@ -226,10 +216,10 @@ class FullMatrix : public Table<2,number>
 				      * by value rather than by
 				      * reference. Unfortunately, we
 				      * can't mark this copy
-				      * constructor @p{explicit},
+				      * constructor <tt>explicit</tt>,
 				      * since that prevents the use of
 				      * this class in containers, such
-				      * as @p{std::vector}. The
+				      * as <tt>std::vector</tt>. The
 				      * responsibility to check
 				      * performance of programs must
 				      * therefore remain with the
@@ -263,7 +253,7 @@ class FullMatrix : public Table<2,number>
 				      * matrix classes. This
 				      * assignment operator uses
 				      * iterators of the class
-				      * @p{MATRIX}. Therefore, sparse
+				      * MATRIX. Therefore, sparse
 				      * matrices are possible sources.
 				      */
     template <class MATRIX>
@@ -284,19 +274,19 @@ class FullMatrix : public Table<2,number>
 				      * Fill rectangular block.
 				      *
 				      * A rectangular block of the
-				      * matrix @p{src} is copied into
-				      * @p{this}. The upper left
+				      * matrix <tt>src</tt> is copied into
+				      * <tt>this</tt>. The upper left
 				      * corner of the block being
 				      * copied is
-				      * @p{(src_offset_i,src_offset_j)}.
+				      * <tt>(src_offset_i,src_offset_j)</tt>.
 				      * The upper left corner of the
 				      * copied block is
-				      * @p{(dst_offset_i,dst_offset_j)}.
+				      * <tt>(dst_offset_i,dst_offset_j)</tt>.
 				      * The size of the rectangular
 				      * block being copied is the
 				      * maximum size possible,
 				      * determined either by the size
-				      * of @p{this} or @p{src}.
+				      * of <tt>this</tt> or <tt>src</tt>.
 				      */
     template<typename number2>
     void fill (const FullMatrix<number2> &src,
@@ -317,17 +307,17 @@ class FullMatrix : public Table<2,number>
 				      * Fill with permutation of
 				      * another matrix.
 				      *
-				      * The matrix @p{src} is copied
+				      * The matrix <tt>src</tt> is copied
 				      * into the target. The two
-				      * permutation @p{p_r} and
-				      * @p{p_c} operate in a way, such
-				      * that @p{result(i,j) =
-				      * src(p_r[i], p_c[j])}.
+				      * permutation <tt>p_r</tt> and
+				      * <tt>p_c</tt> operate in a way, such
+				      * that <tt>result(i,j) =
+				      * src(p_r[i], p_c[j])</tt>.
 				      *
 				      * The vectors may also be a
 				      * selection from a larger set of
 				      * integers, if the matrix
-				      * @p{src} is bigger. It is also
+				      * <tt>src</tt> is bigger. It is also
 				      * possible to duplicate rows or
 				      * columns by this method.
 				      */
@@ -375,12 +365,12 @@ class FullMatrix : public Table<2,number>
     
 				     /**
 				      * STL-like iterator with the
-				      * first entry of row @p{r}.
+				      * first entry of row <tt>r</tt>.
 				      */
     const_iterator begin (const unsigned int r) const;
 
 				     /**
-				      * Final iterator of row @p{r}.
+				      * Final iterator of row <tt>r</tt>.
 				      */
     const_iterator end (const unsigned int r) const;
     
@@ -398,7 +388,7 @@ class FullMatrix : public Table<2,number>
     
 				     /**
 				      * Weighted addition. The matrix
-				      * @p{s*B} is added to @p{this}.
+				      * <tt>s*B</tt> is added to <tt>this</tt>.
 				      *
 				      * $A += sB$
 				      */
@@ -408,7 +398,7 @@ class FullMatrix : public Table<2,number>
 
 				     /**
 				      * Weighted addition of the
-				      * transpose of @p{B} to @p{this}.
+				      * transpose of <tt>B</tt> to <tt>this</tt>.
 				      *
 				      * $A += s B^T$
 				      */
@@ -420,9 +410,9 @@ class FullMatrix : public Table<2,number>
 				      * Matrix-matrix-multiplication.
 				      *
 				      * The optional parameter
-				      * @p{adding} determines, whether the
-				      * result is stored in @p{C} or added
-				      * to @p{C}.
+				      * <tt>adding</tt> determines, whether the
+				      * result is stored in <tt>C</tt> or added
+				      * to <tt>C</tt>.
 				      *
 				      * if (adding)
 				      *  $C += A*B$
@@ -430,8 +420,8 @@ class FullMatrix : public Table<2,number>
 				      * if (!adding)
 				      *  $C = A*B$
 				      *
-				      * Assumes that @p{A} and @p{B} have
-				      * compatible sizes and that @p{C}
+				      * Assumes that <tt>A</tt> and <tt>B</tt> have
+				      * compatible sizes and that <tt>C</tt>
 				      * already has the right size.
 				      */
     template<typename number2>
@@ -441,12 +431,12 @@ class FullMatrix : public Table<2,number>
     
 				     /**
 				      * Matrix-matrix-multiplication using
-				      * transpose of @p{this}.
+				      * transpose of <tt>this</tt>.
 				      *
 				      * The optional parameter
-				      * @p{adding} determines, whether the
-				      * result is stored in @p{C} or added
-				      * to @p{C}.
+				      * <tt>adding</tt> determines, whether the
+				      * result is stored in <tt>C</tt> or added
+				      * to <tt>C</tt>.
 				      *
 				      * if (adding)
 				      *  $C += A^T*B$
@@ -454,8 +444,8 @@ class FullMatrix : public Table<2,number>
 				      * if (!adding)
 				      *  $C = A^T*B$
 				      *
-				      * Assumes that @p{A} and @p{B} have
-				      * compatible sizes and that @p{C}
+				      * Assumes that <tt>A</tt> and <tt>B</tt> have
+				      * compatible sizes and that <tt>C</tt>
 				      * already has the right size.
 				      */
     template<typename number2>
@@ -467,9 +457,9 @@ class FullMatrix : public Table<2,number>
 				      * Matrix-vector-multiplication.
 				      *
 				      * The optional parameter
-				      * @p{adding} determines, whether the
-				      * result is stored in @p{w} or added
-				      * to @p{w}.
+				      * <tt>adding</tt> determines, whether the
+				      * result is stored in <tt>w</tt> or added
+				      * to <tt>w</tt>.
 				      *
 				      * if (adding)
 				      *  $w += A*v$
@@ -485,7 +475,7 @@ class FullMatrix : public Table<2,number>
 				     /**
 				      * Transpose
 				      * matrix-vector-multiplication.
-				      * See @p{vmult} above.
+				      * See vmult() above.
 				      */
     template<typename number2>
     void Tvmult (Vector<number2>       &w,
@@ -494,28 +484,29 @@ class FullMatrix : public Table<2,number>
 
 				     /**
 				      * Return the square of the norm
-				      * of the vector @p{v} with respect
-				      * to the norm induced by this
-				      * matrix,
-				      * i.e. $\left(v,Mv\right)$. This
-				      * is useful, e.g. in the finite
+				      * of the vector <tt>v</tt> with
+				      * respect to the norm induced by
+				      * this matrix,
+				      * i.e. <i>(v,Mv)</i>. This is
+				      * useful, e.g. in the finite
 				      * element context, where the
-				      * $L_2$ norm of a function
-				      * equals the matrix norm with
-				      * respect to the mass matrix of
-				      * the vector representing the
-				      * nodal values of the finite
-				      * element function.
+				      * <i>L<sup>2</sup></i> norm of a
+				      * function equals the matrix
+				      * norm with respect to the mass
+				      * matrix of the vector
+				      * representing the nodal values
+				      * of the finite element
+				      * function.
 				      *
 				      * Obviously, the matrix needs to
-				      * be square for this operation.
+				      * be quadratic for this operation.
 				      */
     template<typename number2>
     number2 matrix_norm_square (const Vector<number2> &v) const;
 
 				     /**
 				      * Build the matrix scalar product
-				      * @p{u^T M v}. This function is mostly
+				      * <tt>u^T M v</tt>. This function is mostly
 				      * useful when building the cellwise
 				      * scalar product of two functions in
 				      * the finite element context.
@@ -531,7 +522,7 @@ class FullMatrix : public Table<2,number>
 				      * transpose, $A = \frac 12(A+A^T)$.
 				      *
 				      * Obviously the matrix must be
-				      * square for this operation.
+				      * quadratic for this operation.
 				      */
     void symmetrize ();
     
@@ -600,8 +591,8 @@ class FullMatrix : public Table<2,number>
 				      * the indefinite case.
 				      *
 				      * The numerical effort to invert
-				      * an @p{n x n} matrix is of the
-				      * order @p{n**3}.
+				      * an <tt>n x n</tt> matrix is of the
+				      * order <tt>n**3</tt>.
 				      */
     void gauss_jordan ();
 
@@ -613,15 +604,15 @@ class FullMatrix : public Table<2,number>
                                       * higher dimensions the
                                       * numerical work explodes.
                                       * Obviously, the matrix needs to
-                                      * be square for this function.
+                                      * be quadratic for this function.
                                       */
     double determinant () const;
 
 				     /**
 				      * Assign the inverse of the
 				      * given matrix to
-				      * @p{*this}. This function is
-				      * hardcoded for square matrices
+				      * <tt>*this</tt>. This function is
+				      * hardcoded for quadratic matrices
 				      * of dimension one to four,
 				      * since the amount of code
 				      * needed grows quickly.  For
@@ -636,11 +627,11 @@ class FullMatrix : public Table<2,number>
 				      * Apply the Jacobi
 				      * preconditioner, which
 				      * multiplies every element of
-				      * the @p{src} vector by the
+				      * the <tt>src</tt> vector by the
 				      * inverse of the respective
 				      * diagonal element and
 				      * multiplies the result with the
-				      * damping factor @p{omega}.
+				      * damping factor <tt>omega</tt>.
 				      */
     template <typename somenumber>
     void precondition_Jacobi (Vector<somenumber>       &dst,
@@ -711,9 +702,9 @@ class FullMatrix : public Table<2,number>
     void diagadd (const number s);
 
 				     /**
-				      * $w=b-A*v$.
+				      * <i>w=b-A*v</i>.
 				      * Residual calculation , returns
-				      * the $l_2$-norm $|w|$.
+				      * the <i>l<sub>2</sub></i>-norm |<i>w</i>|.
 				      */
     template<typename number2, typename number3>
     double residual (Vector<number2>       &w,
@@ -728,10 +719,10 @@ class FullMatrix : public Table<2,number>
 				      *
 				      * If the matrix has more columns
 				      * than rows, this function only
-				      * operates on the left square
+				      * operates on the left quadratic
 				      * submatrix. If there are more
-				      * rows, the upper square part of
-				      * the matrix is considered.
+				      * rows, the upper quadratic part
+				      * of the matrix is considered.
 				      *
 				      * Note that this function does
 				      * not fit into this class at
@@ -747,14 +738,14 @@ class FullMatrix : public Table<2,number>
 				      * more. Conversely, if these
 				      * functions have a meaning on
 				      * this object, then the
-				      * @p{forward} function has no
+				      * forward() function has no
 				      * meaning. This bifacial
 				      * property of this class is
 				      * probably a design mistake and
 				      * may once go away by separating
-				      * the @p{forward} and
-				      * @p{backward} functions into a
-				      * class of their own.
+				      * the forward() and backward()
+				      * functions into a class of
+				      * their own.
 				      */
     template<typename number2>
     void forward (Vector<number2>       &dst,
@@ -764,7 +755,7 @@ class FullMatrix : public Table<2,number>
 				      * Backward elimination of upper
 				      * triangle.
 				      *
-				      * @ref forward
+				      * See forward()
 				      */
     template<typename number2>
     void backward (Vector<number2>       &dst,
@@ -818,12 +809,12 @@ class FullMatrix : public Table<2,number>
 				      *
 				      * The parameters allow for a
 				      * flexible setting of the output
-				      * format: @p{precision} and
-				      * @p{scientific} are used to
+				      * format: <tt>precision</tt> and
+				      * <tt>scientific</tt> are used to
 				      * determine the number format,
-				      * where @p{scientific} = @p{false}
+				      * where <tt>scientific</tt> = <tt>false</tt>
 				      * means fixed point notation.  A
-				      * zero entry for @p{width} makes
+				      * zero entry for <tt>width</tt> makes
 				      * the function compute a width,
 				      * but it may be changed to a
 				      * positive value, if output is
@@ -839,8 +830,8 @@ class FullMatrix : public Table<2,number>
 				      * readable output, even
 				      * integers.
 				      *
-				      * This function
-				      * may produce @em{large} amounts of
+				      * @attention This function
+				      * may produce <b>large</b> amounts of
 				      * output if applied to a large matrix!
 				      */
     void print_formatted (std::ostream       &out,
diff --git a/deal.II/lac/include/lac/precondition.h b/deal.II/lac/include/lac/precondition.h
index 23b5170065..c464064411 100644
--- a/deal.II/lac/include/lac/precondition.h
+++ b/deal.II/lac/include/lac/precondition.h
@@ -2,7 +2,7 @@
 //    $Id$
 //    Version: $Name$
 //
-//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 by the deal.II authors
+//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004 by the deal.II authors
 //
 //    This file is subject to QPL and may not be  distributed
 //    without copyright and license information. Please refer
@@ -49,7 +49,7 @@ class PreconditionIdentity : public Subscriptor
 				      * preconditioner. Since this is
 				      * the identity, this function is
 				      * the same as
-				      * @ref{vmult}.
+				      * vmult().
 				      */
     template<class VECTOR>
     void Tvmult (VECTOR&, const VECTOR&) const;
@@ -64,7 +64,7 @@ class PreconditionIdentity : public Subscriptor
 				      * preconditioner, adding. Since this is
 				      * the identity, this function is
 				      * the same as
-				      * @ref{vmult}.
+				      * vmult_add().
 				      */
     template<class VECTOR>
     void Tvmult_add (VECTOR&, const VECTOR&) const;
@@ -82,35 +82,36 @@ class PreconditionIdentity : public Subscriptor
  * classes.
  *
  * It seems that all builtin preconditioners have a relaxation
- * parameter, so please use @p{PreconditionRelaxation} for these.
+ * parameter, so please use PreconditionRelaxation for these.
+ *
+ * @section PrecUMU Usage
  *
- * @sect3{Use}
  * You will usually not want to create a named object of this type,
  * although possible. The most common use is like this:
- * @begin{verbatim}
+ * @code
  *    SolverGMRES<SparseMatrix<double>,
  *                Vector<double> >      gmres(control,memory,500);
  *
  *    gmres.solve (matrix, solution, right_hand_side,
  *		   PreconditionUseMatrix<SparseMatrix<double>,Vector<double> >
  *		   (matrix,&SparseMatrix<double>::template precondition_Jacobi));
- * @end{verbatim}
+ * @endcode
  * This creates an unnamed object to be passed as the fourth parameter to
- * the solver function of the @p{SolverGMRES} class. It assumes that the
- * @p{SparseMatrix} class has a function @p{precondition_Jacobi} taking two
- * vectors (source and destination) as parameters. (Actually, there is no
+ * the solver function of the SolverGMRES class. It assumes that the
+ * SparseMatrix class has a function <tt>precondition_Jacobi</tt> taking two
+ * vectors (source and destination) as parameters (Actually, there is no
  * function like that, the existing function takes a third parameter,
  * denoting the relaxation parameter; this example is therefore only meant to
- * illustrate the general idea.)
+ * illustrate the general idea).
  *
  * Note that due to the default template parameters, the above example
  * could be written shorter as follows:
- * @begin{verbatim}
+ * @code
  *    ...
  *    gmres.solve (matrix, solution, right_hand_side,
  *		   PreconditionUseMatrix<>
  *		     (matrix,&SparseMatrix<double>::template precondition_Jacobi));
- * @end{verbatim}
+ * @endcode
  *
  * @author Guido Kanschat, Wolfgang Bangerth, 1999
  */
@@ -216,12 +217,13 @@ class PreconditionRelaxation : public Subscriptor
 
 
 /**
- * Jacobi preconditioner using matrix built-in function.  The MATRIX
- * class used is required to have a function
- * @p{precondition_Jacobi(VECTOR&, const VECTOR&, double}
+ * Jacobi preconditioner using matrix built-in function.  The
+ * <tt>MATRIX</tt> class used is required to have a function
+ * <tt>precondition_Jacobi(VECTOR&, const VECTOR&, double</tt>)
+ *
+ * @section PrecJU Usage
  *
- * @sect2{Usage example}
- * @begin{itemize}
+ * @code
  *     // Declare related objects
  *
  * SparseMatrix<double> A;
@@ -237,7 +239,7 @@ class PreconditionRelaxation : public Subscriptor
  * precondition.initialize (A, .6);
  *
  * solver.solve (A, x, b, precondition);
- * @end{itemize}
+ * @endcode
  *
  * @author Guido Kanschat, 2000
  */
@@ -255,7 +257,7 @@ class PreconditionJacobi : public PreconditionRelaxation<MATRIX>
 				      * preconditioner. Since this is
 				      * a symmetric preconditioner,
 				      * this function is the same as
-				      * @ref{vmult}.
+				      * vmult().
 				      */
     template<class VECTOR>
     void Tvmult (VECTOR&, const VECTOR&) const;
@@ -265,12 +267,12 @@ class PreconditionJacobi : public PreconditionRelaxation<MATRIX>
 /**
  * SOR preconditioner using matrix built-in function.  The MATRIX
  * class used is required to have functions
- * @p{precondition_SOR(VECTOR&, const VECTOR&, double)} and
- * @p{precondition_TSOR(VECTOR&, const VECTOR&, double)}.
+ * <tt>precondition_SOR(VECTOR&, const VECTOR&, double)</tt> and
+ * <tt>precondition_TSOR(VECTOR&, const VECTOR&, double)</tt>.
  *
  *
- * @sect2{Usage example}
- * @begin{itemize}
+ * @section PrexSORU Usage
+ * @code
  *     // Declare related objects
  *
  * SparseMatrix<double> A;
@@ -286,7 +288,7 @@ class PreconditionJacobi : public PreconditionRelaxation<MATRIX>
  * precondition.initialize (A, .6);
  *
  * solver.solve (A, x, b, precondition);
- * @end{itemize}
+ * @endcode
  *
  * @author Guido Kanschat, 2000
  */
@@ -311,13 +313,13 @@ class PreconditionSOR : public PreconditionRelaxation<MATRIX>
 
 
 /**
- * SSOR preconditioner using matrix built-in function.  The MATRIX
- * class used is required to have a function
- * @p{precondition_SSOR(VECTOR&, const VECTOR&, double}
+ * SSOR preconditioner using matrix built-in function.  The
+ * <tt>MATRIX</tt> class used is required to have a function
+ * <tt>precondition_SSOR(VECTOR&, const VECTOR&, double)</tt>
  *
  *
- * @sect2{Usage example}
- * @begin{itemize}
+ * @section PrexSSORU Usage
+ * @code
  *     // Declare related objects
  *
  * SparseMatrix<double> A;
@@ -333,7 +335,7 @@ class PreconditionSOR : public PreconditionRelaxation<MATRIX>
  * precondition.initialize (A, .6);
  *
  * solver.solve (A, x, b, precondition);
- * @end{itemize}
+ * @endcode
  *
  * @author Guido Kanschat, 2000
  */
@@ -352,7 +354,7 @@ class PreconditionSSOR : public PreconditionRelaxation<MATRIX>
 				      * preconditioner. Since this is
 				      * a symmetric preconditioner,
 				      * this function is the same as
-				      * @ref{vmult}.
+				      * vmult().
 				      */
     template<class VECTOR>
     void Tvmult (VECTOR&, const VECTOR&) const;
@@ -360,14 +362,14 @@ class PreconditionSSOR : public PreconditionRelaxation<MATRIX>
 
 
 /**
- * Permuted SOR preconditioner using matrix built-in function.  The MATRIX
- * class used is required to have functions
- * @p{PSOR(VECTOR&, const VECTOR&, double)} and
- * @p{TPSOR(VECTOR&, const VECTOR&, double)}.
+ * Permuted SOR preconditioner using matrix built-in function.  The
+ * <tt>MATRIX</tt> class used is required to have functions
+ * <tt>PSOR(VECTOR&, const VECTOR&, double)</tt> and
+ * <tt>TPSOR(VECTOR&, const VECTOR&, double)</tt>.
  *
  *
- * @sect2{Usage example}
- * @begin{itemize}
+ * @section PrecPSORU Usage
+ * @code
  *     // Declare related objects
  *
  * SparseMatrix<double> A;
@@ -388,7 +390,7 @@ class PreconditionSSOR : public PreconditionRelaxation<MATRIX>
  * precondition.initialize (A, permutation, inverse_permutation, .6);
  *
  * solver.solve (A, x, b, precondition);
- * @end{itemize}
+ * @endcode
  *
  * @author Guido Kanschat, 2003
  */
@@ -453,21 +455,21 @@ class PreconditionPSOR : public PreconditionRelaxation<MATRIX>
  * inverse of the matrix. Naturally, this solver needs another
  * preconditionig method.
  *
- * Usually, the use of @p{ReductionControl} is preferred over the use of
- * the basic @p{SolverControl} in defining this solver.
+ * Usually, the use of ReductionControl is preferred over the use of
+ * the basic SolverControl in defining this solver.
  *
- * @sect2{Usage example}
+ * @section PrecItU Usage
  *
- * Krylov space methods like @ref{SolverCG} or @ref{SolverBicgstab}
+ * Krylov space methods like SolverCG or SolverBicgstab
  * become inefficient if soution down to machine accuracy is
  * needed. This is due to the fact, that round-off errors spoil the
  * orthogonality of the vector sequences. Therefore, a nested
  * iteration of two methods is proposed: The outer method is
- * @ref{SolverRichardson}, since it is robust with respect to round-of
+ * SolverRichardson, since it is robust with respect to round-of
  * errors. The inner loop is an appropriate Krylov space method, since
  * it is fast.
  *
- * @begin{itemize}
+ * @code
  *     // Declare related objects
  *
  * SparseMatrix<double> A;
@@ -487,10 +489,10 @@ class PreconditionPSOR : public PreconditionRelaxation<MATRIX>
  * SolverRichardson<Vector<double> > outer_iteration;
  *
  * outer_iteration.solve (A, x, b, precondition);
- * @end{itemize}
+ * @endcode
  *
  * Each time we call the inner loop, reduction of the residual by a
- * factor @p{1.e-2} is attempted. Since the right hand side vector of
+ * factor <tt>1.e-2</tt> is attempted. Since the right hand side vector of
  * the inner iteration is the residual of the outer loop, the relative
  * errors are far from machine accuracy, even if the errors of the
  * outer loop are in the range of machine accuracy.
@@ -548,8 +550,8 @@ class PreconditionLACSolver : public Subscriptor
  * with the matrix-vector product $PA$. It needs an auxiliary vector for that.
  *
  * By this time, this is considered a temporary object to be plugged
- * into eigenvalue solvers. Therefore, no @p{SmartPointer} is used for
- * @p{A} and @p{P}.
+ * into eigenvalue solvers. Therefore, no SmartPointer is used for
+ * <tt>A</tt> and <tt>P</tt>.
  *
  * @author Guido Kanschat, 2000
  */
diff --git a/deal.II/lac/include/lac/shifted_matrix.h b/deal.II/lac/include/lac/shifted_matrix.h
index 16535b8422..8ef9c3c097 100644
--- a/deal.II/lac/include/lac/shifted_matrix.h
+++ b/deal.II/lac/include/lac/shifted_matrix.h
@@ -2,7 +2,7 @@
 //    $Id$
 //    Version: $Name$
 //
-//    Copyright (C) 2001, 2002, 2003 by the deal.II authors
+//    Copyright (C) 2001, 2002, 2003, 2004 by the deal.II authors
 //
 //    This file is subject to QPL and may not be  distributed
 //    without copyright and license information. Please refer
@@ -24,8 +24,9 @@
 /**
  * Matrix with shifted diagonal values.
  *
- * Given a matrix p{A}, this class implements a matrix-vector product with
- * @p{A+\sigma I}, where sigma is a provided shift parameter.
+ * Given a matrix <tt>A</tt>, this class implements a matrix-vector
+ * product with <i>A+s I</i>, where <i>s</i> is a provided shift
+ * parameter.
  *
  * @author Guido Kanschat, 2000, 2001
  */
@@ -34,8 +35,8 @@ class ShiftedMatrix
 {
   public:
 				     /**
-				      * Constructor.
-				      * Provide the base matrix and a shift parameter.
+				      * Constructor.  Provide the base
+				      * matrix and a shift parameter.
 				      */
     ShiftedMatrix (const MATRIX& A, const double sigma);
 
@@ -82,9 +83,9 @@ class ShiftedMatrix
 /**
  * Matrix with shifted diagonal values with respect to a certain scalar product.
  *
- * Given a matrix @p{A}, this class implements a matrix-vector product
- * with @p{A+\sigma M}, where sigma is a provided shift parameter and
- * @p{M} is the matrix representing the identity
+ * Given a matrix <tt>A</tt>, this class implements a matrix-vector product
+ * with <i>A+s M</i>, where <i>s</i> is a provided shift parameter and
+ * <tt>M</tt> is the matrix representing the identity
  *
  * @author Guido Kanschat, 2001
  */
diff --git a/deal.II/lac/include/lac/sparse_decomposition.h b/deal.II/lac/include/lac/sparse_decomposition.h
index 3ac8682c21..70b9074bcb 100644
--- a/deal.II/lac/include/lac/sparse_decomposition.h
+++ b/deal.II/lac/include/lac/sparse_decomposition.h
@@ -2,7 +2,7 @@
 //    $Id$
 //    Version: $Name$
 //
-//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003
+//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004
 //    by the deal.II authors and Stephen "Cheffo" Kolaroff
 //
 //    This file is subject to QPL and may not be  distributed
@@ -28,63 +28,63 @@
  * into another sparse matrix.
  *
  * The decomposition is stored as a sparse matrix which is why this
- * class is derived from the @p{SparseMatrix}. Since it is not a matrix in
- * the usual sense, the derivation is @p{protected} rather than @p{public}.
+ * class is derived from the SparseMatrix. Since it is not a matrix in
+ * the usual sense, the derivation is <tt>protected</tt> rather than <tt>public</tt>.
 
  * @sect3{Fill-in}
  *
  * The sparse LU decompositions are frequently used with additional
  * fill-in, i.e. the sparsity structure of the decomposition is denser
- * than that of the matrix to be decomposed. The @p{initialize}
+ * than that of the matrix to be decomposed. The initialize()
  * function of this class allows this fill-in as long as all entries
  * present in the original matrix are present in the decomposition
  * also, i.e. the sparsity pattern of the decomposition is a superset
  * of the sparsity pattern in the original matrix.
  *
  * Such fill-in can be accomplished by various ways, one of which is a
- * copy-constructor of the @p{SparsityPattern} class which allows the addition
+ * copy-constructor of the SparsityPattern class which allows the addition
  * of side-diagonals to a given sparsity structure.
  *
  * @sect3{Unified use of preconditioners}
  *
  * An object of this class can be used in the same form as all
- * @ref{PreconditionBlock} preconditioners:
- * @begin{verbatim}
+ * PreconditionBlock preconditioners:
+ * @code
  * SparseLUImplementation<double> lu;
  * lu.initialize(matrix, SparseLUImplementation<double>::AdditionalData(...));
  *
  * somesolver.solve (A, x, f, lu);
- * @end{verbatim}
+ * @endcode
  *
- * Through the @p{AdditionalData} object it is possible to specify
+ * Through the AdditionalData object it is possible to specify
  * additional parameters of the LU decomposition.
  *
  * 1/ The matrix diagonals can be strengthened by adding
- * @p{strengthen_diagonal} times the sum of the absolute row entries
+ * <tt>strengthen_diagonal</tt> times the sum of the absolute row entries
  * of each row to the respective diagonal entries. By default no
  * strengthening is performed.
  *
- * 2/ By default, each @p{initialize} function call creates its own
- * sparsity. For that, it copies the sparsity of @p{matrix} and adds a
+ * 2/ By default, each initialize() function call creates its own
+ * sparsity. For that, it copies the sparsity of <tt>matrix</tt> and adds a
  * specific number of extra off diagonal entries specified by
- * @p{extra_off_diagonals}.
+ * <tt>extra_off_diagonals</tt>.
  *
- * 3/ By setting @p{use_previous_sparsity=true} the sparsity is not
- * recreated but the sparsity of the previous @p{initialize} call is
+ * 3/ By setting <tt>use_previous_sparsity=true</tt> the sparsity is not
+ * recreated but the sparsity of the previous initialize() call is
  * reused (recycled). This might be useful when several linear
  * problems on the same sparsity need to solved, as for example
  * several Newton iteration steps on the same triangulation. The
- * default is @p{false}.
+ * default is <tt>false</tt>.
  *
  * 4/ It is possible to give a user defined sparsity to
- * @p{use_this_sparsity}. Then, no sparsity is created but
- * @p[*use_this_sparsity} is used to store the decomposed matrix. For
+ * <tt>use_this_sparsity</tt>. Then, no sparsity is created but
+ * <tt>*use_this_sparsity</tt> is used to store the decomposed matrix. For
  * restrictions on the sparsity see section `Fill-in' above).
  *
  *
  * @sect2{State management}
  *
- * The state management simply requires the @p{initialize} function to
+ * The state management simply requires the initialize() function to
  * be called before the object is used as preconditioner.
  *
  * Obsolete:
@@ -92,33 +92,33 @@
  * decomposition itself has been built, and to introduce some
  * optimization of common "sparse idioms", this class introduces a
  * simple state management.  A SparseLUdecomposition instance is
- * considered @p{not decomposed} if the decompose method has not yet
- * been invoked since the last time the underlying @ref{SparseMatrix}
+ * considered not decomposed if the decompose method has not yet
+ * been invoked since the last time the underlying SparseMatrix
  * had changed. The underlying sparse matrix is considered changed
  * when one of this class reinit methods, constructors or destructors
- * are invoked.  The @p{not decomposed} state is indicated by a false
- * value returned by @p{is_decomposed} method.  It is illegal to apply
- * this decomposition (@p{vmult} method) in not decomposed state; in
- * this case, the @p{vmult} method throws an @p{ExcInvalidState}
+ * are invoked.  The not-decomposed state is indicated by a false
+ * value returned by is_decomposed() method.  It is illegal to apply
+ * this decomposition (vmult() method) in not decomposed state; in
+ * this case, the vmult() method throws an <tt>ExcInvalidState</tt>
  * exception. This object turns into decomposed state immediately
- * after its @p{decompose} method is invoked. The @p{decomposed}
- * state is indicated by true value returned by @p{is_decomposed}
- * method. It is legal to apply this decomposition (@p{vmult} method) in
+ * after its decompose() method is invoked. The decomposed
+ * state is indicated by true value returned by is_decomposed()
+ * method. It is legal to apply this decomposition (vmult() method) in
  * decomposed state.
  *
  * @sect2{Particular implementations}
  *
- * It is enough to override the @p{initialize} and @p{vmult} methods to
+ * It is enough to override the initialize() and vmult() methods to
  * implement particular LU decompositions, like the true LU, or the
  * Cholesky decomposition. Additionally, if that decomposition needs
  * fine tuned diagonal strengthening on a per row basis, it may override the
- * @p{get_strengthen_diagonal} method. You should invoke the non-abstract
+ * get_strengthen_diagonal() method. You should invoke the non-abstract
  * base class method to employ the state management. Implementations
  * may choose more restrictive definition of what is legal or illegal
- * state; but they must conform to the @p{is_decomposed} method
+ * state; but they must conform to the is_decomposed() method
  * specification above.
  *
- * If an exception is thrown by method other than @p{vmult}, this
+ * If an exception is thrown by method other than vmult(), this
  * object may be left in an inconsistent state.
  *
  * @author Stephen "Cheffo" Kolaroff, 2002, based on SparseILU implementation by Wolfgang Bangerth; unified interface: Ralf Hartmann, 2003
@@ -132,10 +132,10 @@ class SparseLUDecomposition : protected SparseMatrix<number>,
     				     /**
 				      * Constructor. Does nothing.
 				      *
-				      * Call the @p{initialize}
+				      * Call the initialize()
 				      * function before using this
 				      * object as preconditioner
-				      * (@p{vmult}).
+				      * (vmult()).
 				      */
     SparseLUDecomposition ();
 
@@ -178,7 +178,7 @@ class SparseLUDecomposition : protected SparseMatrix<number>,
 			const SparsityPattern *use_this_sparsity=0);
 
 					 /**
-					  * @p{strengthen_diag} times
+					  * <tt>strengthen_diag</tt> times
 					  * the sum of absolute row
 					  * entries is added to the
 					  * diagonal entries.
@@ -191,32 +191,32 @@ class SparseLUDecomposition : protected SparseMatrix<number>,
 
 					 /**
 					  * By default, the
-					  * @p{initialize(matrix,
-					  * data)} function creates
+					  * <tt>initialize(matrix,
+					  * data)</tt> function creates
 					  * its own sparsity. This
 					  * sparsity has the same
-					  * @p{SparsityPattern} as
-					  * @p{matrix} with some extra
+					  * SparsityPattern as
+					  * <tt>matrix</tt> with some extra
 					  * off diagonals the number
 					  * of which is specified by
-					  * @p{extra_off_diagonals}.
+					  * <tt>extra_off_diagonals</tt>.
 					  *
 					  * The user can give a
-					  * @p{SparsityPattern} to
-					  * @p{use_this_sparsity}. Then
+					  * SparsityPattern to
+					  * <tt>use_this_sparsity</tt>. Then
 					  * this sparsity is used and
 					  * the
-					  * @p{extra_off_diagonals}
+					  * <tt>extra_off_diagonals</tt>
 					  * argument is ignored.
 					  */
 	unsigned int extra_off_diagonals;
 
 					 /**
 					  * If this flag is true the
-					  * @p{initialize} function uses
+					  * initialize() function uses
 					  * the same sparsity that was
 					  * used during the previous
-					  * @p{initialize} call.
+					  * initialize() call.
 					  *
 					  * This might be useful when
 					  * several linear problems on
@@ -230,17 +230,17 @@ class SparseLUDecomposition : protected SparseMatrix<number>,
 	
 					 /**
 					  * When a
-					  * @ref{SparsityPattern} is
+					  * SparsityPattern is
 					  * given to this argument,
-					  * the @p{initialize}
+					  * the initialize()
 					  * function calls
-					  * @p{reinit(*use_this_sparsity)}
+					  * <tt>reinit(*use_this_sparsity)</tt>
 					  * causing this sparsity to
 					  * be used.
 					  *
 					  * Note that the sparsity
 					  * structures of
-					  * @p{*use_this_sparsity} and
+					  * <tt>*use_this_sparsity</tt> and
 					  * the matrix passed to the
 					  * initialize function need
 					  * not be equal, but that the
@@ -263,15 +263,15 @@ class SparseLUDecomposition : protected SparseMatrix<number>,
 				      * parameters, see the class
 				      * documentation and the
 				      * documentation of the
-				      * @p{SparseLUDecomposition::AdditionalData}
+				      * SparseLUDecomposition::AdditionalData
 				      * class.
 				      *
 				      * According to the
-				      * @p{parameters}, this function
+				      * <tt>parameters</tt>, this function
 				      * creates a new SparsityPattern
 				      * or keeps the previous sparsity
 				      * or takes the sparsity given by
-				      * the user to @p{data}. Then,
+				      * the user to <tt>data</tt>. Then,
 				      * this function performs the LU
 				      * decomposition.
 				      *
@@ -341,7 +341,7 @@ class SparseLUDecomposition : protected SparseMatrix<number>,
 
                                      /**
                                       * Exception. Indicates violation
-                                      * of a @p{state rule}.
+                                      * of a state rule().
                                       */
     DeclException0 (ExcInvalidState);
 
@@ -361,9 +361,9 @@ class SparseLUDecomposition : protected SparseMatrix<number>,
                                       * the sum of absolute values of
                                       * its elements, determines the
                                       * strengthening factor (through
-                                      * @p{get_strengthen_diagonal})
+                                      * get_strengthen_diagonal())
                                       * sf and multiplies the diagonal
-                                      * entry with @p{sf+1}.
+                                      * entry with <tt>sf+1</tt>.
                                       */
     virtual void strengthen_diagonal_impl ();
 
@@ -371,53 +371,53 @@ class SparseLUDecomposition : protected SparseMatrix<number>,
                                       * In the decomposition phase,
                                       * computes a strengthening
                                       * factor for the diagonal entry
-                                      * in row @p{row} with sum of
+                                      * in row <tt>row</tt> with sum of
                                       * absolute values of its
-                                      * elements @p{rowsum}.<br> Note:
+                                      * elements <tt>rowsum</tt>.<br> Note:
                                       * The default implementation in
-                                      * @ref{SparseLUDecomposition}
+                                      * SparseLUDecomposition
                                       * returns
-                                      * @p{strengthen_diagonal}'s
+                                      * <tt>strengthen_diagonal</tt>'s
                                       * value.
                                       */
     virtual number get_strengthen_diagonal(const number rowsum, const unsigned int row) const;
     
                                      /**
                                       * State flag. If not in
-                                      * @em{decomposed} state, it is
-                                      * unlegal to apply the
+                                      * decomposed state, it is
+                                      * illegal to apply the
                                       * decomposition.  This flag is
                                       * cleared when the underlaying
-                                      * @ref{SparseMatrix}
-                                      * @ref{SparsityPattern} is
+                                      * SparseMatrix
+                                      * SparsityPattern is
                                       * changed, and set by
-                                      * @p{decompose}.
+                                      * decompose().
                                       */
     bool decomposed;
 
                                      /**
                                       * The default strenghtening
                                       * value, returned by
-                                      * @p{get_strengthen_diagonal}.
+                                      * get_strengthen_diagonal().
                                       */
     double  strengthen_diagonal;
 
                                      /**
                                       * For every row in the
                                       * underlying
-                                      * @ref{SparsityPattern}, this
+                                      * SparsityPattern, this
                                       * array contains a pointer
                                       * to the row's first
                                       * afterdiagonal entry. Becomes
                                       * available after invocation of
-                                      * @p{decompose}.
+                                      * decompose().
                                       */
     std::vector<const unsigned int*> prebuilt_lower_bound;
     
   private:
                                      /**
                                       * Fills the
-                                      * @ref{prebuilt_lower_bound}
+                                      * #prebuilt_lower_bound
                                       * array.
                                       */
     void prebuild_lower_bound ();
@@ -425,14 +425,14 @@ class SparseLUDecomposition : protected SparseMatrix<number>,
 				     /**
 				      * In general this pointer is
 				      * zero except for the case that
-				      * no @p{SparsityPattern} is
+				      * no SparsityPattern is
 				      * given to this class. Then, a
-				      * @p{SparsityPattern} is created
+				      * SparsityPattern is created
 				      * and is passed down to the
-				      * @p{SparseMatrix} base class.
+				      * SparseMatrix base class.
 				      *
 				      * Nevertheless, the
-				      * @p{SparseLUDecomposition}
+				      * SparseLUDecomposition
 				      * needs to keep ownership of
 				      * this sparsity. It keeps this
 				      * pointer to it enabling it to
diff --git a/deal.II/lac/include/lac/sparse_direct.h b/deal.II/lac/include/lac/sparse_direct.h
index 4b04418ccd..6cc8d97e90 100644
--- a/deal.II/lac/include/lac/sparse_direct.h
+++ b/deal.II/lac/include/lac/sparse_direct.h
@@ -2,7 +2,7 @@
 //    $Id$
 //    Version: $Name$
 //
-//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 by the deal.II authors
+//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004 by the deal.II authors
 //
 //    This file is subject to QPL and may not be  distributed
 //    without copyright and license information. Please refer
@@ -31,63 +31,62 @@
 /**
  * This class provides an interface to the sparse direct solver MA27
  * from the Harwell Subroutine Library. MA27 is a direct solver
- * specialized for sparse symmetric indefinite systems of linear equations and
- * uses a modified form of Gauss elimination. It is included in the
- * Harwell Subroutine Library (see
- * @url{http://www.cse.clrc.ac.uk/Activity/HSL}) and is written in
- * Fortran. The present class only transforms the data stored in
- * @ref{SparseMatrix} objects into the form which is required by the
- * functions resembling MA27, calls these Fortran functions, and
- * interprets some of the returned values indicating error codes,
- * etc. It also manages allocation of the right amount of temporary
- * storage required by these functions.
+ * specialized for sparse symmetric indefinite systems of linear
+ * equations and uses a modified form of Gauss elimination. It is
+ * included in the <a
+ * href="http://www.cse.clrc.ac.uk/Activity/HSL">Harwell Subroutine
+ * Library</a> and is written in Fortran. The present class only
+ * transforms the data stored in SparseMatrix objects into the
+ * form which is required by the functions resembling MA27, calls
+ * these Fortran functions, and interprets some of the returned values
+ * indicating error codes, etc. It also manages allocation of the
+ * right amount of temporary storage required by these functions.
  *
  * For a description of the steps necessary for the installation of
  * HSL subroutines, read the section on external libraries in the
- * deal.II ReadMe file.
+ * <tt>deal.II</tt> ReadMe file.
  *
- * @sect3{Interface and Method}
+ * @section SPDMA1 Interface and Method
  *
- * For the meaning of the three functions @p{initialize},
- * @p{factorize}, and @p{solve}, as well as for the method used in
- * MA27, please see the documentation of these functions, which can be
- * obtained from @url{http://www.cse.clrc.ac.uk/Activity/HSL}. In
- * practice, one will most often call the second @p{solve} function,
- * which solves the linear system for a given right hand sidem but one
- * can as well call the three functions separately if, for example,
- * one would like to solve the same matrix for several right hand side
- * vectors; the MA27 solver can do this efficiently, as it computes a
- * decomposition of the matrix, so that subsequent solves only amount
- * to a forward-backward substitution which is significantly less
- * costly than the decomposition process.
+ * For the meaning of the three functions initialize(), factorize(),
+ * and solve(), as well as for the method used in MA27, please see the
+ * <a href="http://www.cse.clrc.ac.uk/Activity/HSL">documentation</a>
+ * of these functions. In practice, you will most often call the
+ * second solve() function, which solves the linear system for a
+ * given right hand sidem but one can as well call the three functions
+ * separately if, for example, one would like to solve the same matrix
+ * for several right hand side vectors; the MA27 solver can do this
+ * efficiently, as it computes a decomposition of the matrix, so that
+ * subsequent solves only amount to a forward-backward substitution
+ * which is significantly less costly than the decomposition process.
  *
  *
- * @sect3{Parameters to the constructor}
+ * @section SPDMA2 Parameters to the constructor
  *
  * The constructor of this class takes several arguments. The meaning
  * is the following: the MA27 functions require the user to allocate
  * and pass a certain amount of memory for temporary variables or for
  * data to be passed to subsequent functions. The sizes of these
- * arrays are denoted by the variables @p{LIW1}, @p{LIW2}, and @p{LA},
- * where @p{LIW1} denotes the size of the @p{IW} array in the call to
- * @p{MA27A}, while @p{LIW2} is the array size in the call to
- * @p{MA27B}. The documentation of the MA27 functions gives ways to
+ * arrays are denoted by the variables <tt>LIW1</tt>, <tt>LIW2</tt>, and <tt>LA</tt>,
+ * where <tt>LIW1</tt> denotes the size of the <tt>IW</tt> array in the call to
+ * <tt>MA27A</tt>, while <tt>LIW2</tt> is the array size in the call to
+ * <tt>MA27B</tt>. The documentation of the MA27 functions gives ways to
  * obtain estimates for their values, e.g. by evaluating values
  * returned by functions called before. However, the documentation
- * only states that the values have to be @em{at least as large} as
+ * only states that the values have to be <b>at least</b> as large as
  * the estimates, a hint that is not very useful oftentimes (in my
  * humble opinion, the lack of dynamic memory allocation mechanism is
  * a good reason not to program in Fortran 77...).
  *
  * In our experience, it is often necessary to go beyond the proposed
- * values (most often for @p{LA}, but also for @p{LIW1}). The first
+ * values (most often for <tt>LA</tt>, but also for <tt>LIW1</tt>). The first
  * three parameters of the constructor denote by which factor the
  * initial estimates shall be increased. The default values are 1.2
  * (the documentation recommends this value, 1, and 1.5, values which
- * have often worked for us. Note that the value of @p{LIW} is only
+ * have often worked for us. Note that the value of <tt>LIW</tt> is only
  * changed in the second call if the recommended value times
- * @p{LIW_factor_2} is larger than the array size already is from the
- * call to @p{MA27A}; otherwise, @p{LIW_factor_2} is ignored.
+ * <tt>LIW_factor_2</tt> is larger than the array size already is from the
+ * call to <tt>MA27A</tt>; otherwise, <tt>LIW_factor_2</tt> is ignored.
  *
  * If the values thus constructed fail to work, we try to restart the
  * called function with larger values until the calls succeed. The
@@ -95,15 +94,15 @@
  * factor we shall increase the array sizes. If the increment factors
  * are less than or equal to one, then we only try to call the
  * respective calls to the functions once and abort by throwing an
- * error. Note that the @p{MA27C} function writes out an error message
- * if the value of @p{LA} is too small and gives an indication to
+ * error. Note that the <tt>MA27C</tt> function writes out an error message
+ * if the value of <tt>LA</tt> is too small and gives an indication to
  * which size it should be increased. However, most often the
  * indicated value is far too small and can not be relied upon.
  *
  *
- * @sect3{Note on parallelization}
+ * @section SPDMA3 Note on parallelization
  *
- * @sect4{Synchronisation}
+ * @subsection SPDMA4 Synchronisation
  * 
  * Due to the use of global variables through COMMON blocks, the calls
  * to the sparse direct solver routines are not multithreading-safe,
@@ -115,25 +114,24 @@
  * in different parts of your program, and may not want to use a
  * global variable for locking, this class has a lock as static member
  * variable, which may be accessed using the
- * @p{get_synchronisation_lock} function. Note however, that this
- * class does not perform the synchronisation for you within its
- * member functions. The reason is that you will usually want to
- * synchronise over the calls to @p{initialize} and @p{factorize},
- * since there should probably not be a call to one of these function
- * with another matrix between the calls for one matrix. (The author
- * does not really know whether this is true, but it is probably safe
- * to assume that.) Since such cross-function synchronisation can only
- * be performed from outside, it is left to the user of this class to
- * do so.
+ * get_synchronisation_lock() function. Note however, that this class
+ * does not perform the synchronisation for you within its member
+ * functions. The reason is that you will usually want to synchronise
+ * over the calls to initialize() and factorize(), since there should
+ * probably not be a call to one of these function with another matrix
+ * between the calls for one matrix. (The author does not really know
+ * whether this is true, but it is probably safe to assume that.)
+ * Since such cross-function synchronisation can only be performed
+ * from outside, it is left to the user of this class to do so.
  *
- * @sect4{Detached mode}
+ * @subsection SPDMA5 Detached mode
  *
- * As an alternative, you can call the function @p{set_detached_mode}
+ * As an alternative, you can call the function set_detached_mode()
  * right after calling the constructor. This lets the program fork, so
  * that we now have two programs that communicate via pipes.  The
  * forked copy of the program then actually replaces itself by a
- * program called @p{detached_ma27}, that is started in its place
- * through the @p{execv} system call. Now everytime you call one of
+ * program called <tt>detached_ma27</tt>, that is started in its place
+ * through the <tt>execv</tt> system call. Now everytime you call one of
  * the functions of this class, it relays the data to the other
  * program and lets it execute the respective function. The results
  * are then transfered back. Since the MA27 functions are only called
@@ -151,7 +149,7 @@
  * of a factor).
  *
  * Since no more synchronisation is necessary, the
- * @p{get_synchronisation_lock} returns a reference to a member
+ * get_synchronisation_lock() returns a reference to a member
  * variable when the detached mode is set. Thus, you need not change
  * your program: you can still acquire and release the lock as before,
  * it will only have no effect now, since different objects of this
@@ -161,10 +159,10 @@
  * you probably wanted.
  *
  * 
- * @sect4{Internals of the detached mode}
+ * @subsection SPDMA6 Internals of the detached mode
  *
  * The program that actually runs the detached solver is called
- * @p{detached_ma27}, and will show up under this name in the process
+ * <tt>detached_ma27</tt>, and will show up under this name in the process
  * list. It communicates with the main program through a pipe.
  *
  * Since the solver and the main program are two separated processes,
@@ -174,7 +172,7 @@
  * just not get any new jobs, but will happily wait until the end of
  * times. For this reason, the detached solver has a second thread
  * running in parallel that simply checks in regular intervals whether
- * the main program is still alive, using the @p{ps} program. If this
+ * the main program is still alive, using the <tt>ps</tt> program. If this
  * is no longer the case, the detached solver exits as well.
  *
  * Since the intervals between two such checks are a couple of second,
@@ -215,8 +213,8 @@ class SparseDirectMA27 : public Subscriptor
                                       * is).
                                       *
                                       * This function must not be
-                                      * called after @p{initialize}
-                                      * (or the two-argument @p{solve}
+                                      * called after initialize()
+                                      * (or the two-argument solve()
                                       * function has been called. If
                                       * it is to be called, then only
                                       * right after construction of
@@ -264,7 +262,7 @@ class SparseDirectMA27 : public Subscriptor
 				      *
 				      * If the initialization step has
 				      * not been performed yet, then
-				      * the @p{initialize} function is
+				      * the initialize() function is
 				      * called at the beginning of
 				      * this function.
 				      */
@@ -290,7 +288,7 @@ class SparseDirectMA27 : public Subscriptor
 				      * happened before, strange
 				      * things will happen. Note that
 				      * we can't actually call the
-				      * @p{factorize} function from
+				      * factorize() function from
 				      * here if it has not yet been
 				      * called, since we have no
 				      * access to the actual matrix.
@@ -389,7 +387,7 @@ class SparseDirectMA27 : public Subscriptor
 
                                      /**
                                       * Store whether
-                                      * @p{set_detached_mode} has been
+                                      * set_detached_mode() has been
                                       * called.
                                       */
     bool detached_mode;
@@ -459,7 +457,7 @@ class SparseDirectMA27 : public Subscriptor
     std::vector<double>       A;
 
 				     /**
-				      * Length of the @p{A} array.
+				      * Length of the <tt>A</tt> array.
 				      */
     unsigned int         LA;
     
@@ -508,7 +506,7 @@ class SparseDirectMA27 : public Subscriptor
     mutable Threads::ThreadMutex non_static_synchronisation_lock;
     
 				     /**
-				      * Fill the @p{A} array from the
+				      * Fill the <tt>A</tt> array from the
 				      * symmetric part of the given
 				      * matrix.
 				      */
@@ -594,42 +592,40 @@ class SparseDirectMA27 : public Subscriptor
 /**
  * This class provides an interface to the sparse direct solver MA47
  * from the Harwell Subroutine Library. MA47 is a direct solver
- * specialized for sparse symmetric indefinite systems of linear equations and
- * uses a frontal elimination method. It is included in the Harwell
- * Subroutine Library (see
- * @url{http://www.cse.clrc.ac.uk/Activity/HSL}) and is written in
- * Fortran. The present class only transforms the data stored in
- * @ref{SparseMatrix} objects into the form which is required by the
- * functions resembling MA47, calls these Fortran functions, and
- * interprets some of the returned values indicating error codes,
- * etc. It also manages allocation of the right amount of temporary
- * storage required by these functions.
+ * specialized for sparse symmetric indefinite systems of linear
+ * equations and uses a frontal elimination method. It is included in
+ * the <a href="http://www.cse.clrc.ac.uk/Activity/HSL">Harwell
+ * Subroutine Library</a> and is written in Fortran. The present class
+ * only transforms the data stored in SparseMatrix objects into
+ * the form which is required by the functions resembling MA47, calls
+ * these Fortran functions, and interprets some of the returned values
+ * indicating error codes, etc. It also manages allocation of the
+ * right amount of temporary storage required by these functions.
  *
  *
- * @sect3{Interface and Method}
+ * @section SPDMA47a Interface and Method
  *
- * For the meaning of the three functions @p{initialize},
- * @p{factorize}, and @p{solve}, as well as for the method used in
- * MA47, please see the documentation of these functions, which can be
- * obtained from @url{http://www.cse.clrc.ac.uk/Activity/HSL}. In
- * practice, one will most often call the second @p{solve} function,
- * which solves the linear system for a given right hand sidem but one
- * can as well call the three functions separately if, for example,
- * one would like to solve the same matrix for several right hand side
- * vectors; the MA47 solver can do this efficiently, as it computes a
- * decomposition of the matrix, so that subsequent solves only amount
- * to a forward-backward substitution which is significantly less
- * costly than the decomposition process.
+ * For the meaning of the three functions initialize(), factorize(),
+ * and solve(), as well as for the method used in MA47, please see the
+ * <a href="http://www.cse.clrc.ac.uk/Activity/HSL">documentation</a>
+ * of these functions. In practice, one will most often call the
+ * second solve() function, which solves the linear system for a given
+ * right hand sidem but one can as well call the three functions
+ * separately if, for example, one would like to solve the same matrix
+ * for several right hand side vectors; the MA47 solver can do this
+ * efficiently, as it computes a decomposition of the matrix, so that
+ * subsequent solves only amount to a forward-backward substitution
+ * which is significantly less costly than the decomposition process.
  *
  *
- * @sect3{Parameters to the constructor}
+ * @section SPDMA47b Parameters to the constructor
  *
  * The constructor of this class takes several arguments. Their
  * meaning is equivalent to those of the constructor of the
  * @ref{SparseDirectMA27} class; see there for more information.
  *
  *
- * @sect3{Note on parallelization}
+ * @section SPDMA47c Note on parallelization
  *
  * Due to the use of global variables through COMMON blocks, the calls
  * to the sparse direct solver routines is not multithreading-capable,
@@ -641,16 +637,15 @@ class SparseDirectMA27 : public Subscriptor
  * in different parts of your program, and may not want to use a
  * global variable for locking, this class has a lock as static member
  * variable, which may be accessed using the
- * @p{get_synchronisation_lock} function. Note however, that this
- * class does not perform the synchronisation for you within its
- * member functions. The reason is that you will usually want to
- * synchronise over the calls to @p{initialize} and @p{factorize},
- * since there should probably not be a call to one of these function
- * with another matrix between the calls for one matrix. (The author
- * does not really know whether this is true, but it is probably safe
- * to assume that.) Since such cross-function synchronisation can only
- * be performed from outside, it is left to the user of this class to
- * do so.
+ * get_synchronisation_lock() function. Note however, that this class
+ * does not perform the synchronisation for you within its member
+ * functions. The reason is that you will usually want to synchronise
+ * over the calls to initialize() and factorize(), since there should
+ * probably not be a call to one of these function with another matrix
+ * between the calls for one matrix. (The author does not really know
+ * whether this is true, but it is probably safe to assume that.)
+ * Since such cross-function synchronisation can only be performed
+ * from outside, it is left to the user of this class to do so.
  *
  * A detached mode as for MA27 has not yet been implemented for this
  * class.
@@ -668,7 +663,7 @@ class SparseDirectMA47 : public Subscriptor
 				      *
 				      * This function already calls
 				      * the initialization function
-				      * @p{MA47ID} to set up some
+				      * <tt>MA47ID</tt> to set up some
 				      * values.
 				      */
     SparseDirectMA47 (const double LIW_factor_1 = 1.4,
@@ -717,7 +712,7 @@ class SparseDirectMA47 : public Subscriptor
 				      *
 				      * If the initialization step has
 				      * not been performed yet, then
-				      * the @p{initialize} function is
+				      * the initialize() function is
 				      * called at the beginning of
 				      * this function.
 				      */
@@ -743,7 +738,7 @@ class SparseDirectMA47 : public Subscriptor
 				      * happened before, strange
 				      * things will happen. Note that
 				      * we can't actually call the
-				      * @p{factorize} function from
+				      * factorize() function from
 				      * here if it has not yet been
 				      * called, since we have no
 				      * access to the actual matrix.
@@ -866,7 +861,7 @@ class SparseDirectMA47 : public Subscriptor
     unsigned int n_nonzero_elements;
 
 				     /**
-				      * Control values set by @p{MA47ID}.
+				      * Control values set by <tt>MA47ID</tt>.
 				      */
     double       CNTL[2];
     unsigned int ICNTL[7];
@@ -893,7 +888,7 @@ class SparseDirectMA47 : public Subscriptor
     std::vector<double>       A;
 
 				     /**
-				      * Length of the @p{A} array.
+				      * Length of the <tt>A</tt> array.
 				      */
     unsigned int         LA;
     
@@ -918,21 +913,21 @@ class SparseDirectMA47 : public Subscriptor
     static Threads::ThreadMutex synchronisation_lock;
     
 				     /**
-				      * Fill the @p{A} array from the
+				      * Fill the <tt>A</tt> array from the
 				      * symmetric part of the given
 				      * matrix.
 				      */
     void fill_A (const SparseMatrix<double> &matrix);
 
                                      /**
-                                      * Call the @p{ma47id} function
+                                      * Call the <tt>ma47id</tt> function
                                       * with the given args.
                                       */
     void call_ma47id (double       *CNTL,
                       unsigned int *ICNTL);
 
                                      /**
-                                      * Call the @p{ma47ad} function
+                                      * Call the <tt>ma47ad</tt> function
                                       * with the given args.
                                       */
     void call_ma47ad (const unsigned int *n_rows,
@@ -946,7 +941,7 @@ class SparseDirectMA47 : public Subscriptor
                       int                *INFO);
 
                                      /**
-                                      * Call the @p{ma47bd} function
+                                      * Call the <tt>ma47bd</tt> function
                                       * with the given args.
                                       */
     void call_ma47bd (const unsigned int *n_rows,
@@ -963,7 +958,7 @@ class SparseDirectMA47 : public Subscriptor
                       int                *INFO);
 
                                      /**
-                                      * Call the @p{ma47bd} function
+                                      * Call the <tt>ma47bd</tt> function
                                       * with the given args.
                                       */
     void call_ma47cd (const unsigned int *n_rows,
diff --git a/deal.II/lac/include/lac/sparse_matrix.h b/deal.II/lac/include/lac/sparse_matrix.h
index fbee8cf871..c04c023490 100644
--- a/deal.II/lac/include/lac/sparse_matrix.h
+++ b/deal.II/lac/include/lac/sparse_matrix.h
@@ -2,7 +2,7 @@
 //    $Id$
 //    Version: $Name$
 //
-//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 by the deal.II authors
+//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004 by the deal.II authors
 //
 //    This file is subject to QPL and may not be  distributed
 //    without copyright and license information. Please refer
@@ -30,18 +30,8 @@ template<typename number> class FullMatrix;
 /**
  * Sparse matrix.
  *
- *
- * @sect2{On template instantiations}
- *
- * Member functions of this class are either implemented in this file
- * or in a file of the same name with suffix ``.templates.h''. For the
- * most common combinations of the template parameters, instantiations
- * of this class are provided in a file with suffix ``.cc'' in the
- * ``source'' directory. If you need an instantiation that is not
- * listed there, you have to include this file along with the
- * corresponding ``.templates.h'' file and instantiate the respective
- * class yourself.
- *
+ * @ref Instantiations some
+ 
  * @author several, 1994-2003
  */
 template <typename number>
@@ -155,7 +145,7 @@ class SparseMatrix : public virtual Subscriptor
                                           */
 	bool operator == (const const_iterator&) const;
                                          /**
-                                          * Inverse of @p{==}.
+                                          * Inverse of <tt>==</tt>.
                                           */
 	bool operator != (const const_iterator&) const;
 
@@ -197,7 +187,7 @@ class SparseMatrix : public virtual Subscriptor
 				      *
 				      * You have to initialize
 				      * the matrix before usage with
-				      * @p{reinit(SparsityPattern)}.
+				      * reinit(const SparsityPattern&).
 				      */
     SparseMatrix ();
 
@@ -206,12 +196,12 @@ class SparseMatrix : public virtual Subscriptor
 				      * only allowed to be called if the matrix
 				      * to be copied is empty. This is for the
 				      * same reason as for the
-				      * @p{SparsityPattern}, see there for the
+				      * SparsityPattern, see there for the
 				      * details.
 				      *
 				      * If you really want to copy a whole
 				      * matrix, you can do so by using the
-				      * @p{copy_from} function.
+				      * copy_from() function.
 				      */
     SparseMatrix (const SparseMatrix &);
 
@@ -221,16 +211,17 @@ class SparseMatrix : public virtual Subscriptor
 				      * represent the sparsity pattern
 				      * of this matrix. You can change
 				      * the sparsity pattern later on
-				      * by calling the @p{reinit}
-				      * function.
+				      * by calling the reinit(const
+				      * SparsityPattern&) function.
 				      *
 				      * You have to make sure that the
 				      * lifetime of the sparsity
 				      * structure is at least as long
 				      * as that of this matrix or as
-				      * long as @p{reinit} is not
+				      * long as reinit(const
+				      * SparsityPattern&) is not
 				      * called with a new sparsity
-				      * structure.
+				      * pattern.
 				      *
 				      * The constructor is marked
 				      * explicit so as to disallow
@@ -259,8 +250,8 @@ class SparseMatrix : public virtual Subscriptor
 				      * Reinitialize the object but
 				      * keep to the sparsity pattern
 				      * previously used.  This may be
-				      * necessary if you @p{reinit}'d
-				      * the sparsity structure and
+				      * necessary if the sparsity
+				      * structure has changed and you
 				      * want to update the size of the
 				      * matrix.
 				      *
@@ -298,8 +289,10 @@ class SparseMatrix : public virtual Subscriptor
 				      * lifetime of the sparsity
 				      * structure is at least as long
 				      * as that of this matrix or as
-				      * long as @p{reinit} is not called
-				      * with a new sparsity structure.
+				      * long as reinit(const
+				      * SparsityPattern &) is not
+				      * called with a new sparsity
+				      * structure.
 				      *
 				      * The elements of the matrix are
 				      * set to zero by this function.
@@ -320,7 +313,7 @@ class SparseMatrix : public virtual Subscriptor
 				      * Return whether the object is
 				      * empty. It is empty if either
 				      * both dimensions are zero or no
-				      * @p{SparsityPattern} is
+				      * SparsityPattern is
 				      * associated.
 				      */
     bool empty () const;
@@ -358,8 +351,8 @@ class SparseMatrix : public virtual Subscriptor
 				      * matrix.
 				      *
 				      * Note, that this function does
-				      * (in contrary to the
-				      * @p{n_nonzero_elements}) NOT
+				      * (in contrary to
+				      * n_nonzero_elements()) not
 				      * count all entries of the
 				      * sparsity pattern but only the
 				      * ones that are nonzero.
@@ -367,10 +360,12 @@ class SparseMatrix : public virtual Subscriptor
     unsigned int n_actually_nonzero_elements () const;
     
 				     /**
-				      * Set the element @p{(i,j)} to @p{value}.
-				      * Throws an error if the entry does
-				      * not exist. Still, it is allowed to store
-				      * zero values in non-existent fields.
+				      * Set the element (<i>i,j</i>)
+				      * to <tt>value</tt>. Throws an
+				      * error if the entry does not
+				      * exist. Still, it is allowed to
+				      * store zero values in
+				      * non-existent fields.
 				      */
     void set (const unsigned int i, const unsigned int j,
 	      const number value);
@@ -388,9 +383,9 @@ class SparseMatrix : public virtual Subscriptor
     SparseMatrix & operator /= (const number factor);
     
 				     /**
-				      * Add @p{value} to the element
-				      * @p{(i,j)}.  Throws an error if
-				      * the entry does not
+				      * Add <tt>value</tt> to the
+				      * element (<i>i,j</i>).  Throws
+				      * an error if the entry does not
 				      * exist. Still, it is allowed to
 				      * store zero values in
 				      * non-existent fields.
@@ -420,9 +415,8 @@ class SparseMatrix : public virtual Subscriptor
 				      * in the
 				      * symmetrization. Symmetrization
 				      * of the sparsity pattern can be
-				      * obtain by the
-				      * @ref{SparsityPattern}@p{::symmetrize}
-				      * function.
+				      * obtain by
+				      * SparsityPattern::symmetrize().
 				      */
     void symmetrize ();
     
@@ -437,11 +431,11 @@ class SparseMatrix : public virtual Subscriptor
 				      * cheaper. Since this operation
 				      * is notheless not for free, we
 				      * do not make it available
-				      * through @p{operator =}, since
-				      * this may lead to unwanted
-				      * usage, e.g. in copy arguments
-				      * to functions, which should
-				      * really be arguments by
+				      * through <tt>operator =</tt>,
+				      * since this may lead to
+				      * unwanted usage, e.g. in copy
+				      * arguments to functions, which
+				      * should really be arguments by
 				      * reference.
 				      *
 				      * The source matrix may be a matrix
@@ -450,7 +444,7 @@ class SparseMatrix : public virtual Subscriptor
 				      * data type of this matrix.
 				      *
 				      * The function returns a reference to
-				      * @p{this}.
+				      * <tt>*this</tt>.
 				      */
     template <typename somenumber>
     SparseMatrix<number> &
@@ -459,7 +453,7 @@ class SparseMatrix : public virtual Subscriptor
 				     /**
 				      * This function is complete
 				      * analogous to the
-				      * @ref{SparsityPattern}@p{::copy_from}
+				      * SparsityPattern::copy_from()
 				      * function in that it allows to
 				      * initialize a whole matrix in
 				      * one step. See there for more
@@ -473,12 +467,14 @@ class SparseMatrix : public virtual Subscriptor
 				      * cited function is that the
 				      * objects which the inner
 				      * iterator points to need to be
-				      * of type @p{std::pair<unsigned int, value},
-				      * where @p{value}
-				      * needs to be convertible to the
-				      * element type of this class, as
-				      * specified by the @p{number}
-				      * template argument.
+				      * of type <tt>std::pair<unsigned
+				      * int, value</tt>, where
+				      * <tt>value</tt> needs to be
+				      * convertible to the element
+				      * type of this class, as
+				      * specified by the
+				      * <tt>number</tt> template
+				      * argument.
 				      *
 				      * Previous content of the matrix
 				      * is overwritten. Note that the
@@ -506,13 +502,13 @@ class SparseMatrix : public virtual Subscriptor
     void copy_from (const FullMatrix<somenumber> &matrix);
     
 				     /**
-				      * Add @p{matrix} scaled by
-				      * @p{factor} to this matrix. The
-				      * function throws an error if
-				      * the sparsity patterns of the
-				      * two involved matrices do not
-				      * point to the same object,
-				      * since in this case the
+				      * Add <tt>matrix</tt> scaled by
+				      * <tt>factor</tt> to this
+				      * matrix. The function throws an
+				      * error if the sparsity patterns
+				      * of the two involved matrices
+				      * do not point to the same
+				      * object, since in this case the
 				      * operation is cheaper.
 				      *
 				      * The source matrix may be a matrix
@@ -526,7 +522,7 @@ class SparseMatrix : public virtual Subscriptor
     
 				     /**
 				      * Return the value of the entry
-				      * (i,j).  This may be an
+				      * (<i>i,j</i>).  This may be an
 				      * expensive operation and you
 				      * should always take care where
 				      * to call this function.  In
@@ -539,41 +535,55 @@ class SparseMatrix : public virtual Subscriptor
 				      * that returns zero instead (for
 				      * entries that are not in the
 				      * sparsity pattern of the
-				      * matrix), use the @p{el}
+				      * matrix), use the el()
 				      * function.
+				      *
+				      * @deprecated Consider using
+				      * const_iterator instead, since
+				      * it is tailored better to a
+				      * sparse matrix structure.
 				      */
     number operator () (const unsigned int i,
 			const unsigned int j) const;
 
 				     /**
 				      * This function is mostly like
-				      * @p{operator()} in that it
+				      * operator()() in that it
 				      * returns the value of the
-				      * matrix entry @p{(i,j)}. The only
-				      * difference is that if this
-				      * entry does not exist in the
-				      * sparsity pattern, then instead
-				      * of raising an exception, zero
-				      * is returned. While this may be
+				      * matrix entry (<i>i,j</i>). The
+				      * only difference is that if
+				      * this entry does not exist in
+				      * the sparsity pattern, then
+				      * instead of raising an
+				      * exception, zero is
+				      * returned. While this may be
 				      * convenient in some cases, note
 				      * that it is simple to write
 				      * algorithms that are slow
 				      * compared to an optimal
 				      * solution, since the sparsity
 				      * of the matrix is not used.
+				      *
+				      * @deprecated Consider using
+				      * const_iterator instead, since
+				      * it is tailored better to a
+				      * sparse matrix structure.
 				      */
     number el (const unsigned int i,
 	       const unsigned int j) const;
 
 				     /**
-				      * Return the main diagonal element in
-				      * the @p{i}th row. This function throws an
-				      * error if the matrix is not square.
+				      * Return the main diagonal
+				      * element in the <i>i</i>th
+				      * row. This function throws an
+				      * error if the matrix is not
+				      * quadratic (see
+				      * SparsityPattern::optimize_diagonal()).
 				      *
 				      * This function is considerably
-				      * faster than the @p{operator()},
-				      * since for square matrices, the
-				      * diagonal entry is always the
+				      * faster than the operator()(),
+				      * since for quadratic matrices, the
+				      * diagonal entry may be the
 				      * first to be stored in each row
 				      * and access therefore does not
 				      * involve searching for the
@@ -591,22 +601,30 @@ class SparseMatrix : public virtual Subscriptor
 				     /**
 				      * Access to values in internal
 				      * mode.  Returns the value of
-				      * the @p{index}th entry in
-				      * @p{row}. Here, @p{index} refers to
-				      * the internal representation of
-				      * the matrix, not the column. Be
-				      * sure to understand what you are
-				      * doing here.
+				      * the <tt>index</tt>th entry in
+				      * <tt>row</tt>. Here,
+				      * <tt>index</tt> refers to the
+				      * internal representation of the
+				      * matrix, not the column. Be
+				      * sure to understand what you
+				      * are doing here.
+				      *
+				      * @deprecated Use const_iterator
+				      * instead!
 				      */
     number raw_entry (const unsigned int row,
 		      const unsigned int index) const;
     
     				     /**
+				      * @internal
+				      * @deprecated Use const_iterator
+				      * instead!
+				      *
 				      * This is for hackers. Get
-				      * access to the @p{i}th element of
+				      * access to the <i>i</i>th element of
 				      * this matrix. The elements are
 				      * stored in a consecutive way,
-				      * refer to the @p{SparsityPattern}
+				      * refer to the SparsityPattern
 				      * class for more details.
 				      *
 				      * You should use this interface
@@ -624,6 +642,10 @@ class SparseMatrix : public virtual Subscriptor
     number global_entry (const unsigned int i) const;
 
 				     /**
+				      * @internal
+				      * @deprecated Use const_iterator
+				      * instead!
+				      *
 				      * Same as above, but with write
 				      * access.  You certainly know
 				      * what you do?
@@ -632,8 +654,8 @@ class SparseMatrix : public virtual Subscriptor
 
 				     /**
 				      * Matrix-vector multiplication:
-				      * let $dst = M*src$ with $M$
-				      * being this matrix.
+				      * let <i>dst = M*src</i> with
+				      * <i>M</i> being this matrix.
 				      */
     template <typename somenumber>
     void vmult (Vector<somenumber>       &dst,
@@ -641,11 +663,11 @@ class SparseMatrix : public virtual Subscriptor
     
 				     /**
 				      * Matrix-vector multiplication:
-				      * let $dst = M^T*src$ with $M$
-				      * being this matrix. This
-				      * function does the same as
-				      * @p{vmult} but takes the
-				      * transposed matrix.
+				      * let <i>dst = M<sup>T</sup>*src</i> with
+				      * <i>M</i> being this
+				      * matrix. This function does the
+				      * same as vmult() but takes
+				      * the transposed matrix.
 				      */
     template <typename somenumber>
     void Tvmult (Vector<somenumber>       &dst,
@@ -653,8 +675,9 @@ class SparseMatrix : public virtual Subscriptor
   
 				     /**
 				      * Adding Matrix-vector
-				      * multiplication. Add $M*src$ on
-				      * $dst$ with $M$ being this
+				      * multiplication. Add
+				      * <i>M*src</i> on <i>dst</i>
+				      * with <i>M</i> being this
 				      * matrix.
 				      */
     template <typename somenumber>
@@ -663,11 +686,13 @@ class SparseMatrix : public virtual Subscriptor
     
 				     /**
 				      * Adding Matrix-vector
-				      * multiplication. Add $M^T*src$
-				      * to $dst$ with $M$ being this
-				      * matrix. This function does the
-				      * same as @p{vmult_add} but takes
-				      * the transposed matrix.
+				      * multiplication. Add
+				      * <i>M<sup>T</sup>*src</i> to
+				      * <i>dst</i> with <i>M</i> being
+				      * this matrix. This function
+				      * does the same as vmult_add()
+				      * but takes the transposed
+				      * matrix.
 				      */
     template <typename somenumber>
     void Tvmult_add (Vector<somenumber>       &dst,
@@ -689,7 +714,7 @@ class SparseMatrix : public virtual Subscriptor
 				      * element function.
 				      *
 				      * Obviously, the matrix needs to
-				      * be square for this operation.
+				      * be quadratic for this operation.
 				      */
     template <typename somenumber>
     somenumber matrix_norm_square (const Vector<somenumber> &v) const;
@@ -731,13 +756,12 @@ class SparseMatrix : public virtual Subscriptor
 
 				     /**
 				      * Compute the residual of an
-				      * equation @p{Mx=b}, where the
-				      * residual is defined to be
-				      * @p{r=b-Mx} with @p{x} typically
-				      * being an approximate of the
-				      * true solution of the
-				      * equation. Write the residual
-				      * into @p{dst}. The l2 norm of
+				      * equation <i>Mx=b</i>, where
+				      * the residual is defined to be
+				      * <i>r=b-Mx</i>. Write the
+				      * residual into
+				      * <tt>dst</tt>. The
+				      * <i>l<sub>2</sub></i> norm of
 				      * the residual vector is
 				      * returned.
 				      */
@@ -750,11 +774,11 @@ class SparseMatrix : public virtual Subscriptor
 				      * Apply the Jacobi
 				      * preconditioner, which
 				      * multiplies every element of
-				      * the @p{src} vector by the
+				      * the <tt>src</tt> vector by the
 				      * inverse of the respective
 				      * diagonal element and
 				      * multiplies the result with the
-				      * damping factor @p{omega}.
+				      * relaxation factor <tt>omega</tt>.
 				      */
     template <typename somenumber>
     void precondition_Jacobi (Vector<somenumber>       &dst,
@@ -763,7 +787,7 @@ class SparseMatrix : public virtual Subscriptor
 
 				     /**
 				      * Apply SSOR preconditioning to
-				      * @p{src}.
+				      * <tt>src</tt>.
 				      */
     template <typename somenumber>
     void precondition_SSOR (Vector<somenumber>       &dst,
@@ -771,9 +795,8 @@ class SparseMatrix : public virtual Subscriptor
 			    const number              om = 1.) const;
 
 				     /**
-				      * Apply SOR preconditioning matrix to @p{src}.
-				      * The result of this method is
-				      * $dst = (om D - L)^{-1} src$.
+				      * Apply SOR preconditioning
+				      * matrix to <tt>src</tt>.
 				      */
     template <typename somenumber>
     void precondition_SOR (Vector<somenumber>       &dst,
@@ -781,9 +804,9 @@ class SparseMatrix : public virtual Subscriptor
  			   const number              om = 1.) const;
     
 				     /**
-				      * Apply transpose SOR preconditioning matrix to @p{src}.
-				      * The result of this method is
-				      * $dst = (om D - U)^{-1} src$.
+				      * Apply transpose SOR
+				      * preconditioning matrix to
+				      * <tt>src</tt>.
 				      */
     template <typename somenumber>
     void precondition_TSOR (Vector<somenumber>       &dst,
@@ -795,7 +818,7 @@ class SparseMatrix : public virtual Subscriptor
 				      * in-place.  Apply the
 				      * preconditioner matrix without
 				      * copying to a second vector.
-				      * @p{omega} is the relaxation
+				      * <tt>omega</tt> is the relaxation
 				      * parameter.
 				      */
     template <typename somenumber>
@@ -803,18 +826,19 @@ class SparseMatrix : public virtual Subscriptor
 	       const number        omega = 1.) const;
 
 				     /**
-				      * Perform an SOR preconditioning in-place.
-				      * The result is $v = (\omega D - L)^{-1} v$.
-				      * @p{omega} is the damping parameter.
+				      * Perform an SOR preconditioning
+				      * in-place.  <tt>omega</tt> is
+				      * the relaxation parameter.
 				      */
     template <typename somenumber>
     void SOR (Vector<somenumber> &v,
 	      const number        om = 1.) const;
 
 				     /**
-				      * Perform a transpose SOR preconditioning in-place.
-				      * The result is $v = (\omega D - L)^{-1} v$.
-				      * @p{omega} is the damping parameter.
+				      * Perform a transpose SOR
+				      * preconditioning in-place.
+				      * <tt>omega</tt> is the
+				      * relaxation parameter.
 				      */
     template <typename somenumber>
     void TSOR (Vector<somenumber> &v,
@@ -826,16 +850,16 @@ class SparseMatrix : public virtual Subscriptor
 				      *
 				      * The standard SOR method is
 				      * applied in the order
-				      * prescribed by @p{permutation},
+				      * prescribed by <tt>permutation</tt>,
 				      * that is, first the row
-				      * @p{permutation[0]}, then
-				      * @p{permutation[1]} and so
+				      * <tt>permutation[0]</tt>, then
+				      * <tt>permutation[1]</tt> and so
 				      * on. For efficiency reasons,
 				      * the permutation as well as its
 				      * inverse are required.
 				      *
-				      * @p{omega} is the relaxation
-				      * parameter.
+				      * <tt>omega</tt> is the
+				      * relaxation parameter.
 				      */
     template <typename somenumber>
     void PSOR (Vector<somenumber> &v,
@@ -849,16 +873,19 @@ class SparseMatrix : public virtual Subscriptor
 				      *
 				      * The transposed SOR method is
 				      * applied in the order
-				      * prescribed by @p{permutation},
-				      * that is, first the row
-				      * @p{permutation[m()-1]}, then
-				      * @p{permutation[m()-2]} and so
-				      * on. For efficiency reasons,
-				      * the permutation as well as its
-				      * inverse are required.
+				      * prescribed by
+				      * <tt>permutation</tt>, that is,
+				      * first the row
+				      * <tt>permutation[m()-1]</tt>,
+				      * then
+				      * <tt>permutation[m()-2]</tt>
+				      * and so on. For efficiency
+				      * reasons, the permutation as
+				      * well as its inverse are
+				      * required.
 				      *
-				      * @p{omega} is the relaxation
-				      * parameter.
+				      * <tt>omega</tt> is the
+				      * relaxation parameter.
 				      */
     template <typename somenumber>
     void TPSOR (Vector<somenumber> &v,
@@ -867,9 +894,10 @@ class SparseMatrix : public virtual Subscriptor
 	      const number        om = 1.) const;
 
 				     /**
-				      * Do one SOR step on @p{v}.
+				      * Do one SOR step on <tt>v</tt>.
 				      * Performs a direct SOR step
-				      * with right hand side @p{b}.
+				      * with right hand side
+				      * <tt>b</tt>.
 				      */
     template <typename somenumber>
     void SOR_step (Vector<somenumber> &v,
@@ -878,8 +906,9 @@ class SparseMatrix : public virtual Subscriptor
 
 				     /**
 				      * Do one adjoint SOR step on
-				      * @p{v}.  Performs a direct TSOR
-				      * step with right hand side @p{b}.
+				      * <tt>v</tt>.  Performs a direct
+				      * TSOR step with right hand side
+				      * <tt>b</tt>.
 				      */
     template <typename somenumber>
     void TSOR_step (Vector<somenumber> &v,
@@ -887,10 +916,11 @@ class SparseMatrix : public virtual Subscriptor
 		    const number        om = 1.) const;
 
 				     /**
-				      * Do one adjoint SSOR step on
-				      * @p{v}.  Performs a direct SSOR
-				      * step with right hand side @p{b}
-				      * by performing TSOR after SOR.
+				      * Do one SSOR step on
+				      * <tt>v</tt>.  Performs a direct
+				      * SSOR step with right hand side
+				      * <tt>b</tt> by performing TSOR
+				      * after SOR.
 				      */
     template <typename somenumber>
     void SSOR_step (Vector<somenumber> &v,
@@ -903,11 +933,11 @@ class SparseMatrix : public virtual Subscriptor
 				      * pattern of this matrix.
 				      *
 				      * Though the return value is
-				      * declared @p{const}, you should
-				      * be aware that it may change if
-				      * you call any nonconstant
-				      * function of objects which
-				      * operate on it.
+				      * declared <tt>const</tt>, you
+				      * should be aware that it may
+				      * change if you call any
+				      * nonconstant function of
+				      * objects which operate on it.
 				      */
     const SparsityPattern & get_sparsity_pattern () const;
 
@@ -924,21 +954,22 @@ class SparseMatrix : public virtual Subscriptor
     
 				     /**
 				      * STL-like iterator with the
-				      * first entry of row @p{r}.
+				      * first entry of row <tt>r</tt>.
 				      */
     const_iterator begin (const unsigned int r) const;
 
 				     /**
-				      * Final iterator of row @p{r}.
+				      * Final iterator of row
+				      * <tt>r</tt>.
 				      */
     const_iterator end (const unsigned int r) const;
     
 				     /**
 				      * Print the matrix to the given
 				      * stream, using the format
-				      * @p{(line,col) value}, i.e. one
-				      * nonzero entry of the matrix
-				      * per line.
+				      * <tt>(line,col) value</tt>,
+				      * i.e. one nonzero entry of the
+				      * matrix per line.
 				      */
     void print (std::ostream &out) const;
 
@@ -956,14 +987,15 @@ class SparseMatrix : public virtual Subscriptor
 				      *
 				      * The parameters allow for a
 				      * flexible setting of the output
-				      * format: @p{precision} and
-				      * @p{scientific} are used to
-				      * determine the number format,
-				      * where @p{scientific} = @p{false}
-				      * means fixed point notation.  A
-				      * zero entry for @p{width} makes
-				      * the function compute a width,
-				      * but it may be changed to a
+				      * format: <tt>precision</tt> and
+				      * <tt>scientific</tt> are used
+				      * to determine the number
+				      * format, where <tt>scientific =
+				      * false</tt> means fixed point
+				      * notation.  A zero entry for
+				      * <tt>width</tt> makes the
+				      * function compute a width, but
+				      * it may be changed to a
 				      * positive value, if output is
 				      * crude.
 				      *
@@ -977,9 +1009,10 @@ class SparseMatrix : public virtual Subscriptor
 				      * readable output, even
 				      * integers.
 				      *
-				      * This function
-				      * may produce @em{large} amounts of
-				      * output if applied to a large matrix!
+				      * @attention This function may
+				      * produce <b>large</b> amounts
+				      * of output if applied to a
+				      * large matrix!
 				      */
     void print_formatted (std::ostream       &out,
 			  const unsigned int  precision   = 3,
@@ -1012,12 +1045,11 @@ class SparseMatrix : public virtual Subscriptor
 
 				     /**
 				      * Read data that has previously
-				      * been written by
-				      * @p{block_write} en block from
-				      * a file. This is done using the
-				      * inverse operations to the
-				      * above function, so it is
-				      * reasonably fast because the
+				      * been written by block_write()
+				      * from a file. This is done
+				      * using the inverse operations
+				      * to the above function, so it
+				      * is reasonably fast because the
 				      * bitstream is not interpreted
 				      * except for a few numbers up
 				      * front.
@@ -1027,12 +1059,11 @@ class SparseMatrix : public virtual Subscriptor
 				      * contents are lost. Note,
 				      * however, that no checks are
 				      * performed whether new data and
-				      * the underlying
-				      * @ref{SparsityPattern} object
-				      * fit together. It is your
-				      * responsibility to make sure
-				      * that the sparsity pattern and
-				      * the data to be read match.
+				      * the underlying SparsityPattern
+				      * object fit together. It is
+				      * your responsibility to make
+				      * sure that the sparsity pattern
+				      * and the data to be read match.
 				      *
 				      * A primitive form of error
 				      * checking is performed which
@@ -1047,7 +1078,8 @@ class SparseMatrix : public virtual Subscriptor
 				     /**
 				      * Determine an estimate for the
 				      * memory consumption (in bytes)
-				      * of this object.
+				      * of this object. See
+				      * MemoryConsumption.
 				      */
     unsigned int memory_consumption () const;
     
@@ -1099,7 +1131,7 @@ class SparseMatrix : public virtual Subscriptor
 				      * matrix. In order to guarantee
 				      * that it is not deleted while
 				      * still in use, we subscribe to
-				      * it using the @p{SmartPointer}
+				      * it using the SmartPointer
 				      * class.
 				      */
     SmartPointer<const SparsityPattern> cols;
@@ -1119,24 +1151,24 @@ class SparseMatrix : public virtual Subscriptor
     number *val;
 
 				     /**
-				      * Allocated size of
-				      * @p{val}. This can be larger
-				      * than the actually used part if
-				      * the size of the matrix was
-				      * reduced somewhen in the past
-				      * by associating a sparsity
-				      * pattern with a smaller size to
-				      * this object, using the
-				      * @p{reinit} function.
+				      * Allocated size of #val. This
+				      * can be larger than the
+				      * actually used part if the size
+				      * of the matrix was reduced
+				      * somewhen in the past by
+				      * associating a sparsity pattern
+				      * with a smaller size to this
+				      * object, using the reinit()
+				      * function.
 				      */
     unsigned int max_len;
 
 				     /**
-				      * Version of @p{vmult} which only
+				      * Version of vmult() which only
 				      * performs its actions on the
 				      * region defined by
-				      * @p{[begin_row,end_row)}. This
-				      * function is called by @p{vmult}
+				      * <tt>[begin_row,end_row)</tt>. This
+				      * function is called by vmult()
 				      * in the case of enabled
 				      * multithreading.
 				      */
@@ -1148,12 +1180,12 @@ class SparseMatrix : public virtual Subscriptor
 
 				     /**
 				      * Version of
-				      * @p{matrix_norm_square} which
+				      * matrix_norm_square() which
 				      * only performs its actions on
 				      * the region defined by
-				      * @p{[begin_row,end_row)}. This
+				      * <tt>[begin_row,end_row)</tt>. This
 				      * function is called by
-				      * @p{matrix_norm_square} in the
+				      * matrix_norm_square() in the
 				      * case of enabled
 				      * multithreading.
 				      */
@@ -1165,12 +1197,12 @@ class SparseMatrix : public virtual Subscriptor
 
     				     /**
 				      * Version of
-				      * @p{matrix_scalar_product} which
+				      * matrix_scalar_product() which
 				      * only performs its actions on
 				      * the region defined by
-				      * @p{[begin_row,end_row)}. This
+				      * <tt>[begin_row,end_row)</tt>. This
 				      * function is called by
-				      * @p{matrix_scalar_product} in the
+				      * matrix_scalar_product() in the
 				      * case of enabled
 				      * multithreading.
 				      */
@@ -1182,15 +1214,16 @@ class SparseMatrix : public virtual Subscriptor
 					 somenumber               *partial_sum) const;
 
 				     /**
-				      * Version of @p{residual} which
+				      * Version of residual() which
 				      * only performs its actions on
 				      * the region defined by
-				      * @p{[begin_row,end_row)} (these
-				      * numbers are the components of
-				      * @p{interval}). This function is
-				      * called by @p{residual} in the
-				      * case of enabled
-				      * multithreading.
+				      * <tt>[begin_row,end_row)</tt>
+				      * (these numbers are the
+				      * components of
+				      * <tt>interval</tt>). This
+				      * function is called by
+				      * residual() in the case of
+				      * enabled multithreading.
 				      */
     template <typename somenumber>
     void threaded_residual (Vector<somenumber>       &dst,
@@ -1347,7 +1380,7 @@ number SparseMatrix<number>::diag_element (const unsigned int i) const
   Assert (i<m(), ExcInvalidIndex1(i));
   
 				   // Use that the first element in each
-				   // row of a square matrix is the main
+				   // row of a quadratic matrix is the main
 				   // diagonal
   return val[cols->rowstart[i]];
 }
@@ -1363,7 +1396,7 @@ number & SparseMatrix<number>::diag_element (const unsigned int i)
   Assert (i<m(), ExcInvalidIndex1(i));
   
 				   // Use that the first element in each
-				   // row of a square matrix is the main
+				   // row of a quadratic matrix is the main
 				   // diagonal
   return val[cols->rowstart[i]];
 }
diff --git a/deal.II/lac/include/lac/sparsity_pattern.h b/deal.II/lac/include/lac/sparsity_pattern.h
index 1c59455d4c..3211efb90a 100644
--- a/deal.II/lac/include/lac/sparsity_pattern.h
+++ b/deal.II/lac/include/lac/sparsity_pattern.h
@@ -2,7 +2,7 @@
 //    $Id$
 //    Version: $Name$
 //
-//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 by the deal.II authors
+//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004 by the deal.II authors
 //
 //    This file is subject to QPL and may not be  distributed
 //    without copyright and license information. Please refer
@@ -36,7 +36,7 @@ class CompressedSparsityPattern;
  * Structure representing the sparsity pattern of a sparse matrix.
  * 
  * The following picture will illustrate the relation between the
- * @p{SparsityPattern} an the @p{SparseMatrix}.
+ * SparsityPattern an the SparseMatrix.
  *
  * @begin{verbatim}
  *  SparsityPattern:                               \
@@ -73,14 +73,14 @@ class CompressedSparsityPattern;
  * @begin{verbatim}
  * For row = 0
  *   
- * it exists: (0| 3) = colnums[0]
+ * there are: (0| 3) = colnums[0]
  *            (0| 2) = colnums[1]
  *            (0| 9) = colnums[2]
  *            (0|17) = colnums[3]
  *
  * For row = 1
  *   
- * it exists: (1| 1) = colnums[4]
+ * there are: (1| 1) = colnums[4]
  *            (1| 4) = colnums[5]
  * ....
  *
@@ -97,13 +97,16 @@ class CompressedSparsityPattern;
  *                                                /
  * @end{verbatim}
  *
- * If you want to get the @p{3} you need to get its position in the
- * table above and its value by returning the value of the element on
- * which the pointer shows, using @p{*val}.  For example @p{val[8]=3}. Its
- * position is @p{colnums[8]} so @p{row=2}. In other words, if you want to get
- * the element @p{a_{24}} you know that @p{row=2}. To get the element, a
- * search of @p{4} form @p{colnums[rowstart[2]]} to @p{colnums[rowstart[3]]} is
- * needed. Then @p{a_{24}=val[number of the found element] = 3}.
+ * If you want to get the <tt>3</tt> you need to get its position in
+ * the table above and its value by returning the value of the element
+ * on which the pointer shows, using <tt>*val</tt>. For example
+ * <tt>val[8]=3</tt>. Its position is <tt>colnums[8]</tt> so
+ * <tt>row=2</tt>. In other words, if you want to get the element
+ * <i>a<sub>24</sub></i> you know that <tt>row=2</tt>. To get the
+ * element, a search of <tt>4</tt> form <tt>colnums[rowstart[2]]</tt>
+ * to <tt>colnums[rowstart[3]]</tt> is needed. Then
+ * <i>a<sub>24</sub></i>=<tt>val[number of the found element] =
+ * 3</tt>.
  *
  *
  * @author Wolfgang Bangerth and others
@@ -114,7 +117,7 @@ class SparsityPattern : public Subscriptor
 				     /**
 				      * Define a value which is used
 				      * to indicate that a certain
-				      * value in the @p{colnums} array
+				      * value in the #colnums array
 				      * is unused, i.e. does not
 				      * represent a certain column
 				      * number index.
@@ -122,9 +125,9 @@ class SparsityPattern : public Subscriptor
 				      * Indices with this invalid
 				      * value are used to insert new
 				      * entries to the sparsity
-				      * pattern using the @p{add} member
+				      * pattern using the add() member
 				      * function, and are removed when
-				      * calling @p{compress}.
+				      * calling compress().
 				      *
 				      * You should not assume that the
 				      * variable declared here has a
@@ -145,42 +148,50 @@ class SparsityPattern : public Subscriptor
 				      * member variables in other
 				      * classes. You can make the
 				      * structure usable by calling
-				      * the @p{reinit} function.
+				      * the reinit() function.
 				      */
     SparsityPattern ();
     
 				     /**
-				      * Copy constructor. This constructor is
-				      * only allowed to be called if the matrix
-				      * structure to be copied is empty. This is
-				      * so in order to prevent involuntary
-				      * copies of objects for temporaries, which
-				      * can use large amounts of computing time.
-				      * However, copy constructors are needed
-				      * if yo want to use the STL data types
-				      * on classes like this, e.g. to write
-				      * such statements like
-				      * @p{v.push_back (SparsityPattern());},
-				      * with @p{v} a vector of @p{SparsityPattern}
-				      * objects.
+				      * Copy constructor. This
+				      * constructor is only allowed to
+				      * be called if the matrix
+				      * structure to be copied is
+				      * empty. This is so in order to
+				      * prevent involuntary copies of
+				      * objects for temporaries, which
+				      * can use large amounts of
+				      * computing time.  However, copy
+				      * constructors are needed if yo
+				      * want to use the STL data types
+				      * on classes like this, e.g. to
+				      * write such statements like
+				      * <tt>v.push_back
+				      * (SparsityPattern());</tt>,
+				      * with <tt>v</tt> a vector of
+				      * SparsityPattern objects.
 				      *
-				      * Usually, it is sufficient to use the
-				      * explicit keyword to disallow unwanted
-				      * temporaries, but for the STL vectors,
-				      * this does not work. Since copying a
-				      * structure like this is not useful
-				      * anyway because multiple matrices can
-				      * use the same sparsity structure, copies
-				      * are only allowed for empty objects, as
-				      * described above.
+				      * Usually, it is sufficient to
+				      * use the explicit keyword to
+				      * disallow unwanted temporaries,
+				      * but for the STL vectors, this
+				      * does not work. Since copying a
+				      * structure like this is not
+				      * useful anyway because multiple
+				      * matrices can use the same
+				      * sparsity structure, copies are
+				      * only allowed for empty
+				      * objects, as described above.
 				      */
     SparsityPattern (const SparsityPattern &);
 
 				     /**
-				      * Initialize a rectangular matrix with
-				      * @p{m} rows and @p{n} columns.
-				      * The matrix may contain at most @p{max_per_row}
-				      * nonzero entries per row.
+				      * Initialize a rectangular
+				      * matrix with <tt>m</tt> rows
+				      * and <tt>n</tt> columns.  The
+				      * matrix may contain at most
+				      * <tt>max_per_row</tt> nonzero
+				      * entries per row.
 				      *
 				      * If the matrix is quadratic,
 				      * then the last parameter
@@ -196,11 +207,12 @@ class SparsityPattern : public Subscriptor
 
 				     /**
 				      * Initialize a rectangular
-				      * matrix with @p{m} rows and @p{n}
-				      * columns.  The maximal number
-				      * of nonzero entries for each
-				      * row is given by the
-				      * @p{row_lengths} array.
+				      * matrix with <tt>m</tt> rows
+				      * and <tt>n</tt> columns.  The
+				      * maximal number of nonzero
+				      * entries for each row is given
+				      * by the <tt>row_lengths</tt>
+				      * array.
 				      */
     SparsityPattern (const unsigned int               m,
 		     const unsigned int               n,
@@ -209,7 +221,7 @@ class SparsityPattern : public Subscriptor
     
 				     /**
 				      * Initialize a quadratic matrix of dimension
-				      * @p{n} with at most @p{max_per_row}
+				      * <tt>n</tt> with at most <tt>max_per_row</tt>
 				      * nonzero entries per row.
 				      *
 				      * This constructor automatically
@@ -223,12 +235,13 @@ class SparsityPattern : public Subscriptor
 		     const unsigned int max_per_row);
 
 				     /**
-				      * Initialize a quadratic
-				      * matrix with @p{m} rows and @p{m}
-				      * columns.  The maximal number
-				      * of nonzero entries for each
-				      * row is given by the
-				      * @p{row_lengths} array.
+				      * Initialize a quadratic matrix
+				      * with <tt>m</tt> rows and
+				      * <tt>m</tt> columns.  The
+				      * maximal number of nonzero
+				      * entries for each row is given
+				      * by the <tt>row_lengths</tt>
+				      * array.
 				      */
     SparsityPattern (const unsigned int               m,
 		     const std::vector<unsigned int> &row_lengths,
@@ -242,31 +255,39 @@ class SparsityPattern : public Subscriptor
 				      * or other incomplete decompositions.
 				      * Therefore, additional to the original
 				      * entry structure, space for
-				      * @p{extra_off_diagonals}
+				      * <tt>extra_off_diagonals</tt>
 				      * side-diagonals is provided on both
 				      * sides of the main diagonal.
 				      *
-				      * @p{max_per_row} is the maximum number of
-				      * nonzero elements per row which this
-				      * structure is to hold. It is assumed
-				      * that this number is sufficiently large
-				      * to accomodate both the elements in
-				      * @p{original} as well as the new
-				      * off-diagonal elements created by this
-				      * constructor. You will usually want to
-				      * give the same number as you gave for
-				      * @p{original} plus the number of side
-				      * diagonals times two. You may however
-				      * give a larger value if you wish to add
-				      * further nonzero entries for the
-				      * decomposition based on other criteria
-				      * than their being on side-diagonals.
+				      * <tt>max_per_row</tt> is the
+				      * maximum number of nonzero
+				      * elements per row which this
+				      * structure is to hold. It is
+				      * assumed that this number is
+				      * sufficiently large to
+				      * accomodate both the elements
+				      * in <tt>original</tt> as well
+				      * as the new off-diagonal
+				      * elements created by this
+				      * constructor. You will usually
+				      * want to give the same number
+				      * as you gave for
+				      * <tt>original</tt> plus the
+				      * number of side diagonals times
+				      * two. You may however give a
+				      * larger value if you wish to
+				      * add further nonzero entries
+				      * for the decomposition based on
+				      * other criteria than their
+				      * being on side-diagonals.
 				      *
-				      * This function requires that @p{original}
-				      * refer to a quadratic matrix structure.
-				      * It shall be compressed. The matrix 
-				      * structure is not compressed
-				      * after this function finishes.
+				      * This function requires that
+				      * <tt>original</tt> refers to a
+				      * quadratic matrix structure.
+				      * It must be compressed. The
+				      * matrix structure is not
+				      * compressed after this function
+				      * finishes.
 				      */
     SparsityPattern (const SparsityPattern  &original,
 		     const unsigned int      max_per_row,
@@ -290,13 +311,13 @@ class SparsityPattern : public Subscriptor
 				     /**
 				      * Reallocate memory and set up data
 				      * structures for a new matrix with
-				      * @p{m} rows and @p{n} columns,
-				      * with at most @p{max_per_row}
+				      * <tt>m </tt>rows and <tt>n</tt> columns,
+				      * with at most <tt>max_per_row</tt>
 				      * nonzero entries per row.
 				      *
 				      * This function simply maps its
 				      * operations to the other
-				      * @p{reinit} function.
+				      * <tt>reinit</tt> function.
 				      */
     void reinit (const unsigned int m,
 		 const unsigned int n,
@@ -305,14 +326,14 @@ class SparsityPattern : public Subscriptor
 
 				     /**
 				      * Reallocate memory for a matrix
-				      * of size @p{m \times n}. The
+				      * of size <tt>m x n</tt>. The
 				      * number of entries for each row
 				      * is taken from the array
-				      * @p{row_lengths} which has to
+				      * <tt>row_lengths</tt> which has to
 				      * give this number of each row
-				      * @p{i=1...m}.
+				      * <tt>i=1...m</tt>.
 				      *
-				      * If @p{m*n==0} all memory is freed,
+				      * If <tt>m*n==0</tt> all memory is freed,
 				      * resulting in a total reinitialization
 				      * of the object. If it is nonzero, new
 				      * memory is only allocated if the new
@@ -347,8 +368,8 @@ class SparsityPattern : public Subscriptor
 				      * The memory which is no more
 				      * needed is released.
 				      *
-				      * @p{SparseMatrix} objects require the
-				      * @p{SparsityPattern} objects they are
+				      * SparseMatrix objects require the
+				      * SparsityPattern objects they are
 				      * initialized with to be compressed, to
 				      * reduce memory requirements.
 				      */
@@ -356,13 +377,12 @@ class SparsityPattern : public Subscriptor
 
 				     /**
 				      * This function can be used as a
-				      * replacement for @ref{reinit},
-				      * subsequent calls to @ref{add}
-				      * and a final call to
-				      * @ref{close} if you know
-				      * exactly in advance the entries
-				      * that will form the matrix
-				      * sparsity pattern.
+				      * replacement for reinit(),
+				      * subsequent calls to add() and
+				      * a final call to close() if you
+				      * know exactly in advance the
+				      * entries that will form the
+				      * matrix sparsity pattern.
 				      *
 				      * The first two parameters
 				      * determine the size of the
@@ -383,19 +403,19 @@ class SparsityPattern : public Subscriptor
 				      * be equal to
 				      * @ref{n_rows}. These iterators
 				      * may be iterators of
-				      * @p{std::vector},
-				      * @p{std::list}, pointers into a
+				      * <tt>std::vector</tt>,
+				      * <tt>std::list</tt>, pointers into a
 				      * C-style array, or any other
 				      * iterator satisfying the
 				      * requirements of a forward
 				      * iterator. The objects pointed
 				      * to by these iterators
 				      * (i.e. what we get after
-				      * applying @p{operator*} or
-				      * @p{operator->} to one of these
+				      * applying <tt>operator*</tt> or
+				      * <tt>operator-></tt> to one of these
 				      * iterators) must be a container
 				      * itself that provides functions
-				      * @p{begin} and @p{end}
+				      * <tt>begin</tt> and <tt>end</tt>
 				      * designating a range of
 				      * iterators that describe the
 				      * contents of one
@@ -431,7 +451,7 @@ class SparsityPattern : public Subscriptor
 				      * following example code, which
 				      * may be used to fill a sparsity
 				      * pattern:
-				      * @begin{verbatim}
+				      * @code
 				      * std::vector<std::vector<unsigned int> > column_indices (n_rows);
 				      * for (unsigned int row=0; row<n_rows; ++row)
 				      *         // generate necessary columns in this row
@@ -440,28 +460,28 @@ class SparsityPattern : public Subscriptor
 				      * sparsity.copy_from (n_rows, n_cols,
 				      *                     column_indices.begin(),
 				      *                     column_indices.end());
-				      * @end{verbatim}
+				      * @endcode
 				      *
 				      * Note that this example works
 				      * since the iterators
 				      * dereferenced yield containers
-				      * with functions @p{begin} and
-				      * @p{end} (namely
-				      * @p{std::vector}s), and the
+				      * with functions <tt>begin</tt> and
+				      * <tt>end</tt> (namely
+				      * <tt>std::vector</tt>s), and the
 				      * inner iterators dereferenced
 				      * yield unsigned integers as
 				      * column indices. Note that we
 				      * could have replaced each of
-				      * the two @p{std::vector}
-				      * occurrences by @p{std::list},
+				      * the two <tt>std::vector</tt>
+				      * occurrences by <tt>std::list</tt>,
 				      * and the inner one by
-				      * @p{std::set} as well.
+				      * <tt>std::set</tt> as well.
 				      *
 				      * Another example would be as
 				      * follows, where we initialize a
 				      * whole matrix, not only a
 				      * sparsity pattern:
-				      * @begin{verbatim}
+				      * @code
 				      * std::vector<std::map<unsigned int,double> > entries (n_rows);
 				      * for (unsigned int row=0; row<n_rows; ++row)
 				      *         // generate necessary pairs of columns
@@ -474,7 +494,7 @@ class SparsityPattern : public Subscriptor
 				      * matrix.reinit (sparsity);
 				      * matrix.copy_from (column_indices.begin(),
 				      *                   column_indices.end());
-				      * @end{verbatim}
+				      * @endcode
 				      *
 				      * This example works because
 				      * dereferencing iterators of the
@@ -482,12 +502,12 @@ class SparsityPattern : public Subscriptor
 				      * unsigned integers and a value,
 				      * the first of which we take as
 				      * column index. As previously,
-				      * the outer @p{std::vector}
+				      * the outer <tt>std::vector</tt>
 				      * could be replaced by
-				      * @p{std::list}, and the inner
-				      * @p{std::map<unsigned int,double>}
+				      * <tt>std::list</tt>, and the inner
+				      * <tt>std::map<unsigned int,double></tt>
 				      * could be replaced by
-				      * @p{std::vector<std::pair<unsigned int,double> >},
+				      * <tt>std::vector<std::pair<unsigned int,double> ></tt>,
 				      * or a list or set of such
 				      * pairs, as they all return
 				      * iterators that point to such
@@ -503,7 +523,7 @@ class SparsityPattern : public Subscriptor
 				     /**
 				      * Copy data from an object of
 				      * type
-				      * @ref{CompressedSparsityPattern}.
+				      * CompressedSparsityPattern.
 				      * Previous content of this
 				      * object is lost, and the
 				      * sparsity pattern is in
@@ -547,35 +567,38 @@ class SparsityPattern : public Subscriptor
 
 				     /**
 				      * Return the index of the matrix
-				      * element with row number @p{i}
-				      * and column number @p{j}. If
+				      * element with row number <tt>i</tt>
+				      * and column number <tt>j</tt>. If
 				      * the matrix element is not a
 				      * nonzero one, return
-				      * @p{SparsityPattern::invalid_entry}.
+				      * SparsityPattern::invalid_entry.
 				      *
-				      * This function is usually called
-				      * by the @p{operator()} of the
-				      * @p{SparseMatrix}. It shall only be
-				      * called for compressed sparsity
-				      * patterns, since in this case
-				      * searching whether the entry
-				      * exists can be done quite fast
-				      * with a binary sort algorithm
-				      * because the column numbers are
-				      * sorted.
+				      * This function is usually
+				      * called by the
+				      * SparseMatrix::operator()(). It
+				      * may only be called for
+				      * compressed sparsity patterns,
+				      * since in this case searching
+				      * whether the entry exists can
+				      * be done quite fast with a
+				      * binary sort algorithm because
+				      * the column numbers are sorted.
 				      *
-				      * If @p{m} is the number of
-				      * entries in @p{row}, then the
+				      * If <tt>m</tt> is the number of
+				      * entries in <tt>row</tt>, then the
 				      * complexity of this function is
-				      * @p{log(m)} if the sparsity
+				      * <i>log(m)</i> if the sparsity
 				      * pattern is compressed.
+				      *
+				      * @deprecated Use
+				      * SparseMatrix::const_iterator
 				      */
     unsigned int operator() (const unsigned int i, 
 			     const unsigned int j) const;
 
 				     /**
 				      * This is the inverse operation
-				      * to @p{operator()}: given a
+				      * to operator()(): given a
 				      * global index, find out row and
 				      * column of the matrix entry to
 				      * which it belongs. The returned
@@ -586,12 +609,12 @@ class SparsityPattern : public Subscriptor
 				      * called if the sparsity pattern
 				      * is closed. The global index
 				      * must then be between zero and
-				      * @p{n_nonzero_elements}.
+				      * n_nonzero_elements().
 				      *
-				      * If @p{N} is the number of
+				      * If <tt>N</tt> is the number of
 				      * rows of this matrix, then the
 				      * complexity of this function is
-				      * @p{log(N)}.
+				      * <i>log(N)</i>.
 				      */
     std::pair<unsigned int, unsigned int>
     matrix_position (const unsigned int global_index) const;
@@ -622,11 +645,11 @@ class SparsityPattern : public Subscriptor
     
 				     /**
 				      * Print the sparsity of the matrix
-				      * in a format that @p{gnuplot} understands
+				      * in a format that <tt>gnuplot</tt> understands
 				      * and which can be used to plot the
 				      * sparsity pattern in a graphical
 				      * way. The format consists of pairs
-				      * @p{i j} of nonzero elements, each
+				      * <tt>i j</tt> of nonzero elements, each
 				      * representing one entry of this
 				      * matrix, one per line of the output
 				      * file. Indices are counted from
@@ -635,14 +658,14 @@ class SparsityPattern : public Subscriptor
 				      * way as matrices are displayed, we
 				      * print the negative of the column
 				      * index, which means that the
-				      * @p{(0,0)} element is in the top left
+				      * <tt>(0,0)</tt> element is in the top left
 				      * rather than in the bottom left
 				      * corner.
 				      *
 				      * Print the sparsity pattern in
 				      * gnuplot by setting the data style
 				      * to dots or points and use the
-				      * @p{plot} command.
+				      * <tt>plot</tt> command.
 				      */
     void print_gnuplot (std::ostream &out) const;
 
@@ -675,21 +698,21 @@ class SparsityPattern : public Subscriptor
 				     /**
 				      * Access to column number field.
 				      * Return the column number of
-				      * the @p{index}th entry in
-				      * @p{row}. Note that the if
+				      * the <tt>index</tt>th entry in
+				      * <tt>row</tt>. Note that the if
 				      * diagonal elements are
 				      * optimized, the first element
 				      * in each row is the diagonal
 				      * element,
-				      * i.e. @p{column_number(row,0)==row}.
+				      * i.e. <tt>column_number(row,0)==row</tt>.
 				      *
 				      * If the sparsity pattern is
 				      * already compressed, then
 				      * (except for the diagonal
 				      * element), the entries are
 				      * sorted by columns,
-				      * i.e. @p{column_number(row,i)}
-				      * @p{<} @p{column_number(row,i+1)}.
+				      * i.e. <tt>column_number(row,i)</tt>
+				      * <tt><</tt> <tt>column_number(row,i+1)</tt>.
 				      */
     unsigned int column_number (const unsigned int row,
 				const unsigned int index) const;
@@ -743,7 +766,7 @@ class SparsityPattern : public Subscriptor
 				      * and @p{column_number} instead.
 				      *
 				      * Though the return value is declared
-				      * @p{const}, you should be aware that it
+				      * <tt>const</tt>, you should be aware that it
 				      * may change if you call any nonconstant
 				      * function of objects which operate on
 				      * it.
@@ -760,16 +783,15 @@ class SparsityPattern : public Subscriptor
     const unsigned int * get_rowstart_indices () const;
 
 				     /**
+				      * @deprecated. Use @p{row_length}
+				      * and @p{column_number} instead.
+				      *
 				      * This is kind of an expert mode: get
 				      * access to the colnums array, but
 				      * readonly.
 				      *
-				      * Use of this function is highly
-				      * deprecated. Use @p{row_length}
-				      * and @p{column_number} instead.
-				      *
 				      * Though the return value is declared
-				      * @p{const}, you should be aware that it
+				      * <tt>const</tt>, you should be aware that it
 				      * may change if you call any nonconstant
 				      * function of objects which operate on
 				      * it.
@@ -810,12 +832,11 @@ class SparsityPattern : public Subscriptor
 
 				     /**
 				      * Read data that has previously
-				      * been written by
-				      * @p{block_write} en block from
-				      * a file. This is done using the
-				      * inverse operations to the
-				      * above function, so it is
-				      * reasonably fast because the
+				      * been written by block_write()
+				      * from a file. This is done
+				      * using the inverse operations
+				      * to the above function, so it
+				      * is reasonably fast because the
 				      * bitstream is not interpreted
 				      * except for a few numbers up
 				      * front.
@@ -837,7 +858,8 @@ class SparsityPattern : public Subscriptor
 				     /**
 				      * Determine an estimate for the
 				      * memory consumption (in bytes)
-				      * of this object.
+				      * of this object. See
+				      * MemoryConsumption.
 				      */
     unsigned int memory_consumption () const;
 
@@ -898,13 +920,13 @@ class SparsityPattern : public Subscriptor
   private:
 				     /**
 				      * Maximum number of rows that can
-				      * be stored in the @p{row_start} array.
+				      * be stored in the #rowstart array.
 				      * Since reallocation of that array
 				      * only happens if the present one is
 				      * too small, but never when the size
 				      * of this matrix structure shrinks,
-				      * @p{max_dim} might be larger than
-				      * @p{rows} and in this case @p{row_start}
+				      * #max_dim might be larger than
+				      * #rows and in this case #rowstart
 				      * has more elements than are used.
 				      */
     unsigned int max_dim;
@@ -923,8 +945,8 @@ class SparsityPattern : public Subscriptor
 
 				     /**
 				      * Size of the actually allocated array
-				      * @p{colnums}. Here, the same applies as
-				      * for the @p{rowstart} array, i.e. it
+				      * #colnums. Here, the same applies as
+				      * for the #rowstart array, i.e. it
 				      * may be larger than the actually used
 				      * part of the array.
 				      */
@@ -933,7 +955,7 @@ class SparsityPattern : public Subscriptor
 				     /**
 				      * Maximum number of elements per
 				      * row. This is set to the value
-				      * given to the @p{reinit} function
+				      * given to the reinit() function
 				      * (or to the constructor), or to
 				      * the maximum row length
 				      * computed from the vectors in
@@ -941,51 +963,60 @@ class SparsityPattern : public Subscriptor
 				      * constructors or reinit
 				      * versions are called. Its value
 				      * is more or less meaningsless
-				      * after @p{compress()} has been
+				      * after compress() has been
 				      * called.
 				      */
     unsigned int max_row_length;
 
 				     /**
-				      * Array which hold for each row which
-				      * is the first element in @p{colnums}
-				      * belonging to that row. Note that
-				      * the size of the array is one larger
-				      * than the number of rows, because
-				      * the last element is used for
-				      * @p{row=rows}, i.e. the row past the
-				      * last used one. The value of
-				      * @p{rowstart[rows]} equals the index
-				      * of the element past the end in
-				      * @p{colnums}; this way, we are able to
-				      * write loops like
-				      * @p{for (i=rowstart[k]; i<rowstart[k+1]; ++i)}
+				      * Array which hold for each row
+				      * which is the first element in
+				      * #colnums belonging to that
+				      * row. Note that the size of the
+				      * array is one larger than the
+				      * number of rows, because the
+				      * last element is used for
+				      * <tt>row</tt>=#rows, i.e. the
+				      * row past the last used
+				      * one. The value of
+				      * #rowstart[#rows]} equals the
+				      * index of the element past the
+				      * end in #colnums; this way, we
+				      * are able to write loops like
+				      * <tt>for (i=rowstart[k];
+				      * i<rowstart[k+1]; ++i)</tt>
 				      * also for the last row.
 				      *
 				      * Note that the actual size of the
 				      * allocated memory may be larger than
 				      * the region that is used. The actual
 				      * number of elements that was allocated
-				      * is stored in @p{max_dim}.
+				      * is stored in #max_dim.
 				      */
     unsigned int *rowstart;
 
 				     /**
-				      * Array of column numbers. In this array,
-				      * we store for each non-zero element its
-				      * column number. The column numbers for
-				      * the elements in row @p{r} are stored
-				      * within the index range
-				      * @p{rowstart[r]...rowstart[r+1]}. Therefore
-				      * to find out whether a given element
-				      * @p{(r,c)} exists, we have to check
-				      * whether the column number @p{c} exists in
-				      * the abovementioned range within this
-				      * array. If it exists, say at position
-				      * @p{p} within this array, the value of
-				      * the respective element in the sparse
-				      * matrix will also be at position @p{p}
-				      * of the values array of that class.
+				      * Array of column numbers. In
+				      * this array, we store for each
+				      * non-zero element its column
+				      * number. The column numbers for
+				      * the elements in row <i>r</i>
+				      * are stored within the index
+				      * range
+				      * #rowstart[<i>r</i>]...#rowstart[<i>r+1</i>]. Therefore
+				      * to find out whether a given
+				      * element (<i>r,c</i>) exists,
+				      * we have to check whether the
+				      * column number <i>c</i> exists
+				      * in the abovementioned range
+				      * within this array. If it
+				      * exists, say at position
+				      * <i>p</i> within this array,
+				      * the value of the respective
+				      * element in the sparse matrix
+				      * will also be at position
+				      * <i>p</i> of the values array
+				      * of that class.
 				      *
 				      * At the beginning, all elements
 				      * of this array are set to
@@ -1016,8 +1047,9 @@ class SparsityPattern : public Subscriptor
     unsigned int *colnums;
 
 				     /**
-				      * Store whether the @p{compress} function
-				      * was called for this object.
+				      * Store whether the compress()
+				      * function was called for this
+				      * object.
 				      */
     bool compressed;
 
@@ -1029,7 +1061,7 @@ class SparsityPattern : public Subscriptor
     
 				     /**
 				      * Optimized replacement for
-				      * @p{std::lower_bound} for
+				      * <tt>std::lower_bound</tt> for
 				      * searching within the range of
 				      * column indices. Slashes
 				      * execution time by
@@ -1053,7 +1085,7 @@ class SparsityPattern : public Subscriptor
 				      * Helper function to get the
 				      * column index from a
 				      * dereferenced iterator in the
-				      * @ref{copy_from} function, if
+				      * copy_from() function, if
 				      * the inner iterator type points
 				      * to plain unsigned integers.
 				      */
@@ -1065,7 +1097,7 @@ class SparsityPattern : public Subscriptor
 				      * Helper function to get the
 				      * column index from a
 				      * dereferenced iterator in the
-				      * @ref{copy_from} function, if
+				      * copy_from() function, if
 				      * the inner iterator type points
 				      * to pairs of unsigned integers
 				      * and some other value.
@@ -1079,7 +1111,7 @@ class SparsityPattern : public Subscriptor
 				      * for certain types of
 				      * containers that make the first
 				      * element of the pair constant
-				      * (such as @p{std::map}).
+				      * (such as <tt>std::map</tt>).
 				      */
     template <typename value>
     unsigned int
@@ -1096,6 +1128,7 @@ class SparsityPattern : public Subscriptor
 /*@}*/
 /*---------------------- Inline functions -----------------------------------*/
 
+/// @if NoDoc
 
 inline
 const unsigned int *
@@ -1363,5 +1396,6 @@ SparsityPattern::copy_from (const unsigned int    n_rows,
   compress ();
 }
 
+/// @endif
 
 #endif
-- 
2.39.5