improve ref tables

1 files changed, 83 insertions, 75 deletions

diff --git a/doc/QuickReference.dox b/doc/QuickReference.dox
index 47939e67b..fd08a4be0 100644
--- a/doc/QuickReference.dox
+++ b/doc/QuickReference.dox
@@ -75,11 +75,11 @@ Conversion between the matrix and array worlds:
 \code
 Array44f a1, a1;
 Matrix4f m1, m2;
-m1 = a1 * a2;           // OK, coeffwise product
-a1 = m1 * m2;           // OK, matrix product
-a2 = a1 + m1.array();
-m2 = a1.matrix() + m1;
-ArrayWrapper<Matrix4f> m1a(m1);  // m1a is an alias for m1.array(), they share the same coefficients
+m1 = a1 * a2;                     // coeffwise product, implicit conversion from array to matrix.
+a1 = m1 * m2;                     // matrix product, implicit conversion from matrix to array.
+a2 = a1 + m1.array();             // mixing array and matrix is forbidden
+m2 = a1.matrix() + m1;            // and explicit conversion is required.
+ArrayWrapper<Matrix4f> m1a(m1);   // m1a is an alias for m1.array(), they share the same coefficients
 MatrixWrapper<Array44f> a1m(a1);
 \endcode
 
@@ -99,7 +99,7 @@ Vector2f  v1(x, y);
 Array3i   v2(x, y, z);
 Vector4d  v3(x, y, z, w);
 
-VectorXf  v5;
+VectorXf  v5; // empty object
 ArrayXf   v6(size);
 \endcode</td><td>\code
 Matrix4f  m1;
@@ -107,11 +107,10 @@ Matrix4f  m1;
 
 
 
-MatrixXf  m5;
+MatrixXf  m5; // empty object
 MatrixXf  m6(nb_rows, nb_columns);
-\endcode</td><td>
-The coeffs are left uninitialized \n \n
- \n \n Empty object \n The coeffs are left uninitialized</td></tr>
+\endcode</td><td class="note">
+By default, the coefficients \n are left uninitialized</td></tr>
 <tr><td>Comma initializer</td>
 <td>\code
 Vector3f  v1;     v1 << x, y, z;
@@ -145,7 +144,7 @@ matrix.rows();          matrix.cols();
 matrix.innerSize();     matrix.outerSize();
 matrix.innerStride();   matrix.outerStride();
 matrix.data();
-\endcode</td><td>\n Inner/Outer* are storage order dependent</td></tr>
+\endcode</td><td class="note">\n Inner/Outer* are storage order dependent</td></tr>
 <tr><td>Compile-time info</td>
 <td colspan="2">\code
 ObjectType::Scalar              ObjectType::RowsAtCompileTime
@@ -165,7 +164,7 @@ matrix.resize(Eigen::NoChange, nb_cols);
 matrix.resize(nb_rows, Eigen::NoChange);
 matrix.resizeLike(other_matrix);
 matrix.conservativeResize(nb_rows, nb_cols);
-\endcode</td><td></td>no-op if the new sizes match,\n otherwise data are lost \n \n resizing with data preservation</tr>
+\endcode</td><td class="note">no-op if the new sizes match,\n otherwise data are lost \n \n resizing with data preservation</td></tr>
 
 <tr><td>Coeff access with \n range checking</td>
 <td>\code
@@ -175,7 +174,7 @@ vector[i]     vector.y()
               vector.w()
 \endcode</td><td>\code
 matrix(i,j)
-\endcode</td><td><em class="note">Range checking is disabled if \n NDEBUG or EIGEN_NO_DEBUG is defined</em></td></tr>
+\endcode</td><td class="note">Range checking is disabled if \n NDEBUG or EIGEN_NO_DEBUG is defined</td></tr>
 
 <tr><td>Coeff access without \n range checking</td>
 <td>\code
@@ -190,7 +189,7 @@ matrix.coeffRef(i,j)
 <td colspan="2">\code
 object = expression;
 object_of_float = expression_of_double.cast<float>();
