adress some remarks of the reviews

BGL/doc/BGL/Concepts/FaceListGraph.h

@@ -27,7 +27,7 @@ Type              | Description
 
 Expression        |  returns                               | Description
 ----------------- | ---------------                        | -----------------------
-`faces(g)`        |  `CGAL::Iterator_range<face_iterator>` | An iterator range over all faces, convertible to `std::pair<face_iterator, face_iterator>`
+`faces(g)`        |  `std::pair<face_iterator, face_iterator>` | An iterator range over all faces. 
 `num_faces(g)`    |  `faces_size_type`                     | An upper bound of the number of faces of the graph.
 
 \attention `num_faces()` may return a number larger than `std::distance(faces(g).first, faces(g).second)`.

BGL/doc/BGL/Concepts/HalfedgeListGraph.h

@@ -28,7 +28,7 @@ Type                 | Description
 Expression                            | Returns                                   | Description  
 ------------------------------------- | ------------------------------------------| -----------
 `num_halfedges(g)`                    | `halfedges_size_type`                     | An upper bound of the number of halfedges of the graph.
-`halfedges(g)`                        | `CGAL::Iterator_range<halfedge_iterator>` | An iterator range over the halfedges of the graph, convertible to `std::pair<halfedge_iterator,halfedge_iterator>`
+`halfedges(g)`                        | `std::pair<halfedge_iterator,halfedge_iterator>` | An iterator range over the halfedges of the graph.
 
 \attention `num_halfedges()` may return a number larger than `std::distance(halfedges(g).first,halfedges(g).second)`.
 This is the case for implementations only marking halfedges deleted in the halfedge container.

STL_Extension/doc/STL_Extension/CGAL/iterator_range.h

