--- a/doc/ChangeLog	Mon Aug 27 19:50:23 2007 +0000
+++ b/doc/ChangeLog	Mon Aug 27 20:20:55 2007 +0000
@@ -1,3 +1,13 @@
+2007-08-27  David Bateman  <dbateman@free.fr>
+
+	* interpreter/struct.txi: Remove.
+	* interpreter/containers.txi: Combine with this chapter. Add
+	examples, and section on comma separated lists. Document the
+	difference between "c(1,:) = []" and c{1,:} = []" for a cell
+	arrays.
+	* interpreter/octave.texi: Document new indexing of containers
+	section.
+
 2007-08-25  David Bateman  <dbateman@free.fr>
 
         * interpreter/geometry.txi: Add examples and explanatory text.

--- a/doc/interpreter/container.txi	Mon Aug 27 19:50:23 2007 +0000
+++ b/doc/interpreter/container.txi	Mon Aug 27 20:20:55 2007 +0000
@@ -2,9 +2,405 @@
 @c This is part of the Octave manual.
 @c For copying conditions, see the file gpl.texi.
 
+@node Data Containers
+@chapter Data Containers
+@cindex containers
+
+Octave includes support for two different mechanaisms to contain
+arbitrary data types in the same variable. Structures, which are C-like,
+and are indexed with named fields, and cell arrays, where each element
+of the array can have a different data type and or shape.
+
+@menu
+* Data Structures::
+* Cell Arrays::
+* Comma Separated Lists::
+@end menu
+
+@node Data Structures
+@section Data Structures
+@cindex structures
+@cindex data structures
+
+Octave includes support for organizing data in structures.  The current
+implementation uses an associative array with indices limited to
+strings, but the syntax is more like C-style structures.  Here are some
+examples of using data structures in Octave.
+
+Elements of structures can be of any value type.  For example, the three
+expressions
+
+@example
+@group
+x.a = 1
+x.b = [1, 2; 3, 4]
+x.c = "string"
+@end group
+@end example
+
+@noindent
+create a structure with three elements.  To print the value of the
+structure, you can type its name, just as for any other variable:
+
+@example
+@group
+octave:2> x
+x =
+@{
+  a = 1
+  b =
+
+    1  2
+    3  4
+
+  c = string
+@}
+@end group
+@end example
+
+@noindent
+Note that Octave may print the elements in any order.
+
+Structures may be copied.
+
+@example
+@group
+octave:1> y = x
+y =
+@{
+  a = 1
+  b =
+
+    1  2
+    3  4
+
+  c = string
+@}
+@end group
+@end example
+
+Since structures are themselves values, structure elements may reference
+other structures.  The following statements change the value of the
+element @code{b} of the structure @code{x} to be a data structure
+containing the single element @code{d}, which has a value of 3.
+
+@example
+@group
+octave:1> x.b.d = 3
+x.b.d = 3
+octave:2> x.b
+ans =
+@{
+  d = 3
+@}
+octave:3> x
+x =
+@{
+  a = 1
+  b =
+  @{
+    d = 3
+  @}
+
+  c = string
+@}
+@end group
+@end example
+
+Note that when Octave prints the value of a structure that contains
+other structures, only a few levels are displayed.  For example,
+
+@example
+@group
+octave:1> a.b.c.d.e = 1;
+octave:2> a
+a =
+@{
+  b =
+  @{
+    c =
+    @{
+      d: 1x1 struct
+    @}
+  @}
+@}
+@end group
+@end example
+
+@noindent
+This prevents long and confusing output from large deeply nested
+structures.
+
+@DOCSTRING(struct_levels_to_print)
+
+Functions can return structures.  For example, the following function
+separates the real and complex parts of a matrix and stores them in two
+elements of the same structure variable.
+
+@example
+@group
+octave:1> function y = f (x)
+> y.re = real (x);
+> y.im = imag (x);
+> endfunction
+@end group
+@end example
+
+When called with a complex-valued argument, @code{f} returns the data
+structure containing the real and imaginary parts of the original
+function argument.
+
+@example
+@group
+octave:2> f (rand (2) + rand (2) * I)
+ans =
+@{
+  im =
+
+    0.26475  0.14828
+    0.18436  0.83669
+
+  re =
+
+    0.040239  0.242160
+    0.238081  0.402523
+@}
+@end group
+@end example
+
+Function return lists can include structure elements, and they may be
+indexed like any other variable.  For example,
+
+@example
+@group
+octave:1> [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4])
+x.u =
+
+  -0.40455  -0.91451
+  -0.91451   0.40455
+
+x.s =
+
+  0.00000  0.00000  0.00000
+  0.00000  5.46499  0.00000
+  0.00000  0.00000  0.36597
+
+x.v =
+
+  -0.57605   0.81742
+  -0.81742  -0.57605
+@end group
+@end example
+
+It is also possible to cycle through all the elements of a structure in
+a loop, using a special form of the @code{for} statement
+(@pxref{The for Statement})
+
+@menu
+* Structure Arrays::
+* Creating Structures::
+* Manipulating Structures::
+@end menu
+
+@node Structure Arrays
+@subsection Structure Arrays
+
+A structure array is a particular instance of a structure, where each of
+the fields of the structure is represented by a cell array. Each of
+these cell arrays has the same dimensions. An example of the creation of
+a structure array is
+
+@example
+@group
+x(1).a = "string1"
+x(2).a = "string2"
+x(1).b = 1
+x(2).b = 2
+@end group
+@end example
+
+@noindent
+which creates a 2-by-1 structure array with two fields. As previously,
+to print the value of the structure array, you can type its name:
+
+@example
+@group
+octave:2> x
+x =
+@{
+  a =
+
+  (,
+    [1] = string1
+    [2] = string2
+  ,)
+
+  b =
+
+  (,
+    [1] =  1
+    [2] =  2
+  ,)
+
+@}
+@end group
+@end example
+
+Individual elements of the structure array can be returned by indexing
+the variable like @code{@var{x} (1)}, which returns a structure with the
+two fields like
+
+@example
+@group
+octave:2> x(1)
+ans =
+@{
+  a = string1
+  b =  1
+@}
+@end group
+@end example
+
+Furthermore, the structure array can return a comma seperated list
+(@pxref{Comma Separated Lists}), if indexed by one of itself field
+names. For example
+
+@example
+@group
+octave:3> x.a
+ans =
+
+(,
+  [1] = string1
+  [2] = string2
+,)
+@end group
+@end example
+
+The function @code{size} with return the size of the structure. For
+the example above
+
+@example
+@group
+octave:4> size(x)
+ans =
+
+   1   2
+@end group
+@end example
+
+Elements can be deleted from a structure array in a similar manner to a
+numerial array, by assignment the elements to an empty matrix. For
+example
+
+@example
+@group
+in = struct ('call1', @{x, Inf, 'last'@}, 'call2', @{x, Inf, 'first'@});
+in (1, :) = []
+@result{} in =
+      {
+        call1 =
+      
+        (,
+          [1] = Inf
+          [2] = last
+        ,)
+      
+        call2 =
+      
+        (,
+          [1] = Inf
+          [2] = first
+        ,)
+      
+      }
+@end group
+@end example
+
+@node Creating Structures
+@subsection Creating Structures
+
+As well as indexing a structure with ".", Octave can create a structure
+with the @code{struct} command. @code{struct} takes pairs of arguments,
+where the first argument in the pair is the fieldname to include in the
+structure and the second is a scalar or cell array, representing the
+values to include in the structure or structure array. For example
+
+@example
+@group
+struct ('field1', 1, 'field2', 2)
+@result{} ans =
+      @{
+        field1 =  1
+        field2 =  2
+      @}
+@end group
+@end example
+
+If the values passed to @code{struct} are a mix of scalar and cell
+arrays, then the scalar arguments are expanded to create a 
+structure array with a consistent dimension. For example
+
+@example
+@group
+struct ('field1', @{1, 'one'@}, 'field2', @{2, 'two'@}, 'field3', 3);
+@result{} ans =
+      @{
+        field1 =
+      
+        (,
+          [1] =  1
+          [2] = one
+        ,)
+      
+        field2 =
+      
+        (,
+          [1] =  2
+          [2] = two
+        ,)
+      
+        field3 =
+      
+        (,
+          [1] =  3
+          [2] =  3
+        ,)
+      
+      @}
+@end group
+@end example
+
+@DOCSTRING(struct)
+
+@DOCSTRING(isstruct)
+
+Additional functions that can manipulate the fields of a structure are
+listed below.
+
+@DOCSTRING(rmfield)
+
+@DOCSTRING(setfield)
+
+@DOCSTRING(orderfields)
+
+@node Manipulating Structures
+@subsection Manipulating Structures
+
+Other functions that can manipulate the fields of a structure are given below.
+
+@DOCSTRING(fieldnames)
+
+@DOCSTRING(isfield)
+
+@DOCSTRING(getfield)
+
+@DOCSTRING(struct2cell)
+
+@DOCSTRING(substruct)
+
 @node Cell Arrays
