Added doc about the fact that the shape inference can remove expected error.

doc/tutorial/shape_info.txt

@@ -22,19 +22,85 @@ Currently shape informations are used for 2 things in Theano:
 .. code-block:: python
 
    import theano
-   x = theano.tensor.matrix()
+   x = theano.tensor.matrix('x')
    f = theano.function([x], (x**2).shape)
    theano.printing.debugprint(f)
-   # MakeVector [@26301776] ''   2
-   #  |Shape_i{0} [@26321296] ''   1
-   #  | |<TensorType(float64, matrix)> [@26153424]
-   #  |Shape_i{1} [@26322512] ''   0
-   #  | |<TensorType(float64, matrix)> [@26153424]
+   #MakeVector [@43860304] ''   2
+   # |Shape_i{0} [@43424912] ''   1
+   # | |x [@43423568]
+   # |Shape_i{1} [@43797968] ''   0
+   # | |x [@43423568]
 
 The output of this compiled function do not contain any multiplication
 or power. Theano has removed them to compute directly the shape of the
 output.
 
+Shape inference problem
+=======================
+
+Theano do shape information propagation in the graph. Sometimes this
+can had error. Example:
+
+.. code-block:: python
+   
+   import numpy
+   import theano
+   x = theano.tensor.matrix('x')
+   y = theano.tensor.matrix('y')
+   z = theano.tensor.join(0,x,y)
+   xv = numpy.random.rand(5,4)
+   yv = numpy.random.rand(3,3)
+
+   f = theano.function([x,y], z.shape)
+   theano.printing.debugprint(f)
+   #MakeVector [@23910032] ''   4
+   # |Elemwise{Add{output_types_preference=transfer_type{0}}}[(0, 0)] [@24055120] ''   3
+   # | |Shape_i{0} [@23154000] ''   1
+   # | | |x [@23151760]
+   # | |Shape_i{0} [@23593040] ''   2
+   # | | |y [@23151888]
+   # |Shape_i{1} [@23531152] ''   0
+   # | |x [@23151760]
+
+   #MakeVector [@56338064] ''   4
+   # |Elemwise{Add{output_types_preference=transfer_type{0}}}[(0, 0)] [@56483152] ''   3
+   # | |Shape_i{0} [@55586128] ''   1
+   # | | |<TensorType(float64, matrix)> [@55583888]
+   # | |Shape_i{0} [@56021072] ''   2
+   # | | |<TensorType(float64, matrix)> [@55584016]
+   # |Shape_i{1} [@55959184] ''   0
+   # | |<TensorType(float64, matrix)> [@55583888]
+
+   print f(xv,yv)# DONT RAISE AN ERROR AS SHOULD BE.
+   #[8,4]
+
+   f = theano.function([x,y], z)# Don't take the shape.
+   theano.printing.debugprint(f)
+   #Join [@44540496] ''   0
+   # |0 [@44540432]
+   # |x [@44540240]
+   # |y [@44540304]
+
+   f(xv,yv)
+   # Raise a dimensions mismatch error.
+
+As you see, when you ask for the shape of some computation(join in the
+example), we sometimes compute the shape without executing the
+computation(there is no join in the first output or debugprint).
+
+This make the computation of the shape faster, but can hide error. In
+the example, the computation of the shape of join is done on the first
+theano variable in the join, not on the other.
+
+This can probably happen with many other op as elemwise, dot, ...
+
+You can detect those problem by running the code without this
+optimization with the theano flag
+`optimizer_excluding=local_shape_to_shape_i`. You can also have the
+same effect by running in the mode FAST_COMPILE(won't apply this
+optimization and most other optimization too) or DEBUG_MODE(will test
+before and after all optimizations(much slower)).
+
 
 Specifing exact shape
 =====================