Mercurial > hg > octave-lyh
changeset 3373:36405da8e173
[project @ 1999-11-23 20:54:17 by jwe]
line wrap: on
line diff
--- a/doc/interpreter/data.txi +++ b/doc/interpreter/data.txi @@ -123,52 +123,13 @@ data structure type doesn't have rows or columns, so the @code{rows} and @code{columns} functions return @minus{}1 for structure arguments. -@deftypefn {Function File} {} columns (@var{a}) -Return the number of columns of @var{a}. -@end deftypefn - -@deftypefn {Function File} {} rows (@var{a}) -Return the number of rows of @var{a}. -@end deftypefn +@DOCSTRING(columns) -@deftypefn {Function File} {} length (@var{a}) -Return the number of rows of @var{a} or the number of columns of -@var{a}, whichever is larger. -@end deftypefn - -@deftypefn {Function File} {} size (@var{a}, @var{n}) -Return the number rows and columns of @var{a}. - -With one input argument and one output argument, the result is returned -in a 2 element row vector. If there are two output arguments, the -number of rows is assigned to the first, and the number of columns to -the second. For example, +@DOCSTRING(rows) -@example -@group -size ([1, 2; 3, 4; 5, 6]) - @result{} [ 3, 2 ] - -[nr, nc] = size ([1, 2; 3, 4; 5, 6]) - @result{} nr = 3 - @result{} nc = 2 -@end group -@end example - -If given a second argument of either 1 or 2, @code{size} will return -only the row or column dimension. For example +@DOCSTRING(length) -@example -size ([1, 2; 3, 4; 5, 6], 2) - @result{} 2 -@end example +@DOCSTRING(size) -@noindent -returns the number of columns in the given matrix. -@end deftypefn +@DOCSTRING(isempty) -@deftypefn {Function File} {} isempty (@var{a}) -Return 1 if @var{a} is an empty matrix (either the number of rows, or -the number of columns, or both are zero). Otherwise, return 0. -@end deftypefn -
--- a/doc/interpreter/diffeq.txi +++ b/doc/interpreter/diffeq.txi @@ -40,29 +40,7 @@ @noindent using Hindmarsh's ODE solver @sc{Lsode}. -@deftypefn {Loadable Function} {} lsode (@var{fcn}, @var{x0}, @var{t}, @var{t_crit}) -Return a matrix of @var{x} as a function of @var{t}, given the initial -state of the system @var{x0}. Each row in the result matrix corresponds -to one of the elements in the vector @var{t}. The first element of -@var{t} corresponds to the initial state @var{x0}, so that the first row -of the output is @var{x0}. - -The first argument, @var{fcn}, is a string that names the function to -call to compute the vector of right hand sides for the set of equations. -It must have the form - -@example -@var{xdot} = f (@var{x}, @var{t}) -@end example - -@noindent -where @var{xdot} and @var{x} are vectors and @var{t} is a scalar. - -The fourth argument is optional, and may be used to specify a set of -times that the ODE solver should not integrate past. It is useful for -avoiding difficulties with singularities and points where there is a -discontinuity in the derivative. -@end deftypefn +@DOCSTRING(lsode) Here is an example of solving a set of three differential equations using @code{lsode}. Given the function @@ -107,13 +85,7 @@ @end group @end example -@deftypefn {Loadable Function} {} lsode_options (@var{opt}, @var{val}) -When called with two arguments, this function allows you set options -parameters for the function @code{lsode}. Given one argument, -@code{lsode_options} returns the value of the corresponding option. If -no arguments are supplied, the names of all the available options and -their current values are displayed. -@end deftypefn +@DOCSTRING(lsode_options) See Alan C. Hindmarsh, @cite{ODEPACK, A Systematized Collection of ODE Solvers}, in Scientific Computing, R. S. Stepleman, editor, (1983) for @@ -140,49 +112,9 @@ @noindent using Petzold's DAE solver @sc{Dassl}. -@deftypefn {Loadable Function} {[@var{x}, @var{xdot}] =} dassl (@var{fcn}, @var{x0}, @var{xdot0}, @var{t}, @var{t_crit}) -Return a matrix of states and their first derivatives with respect to -@var{t}. Each row in the result matrices correspond to one of the -elements in the vector @var{t}. The first element of @var{t} -corresponds to the initial state @var{x0} and derivative @var{xdot0}, so -that the first row of the output @var{x} is @var{x0} and the first row -of the output @var{xdot} is @var{xdot0}. - -The first argument, @var{fcn}, is a string that names the function to -call to compute the vector of residuals for the set of equations. -It must have the form - -@example -@var{res} = f (@var{x}, @var{xdot}, @var{t}) -@end example - -@noindent -where @var{x}, @var{xdot}, and @var{res} are vectors, and @var{t} is a -scalar. +@DOCSTRING(dassl) -The second and third arguments to @code{dassl} specify the initial -condition of the states and their derivatives, and the fourth argument -specifies a vector of output times at which the solution is desired, -including the time corresponding to the initial condition. - -The set of initial states and derivatives are not strictly required to -be consistent. In practice, however, @sc{Dassl} is not very good at -determining a consistent set for you, so it is best if you ensure that -the initial values result in the function evaluating to zero. - -The fifth argument is optional, and may be used to specify a set of -times that the DAE solver should not integrate past. It is useful for -avoiding difficulties with singularities and points where there is a -discontinuity in the derivative. -@end deftypefn - -@deftypefn {Loadable Function} {} dassl_options (@var{opt}, @var{val}) -When called with two arguments, this function allows you set options -parameters for the function @code{lsode}. Given one argument, -@code{dassl_options} returns the value of the corresponding option. If -no arguments are supplied, the names of all the available options and -their current values are displayed. -@end deftypefn +@DOCSTRING(dassl_options) See K. E. Brenan, et al., @cite{Numerical Solution of Initial-Value Problems in Differential-Algebraic Equations}, North-Holland (1989) for
--- a/doc/interpreter/errors.txi +++ b/doc/interpreter/errors.txi @@ -10,131 +10,19 @@ when they encounter abnormal conditions, you should print the error messages using the functions described in this chapter. -@deftypefn {Built-in Function} {} error (@var{template}, @dots{}) -The @code{error} function formats the optional arguments under the -control of the template string @var{template} using the same rules as -the @code{printf} family of functions (@pxref{Formatted Output}). -The resulting message is prefixed by the string @samp{error: } and -printed on the @code{stderr} stream. - -Calling @code{error} also sets Octave's internal error state such that -control will return to the top level without evaluating any more -commands. This is useful for aborting from functions or scripts. - -If the error message does not end with a new line character, Octave will -print a traceback of all the function calls leading to the error. For -example, given the following function definitions: - -@example -@group -function f () g () end -function g () h () end -function h () nargin == 1 || error ("nargin != 1"); end -@end group -@end example - -@noindent -calling the function @code{f} will result in a list of messages that -can help you to quickly locate the exact location of the error: +@DOCSTRING(error) -@example -@group -f () -error: nargin != 1 -error: evaluating index expression near line 1, column 30 -error: evaluating binary operator `||' near line 1, column 27 -error: called from `h' -error: called from `g' -error: called from `f' -@end group -@end example - -If the error message ends in a new line character, Octave will print the -message but will not display any traceback messages as it returns -control to the top level. For example, modifying the error message -in the previous example to end in a new line causes Octave to only print -a single message: - -@example -@group -function h () nargin == 1 || error ("nargin != 1\n"); end -f () -error: nargin != 1 -@end group -@end example -@end deftypefn +@DOCSTRING(error_text) -@defvr {Built-in Variable} error_text -This variable contains the text of error messages that would have -been printed in the body of the most recent @code{unwind_protect} or -@code{try} statement or the @var{try} part of the most recent call to -the @code{eval} function. Outside of the @code{unwind_protect} and -@code{try} statements or the @code{eval} function, or if no error has -occurred within them, the value of @code{error_text} is guaranteed to be -the empty string. - -Note that the message does not include the first @samp{error: } prefix, -so that it may easily be passed to the @code{error} function without -additional processing@footnote{Yes, it's a kluge, but it seems to be a -reasonably useful one.}. - -@xref{The try Statement} and @ref{The unwind_protect Statement}. -@end defvr - -@defvr {Built-in Variable} beep_on_error -If the value of @code{beep_on_error} is nonzero, Octave will try -to ring your terminal's bell before printing an error message. The -default value is 0. -@end defvr +@DOCSTRING(beep_on_error) -@deftypefn {Built-in Function} {} warning (@var{msg}) -Print a warning message @var{msg} prefixed by the string @samp{warning: }. -After printing the warning message, Octave will continue to execute -commands. You should use this function should when you want to notify -the user of an unusual condition, but only when it makes sense for your -program to go on. -@end deftypefn - -@deftypefn {Built-in Function} {} usage (@var{msg}) -Print the message @var{msg}, prefixed by the string @samp{usage: }, and -set Octave's internal error state such that control will return to the -top level without evaluating any more commands. This is useful for -aborting from functions. - -After @code{usage} is evaluated, Octave will print a traceback of all -the function calls leading to the usage message. +@DOCSTRING(warning) -You should use this function for reporting problems errors that result -from an improper call to a function, such as calling a function with an -incorrect number of arguments, or with arguments of the wrong type. For -example, most functions distributed with Octave begin with code like -this - -@example -@group -if (nargin != 2) - usage ("foo (a, b)"); -endif -@end group -@end example - -@noindent -to check for the proper number of arguments. -@end deftypefn +@DOCSTRING(usage) The following pair of functions are of limited usefulness, and may be removed from future versions of Octave. -@deftypefn {Function File} {} perror (@var{name}, @var{num}) -Print the error message for function @var{name} corresponding to the -error number @var{num}. This function is intended to be used to print -useful error messages for those functions that return numeric error -codes. -@end deftypefn +@DOCSTRING(perror) -@deftypefn {Function File} {} strerror (@var{name}, @var{num}) -Return the text of an error message for function @var{name} -corresponding to the error number @var{num}. This function is intended -to be used to print useful error messages for those functions that -return numeric error codes. -@end deftypefn +@DOCSTRING(strerror)
--- a/doc/interpreter/image.txi +++ b/doc/interpreter/image.txi @@ -17,122 +17,32 @@ to improve Octave's image processing capabilities in other ways, please contact @email{bug-octave@@bevo.che.wisc.edu}. -@deftypefn {Function File} {} colormap (@var{map}) -@deftypefnx {Function File} {} colormap ("default") -Set the current colormap. - -@code{colormap (@var{map})} sets the current colormap to @var{map}. The -color map should be an @var{n} row by 3 column matrix. The columns -contain red, green, and blue intensities respectively. All entries -should be between 0 and 1 inclusive. The new colormap is returned. - -@code{colormap ("default")} restores the default colormap (a gray scale -colormap with 64 entries). The default colormap is returned. +@DOCSTRING(colormap) -With no arguments, @code{colormap} returns the current color map. -@end deftypefn +@DOCSTRING(gray) -@deftypefn {Function File} {} gray (@var{n}) -Return a gray colormap with @var{n} entries corresponding to values from -0 to @var{n}-1. The argument @var{n} should be a scalar. If it is -omitted, 64 is assumed. -@end deftypefn - -@deftypefn {Function File} {[@var{img}, @var{map}] =} gray2ind (@var{}) -Convert a gray scale intensity image to an Octave indexed image. -@end deftypefn +@DOCSTRING(gray2ind) -@deftypefn {Function File} {} image (@var{x}, @var{zoom}) -Display a matrix as a color image. The elements of @var{x} are indices -into the current colormap and should have values between 1 and the -length of the colormap. If @var{zoom} is omitted, a value of 4 is -assumed. -@end deftypefn +@DOCSTRING(image) -@deftypefn {Function File} {} imagesc (@var{x}, @var{zoom}) -Display a scaled version of the matrix @var{x} as a color image. The -matrix is scaled so that its entries are indices into the current -colormap. The scaled matrix is returned. If @var{zoom} is omitted, a -value of 4 is assumed. -@end deftypefn +@DOCSTRING(imagesc) -@deftypefn {Function File} {} imshow (@var{x}, @var{map}) -@deftypefnx {Function File} {} imshow (@var{x}, @var{n}) -@deftypefnx {Function File} {} imshow (@var{i}, @var{n}) -@deftypefnx {Function File} {} imshow (@var{r}, @var{g}, @var{b}) -Display images. +@DOCSTRING(imshow) -@code{imshow (@var{x})} displays an indexed image using the current -colormap. - -@code{imshow (@var{x}, @var{map})} displays an indexed image using the -specified colormap. - -@code{imshow (@var{i}, @var{n})} displays a gray scale intensity image. - -@code{imshow (@var{r}, @var{g}, @var{b})} displays an RGB image. -@end deftypefn +@DOCSTRING(ind2gray) -@deftypefn {Function File} {} ind2gray (@var{x}, @var{map}) -Convert an Octave indexed image to a gray scale intensity image. -If @var{map} is omitted, the current colormap is used to determine the -intensities. -@end deftypefn +@DOCSTRING(ind2rgb) -@deftypefn {Function File} {[@var{r}, @var{g}, @var{b}] =} ind2rgb (@var{x}, @var{map}) -Convert an indexed image to red, green, and blue color components. -If @var{map} is omitted, the current colormap is used for the conversion. -@end deftypefn +@DOCSTRING(loadimage) -@deftypefn {Function File} {[@var{x}, @var{map}] =} loadimage (@var{file}) -Load an image file and it's associated color map from the specified -@var{file}. The image must be stored in Octave's image format. -@end deftypefn - -@deftypefn {Function File} {} rgb2ntsc (@var{rgb}) -Image format conversion. -@end deftypefn +@DOCSTRING(rgb2ntsc) -@deftypefn {Function File} {} ntsc2rgb (@var{yiq}) -Image format conversion. -@end deftypefn - -@deftypefn {Function File} {} ocean (@var{n}) -Create color colormap. The argument @var{n} should be a scalar. If it -is omitted, 64 is assumed. -@end deftypefn +@DOCSTRING(ntsc2rgb) -@deftypefn {Function File} {[@var{x}, @var{map}] =} rgb2ind (@var{r}, @var{g}, @var{b}) -Convert and RGB image to an Octave indexed image. -@end deftypefn +@DOCSTRING(ocean) -@deftypefn {Function File} {} saveimage (@var{file}, @var{x}, @var{fmt}, @var{map}) -Save the matrix @var{x} to @var{file} in image format @var{fmt}. Valid -values for @var{fmt} are - -@table @code -@item "img" -Octave's image format. The current colormap is also saved in the file. - -@item "ppm" -Portable pixmap format. +@DOCSTRING(rgb2ind) -@item "ps" -PostScript format. Note that images saved in PostScript format can not -be read back into Octave with loadimage. -@end table - -If the fourth argument is supplied, the specified colormap will also be -saved along with the image. +@DOCSTRING(saveimage) -Note: if the colormap contains only two entries and these entries are -black and white, the bitmap ppm and PostScript formats are used. If the -image is a gray scale image (the entries within each row of the colormap -are equal) the gray scale ppm and PostScript image formats are used, -otherwise the full color formats are used. -@end deftypefn - -@defvr {Built-in Variable} IMAGEPATH -A colon separated list of directories in which to search for image -files. -@end defvr +@DOCSTRING(IMAGEPATH)
--- a/doc/interpreter/io.txi +++ b/doc/interpreter/io.txi @@ -85,9 +85,9 @@ @DOCSTRING(ans) -DOCSTRING(disp) +@DOCSTRING(disp) -DOCSTRING(format) +@DOCSTRING(format) @DOCSTRING(print_answer_id_name)
--- a/doc/interpreter/linalg.txi +++ b/doc/interpreter/linalg.txi @@ -19,58 +19,58 @@ @node Basic Matrix Functions, Matrix Factorizations, Linear Algebra, Linear Algebra @section Basic Matrix Functions -DOCSTRING(balance) +@DOCSTRING(balance) -DOCSTRING(cond) +@DOCSTRING(cond) -DOCSTRING(det) +@DOCSTRING(det) -DOCSTRING(eig) +@DOCSTRING(eig) -DOCSTRING(givens) +@DOCSTRING(givens) -DOCSTRING(inv) +@DOCSTRING(inv) -DOCSTRING(norm) +@DOCSTRING(norm) -DOCSTRING(null) +@DOCSTRING(null) -DOCSTRING(orth) +@DOCSTRING(orth) -DOCSTRING(pinv) +@DOCSTRING(pinv) -DOCSTRING(rank) +@DOCSTRING(rank) -DOCSTRING(trace) +@DOCSTRING(trace) @node Matrix Factorizations, Functions of a Matrix, Basic Matrix Functions, Linear Algebra @section Matrix Factorizations -DOCSTRING(chol) +@DOCSTRING(chol) -DOCSTRING(hess) +@DOCSTRING(hess) -DOCSTRING(lu) +@DOCSTRING(lu) -DOCSTRING(qr) +@DOCSTRING(qr) -DOCSTRING(qz) +@DOCSTRING(qz) -DOCSTRING(qzhess) +@DOCSTRING(qzhess) -DOCSTRING(schur) +@DOCSTRING(schur) -DOCSTRING(svd) +@DOCSTRING(svd) @node Functions of a Matrix, , Matrix Factorizations, Linear Algebra @section Functions of a Matrix -DOCSTRING(expm) +@DOCSTRING(expm) -DOCSTRING(logm) +@DOCSTRING(logm) -DOCSTRING(sqrtm) +@DOCSTRING(sqrtm) -DOCSTRING(kron) +@DOCSTRING(kron) -DOCSTRING(syl) +@DOCSTRING(syl)
--- a/scripts/ChangeLog +++ b/scripts/ChangeLog @@ -9,6 +9,24 @@ * linear-algebra/trace.m: Ditto. * linear-algebra/qzhess.m: Ditto. * miscellaneous/menu.m: Ditto. + * general/perror.m: Ditto. + * general/strerror.m: Ditto. + * general/columns.m: Ditto. + * general/rows.m: Ditto. + * image/colormap.m: Ditto. + * image/gray.m: Ditto. + * image/gray2ind.m: Ditto. + * image/image.m: Ditto. + * image/imagesc.m: Ditto. + * image/imshow.m: Ditto. + * image/ind2gray.m: Ditto. + * image/ind2rgb.m: Ditto. + * image/loadimage.m: Ditto. + * image/rgb2ntsc.m: Ditto. + * image/ntsc2rgb.m: Ditto. + * image/ocean.m: Ditto. + * image/rgb2ind.m: Ditto. + * image/saveimage.m: Ditto. * io/printf.m: Ditto. * io/puts.m: Ditto.
--- a/scripts/general/columns.m +++ b/scripts/general/columns.m @@ -17,10 +17,10 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: columns (x) -## -## Return the the number of columns in x. -## +## @deftypefn {Function File} {} columns (@var{a}) +## Return the number of columns of @var{a}. +## @end deftypefn + ## See also: size, rows, length, is_scalar, is_vector, is_matrix ## Author: jwe
--- a/scripts/general/is_scalar.m +++ b/scripts/general/is_scalar.m @@ -18,7 +18,7 @@ ## 02111-1307, USA. ## -*- texinfo -*- -## @deftypefn {Usage} {} is_scalar (@var{a}) +## @deftypefn {Function File} {} is_scalar (@var{a}) ## Return 1 if @var{a} is a scalar. Otherwise, return 0. ## @end deftypefn
--- a/scripts/general/is_square.m +++ b/scripts/general/is_square.m @@ -18,7 +18,7 @@ ## 02111-1307, USA. ## -*- texinfo -*- -## @deftypefn {Usage} {} is_square (@var{x}) +## @deftypefn {Function File} {} is_square (@var{x}) ## If @var{x} is a square matrix, then return the dimension of @var{x}. ## Otherwise, return 0. ## @end deftypefn
--- a/scripts/general/is_vector.m +++ b/scripts/general/is_vector.m @@ -18,7 +18,7 @@ ## 02111-1307, USA. ## -*- texinfo -*- -## @deftypefn {Usage} {} is_vector (@var{a}) +## @deftypefn {Function File} {} is_vector (@var{a}) ## Return 1 if @var{a} is a vector. Otherwise, return 0. ## @end deftypefn
--- a/scripts/general/perror.m +++ b/scripts/general/perror.m @@ -17,10 +17,13 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: perror (name, err) -## -## Print an error message for error number `err' from function "name". -## +## @deftypefn {Function File} {} perror (@var{name}, @var{num}) +## Print the error message for function @var{name} corresponding to the +## error number @var{num}. This function is intended to be used to print +## useful error messages for those functions that return numeric error +## codes. +## @end deftypefn + ## See also: strerror ## Author: jwe
--- a/scripts/general/rows.m +++ b/scripts/general/rows.m @@ -17,10 +17,10 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: rows (x) -## -## Return the the number of rows in x. -## +## @deftypefn {Function File} {} rows (@var{a}) +## Return the number of rows of @var{a}. +## @end deftypefn + ## See also: size, columns, length, is_scalar, is_vector, is_matrix ## Author: jwe
--- a/scripts/general/strerror.m +++ b/scripts/general/strerror.m @@ -17,10 +17,12 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: msg = strerror (name, err) -## -## Return the text of an error message for error number `err' from -## function "name". +## @deftypefn {Function File} {} strerror (@var{name}, @var{num}) +## Return the text of an error message for function @var{name} +## corresponding to the error number @var{num}. This function is intended +## to be used to print useful error messages for those functions that +## return numeric error codes. +## @end deftypefn ## Author: jwe
--- a/scripts/image/colormap.m +++ b/scripts/image/colormap.m @@ -17,17 +17,20 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. +## @deftypefn {Function File} {} colormap (@var{map}) +## @deftypefnx {Function File} {} colormap ("default") ## Set the current colormap. -## -## colormap (map) sets the current colormap to map. map should be an n -## row by 3 column matrix. The columns contain red, green, and blue -## intensities respectively. All entries should be between 0 and 1 -## inclusive. The new colormap is returned. -## -## colormap ("default") restores the default colormap (a gray scale -## colormap with 64 entries). The default colormap is returned. -## -## colormap with no arguments returns the current colormap. +## +## @code{colormap (@var{map})} sets the current colormap to @var{map}. The +## color map should be an @var{n} row by 3 column matrix. The columns +## contain red, green, and blue intensities respectively. All entries +## should be between 0 and 1 inclusive. The new colormap is returned. +## +## @code{colormap ("default")} restores the default colormap (a gray scale +## colormap with 64 entries). The default colormap is returned. +## +## With no arguments, @code{colormap} returns the current color map. +## @end deftypefn ## Author: Tony Richardson <arichard@stark.cc.oh.us> ## Created: July 1994
--- a/scripts/image/gray.m +++ b/scripts/image/gray.m @@ -17,7 +17,11 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## Colormap. +## @deftypefn {Function File} {} gray (@var{n}) +## Return a gray colormap with @var{n} entries corresponding to values from +## 0 to @var{n}-1. The argument @var{n} should be a scalar. If it is +## omitted, 64 is assumed. +## @end deftypefn ## Author: Tony Richardson <arichard@stark.cc.oh.us> ## Created: July 1994
--- a/scripts/image/gray2ind.m +++ b/scripts/image/gray2ind.m @@ -17,7 +17,9 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## Image format conversion +## @deftypefn {Function File} {[@var{img}, @var{map}] =} gray2ind (@var{}) +## Convert a gray scale intensity image to an Octave indexed image. +## @end deftypefn ## Author: Tony Richardson <arichard@stark.cc.oh.us> ## Created: July 1994
--- a/scripts/image/image.m +++ b/scripts/image/image.m @@ -17,14 +17,13 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## Display an octave image matrix. -## -## image (x) displays a matrix as a color image. The elements of x are -## indices into the current colormap and should have values between 1 -## and the length of the colormap. -## -## image (x, zoom) changes the zoom factor. The default value is 4. -## +## @deftypefn {Function File} {} image (@var{x}, @var{zoom}) +## Display a matrix as a color image. The elements of @var{x} are indices +## into the current colormap and should have values between 1 and the +## length of the colormap. If @var{zoom} is omitted, a value of 4 is +## assumed. +## @end deftypefn + ## SEE ALSO: imshow, imagesc, colormap. ## Author: Tony Richardson <arichard@stark.cc.oh.us>
--- a/scripts/image/imagesc.m +++ b/scripts/image/imagesc.m @@ -17,14 +17,13 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## Scale and display a matrix as an image. -## -## imagesc(x) displays a scaled version of the matrix x. The matrix is -## scaled so that its entries are indices into the current colormap. -## The scaled matrix is returned. -## -## imagesc (x, zoom) sets the magnification, the default value is 4. -## +## @deftypefn {Function File} {} imagesc (@var{x}, @var{zoom}) +## Display a scaled version of the matrix @var{x} as a color image. The +## matrix is scaled so that its entries are indices into the current +## colormap. The scaled matrix is returned. If @var{zoom} is omitted, a +## value of 4 is assumed. +## @end deftypefn + ## SEE ALSO: image, imshow ## Author: Tony Richardson <arichard@stark.cc.oh.us>
--- a/scripts/image/imshow.m +++ b/scripts/image/imshow.m @@ -17,16 +17,23 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. +## @deftypefn {Function File} {} imshow (@var{x}, @var{map}) +## @deftypefnx {Function File} {} imshow (@var{x}, @var{n}) +## @deftypefnx {Function File} {} imshow (@var{i}, @var{n}) +## @deftypefnx {Function File} {} imshow (@var{r}, @var{g}, @var{b}) ## Display images. -## -## imshow (X) displays an indexed image using the current colormap. -## -## imshow (X, map) displays an indexed image using the specified colormap. -## -## imshow (I, n) displays a gray scale intensity image. -## -## imshow (R, G, B) displays an RGB image. -## +## +## @code{imshow (@var{x})} displays an indexed image using the current +## colormap. +## +## @code{imshow (@var{x}, @var{map})} displays an indexed image using the +## specified colormap. +## +## @code{imshow (@var{i}, @var{n})} displays a gray scale intensity image. +## +## @code{imshow (@var{r}, @var{g}, @var{b})} displays an RGB image. +## @end deftypefn + ## SEE ALSO: image, imagesc, colormap, gray2ind, rgb2ind. ## Author: Tony Richardson <arichard@stark.cc.oh.us>
--- a/scripts/image/ind2gray.m +++ b/scripts/image/ind2gray.m @@ -17,15 +17,12 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## Convert an octave indexed image to a gray scale intensity image. -## -## Y = ind2gray (X) converts an indexed image to a gray scale intensity -## image. The current colormap is used to determine the intensities. -## The intensity values lie between 0 and 1 inclusive. -## -## Y = ind2gray (X, map) uses the specified colormap instead of the -## current one in the conversion process. -## +## @deftypefn {Function File} {} ind2gray (@var{x}, @var{map}) +## Convert an Octave indexed image to a gray scale intensity image. +## If @var{map} is omitted, the current colormap is used to determine the +## intensities. +## @end deftypefn + ## SEE ALSO: gray2ind, rgb2ntsc, image, colormap ## Author: Tony Richardson <arichard@stark.cc.oh.us>
--- a/scripts/image/ind2rgb.m +++ b/scripts/image/ind2rgb.m @@ -17,12 +17,11 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. +## @deftypefn {Function File} {[@var{r}, @var{g}, @var{b}] =} ind2rgb (@var{x}, @var{map}) ## Convert an indexed image to red, green, and blue color components. -## -## [R G B] = ind2rgb(X) uses the current colormap for the conversion. -## -## [R G B] = ind2rgb(X,map) uses the specified colormap. -## +## If @var{map} is omitted, the current colormap is used for the conversion. +## @end deftypefn + ## SEE ALSO: rgb2ind, image, imshow, ind2gray, gray2ind. ## Author: Tony Richardson <arichard@stark.cc.oh.us>
--- a/scripts/image/loadimage.m +++ b/scripts/image/loadimage.m @@ -17,12 +17,11 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## Load an image file. -## -## [img, map] = loadimage (img_file) loads an image and it's associated -## color map from file img_file. The image must be in stored in -## octave's image format. -## +## @deftypefn {Function File} {[@var{x}, @var{map}] =} loadimage (@var{file}) +## Load an image file and it's associated color map from the specified +## @var{file}. The image must be stored in Octave's image format. +## @end deftypefn + ## SEE ALSO: saveimage, load, save ## Author: Tony Richardson <arichard@stark.cc.oh.us>
--- a/scripts/image/ntsc2rgb.m +++ b/scripts/image/ntsc2rgb.m @@ -17,7 +17,9 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. +## @deftypefn {Function File} {} ntsc2rgb (@var{yiq}) ## Image format conversion. +## @end deftypefn ## Author: Tony Richardson <arichard@stark.cc.oh.us> ## Created: July 1994
--- a/scripts/image/ocean.m +++ b/scripts/image/ocean.m @@ -17,7 +17,10 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## Colormap. +## @deftypefn {Function File} {} ocean (@var{n}) +## Create color colormap. The argument @var{n} should be a scalar. If it +## is omitted, 64 is assumed. +## @end deftypefn ## Author: Tony Richardson <arichard@stark.cc.oh.us> ## Created: July 1994
--- a/scripts/image/rgb2ind.m +++ b/scripts/image/rgb2ind.m @@ -17,10 +17,10 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## Convert and RGB image to an octave indexed image. -## -## [X, map] = rgb2ind (R, G, B) -## +## @deftypefn {Function File} {[@var{x}, @var{map}] =} rgb2ind (@var{r}, @var{g}, @var{b}) +## Convert and RGB image to an Octave indexed image. +## @end deftypefn + ## SEE ALSO: ind2rgb, rgb2ntsc. ## ## Bugs: The color map may have duplicate entries.
--- a/scripts/image/rgb2ntsc.m +++ b/scripts/image/rgb2ntsc.m @@ -17,7 +17,9 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. +## @deftypefn {Function File} {} rgb2ntsc (@var{rgb}) ## Image format conversion. +## @end deftypefn ## Author: Tony Richardson <arichard@stark.cc.oh.us> ## Created: July 1994
--- a/scripts/image/saveimage.m +++ b/scripts/image/saveimage.m @@ -17,30 +17,32 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## Save a matrix to disk in image format. -## -## saveimage (filename, x) saves matrix x to file filename in octave's -## image format. The current colormap is saved in the file also. -## -## saveimage (filename, x, "img") saves the image in the default format -## and is the same as saveimage (filename, x). -## -## saveimage (filename, x, "ppm") saves the image in ppm format instead -## of the default octave image format. -## -## saveimage (filename, x, "ps") saves the image in PostScript format -## instead of the default octave image format. (Note: images saved in -## PostScript format can not be read back into octave with loadimage.) -## -## saveimage (filename, x, format, map) saves the image along with the -## specified colormap in the specified format. -## -## Note: If the colormap contains only two entries and these entries -## are black and white, the bitmap ppm and PostScript formats are used. -## If the image is a gray scale image (the entries within each row of -## the colormap are equal) the gray scale ppm and PostScript image -## formats are used, otherwise the full color formats are used. -## +## @deftypefn {Function File} {} saveimage (@var{file}, @var{x}, @var{fmt}, @var{map}) +## Save the matrix @var{x} to @var{file} in image format @var{fmt}. Valid +## values for @var{fmt} are +## +## @table @code +## @item "img" +## Octave's image format. The current colormap is also saved in the file. +## +## @item "ppm" +## Portable pixmap format. +## +## @item "ps" +## PostScript format. Note that images saved in PostScript format can not +## be read back into Octave with loadimage. +## @end table +## +## If the fourth argument is supplied, the specified colormap will also be +## saved along with the image. +## +## Note: if the colormap contains only two entries and these entries are +## black and white, the bitmap ppm and PostScript formats are used. If the +## image is a gray scale image (the entries within each row of the colormap +## are equal) the gray scale ppm and PostScript image formats are used, +## otherwise the full color formats are used. +## @end deftypefn + ## The conversion to PostScript is based on pbmtolps.c, which was ## written by ## @@ -49,7 +51,7 @@ ## University of British Columbia ## ## and is part of the portable bitmap utilities, -## + ## SEE ALSO: loadimage, save, load, colormap ## Author: Tony Richardson <arichard@stark.cc.oh.us>
--- a/scripts/io/puts.m +++ b/scripts/io/puts.m @@ -17,8 +17,8 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. --*- texinfo -*-\n\ -## @deftypefn {Built-in Function} {} puts (@var{string}) +## -*- texinfo -*- +## @deftypefn {Function File} {} puts (@var{string}) ## Write a string to the standard output with no formatting. ## @end deftypefn
--- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,26 +1,32 @@ 1999-11-23 John W. Eaton <jwe@bevo.che.wisc.edu> - * balance.cc (Fbalance): Texinfoize doc string. - * det.cc (Fdet): Ditto. - * eig.cc (Feig): Ditto. - * givens.cc (Fgivens): Ditto. - * inv.cc (Finv): Ditto. - * chol.cc (Fchol): Ditto. - * hess.cc (Fhess): Ditto. - * lu.cc (Flu): Ditto. - * qr.cc (Fqr): Ditto. - * schur.cc (Fschur): Ditto. - * svd.cc (Fsvd): Ditto. - * expm.cc (Fexpm): Ditto. - * log.cc (Flogm, Fsqrtm): Ditto. - * syl.cc (Fsyl): Ditto. - * pinv.cc (Fpinv): Ditto. - * qz.cc (Fqz): Ditto. + * DLD-FUNCTIONS/balance.cc (Fbalance): Texinfoize doc string. + * DLD-FUNCTIONS/det.cc (Fdet): Ditto. + * DLD-FUNCTIONS/eig.cc (Feig): Ditto. + * DLD-FUNCTIONS/givens.cc (Fgivens): Ditto. + * DLD-FUNCTIONS/inv.cc (Finv): Ditto. + * DLD-FUNCTIONS/chol.cc (Fchol): Ditto. + * DLD-FUNCTIONS/hess.cc (Fhess): Ditto. + * DLD-FUNCTIONS/lu.cc (Flu): Ditto. + * DLD-FUNCTIONS/qr.cc (Fqr): Ditto. + * DLD-FUNCTIONS/schur.cc (Fschur): Ditto. + * DLD-FUNCTIONS/svd.cc (Fsvd): Ditto. + * DLD-FUNCTIONS/expm.cc (Fexpm): Ditto. + * DLD-FUNCTIONS/log.cc (Flogm, Fsqrtm): Ditto. + * DLD-FUNCTIONS/syl.cc (Fsyl): Ditto. + * DLD-FUNCTIONS/pinv.cc (Fpinv): Ditto. + * DLD-FUNCTIONS/qz.cc (Fqz): Ditto. + * DLD-FUNCTIONS/dassl.cc (Fdassl, Fdassl_options): Ditto. + * DLD-FUNCTIONS/lsode.cc (Flsode, Flsode_options): Ditto. + * data.cc (Flength, Fsize, Fisempty): Ditto. * sysdep.cc (Fkbhit): Ditto. * input.cc (Fkeyboard, Finput): Ditto. * variables.cc (ans): Ditto. * pr-output.cc (Fdisp, Fformat): Ditto. * ov.cc (Vprint_answer_id_name): Ditto. + * defaults.cc (IMAGEPATH): Ditto. + * error.cc (Ferror, Fwarning, Fusage, error_text, beep_on_error): + Ditto. * load-save.cc (Fload, Fsave, Vdefault_save_format, Vsave_precision): Ditto. * file-io.cc (Ffflush, Ffopen, Ffclose, Ffputs, Ffgetl, Ffgets,
--- a/src/DLD-FUNCTIONS/dassl.cc +++ b/src/DLD-FUNCTIONS/dassl.cc @@ -133,15 +133,42 @@ while (0) DEFUN_DLD (dassl, args, , - "dassl (\"function_name\", x_0, xdot_0, t_out)\n\ -dassl (F, X_0, XDOT_0, T_OUT, T_CRIT)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {[@var{x}, @var{xdot}] =} dassl (@var{fcn}, @var{x0}, @var{xdot0}, @var{t}, @var{t_crit})\n\ +Return a matrix of states and their first derivatives with respect to\n\ +@var{t}. Each row in the result matrices correspond to one of the\n\ +elements in the vector @var{t}. The first element of @var{t}\n\ +corresponds to the initial state @var{x0} and derivative @var{xdot0}, so\n\ +that the first row of the output @var{x} is @var{x0} and the first row\n\ +of the output @var{xdot} is @var{xdot0}.\n\ +\n\ +The first argument, @var{fcn}, is a string that names the function to\n\ +call to compute the vector of residuals for the set of equations.\n\ +It must have the form\n\ +\n\ +@example\n\ +@var{res} = f (@var{x}, @var{xdot}, @var{t})\n\ +@end example\n\ \n\ -The first argument is the name of the function to call to\n\ -compute the vector of residuals. It must have the form\n\ +@noindent\n\ +where @var{x}, @var{xdot}, and @var{res} are vectors, and @var{t} is a\n\ +scalar.\n\ +\n\ +The second and third arguments to @code{dassl} specify the initial\n\ +condition of the states and their derivatives, and the fourth argument\n\ +specifies a vector of output times at which the solution is desired, \n\ +including the time corresponding to the initial condition.\n\ \n\ - res = f (x, xdot, t)\n\ +The set of initial states and derivatives are not strictly required to\n\ +be consistent. In practice, however, @sc{Dassl} is not very good at\n\ +determining a consistent set for you, so it is best if you ensure that\n\ +the initial values result in the function evaluating to zero.\n\ \n\ -where x, xdot, and res are vectors, and t is a scalar.") +The fifth argument is optional, and may be used to specify a set of\n\ +times that the DAE solver should not integrate past. It is useful for\n\ +avoiding difficulties with singularities and points where there is a\n\ +discontinuity in the derivative.\n\ +@end deftypefn") { octave_value_list retval; @@ -351,10 +378,14 @@ } DEFUN_DLD (dassl_options, args, , - "dassl_options (KEYWORD, VALUE)\n\ -\n\ -Set or show options for dassl. Keywords may be abbreviated\n\ -to the shortest match.") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} dassl_options (@var{opt}, @var{val})\n\ +When called with two arguments, this function allows you set options\n\ +parameters for the function @code{lsode}. Given one argument,\n\ +@code{dassl_options} returns the value of the corresponding option. If\n\ +no arguments are supplied, the names of all the available options and\n\ +their current values are displayed.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/lsode.cc +++ b/src/DLD-FUNCTIONS/lsode.cc @@ -157,14 +157,30 @@ while (0) DEFUN_DLD (lsode, args, nargout, - "lsode (F, X0, T_OUT, T_CRIT)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} lsode (@var{fcn}, @var{x0}, @var{t}, @var{t_crit})\n\ +Return a matrix of @var{x} as a function of @var{t}, given the initial\n\ +state of the system @var{x0}. Each row in the result matrix corresponds\n\ +to one of the elements in the vector @var{t}. The first element of\n\ +@var{t} corresponds to the initial state @var{x0}, so that the first row\n\ +of the output is @var{x0}.\n\ +\n\ +The first argument, @var{fcn}, is a string that names the function to\n\ +call to compute the vector of right hand sides for the set of equations.\n\ +It must have the form\n\ \n\ -The first argument is the name of the function to call to\n\ -compute the vector of right hand sides. It must have the form\n\ +@example\n\ +@var{xdot} = f (@var{x}, @var{t})\n\ +@end example\n\ \n\ - xdot = f (x, t)\n\ +@noindent\n\ +where @var{xdot} and @var{x} are vectors and @var{t} is a scalar.\n\ \n\ -where xdot and x are vectors and t is a scalar.\n") +The fourth argument is optional, and may be used to specify a set of\n\ +times that the ODE solver should not integrate past. It is useful for\n\ +avoiding difficulties with singularities and points where there is a\n\ +discontinuity in the derivative.\n\ +@end deftypefn") { octave_value_list retval; @@ -452,10 +468,14 @@ } DEFUN_DLD (lsode_options, args, , - "lsode_options (KEYWORD, VALUE)\n\ -\n\ -Set or show options for lsode. Keywords may be abbreviated\n\ -to the shortest match.") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} lsode_options (@var{opt}, @var{val})\n\ +When called with two arguments, this function allows you set options\n\ +parameters for the function @code{lsode}. Given one argument,\n\ +@code{lsode_options} returns the value of the corresponding option. If\n\ +no arguments are supplied, the names of all the available options and\n\ +their current values are displayed.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/data.cc +++ b/src/data.cc @@ -592,13 +592,12 @@ } DEFUN (length, args, , - "length (x): return the `length' of the object X\n\ -\n\ -For matrix objects, the length is the number of rows or columns,\n\ -whichever is greater (this odd definition is used for compatibility\n\ -with Matlab).\n\ -\n\ -See also: size, rows, columns, is_scalar, is_vector, is_matrix") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} length (@var{a})\n\ +Return the `lenghth' of the object @var{a}. For matrix objects, the\n\ +length is the number of rows or columns, whichever is greater (this\n\ +odd definition is used for compatibility with Matlab).\n\ +@end deftypefn") { octave_value retval; @@ -616,12 +615,37 @@ } DEFUN (size, args, nargout, - "[m, n] = size (x): return rows and columns of X\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} size (@var{a}, @var{n})\n\ +Return the number rows and columns of @var{a}.\n\ +\n\ +With one input argument and one output argument, the result is returned\n\ +in a 2 element row vector. If there are two output arguments, the\n\ +number of rows is assigned to the first, and the number of columns to\n\ +the second. For example,\n\ +\n\ +@example\n\ +@group\n\ +size ([1, 2; 3, 4; 5, 6])\n\ + @result{} [ 3, 2 ]\n\ \n\ -d = size (x): return number of rows and columns of x as a row vector\n\ +[nr, nc] = size ([1, 2; 3, 4; 5, 6])\n\ + @result{} nr = 3\n\ + @result{} nc = 2\n\ +@end group\n\ +@end example\n\ +\n\ +If given a second argument of either 1 or 2, @code{size} will return\n\ +only the row or column dimension. For example\n\ \n\ -m = size (x, 1): return number of rows in x\n\ -m = size (x, 2): return number of columns in x") +@example\n\ +size ([1, 2; 3, 4; 5, 6], 2)\n\ + @result{} 2\n\ +@end example\n\ +\n\ +@noindent\n\ +returns the number of columns in the given matrix.\n\ +@end deftypefn") { octave_value_list retval; @@ -789,7 +813,11 @@ } DEFUN (isempty, args, , - "isempty (x): return nonzero if x is an empty matrix, string, or list") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} isempty (@var{a})\n\ +Return 1 if @var{a} is an empty matrix (either the number of rows, or\n\ +the number of columns, or both are zero). Otherwise, return 0.\n\ +@end deftypefn") { double retval = 0.0; @@ -836,7 +864,7 @@ DEFUN (is_matrix, args, , "-*- texinfo -*-\n\ -@deftypefn {Usage} {} is_matrix (@var{a})\n\ +@deftypefn {Built-in Function} {} is_matrix (@var{a})\n\ Return 1 if @var{a} is a matrix. Otherwise, return 0.\n\ @end deftypefn") {
--- a/src/defaults.cc +++ b/src/defaults.cc @@ -489,17 +489,20 @@ @end defvr"); DEFVAR (IMAGEPATH, OCTAVE_IMAGEPATH, imagepath, - "colon separated list of directories to search for image files"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} IMAGEPATH +A colon separated list of directories in which to search for image\n\ +files.\n\ +@end defvr"); DEFCONST (OCTAVE_HOME, Voctave_home, "top-level Octave installation directory"); DEFCONSTX ("OCTAVE_VERSION", SBV_OCTAVE_VERSION, OCTAVE_VERSION, "-*- texinfo -*-\n\ -@defvr\n\ +@defvr {Built-in Variable} OCTAVE_VERSION\n\ The version number of Octave, as a string.\n\ @end defvr"); - } DEFUN (rehash, , ,
--- a/src/dynamic-ld.cc +++ b/src/dynamic-ld.cc @@ -340,7 +340,6 @@ @code{warn_reload_forces_clear}, Octave will warn you when this happens,\n\ and print a list of the additional functions that it is forced to clear.\n\ @end defvr"); - } /*
--- a/src/error.cc +++ b/src/error.cc @@ -265,31 +265,105 @@ } DEFUN (error, args, , - "error (FMT, ...): print message according to FMT and set error state.\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} error (@var{template}, @dots{})\n\ +The @code{error} function formats the optional arguments under the\n\ +control of the template string @var{template} using the same rules as\n\ +the @code{printf} family of functions (@pxref{Formatted Output}).\n\ +The resulting message is prefixed by the string @samp{error: } and\n\ +printed on the @code{stderr} stream.\n\ +\n\ +Calling @code{error} also sets Octave's internal error state such that\n\ +control will return to the top level without evaluating any more\n\ +commands. This is useful for aborting from functions or scripts.\n\ \n\ -This should eventually take us up to the top level, possibly\n\ -printing traceback messages as we go.\n\ +If the error message does not end with a new line character, Octave will\n\ +print a traceback of all the function calls leading to the error. For\n\ +example, given the following function definitions:\n\ +\n\ +@example\n\ +@group\n\ +function f () g () end\n\ +function g () h () end\n\ +function h () nargin == 1 || error (\"nargin != 1\"); end\n\ +@end group\n\ +@end example\n\ \n\ -If the resulting error message ends in a newline character, traceback\n\ -messages are not printed.\n\ +@noindent\n\ +calling the function @code{f} will result in a list of messages that\n\ +can help you to quickly locate the exact location of the error:\n\ \n\ -See also: printf") +@example\n\ +@group\n\ +f ()\n\ +error: nargin != 1\n\ +error: evaluating index expression near line 1, column 30\n\ +error: evaluating binary operator `||' near line 1, column 27\n\ +error: called from `h'\n\ +error: called from `g'\n\ +error: called from `f'\n\ +@end group\n\ +@end example\n\ +\n\ +If the error message ends in a new line character, Octave will print the\n\ +message but will not display any traceback messages as it returns\n\ +control to the top level. For example, modifying the error message\n\ +in the previous example to end in a new line causes Octave to only print\n\ +a single message:\n\ +\n\ +@example\n\ +@group\n\ +function h () nargin == 1 || error (\"nargin != 1\\n\"); end\n\ +f ()\n\ +error: nargin != 1\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { return handle_message (error, "unspecified error", args); } DEFUN (warning, args, , - "warning (FMT, ...): print a warning message according to FMT.\n\ -\n\ -See also: error, printf") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} warning (@var{msg})\n\ +Print a warning message @var{msg} prefixed by the string @samp{warning: }. \n\ +After printing the warning message, Octave will continue to execute\n\ +commands. You should use this function should when you want to notify\n\ +the user of an unusual condition, but only when it makes sense for your\n\ +program to go on.\n\ +@end deftypefn") { return handle_message (warning, "unspecified warning", args); } DEFUN (usage, args, , - "usage (FMT, ...): print a usage message according to FMT.\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} usage (@var{msg})\n\ +Print the message @var{msg}, prefixed by the string @samp{usage: }, and\n\ +set Octave's internal error state such that control will return to the\n\ +top level without evaluating any more commands. This is useful for\n\ +aborting from functions.\n\ +\n\ +After @code{usage} is evaluated, Octave will print a traceback of all\n\ +the function calls leading to the usage message.\n\ \n\ -See also: error, printf") +You should use this function for reporting problems errors that result\n\ +from an improper call to a function, such as calling a function with an\n\ +incorrect number of arguments, or with arguments of the wrong type. For\n\ +example, most functions distributed with Octave begin with code like\n\ +this\n\ +\n\ +@example\n\ +@group\n\ +if (nargin != 2)\n\ + usage (\"foo (a, b)\");\n\ +endif\n\ +@end group\n\ +@end example\n\ +\n\ +@noindent\n\ +to check for the proper number of arguments.\n\ +@end deftypefn") { return handle_message (usage, "unknown", args); } @@ -331,14 +405,31 @@ symbols_of_error (void) { DEFVAR (beep_on_error, 0.0, beep_on_error, - "if true, beep before printing error messages"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} beep_on_error\n\ +If the value of @code{beep_on_error} is nonzero, Octave will try\n\ +to ring your terminal's bell before printing an error message. The\n\ +default value is 0.\n\ +@end defvr"); DEFCONST (error_text, "", - "the text of error messages that would have been printed in the\n\ -body of the most recent unwind_protect statement or the TRY part of\n\ -the most recent eval() command. Outside of unwind_protect and\n\ -eval(), or if no error has ocurred within them, the value of\n\ -__error_text__ is guaranteed to be the empty string."); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} error_text\n\ +This variable contains the text of error messages that would have\n\ +been printed in the body of the most recent @code{unwind_protect} or\n\ +@code{try} statement or the @var{try} part of the most recent call to\n\ +the @code{eval} function. Outside of the @code{unwind_protect} and\n\ +@code{try} statements or the @code{eval} function, or if no error has\n\ +occurred within them, the value of @code{error_text} is guaranteed to be\n\ +the empty string.\n\ +\n\ +Note that the message does not include the first @samp{error: } prefix,\n\ +so that it may easily be passed to the @code{error} function without\n\ +additional processing@footnote{Yes, it's a kluge, but it seems to be a\n\ +reasonably useful one.}.\n\ +\n\ +@xref{The try Statement} and @ref{The unwind_protect Statement}.\n\ +@end defvr"); } /*
--- a/src/help.cc +++ b/src/help.cc @@ -1064,7 +1064,6 @@ will not add additional help information to the end of the output from\n\ the @code{help} command and usage messages for built-in commands.\n\ @end defvr"); - } /*
--- a/src/input.cc +++ b/src/input.cc @@ -1014,7 +1014,6 @@ The value of @code{echo_executing_commands} is set by the @kbd{echo}\n\ command and the command line option @code{--echo-input}.\n\ @end defvr"); - } /*
--- a/src/load-save.cc +++ b/src/load-save.cc @@ -2864,7 +2864,6 @@ This variable specifies the number of digits to keep when saving data in\n\ text format. The default value is 17.\n\ @end defvr"); - } /*
--- a/src/mappers.cc +++ b/src/mappers.cc @@ -221,7 +221,7 @@ DEFUN_MAPPER (ceil, 0, 0, 0, ceil, 0, ceil, 0.0, 0.0, 0, "-*- texinfo -*-\n\ -@deftypefn {Usage} {} ceil (@var{x})\n\ +@deftypefn {Mapping Function} {} ceil (@var{x})\n\ Return the smallest integer not less than @var{x}. If @var{x} is\n\ complex, return @code{ceil (real (@var{x})) + ceil (imag (@var{x})) * I}.\n\ @end deftypefn"); @@ -297,7 +297,7 @@ DEFUN_MAPPER (exp, 0, 0, 0, exp, 0, exp, 0.0, 0.0, 0, "-*- texinfo -*-\n\ -@deftypefn {Usage} {} exp (@var{x})\n\ +@deftypefn {Mapping Function} {} exp (@var{x})\n\ Compute the exponential of @var{x}. To compute the matrix exponential,\n\ see @ref{Linear Algebra}.\n\ @end deftypefn"); @@ -318,14 +318,14 @@ DEFUN_MAPPER (fix, 0, 0, 0, fix, 0, fix, 0.0, 0.0, 0, "-*- texinfo -*-\n\ -@deftypefn {Usage} {} fix (@var{x})\n\ +@deftypefn {Mapping Function} {} fix (@var{x})\n\ Truncate @var{x} toward zero. If @var{x} is complex, return\n\ @code{fix (real (@var{x})) + fix (imag (@var{x})) * I}.\n\ @end deftypefn"); DEFUN_MAPPER (floor, 0, 0, 0, floor, 0, floor, 0.0, 0.0, 0, "-*- texinfo -*-\n\ -@deftypefn {Usage} {} floor (@var{x})\n\ +@deftypefn {Mapping Function} {} floor (@var{x})\n\ Return the largest integer not greater than @var{x}. If @var{x} is\n\ complex, return @code{floor (real (@var{x})) + floor (imag (@var{x})) * I}.\n\ @end deftypefn");
--- a/src/oct-hist.cc +++ b/src/oct-hist.cc @@ -725,7 +725,6 @@ on the command line are saved in the file specified by the variable\n\ @code{history_file}.\n\ @end defvr"); - } /*
--- a/src/ov-usr-fcn.cc +++ b/src/ov-usr-fcn.cc @@ -641,7 +641,6 @@ @code{return_last_computed_value} is 0, or 4, if the value of\n\ @code{return_last_computed_value} is nonzero.\n\ @end defvr"); - } /*
--- a/src/ov.cc +++ b/src/ov.cc @@ -1616,7 +1616,6 @@ is issued when Octave encounters a division by zero. If the value is\n\ 0, the warning is omitted. The default value is 1.\n\ @end defvr"); - } /*
--- a/src/pager.cc +++ b/src/pager.cc @@ -555,7 +555,6 @@ (such as @code{less}---see @ref{Installation}) are also capable of moving\n\ backward on the output. The default value is 1.\n\ @end defvr"); - } /*
--- a/src/pr-output.cc +++ b/src/pr-output.cc @@ -2083,7 +2083,6 @@ @noindent\n\ The default value of @code{split_long_rows} is nonzero.\n\ @end defvr"); - } /*
--- a/src/pt-decl.cc +++ b/src/pt-decl.cc @@ -190,7 +190,7 @@ { DEFVAR (default_global_variable_value, , 0, "-*- texinfo -*-\n\ -@defvr default_global_variable_value\n\ +@defvr {Built-in Variable} default_global_variable_value\n\ The default for value for otherwise uninitialized global variables.\n\ Only used if the variable initialize_global_variables is nonzero.\n\ If @code{initialize_global_variables} is nonzero, the value of\n\
--- a/src/pt-mat.cc +++ b/src/pt-mat.cc @@ -663,7 +663,6 @@ @end group\n\ @end example\n\ @end defvr"); - } /*
--- a/src/pt-plot.cc +++ b/src/pt-plot.cc @@ -1351,7 +1351,6 @@ can be changed in your startup script or at the command line in case\n\ configure got it wrong, or if you upgrade your gnuplot installation.\n\ @end defvr"); - } /*
--- a/src/pt-stmt.cc +++ b/src/pt-stmt.cc @@ -209,7 +209,6 @@ is executed, Octave will either print @samp{ans = 4} or nothing\n\ depending on the value of @code{silent_functions}.\n\ @end defvr"); - } /*