From e3bc22b104412eb921d809dc22f21ad72bd451f0 Mon Sep 17 00:00:00 2001
From: Monique Teillaud <Monique.Teillaud@inria.fr>
Date: Fri, 7 Sep 2018 15:36:49 +0200
Subject: [PATCH] small fixes, new comments and todos

---
 .../Periodic_4_hyperbolic_triangulation_2.txt | 159 +++++++-----------
 1 file changed, 62 insertions(+), 97 deletions(-)

diff --git a/Periodic_4_hyperbolic_triangulation_2/doc/Periodic_4_hyperbolic_triangulation_2/Periodic_4_hyperbolic_triangulation_2.txt b/Periodic_4_hyperbolic_triangulation_2/doc/Periodic_4_hyperbolic_triangulation_2/Periodic_4_hyperbolic_triangulation_2.txt
index 5f6cacb236f..96514c52983 100644
--- a/Periodic_4_hyperbolic_triangulation_2/doc/Periodic_4_hyperbolic_triangulation_2/Periodic_4_hyperbolic_triangulation_2.txt
+++ b/Periodic_4_hyperbolic_triangulation_2/doc/Periodic_4_hyperbolic_triangulation_2/Periodic_4_hyperbolic_triangulation_2.txt
@@ -14,7 +14,7 @@ namespace CGAL {
 \image html new-triangulation-350px.png 
 
 This package allows to compute Delaunay triangulations of the Bolza surface, which is the
-most symmetric surface of genus 2. The Bolza surface is a hyperbolic closed compact orientable surface of genus 2. 
+most symmetric surface of genus 2. The Bolza surface is a hyperbolic closed compact orientable surface. 
 
 A triangulation is defined as a <i>simplicial complex</i>, i.e.:
 <ul>
@@ -31,8 +31,13 @@ A triangulations of the Bolza surface can be seen as a periodic triangulation of
 
 Let \f$\mathbb{H}^2\f$ denote the hyperbolic plane, represented in the Poincaré disk model.
 Consider the regular hyperbolic octagon \f$ \mathcal D_O \f$ centered at the origin, with 
-all angles equal to \f$ \pi/4\f$. Note that \f$\mathcal D_O\f$ is unique up to rotation, and cannot
-be scaled, since this operation would change its angle sum. 
+all angles equal to \f$ \pi/4\f$ that is shown in
+\cgalFigureRef{P4HTriangulationOctagonId} - Left.
+Note that \f$\mathcal D_O\f$ is unique up to rotation, and cannot
+be scaled, since this operation would change its angle sum.
+\cgalModifBegin 
+shouldn't it be more simply: its angles ?
+\cgalModifEnd
 Now, consider the 
 four hyperbolic translations \f$ a,b,c,d\f$ with their respective inverses \f$\overline{a}, 
 \overline{b}, \overline{c}, \overline{d}\f$ that identify the opposite sides of 
@@ -40,7 +45,7 @@ four hyperbolic translations \f$ a,b,c,d\f$ with their respective inverses \f$\o
 See \cgalFigureRef{P4HTriangulationOctagonId} - Left. 
 
 The four translations 
-\f$a, b, c, d\f$ generate a discrete group of orientation-preserving isometries, with 
+\f$a, b, c, d\f$ generate a (non-commutative) discrete group of orientation-preserving isometries, with 
 finite presentation
 \f[ \mathcal{G} = \left< a,b,c,d \; \bigg| \; 
     abcd\overline{a}\overline{b}\overline{c}\overline{d} \right>. \f]
@@ -104,17 +109,11 @@ D\f$ under the action of \f$\mathcal G\f$.
 
 \section P4HT2_representation Representation 
 
-\cgalModifBegin 
-  begin: ? 
-\cgalModifEnd
 When there is no risk
 of confusion, the same notation will be used for a point on the
 surface \f$\mathcal M\f$ and its representative in \f$\mathcal
 D\f$. Similarly, \f$\mathcal{P}\f$ denotes both a set of points on the
 surface and the set of their representatives in \f$\mathcal D\f$. 
-\cgalModifBegin 
-  end: ? 
-\cgalModifEnd
 
 The Delaunay triangulation of \f$\mathcal{M}\f$ defined by a point set
 \f$\mathcal{P}\f$ is defined as the projection by \f$\pi\f$ of the
@@ -128,7 +127,7 @@ orbits of points, all faces of the Delaunay triangulation of
 \f$\mathcal{G}\f$ project by \f$\pi\f$ onto the same face on the
 surface \f$\mathcal{M}\f$; the data structure stores a unique
 <i>canonical</i> representative of each orbit, which has at least one
-vertex in \f$\mathcal D\f$. Some faces have vertices both inside and
+vertex in \f$\mathcal D\f$. Some canonical faces have vertices both inside and
 outside \f$\mathcal D\f$. Such faces can be uniquely specified by
 three pairs of points in \f$\mathcal D\f$ and (reduced) translations
 of \f$\mathcal{G}\f$; points in the original domain are paired with
@@ -150,10 +149,10 @@ three translations that are paired with the point in each vertex. See
 More precisely, the translations are elements of the subset
 \f$\mathcal N\f$ of \f$\mathcal G\f$ for which the image of
 \f$\mathcal D_O\f$ has at least one vertex in common with
-\f$\mathcal D_O\f$. 
-See \cgalFigureRef{P4HTriangulationCanonicalRepExample}.  
-We consider the images of \f$\mathcal D_O\f$ under translations of
-\f$\mathcal N\f$ to be ordered counterclockwise around
+\f$\mathcal D_O\f$. These images of  \f$\mathcal D_O\f$ by
+translations in \f$\mathcal N\f$ are shaded in 
+\cgalFigureRef{P4HTriangulationCanonicalRepExample}; we consider them
+to be ordered counterclockwise around
 \f$\mathcal D_O\f$, arbitrarily starting with the one corresponding to
 translation \f$abcd\f$.  The canonical representative in
 \f$\mathbb H^2\f$ of a face on \f$\mathcal M\f$ is such that 
@@ -193,7 +192,7 @@ A periodic hyperbolic triangulation is said to be `valid` if and only if
         complex. </li>
 </ol>
 
-Some point sets do not admit a triangulation of \f$\mathcal M\f$. For
+Some point sets do not define a valid triangulation of \f$\mathcal M\f$. For
 instance, a single point does not define a valid triangulation of
 \f$\mathcal M\f$, as the induced subdivision would not be a simplicial
 complex. Another example is shown in
@@ -218,7 +217,7 @@ projection by \f$\pi\f$ of the Delaunay triangulation of \f$\mathcal{G}
 \f$\mathcal M\f$ is a simplicial 
 complex for any set of input points \f$\mathcal{P}\f$
 \cgalCite{cgal:btv-dtosl-16}. 
-See \cgalFigureRef{P4HTriangulationDummyPoints}
+See \cgalFigureRef{P4HTriangulationDummyPoints}. 
 
 \cgalFigureAnchor{P4HTriangulationDummyPoints}
 <center>
@@ -239,14 +238,6 @@ If the set of input points is not sufficiently large, or if the points
 are not well-distributed on the surface, then the final triangulation will contain the
 dummy points necessary to guarantee that the triangulation is a simplicial complex. 
 
-\cgalModifBegin 
-  tout ce qui concerne les experiences pourrait eventuellement
-  descendre dans la sec Performance [modified, texte proposé ci-dessous]
-
-See \ref P4HT2_Performance for experiments showing the average number of random points
-needed in order to remove all dummy points from the triangulation.  
-\cgalModifEnd
-
 
 \section P4HT2_design Software Design 
 
@@ -254,8 +245,8 @@ needed in order to remove all dummy points from the triangulation.
   TODO enlever les redondances dans cette section et améliorer la structure [modified]
 \cgalModifEnd 
 
-The main class of this package is `Periodic_4_hyperbolic_Delaunay_triangulation_2`, and
-it implements Delaunay triangulations of the Bolza surface \f$\mathcal M\f$. The prefix 
+The main class of this package is `Periodic_4_hyperbolic_Delaunay_triangulation_2`, which
+implements Delaunay triangulations of the Bolza surface \f$\mathcal M\f$. The prefix 
 "Periodic_4" emphasizes that the triangulation in the universal covering \f$\mathbb H^2\f$ 
 is periodic in the four directions defined by the hyperbolic translations \f$ a,b,c\f$, 
 and \f$d\f$.
@@ -270,7 +261,7 @@ point sets (i.e., more than three co-circular points) are handled with symbolic
 The implementation is fully dynamic, supporting both point insertion and vertex removal.
 However, a vertex can be removed only if the triangulation remains valid (as defined above).
 
-The main class `Periodic_4_hyperbolic_Delaunay_triangulation_2` provides high-level geometric 
+The class `Periodic_4_hyperbolic_Delaunay_triangulation_2` provides high-level geometric 
 functionality specific to Delaunay triangulations, such as point insertion and vertex removal, 
 the side-of-circle test, finding the conflicting region of a given point, and dual functions. 
 It inherits from a base class called `Periodic_4_hyperbolic_triangulation_2` that provides 
@@ -279,36 +270,35 @@ and access functions, but supports neither point insertion nor vertex removal.
 
 Both classes `Periodic_4_hyperbolic_triangulation_2` and `Periodic_4_hyperbolic_Delaunay_triangulation_2`
 require two template parameters that reflect the separation between the geometric and combinatorial
-structure of the triangulation:
+structures of the triangulation:
 
 - a <B>geometric traits</B> class, which provides all objects, predicates, and constructions 
-necessary for the computation of Delaunay triangulations of the Bolza surface. It also provides 
-the hyperbolic translations generating the group \f$\mathcal G\f$ and  the translations in the 
-set \f$\mathcal N\f$. This parameter must meet the requirements described in the concept
-`Periodic_4HyperbolicDelaunayTriangulationTraits_2`. For more details, see 
+necessary for the computation of Delaunay triangulations of the Bolza surface.For more details, see 
 Section \ref P4HT2_traits. 
 
 - a <B>triangulation data structure</B> class, which encodes the combinatorial structure of 
-the triangulation. This parameter must meet the requirements described in the concept 
-`TriangulationDataStructure_2`, and for the purposes of this package is described in 
-Section \ref P4HT2_datastructure.
+the triangulation. See Section \ref P4HT2_datastructure.
 
 \subsection P4HT2_traits The Geometric Traits Parameter 
 
 The geometric traits class must fulfill the requirements described in the concept
 `Periodic_4HyperbolicDelaunayTriangulationTraits_2`. It must provide all necessary objects, 
-predicates, and constructions, as well as the hyperbolic translations of the group 
-\f$\mathcal G\f$.
+predicates, and constructions,
+
+\cgalModifBegin
+TODO corriger la fin de la phrase suite aux discussions 
+"as well as the hyperbolic translations of the group 
+\f$\mathcal G\f$."
+\cgalModifEnd
 
 A model for the concept `Periodic_4HyperbolicDelaunayTriangulationTraits_2` offered by this
 package is the class `Periodic_4_hyperbolic_Delaunay_triangulation_traits_2`. The class requires 
 two template parameters:
 \cgalModifBegin 
-  1- BUG dans le ref manual : les paramètres templates ne sont pas
-  documentes. TODO fix [modified]
+TODO un seul template est documente - enlever le concept
+translations
+\cgalModifEnd
 
-  2- il y a une raison pour ne pas mettre Core-expr comme default ? [non; c'est ajouté]
-\cgalModifEnd 
 <ul>
 	<li> A `Kernel` with a `number type` that guarantees exact computations on algebraic numbers 
   with nested square roots. The default value for this parameter is `CGAL::Cartesian<CORE::Expr>`.</li>
@@ -316,45 +306,16 @@ two template parameters:
   be the same as the `number type` of the `Kernel`. This template parameter defaults to the class
   `Hyperbolic_octagon_translation<Kernel::NT>`. </li>
 </ul>
-\cgalModifBegin 
-  D'habitude on n'impose pas un parametre template dans un
-  concept. Dans le concept on dit seulement que le NT doit être fourni
-  comme nested type. En pratique dans le modele il y a un template
-  parameter. Dans ton ref manual c'est en fait ce que tu fais, tu ne
-  demandes pas le template. TOD rendre tout ca coherent. 
-
-  [modified]
-\cgalModifEnd 
-
 
 \cgalModifBegin 
-  If the field type used in `Kernel` provides exact operations with algebraic numbers involving
-  nested square roots, then the traits class provides exact predicates
-  and exact constructions.
-
-  sinon, tout le code plante, c'est-ce pas ? ce n'est pas vraiment ce qu'on veut... de
-  plus c'est contradictoire avec ce qui est  écrit plus haut : A
-  `Kernel` with a `number type` that guarantees 
-  exact computations on algebraic numbers with nested square
-  roots. TODO rendre le texte coherent. 
-
-  [d'après discussion, à enlever]
-\cgalModifEnd 
-
-\cgalModifBegin 
-  In addition, inexact constructions using `double` number type are also provided.
-
-  pour quoi faire ? 
-  [En fait, ce n'est pas documenté. Je propose d'enlever cette phrase.]
-\cgalModifEnd 
-
+TODO reflechir NT vs FT et assurer la coherence 
+\cgalModifEnd
 
 \subsection P4HT2_datastructure The Triangulation Data Structure Parameter 
 
 The triangulation data structure class is the second template parameter of the periodic hyperbolic
 triangulation classes. It is a container for the faces and vertices and maintains
-incidence and adjacency relations. For details, see Chapter 
-\ref Chapter_2D_Triangulation_Data_Structure. 
+incidence and adjacency relations. 
 This parameter must meet the requirements described in the concept `TriangulationDataStructure_2`, 
 for which \cgal offers the model `Triangulation_data_structure_2`. 
 This model is itself parameterized by a vertex 
@@ -368,44 +329,52 @@ The default value for the triangulation data structure parameter in the hyperbol
 triangulation classes is 
 `Triangulation_data_structure_2< Periodic_4_hyperbolic_triangulation_face_base_2<Traits>, Periodic_4_hyperbolic_triangulation_vertex_base_2<Traits> >`, 
 where `Traits` is a model of `Periodic_4HyperbolicDelaunayTriangulationTraits_2`.
+\cgalModifBegin 
+est-ce que c'est vraiment le meme concept de traits pour les deux hyperbolic periodic 
+triangulation classes ? a priori non... ne parler que de la classe
+Delaunay corrigerait le probleme. 
+\cgalModifEnd
 
 \section P4HT2_examples Example
 
-This example shows the initialization of a periodic hyperbolic 2D Delaunay triangulation,  the
-insertion of random points uniformly distributed in the unit disk for the Euclidean metric, and the
-properties of the triangulation after the insertion. It uses the default parameter of the
-`Periodic_4_hyperbolic_Delaunay_triangulation_2` class for the triangulation data structure.
-
 Most functionalities of periodic hyperbolic triangulations are similar
 to those of Euclidean 2D triangulations. 
-
-\cgalModifBegin
 We refer the reader to selected examples of the \ref Chapter_2D_Triangulations "2D Triangulation" package:
 <ul>
   <li> \ref Subsection_2D_Triangulations_Voronoi
   <li> \ref Triangulation_2AddingColors
 </ul>
+\cgalModifBegin 
+TODO corriger le premier ref pour enlever le mot Example: pour assurer
+la coherence avec le deuxieme ref
 \cgalModifEnd
 
-\cgalModifBegin
-TODO mettre le lien précis, envoyer directement sur la sec examples de T2 
-
-[modified: added two links; implement here instead?]
-\cgalModifEnd
+The example below shows the initialization of a periodic hyperbolic 2D Delaunay triangulation,  the
+insertion of random points uniformly distributed in the unit disk for the Euclidean metric, and the
+properties of the triangulation after the insertion. It uses the default parameter of the
+`Periodic_4_hyperbolic_Delaunay_triangulation_2` class for the triangulation data structure.
 
 \cgalExample{Periodic_4_hyperbolic_triangulation_2/p4ht2_example_insertion.cpp}
 
+\cgalModifBegin 
+TODO ajouter dans le code 1 ou 2 commentaires bien places qui
+rappellent que les dummy points sont enleves automatiquement (si
+possible) quand on insere un "range" de points mais qu'ils ne le sont
+pas par defaut quand n insere les points un par un.
+Illustrer aussi le booleen qui permet de choisir de les enlever ?
+\cgalModifEnd
+
 
 \section P4HT2_Performance Performance
 
-We perform tests to measure the insertion execution time of our implementation against existing
-\cgal code. We generate random points, uniformly distributed in the unit disk with respect to
-the Euclidean metric. From the generated points, we select 1 million points that lie in the original 
+We have measured the insertion execution time of our implementation
+against other \cgal triangulations. Random points, uniformly distributed in the unit disk with respect to
+the Euclidean metric, are generated. From these generated points, we select 1 million points that lie in the original 
 octagon \f$\mathcal D_O\f$. We insert the same set of points in three triangulations:
 <ul>
   <li> a periodic hyperbolic Delaunay triangulation with `CORE::Expr` as `number type`;
-  <li> a non-periodic Euclidean Delaunay triangulation with `CORE::Expr` as `number type`;
-  <li> a non-periodic Euclidean Delaunay triangulation with `double` as `number_type`. 
+  <li> a (non-periodic) Euclidean Delaunay triangulation with `CORE::Expr` as `number type`;
+  <li> a (non-periodic) Euclidean Delaunay triangulation with `double` as `number_type`. 
 </ul>
 We report results averaged over 10 executions of this experiment in \ref Table_1 "Table 1" below. The experiments
 have been executed on two machines:
@@ -425,13 +394,10 @@ have been executed on two machines:
 </table>
 </center>
 
-
-\cgalModifBegin
-Another experiment we have conducted shows that, on average, all dummy points are removed 
+Another experiment shows that, on average, all dummy points are removed 
 from the triangulation with the insertion of less than 200 random points uniformly distributed 
 in the unit disk with respect to the Euclidean metric \cgalCite{cgal:it-idtbs-17}. 
-
-The experiment we conduct is the following: We start with an empty triangulation of the Bolza 
+We start with an empty triangulation of the Bolza 
 surface (i.e., initialized with only the dummy points), and we start inserting random points 
 one by one. After each insertion, the unnecessary dummy points (if any) are removed from the 
 triangulation. As soon as the last dummy point has been removed, we stop the process and record 
@@ -448,7 +414,6 @@ the number of random points inserted. Results are shown in \cgalFigureRef{P4HDum
   points needed to remove all dummy points was 23, the maximum 188, and on average 64 random 
   points were needed.
 \cgalFigureCaptionEnd
-\cgalModifEnd
 
 
 \section P4HT2_Design Design and Implementation History