@@ -38,7 +38,7 @@ namespace CGAL {
   public:
 
     typedef I iterator;
-    typedef const I const_iterator;
+    typedef I const_iterator;
 
     Iterator_range(I b, I e)
       : Base(b,e)
@@ -49,12 +49,12 @@ namespace CGAL {
     {}
 
 
-  const I& begin() const
+  I begin() const
   {
     return this->first;
   }
 
-  const I& end() const
+  I end() const
   {
     return this->second;
   }

STL_Extension/include/CGAL/iterator_range.h

@@ -27,10 +27,10 @@ namespace CGAL {
 
   /*!
 \ingroup PkgStlExtension
-  /// `CGAL::iterator_range` is a...
+  /// `CGAL::Iterator_range` is a...
   */
   template <typename I>
-  class iterator_range
+  class Iterator_range
     : public std::pair<I,I>{
     
     typedef std::pair<I,I> Base;
@@ -38,13 +38,13 @@ namespace CGAL {
   public:
 
     typedef I iterator;
-    typedef const I const_iterator;
+    typedef I const_iterator;
 
-    iterator_range(I b, I e)
+    Iterator_range(I b, I e)
       : Base(b,e)
     {}
 
-    iterator_range(const std::pair<I,I>& ip)
+    Iterator_range(const std::pair<I,I>& ip)
       : Base(ip)
     {}
 
@@ -53,44 +53,44 @@ namespace CGAL {
       return std::make_pair(begin(),end());
     }
 
-  const I& begin() const
+  I begin() const
   {
     return this->first;
   }
 
-  const I& end() const
+  I end() const
   {
     return this->second;
   }
 };
 
   template <typename T>
-  iterator_range<T>
+  Iterator_range<T>
   make_range(const T& b, const T&e)
   {
-    return iterator_range<T>(b,e);
+    return Iterator_range<T>(b,e);
   }
 
   template<typename T>
-  inline T range_begin( iterator_range<T> & x )
+  inline T range_begin( Iterator_range<T> & x )
   {
     return x.first;
   }
   
   template<typename T>
-  inline T range_end( iterator_range<T> & x )
+  inline T range_end( Iterator_range<T> & x )
   {
     return x.second;
   }
   
   template<typename T>
-  inline T range_begin(const iterator_range<T>& x )
+  inline T range_begin(const Iterator_range<T>& x )
   {
     return x.first;
   }
   
   template<typename T>
-  inline T range_end(const iterator_range<T>& x )
+  inline T range_end(const Iterator_range<T>& x )
   {
     return x.second;
   }  
@@ -108,20 +108,20 @@ namespace boost {
   struct range_const_iterator;
 
   template <typename T> 
-  struct range_iterator<CGAL::iterator_range<T> >
+  struct range_iterator<CGAL::Iterator_range<T> >
   {
     typedef T type;
   };
 
 
   template<typename T>
-  struct range_mutable_iterator< CGAL::iterator_range<T> >
+  struct range_mutable_iterator< CGAL::Iterator_range<T> >
   {
     typedef T type;
   };
   
   template<typename T>
-  struct range_const_iterator< CGAL::iterator_range<T> >
+  struct range_const_iterator< CGAL::Iterator_range<T> >
   {
     typedef T type;
   };

Surface_mesh/doc/Surface_mesh/Surface_mesh.txt

@@ -281,9 +281,9 @@ the surface mesh, they are taken from the free list in case it is
 not empty. 
 
 For all elements we offer a function to obtain the number of 
-elements, as well as the number of removed elements.
+used elements, as well as the number of used and removed elements.
-For vertices the functions are `Surface_mesh::numbr_of_vertices()`
+For vertices the functions are `Surface_mesh::number_of_vertices()`
-and `Surface_mesh::number_of_removed_vertices()`, respectively. 
+and `Surface_mesh::num_vertices()`, respectively. 
 The first function is slightly different from the free function 
 `num_vertices(const G&)` of the \sc{Bgl} package. 
 As \sc{Bgl} style algorithms use the indices of elements

Surface_mesh/include/CGAL/Surface_mesh/Surface_mesh.h

@@ -1341,6 +1341,11 @@ public:
     /// an upperbound on the index, and is needed
     /// by algorithms that temporarily store a 
     /// property in a vector of the appropriate size.
+    /// Note however that by garbage collecting elements get new indices.
+    /// In case you store vertex descriptors in an auxiliary data structure
+    /// or in a property these vertex descriptors are potentially no longer 
+    /// refering to the right vertices. 
+
 
     ///@{
    /// returns the number of used and removed vertices in the mesh.
@@ -1575,6 +1580,14 @@ public:
         return valid;
     }
 
+
+    /// performs a validity check on a single face.
+    bool is_valid(Edge_index e) const {
+      Halfedge_index h = halfedge(e);
+      return is_valid(h) && is_valid(opposite(h));
+    }
+
+
     /// performs a validity check on a single face.
     bool is_valid(Face_index f) const {
         Halfedge_index h = fconn_[f].halfedge_;
@@ -1623,6 +1636,12 @@ public:
         return hconn_[h].next_halfedge_;
     }
 
+    /// returns the previous halfedge within the incident face.
+    Halfedge_index prev(Halfedge_index h) const
+    {
+        return hconn_[h].prev_halfedge_;
+    }
+
     /// @cond CGAL_DOCUMENT_INTERNALS
     // sets the next halfedge of `h` within the face to `nh`.
     void set_next_only(Halfedge_index h, Halfedge_index nh)
@@ -1691,12 +1710,6 @@ public:
         return target(opposite(h));
     }
 
-    /// returns the previous halfedge within the incident face.
-    Halfedge_index prev(Halfedge_index h) const
-    {
-        return hconn_[h].prev_halfedge_;
-    }
-
     /// returns `opposite(next(h))`, that is the next halfedge \ref SurfaceMeshOrientation 
     /// "clockwise" around the target vertex of `h`. 
     Halfedge_index next_around_target(Halfedge_index h) const
@@ -1765,8 +1778,9 @@ public:
 
     /// \name Borders
     ///
-    ///  A vertex, halfedge, or edge is on the border of a surface mesh
+    ///  A halfedge, or edge is on the border of a surface mesh
-    /// if it is incident to a `null_face()`.  While for a halfedge and
+    /// if it is incident to a `null_face()`.  A vertex is on a border
+    /// if it is incident to a border halfedge. While for a halfedge and
     /// edge this is a constant time operation, for a vertex it means
     /// to look at all incident halfedges.  If algorithms operating on a 
     /// surface mesh maintain that the halfedge associated to a border vertex is
@@ -2052,7 +2066,8 @@ private: //------------------------------------------------------- private data
 
   /// \relates Surface_mesh
   /// Inserts the surface mesh in an output stream in Ascii OFF format. 
-  /// If the vertices have a normal property it is also inserted in the stream.
+  /// If the vertices have the property "v:normal" it is also inserted in the stream.
+  /// \note `operator<<(std::ostream&,const P&)` must be defined.
   template <typename P>
   std::ostream& operator<<(std::ostream& os, const Surface_mesh<P>& sm)
   {
@@ -2060,7 +2075,8 @@ private: //------------------------------------------------------- private data
   }
   /// \relates Surface_mesh
   /// Extracts the surface mesh from an input stream in Ascii OFF format.
-  /// If the vertices have a normal property it is also extracted from the stream.
+  /// If the vertices have the property "v:normal" it is also extracted from the stream.
+  /// \note `operator>>(std::istream&,const P&)` must be defined.
   template <typename P>
   std::istream& operator>>(std::istream& is, Surface_mesh<P>& sm)
   {