From 4c7243c1fb39f45832983c8f726c599f82394b05 Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Wed, 9 Jul 2014 17:10:31 +0000
Subject: [PATCH] Minor edits.

git-svn-id: https://svn.dealii.org/branches/branch_manifold_id_intermediate@33127 0785d39b-7218-0410-832d-ea1e28bc413d
---
 deal.II/doc/doxygen/headers/manifold.h | 58 ++++++++++++++------------
 1 file changed, 32 insertions(+), 26 deletions(-)

diff --git a/deal.II/doc/doxygen/headers/manifold.h b/deal.II/doc/doxygen/headers/manifold.h
index f03fd15208..ac21c54520 100644
--- a/deal.II/doc/doxygen/headers/manifold.h
+++ b/deal.II/doc/doxygen/headers/manifold.h
@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------
 // $Id: manifold.h 30130 2013-07-23 13:01:18Z heltai $
 //
-// Copyright (C) 2003 - 2013 by the deal.II authors
+// Copyright (C) 2003 - 2014 by the deal.II authors
 //
 // This file is part of the deal.II library.
 //
@@ -16,34 +16,37 @@
 
 
 /**
- * @defgroup manifold Boundary description for triangulations
+ * @defgroup manifold Manifold description for triangulations
  *
  * The classes in this module are concerned with the description of the
- * manifold of a domain in which a Triangulation lives. This manifold
- * description is necessary in two contexts:
+ * manifold in which the domain that a Triangulation describes lives. This
+ * manifold description is necessary in two contexts:
+ *
  * <ul>
  *
  *   <li> Mesh refinement: Whenever a cell is refined, it is necessary
  *   to introduce some new vertices in the Triangulation. In the
  *   simplest case, one assumes that the objects that make up the
  *   Triangulation are straight line segments, a bi-linear surface or
- *   a tri-linear volume, the next vertex is simply put into the
+ *   a tri-linear volume. The next vertex is then simply put into the
  *   middle of the old ones. This is the default behavior of the
  *   Triangulation class, and is described by the FlatManifold class.
  *
- *   On the other hand, if one deals with curved geometries, or
- *   geometries which require a denser refinement in some direction,
- *   this is not the appropriate thing to do. The classes derived from
- *   the Manifold base class therefore describe the geometry of a
- *   domain. One can then attach an object of a class derived from
- *   this base class to the Triangulation object using the
- *   Triangulation::set_manifold() function, and the Triangulation
- *   will ask the manifold object where a new vertex should be located
- *   upon mesh refinement. Several classes already exist to support
- *   the most common geometries, e.g., CylinderManifold, or
- *   PolarManifold, which represent respectively the geometry obtained
- *   when describing your space in cylindrical coordintes or in polar
- *   coordinates.
+ *   On the other hand, if one deals with curved geometries, or geometries
+ *   which require a denser refinement in some direction, this is not the
+ *   appropriate thing to do. The classes derived from the Manifold base class
+ *   therefore describe the geometry of a domain. One can then attach an
+ *   object of a class derived from this base class to the Triangulation
+ *   object using the Triangulation::set_manifold() function associating it
+ *   with a manifold id (see types::manifold_id), use this manifold id on the
+ *   cells, faces or edges of the triangulation that should be described by
+ *   this manifold using the TriaAccessor::set_manifold_id() function, and
+ *   then the Triangulation will ask the manifold object where a new vertex to
+ *   be located on a cell, face or edge so attributed should be located upon
+ *   mesh refinement. Several classes already exist to support the most common
+ *   geometries, e.g., CylinderManifold, or PolarManifold, which represent
+ *   respectively the geometry obtained when describing your space in
+ *   cylindrical coordintes or in polar coordinates.
  *
  *   <li> Integration: When using higher order finite element methods, it is
  *   often necessary to compute cell terms (like cell contributions to the
@@ -57,14 +60,17 @@
  *
  * </ul>
  *
- * In deal.II, a Manifold is seen as a collection of points, together
- * with a notion of distance between points (on the manifold). New
- * points are obtained by providing a local coordinate system on the
- * manifold, identifying existing points in the local coordinate
- * system (pulling them back using the local map to obtain their local
- * coordinates), find the new point in the local coordinate system by
- * weighted sums of the existing points, and transforming back the
- * point in the real space (pushing it forward using the local map).
+ * In deal.II, a Manifold is seen as a collection of points, together with a
+ * notion of distance between points (on the manifold). New points are
+ * typically obtained by providing a local coordinate system on the manifold,
+ * identifying existing points in the local coordinate system (pulling them
+ * back using the local map to obtain their local coordinates), find the new
+ * point in the local coordinate system by weighted sums of the existing
+ * points, and transforming back the point in the real space (pushing it
+ * forward using the local map).  (However, this pull back and push forward
+ * only happens in classes that implement manifolds, and your own class can
+ * also choose other ways of figuring out where a new point should be
+ * located.)
  *
  * While this process is non trivial in most cases of interest, for
  * most of the trivial geometries, like cylinders, spheres or shells,
-- 
2.39.5