improved documentation. Added new allocator methods and clarified a bit how to delete elements

docs/Doxygen/allocation.dxy

@@ -4,7 +4,7 @@ Creating elements
 To create a simple single triangle mesh or to add elements to an existing mesh you should use the AddVertices and AddFaces functions, elements are added at the end of the mesh. These functions returns a pointer to the first allocated element.
 
 Adding element to a vector can cause reallocation, and therefore invalidation of any pointer that points to the mesh elements. These fucntion manage safely re-allocation and updating of pointers for all the pointers stored internally in the mesh (e.g. if you add some vertices and that causes a reallocation of the vertex vector, the pointers from faces to vertices will be automatically updated by the Allocator functions.
-
+You should never directly reallocate or resize the vertex or face vectors.
 
 \dontinclude trimesh_allocate.cpp
 \skip MyMesh
@@ -12,7 +12,14 @@ Adding element to a vector can cause reallocation, and therefore invalidation of
 
 look to platonic.h for more examples.
 
-If you keep interally some pointers to the mesh elements adding elements can invalidate them. In that case you should pass to the vcg::tri::Allocator functions a PointerUpdater to be used to update your private pointers.
+Alternatively you can add single vertex and faces in a more compact way as follows:
+
+\dontinclude trimesh_allocate.cpp
+\skip Alternative
+\until AddFace(
+
+
+If you keep internally some pointers to the mesh elements adding elements can invalidate them. In that case you should pass to the vcg::tri::Allocator functions a PointerUpdater to be used to update your private pointers.
 
 \dontinclude trimesh_allocate.cpp
 \skip dangerous
@@ -25,7 +32,8 @@ The library adopts a <em>Lazy Deletion Strategy</em> i.e. the elements in the ve
 
 Note that the basic deletion functions are very low level ones. They simply mark as deleted the corresponding entries without affecting the rest of the structures. So for example if you delete a vertex with these structures without checking that all the faces incident on it have been removed you could create a non consistent situation.
 Similarly, but less dangerously, when you delete a face its vertices are left around so at the end you can have unreferenced floating vertices.
-The following snippet of code delete a few faces from an icosahedron.
+Again you should never, ever try to delete vertexes by yourself by directly flagging deleted, but you must call the Allocator utility function.
+The following snippet of code shows how to delete a few faces from an icosahedron.
 \dontinclude trimesh_allocate.cpp
 \skip Icosahedron
 \until face[3]
@@ -38,7 +46,7 @@ m.face.size() != m.FN()
 
 Therefore when you scan the containers of vertices and faces you could encounter deleted elements so you should take care with a simple !IsD() check:
 \dontinclude trimesh_allocate.cpp
-\skip FaceIterator
+\skip loop
 \until  }
 \until }
 In some situations, particularly when you have to loop many many times over the element of the mesh without deleting/creating anything, it can be practical and convenient to get rid of deleted elements by explicitly calling the two garbage collecting functions:
@@ -65,6 +73,6 @@ Given the intricate nature of the mesh itself it is severely forbidden any attem
 \skip m2
 \until Append
 
-In the vcg::tri::Append utility class there are aslo functions for copying only a subset of the second mesh (the selected one) or to append the second mesh to the first one.
+In the vcg::tri::Append utility class there are also functions for copying only a subset of the second mesh (the selected one) or to append the second mesh to the first one.
 
 */

docs/Doxygen/main_concept.dxy

@@ -22,7 +22,7 @@ In other words, to define a type of mesh you need only to derive from vcg::tri::
 \skip class
 \until MyMesh
 
-The face, the edge and the vertex type are the crucial bits to understand in order to be able to take the best from VCG Lib. A vertex, an edge, a face and a tetrahedron are just an user defined (possibly empty) collection of attribute. For example you will probably expect MyVertex to contain the (x,y,z) position of the vertex, but what about the surface normal at the vertex?.. and the color? VCG Lib gives you a pretty elegant way to define whichever attributes you want to store in each vertex, face, or edge. For example, the following example shows three valid definitions of MyVertex of increasing complexity :
+The face, the edge and the vertex type are the crucial bits to understand in order to be able to take the best from VCG Lib. A vertex, an edge, a face and a tetrahedron are just an user defined (possibly empty) collection of attributes. For example you will probably expect MyVertex to contain the (x,y,z) position of the vertex, but what about the surface normal at the vertex?.. and the color? VCG Lib gives you a pretty elegant way to define whichever attributes you want to store in each vertex, face, or edge. For example, the following example shows three valid definitions of MyVertex of increasing complexity :
 
 \dontinclude trimesh_base.cpp
 \skip MyVertex0