From bug-octave-request at bevo dot che dot wisc dot edu Fri Dec 12 12:45:54 2003
Subject: Re: documentation of variable-length argument lists not up to date
From: Thorsten Meyer <thorsten dot meyier at gmx dot de>
To: bug-octave at bevo dot che dot wisc dot edu
Date: Thu, 11 Dec 2003 14:47:32 -0600

Hi,

thanks for the hint about the varargin argument. Now I have tried to 
write an update to the documentation of variable-length argument lists 
in func.txi.
Is it in an acceptable form (and did I get the diff right?)?

Thorsten

here is the output of diff -cp func.new.txi func.txi:
*** func.new.txi    2003-12-11 21:21:19.000000000 +0100
--- /home/thorsten/download/octave-2.1.50/doc/interpreter/func.txi    
2002-11-20 20:03:04.000000000 +0100
*************** At the top level,  at code{nargout} is unde
*** 356,415 ****
   at cindex Variable-length argument lists
   at cindex @code{...}
 
! Octave has a mechanism for handling functions that take an
  unspecified number of arguments, so it is not necessary to place an
  upper bound on the number of optional arguments that a function can
  accept.
-  at c XXX FIXME XXX -- What did "real" mean in this context?
-  at c does that mean "real as opposed to some matlab version"?
 
! There are two forms of syntax for variable-length argument lists.
! One of them is deprecated because of its incompatibility with matlab 5.
 
!  at subsection Variable-length Argument Lists Using @var{varargin}
!
! This syntax is compatible with matlab 5.
!  at c XXX FIXME XXX -- Is that right?
! Here is a simple example of a function that uses  at var{varargin} to 
print a header
! followed by a an unspecified number of values:
!
!  at example
! function foo (heading, varargin)
!   disp(heading);
!   for n = 1:length(varargin)
!     disp(varargin{n});
!   endfor
! endfunction
!  at end example
!
!  at defvr {Keyword} varargin
! In the function header this keyword stands for the entire list of optional
! argument. Here,  at var{varargin} may only appear once and must be the 
last element in the list
! of arguments. Within the function body  at var{varargin} is an ordinary 
cell array containing
!  at c XXX FIXME XXX -- add a reference to cell arrays
! the optional arguments.  at var{varargin} may even be assigned to.
!  at end defvr
!
! This feature can be useful to implement default values as in this example:
!
!  at example
! function footwo (varargin)
!   if length(varargin) == 0
!     varargin = {"default argument"};
!   end
!   for n = 1:length(varargin)
!     disp(varargin{n});
!   endfor
! endfunction
!  at end example
!
! If the function  at var{footwo} is called with no arguments, it will use 
the string
! "default argument" instead.
!
!  at c XXX FIXME XXX -- Should the old syntax remain part of the 
documentation?
!  at subsection Variable-length Argument Lists Using @var{...}
!
! Here is an example of a function that uses the old deprecated syntax 
to print a
  header followed by an unspecified number of values:
 
   at example
--- 356,370 ----
   at cindex Variable-length argument lists
   at cindex @code{...}
 
! Octave has a real mechanism for handling functions that take an
  unspecified number of arguments, so it is not necessary to place an
  upper bound on the number of optional arguments that a function can
  accept.
 
!  at c XXX FIXME XXX -- should we add a note about why this feature is not
!  at c compatible with Matlab 5?
 
! Here is an example of a function that uses the new syntax to print a
  header followed by an unspecified number of values:
 
   at example



-------------------------------------------------------------
Octave is freely available under the terms of the GNU GPL.

Octave's home on the web:  http://www.octave.org
How to fund new projects:  http://www.octave.org/funding.html
Subscription information:  http://www.octave.org/archive.html
-------------------------------------------------------------