@jwe: regarding comment #9, do you know of a fancy way to use templates to reduce the number of files that instantiate operators?  Or, is it just the case that every file in libinterp/operators that defines operators between two data types needs to be modified to generate a warning?

I rewrote large parts of 8.1 and 8.1.1 (and a very small modification to 8.2). I removed the unnecessarily complicated stuff and tried to write the rest both more accurately, thus the level of complexity may seem about the same. Further, I gave more basic examples. The diff is attached.

Further, I think that the documentation would gain by deleting the last part of 8.1.1 starting from "A second use of indexing...". First, I do not see the well-defined first use of indexing, but then the given examples are either not about indexing at all (the point with sqrt, which is rather about using vectors and matrices as fundamental data types rather than scalars, which is probably the reason why anybody would turn to Octave in the first case, or in any case the first thing he would learn -- discussed already in 19.1), or should rather be done by a repmat in the second example. Preallocation is already done in 19.6. I do not see that it is specific to indexing.

Last point: From inspecting this part of the documentation, I did not really get the conventions with @samp, @math, @var, @code. I did it as good as I could, but feel free to make these more consistent if there are conventions regarding their use.

(file #43982)

I tried adding a warning message for double arrays multiplied by double arrays only.  The patch is attached as m-m.diff.  It seems to work, but as I understand it, the full solution would require modifying every file in libinterp/operators that involves array-by-array operators.  That is a lot of files because there seems to be one file for each two-way combination of arrays that can be operated on.  For example, there is float array-by-double array, complex double array-by-permutation matrix, diagonal-matrix-by-double-matrix, etc., etc.  That is a lot of files, unless there is a easier way to do this.

Octave is already using a bunch of macros in these files.  Maybe clever use of templates could help?  Or maybe I have to buckle down and write a Perl script to do all the modification.

(file #43974)

In Matlab R2016a:

>> x = reshape (1:8, [2 2 2])
x(1,3)

x(:,:,1) =

     1     3
     2     4


x(:,:,2) =

     5     7
     6     8


ans =

     5

>>

So Octave is behaving compatible to Matlab with that respect.

With respect to the behaviour of mtimes and *: The last paragraph in my initial bug report was nonsense: as you say, what I describe can be done with the double colon trick without any explizit reshaping to singleton dimension and so on. So I do not see a use case for the present behaviour (apart from saving 5 characters for the parentheses, colons and the comma), and thus it is probably best to do input validation and raise an error when any argument has more than two dimensions.

As regards the documentation: yes, in 8.1.1 there is some documentation, but specifically the action of the colon in this respect is at best implicitly defined. If I find time, I will think about a rewording of this section.

But: isn't it the case that the second paragraph in 8.1.1 that you reproduced below treats cases that cannot validly appear and is thus unnecessarily complex? What I mean is the case "nidx < nd but one of the indices idx(i) is outside...". If i<length(nidx), that is, if this excessive idx-entry concerns any but the last specified dimension, it errors out in any case? So to me it seems that we can define the action described in this paragraph as: "If nidx < nd, then the result is an implicit reshape that folds the last nd - nidx + 1 dimensions into one." This includes the case that idx(end) is within the size of the corresponding dimension, in which case it would be equivalent to the present definition via addition of singleton dimensions (meaning: idx=[idx ones(1,nd-nidx)]), as well as if the last entry is larger than the corresponding dimension. If any other entry is larger than its dimension, it would give an error.

By the way, this is presumably again an extension over what Matlab allows, I would guess Matlab would allow only nidx==nd or nidx==1, in which case the answer is A(:)(idx). This should then probably also be documented.

Is something wrong with Savannah?  Michael Godfrey posted a response to this report, which I will include manually, but it doesn't seem to have been received to this bug report.

                                      < M A T L A B (R) >
                            Copyright 1984-2017 The MathWorks, Inc.
                             R2017b (9.3.0.713579) 64-bit (glnxa64)
                                       September 14, 2017


To get started, type one of these: helpwin, helpdesk, or demo.
For product information, visit www.mathworks.com.

>> a = rand (2,2,2);
>> b = rand (2,2,2);
>> c = a * b;
Error using *
Arguments must be 2-D, or at least one argument must be scalar. Use TIMES (.*) for elementwise
multiplication.

>> c2 = mtimes (a, b);
Error using *
Arguments must be 2-D, or at least one argument must be scalar. Use TIMES (.*) for elementwise
multiplication.

>> isequal (c, c2)
Undefined function or variable 'c'.

We certainly don't want to get rid of it.  As for documentation, see the section 8.1.1 "Advanced Indexing".  There is documentation there, but it is not an easy concept to explain.  The text is

8.1.1 Advanced Indexing
An array with ‘nd’ dimensions can be indexed by a vector idx which has from 1 to ‘nd’
elements. If any element of idx is not a scalar then the complete set of index tuples will be
generated from the Cartesian product of the index elements.
For the ordinary and most common case, the number of indices (nidx = numel (idx))
matches the number of dimensions ‘nd’. In this case, each element of idx corresponds to
its respective dimension, i.e., idx(1) refers to dimension 1, idx(2) refers to dimension 2,
etc. If nidx < nd, and every index is less than the size of the array in the ith dimension
(idx(i) < size (array, i)), then the index expression is padded with nd - nidx trailing
singleton dimensions. If nidx < nd but one of the indices idx(i) is outside the size of the
current array, then the last nd - nidx + 1 dimensions are folded into a single dimension
with an extent equal to the product of extents of the original dimensions. This is easiest to
understand with an example.

In this situation, it is the last bit which takes precedence.  By indexing a 3-D object with only 2 indices (:,:) all of the dimensions >= 2 are folded in to the second dimension.  So rand (3,3,3) becomes a 3x9 2-D matrix.

If you can think of language that would be clearer to explain this it would be useful.