-\endcode</td><td>the destination is automatically resized (if possible)</td></tr>
+\endcode</td><td class="note">the destination is automatically resized (if possible)</td></tr>
 
 </table>
 
@@ -289,27 +288,27 @@ VectorXf::Unit(4,1) == Vector4f(0,1,0,0)
 
 
 
-\subsection QuickRef_Map Map
+\subsection QuickRef_Map Mapping external arrays
 
 <table class="tutorial_code">
 <tr>
-<td>Contiguous memory</td>
+<td>Contiguous \n memory</td>
 <td>\code
 float data[] = {1,2,3,4};
-Map<Vector3f> v1(data);   // uses v1 as a Vector3f object
-Map<ArrayXf>  v2(data,3); // uses v2 as a ArrayXf object
-Map<Array22f> m1(data);     // uses m1 as a Array22f object
-Map<MatrixXf>  m2(data,2,2); // uses m2 as a MatrixXf object
+Map<Vector3f> v1(data);       // uses v1 as a Vector3f object
+Map<ArrayXf>  v2(data,3);     // uses v2 as a ArrayXf object
+Map<Array22f> m1(data);       // uses m1 as a Array22f object
+Map<MatrixXf> m2(data,2,2);   // uses m2 as a MatrixXf object
 \endcode</td>
 </tr>
 <tr>
-<td>Typical usage of strides</td>
+<td>Typical usage \n of strides</td>
 <td>\code
 float data[] = {1,2,3,4,5,6,7,8,9};
-Map<VectorXf,0,InnerStride<2> >  v1(data,3);                      // == [1,3,5]
-Map<VectorXf,0,InnerStride<> >   v2(data,3,InnerStride<>(3));     // == [1,4,7]
-Map<MatrixXf,0,OuterStride<> >   m1(data,2,3,OuterStride<>(3));   // == |1,4,7|
-Map<MatrixXf,0,OuterStride<3> >  m2(data,2,3);                    //    |2,5,8|
+Map<VectorXf,0,InnerStride<2> >  v1(data,3);                      // = [1,3,5]
+Map<VectorXf,0,InnerStride<> >   v2(data,3,InnerStride<>(3));     // = [1,4,7]
+Map<MatrixXf,0,OuterStride<3> >  m2(data,2,3);                    // both lines     |1,4,7|
+Map<MatrixXf,0,OuterStride<> >   m1(data,2,3,OuterStride<>(3));   // are equal to:  |2,5,8|
 \endcode</td>
 </tr>
 </table>
@@ -320,32 +319,32 @@ Map<MatrixXf,0,OuterStride<3> >  m2(data,2,3);                    //    |2,5,8|
 
 <table class="tutorial_code">
 <tr><td>
-add/subtract</td><td>\code
-mat3 = mat1 + mat2;      mat3 += mat1;
-mat3 = mat1 - mat2;      mat3 -= mat1;\endcode
+add \n subtract</td><td>\code
+mat3 = mat1 + mat2;           mat3 += mat1;
+mat3 = mat1 - mat2;           mat3 -= mat1;\endcode
 </td></tr>
 <tr><td>
 scalar product</td><td>\code
-mat3 = mat1 * s1;   mat3 = s1 * mat1;   mat3 *= s1;
-mat3 = mat1 / s1;   mat3 /= s1;\endcode
+mat3 = mat1 * s1;             mat3 *= s1;           mat3 = s1 * mat1;
+mat3 = mat1 / s1;             mat3 /= s1;\endcode
 </td></tr>
 <tr><td>
-matrix/vector product \matrixworld</td><td>\code
+matrix/vector \n products \matrixworld</td><td>\code
 col2 = mat1 * col1;
-row2 = row1 * mat1;     row1 *= mat1;
-mat3 = mat1 * mat2;     mat3 *= mat1; \endcode
+row2 = row1 * mat1;           row1 *= mat1;
+mat3 = mat1 * mat2;           mat3 *= mat1; \endcode
 </td></tr>
 <tr><td>
