big improvements to tutorial, especially page 2 (matrix arithmetic).

add placeholders for some 'special topic' pages.

16 files changed, 348 insertions, 200 deletions

diff --git a/doc/C00_QuickStartGuide.dox b/doc/C00_QuickStartGuide.dox
index c107f3664..3c2ccc39a 100644
--- a/doc/C00_QuickStartGuide.dox
+++ b/doc/C00_QuickStartGuide.dox
@@ -3,7 +3,7 @@ namespace Eigen {
 /** \page GettingStarted Getting started
     \ingroup Tutorial
 
-This is a very short guide on how to get started with Eigen. It is intended for people who do not like to read long documents and want to start coding as soon as possible. The \ref TutorialCore "Tutorial" is a longer document wich goes in more detail.
+This is a very short guide on how to get started with Eigen. It is intended for people who do not like to read long documents and want to start coding as soon as possible. The \ref TutorialMatrixClass "Tutorial" is a longer document wich goes in more detail.
 
 \section GettingStartedInstallation How to "install" Eigen?
 
@@ -92,7 +92,8 @@ The use of fixed-size matrices and vectors has two advantages. The compiler emit
 
 \section GettingStartedConclusion Where to go from here?
 
-This short introduction should be enough that you can start coding, while referring to the tables to find the functions you need. Alternatively, you can read the longer \ref TutorialCore "Tutorial" in which the Eigen library is explained in more detail. 
+You could directly use our reference tables and class documentation, or if you do not yet feel ready for that, you could
+read the longer \ref TutorialMatrixClass "Tutorial" in which the Eigen library is explained in more detail.
 
 */
 
diff --git a/doc/C01_TutorialMatrixClass.dox b/doc/C01_TutorialMatrixClass.dox
index c73bbf5cc..da6e2d44f 100644
--- a/doc/C01_TutorialMatrixClass.dox
+++ b/doc/C01_TutorialMatrixClass.dox
@@ -1,21 +1,36 @@
 namespace Eigen {
 
-o /** \page tut_matrix Tutorial page 1 - the Matrix class
+/** \page TutorialMatrixClass Tutorial page 1 - the %Matrix class
 
 \ingroup Tutorial
 
+\li \b Previous: \ref GettingStarted
+\li \b Next: \ref TutorialMatrixArithmetic
+
 We assume that you have already read the \ref GettingStarted "quick \"getting started\" tutorial.
 This page is the first one in a much longer multi-page tutorial.
 
+\b Table \b of \b contents
+  - \ref TutorialMatrixFirst3Params
+  - \ref TutorialMatrixVectors
+  - \ref TutorialMatrixDynamic
+  - \ref TutorialMatrixConstructors
+  - \ref TutorialMatrixCoeffAccessors
+  - \ref TutorialMatrixSizesResizing
+  - \ref TutorialMatrixAssignment
+  - \ref TutorialMatrixFixedVsDynamic
+  - \ref TutorialMatrixOptTemplParams
+  - \ref TutorialMatrixTypedefs
+
 In Eigen, all matrices and vectors are object of the Matrix class.
 Vectors are just a special case of matrices, with either 1 row or 1 column.
 
-\section tut_matrix_class The Matrix class
+\section TutorialMatrixFirst3Params The first 3 template parameters of Matrix
 
 The Matrix class takes 6 template parameters, but for now it's enough to
 learn about the 3 first parameters. The 3 remaining parameters have default
 values, which for now we will leave untouched, and which we
-\ref tut_matrix_3_last_template_params "discuss below".
+\ref TutorialMatrixOptTemplParams "discuss below".
 
 The 3 mandatory template parameters of Matrix are:
 \code
@@ -23,7 +38,7 @@ Matrix<typename Scalar, int RowsAtCompileTime, int ColsAtCompileTime>
 \endcode
 \li \c Scalar is the scalar type, i.e. the type of the coefficients.
     That is, if you want a matrix of floats, choose \c float here.
-    See \ref topic_scalar_types "Scalar types" for a list of all supported
+    See \ref TopicScalarTypes "Scalar types" for a list of all supported
     scalar types and for how to extend support to new types.
 \li \c RowsAtCompileTime and \c ColsAtCompileTime are the number of rows
     and columns of the matrix as known at compile-time.
@@ -33,9 +48,9 @@ a 4x4 matrix of floats. Here is how it is defined by Eigen:
 \code
 typedef Matrix<float,4,4> Matrix4f;
 \endcode
-We discuss \ref tut_matrix_typedefs "below" these convenience typedefs.
+We discuss \ref TutorialMatrixTypedefs "below" these convenience typedefs.
 
-\section tut_matrix_vectors Vectors
+\section TutorialMatrixVectors Vectors
 
 As mentioned above, in Eigen, vectors are just a special case of
 matrices, with either 1 row or 1 column. The case where they have 1 column is the most common;
@@ -51,7 +66,7 @@ and we also offer convenience typedefs for row-vectors, for example:
 typedef Matrix<int, 1, 2> RowVector2i;
 \endcode
 
-\section tut_matrix_dynamic The special value Dynamic
+\section TutorialMatrixDynamic The special value Dynamic
 
 Of course, Eigen is not limited to matrices whose dimensions are known at compile time.
 The above-discussed \c RowsAtCompileTime and \c ColsAtCompileTime can take the special
@@ -72,7 +87,7 @@ You can perfectly have e.g. a fixed number of rows with a dynamic number of colu
 Matrix<float, 3, Dynamic>
 \endcode
 
-\section tut_matrix_constructors Constructors
+\section TutorialMatrixConstructors Constructors
 
 A default constructor is always available, and always has zero runtime cost. You can do:
 \code
@@ -109,7 +124,7 @@ Vector3d b(5.0, 6.0, 7.0);
 Vector4d c(5.0, 6.0, 7.0, 8.0);
 \endcode
 
-\section tut_matrix_coefficient_accessors Coefficient accessors
+\section TutorialMatrixCoeffAccessors Coefficient accessors
 
 The primary coefficient accessors and mutators in Eigen are the overloaded parenthesis operators.
 For matrices, the row index is always passed first. For vectors, just pass one index.
@@ -123,20 +138,20 @@ m(index)
 \endcode
 is not restricted to vectors, it is also available for general matrices, meaning index-based access
 in the array of coefficients. This however depends on the matrix's storage order. All Eigen matrices default to
-column-major storage order, but this can be changed to row-major, see \ref topic_storage_orders "Storage orders".
+column-major storage order, but this can be changed to row-major, see \ref TopicStorageOrders "Storage orders".
 
 The operator[] is also overloaded for index-based access in vectors, but keep in mind that C++ doesn't allow operator[] to
 take more than one argument. We restrict operator[] to vectors, because an awkwardness in the C++ language
 would make matrix[i,j] compile to the same thing as matrix[j] !
 
-\section tut_matrix_sizes_and_resizing Resizing
+\section TutorialMatrixSizesResizing Resizing
 
 The current sizes can be retrieved by rows(), cols() and size(). Resizing a dynamic-size matrix is done by the resize() method.
 For example: \include tut_matrix_resize.cpp
 Output: \verbinclude tut_matrix_resize.out
 
 The resize() method is a no-operation if the actual array size doesn't change; otherwise it is destructive.
-If you want a conservative variant of resize(), use conservativeResize().
+If you want a conservative variant of resize(), use conservativeResize(), see \ref TopicResizing "this page" for more details.
 
 All these methods are still available on fixed-size matrices, for the sake of API uniformity. Of course, you can't actually
 resize a fixed-size matrix. Trying to change a fixed size to an actually different value will trigger an assertion failure;
@@ -144,9 +159,22 @@ but the following code is legal:
 \include tut_matrix_resize_fixed_size.cpp
 Output: \verbinclude tut_matrix_resize_fixed_size.out
 
-\section tut_matrix_fixed_vs_dynamic Fixed vs. Dynamic size
+\section TutorialMatrixAssignment Assignment and resizing
+
+Assignment is the action of copying a matrix into another, using \c operator=. The only non-obvious thing to know here, is that
+Eigen does automatic resizing of the left hand side to match the right hand side's size. For example:
+\include tut_matrix_assignment_resizing.cpp
+Output: \verbinclude tut_matrix_assignment_resizing.out
+
+Of course, if the left hand side is of fixed size, resizing it is not allowed.
 
-When should one use fixed sizes (e.g. \c Matrix4f), and when should one prefer dynamic sizes (e.g. \c MatrixXf) ?
+If you do not want this automatic resizing to happen (for example for debugging purposes), you can disable it, see
+\ref TopicResizing "this page".
+
+
+\section TutorialMatrixFixedVsDynamic Fixed vs. Dynamic size
+
+When should one use fixed sizes (e.g. \c Matrix4f), and when should one prefer dynamic sizes (e.g. \c MatrixXf)?
 The simple answer is: use fixed
 sizes for very small sizes where you can, and use dynamic sizes for larger sizes or where you have to. For small sizes,
 especially for sizes smaller than (roughly) 16, using fixed sizes is hugely beneficial
@@ -169,9 +197,9 @@ greater than (roughly) 32, the performance benefit of using fixed sizes becomes
 Worse, trying to create a very large matrix using fixed sizes could result in a stack overflow,
 since Eigen will try to allocate the array as a static array, which by default goes on the stack.
 Finally, depending on circumstances, Eigen can also be more aggressive trying to vectorize
-(use SIMD instructions) when dynamic sizes are used, see \ref topic_vectorization "Vectorization".
+(use SIMD instructions) when dynamic sizes are used, see \ref TopicVectorization "Vectorization".
 
-\section tut_matrix_optional_template_params Optional template parameters
+\section TutorialMatrixOptTemplParams Optional template parameters
 
 We mentioned at the beginning of this page that the Matrix class takes 6 template parameters,
 but so far we only discussed the first 3. The remaining 3 parameters are optional. Here is
@@ -186,7 +214,7 @@ Matrix<typename Scalar,
 \endcode
 \li \c Options is a bit field; let us only mention here one bit: \c RowMajor. It specifies that the matrices
       of this type use row-major storage order; the default is column-major. See the page on
-      \ref topic_storage_orders "storage orders". For example, this type means row-major 3x3 matrices:
+      \ref TopicStorageOrders "storage orders". For example, this type means row-major 3x3 matrices:
       \code
       Matrix<float,3,3,RowMajor>
       \endcode
@@ -198,7 +226,7 @@ Matrix<typename Scalar,
       Matrix<float,Dynamic,Dynamic,0,3,4>
       \endcode
 
-\section tut_matrix_typedefs Convenience typedefs
+\section TutorialMatrixTypedefs Convenience typedefs
 
 Eigen defines the following Matrix typedefs:
 \li MatrixNT for Matrix<T, N, N>. For example, MatrixXi for Matrix<int, Dynamic, Dynamic>.
@@ -210,7 +238,9 @@ Where:
 \li T can be any one of \c i (meaning int), \c f (meaning float), \c d (meaning double),
       \c cf (meaning complex<float>), or \c cd (meaning complex<double>). The fact that typedefs are only
     defined for these 5 types doesn't mean that they are the only supported scalar types. For example,
-    all standard integer types are supported, see \ref topic_scalar_types "Scalar types".
+    all standard integer types are supported, see \ref TopicScalarTypes "Scalar types".
+
+\li \b Next: \ref TutorialMatrixArithmetic
 
 */
 
diff --git a/doc/C02_TutorialMatrixArithmetic.dox b/doc/C02_TutorialMatrixArithmetic.dox
index 431ef595e..10156d575 100644
--- a/doc/C02_TutorialMatrixArithmetic.dox
+++ b/doc/C02_TutorialMatrixArithmetic.dox
@@ -1,202 +1,125 @@
 namespace Eigen {
 
-/** \page TutorialMatrixArithmetic Tutorial - Matrix and vector arithmetic
+/** \page TutorialMatrixArithmetic Tutorial page 2 - %Matrix and vector arithmetic
     \ingroup Tutorial
 
-This tutorial aims to provide an overview and some details on how to perform arithmetic between matrices, vectors and scalars with Eigen.
+\li \b Previous: \ref TutorialMatrixClass
+\li \b Next: \ref TutorialArrayClass
 
-\b Table \b of \b contents
-  - \ref TutorialMatrixArithmCommaInitializer
-  - \ref TutorialMatrixArithmElementaryOperations
-    - \ref TutorialMatrixArithmExamples
-    - \ref TutorialMatrixArithmProduct
-    - \ref TutorialMatrixArithmSimpleExample
-    - \ref TutorialMatrixCombiningOperators
-    - \ref TutorialMatrixOperatorValidity
-  - \ref TutorialMatrixArithmReductionOperations
-
-
-\section TutorialMatrixArithmCommaInitializer Comma initializer
-Eigen offers a comma initializer syntax which allows to set all the coefficients of any dense objects (matrix, vector, array, block, etc.) to specific values:
-<table class="tutorial_code"><tr><td>
-\code Matrix3f m;
-m << 1, 2, 3,
-     4, 5, 6,
-     7, 8, 9;
-cout << m;
-\endcode
-</td>
-<td>
-output:
-\code
-1 2 3
-4 5 6
-7 8 9
-\endcode
-</td></tr></table>
-
-Moreover, Eigen also supports to load a matrix through a set of blocks:
-<table class="tutorial_code"><tr><td>
-\code
-int rows=5, cols=5;
-MatrixXf m(rows,cols);
-m << (Matrix3f() << 1, 2, 3, 4, 5, 6, 7, 8, 9).finished(),
-     MatrixXf::Zero(3,cols-3),
-     MatrixXf::Zero(rows-3,3),
-     MatrixXf::Identity(rows-3,cols-3);
-cout << m;
-\endcode
-</td>
-<td>
-output:
-\code
-1 2 3 0 0
-4 5 6 0 0
-7 8 9 0 0
-0 0 0 1 0
-0 0 0 0 1
-\endcode
-</td></tr></table>
-
-FIXME: is this still needed?
-<span class="note">\b Side \b note: here \link CommaInitializer::finished() .finished() \endlink
-is used to get the actual matrix object once the comma initialization
-of our temporary submatrix is done. Note that despite the apparent complexity of such an expression,
-Eigen's comma initializer usually compiles to very optimized code without any overhead.</span>
-
-\section TutorialMatrixArithmElementaryOperations Basic arithmetic operators
-
-Eigen takes advantage of C++ operator overloading to make arithmetic operations intuitive. In the case of matrices and vectors, Eigen only supports arithmetic operations that have a linear-algebraic meaning. Therefore, adding an scalar to a vector or matrix cannot be written as \p scalar \p + \p matrix . Nonetheless, Eigen provides an Array class that is able to perform other types of operations such as column-wise and row-wise addition, substraction, etc. For more information see FIXME:link to Array class.
-
-\subsection TutorialMatrixArithmExamples Usage examples
-Some basic examples are presented in the following table, showing how easy it is to express arithmetic operations with Eigen.
-
-<table class="tutorial_code" align="center">
-<tr><td>
-matrix/vector product \matrixworld</td><td>\code
-col2 = mat1 * col1;
-row2 = row1 * mat1;     row1 *= mat1;
-mat3 = mat1 * mat2;     mat3 *= mat1; \endcode
-</td></tr>
-<tr><td>
-add/subtract</td><td>\code
-mat3 = mat1 + mat2;      mat3 += mat1;
-mat3 = mat1 - mat2;      mat3 -= mat1;\endcode
-</td></tr>
-<tr><td>
-scalar product/division</td><td>\code
-mat3 = mat1 * s1;   mat3 = s1 * mat1;   mat3 *= s1;
-mat3 = mat1 / s1;   mat3 /= s1;\endcode
-</td></tr>
-</table>
-
-\subsection TutorialMatrixArithmProduct	Product types
-It is important to point out that the product operation can be understood in different ways between matrices and vectors. Eigen treats the \p * \operator as matrix product or multiplication by a scalar. However, dot and cross products are also supported through the \p .dot() and \p .cross() operations:
+This tutorial aims to provide an overview and some details on how to perform arithmetic
+between matrices, vectors and scalars with Eigen.
 
+\b Table \b of \b contents
+  - \ref TutorialArithmeticIntroduction
+  - \ref TutorialArithmeticMentionCommaInitializer
+  - \ref TutorialArithmeticAddSub
+  - \ref TutorialArithmeticScalarMulDiv
+  - \ref TutorialArithmeticMentionXprTemplates
+  - \ref TutorialArithmeticMatrixMul
+  - \ref TutorialArithmeticDotAndCross
+  - \ref TutorialArithmeticRedux
+  - \ref TutorialArithmeticValidity
+
+\section TutorialArithmeticIntroduction Introduction
+
+Eigen offers matrix/vector arithmetic operations either through overloads of common C++ arithmetic operators such as +, -, *,
+or through special methods such as dot(), cross(), etc.
+For the Matrix class (matrices and vectors), operators are only overloaded to support
+linear-algebraic operations. For example, \c matrix1 \c * \c matrix2 means matrix-matrix product,
+and \c vector \c + \c scalar is just not allowed. If you want to perform all kinds of array operations,
+not linear algebra, see \ref TutorialArrayClass "next page".
+
+\section TutorialArithmeticMentionCommaInitializer A note about comma-initialization
+
+In examples below, we'll be initializing matrices with a very convenient device known as the \em comma-initializer.
+For now, it is enough to know this example:
+\include Tutorial_commainit_01.cpp
+Output: \verbinclude Tutorial_commainit_01.out
+The comma initializer is discussed in \ref TutorialAdvancedInitialization "this page".
+
+\section TutorialArithmeticAddSub Addition and substraction
+
+The left hand side and right hand side must, of course, have the same numbers of rows and of columns. They must
+also have the same \c Scalar type, as Eigen doesn't do automatic type promotion. The operators at hand here are:
+\li binary operator + as in \c a+b
+\li binary operator - as in \c a-b
+\li unary operator - as in \c -a
+\li compound operator += as in \c a+=b
+\li compound operator -= as in \c a-=b
+
+Example: \include tut_arithmetic_add_sub.cpp
+Output: \verbinclude tut_arithmetic_add_sub.out
+
+\section TutorialArithmeticScalarMulDiv Scalar multiplication and division
+
+Multiplication and division by a scalar is very simple too. The operators at hand here are:
+\li binary operator * as in \c matrix*scalar
+\li binary operator * as in \c scalar*matrix
+\li binary operator / as in \c matrix/scalar
+\li compound operator *= as in \c matrix*=scalar
+\li compound operator /= as in \c matrix/=scalar
+
+Example: \include tut_arithmetic_scalar_mul_div.cpp
+Output: \verbinclude tut_arithmetic_scalar_mul_div.out
+
+\section TutorialArithmeticMentionXprTemplates A note about expression templates
+
+This is an advanced topic that we explain in \ref TopicEigenExpressionTemplates "this page",
+but it is useful to just mention it now. In Eigen, arithmetic operators such as \c operator+ don't
+perform any computation by themselves, they just return an "expression object" describing the computation to be
+performed. The actual computation happens later, when the whole expression is evaluated, typically in \c operator=.
+While this might sound heavy, any modern optimizing compiler is able to optimize away that abstraction and
+the result is perfectly optimized code. For example, when you do:
 \code
-  Matrix3f	m1,m2,m3;
-  Vector3f	v1,v2,v3;
-  
-  // matrix product
-  m1 = m2 * m3;
-  
-  // vector cross product: v1 = v2 X v3
-  v1 = v2.cross(v3);
-  
-  // vector dot product: v2 . v3 (returns scalar)
-  float dotResult = v2.dot(v3);  
+VectorXf a(50), b(50), c(50), d(50);
+...
+a = 3*b + 4*c + 5*d;
 \endcode
-
-<strong> Note:</strong> cross product is only defined for 3-dimensional vectors.
-
-\subsection TutorialMatrixArithmSimpleExample A simple example with matrix linear algebra
-
-The next piece of code shows a simple program that creates two dynamic 3x3 matrices and initializes them, performing some simple operations and displaying the results at each step.
-
+Eigen compiles it to just one for loop, so that the arrays are traversed only once. Simplyfying (e.g. ignoring
+SIMD optimizations), this loop looks like this:
 \code
-  #include <Eigen/Dense>
-  #include <iostream>
-  
-  using namespace Eigen;
-  
-  int main()
-  {
-    MatrixXf	m(3,3);	// Matrix m is 3x3
-    VectorXf	n(3,3);	// 3-component vector
-    
-    m << 1,2,3,		// Assign some values to m
-         4,5,6,
-         7,8,9;
-         
-    n << 10,11,12,	// Assign some values to n
-         13,14,15,
-         16,17,18;
-
-         
-    // simple matrix-product-scalar
-    std::cout << "3*m = " << 3*m << std::endl;
-
-    // simple matrix-divided-by-scalar
-    std::cout << "m/3 = " << m/3 << std::endl;
-    
-    // matrix multiplication
-    std::cout << "m*n = " << m*n << std::endl;
-    
-    return 0;
-  }
+for(int i = 0; i < 50; ++i)
+  a[i] = 3*b[i] + 4*c[i] + 5*d[i];
 \endcode
+Thus, you should not be afraid of using relatively large arithmetic expressions with Eigen: it only gives Eigen
+more opportunities for optimization.
 
+\section TutorialArithmeticMatrixMul Matrix-matrix and matrix-vector multiplication
 
-\subsection TutorialMatrixCombiningOperators Combining operators in a single statement
+Matrix-matrix multiplication is again done with \c operator*. Since vectors are a special
+case of matrices, they are implicitly handled there too, so matrix-vector product is really just a special
+case of matrix-matrix product, and so is vector-vector outer product. Thus, all these cases are handled by just
+two operators:
+\li binary operator * as in \c a*b
+\li compound operator *= as in \c a*=b
 
-As said before, Eigen's classes already provide implementations for linear-algebra operations. Combining operators in more complex expressions is posssible and often desirable, since it may help to avoid temporary memory allocations, making code execution faster (FIXME: add reference to lazy evaluation?) :
+Example: \include tut_arithmetic_matrix_mul.cpp
+Output: \verbinclude tut_arithmetic_matrix_mul.out
 
+Note: if you read the above paragraph on expression templates and are worried that doing \c m=m*m might cause
+aliasing issues, be reassured for now: Eigen treats matrix multiplication as a special case and takes care of
+introducing a temporary here, so it will compile \c m=m*m as:
 \code
-  MatrixXf	m(3,3), n(3,3);
-  MatrixXf	q(3,3), p(3,3);
-  
-  // initialize... etc
-  .....
-  
-  // METHOD 1: use temporary allocation
-  {
-    MatrixXf	tempMatrix;
-
-    tempMatrix = m + 3*n;
-    p = tempMatrix * q;
-  }
-
-  // METHOD 2: avoids extra memory allocation if possible
-  // (Eigen will take care of that automatically)
-  p = (m + 3*n) * q;	// matrix addition and multiplication by a vector
-  
+tmp = m*m;
+m = tmp;
 \endcode
+For more details on this topic, see \ref TopicEigenExpressionTemplates "this page".
 
-Eigen will try to do its best in order to avoid temporary allocation and evaluate the expressions as fast as possible. FIXME: anything else to say here, is this correct?
+\section TutorialArithmeticDotAndCross Dot product and cross product
 
+The above-discussed \c operator* does not allow to compute dot and cross products. For that, you need the dot() and cross() methods.
+Example: \include tut_arithmetic_dot_cross.cpp
+Output: \verbinclude tut_arithmetic_dot_cross.out
 
-\subsection TutorialMatrixOperatorValidity Validity of operations
-The validity of the operations between matrices depend on the data type. In order to report whether an operation is valid or not, Eigen makes use of both compile-time and run-time information. In the case that the size of the matrices and vectors involved in the operations are known at compile time (fixed-size matrices such as \p Matrix3f), Eigen will be able to perfom a compile-time check and stop the compiler with an error if one of the operations is not possible:
+Remember that cross product is only for vectors of size 3. Dot product is for vectors of any sizes.
+When using complex numbers, Eigen's dot product is conjugate-linear in the first variable and linear in the
+second variable.
 
-\code
-  Matrix3f m;
-  Vector4f v;
-  
-  v = m*v;	// Compile-time error: YOU_MIXED_MATRICES_OF_DIFFERENT_SIZES
-\endcode
-
-On the other hand, operations between dynamic-size matrices will take place at run-time, generating a run-time assertion if invalid operands are detected. FIXME: link to how to change the handler?
+\section TutorialArithmeticRedux Basic arithmetic reduction operations
+Eigen also provides some reduction operations to obtain values such as the sum or the maximum
+or minimum of all the coefficients in a given matrix or vector.
 
-\code
-  MatrixXf	m(3,3);
-  VectorXf	v(4);
-  
-  v = m * v;	// Run-time assertion: "invalid matrix product"
-\endcode
-
-
-\section TutorialMatrixArithmReductionOperations Basic arithmetic reduction operations
-Eigen also provides some basic but extremely useful reduction arithmetic operators to obtain values such as the sum or the maximum or minimum of all the coefficients in a given matrix or vector. The following table presents the basic arithmetic reduction operations and their syntax.
+TODO: convert this from table format to tutorial/examples format.
 
 <table class="tutorial_code" align="center">
 <tr><td align="center">\b Reduction \b operation</td><td align="center">\b Usage \b example</td></tr>
@@ -239,8 +162,29 @@ MatrixXf m;
 float trace = m.trace();\endcode</td></tr>
 </table>
 
+\subsection TutorialArithmeticValidity Validity of operations
+Eigen checks the validity of the operations that you perform. When possible,
+it checks them at compile-time, producing compilation errors. These error messages can be long and ugly,
+but Eigen writes the important message in UPPERCASE_LETTERS_SO_IT_STANDS_OUT. For example:
+\code
+  Matrix3f m;
+  Vector4f v;
+  v = m*v;      // Compile-time error: YOU_MIXED_MATRICES_OF_DIFFERENT_SIZES
+\endcode
+
+Of course, in many cases, for example when checking dynamic sizes, the check cannot be performed at compile time.
+Eigen then uses runtime assertions. This means that executing an illegal operation will result in a crash at runtime,
+with an error message.
+
+\code
+  MatrixXf m(3,3);
+  VectorXf v(4);
+  v = m * v; // Run-time assertion failure here: "invalid matrix product"
+\endcode
 
+For more details on this topic, see \ref TopicAssertions "this page".
 
+\li \b Next: \ref TutorialArrayClass
 
 */
 
diff --git a/doc/C03_TutorialArrayClass.dox b/doc/C03_TutorialArrayClass.dox
index 04ecfde37..8944c061a 100644
--- a/doc/C03_TutorialArrayClass.dox
+++ b/doc/C03_TutorialArrayClass.dox
@@ -1,8 +1,11 @@
 namespace Eigen {
 
-/** \page TutorialArrayClass Tutorial - The Array Class
+/** \page TutorialArrayClass Tutorial page 3 - The Array Class
     \ingroup Tutorial
 
+\li \b Previous: \ref TutorialMatrixArithmetic
+\li \b Next: (not yet written)
+
 This tutorial aims to provide an overview and explanations on how to use Eigen's \b Array class
 
 \b Table \b of \b contents
diff --git a/doc/C05_TutorialAdvancedInitialization.dox b/doc/C05_TutorialAdvancedInitialization.dox
new file mode 100644
index 000000000..a658986c9
--- /dev/null
+++ b/doc/C05_TutorialAdvancedInitialization.dox
@@ -0,0 +1,29 @@
+namespace Eigen {
+
+/** \page TutorialAdvancedInitialization Tutorial - Advanced initialization
+    \ingroup Tutorial
+
+\section TutorialMatrixArithmCommaInitializer Comma initializer
+
+Eigen offers a comma initializer syntax which allows to set all the coefficients
+of any dense objects (matrix, vector, array, block, etc.) to specific values:
+\include Tutorial_commainit_01.cpp
+Output: \verbinclude Tutorial_commainit_01.out
+
+Moreover, the elements of the initialization list may themselves be Eigen expressions:
+\include Tutorial_commainit_02.cpp
+Output: \verbinclude Tutorial_commainit_02.out
+
+<span class="note">\b Side \b note: here \link CommaInitializer::finished() .finished() \endlink
+is used to get the actual matrix object once the comma initialization
+of our temporary submatrix is done. Note that despite the apparent complexity of such an expression,
+Eigen's comma initializer usually compiles to very optimized code without any overhead.</span>
+
+
+TODO mention using the comma initializer to fill a block xpr like m.row(i) << 1,2,3;
+
+TODO add more sections about Identity(), Zero(), Constant(), Random(), LinSpaced().
+
+*/
+
+}
diff --git a/doc/I06_TopicEigenExpressionTemplates.dox b/doc/I06_TopicEigenExpressionTemplates.dox
new file mode 100644
index 000000000..b31fd47f9
--- /dev/null
+++ b/doc/I06_TopicEigenExpressionTemplates.dox
@@ -0,0 +1,12 @@
+namespace Eigen {
+
+/** \page TopicEigenExpressionTemplates Expression templates in Eigen
+
+
+TODO: write this dox page!
+
+Is linked from the tutorial on arithmetic ops.
+
+*/
+
+}
diff --git a/doc/I07_TopicScalarTypes.dox b/doc/I07_TopicScalarTypes.dox
new file mode 100644
index 000000000..2ff03c198
--- /dev/null
+++ b/doc/I07_TopicScalarTypes.dox
@@ -0,0 +1,12 @@
+namespace Eigen {
+
+/** \page TopicScalarTypes Scalar types
+
+
+TODO: write this dox page!
+
+Is linked from the tutorial on the Matrix class.
+
+*/
+
+}
diff --git a/doc/I08_Resizing.dox b/doc/I08_Resizing.dox
new file mode 100644
index 000000000..c323e17ad
--- /dev/null
+++ b/doc/I08_Resizing.dox
@@ -0,0 +1,11 @@
+namespace Eigen {
+
+/** \page TopicResizing Resizing
+
+
+TODO: write this dox page!
+
+Is linked from the tutorial on the Matrix class.
+
+*/
+}
diff --git a/doc/I08_StorageOrders.dox b/doc/I08_StorageOrders.dox
new file mode 100644
index 000000000..0ceb771d3
--- /dev/null
+++ b/doc/I08_StorageOrders.dox
@@ -0,0 +1,11 @@
+namespace Eigen {
+
+/** \page TopicStorageOrders Storage orders
+
+
+TODO: write this dox page!
+
+Is linked from the tutorial on the Matrix class.
+
+*/
+}
diff --git a/doc/I09_Vectorization.dox b/doc/I09_Vectorization.dox
new file mode 100644
index 000000000..63831e59f
--- /dev/null
+++ b/doc/I09_Vectorization.dox
@@ -0,0 +1,9 @@
+namespace Eigen {
+
+/** \page TopicVectorization Vectorizaion
+
+
+TODO: write this dox page!
+
+*/
+}
diff --git a/doc/I10_Assertions.dox b/doc/I10_Assertions.dox
new file mode 100644
index 000000000..0370abc70
--- /dev/null
+++ b/doc/I10_Assertions.dox
@@ -0,0 +1,11 @@
+namespace Eigen {
+
+/** \page TopicAssertions Assertions
+
+
+TODO: write this dox page!
+
+Is linked from the tutorial on matrix arithmetic.
+
+*/
+}
diff --git a/doc/examples/tut_arithmetic_add_sub.cpp b/doc/examples/tut_arithmetic_add_sub.cpp
new file mode 100644
index 000000000..e97477b6e
--- /dev/null
+++ b/doc/examples/tut_arithmetic_add_sub.cpp
@@ -0,0 +1,22 @@
+#include <iostream>
+#include <Eigen/Dense>
+
+using namespace Eigen;
+
+int main()
+{
+  Matrix2d a;
+  a << 1, 2,
+       3, 4;
+  MatrixXd b(2,2);
+  b << 2, 3,
+       1, 4;
+  std::cout << "a + b =\n" << a + b << std::endl;
+  std::cout << "a - b =\n" << a - b << std::endl;
+  std::cout << "Doing a += b;" << std::endl;
+  a += b;
+  std::cout << "Now a =\n" << a << std::endl;
+  Vector3d v(1,2,3);
+  Vector3d w(1,0,0);
+  std::cout << "-v + w - v =\n" << -v + w - v << std::endl;
+}
diff --git a/doc/examples/tut_arithmetic_dot_cross.cpp b/doc/examples/tut_arithmetic_dot_cross.cpp
new file mode 100644
index 000000000..0f8e45359
--- /dev/null
+++ b/doc/examples/tut_arithmetic_dot_cross.cpp
@@ -0,0 +1,12 @@
+#include <iostream>
+#include <Eigen/Dense>
+
+using namespace Eigen;
+int main()
+{
+  Vector3d v(1,2,3);
+  Vector3d w(0,1,2);
+
+  std::cout << "Dot product: " << v.dot(w) << std::endl;
+  std::cout << "Cross product:\n" << v.cross(w) << std::endl;
+}
diff --git a/doc/examples/tut_arithmetic_matrix_mul.cpp b/doc/examples/tut_arithmetic_matrix_mul.cpp
new file mode 100644
index 000000000..63be38241
--- /dev/null
+++ b/doc/examples/tut_arithmetic_matrix_mul.cpp
@@ -0,0 +1,19 @@
+#include <iostream>
+#include <Eigen/Dense>
+
+using namespace Eigen;
+int main()
+{
+  Matrix2d mat;
+  mat << 1, 2,
+         3, 4;
+  Vector2d vec(-1,1);
+  RowVector2d rowvec(2,0);
+  std::cout << "Here is mat*mat:\n" << mat*mat << std::endl;
+  std::cout << "Here is mat*vec:\n" << mat*vec << std::endl;
+  std::cout << "Here is rowvec*mat:\n" << rowvec*mat << std::endl;
+  std::cout << "Here is rowvec*vec:\n" << rowvec*vec << std::endl;
+  std::cout << "Here is vec*rowvec:\n" << vec*rowvec << std::endl;
+  std::cout << "Let's multiply mat by itself" << std::endl;
+  std::cout << "Now mat is mat:\n" << mat << std::endl;
+}
diff --git a/doc/examples/tut_arithmetic_scalar_mul_div.cpp b/doc/examples/tut_arithmetic_scalar_mul_div.cpp
new file mode 100644
index 000000000..d5f65b53e
--- /dev/null
+++ b/doc/examples/tut_arithmetic_scalar_mul_div.cpp
@@ -0,0 +1,17 @@
+#include <iostream>
+#include <Eigen/Dense>
+
+using namespace Eigen;
+
+int main()
+{
+  Matrix2d a;
+  a << 1, 2,
+       3, 4;
+  Vector3d v(1,2,3);
+  std::cout << "a * 2.5 =\n" << a * 2.5 << std::endl;
+  std::cout << "0.1 * v =\n" << 0.1 * v << std::endl;
+  std::cout << "Doing v *= 2;" << std::endl;
+  v *= 2;
+  std::cout << "Now v =\n" << v << std::endl;
+}
diff --git a/doc/snippets/tut_matrix_assignmnet_resizing.cpp b/doc/snippets/tut_matrix_assignmnet_resizing.cpp
new file mode 100644
index 000000000..96b3c88d3
--- /dev/null
+++ b/doc/snippets/tut_matrix_assignmnet_resizing.cpp
@@ -0,0 +1,5 @@
+MatrixXf a(2,2);
+cout << "a is of size " << a.rows() << "x" << a.cols() << std::endl;
+MatrixXf b(3,3);
+a = b;
+cout << "a is now of size " << a.rows() << "x" << a.cols() << std::endl;