# HG changeset patch
# User Arun Giridhar <arungiridhar@gmail.com>
# Date 1677278585 18000
# Node ID 0d77475a7507aa87631e61db5c9a3f87b8bc2136
# Parent  f184279bd67fd49e6123eba25e63cefecdb819e5
doc: Expand vector indexing description (bug #63833)

expr.txi: Describe the rules for the shape of A(P)
when A and/or P are matrices, arrays, and/or vectors.

diff -r f184279bd67f -r 0d77475a7507 doc/interpreter/expr.txi
--- a/doc/interpreter/expr.txi	Sat Feb 18 15:01:10 2023 +0100
+++ b/doc/interpreter/expr.txi	Fri Feb 24 17:43:05 2023 -0500
@@ -144,6 +144,18 @@
 @end group
 @end example
 
+The shape rules for @var{A}(@var{P}) are:
+@itemize @bullet
+@item When at least one of @var{A} or @var{P} has two or more dimensions, then
+@var{A}(@var{P}) takes the shape of @var{P}.  This happens when at least one
+of the variables is a 2-D matrix or an N-D array.
+
+@item When both @var{A} and @var{P} are 1-D vectors, then @var{A}(@var{P}) takes
+the shape of @var{A} itself.  In particular, when @var{A} is a row vector, then
+@var{A}(@var{P}) is also a row vector irrespective of @var{P}'s shape.  The
+case when @var{A} is a column vector is analogous.
+@end itemize
+
 Note that it is permissible to use a 1-D index with a multi-dimensional
 object (also called linear indexing).  In this case, the elements of the
 multi-dimensional array are taken in column-first order like Fortran.  That is,