-transpose et adjoint \matrixworld</td><td>\code
+transposition \n adjoint \matrixworld</td><td>\code
 mat1 = mat2.transpose();      mat1.transposeInPlace();
 mat1 = mat2.adjoint();        mat1.adjointInPlace();
 \endcode
 </td></tr>
 <tr><td>
-\link MatrixBase::dot() dot \endlink \& inner products \matrixworld</td><td>\code
+\link MatrixBase::dot() dot \endlink product \n inner product \matrixworld</td><td>\code
+scalar = vec1.dot(vec2);
 scalar = col1.adjoint() * col2;
-scalar = (col1.adjoint() * col2).value();
-scalar = vec1.dot(vec2);\endcode
+scalar = (col1.adjoint() * col2).value();\endcode
 </td></tr>
 <tr><td>
 outer product \matrixworld</td><td>\code
@@ -353,7 +352,7 @@ mat = col1 * col2.transpose();\endcode
 </td></tr>
 
 <tr><td>
-\link MatrixBase::norm() norm \endlink and \link MatrixBase::normalized() normalization \endlink \matrixworld</td><td>\code
+\link MatrixBase::norm() norm \endlink \n \link MatrixBase::normalized() normalization \endlink \matrixworld</td><td>\code
 scalar = vec1.norm();         scalar = vec1.squaredNorm()
 vec2 = vec1.normalized();     vec1.normalize(); // inplace \endcode
 </td></tr>
@@ -400,7 +399,7 @@ array1 < array2     array1 > array2     array1 < scalar     array1 > scalar
 array1 <= array2    array1 >= array2    array1 <= scalar    array1 >= scalar
 array1 == array2    array1 != array2    array1 == scalar    array1 != scalar
 \endcode</td></tr>
-<tr><td>Special functions \n and STL variants</td><td>\code
+<tr><td>Trigo, power, and \n misc functions \n and the STL variants</td><td>\code
 array1.min(array2)            std::min(array1,array2)
 array1.max(array2)            std::max(array1,array2)
 array1.abs2()
@@ -424,7 +423,8 @@ array1.tan()                  std::tan(array1)
 
 Eigen provides several reduction methods such as:
 \link DenseBase::minCoeff() minCoeff() \endlink, \link DenseBase::maxCoeff() maxCoeff() \endlink,
-\link DenseBase::sum() sum() \endlink, \link MatrixBase::trace() trace() \endlink \matrixworld,
+\link DenseBase::sum() sum() \endlink, \link DenseBase::prod() prod() \endlink,
+\link MatrixBase::trace() trace() \endlink \matrixworld,
 \link MatrixBase::norm() norm() \endlink \matrixworld, \link MatrixBase::squaredNorm() squaredNorm() \endlink \matrixworld,
 \link DenseBase::all() all() \endlink \redstar,and \link DenseBase::any() any() \endlink \redstar.
 All reduction operations can be done matrix-wise,
@@ -444,14 +444,21 @@ mat = 2 7 8
 \endcode</td></tr>
 </table>
 
-Also note that maxCoeff and minCoeff can takes optional arguments returning the coordinates of the respective min/max coeff: \link DenseBase::maxCoeff(int*,int*) const maxCoeff(int* i, int* j) \endlink, \link DenseBase::minCoeff(int*,int*) const minCoeff(int* i, int* j) \endlink.
-
-<span class="note">\b Side \b note: The all() and any() functions are especially useful in combination with coeff-wise comparison operators.</span>
-
+Special versions of \link DenseBase::minCoeff(int*,int*) minCoeff \endlink and \link DenseBase::maxCoeff(int*,int*) maxCoeff \endlink:
+\code
+int i, j;
+s = vector.minCoeff(&i);        // s == vector[i]
+s = matrix.maxCoeff(&i, &j);    // s == matrix(i,j)
+\endcode
+Typical use cases of all() and any():
+\code
+if((array1 > 0).all()) ...      // if all coefficients of array1 are greater than 0 ...
+if((array1 < array2).any()) ... // if there exist a pair i,j such that array1(i,j) < array2(i,j) ...
+\endcode
 
 
 
