cleanup

Documentation/doc/Documentation/Getting_started.txt

@@ -3,7 +3,12 @@
 
 - \subpage installation describes how to install %CGAL, and lists the third party libraries on which %CGAL depends, or for which %CGAL provides interfaces. 
 
-- \subpage introduction presents you some short example programs to get a first idea of the look and feel of a program that uses %CGAL.
+- \subpage introduction presents you some short example programs to
+  get a first idea for the look and feel of a program that uses \cgal.
+  We introduce the notion of the \em kernel which defines geometric primitives,
+  the notion of  <em>traits classes</em> which define what primitives are used
+  by a geometric algorithm, the notions of \em concept and \em model.
+  
 
 - \subpage preliminaries lists the licenses under which the %CGAL datastructures and algorithms are distributed, how to control inlining, thread safety, code deprecation, checking of pre- and postconditions, and how to alter the failure behavior. 
 

Documentation/doc/Documentation/Introduction.txt

@@ -32,8 +32,12 @@ In this first example we see how to construct some points
 and a segment, and we perform some basic operations on them.
  
 All \cgal header files are in the subdirectory `include/CGAL`.  All \cgal 
-classes and functions are in the namespace `CGAL`.  The geometric
-primitives, like the point type, are defined in a \em kernel.
+classes and functions are in the namespace `CGAL`.  
+Classes start with a capital letter, global
+function with a lowercase letter, and constants are all uppercase.
+The dimension of an object is expressed with a suffix.
+
+The geometric primitives, like the point type, are defined in a \em kernel.
 The kernel we have chosen for this first example uses `double`
 precision floating point numbers for the %Cartesian coordinates of the point.
 
@@ -43,6 +47,8 @@ computation. A predicate has a discrete set of possible answers,
 whereas a construction produces either a number, or another
 geometric entity.
 
+
+
 \cgalExample{Kernel_23/points_and_segment.cpp}
 
 
@@ -52,9 +58,17 @@ as the next example shows.
 
 \cgalExample{Kernel_23/surprising.cpp}
 
+When reading the code, we would assume that it prints three times "collinear".
+However we obtain:
 
-When reading the code, we would assume that it prints three times "collinear", 
-but as the fractions are not representable as double precision number
+\verbatim
+not collinear
+not collinear
+collinear
+\endverbatim
+
+
+As the fractions are not representable as double precision number
 the collinearity test will internally compute a determinant of a 3x3 matrix
 which is close but not equal to zero, and hence the non collinearity for the
 first two tests.  
@@ -63,9 +77,9 @@ Something similar can happen with points that perform a left turn,
 but due to rounding errors during the determinant computation, it
 seems that the points are collinear, or perform a right turn.
 
-If you need that the number gets interpreted at its full precision
+If you need that the numbers get interpreted at their full precision
 you can use a \cgal kernel that performs exact predicates and 
-constructions. 
+extract constructions. 
 
 \cgalExample{Kernel_23/exact.cpp}
 
@@ -92,8 +106,10 @@ Most \cgal packages explain what kind of kernel they need or support.
 \section intro_convex_hull The Convex Hull of a Sequence of Points
 
 All examples in this section compute the 2D convex hull of a set of points.
-The convex hull function expects by a begin/end iterator pair denoting a sequence of points,
-and it writes the points on the convex hull into an output iterator.
+We show that algorithms get their input as a begin/end iterator pair 
+denoting a range of points, and that they write the result, in the
+example the points on the convex hull, into an output iterator.
+
 
 \subsection intro_array The Convex Hull of Points in a Built-in Array
 
@@ -144,36 +160,6 @@ iterator generated by the helper function
 `std::back_inserter(result)`. This output iterator does nothing when
 incremented, and calls `result.push_back(..)` on the assignment.
 
-\subsection intro_streams The Convex Hull of Points in a Stream
-
-The next example program reads a sequence of points from standard
-input `std::cin` and writes the points on the convex hull to standard
-output `std::cout`.
-
-Instead of storing the points in a container such as an `std::vector`,
-and passing the begin/end iterator of the vector to the convex hull
-function, we use helper classes that turn file pointers into
-iterators.
-
-\cgalExample{Convex_hull_2/iostream_convex_hull_2.cpp}
-
-In the example code you see input and output stream iterators
-templated with the point type.  A `std::istream_iterator<Point_2>`
-hence allows to traverse a sequence of objects of type `Point_2`, which 
-come from standard input as we pass `std::cin` to the
-constructor of the iterator. The variable `input_end` denotes
-end-of-file.
-
-A `std::ostream_iterator<Point_2>` is an output iterator, that is an
-iterator to which, when dereferenced, we can assign a value.  When
-such an assignment to the output iterator happens somewhere inside the
-convex hull function, the iterator just writes the assigned point to
-standard output, because the iterator was constructed with
-`std::cout`.
-
-The call to the convex hull function takes three arguments, the input
-iterator range, and the output iterator to which the result gets
-written.
 
 If you know the \stl, the Standard Template Library, the above makes
 perfect sense, as this is the way the \stl decouples algorithms from
@@ -183,13 +169,26 @@ familiarize yourself with its basic ideas.
 
 \section intro_traits About Kernels and Traits Classes
 
+In this section we show how we express the requirements that must
+be fulfilled in order that a function like `convex_hull_2()`
+can be used with an arbitrary point type.
+
 If you look at the manual page of the function `convex_hull_2()`
 and the other 2D convex hull algorithms, you see that they come in two
 versions. In the examples we have seen so far the function that takes two
-iterators for the sequence of input points and an output iterator for
+iterators for the range of input points and an output iterator for
 writing the result to. The second version has an additional template
 parameter `Traits`, and an additional parameter of this type.
 
+\code{.cpp}
+template<class InputIterator , class OutputIterator , class Traits >
+OutputIterator 
+convex_hull_2(InputIterator first,
+              InputIterator beyond,
+              OutputIterator result,
+              const Traits & ch_traits)
+\endcode 	
+
 What are the geometric primitives a typical convex hull algorithm
 uses? Of course, this depends on the algorithm, so let us consider
 what is probably the simplest efficient algorithm, the so-called
@@ -298,7 +297,8 @@ An example for a concept with required free functions is the `HalfedgeGraph` in
 there must be a global function `halfedges(const G&)`, etc.
 
 An example for a concept with a required traits class is `InputIterator`.
-There must exist a specialization of the class `std::iterator_traits`.
+For a model of an `InputIterator` a specialization of the class `std::iterator_traits`
+must exist (or the generic template must be applicable).
 
 \section intro_further Further Reading
 

Kernel_23/examples/Kernel_23/exact.cpp

@@ -15,6 +15,5 @@ int main()
     std::cout << (CGAL::collinear(p,m,r) ? "collinear\n" : "not collinear\n");   
   }
  
-  std::cout << std::flush;
   return 0;
 }

Kernel_23/examples/Kernel_23/surprising.cpp

@@ -18,6 +18,5 @@ int main()
     Point_2 p(0,0), q(1, 1), r(2, 2);
     std::cout << (CGAL::collinear(p,q,r) ? "collinear\n" : "not collinear\n");   
   }  
-  std::cout << std::flush;
   return 0;
 }