Update e-mail address

3 files changed, 8 insertions, 58 deletions

diff --git a/doc/CustomizingEigen.dox b/doc/CustomizingEigen.dox
index f51c02e27..49ab4d961 100644
--- a/doc/CustomizingEigen.dox
+++ b/doc/CustomizingEigen.dox
@@ -2,7 +2,7 @@ namespace Eigen {
 
 /** \page CustomizingEigen Customizing/Extending Eigen
 
-Eigen2 can be extended in several way, for instance, by defining global methods, \ref ExtendingMatrixBase "by adding custom methods to MatrixBase", adding support to \ref CustomScalarType "custom types" etc.
+Eigen2 can be extended in several ways, for instance, by defining global methods, \ref ExtendingMatrixBase "by adding custom methods to MatrixBase", adding support to \ref CustomScalarType "custom types" etc.
 
 \b Table \b of \b contents
   - \ref ExtendingMatrixBase
diff --git a/doc/QuickStartGuide.dox b/doc/QuickStartGuide.dox
index 5e5959e18..9bb2fbe00 100644
--- a/doc/QuickStartGuide.dox
+++ b/doc/QuickStartGuide.dox
@@ -22,7 +22,7 @@ namespace Eigen {
   - \ref TutorialCoreTransposeAdjoint
   - \ref TutorialCoreDotNorm
   - \ref TutorialCoreTriangularMatrix
-  - \ref TutorialLazyEvaluation
+  - \ref TutorialCoreSpecialTopics
 \n
 
 <hr>
@@ -93,7 +93,7 @@ For dynamic-size, that is in order to left the number of rows or of columns unsp
 <a href="#" class="top">top</a>\section TutorialCoreMatrixInitialization Matrix and vector creation and initialization
 
 
-\subsection TutorialPredefMat PredefinedMatrix
+\subsection TutorialPredefMat Predefined Matrices
 Eigen offers several static methods to create special matrix expressions, and non-static methods to assign these expressions to existing matrices:
 
 <table class="tutorial_code">
@@ -509,63 +509,13 @@ vec1.normalize();\endcode
 
 todo
 
-<a href="#" class="top">top</a>\section TutorialLazyEvaluation Lazy evaluation of expressions
+<a href="#" class="top">top</a>\section TutorialCoreSpecialTopics Special Topics
 
-When you write a line of code involving a complex expression such as
+There are some \ref SpecialTopics "other topics" about which we suggest that you read.
 
-\code mat1 = mat2 + mat3 * (mat4 + mat5); \endcode
+In particular, thanks to expression templates, Eigen is able to apply \ref TopicLazyEvaluation "lazy evaluation" whenever that is beneficial.
 
-Eigen determines automatically, for each sub-expression, whether to evaluate it into a temporary variable. Indeed, in certain cases it is better to evaluate immediately a sub-expression into a temporary variable, while in other cases it is better to avoid that.
-
-A traditional math library without expression templates always evaluates all sub-expressions into temporaries. So with this code,
-
-\code vec1 = vec2 + vec3; \endcode
-
-a traditional library would evaluate \c vec2 + vec3 into a temporary \c vec4 and then copy \c vec4  into \c vec1. This is of course inefficient: the arrays are traversed twice, so there are a lot of useless load/store operations.
-
-Expression-templates-based libraries can avoid evaluating sub-expressions into temporaries, which in many cases results in large speed improvements. This is called <i>lazy evaluation</i> as an expression is getting evaluated as late as possible, instead of immediately. However, most other expression-templates-based libraries <i>always</i> choose lazy evaluation. There are two problems with that: first, lazy evaluation is not always a good choice for performance; second, lazy evaluation can be very dangerous, for example with matrix products: doing <tt>matrix = matrix*matrix</tt> gives a wrong result if the matrix product is lazy-evaluated, because of the way matrix product works.
-
-For these reasons, Eigen has intelligent compile-time mechanisms to determine automatically when to use lazy evaluation, and when on the contrary it should evaluate immediately into a temporary variable.
-
-So in the basic example,
-
-\code matrix1 = matrix2 + matrix3; \endcode
-
-Eigen chooses lazy evaluation. Thus the arrays are traversed only once, producing optimized code. If you really want to force immediate evaluation, use \link MatrixBase::eval() eval() \endlink:
-
-\code matrix1 = (matrix2 + matrix3).eval(); \endcode
-
-Here is now a more involved example:
-
-\code matrix1 = -matrix2 + matrix3 + 5 * matrix4; \endcode
-
-Eigen chooses lazy evaluation at every stage in that example, which is clearly the correct choice. In fact, lazy evaluation is the "default choice" and Eigen will choose it except in a few circumstances.
-
-<b>The first circumstance</b> in which Eigen chooses immediate evaluation, is when it sees an assignment <tt>a = b;</tt> and the expression \c b has the evaluate-before-assigning \link flags flag \endlink. The most importat example of such an expression is the \link Product matrix product expression \endlink. For example, when you do
-
-\code matrix = matrix * matrix; \endcode
-
-Eigen first evaluates <tt>matrix * matrix</tt> into a temporary matrix, and then copies it into the original \c matrix. This guarantees a correct result as we saw above that lazy evaluation gives wrong results with matrix products. It also doesn't cost much, as the cost of the matrix product itself is much higher.
-
-What if you know what you are doing and want to force lazy evaluation? Then use \link MatrixBase::lazy() .lazy() \endlink instead. Here is an example:
-
-\code matrix1 = (matrix2 * matrix2).lazy(); \endcode
-
-Here, since we know that matrix2 is not the same matrix as matrix1, we know that lazy evaluation is not dangerous, so we may force lazy evaluation. Concretely, the effect of lazy() here is to remove the evaluate-before-assigning \link flags flag \endlink and also the evaluate-before-nesting \link flags flag \endlink which we now discuss.
-
-<b>The second circumstance</b> in which Eigen chooses immediate evaluation, is when it sees a nested expression such as <tt>a + b</tt> where \c b is already an expression having the evaluate-before-nesting \link flags flag \endlink. Again, the most importat example of such an expression is the \link Product matrix product expression \endlink. For example, when you do
-
-\code matrix1 = matrix2 + matrix3 * matrix4; \endcode
-
-the product <tt>matrix3 * matrix4</tt> gets evaluated immediately into a temporary matrix. Indeed, experiments showed that it is often beneficial for performance to evaluate immediately matrix products when they are nested into bigger expressions.
-
-Again, \link MatrixBase::lazy() .lazy() \endlink can be used to force lazy evaluation here.
-
-<b>The third circumstance</b> in which Eigen chooses immediate evaluation, is when its cost model shows that the total cost of an operation is reduced if a sub-expression gets evaluated into a temporary. Indeed, in certain cases, an intermediate result is sufficiently costly to compute and is reused sufficiently many times, that is worth "caching". Here is an example:
-
-\code matrix1 = matrix2 * (matrix3 + matrix4); \endcode
-
-Here, provided the matrices have at least 2 rows and 2 columns, each coefficienct of the expression <tt>matrix3 + matrix4</tt> is going to be used several times in the matrix product. Instead of computing the sum everytime, it is much better to compute it once and store it in a temporary variable. Eigen understands this and evaluates <tt>matrix3 + matrix4</tt> into a temporary variable before evaluating the product.
+todo
 
 */
 
diff --git a/doc/tutorial.cpp b/doc/tutorial.cpp
index 6d3eb8bc2..62be7c270 100644
--- a/doc/tutorial.cpp
+++ b/doc/tutorial.cpp
@@ -52,7 +52,7 @@ int main(int argc, char *argv[])
   m4 = -m4 + m4 + 5 * m4; // same here, Eigen chooses lazy evaluation for all that.
   m4 = m4 * (m4 + m4); // here Eigen chooses to first evaluate m4 + m4 into a temporary.
                        // indeed, here it is an optimization to cache this intermediate result.
-  m3 = m3 * m4.block<3,3>(1,1); // here Eigen chooses NOT to evaluate transpose() into a temporary
+  m3 = m3 * m4.block<3,3>(1,1); // here Eigen chooses NOT to evaluate block() into a temporary
     // because accessing coefficients of that block expression is not more costly than accessing
     // coefficients of a plain matrix.
   m4 = m4 * m4.transpose(); // same here, lazy evaluation of the transpose.