From 2b4de69e3c77e4a6389a2426727c2d32bc7d8379 Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Wed, 23 Oct 2019 07:41:42 -0600
Subject: [PATCH] Provide a link to the geometry paper.

---
 doc/doxygen/headers/glossary.h  | 26 ++++++++++++++++++++++++++
 doc/doxygen/headers/manifold.h  |  3 +++
 include/deal.II/grid/manifold.h |  6 +++++-
 3 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/doc/doxygen/headers/glossary.h b/doc/doxygen/headers/glossary.h
index 2fcb74a894..49ebf4cd13 100644
--- a/doc/doxygen/headers/glossary.h
+++ b/doc/doxygen/headers/glossary.h
@@ -1033,6 +1033,31 @@
  * </dd>
  *
  *
+ * <dt class="glossary">@anchor geometry_paper <b>geometry paper</b></dt>
+ * <dd>The "geometry paper" is a paper by L. Heltai, W. Bangerth, M. Kronbichler,
+ * and A. Mola, titled
+ * "Using exact geometry information in finite element computations", that
+ * describes how deal.II describes the geometry of domains. In particular,
+ * it discusses the algorithmic foundations on which the Manifold class
+ * is based, and what kind of information it needs to provide for mesh
+ * refinement, the computation of normal vectors, and the many other places
+ * where geometry enters into finite element computations.
+ *
+ * The paper is currently available on arXiv at https://arxiv.org/abs/1910.09824 .
+ * The full reference for this paper is as follows:
+ * @code{.bib}
+@misc{heltai2019using,
+    title={Using exact geometry information in finite element computations},
+    author={Luca Heltai and Wolfgang Bangerth and Martin Kronbichler and Andrea Mola},
+    year={2019},
+    eprint={1910.09824},
+    archivePrefix={arXiv},
+    primaryClass={math.NA}
+}
+ * @endcode
+ * </dd>
+ *
+ *
  * <dt class="glossary">@anchor GlossGhostCell <b>Ghost cells</b></dt>
  * <dd>
  * If a mesh is distributed across multiple MPI processes using the
@@ -1133,6 +1158,7 @@
  * used.
  * </dd>
  *
+ *
  * <dt class="glossary">@anchor hp_paper <b>%hp paper</b></dt>
  * <dd>The "hp paper" is a paper by W. Bangerth and O. Kayser-Herold, titled
  * "Data Structures and Requirements for hp Finite Element Software", that
diff --git a/doc/doxygen/headers/manifold.h b/doc/doxygen/headers/manifold.h
index e7912b49d6..16cf268e28 100644
--- a/doc/doxygen/headers/manifold.h
+++ b/doc/doxygen/headers/manifold.h
@@ -74,6 +74,9 @@
  *   using high order mappings.
  *
  * </ul>
+ * Many other examples, as well as much theoretical underpinning for the
+ * implementation in deal.II, is provided in the
+ * @ref GlossGeometryPaper "geometry paper".
  *
  * In deal.II, a Manifold is seen as a collection of points, together
  * with a notion of distance between points (on the manifold). New
diff --git a/include/deal.II/grid/manifold.h b/include/deal.II/grid/manifold.h
index fa83781cd6..34a1fd3dd8 100644
--- a/include/deal.II/grid/manifold.h
+++ b/include/deal.II/grid/manifold.h
@@ -163,6 +163,8 @@ namespace Manifolds
                                  const bool with_interpolation = false);
 } // namespace Manifolds
 
+
+
 /**
  * Manifolds are used to describe the geometry of boundaries of domains as
  * well as the geometry of the interior. Manifold objects are therefore
@@ -172,7 +174,9 @@ namespace Manifolds
  *
  * Manifolds are best understood by using the language of differential
  * geometry, but their common uses can be easily described simply through
- * examples.
+ * examples. An exhaustive discussion of how, where, and why this class
+ * is used is provided in the
+ * @ref GlossGeometryPaper "geometry paper".
  *
  *
  * <h3>Common use case: Creating a new vertex</h3>
-- 
2.39.5