bugGNU Octave - Bugs: bug #52723, unexpected space in matrix...

 
 

bug #52723: unexpected space in matrix expression (brackets) in document

Submitter:  None
Submitted:  Fri 22 Dec 2017 03:22:30 AM UTC
   
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Originator Email:  -email is unavailable-
Open/Closed:  * Closed Release:  * 4.2.1
Operating System:  * Any Fixed Release:  None
Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Wed 27 Dec 2017 03:22:08 AM UTC, comment #8: 

GNU Octave has very high quality and helps me a lot. I like it very much.
Most of what I found recently is just very small problems. I just report them in the hope of making it even more perfect.

Meanwhile, I know there are many developing works which are more important than fixing these small problems,
so I also hope that these small bug reports do not interrupt maintainers too much.

Thank maintainers for bring us such good software and document.

Anonymous
Tue 26 Dec 2017 07:36:33 PM UTC, comment #7: 

Regarding comment #6, it isn't a problem that you have been posting so many bug reports about the documentation.  Many of the Octave Maintainers have worked with Octave for over 10 years and we don't see the problems that new people coming to use the software for the first time do.

I made another attempt to rewrite the advanced indexing section to be clearer in this cset (http://hg.savannah.gnu.org/hgweb/octave/rev/abe0b0e08897).

Rik <rik5>
Group administrator
Sat 23 Dec 2017 02:42:16 PM UTC, comment #6: 

I'm sorry for posting too many recently,
and again thank maintainers very much for fixing them.

Anonymous
Sat 23 Dec 2017 12:05:29 PM UTC, comment #5: 

A too too small typo found in Section 11.9.4 Nested Functions, page 200:


--- a/doc/interpreter/func.txi
+++ b/doc/interpreter/func.txi
@@ -1047,7 +1047,7 @@
   ## Can NOT call: ex_aa and ex_ab

   function ex_a ()
-    ## Call call everything
+    ## Can call everything

     function ex_aa ()
       ## Can call everything


Anonymous
Sat 23 Dec 2017 04:42:01 AM UTC, comment #4: 

Thank maintainers very much for fixing so many small issues found recently.

The Advanced Indexing section seems still have problems:
(1)
after using 'nd' instead of 'n', some following 'n' should also be changed to 'nd'.
and (2)
there are still 'm' and 'm(i)', so 'm' is still ambiguous.

Possible solutions:
(1)
like 'nd', let 'md' denote the number of indices (i.e. 'md=numel(m)'), and 'm(i)' still denotes the i-th index.
or (2)
do not use 'm(i)' at all, then there is no ambiguity, and we can still let 'm'/'n' denote the number of indices/dimensions as the original version. This makes less difference from the original version.


patch for solution (1):

--- a/doc/interpreter/expr.txi
+++ b/doc/interpreter/expr.txi
@@ -123,7 +123,7 @@
 a(end) = [];      # delete element
 a(1:2:end)        # odd elements of a => [1, 3]
 a(2:2:end)        # even elements of a => [2, 4]
-a(end:-1:1)       # reversal of a => [4, 3, 2 , 1]
+a(end:-1:1)       # reversal of a => [4, 3, 2, 1]
 @end group
 @end example

@@ -134,18 +134,18 @@
 @node Advanced Indexing
 @subsection Advanced Indexing

-An array with @samp{nd} dimensions can be indexed using @samp{m}
+An array with @samp{nd} dimensions can be indexed using @samp{md}
 indices.  More generally, the set of index tuples determining the
 result is formed by the Cartesian product of the index vectors (or
 ranges or scalars).

-For the ordinary and most common case, @w{@code{m == nd}}, and each
-index corresponds to its respective dimension.  If @w{@code{m < nd}},
+For the ordinary and most common case, @w{@code{md == nd}}, and each
+index corresponds to its respective dimension.  If @w{@code{md < nd}},
 and every index is less than the size of the array in the @math{i^{th}}
 dimension (@code{m(i) < size (@var{array}, i)}), then the index expression
-is padded with @w{@code{n - m}} trailing singleton dimensions.
-If @w{@code{m < nd}} but one of the indices @code{m(i)} is outside the
-size of the current array, then the last @w{@code{n-m+1}} dimensions
+is padded with @w{@code{nd - md}} trailing singleton dimensions.
+If @w{@code{md < nd}} but one of the indices @code{m(i)} is outside the
+size of the current array, then the last @w{@code{nd-md+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.
@@ -164,10 +164,10 @@
    5   7
    6   8

-a(2,1,2);   # Case (m == n): ans = 6
-a(2,1);     # Case (m < n), idx within array:
+a(2,1,2);   # Case (md == nd): ans = 6
+a(2,1);     # Case (md < nd), idx within array:
             # equivalent to a(2,1,1), ans = 2
-a(2,4);     # Case (m < n), idx outside array:
+a(2,4);     # Case (md < nd), idx outside array:
             # Dimension 2 & 3 folded into new dimension of size 2x2 = 4
             # Select 2nd row, 4th element of [2, 4, 6, 8], ans = 8
 @end example


patch for solution (2):

--- a/doc/interpreter/expr.txi
+++ b/doc/interpreter/expr.txi
@@ -123,7 +123,7 @@
 a(end) = [];      # delete element
 a(1:2:end)        # odd elements of a => [1, 3]
 a(2:2:end)        # even elements of a => [2, 4]
-a(end:-1:1)       # reversal of a => [4, 3, 2 , 1]
+a(end:-1:1)       # reversal of a => [4, 3, 2, 1]
 @end group
 @end example

@@ -134,17 +134,17 @@
 @node Advanced Indexing
 @subsection Advanced Indexing

-An array with @samp{nd} dimensions can be indexed using @samp{m}
+An array with @samp{n} dimensions can be indexed using @samp{m}
 indices.  More generally, the set of index tuples determining the
 result is formed by the Cartesian product of the index vectors (or
 ranges or scalars).

-For the ordinary and most common case, @w{@code{m == nd}}, and each
-index corresponds to its respective dimension.  If @w{@code{m < nd}},
+For the ordinary and most common case, @w{@code{m == n}}, and each
+index corresponds to its respective dimension.  If @w{@code{m < n}},
 and every index is less than the size of the array in the @math{i^{th}}
-dimension (@code{m(i) < size (@var{array}, i)}), then the index expression
-is padded with @w{@code{n - m}} trailing singleton dimensions.
-If @w{@code{m < nd}} but one of the indices @code{m(i)} is outside the
+dimension (size (@var{array}, i)}), then the index expression
+is padded with @w{@code{n - m}} trailing singleton dimensions.
+If @w{@code{m < n}} but one of the indices is outside the
 size of the current array, then the last @w{@code{n-m+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


Anonymous
Sat 23 Dec 2017 12:09:36 AM UTC, comment #3: 

I checked in a fix here (http://hg.savannah.gnu.org/hgweb/octave/rev/b9d482dd90f3).

I rewrote the Advanced Indexing section to use 'nd' instead of 'n' for number of dimensions which helped a bit with the clarity.

Rik <rik5>
Group administrator
Fri 22 Dec 2017 07:04:04 AM UTC, comment #2: 

And another issue in the same chapter:
(It's too small so I didn't open a new bug report.)

In Section 8.3 Arithmetic Operators, page 145,
unlike ".*" (times), the "*" (mtimes) has no relation to broadcasting.

--- a/doc/interpreter/expr.txi
+++ b/doc/interpreter/expr.txi
@@ -535,8 +535,7 @@
 @item @var{x} * @var{y}
 @opindex *
 Matrix multiplication.  The number of columns of @var{x} must agree with
-the number of rows of @var{y}, or they must be broadcastable to the same
-shape.
+the number of rows of @var{y}.

 @item @var{x} .* @var{y}
 @opindex .*


Anonymous
Fri 22 Dec 2017 04:26:04 AM UTC, comment #1: 

Section 8.1.1 Advanced Indexing, paragraph 2:

   For the ordinary and most common case, ‘m == n’, and each index
corresponds to its respective dimension.  If ‘m < n’ and every index is
less than the size of the array in the i^{th} dimension, ‘m(i) < n(i)’,
then the index expression is padded with trailing singleton dimensions
(‘[ones (m-n, 1)]’).  If ‘m < n’ but one of the indices ‘m(i)’ is
outside the size of the current array, then the last ‘n-m+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.


1.
"ones(m-n, 1)" should be "ones(n-m, 1)" since m < n.
2.
It seems that "ones(n-m, 1)" is not necessary to be put into "[ ]"
since an index expression is a cs-list rather than a vector.
3.
It seems that the symbol 'm' and 'n' have been reused.
Standalone 'm' means the number of indices and 'n' means 'ndims(a)',
but in 'm(i)' 'n(i)', 'm' means the whole indices and 'n' means 'size(a)'.
4.
If m < n, not any one of the indices 'm(i)' but only the last index 'm(end)' can be outside the size.
For example, if 'a = reshape(1:8,2,2,2)', then 'a(4,_)' is not allowd but 'a(_,4)' is allowed.

octave:2>  a
a =

ans(:,:,1) =

   1   3
   2   4

ans(:,:,2) =

   5   7
   6   8

octave:3>  a(2,4)
ans =  8
octave:4>  a(4,2)
error: a(4,_): out of bound 2



I try to rephase the paragraph as follow:

   For the ordinary and most common case, ‘m == n’, and each index
corresponds to its respective dimension.  If ‘m < n’ and every index is
less than the size of the array in the i^{th} dimension, then the index
expression is padded with ‘n-m’ trailing singleton dimensions.
If ‘m < n’ but the last index is outside the size of the current array,
then the last ‘n-m+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.


and a more neat version:

   For the ordinary and most common case, ‘m == n’, and each index
corresponds to its respective dimension.  If ‘m < n’, then the last
‘n-m+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.


Anonymous
Fri 22 Dec 2017 03:22:30 AM UTC, original submission:  

The GNU convention to add a space between the function name
and the "(" may cause problem within the matrix expression "[ ]".
As described in Section 4.1 Matrices,
"[ sin (pi) ]" will result in an error
and instead we should use "[ (sin (pi)) ]" or "[ sin(pi) ]".

However, this case still appears in the document:
 Section 8.1.1, paragraph 2:
  "[ones (m-n, 1)]"
 Section 15.2.2.2, function ezmesh,ezmeshc,ezsurf,ezsurfc:
  "[FX (S, T), FY (S, T), FZ (S, T)]"
while the following seems to be correct:
 Section 21.2.1:
  "[D(1:n,n) * M; zeros(m-n, columns (M))]"
 Section 28.5:
  "x = 2 pi [0, (rand (1, 98)), 1]"
  "cc = [(eye (2)), (eye (2))]"
The above results are got from INFO version document with regexp

\[[^][]*\w+ \(


It seems that Section 8.1.1 also has other problems. I would try to give some suggestion later.
Possible solution to Section 15.2.2.2:

diff -ur a/scripts/plot/draw/ezmeshc.m b/scripts/plot/draw/ezmeshc.m
--- a/scripts/plot/draw/ezmeshc.m
+++ b/scripts/plot/draw/ezmeshc.m
@@ -32,8 +32,8 @@
 ## @code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.
 ##
 ## If three functions are passed, then plot the parametrically defined
-## function @code{[@var{fx} (@var{s}, @var{t}), @var{fy} (@var{s}, @var{t}),
-## @var{fz} (@var{s}, @var{t})]}.
+## function @code{[@var{fx}(@var{s}, @var{t}), @var{fy}(@var{s}, @var{t}),
+## @var{fz}(@var{s}, @var{t})]}.
 ##
 ## If @var{dom} is a two element vector, it represents the minimum and maximum
 ## values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
diff -ur a/scripts/plot/draw/ezmesh.m b/scripts/plot/draw/ezmesh.m
--- a/scripts/plot/draw/ezmesh.m
+++ b/scripts/plot/draw/ezmesh.m
@@ -32,8 +32,8 @@
 ## @code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.
 ##
 ## If three functions are passed, then plot the parametrically defined
-## function @code{[@var{fx} (@var{s}, @var{t}), @var{fy} (@var{s}, @var{t}),
-## @var{fz} (@var{s}, @var{t})]}.
+## function @code{[@var{fx}(@var{s}, @var{t}), @var{fy}(@var{s}, @var{t}),
+## @var{fz}(@var{s}, @var{t})]}.
 ##
 ## If @var{dom} is a two element vector, it represents the minimum and maximum
 ## values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
diff -ur a/scripts/plot/draw/ezsurfc.m b/scripts/plot/draw/ezsurfc.m
--- a/scripts/plot/draw/ezsurfc.m
+++ b/scripts/plot/draw/ezsurfc.m
@@ -32,8 +32,8 @@
 ## @code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.
 ##
 ## If three functions are passed, then plot the parametrically defined
-## function @code{[@var{fx} (@var{s}, @var{t}), @var{fy} (@var{s}, @var{t}),
-## @var{fz} (@var{s}, @var{t})]}.
+## function @code{[@var{fx}(@var{s}, @var{t}), @var{fy}(@var{s}, @var{t}),
+## @var{fz}(@var{s}, @var{t})]}.
 ##
 ## If @var{dom} is a two element vector, it represents the minimum and maximum
 ## values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
diff -ur a/scripts/plot/draw/ezsurf.m b/scripts/plot/draw/ezsurf.m
--- a/scripts/plot/draw/ezsurf.m
+++ b/scripts/plot/draw/ezsurf.m
@@ -32,8 +32,8 @@
 ## @code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.
 ##
 ## If three functions are passed, then plot the parametrically defined
-## function @code{[@var{fx} (@var{s}, @var{t}), @var{fy} (@var{s}, @var{t}),
-## @var{fz} (@var{s}, @var{t})]}.
+## function @code{[@var{fx}(@var{s}, @var{t}), @var{fy}(@var{s}, @var{t}),
+## @var{fz}(@var{s}, @var{t})]}.
 ##
 ## If @var{dom} is a two element vector, it represents the minimum and maximum
 ## values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,


Anonymous

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by None (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follow 2 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2017-12-23 rik5 StatusNone Fixed
        Open/ClosedOpen Closed

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code