Relatively straightforward changes to wording of documentation, focusing particularly on the sparse and (to a lesser extent) geometry pages.

4 files changed, 41 insertions, 41 deletions

diff --git a/doc/C00_QuickStartGuide.dox b/doc/C00_QuickStartGuide.dox
index 21b0af50d..8534cb0c3 100644
--- a/doc/C00_QuickStartGuide.dox
+++ b/doc/C00_QuickStartGuide.dox
@@ -67,7 +67,7 @@ The output is as follows:
 
 The second example starts by declaring a 3-by-3 matrix \c m which is initialized using the \link DenseBase::Random(Index,Index) Random() \endlink method with random values between -1 and 1. The next line applies a linear mapping such that the values are between 10 and 110. The function call \link DenseBase::Constant(Index,Index,const Scalar&) MatrixXd::Constant\endlink(3,3,1.2) returns a 3-by-3 matrix expression having all coefficients equal to 1.2. The rest is standard arithmetics.
 
-The next line of the \c main function introduces a new type: \c VectorXd. This represents a (column) vector of arbitrary size. Here, the vector \c v is created to contains \c 3 coefficients which are left unitialized. The one but last line uses the so-called comma-initializer, explained in \ref TutorialAdvancedInitialization, to set all coefficients of the vector \c v to be as follows:
+The next line of the \c main function introduces a new type: \c VectorXd. This represents a (column) vector of arbitrary size. Here, the vector \c v is created to contain \c 3 coefficients which are left unitialized. The one but last line uses the so-called comma-initializer, explained in \ref TutorialAdvancedInitialization, to set all coefficients of the vector \c v to be as follows:
 
 \f[
 v =
diff --git a/doc/C07_TutorialReductionsVisitorsBroadcasting.dox b/doc/C07_TutorialReductionsVisitorsBroadcasting.dox
index 44e963424..e58ff6e2c 100644
--- a/doc/C07_TutorialReductionsVisitorsBroadcasting.dox
+++ b/doc/C07_TutorialReductionsVisitorsBroadcasting.dox
@@ -93,7 +93,7 @@ Array.
 
 The arguments passed to a visitor are pointers to the variables where the
 row and column position are to be stored. These variables should be of type
-\link DenseBase::Index Index \endlink (FIXME: link ok?), as shown below:
+\link DenseBase::Index Index \endlink, as shown below:
 
 <table class="example">
 <tr><th>Example:</th><th>Output:</th></tr>
@@ -141,7 +141,7 @@ return a 'column-vector'</b>
 
 \subsection TutorialReductionsVisitorsBroadcastingPartialReductionsCombined Combining partial reductions with other operations
 It is also possible to use the result of a partial reduction to do further processing.
-Here is another example that aims to find the column whose sum of elements is the maximum
+Here is another example that finds the column whose sum of elements is the maximum
  within a matrix. With column-wise partial reductions this can be coded as:
 
 <table class="example">
diff --git a/doc/C08_TutorialGeometry.dox b/doc/C08_TutorialGeometry.dox
index 983152ca5..aea0b6642 100644
--- a/doc/C08_TutorialGeometry.dox
+++ b/doc/C08_TutorialGeometry.dox
@@ -6,7 +6,7 @@ namespace Eigen {
 \li \b Previous: \ref TutorialReductionsVisitorsBroadcasting
 \li \b Next: \ref TutorialSparse
 
-In this tutorial, we will shortly introduce the many possibilities offered by the \ref Geometry_Module "geometry module", namely 2D and 3D rotations and projective or affine transformations.
+In this tutorial, we will briefly introduce the many possibilities offered by the \ref Geometry_Module "geometry module", namely 2D and 3D rotations and projective or affine transformations.
 
 \b Table \b of \b contents
   - \ref TutorialGeoElementaryTransformations
@@ -78,7 +78,7 @@ representations are rotation matrices, while for other usages Quaternion is the
 representation of choice as they are compact, fast and stable. Finally Rotation2D and
 AngleAxis are mainly convenient types to create other rotation objects.
 
-<strong>Notes on Translation and Scaling</strong>\n Likewise AngleAxis, these classes were
+<strong>Notes on Translation and Scaling</strong>\n Like AngleAxis, these classes were
 designed to simplify the creation/initialization of linear (Matrix) and affine (Transform)
 transformations. Nevertheless, unlike AngleAxis which is inefficient to use, these classes
 might still be interesting to write generic and efficient algorithms taking as input any
@@ -186,7 +186,7 @@ matNxN = t.extractRotation();
 While transformation objects can be created and updated concatenating elementary transformations,
 the Transform class also features a procedural API:
 <table class="manual">
-<tr><th></th><th>procedurale API</th><th>equivalent natural API </th></tr>
+<tr><th></th><th>procedural API</th><th>equivalent natural API </th></tr>
 <tr><td>Translation</td><td>\code
 t.translate(Vector_(tx,ty,..));
 t.pretranslate(Vector_(tx,ty,..));
@@ -234,7 +234,7 @@ t = Translation_(..) * t * RotationType(..) * Translation_(..) * Scaling_(..);
 <table class="manual">
 <tr><td style="max-width:30em;">
 Euler angles might be convenient to create rotation objects.
-On the other hand, since there exist 24 differents convension,they are pretty confusing to use. This example shows how
+On the other hand, since there exist 24 different conventions, they are pretty confusing to use. This example shows how
 to create a rotation matrix according to the 2-1-2 convention.</td><td>\code
 Matrix3f m;
 m = AngleAxisf(angle1, Vector3f::UnitZ())
diff --git a/doc/C09_TutorialSparse.dox b/doc/C09_TutorialSparse.dox
index 8b5401dd7..5d9050a85 100644
--- a/doc/C09_TutorialSparse.dox
+++ b/doc/C09_TutorialSparse.dox
@@ -15,10 +15,10 @@ namespace Eigen {
 
 \section TutorialSparseIntro Sparse matrix representations
 
-In many applications (e.g., finite element methods) it is common to deal with very large matrices where only a few coefficients are different than zero. Both in term of memory consumption and performance, it is fundamental to use an adequate representation storing only nonzero coefficients. Such a matrix is called a sparse matrix.
+In many applications (e.g., finite element methods) it is common to deal with very large matrices where only a few coefficients are different from zero.  In such cases, memory consumption can be reduced and performance increased by using a specialized representation storing only nonzero coefficients. Such a matrix is called a sparse matrix.
 
 \b Declaring \b sparse \b matrices \b and \b vectors \n
-The SparseMatrix class is the main sparse matrix representation of the Eigen's sparse module which offers high performance, low memory usage, and compatibility with most of sparse linear algebra packages. Because of its limited flexibility, we also provide a DynamicSparseMatrix variant tailored for low-level sparse matrix assembly. Both of them can be either row major or column major:
+The SparseMatrix class is the main sparse matrix representation of Eigen's sparse module; it offers high performance, low memory usage, and compatibility with most sparse linear algebra packages. These advantages come at the cost of some loss of flexibility, particularly during the assembly of the sparse matrix; consequently, a variant called DynamicSparseMatrix is offered which is tailored for low-level sparse matrix assembly. Both of them can be either row major or column major:
 
 \code
 #include <Eigen/Sparse>
@@ -33,11 +33,11 @@ Although a sparse matrix could also be used to represent a sparse vector, for th
 SparseVector<std::complex<float> > v1(1000); // declare a column sparse vector of complex<float> of size 1000
 SparseVector<double,RowMajor> v2(1000);      // declare a row sparse vector of double of size 1000
 \endcode
-Note that here the size of a vector denotes its dimension and not the number of nonzero coefficients which is initially zero (like sparse matrices).
+As with dense vectors, the size of a sparse vector denotes its dimension and not the number of nonzero coefficients. At the time of allocation, both sparse matrices and sparse vectors do not have any nonzero coefficients---they correspond to the "all zeros" matrix or vector. 
 
 
 \b Overview \b of \b the \b internal \b sparse \b storage \n
-In order to get the best of the Eigen's sparse objects, it is important to have a rough idea of the way they are internally stored. The SparseMatrix class implements the common and generic Compressed Column/Row Storage scheme. It consists of three compact arrays storing the values with their respective inner coordinates, and pointer indices to the begining of each outer vector. For instance, let \c m be a column-major sparse matrix. Then its nonzero coefficients are sequentially stored in memory in a column-major order (\em values). A second array of integer stores the respective row index of each coefficient (\em inner \em indices). Finally, a third array of integer, having the same length than the number of columns, stores the index in the previous arrays of the first element of each column (\em outer \em indices).
+In order to get the most out of Eigen's sparse objects, it is important to have a rough idea of the way they are represented internally. The SparseMatrix class implements the widely-used Compressed Column (or Row) Storage scheme. It consists of three compact arrays: one for the coefficient values, and two for the indices of the nonzero entries. However, the indices are \em not stored as a direct column, row list; instead, the beginning of each column (or row) is encoded as a pointer index.  For instance, let \c m be a column-major sparse matrix. Then its nonzero coefficients are sequentially stored in memory in column-major order (\em values). A second array of integers stores the respective row index of each coefficient (\em inner \em indices). Finally, a third array of integers, having the same length as the number of columns, stores the index in the previous arrays of the first element of each column (\em outer \em indices).
 
 Here is an example, with the matrix:
 <table class="manual">
@@ -55,17 +55,17 @@ and its internal representation using the Compressed Column Storage format:
 </table>
 Outer indices:<table class="manual"><tr><td>0</td><td>2</td><td>4</td><td>5</td><td>6</td><td>\em 7 </td></tr></table>
 
-As you can guess, here the storage order is even more important than with dense matrix. We will therefore often make a clear difference between the \em inner and \em outer dimensions. For instance, it is easy to loop over the coefficients of an \em inner \em vector (e.g., a column of a column-major matrix), but completely inefficient to do the same for an \em outer \em vector (e.g., a row of a col-major matrix).
+As you might guess, here the storage order is even more important than with dense matrices. We will therefore often make a clear difference between the \em inner and \em outer dimensions. For instance, it is efficient to loop over the coefficients of an \em inner \em vector (e.g., a column of a column-major matrix), but completely inefficient to do the same for an \em outer \em vector (e.g., a row of a column-major matrix).
 
 The SparseVector class implements the same compressed storage scheme but, of course, without any outer index buffer.
 
-Since all nonzero coefficients of such a matrix are sequentially stored in memory, random insertion of new nonzeros can be extremely costly. To overcome this limitation, Eigen's sparse module provides a DynamicSparseMatrix class which is basically implemented as an array of SparseVector. In other words, a DynamicSparseMatrix is a SparseMatrix where the values and inner-indices arrays have been splitted into multiple small and resizable arrays. Assuming the number of nonzeros per inner vector is relatively low, this slight modification allow for very fast random insertion at the cost of a slight memory overhead and a lost of compatibility with other sparse libraries used by some of our highlevel solvers. Note that the major memory overhead comes from the extra memory preallocated by each inner vector to avoid an expensive memory reallocation at every insertion.
+Since all nonzero coefficients of such a matrix are sequentially stored in memory, inserting a new nonzero near the "beginning" of the matrix can be extremely costly. As described below (\ref TutorialSparseFilling), one strategy is to fill nonzero coefficients in order. In cases where this is not possible, Eigen's sparse module also provides a DynamicSparseMatrix class which allows efficient random insertion. DynamicSparseMatrix is essentially implemented as an array of SparseVector, where the values and inner-indices arrays have been split into multiple small and resizable arrays. Assuming the number of nonzeros per inner vector is relatively small, this modification allows for very fast random insertion at the cost of a slight memory overhead (due to extra memory preallocated by each inner vector to avoid an expensive memory reallocation at every insertion) and a loss of compatibility with other sparse libraries used by some of our high-level solvers. Once complete, a DynamicSparseMatrix can be converted to a SparseMatrix to permit usage of these sparse libraries.
 
-To summarize, it is recommanded to use a SparseMatrix whenever this is possible, and reserve the use of DynamicSparseMatrix for matrix assembly purpose when a SparseMatrix is not flexible enough. The respective pro/cons of both representations are summarized in the following table:
+To summarize, it is recommended to use SparseMatrix whenever possible, and reserve the use of DynamicSparseMatrix to assemble a sparse matrix in cases when a SparseMatrix is not flexible enough. The respective pros/cons of both representations are summarized in the following table:
 
 <table class="manual">
 <tr><td></td> <td>SparseMatrix</td><td>DynamicSparseMatrix</td></tr>
-<tr><td>memory usage</td><td>***</td><td>**</td></tr>
+<tr><td>memory efficiency</td><td>***</td><td>**</td></tr>
 <tr><td>sorted insertion</td><td>***</td><td>***</td></tr>
 <tr><td>random insertion \n in sorted inner vector</td><td>**</td><td>**</td></tr>
 <tr><td>sorted insertion \n in random inner vector</td><td>-</td><td>***</td></tr>
@@ -82,7 +82,7 @@ To summarize, it is recommanded to use a SparseMatrix whenever this is possible,
 
 \b Matrix \b and \b vector \b properties \n
 
-Here mat and vec represents any sparse-matrix and sparse-vector types respectively.
+Here mat and vec represent any sparse-matrix and sparse-vector type, respectively.
 
 <table class="manual">
 <tr><td>Standard \n dimensions</td><td>\code
@@ -96,7 +96,7 @@ mat.innerSize()
 mat.outerSize()\endcode</td>
 <td></td>
 </tr>
-<tr><td>Number of non \n zero coefficiens</td><td>\code
+<tr><td>Number of non \n zero coefficients</td><td>\code
 mat.nonZeros() \endcode</td>
 <td>\code
 vec.nonZeros() \endcode</td></tr>
@@ -105,12 +105,12 @@ vec.nonZeros() \endcode</td></tr>
 
 \b Iterating \b over \b the \b nonzero \b coefficients \n
 
-Iterating over the coefficients of a sparse matrix can be done only in the same order than the storage order. Here is an example:
+Iterating over the coefficients of a sparse matrix can be done only in the same order as the storage order. Here is an example:
 <table class="manual">
 <tr><td>
 \code
 SparseMatrixType mat(rows,cols);
-for (int k=0; k\<m1.outerSize(); ++k)
+for (int k=0; k<m1.outerSize(); ++k)
   for (SparseMatrixType::InnerIterator it(mat,k); it; ++it)
   {
     it.value();
@@ -134,7 +134,7 @@ for (SparseVector<double>::InnerIterator it(vec); it; ++it)
 
 \section TutorialSparseFilling Filling a sparse matrix
 
-Owing to the special storage scheme of a SparseMatrix, it is obvious that for performance reasons a sparse matrix cannot be filled as easily as a dense matrix. For instance the cost of a purely random insertion into a SparseMatrix is in O(nnz) where nnz is the current number of non zeros. In order to cover all uses cases with best efficiency, Eigen provides various mechanisms, from the easiest but slowest, to the fastest but restrictive one.
+Because of the special storage scheme of a SparseMatrix, adding new nonzero entries can have consequences for performance. For instance, the cost of a purely random insertion into a SparseMatrix is O(nnz), where nnz is the current number of nonzero coefficients.  In order to cover all use cases with best efficiency, Eigen provides various mechanisms, from the easiest but slowest, to the fastest but most restrictive.
 
 If you don't have any prior knowledge about the order your matrix will be filled, then the best choice is to use a DynamicSparseMatrix. With a DynamicSparseMatrix, you can add or modify any coefficients at any time using the coeffRef(row,col) method. Here is an example:
 \code
@@ -145,17 +145,17 @@ for (...)
     for each i interacting with j     // the i can be random
       aux.coeffRef(i,j) += foo(i,j);
 \endcode
-Then the DynamicSparseMatrix object can be converted to a compact SparseMatrix to be used, e.g., by one of our supported solver:
+Then the DynamicSparseMatrix object can be converted to a compact SparseMatrix to be used, e.g., by one of our supported solvers:
 \code
 SparseMatrix<float> mat(aux);
 \endcode
 
 In order to optimize this process, instead of the generic coeffRef(i,j) method one can also use:
- - \code m.insert(i,j) = value; \endcode which assumes the coefficient of coordinate (row,col) does not already exist (otherwise this is a programming error and your program will stop).
- - \code m.insertBack(i,j) = value; \endcode which, in addition to the requirements of insert(), also assumes that the coefficient of coordinate (row,col) will be inserted at the end of the target inner-vector. More precisely, if the matrix m is column major, then the row index of the last non zero coefficient of the j-th column must be smaller than i.
+ - \code m.insert(i,j) = value; \endcode which assumes the coefficient of coordinate (i,j) does not already exist (otherwise this is a programming error and your program will stop).
+ - \code m.insertBack(i,j) = value; \endcode which, in addition to the requirements of insert(), also assumes that the coefficient of coordinate (i,j) will be inserted at the end of the target inner-vector. More precisely, if the matrix m is column major, then the row index of the last non zero coefficient of the j-th column must be smaller than i.
 
 
-Actually, the SparseMatrix class also supports random insertion via the insert() method. However, its uses should be reserved in cases where the inserted non zero is nearly the last one of the compact storage array. In practice, this means it should be used only to perform random (or sorted) insertion into the current inner-vector while filling the inner-vectors in an increasing order. Moreover, with a SparseMatrix an insertion session must be closed by a call to finalize() before any use of the matrix. Here is an example for a column major matrix:
+The SparseMatrix class also supports random insertion via the insert() method. However, it should only be used when the inserted coefficient is nearly the last one of the compact storage array. In practice, this means it should be used only to perform random (or sorted) insertion into the current inner-vector while filling the inner-vectors in increasing order. Moreover, with a SparseMatrix an insertion session must be closed by a call to finalize() before any use of the matrix. Here is an example for a column major matrix:
 
 \code
 SparseMatrix<float> mat(1000,1000);
@@ -166,7 +166,7 @@ for each j                                  // should be in increasing order for
 mat.finalize();
 \endcode
 
-Finally, the fastest way to fill a SparseMatrix object is to insert the elements in a purely coherence order (increasing inner index per increasing outer index). To this end, Eigen provides a very low but optimal API and illustrated below:
+Finally, the fastest way to fill a SparseMatrix object is to insert the elements in purely increasing order (increasing inner index per outer index, and increasing outer index) using the insertBack() function:
 
 \code
 SparseMatrix<float> mat(1000,1000);
@@ -179,41 +179,41 @@ for(int j=0; j<1000; ++j)
 }
 mat.finalize();                             // optional for a DynamicSparseMatrix
 \endcode
-Note that there also exist the insertBackByOuterInner(Index outer, Index, inner) function which allows to write code agnostic to the storage order.
+Note that there is also an insertBackByOuterInner(Index outer, Index inner) function which allows one to write code agnostic to the storage order.
 
 \section TutorialSparseFeatureSet Supported operators and functions
 
-In the following \em sm denote a sparse matrix, \em sv a sparse vector, \em dm a dense matrix, and \em dv a dense vector.
-In Eigen's sparse module we chose to expose only the subset of the dense matrix API which can be efficiently implemented. Moreover, all combinations are not always possible. For instance, it is not possible to add two sparse matrices having two different storage order. On the other hand it is perfectly fine to evaluate a sparse matrix/expression to a matrix having a different storage order:
+In the following \em sm denotes a sparse matrix, \em sv a sparse vector, \em dm a dense matrix, and \em dv a dense vector.
+In Eigen's sparse module we chose to expose only the subset of the dense matrix API which can be efficiently implemented. Moreover, not every combination is allowed; for instance, it is not possible to add two sparse matrices having two different storage orders. On the other hand, it is perfectly fine to evaluate a sparse matrix or expression to a matrix having a different storage order:
 \code
 SparseMatrixType sm1, sm2, sm3;
-sm3 = sm1.transpose() + sm2;                    // invalid
-sm3 = SparseMatrixType(sm1.transpose()) + sm2;  // correct
+sm3 = sm1.transpose() + sm2;                    // invalid, because transpose() changes the storage order
+sm3 = SparseMatrixType(sm1.transpose()) + sm2;  // correct, because evaluation reformats as column-major
 \endcode
 
-Here are some examples of the supported operations:
+Here are some examples of supported operations:
 \code
-s_1 *= 0.5;
-sm4 = sm1 + sm2 + sm3;          // only if s_1, s_2 and s_3 have the same storage order
+sm1 *= 0.5;
+sm4 = sm1 + sm2 + sm3;          // only if sm1, sm2 and sm3 have the same storage order
 sm3 = sm1 * sm2;
 dv3 = sm1 * dv2;
 dm3 = sm1 * dm2;
 dm3 = dm2 * sm1;
-sm3 = sm1.cwiseProduct(sm2);    // only if s_1 and s_2 have the same storage order
+sm3 = sm1.cwiseProduct(sm2);    // only if sm1 and sm2 have the same storage order
 dv2 = sm1.triangularView<Upper>().solve(dv2);
 \endcode
 
-The product of a sparse symmetric matrix A with a dense matrix/vector dv can be optimized by telling that to Eigen:
+The product of a sparse \em symmetric matrix A with a dense matrix (or vector) d can be optimized by specifying the symmetry of A using selfadjointView:
 \code
-res = A.selfadjointView<>() * dv;        // if all coefficients of A are stored
-res = A.selfadjointView<Upper>() * dv;   // if only the upper part of A is stored
-res = A.selfadjointView<Lower>() * dv;   // if only the lower part of A is stored
+res = A.selfadjointView<>() * d;        // if all coefficients of A are stored
+res = A.selfadjointView<Upper>() * d;   // if only the upper part of A is stored
+res = A.selfadjointView<Lower>() * d;   // if only the lower part of A is stored
 \endcode
 
 
 \section TutorialSparseDirectSolvers Using the direct solvers
 
-To solve a sparse problem you currently have to use one or multiple of the following "unsupported" module:
+To solve a sparse problem you currently have to use one or several of the following "unsupported" modules:
 - \ref SparseExtra_Module
   - \b solvers: SparseLLT<SparseMatrixType>, SparseLDLT<SparseMatrixType> (\#include <Eigen/SparseExtra>)
   - \b notes: built-in basic LLT and LDLT solvers
@@ -230,7 +230,7 @@ To solve a sparse problem you currently have to use one or multiple of the follo
   - \b solver: SparseLLT<SparseMatrixType, Taucs> (\#include <Eigen/TaucsSupport>)
   - \b notes: LLT solving using Taucs, requires a SparseMatrix object (not recommended)
 
-\warning Those modules are currently considered to be "unsupported" because 1) they are not documented, and 2) their API is likely to change in the future.
+\warning Those modules are currently considered to be unsupported because 1) they are not documented, and 2) their API is likely to change in the future.
 
 Here is a typical example:
 \code
@@ -243,7 +243,7 @@ VectorXd b, x;
 // solve Ax = b using UmfPack:
 SparseLU<SparseMatrix<double>,UmfPack> lu_of_A(A);
 if(!lu_of_A.succeeded()) {
-  // decomposiiton failed
+  // decomposition failed
   return;
 }
 if(!lu_of_A.solve(b,&x)) {