removed all notes about flattening from both user and ref manuals

Weights/doc/Weights/PackageDescription.txt

@@ -96,7 +96,7 @@ being the power parameter.
 
 Here, `q` is a query point and the points `p0`, `p1`, and `p2` are ordered.
 
-This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Flattening)
+This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Coplanarity)
 while alternative formulations are explained in \ref Weights_Implementation.
 
 \cgalFigureBegin{three_point_family_weight, three_point_family.svg}
@@ -133,7 +133,7 @@ with notations shown in the figure below.
 
 Here, `q` is a query point and the points `p0`, `p1`, and `p2` are ordered.
 
-This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Flattening)
+This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Coplanarity)
 while alternative formulations are explained in \ref Weights_Implementation.
 
 \cgalFigureBegin{wachspress_weight, wachspress.svg}
@@ -198,7 +198,7 @@ The \f$\pm\f$ sign is a sign of the weight that depends on the configuration.
 
 Here, `q` is a query point and the points `p0`, `p1`, and `p2` are ordered.
 
-This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Flattening)
+This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Coplanarity)
 while alternative formulations are explained in \ref Weights_Implementation.
 
 \cgalFigureBegin{mean_value_weight, mean_value.svg}
@@ -262,7 +262,7 @@ with notations shown in the figure below.
 
 Here, `q` is a query point and the points `p0`, `p1`, and `p2` are ordered.
 
-This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Flattening)
+This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Coplanarity)
 while alternative formulations are explained in \ref Weights_Implementation.
 
 \cgalFigureBegin{discrete_harmonic_weight, discrete_harmonic.svg}

Weights/doc/Weights/Weights.txt

@@ -93,40 +93,25 @@ The parameter `traits` with a traits class can be omitted for all functions and
 if it can be deduced from the input point type.
 
 Several weights in this package have different implementations. One reason to have it is
-explained in section about \ref Weights_Implementation_Flattening. Another reason is that
+explained in section about \ref Weights_Implementation_Coplanarity. Another reason is that
 in different communities the same weights are named and computed differently. If one searches
 for these weights, one needs to know all their alternative names, which is tiresome. We provide
 the most common names and implementations of these weights.
 
 
-\subsection Weights_Implementation_Flattening Coplanarity
+\subsection Weights_Implementation_Coplanarity Coplanarity
-
-\cgalFigureBegin{flattening, flattening.svg}
-  The non-planar configuration (top) is flattened to the planar configuration (bottom).
-\cgalFigureEnd
 
 When computing weights for a query point \f$q\f$ with respect to its neighbors
 \f$p_0\f$, \f$p_1\f$, and \f$p_2\f$, the local configuration is a quadrilateral
 [\f$p_0\f$, \f$p_1\f$, \f$p_2\f$, \f$q\f$] or two connected triangles [\f$q\f$, \f$p_0\f$, \f$p_1\f$]
 and [\f$q\f$, \f$p_1\f$, \f$p_2\f$]. When working in 3D, these triangles are not
 necessarily coplanar, in other words, they do not belong to the same common plane.
-When they are not coplanar, they can be made coplanar through the process called *flattening* (see the Figure above),
-however the latter introduces a distortion because the weights are computed with respect to the
-flattened configuration rather than to the original non-flat configuration.
 
 Certain weights in this package support only coplanar configurations, while other weights support both.
 The weights, which support non-coplanar configurations, provide the corresponding overloads with 3D points,
 while other weights accept only 2D point types. For example, \ref PkgWeightsRefCotangentWeights "cotangent weights"
-support both flat and non-flat configurations, while \ref PkgWeightsRefDiscreteHarmonicWeights "discrete harmonic weights"
+support both coplanar and non-coplanar configurations, while \ref PkgWeightsRefDiscreteHarmonicWeights "discrete harmonic weights"
-support only flat configurations.
+support only coplanar configurations.
-
-If you still want to compute the coplanar weights, such as discrete harmonic weights, in 3D,
-you can either provide your own way to flatten the 3D configuration or you can use one of the projection
-traits available in CGAL as the last parameter to the weight function (see \ref Weights_Examples_ProjectionTraits
-for example, where the common plane is a horizontal plane). If the two triangles are not exactly coplanar,
-this projection traits will introduce an error, but this error is proportional to how much these triangles
-differ from the common plane. If the non-coplanarity difference between them is due to noise or inexact computations,
-it won't affect much the final computation result.
 
 
 \subsection Weights_Implementation_Boundaries Boundaries
@@ -179,22 +164,10 @@ The used type of barycentric weights is `Wachspress_weights_2`.
 \cgalExample{Weights/coordinates_multiple_queries.cpp}
 
 
-\subsection Weights_Examples_ProjectionTraits Computing 2D Weights in 3D
-
-If you have a 2D polygon in 3D plane that is not an XY plane, you can still compute
-the 2D weights, however you need to provide a special projection traits class.
-The common plane that is used in this example is projectable to the XY plane. We first
-compute `Mean_value_weights_2` for a 3D polygon in this plane. We then also show how to use
-the projection traits to compute the \ref PkgWeightsRefWachspressWeights "2D Wachspress weight"
-for 3D points, which are not strictly coplanar.
-
-\cgalExample{Weights/projection_traits.cpp}
-
-
 \subsection Weights_Examples_CustomTraits Weights with Custom Traits
 
