updates following the "general comments" in Efi's review

Circular_kernel_3/doc_tex/Circular_kernel_3/CK.tex

@@ -1,22 +1,50 @@
 \section{Introduction}
 
-The goal of the 3D spherical kernel is to offer to the user a large set
+The goal of the 3D spherical kernel is to offer to the user a large
-of functionalities on spheres, circles and circular arcs in the 3D
+set of functionalities on spheres, circles and circular arcs in the 3D
-space, in a similar way as what the 2D circular kernel package (see
+space. These functionalities require computing on algebraic numbers,
-Chapter~\ref{chapter-circular-kernel}) does in the plane. All the
+which motivates the creation of a new kernel concept extending the
-choices (interface, robustness, representation, and so on) made here
+\cgal\ \ccc{Kernel} concept, which is restricted to objects
-are consistent with the choices made in the \cgal\ kernel, for which
+and functionality in a \ccc{FieldNumberType}.
-we refer the user to the kernel manual.
+
+All the choices (interface, robustness, representation, and so on)
+made here are consistent with the choices made in the \cgal\ kernel,
+for which we refer the user to the kernel manual
+(Chapter~\ref{chapter-kernel-23}).
+
+\section{Spherical Kernel Objects\label{section-SK-objects}}
+
+New main geometric objects are introduced by \ccc{Spherical_kernel_3}:
+circular arcs ((model of \ccc{SphericalKernel::CircularArc_3}), points
+of circular arcs (model of \ccc{SphericalKernel::CircularArcPoint_3}),
+and line segments (model of \ccc{SphericalKernel::LineArc_3}) whose
+endpoints are points of this new type.
+
+\ccc{SphericalKernel::CircularArcPoint_3} is used in particular for
+endpoints of arcs and intersection points between spheres, circles or
+arcs. The coordinates of these points are algebraic numbers of degree
+two. Therefore, general predicates offered by the \ccc{Kernel} on
+\ccc{Point_3}, which have coordinates in a \ccc{FieldNumberType},
+would require heavy algebraic computations in algebraic extensions
+of higher degrees and thus are not provided on
+them, which explains the need for a new point type. 
+
+A consistent set of predicates and constructions is offered on this
+new type of points. The spherical kernel currently implements a set of
+fundamental functionalities like intersection, comparisons, inclusion,
+etc. More might be provided in the future, as long as only algebraic
+numbers of degree two are used.
 
 \section{Software Design}
 
 The design of \ccc{Spherical_kernel_3} is similar to the design of
-\ccc{Circular_kernel_2}. It has two template parameters:
+\ccc{Circular_kernel_2} (see Chapter~\ref{chapter-circular-kernel}). 
+It has two template parameters:
 \begin{itemize}
-\item {} the \ccc{LinearKernel}, from which the spherical kernel derives,
+\item {} the first parameter must model the \cgal\ 
-provides all elementary geometric objects like points, lines, spheres, and
+three dimensional \ccc{Kernel} concept. The spherical kernel derives
-elementary functionality on them. It must model the \cgal\ three 
+from it, and it provides all elementary geometric objects like points,
-dimensional \ccc{Kernel} concept.
+lines, spheres, circles and elementary functionality on them.
 %The \cgal\ 2D Kernel can be used as parameter,
 %but the user may plug his own kernel 
 %instead, as long as it follows the \cgal\ kernel concept. 
@@ -27,19 +55,16 @@ robustness of the package relies on the fact that the algebraic kernel
 provides exact computations on algebraic objects.
 \end{itemize}
 
-The 3D spherical kernel uses the extensibility scheme presented in the 
+The 3D spherical kernel uses the extensibility scheme presented in the
-kernel manual (see Section~\ref{section-extensible-kernel}). 
+kernel manual (see Section~\ref{section-extensible-kernel}). The types
-The types of \ccc{LinearKernel} are inherited
+of \ccc{Kernel} are inherited by the 3D spherical kernel and some
-by the 3D spherical kernel and some types are taken from the
+types are taken from the \ccc{AlgebraicKernelForSpheres}
-\ccc{AlgebraicKernelForSpheres} parameter. New main geometric objects are
+parameter. \ccc{Spherical_kernel_3} introduces new geometric objects
-introduced by \ccc{Spherical_kernel_3}: circles in 3D, circular arcs,
+as mentioned in Section~\ref{section-SK-objects}.
-points of circular arcs (used in particular for endpoints of arcs and
-intersection points between arcs), and line segments, whose endpoints
-are points of this new type.
 
 In fact, the spherical kernel is documented as a concept,
 \ccc{SphericalKernel}. One model is currently provided: 
-\ccc{Spherical_kernel_3<LinearKernel,AlgebraicKernelForSpheres>}.
+\ccc{Spherical_kernel_3<Kernel,AlgebraicKernelForSpheres>}.
 
 \section{Example}
 \textit{following example to be improved, and more examples and explanations to be added...}

Circular_kernel_3/doc_tex/Circular_kernel_3_ref/BasicGeometricKernel.tex

@@ -1,35 +0,0 @@
-\begin{ccRefConcept}{LinearKernel} 
-
-\ccDefinition
-
-The geometric kernel parameter of \ccc{CGAL::Spherical_kernel_3} is
-supposed to be a model of the \textit{(three-dimensional)} \ccc{Kernel}
-concept, so that the spherical kernel provides all functionalities of a
-\cgal\ kernel.
-
-%In fact, even though all types and operations of the
-%\ccc{CGAL::Kernel} concept are required so that
-%\ccc{CGAL::Circular_kernel_2} actually refines \ccc{CGAL::Kernel}, only
-%the following types are explicitly used by \ccc{Circular_kernel_2} and
-%can thus be considered as minimal requirements:
-
-%\ccNestedType{RT}{A model of \ccc{RingNumberType}.}
-%\ccNestedType{FT}{A model of \ccc{FieldNumberType<RT>}.} \footnote{concept template...?}
-
-%\ccNestedType{Point_2}{A model of \ccc{Point_2}.}
-%\ccNestedType{Line_2}{A model of \ccc{Line_2}.}
-%\ccNestedType{Circle_2}{A model of \ccc{Circle_2}.}
-%\ccNestedType{Object_2}{A model of \ccc{Object_2}.}
-
-%Note that all operations on these types are also required.
-
-\ccHasModels
-
-All \cgal\ kernels
-
-\ccSeeAlso
-
-\ccRefIdfierPage{Kernel}\\
-\ccRefIdfierPage{SphericalKernel}
-
-\end{ccRefConcept}

Circular_kernel_3/doc_tex/Circular_kernel_3_ref/CCircle_3.tex

@@ -1,6 +1,8 @@
 
 \begin{ccRefConcept}{SphericalKernel::Circle_3}
 
+TO BE MOVED TO KERNEL
+
 Concept for circles in 3D.
 
 \ccRefines

Circular_kernel_3/doc_tex/Circular_kernel_3_ref/Circle_3.tex

@@ -1,5 +1,7 @@
 \begin{ccRefClass}{Circle_3<SphericalKernel>}
 
+TO BE MOVED TO KERNEL
+
 \ccInclude{CGAL/Circle_3.h}
 
 \ccIsModel

Circular_kernel_3/doc_tex/Circular_kernel_3_ref/GeomFunctorsOtherConstructions.tex

@@ -1,7 +1,7 @@
 \begin{ccRefFunctionObjectConcept}{SphericalKernel::ConstructRadicalPlane_3}
 \ccCreationVariable{fo}
 
-\textbf{!!!!!!! could go to Kernel}
+TO BE MOVED TO KERNEL
 
 An object \ccVar\ of this type must provide:
 
@@ -21,6 +21,8 @@ The \textit{power} of \ccc{p} with respect to a sphere \ccc{s} centered at
 \begin{ccRefFunctionObjectConcept}{SphericalKernel::ConstructDiametralSphere_3}
 \ccCreationVariable{fo}
 
+TO BE MOVED TO KERNEL
+
 An object \ccVar\ of this type must provide:
 
 \ccMemberFunction{SphericalKernel::Sphere_3

Circular_kernel_3/doc_tex/Circular_kernel_3_ref/Intersect.tex

@@ -30,9 +30,7 @@ when this ordering is defined on the computed objects.}
 For the \textbf{first operator}, \ccc{Type1} and \ccc{Type2} can both 
 be either
 
-\textbf{!!!!!!! we coded here the intersection \ccc{Line_3}-\ccc{Line_3}, 
+\textbf{!!!!!!! intersection \ccc{Line_3}-\ccc{Line_3}  TO BE MOVED TO KERNEL}
-since it was apparently forgotten in \ccc{CGAL::Kernel}, this code
-should be moved there}
 
 \begin{itemize}
 \item {} \ccc{SphericalKernel::Sphere_3},
@@ -62,7 +60,7 @@ line segments.
 
 For the \textbf{second operator}, \ccc{Type1}, \ccc{Type2} and \ccc{Type3}
 can be either
-\textbf{!!!!!!! case of 3 planes is missing, again it should be in Kernel}
+\textbf{!!!!!!! case of 3 planes TO BE MOVED TO KERNEL}
 
 \begin{itemize}
 \item {} \ccc{SphericalKernel::Sphere_3} or

Circular_kernel_3/doc_tex/Circular_kernel_3_ref/SphericalKernel.tex

@@ -4,14 +4,14 @@
 \ccc{Kernel}
 
 \ccHasModels
-\ccc{CGAL::Spherical_kernel_3<LinearKernel,AlgebraicKernelForSpheres>}\\
+\ccc{CGAL::Spherical_kernel_3<Kernel,AlgebraicKernelForSpheres>}\\
 \ccc{Exact_spherical_kernel_3}
 
 \ccTypes
 
 A model of \ccc{SphericalKernel} is supposed to provide some basic types
 
-\ccNestedType{Linear_kernel}{Model of \ccc{LinearKernel}.}
+\ccNestedType{Linear_kernel}{Model of \ccc{Kernel}.}
 \ccGlue
 \ccNestedType{Algebraic_kernel}{Model of \ccc{AlgebraicKernelForSpheres}.}
 
@@ -37,7 +37,7 @@ and to define the following geometric objects
 \ccGlue
 \ccNestedType{Sphere_3}{Model of \ccc{Kernel::Sphere_3}.}
 
-\ccNestedType{Circle_3}{Model of \ccc{SphericalKernel::Circle_3}.}
+\ccNestedType{Circle_3}{Model of \ccc{Kernel::Circle_3}.}
 \ccGlue
 \ccNestedType{Line_arc_3}{Model of \ccc{SphericalKernel::LineArc_3}.}
 \ccGlue
@@ -104,8 +104,8 @@ constructions and other functionalities.
 \ccGlue
 \ccNestedType{Construct_supporting_circle_3}{Model of \ccc{SphericalKernel::ConstructSupportingCircle_3}.}
 
-\ccNestedType{Construct_diametral_sphere_3}{Model of \ccc{SphericalKernel::ConstructDiametralSphere_3}.}
+\ccNestedType{Construct_diametral_sphere_3}{Model of \ccc{SphericalKernel::ConstructDiametralSphere_3}.TO BE MOVED TO KERNEL}
-\ccNestedType{Construct_radical_plane_3}{Model of \ccc{SphericalKernel::ConstructRadicalPlane_3}.\textbf{!!!!!!! could go to Kernel}}
+\ccNestedType{Construct_radical_plane_3}{Model of \ccc{SphericalKernel::ConstructRadicalPlane_3}. TO BE MOVED TO KERNEL}
 
 \ccNestedType{Construct_bbox_3}{Model of \ccc{SphericalKernel::ConstructBbox_3}.}
 

Circular_kernel_3/doc_tex/Circular_kernel_3_ref/intro.tex

@@ -7,8 +7,6 @@
 
 \ccRefConceptPage{SphericalKernel}
 
-\ccRefConceptPage{LinearKernel}
-
 	\subsubsection*{Functors}
 
 \ccRefConceptPage{SphericalKernel::ConstructPlane_3}\\
@@ -96,7 +94,7 @@
 
 \ccRefIdfierPage{CGAL::Circular_arc_point_3<SphericalKernel>}
 
-	\subsubsection*{Circles}
+	\subsubsection*{Circles - to be moved to Kernel}
 
 \ccRefIdfierPage{CGAL::Circle_3<SphericalKernel>}
 

Circular_kernel_3/doc_tex/Circular_kernel_3_ref/main.tex

@@ -4,7 +4,6 @@
 % geometric kernels
 
 \input{Circular_kernel_3_ref/SphericalKernel}
-\input{Circular_kernel_3_ref/BasicGeometricKernel}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % geometric objects