-<a href="#" class="top">top</a>\section QuickRef_Blocks Matrix blocks
+<a href="#" class="top">top</a>\section QuickRef_Blocks Sub-matrices
 
 Read-write access to a \link DenseBase::col(int) column \endlink
 or a \link DenseBase::row(int) row \endlink of a matrix (or array):
@@ -501,7 +508,7 @@ Read-write access to sub-matrices:</td><td></td><td></td></tr>
  mat1.bottomRows<rows>()
  mat1.leftCols<cols>()
  mat1.rightCols<cols>()\endcode
- <td>specialized versions of block() when the block fit two corners</td></tr>
+ <td>specialized versions of block() \n when the block fit two corners</td></tr>
 </table>
 
 
@@ -514,7 +521,7 @@ Read-write access to sub-matrices:</td><td></td><td></td></tr>
 
 <table class="tutorial_code">
 <tr><td>
-\link MatrixBase::asDiagonal() make a diagonal matrix \endlink \n from a vector </td><td>\code
+view a vector \link MatrixBase::asDiagonal() as a diagonal matrix \endlink \n </td><td>\code
 mat1 = vec1.asDiagonal();\endcode
 </td></tr>
 <tr><td>
@@ -522,13 +529,13 @@ Declare a diagonal matrix</td><td>\code
 DiagonalMatrix<Scalar,SizeAtCompileTime> diag1(size);
 diag1.diagonal() = vector;\endcode
 </td></tr>
-<tr><td>Access \link MatrixBase::diagonal() the diagonal and super/sub diagonals of a matrix \endlink as a vector (read/write)</td>
+<tr><td>Access the \link MatrixBase::diagonal() diagonal \endlink and \link MatrixBase::diagonal(int) super/sub diagonals \endlink of a matrix as a vector (read/write)</td>
  <td>\code
-vec1 = mat1.diagonal();            mat1.diagonal() = vec1;      // main diagonal
-vec1 = mat1.diagonal(+n);          mat1.diagonal(+n) = vec1;    // n-th super diagonal
-vec1 = mat1.diagonal(-n);          mat1.diagonal(-n) = vec1;    // n-th sub diagonal
-vec1 = mat1.diagonal<1>();         mat1.diagonal<1>() = vec1;   // first super diagonal
-vec1 = mat1.diagonal<-2>();        mat1.diagonal<-2>() = vec1;  // second sub diagonal
+vec1 = mat1.diagonal();        mat1.diagonal() = vec1;      // main diagonal
+vec1 = mat1.diagonal(+n);      mat1.diagonal(+n) = vec1;    // n-th super diagonal
+vec1 = mat1.diagonal(-n);      mat1.diagonal(-n) = vec1;    // n-th sub diagonal
+vec1 = mat1.diagonal<1>();     mat1.diagonal<1>() = vec1;   // first super diagonal
+vec1 = mat1.diagonal<-2>();    mat1.diagonal<-2>() = vec1;  // second sub diagonal
 \endcode</td>
 </tr>
 
@@ -545,13 +552,12 @@ mat3 = mat1 * diag1.inverse()
 
 \subsection QuickRef_TriangularView Triangular views
 
-TriangularView allows to get views on a triangular part of a dense matrix and perform optimized operations on it. The opposite triangular is never referenced and can be
-used to store other information.
+TriangularView gives a view on a triangular part of a dense matrix and allows to perform optimized operations on it. The opposite triangular part is never referenced and can be used to store other information.
 
 <table class="tutorial_code">
 <tr><td>
-Reference a read/write triangular part of a given \n
-matrix (or expression) m with optional unit diagonal:
+Reference to a triangular with optional \n
+unit or null diagonal (read/write):
 </td><td>\code
 m.triangularView<Xxx>()
 \endcode \n