-As you could see from the previous example, it is possible to provide your own traits
+As you could see from the reference manual, it is possible to provide your own traits class
-class with basic geometric objects, constructions, and predicates required by the algorithm.
+with basic geometric objects, constructions, and predicates to the weight functions.
 All weights in this \cgal component are models of the `AnalyticWeightTraits_2` and `AnalyticWeightTraits_3`
 concepts. However, many weights do not require all objects from these concepts. This example shows that
 the inverse distance weight, for instance, requires only the squared distance object which is specified

Weights/doc/Weights/examples.txt

@@ -3,7 +3,6 @@
 \example Weights/coordinates_one_query.cpp
 \example Weights/coordinates_multiple_queries.cpp
 \example Weights/weighted_laplacian.cpp
-\example Weights/projection_traits.cpp
 \example Weights/custom_traits.cpp
 \example Weights/convergence.cpp
 */

Weights/include/CGAL/Weights/internal/utils.h

@@ -432,6 +432,61 @@ namespace internal {
     return Point_2(x, y);
   }
 
+  // Flattening.
+
+  // \cgalFigureBegin{flattening, flattening.svg}
+  //   The non-planar configuration (top) is flattened to the planar configuration (bottom).
+  // \cgalFigureEnd
+
+  // When computing weights for a query point \f$q\f$ with respect to its neighbors
+  // \f$p_0\f$, \f$p_1\f$, and \f$p_2\f$, the local configuration is a quadrilateral
+  // [\f$p_0\f$, \f$p_1\f$, \f$p_2\f$, \f$q\f$] or two connected triangles [\f$q\f$, \f$p_0\f$, \f$p_1\f$]
+  // and [\f$q\f$, \f$p_1\f$, \f$p_2\f$]. When working in 3D, these triangles are not
+  // necessarily coplanar, in other words, they do not belong to the same common plane.
+  // When they are not coplanar, they can be made coplanar through the process called *flattening* (see the Figure above),
+  // however the latter introduces a distortion because the weights are computed with respect to the
+  // flattened configuration rather than to the original non-flat configuration.
+
+  // \subsection Weights_Examples_ProjectionTraits Computing 2D Weights in 3D
+
+  // If you have a 2D polygon in 3D plane that is not an XY plane, you can still compute
+  // the 2D weights, however you need to provide a special projection traits class.
+  // The common plane that is used in this example is projectable to the XY plane. We first
+  // compute `Mean_value_weights_2` for a 3D polygon in this plane. We then also show how to use
+  // the projection traits to compute the \ref PkgWeightsRefWachspressWeights "2D Wachspress weight"
+  // for 3D points, which are not strictly coplanar.
+
+  // \cgalExample{Weights/projection_traits.cpp}
+
+  // Example of flattening:
+
+  // 3D configuration.
+  // const Point_3 p0(0, 1, 1);
+  // const Point_3 p1(2, 0, 1);
+  // const Point_3 p2(7, 1, 1);
+  // const Point_3 q0(3, 1, 1);
+
+  // Choose a type of the weight:
+  // e.g. 0 - Wachspress (WP) weight.
+  // const FT wp = FT(0);
+
+  // Compute WP weights for q1, which is not on the plane [p0, p1, p2].
+
+  // Point_3 q1(3, 1, 2);
+  // std::cout << "3D wachspress (WP, q1): ";
+  // std::cout << CGAL::Weights::three_point_family_weight(p0, p1, p2, q1, wp) << std::endl;
+
+  // Converge q1 towards q0 that is we flatten the configuration.
+  // We also compare the result with the authalic weight.
+
+  // std::cout << "Converge q1 to q0: " << std::endl;
+  // for (FT x = FT(0); x <= FT(1); x += step) {
+  //   std::cout << "3D wachspress/authalic: ";
+  //   q1 = Point_3(3, 1, FT(2) - x);
+  //   std::cout << CGAL::Weights::three_point_family_weight(p0, p1, p2, q1, wp) << "/";
+  //   std::cout << CGAL::Weights::authalic_weight(p0, p1, p2, q1) << std::endl;
+  // }
+
   // Flattens an arbitrary quad into a planar quad.
   template<typename GeomTraits>
   void flatten(

Weights/include/CGAL/Weights/three_point_family_weights.h

@@ -130,35 +130,6 @@ namespace Weights {
 
   namespace internal {
 
-  // Example of flattening:
-
-  // 3D configuration.
-  // const Point_3 p0(0, 1, 1);
-  // const Point_3 p1(2, 0, 1);
-  // const Point_3 p2(7, 1, 1);
-  // const Point_3 q0(3, 1, 1);
-
-  // Choose a type of the weight:
-  // e.g. 0 - Wachspress (WP) weight.
-  // const FT wp = FT(0);
-
-  // Compute WP weights for q1, which is not on the plane [p0, p1, p2].
-
-  // Point_3 q1(3, 1, 2);
-  // std::cout << "3D wachspress (WP, q1): ";
-  // std::cout << CGAL::Weights::three_point_family_weight(p0, p1, p2, q1, wp) << std::endl;
-
-  // Converge q1 towards q0 that is we flatten the configuration.
-  // We also compare the result with the authalic weight.
-
-  // std::cout << "Converge q1 to q0: " << std::endl;
-  // for (FT x = FT(0); x <= FT(1); x += step) {
-  //   std::cout << "3D wachspress/authalic: ";
-  //   q1 = Point_3(3, 1, FT(2) - x);
-  //   std::cout << CGAL::Weights::three_point_family_weight(p0, p1, p2, q1, wp) << "/";
-  //   std::cout << CGAL::Weights::authalic_weight(p0, p1, p2, q1) << std::endl;
-  // }
-
   template<typename GeomTraits>
   typename GeomTraits::FT three_point_family_weight(
     const typename GeomTraits::Point_3& t,