-@chapter Cell Arrays
-@cindex containers
+@section Cell Arrays
 @cindex cell arrays
 
 It can be both necessary and convenient to store several variables of
@@ -80,7 +476,7 @@
 @end menu
 
 @node Creating Cell Arrays
-@section Creating Cell Array
+@subsection Creating Cell Array
 
 The introductory example showed how to create a cell array containing
 currently available variables. In many situations, however, it is useful
@@ -138,7 +534,7 @@
 @DOCSTRING(mat2cell)
 
 @node Indexing Cell Arrays
-@section Indexing Cell Arrays
+@subsection Indexing Cell Arrays
 
 As shown in the introductory example elements can be inserted from cell
 arrays using the @samp{@{} and @samp{@}} operators. Besides the change
@@ -164,14 +560,135 @@
 with a single variable as is the case with numerical arrays.
 
 Accessing multiple elements of a cell array with the @samp{@{} and
-@samp{@}} operators will result in a comma-separated list of all
-the requested elements. This list can then be used anywhere where a
-comma-separated list is used, such as in the creation of a new
-numerical array or cell array, or be passed as arguments to a
-function. If all the accessed elements of a cell array are scalars or
-column vectors, they can be concatenated into a new column vector
-containing the elements, by surrounding the list with @code{[} and
-@code{]} as in the following example
+@samp{@}} operators will result in a comma-separated list (@pxref{Comma
+Separated Lists}) of all the requested elements as discussed later. 
+
+One distinction between @samp{@{} and @samp{(} to index cell arrays is
+in the deletion of elements from the cell array. In a similar manner to
+a numerical array the @samp{()} operator can be used to delete elements
+from the cell array. The @samp{@{@}} operator however will remove the
+elements of the cell array, but not delete the space for them. For example
+
+@example
+@group
+x = {'1', '2'; '3', '4'};
+x{1, :} = []
+@result x =
+      {
+        [1,1] = [](0x0)
+        [2,1] = 3
+        [1,2] = [](0x0)
+        [2,2] = 4
+      }
+
+x(1, :) = []
+@result {} x =
+      {
+        [1,1] = 3
+        [1,2] = 4
+      }
+@end group
+@end example
+
+@node Cell Arrays of Strings
+@subsection Cell Arrays of Strings
+
+One common use of cell arrays is to store multiple strings in the same
+variable. It is possible to store multiple strings in a character matrix
+by letting each row be a string. This, however, introduces the problem
+that all strings must be of equal length. Therefore it is recommended to
+use cell arrays to store multiple strings. If, however, the character
+matrix representation is required for an operation, it can be converted
+to a cell array of strings using the @code{cellstr} function
+
+@example
+a = ["hello"; "world"];
+c = cellstr (a)
+     @result{} c =
+         @{
+           [1,1] = hello
+           [2,1] = world
+         @}
+@end example
+
+One further advantage of using cell arrays to store multiple strings, is
+that most functions for string manipulations included with Octave
+supports this representation. As an example, it is possible to compare
+one string with many others using the @code{strcmp} function. If one of
+the arguments to this function is a string and the other is a cell array
+of strings, each element of the cell array will be compared the string
+argument,
+
+@example
+c = @{"hello", "world"@};
+strcmp ("hello", c)
+     @result{} ans =
+        1   0
+@end example
+
+@noindent
+The following functions for string manipulation support cell arrays of
+strings, @code{strcmp}, @code{strcmpi}, @code{strncmp}, @code{strncmpi}, 
+@code{str2double}, @code{str2mat}, @code{strappend}, @code{strtrunc},
+@code{strvcat}, @code{strfind}, and @code{strmatch}.
+
+@DOCSTRING(cellstr)
+
+@DOCSTRING(iscellstr)
+
+@DOCSTRING(cellidx)
+
+@node Processing Data in Cell Arrays
+@subsection Processing Data in Cell Arrays
+
+Data that is stored in a cell array can be processed in several ways
+depending on the actual data. The most simple way to process that data
+is to iterate through it using one or more @code{for} loops. The same
+idea can be implemented easier through the use of the @code{cellfun}
+function that calls a user specified function on all elements of a cell
+array.
+
+@DOCSTRING(cellfun)
+
+An alternative is to convert the data to a different container, such as
+a matrix or a data structure.  Depending on the data this is possible
+using the @code{cell2mat} and @code{cell2struct} functions.
+
+@DOCSTRING(cell2mat)
+
+@DOCSTRING(cell2struct)
+
+@node Comma Separated Lists
+@section Comma Separated Lists
+@cindex comma separated lists
+
+Comma separated lists are the basic argument type to all Octave
+functions. In the example
+
+@example
+max (@var{a}, @var{b})
+@end example
+
+@noindent
+@code{@var{a}, @var{b}} is a somma separated list. Comma separated lists
+can appear on both the right and left hand side of an equation. For
+example
+
+@example
+[@var{i}, @var{j}] = ceil (find (@var{x}, [], 'last'));
+@end example
+
+@noindent
+where @code{@var{i}, @var{j}} is equally a comma separated list. Comma
+separated lists can not be directly manipulated by the user. However,
+both structures are cell arrays can be converted into into comma
+separated lists, which makes them useful to keep the input arguments and
+return values of functions organized. Another example of where a comma
+separated list can be used is in the creation of a new array. If all the
+accessed elements of a cell array are scalars or column vectors, they
+can be concatenated into a new column vector containing the elements, by
+surrounding the list with @code{[} and @code{]} as in the following
+example
 
 @example
 a = @{1, [2, 3], 4@};
@@ -228,70 +745,31 @@
          @}
 @end example
 
-@node Cell Arrays of Strings
-@section Cell Arrays of Strings
-
-One common use of cell arrays is to store multiple strings in the same
-variable. It is possible to store multiple strings in a character matrix
-by letting each row be a string. This, however, introduces the problem
-that all strings must be of equal length. Therefore it is recommended to
-use cell arrays to store multiple strings. If, however, the character
-matrix representation is required for an operation, it can be converted
-to a cell array of strings using the @code{cellstr} function
-
-@example
-a = ["hello"; "world"];
-c = cellstr (a)
-     @result{} c =
-         @{
-           [1,1] = hello
-           [2,1] = world
-         @}
-@end example
-
-One further advantage of using cell arrays to store multiple strings, is
-that most functions for string manipulations included with Octave
-supports this representation. As an example, it is possible to compare
-one string with many others using the @code{strcmp} function. If one of
-the arguments to this function is a string and the other is a cell array
-of strings, each element of the cell array will be compared the string
-argument,
+A comma separated list can equally appear on the left-hand side of an
+assignment. An example is 
 
 @example
-c = @{"hello", "world"@};
-strcmp ("hello", c)
-     @result{} ans =
-        1   0
+@group
+in @{1@} = ceil (rand (10, 1));
+in @{2@} = [];
+in @{3@} = 'last';
+in @{4@} = 'first';
+out = cell (4, 1);
+[out@{1:2@}] = find (in@{1 : 3@});
+[out@{3:4@}] = find (in@{[1, 2, 4]@});
+@end group
 @end example
 
-@noindent
-The following functions for string manipulation support cell arrays of
-strings, @code{strcmp}, @code{strcmpi}, @code{strncmp}, @code{strncmpi}, 
-@code{str2double}, @code{str2mat}, @code{strappend}, @code{strtrunc},
-@code{strvcat}, @code{strfind}, and @code{strmatch}.
-
-@DOCSTRING(cellstr)
-
-@DOCSTRING(iscellstr)
-
-@DOCSTRING(cellidx)
-
-@node Processing Data in Cell Arrays
-@section Processing Data in Cell Arrays
+Structures arrays can equally be used to create comma separated
+lists. This is done by addresses one of the fields of a structure
+array. For example
 
-Data that is stored in a cell array can be processed in several ways
-depending on the actual data. The most simple way to process that data
-is to iterate through it using one or more @code{for} loops. The same
-idea can be implemented easier through the use of the @code{cellfun}
-function that calls a user specified function on all elements of a cell
-array.
-
-@DOCSTRING(cellfun)
-
-An alternative is to convert the data to a different container, such as
-a matrix or a data structure.  Depending on the data this is possible
-using the @code{cell2mat} and @code{cell2struct} functions.
-
-@DOCSTRING(cell2mat)
-
-@DOCSTRING(cell2struct)
+@example
+@group
+x = ceil (randn (10, 1)); 
+in = struct ('call1', @{x, Inf, 'last'@}, 'call2', @{x, Inf, 'first'@});
+out = struct ('call1', cell (2, 1), 'call2', cell (2, 1));
+[out.call1] = find (in.call1);
+[out.call2] = find (in.call2);
+@end group
+@end example

--- a/doc/interpreter/octave.texi	Mon Aug 27 19:50:23 2007 +0000
+++ b/doc/interpreter/octave.texi	Mon Aug 27 20:20:55 2007 +0000
@@ -132,8 +132,7 @@
 * Data Types::                  
 * Numeric Data Types::          
 * Strings::                     
-* Data Structures::             
-* Cell Arrays::                  
+* Data Containers::             
 * Variables::                   
 * Expressions::                 Expressions.
 * Evaluation::                  
@@ -265,12 +264,11 @@
 * String Conversions::          
 * Character Class Functions::   
 
-Cell Arrays
+Data Containers
 
-* Creating Cell Arrays::                 
-* Indexing Cell Arrays::
-* Cell Arrays of Strings::
-* Processing Data in Cell Arrays::
+* Data Structures::
+* Cell Arrays::
+* Comma Separated Lists::
 
 Variables
 
@@ -580,7 +578,6 @@
 @include data.texi
 @include numbers.texi
 @include strings.texi
-@include struct.texi
 @include container.texi
 @include var.texi
 @include expr.texi

--- a/doc/interpreter/struct.txi	Mon Aug 27 19:50:23 2007 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,208 +0,0 @@
-@c Copyright (C) 1996, 1997, 2007 John W. Eaton
-@c This is part of the Octave manual.
-@c For copying conditions, see the file gpl.texi.
-
-@c FIXME update for structure arrays
-@c FIXME need discussion of comma-separated lists somewhere
-
-@node Data Structures
-@chapter Data Structures
-@cindex structures
-@cindex data structures
-
-Octave includes support for organizing data in structures.  The current
-implementation uses an associative array with indices limited to
-strings, but the syntax is more like C-style structures.  Here are some
-examples of using data structures in Octave.
-
-Elements of structures can be of any value type.  For example, the three
-expressions
-
-@example
-@group
-x.a = 1
-x.b = [1, 2; 3, 4]
-x.c = "string"
-@end group
-@end example
-
-@noindent
-create a structure with three elements.  To print the value of the
-structure, you can type its name, just as for any other variable:
-
-@example
-@group
-octave:2> x
-x =
-@{
-  a = 1
-  b =
-
-    1  2
-    3  4
-
-  c = string
-@}
-@end group
-@end example
-
-@noindent
-Note that Octave may print the elements in any order.
-
-Structures may be copied.
-
-@example
-@group
-octave:1> y = x
-y =
-@{
-  a = 1
-  b =
-
-    1  2
-    3  4
-
-  c = string
-@}
-@end group
-@end example
-
-Since structures are themselves values, structure elements may reference
-other structures.  The following statements change the value of the
-element @code{b} of the structure @code{x} to be a data structure
-containing the single element @code{d}, which has a value of 3.
-
-@example
-@group
-octave:1> x.b.d = 3
-x.b.d = 3
-octave:2> x.b
-ans =
-@{
-  d = 3
-@}
-octave:3> x
-x =
-@{
-  a = 1
-  b =
-  @{
-    d = 3
-  @}
-
-  c = string
-@}
-@end group
-@end example
-
-Note that when Octave prints the value of a structure that contains
-other structures, only a few levels are displayed.  For example,
-
-@example
-@group
-octave:1> a.b.c.d.e = 1;
-octave:2> a
-a =
-@{
-  b =
-  @{
-    c =
-    @{
-      d: 1x1 struct
-    @}
-  @}
-@}
-@end group
-@end example
-
-@noindent
-This prevents long and confusing output from large deeply nested
-structures.
-
-@DOCSTRING(struct_levels_to_print)
-
-Functions can return structures.  For example, the following function
-separates the real and complex parts of a matrix and stores them in two
-elements of the same structure variable.
-
-@example
-@group
-octave:1> function y = f (x)
-> y.re = real (x);
-> y.im = imag (x);
-> endfunction
-@end group
-@end example
-
-When called with a complex-valued argument, @code{f} returns the data
-structure containing the real and imaginary parts of the original
-function argument.
-
-@example
-@group
-octave:2> f (rand (2) + rand (2) * I)
-ans =
-@{
-  im =
-
-    0.26475  0.14828
-    0.18436  0.83669
-
-  re =
-
-    0.040239  0.242160
-    0.238081  0.402523
-@}
-@end group
-@end example
-
-Function return lists can include structure elements, and they may be
-indexed like any other variable.  For example,
-
-@example
-@group
-octave:1> [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4])
-x.u =
-
-  -0.40455  -0.91451
-  -0.91451   0.40455
-
-x.s =
-
-  0.00000  0.00000  0.00000
-  0.00000  5.46499  0.00000
-  0.00000  0.00000  0.36597
-
-x.v =
-
-  -0.57605   0.81742
-  -0.81742  -0.57605
-@end group
-@end example
-
-It is also possible to cycle through all the elements of a structure in
-a loop, using a special form of the @code{for} statement
-(@pxref{The for Statement})
-
-The following functions are available to give you information about
-structures.
-
-@DOCSTRING(struct)
-
-@DOCSTRING(isstruct)
-
-@DOCSTRING(fieldnames)
-
-@DOCSTRING(isfield)
-
-@DOCSTRING(getfield)
-
-@DOCSTRING(orderfields)
-
-@DOCSTRING(rmfield)
-
-@DOCSTRING(setfield)
-
-@DOCSTRING(struct2cell)
-
-@DOCSTRING(substruct)