Merge pull request #1362 from nouiz/doc_adv_idx

doc/library/tensor/basic.txt

@@ -897,17 +897,31 @@ Reductions
 Indexing
 ========
 
-Like numpy, Theano distinguishes between *basic* and *advanced* indexing.
+Like NumPy, Theano distinguishes between *basic* and *advanced* indexing.
 Theano fully supports basic indexing
-(see `numpy's basic indexing  <http://docs.scipy.org/doc/numpy/reference/arrays.indexing.html>`_).
+(see `NumPy's indexing  <http://docs.scipy.org/doc/numpy/reference/arrays.indexing.html>`_).
 
-Advanced indexing is almost entirely unsupported (for now).
-The one sort of advanced indexing that is supported is the retrieval of the c[i]'th element of each
-row of a matrix x:
+`Integer advanced indexing
+<http://docs.scipy.org/doc/numpy/reference/arrays.indexing.html#integer>`_
+will be supported in 0.6rc4 (or the development version). We do not
+support boolean masks, as Theano do not have a boolean type (we use
+int8 for the output of logic operator). To imitate boolean advanced
+indexing, you can do::
 
->>> x = T.fmatrix()
->>> c = T.lvector()
->>> x[T.arange(c.shape[0]), c]
+    # NumPy indexing with a mask
+    n = np.arange(9).reshape(3,3)
+    n[n>4] # array([5, 6, 7, 8])
+
+    # Theano indexing with a "mask"
+    t = tt.arange(9).reshape((3,3))
+    t[t>4].eval()  # an array with shape (3, 3, 3)
+
+    # getting a Theano result like NumPy
+    t[(t>4).nonzero()].eval() # array([5, 6, 7, 8])
+
+The gradient of Advanced indexing need in many cases NumPy
+1.8. It isn't released as of April 30, 2013. You can use NumPy
+development version to have this feature now.
 
 
 Index-assignment is *not* supported.  If you want to do something like ``a[5]