@@ -574,19 +580,21 @@ m3 += s1 * m1.adjoint().triangularView<Eigen::UnitUpper>() * m2
 m3 -= s1 * m2.conjugate() * m1.adjoint().triangularView<Eigen::Lower>() \endcode
 </td></tr>
 <tr><td>
-Solving linear equations:\n(\f$ m_2 := m_1^{-1} m_2 \f$)
-</td><td>\code
-m1.triangularView<Eigen::UnitLower>().solveInPlace(m2)
-m1.adjoint().triangularView<Eigen::Upper>().solveInPlace(m2)\endcode
+Solving linear equations:\n
+\f$ M_2 := L_1^{-1} M_2 \f$ \n
+\f$ M_3 := {L_1^*}^{-1} M_3 \f$ \n
+\f$ M_4 := M_3 U_1^{-1} \f$
+</td><td>\n \code
+L1.triangularView<Eigen::UnitLower>().solveInPlace(M2)
+L1.triangularView<Eigen::Lower>().adjoint().solveInPlace(M3)
+U1.triangularView<Eigen::Upper>().solveInPlace<OnTheRight>(M4)\endcode
 </td></tr>
 </table>
 
-
-
 \subsection QuickRef_SelfadjointMatrix Symmetric/selfadjoint views
 
-Just as for triangular matrix, you can reference any triangular part of a square matrix to see it a selfadjoint
-matrix and perform special and optimized operations. Again the opposite triangular is never referenced and can be
+Just as for triangular matrix, you can reference any triangular part of a square matrix to see it as a selfadjoint
+matrix and perform special and optimized operations. Again the opposite triangular part is never referenced and can be
 used to store other information.
 
 <table class="tutorial_code">
@@ -602,26 +610,26 @@ m3  = s1 * m1.conjugate().selfadjointView<Eigen::Upper>() * m3;
 m3 -= s1 * m3.adjoint() * m1.selfadjointView<Eigen::Lower>();\endcode
 </td></tr>
 <tr><td>
-Rank 1 and rank K update:
-</td><td>\code
-// fast version of m1 += s1 * m2 * m2.adjoint():
-m1.selfadjointView<Eigen::Upper>().rankUpdate(m2,s1);
-// fast version of m1 -= m2.adjoint() * m2:
+Rank 1 and rank K update: \n
+\f$ upper(M_1) += s1 M_2^* M_2 \f$ \n
+\f$ lower(M_1) -= M_2 M_2^* \f$
+</td><td>\n \code
+M1.selfadjointView<Eigen::Upper>().rankUpdate(M2,s1);
 m1.selfadjointView<Eigen::Lower>().rankUpdate(m2.adjoint(),-1); \endcode
 </td></tr>
 <tr><td>
-Rank 2 update: (\f$ m += s u v^* + s v u^* \f$)
+Rank 2 update: (\f$ M += s u v^* + s v u^* \f$)
 </td><td>\code
-m.selfadjointView<Eigen::Upper>().rankUpdate(u,v,s);
+M.selfadjointView<Eigen::Upper>().rankUpdate(u,v,s);
 \endcode
 </td></tr>
 <tr><td>
-Solving linear equations:\n(\f$ m_2 := m_1^{-1} m_2 \f$)
+Solving linear equations:\n(\f$ M_2 := M_1^{-1} M_2 \f$)
 </td><td>\code
 // via a standard Cholesky factorization
-m1.selfadjointView<Eigen::Upper>().llt().solveInPlace(m2);
+m2 = m1.selfadjointView<Eigen::Upper>().llt().solve(m2);
 // via a Cholesky factorization with pivoting
-m1.selfadjointView<Eigen::Upper>().ldlt().solveInPlace(m2);
+m2 = m1.selfadjointView<Eigen::Lower>().ldlt().solve(m2);
 \endcode
 </td></tr>
 </table>