Mercurial > octave-nkf
changeset 3372:f16c2ce14886
[project @ 1999-11-23 19:07:09 by jwe]
line wrap: on
line diff
--- a/doc/interpreter/io.txi Sun Nov 21 17:31:10 1999 +0000 +++ b/doc/interpreter/io.txi Tue Nov 23 19:07:18 1999 +0000 @@ -31,43 +31,15 @@ @code{PAGER}, and you can turn paging off by setting the value of the variable @code{page_screen_output} to 0. -@deffn {Command} more -@deffnx {Command} more on -@deffnx {Command} more off -Turn output pagination on or off. Without an argument, @code{more} -toggles the current state. -@end deffn +@DOCSTRING(more) -@defvr {Built-in Variable} PAGER -The default value is normally @code{"less"}, @code{"more"}, or -@code{"pg"}, depending on what programs are installed on your system. -@xref{Installation}. - -When running interactively, Octave sends any output intended for your -terminal that is more than one screen long to the program named by the -value of the variable @code{PAGER}. -@end defvr +@DOCSTRING(PAGER) -@defvr {Built-in Variable} page_screen_output -If the value of @code{page_screen_output} is nonzero, all output -intended for the screen that is longer than one page is sent through a -pager. This allows you to view one screenful at a time. Some pagers -(such as @code{less}---see @ref{Installation}) are also capable of moving -backward on the output. The default value is 1. -@end defvr +@DOCSTRING(page_screen_output) -@defvr {Built-in Variable} page_output_immediately -If the value of @code{page_output_immediately} is nonzero, Octave sends -output to the pager as soon as it is available. Otherwise, Octave -buffers its output and waits until just before the prompt is printed to -flush it to the pager. The default value is 0. +@DOCSTRING(page_output_immediately) -@deftypefn {Built-in Function} {} fflush (@var{fid}) -Flush output to @var{fid}. This is useful for ensuring that all -pending output makes it to the screen before some other event occurs. -For example, it is always a good idea to flush the standard output -stream before calling @code{input}. -@end deftypefn +@DOCSTRING(fflush) @c XXX FIXME XXX -- maybe this would be a good place to describe the @c following message: @@ -75,7 +47,6 @@ @c warning: connection to external pager (pid = 9334) lost -- @c warning: pending computations and output may be lost @c warning: broken pipe -@end defvr @menu * Basic Input and Output:: @@ -112,124 +83,13 @@ The @code{format} command offers some control over the way Octave prints values with @code{disp} and through the normal echoing mechanism. -@defvr {Built-in Variable} ans -This variable holds the most recently computed result that was not -explicitly assigned to a variable. For example, after the expression - -@example -3^2 + 4^2 -@end example - -@noindent -is evaluated, the value of @code{ans} is 25. -@end defvr - -@deftypefn {Built-in Function} {} disp (@var{x}) -Display the value of @var{x}. For example, - -@example -disp ("The value of pi is:"), disp (pi) - - @print{} the value of pi is: - @print{} 3.1416 -@end example - -@noindent -Note that the output from @code{disp} always ends with a newline. -@end deftypefn +@DOCSTRING(ans) -@deffn {Command} format options -Control the format of the output produced by @code{disp} and Octave's -normal echoing mechanism. Valid options are listed in the following -table. - -@table @code -@item short -Octave will try to print numbers with at -least 3 significant figures within a field that is a maximum of 8 -characters wide. - -If Octave is unable to format a matrix so that columns line up on the -decimal point and all the numbers fit within the maximum field width, -it switches to an @samp{e} format. - -@item long -Octave will try to print numbers with at least 15 significant figures -within a field that is a maximum of 24 characters wide. - -As will the @samp{short} format, Octave will switch to an @samp{e} -format if it is unable to format a matrix so that columns line up on the -decimal point and all the numbers fit within the maximum field width. - -@item long e -@itemx short e -The same as @samp{format long} or @samp{format short} but always display -output with an @samp{e} format. For example, with the @samp{short e} -format, pi is displayed as @code{3.14e+00}. +DOCSTRING(disp) -@item long E -@itemx short E -The same as @samp{format long e} or @samp{format short e} but always -display output with an uppercase @samp{E} format. For example, with -the @samp{long E} format, pi is displayed as -@code{3.14159265358979E+00}. - -@item free -@itemx none -Print output in free format, without trying to line up columns of -matrices on the decimal point. This also causes complex numbers to be -formatted like this @samp{(0.604194, 0.607088)} instead of like this -@samp{0.60419 + 0.60709i}. - -@item bank -Print in a fixed format with two places to the right of the decimal -point. - -@item + -Print a @samp{+} symbol for nonzero matrix elements and a space for zero -matrix elements. This format can be very useful for examining the -structure of a large matrix. - -@item hex -Print the hexadecimal representation numbers as they are stored in -memory. For example, on a workstation which stores 8 byte real values -in IEEE format with the least significant byte first, the value of -@code{pi} when printed in @code{hex} format is @code{400921fb54442d18}. -This format only works for numeric values. +DOCSTRING(format) -@item bit -Print the bit representation of numbers as stored in memory. -For example, the value of @code{pi} is - -@example -@group -01000000000010010010000111111011 -01010100010001000010110100011000 -@end group -@end example - -(shown here in two 32 bit sections for typesetting purposes) when -printed in bit format on a workstation which stores 8 byte real values -in IEEE format with the least significant byte first. This format only -works for numeric types. -@end table - -By default, Octave will try to print numbers with at least 5 significant -figures within a field that is a maximum of 10 characters wide. - -If Octave is unable to format a matrix so that columns line up on the -decimal point and all the numbers fit within the maximum field width, -it switches to an @samp{e} format. - -If @code{format} is invoked without any options, the default format -state is restored. -@end deffn - -@defvr {Built-in Variable} print_answer_id_name -If the value of @code{print_answer_id_name} is nonzero, variable -names are printed along with the result. Otherwise, only the result -values are printed. The default value is 1. -@end defvr +@DOCSTRING(print_answer_id_name) @node Terminal Input, Simple File I/O, Terminal Output, Basic Input and Output @subsection Terminal Input @@ -239,61 +99,11 @@ used for managing an interactive dialog with a user, and the @code{keyboard} function is normally used for doing simple debugging. -@deftypefn {Built-in Function} {} input (@var{prompt}) -@deftypefnx {Built-in Function} {} input (@var{prompt}, "s") -Print a prompt and wait for user input. For example, - -@example -input ("Pick a number, any number! ") -@end example - -@noindent -prints the prompt - -@example -Pick a number, any number! -@end example - -@noindent -and waits for the user to enter a value. The string entered by the user -is evaluated as an expression, so it may be a literal constant, a -variable name, or any other valid expression. - -Currently, @code{input} only returns one value, regardless of the number -of values produced by the evaluation of the expression. - -If you are only interested in getting a literal string value, you can -call @code{input} with the character string @code{"s"} as the second -argument. This tells Octave to return the string entered by the user -directly, without evaluating it first. +@DOCSTRING(input) -Because there may be output waiting to be displayed by the pager, it is -a good idea to always call @code{fflush (stdout)} before calling -@code{input}. This will ensure that all pending output is written to -the screen before your prompt. @xref{Input and Output}. -@end deftypefn +@DOCSTRING(menu) -@deftypefn {Function File} {} menu (@var{title}, @var{opt1}, @dots{}) -Print a title string followed by a series of options. Each option will -be printed along with a number. The return value is the number of the -option selected by the user. This function is useful for interactive -programs. There is no limit to the number of options that may be passed -in, but it may be confusing to present more than will fit easily on one -screen. -@end deftypefn - -@deftypefn {Built-in Function} {} keyboard (@var{prompt}) -This function is normally used for simple debugging. When the -@code{keyboard} function is executed, Octave prints a prompt and waits -for user input. The input strings are then evaluated and the results -are printed. This makes it possible to examine the values of variables -within a function, and to assign new values to variables. No value is -returned from the @code{keyboard} function, and it continues to prompt -for input until the user types @samp{quit}, or @samp{exit}. - -If @code{keyboard} is invoked without any arguments, a default prompt of -@samp{debug> } is used. -@end deftypefn +@DOCSTRING(keyboard) For both @code{input} and @code{keyboard}, the normal command line history and editing functions are available at the prompt. @@ -302,20 +112,7 @@ character from the keyboard without requiring the user to type a carriage return. -@c XXX FIXME XXX -- perhaps kbhit should also be able to print a prompt -@c string? - -@deftypefn {Built-in Function} {} kbhit () -Read a single keystroke from the keyboard. For example, - -@example -x = kbhit (); -@end example - -@noindent -will set @var{x} to the next character typed at the keyboard as soon as -it is typed. -@end deftypefn +@DOCSTRING(kbhit) @node Simple File I/O, , Terminal Input, Basic Input and Output @subsection Simple File I/O @@ -328,132 +125,18 @@ Note that Octave can not yet save or load structure variables or any user-defined types. -@deffn {Command} save options file v1 v2 @dots{} -Save the named variables @var{v1}, @var{v2}, @dots{} in the file -@var{file}. The special filename @samp{-} can be used to write the -output to your terminal. If no variable names are listed, Octave saves -all the variables in the current scope. Valid options for the -@code{save} command are listed in the following table. Options that -modify the output format override the format specified by the built-in -variable @code{default_save_format}. - -@table @code -@item -ascii -Save the data in Octave's text data format. - -@item -binary -Save the data in Octave's binary data format. - -@item -float-binary -Save the data in Octave's binary data format but only using single -precision. You should use this format only if you know that all the -values to be saved can be represented in single precision. - -@item -mat-binary -Save the data in @sc{Matlab}'s binary data format. - -@item -save-builtins -Force Octave to save the values of built-in variables too. By default, -Octave does not save built-in variables. -@end table - -The list of variables to save may include wildcard patterns containing -the following special characters: -@table @code -@item ? -Match any single character. - -@item * -Match zero or more characters. - -@item [ @var{list} ] -Match the list of characters specified by @var{list}. If the first -character is @code{!} or @code{^}, match all characters except those -specified by @var{list}. For example, the pattern @samp{[a-zA-Z]} will -match all lower and upper case alphabetic characters. -@end table - -Except when using the @sc{Matlab} binary data file format, saving global -variables also saves the global status of the variable, so that if it is -restored at a later time using @samp{load}, it will be restored as a -global variable. - -The command - -@example -save -binary data a b* -@end example - -@noindent -saves the variable @samp{a} and all variables beginning with @samp{b} to -the file @file{data} in Octave's binary format. -@end deffn +@DOCSTRING(save) There are two variables that modify the behavior of @code{save} and one that controls whether variables are saved when Octave exits unexpectedly. -@defvr {Built-in Variable} crash_dumps_octave_core -If this variable is set to a nonzero value, Octave tries to save all -current variables the the file "octave-core" if it crashes or receives a -hangup, terminate or similar signal. The default value is 1. -@end defvr - -@defvr {Built-in Variable} default_save_format -This variable specifies the default format for the @code{save} command. -It should have one of the following values: @code{"ascii"}, -@code{"binary"}, @code{float-binary}, or @code{"mat-binary"}. The -initial default save format is Octave's text format. -@end defvr +@DOCSTRING(crash_dumps_octave_core) -@defvr {Built-in Variable} save_precision -This variable specifies the number of digits to keep when saving data in -text format. The default value is 17. -@end defvr - -@deffn {Command} load options file v1 v2 @dots{} -Load the named variables from the file @var{file}. As with @code{save}, -you may specify a list of variables and @code{load} will only extract -those variables with names that match. For example, to restore the -variables saved in the file @file{data}, use the command - -@example -load data -@end example - -Octave will refuse to overwrite existing variables unless you use the -option @samp{-force}. +@DOCSTRING(default_save_format) -If a variable that is not marked as global is loaded from a file when a -global symbol with the same name already exists, it is loaded in the -global symbol table. Also, if a variable is marked as global in a file -and a local symbol exists, the local symbol is moved to the global -symbol table and given the value from the file. Since it seems that -both of these cases are likely to be the result of some sort of error, -they will generate warnings. - -The @code{load} command can read data stored in Octave's text and -binary formats, and @sc{Matlab}'s binary format. It will automatically -detect the type of file and do conversion from different floating point -formats (currently only IEEE big and little endian, though other formats -may added in the future). - -Valid options for @code{load} are listed in the following table. +@DOCSTRING(save_precision) -@table @code -@item -force -Force variables currently in memory to be overwritten by variables with -the same name found in the file. - -@item -ascii -Force Octave to assume the file is in Octave's text format. - -@item -binary -Force Octave to assume the file is in Octave's binary format. - -@item -mat-binary -Force Octave to assume the file is in @sc{Matlab}'s binary format. -@end table -@end deffn +@DOCSTRING(load) @node C-Style I/O Functions, , Basic Input and Output, Input and Output @section C-Style I/O Functions @@ -471,22 +154,11 @@ always use the symbolic names given in the table below, since it will make your programs easier to understand. -@defvr {Built-in Variable} stdin -The standard input stream (file id 0). When Octave is used -interactively, this is filtered through the command line editing -functions. -@end defvr +@DOCSTRING(stdin) -@defvr {Built-in Variable} stdout -The standard output stream (file id 1). Data written to the -standard output is normally filtered through the pager. -@end defvr +@DOCSTRING(stdout) -@defvr {Built-in Variable} stderr -The standard error stream (file id 2). Even if paging is turned on, -the standard error is not sent to the pager. It is useful for error -messages and prompts. -@end defvr +@DOCSTRING(stderr) @menu * Opening and Closing Files:: @@ -513,135 +185,23 @@ @node Opening and Closing Files, Simple Output, C-Style I/O Functions, C-Style I/O Functions @subsection Opening and Closing Files -@deftypefn {Built-in Function} {[@var{fid}, @var{msg}] =} fopen (@var{name}, @var{mode}, @var{arch}) -@deftypefnx {Built-in Function} {@var{fid_list} =} fopen ("all") -@deftypefnx {Built-in Function} {@var{file} =} fopen (@var{fid}) -The first form of the @code{fopen} function opens the named file with -the specified mode (read-write, read-only, etc.) and architecture -interpretation (IEEE big endian, IEEE little endian, etc.), and returns -an integer value that may be used to refer to the file later. If an -error occurs, @var{fid} is set to @minus{}1 and @var{msg} contains the -corresponding system error message. The @var{mode} is a one or two -character string that specifies whether the file is to be opened for -reading, writing, or both. - -The second form of the @code{fopen} function returns a vector of file ids -corresponding to all the currently open files, excluding the -@code{stdin}, @code{stdout}, and @code{stderr} streams. - -The third form of the @code{fopen} function returns the name of a -currently open file given its file id. - -For example, - -@example -myfile = fopen ("splat.dat", "r", "ieee-le"); -@end example - -@noindent -opens the file @file{splat.dat} for reading. If necessary, binary -numeric values will be read assuming they are stored in IEEE format with -the least significant bit first, and then converted to the native -representation. - -Opening a file that is already open simply opens it again and returns a -separate file id. It is not an error to open a file several times, -though writing to the same file through several different file ids may -produce unexpected results. - -The possible values @samp{mode} may have are - -@table @asis -@item @samp{r} -Open a file for reading. - -@item @samp{w} -Open a file for writing. The previous contents are discared. +@DOCSTRING(fopen) -@item @samp{a} -Open or create a file for writing at the end of the file. - -@item @samp{r+} -Open an existing file for reading and writing. - -@item @samp{w+} -Open a file for reading or writing. The previous contents are -discarded. - -@item @samp{a+} -Open or create a file for reading or writing at the end of the -file. -@end table - -The parameter @var{arch} is a string specifying the default data format -for the file. Valid values for @var{arch} are: - -@table @asis -@samp{native} -The format of the current machine (this is the default). - -@samp{ieee-le} -IEEE big endian format. - -@samp{ieee-be} -IEEE little endian format. - -@samp{vaxd} -VAX D floating format. - -@samp{vaxg} -VAX G floating format. - -@samp{cray} -Cray floating format. -@end table - -@noindent -however, conversions are currently only supported for @samp{native} -@samp{ieee-be}, and @samp{ieee-le} formats. -@end deftypefn - -@deftypefn {Built-in Function} {} fclose (@var{fid}) -Closes the specified file. If an error is encountered while trying to -close the file, an error message is printed and @code{fclose} returns -0. Otherwise, it returns 1. -@end deftypefn +@DOCSTRING(fclose) @node Simple Output, Line-Oriented Input, Opening and Closing Files, C-Style I/O Functions @subsection Simple Output -@deftypefn {Built-in Function} {} fputs (@var{fid}, @var{string}) -Write a string to a file with no formatting. -@end deftypefn +@DOCSTRING(fputs) -@deftypefn {Built-in Function} {} puts (@var{string}) -Write a string to the standard output with no formatting. -@end deftypefn +@DOCSTRING(puts) @node Line-Oriented Input, Formatted Output, Simple Output, C-Style I/O Functions @subsection Line-Oriented Input -@deftypefn {Built-in Function} {} fgetl (@var{fid}, @var{len}) -Read characters from a file, stopping after a newline, or EOF, -or @var{len} characters have been read. The characters read, excluding -the possible trailing newline, are returned as a string. - -If @var{len} is omitted, @code{fgetl} reads until the next newline -character. - -If there are no more characters to read, @code{fgetl} returns @minus{}1. -@end deftypefn +@DOCSTRING(fgetl) -@deftypefn {Built-in Function} {} fgets (@var{fid}, @var{len}) -Read characters from a file, stopping after a newline, or EOF, -or @var{len} characters have been read. The characters read, including -the possible trailing newline, are returned as a string. - -If @var{len} is omitted, @code{fgets} reads until the next newline -character. - -If there are no more characters to read, @code{fgets} returns @minus{}1. -@end deftypefn +@DOCSTRING(fgets) @node Formatted Output, Output Conversion for Matrices, Line-Oriented Input, C-Style I/O Functions @subsection Formatted Output @@ -653,24 +213,11 @@ interpret the format template differently in order to improve the performance of printing vector and matrix values. -@deftypefn {Function File} {} printf (@var{template}, @dots{}) -The @code{printf} function prints the optional arguments under the -control of the template string @var{template} to the stream -@code{stdout}. -@end deftypefn +@DOCSTRING(printf) -@deftypefn {Built-in Function} {} fprintf (@var{fid}, @var{template}, @dots{}) -This function is just like @code{printf}, except that the output is -written to the stream @var{fid} instead of @code{stdout}. -@end deftypefn +@DOCSTRING(fprintf) -@deftypefn {Built-in Function} {} sprintf (@var{template}, @dots{}) -This is like @code{printf}, except that the output is returned as a -string. Unlike the C library function, which requires you to provide a -suitably sized string as an argument, Octave's @code{sprintf} function -returns the string, automatically sized to hold all of the items -converted. -@end deftypefn +@DOCSTRING(sprintf) The @code{printf} function can be used to print any number of arguments. The template string argument you supply in a call provides @@ -1051,60 +598,9 @@ functions. One can be used to extract vectors of data from a file, and the other is more `C-like'. -@deftypefn {Built-in Function} {[@var{val}, @var{count}] =} fscanf (@var{fid}, @var{template}, @var{size}) -@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}] = } fscanf (@var{fid}, @var{template}, "C") -In the first form, read from @var{fid} according to @var{template}, -returning the result in the matrix @var{val}. - -The optional argument @var{size} specifies the amount of data to read -and may be one of - -@table @code -@item Inf -Read as much as possible, returning a column vector. - -@item @var{nr} -Read up to @var{nr} elements, returning a column vector. - -@item [@var{nr}, Inf] -Read as much as possible, returning a matrix with @var{nr} rows. If the -number of elements read is not an exact multiple of @var{nr}, the last -column is padded with zeros. - -@item [@var{nr}, @var{nc}] -Read up to @code{@var{nr} * @var{nc}} elements, returning a matrix with -@var{nr} rows. If the number of elements read is not an exact multiple -of @var{nr}, the last column is padded with zeros. -@end table +DOSTRING(fscanf) -@noindent -If @var{size} is omitted, a value of @code{Inf} is assumed. - -A string is returned if @var{template} specifies only character -conversions. - -The number of items successfully read is returned in @var{count}. - -In the second form, read from @var{fid} according to @var{template}, -with each conversion specifier in @var{template} corresponding to a -single scalar return value. This form is more `C-like', and also -compatible with previous versions of Octave. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{val}, @var{count}] =} sscanf (@var{string}, @var{template}, @var{size}) -@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}] = } sscanf (@var{string}, @var{template}, "C") -This is like @code{fscanf}, except that the characters are taken from the -string @var{string} instead of from a stream. Reaching the end of the -string is treated as an end-of-file condition. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{val}, @var{count}] =} scanf (@var{template}, @var{size}) -@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}] = } scanf (@var{template}, "C") -This is equivalent to calling @code{fscanf} with @var{fid} = @code{stdin}. - -It is currently not useful to call @code{scanf} in interactive -programs. -@end deftypefn +@DOCSTRING(sscanf) Calls to @code{scanf} are superficially similar to calls to @code{printf} in that arbitrary arguments are read under the control of @@ -1309,190 +805,23 @@ of integer data and convert among ths supported floating point formats as the data are read. -@deftypefn {Built-in Function} {[@var{val}, @var{count}] =} fread (@var{fid}, @var{size}, @var{precision}, @var{skip}, @var{arch}) -Read binary data of type @var{precision} from the specified file ID -@var{fid}. - -The optional argument @var{size} specifies the amount of data to read -and may be one of - -@table @code -@item Inf -Read as much as possible, returning a column vector. - -@item @var{nr} -Read up to @var{nr} elements, returning a column vector. - -@item [@var{nr}, Inf] -Read as much as possible, returning a matrix with @var{nr} rows. If the -number of elements read is not an exact multiple of @var{nr}, the last -column is padded with zeros. - -@item [@var{nr}, @var{nc}] -Read up to @code{@var{nr} * @var{nc}} elements, returning a matrix with -@var{nr} rows. If the number of elements read is not an exact multiple -of @var{nr}, the last column is padded with zeros. -@end table - -@noindent -If @var{size} is omitted, a value of @code{Inf} is assumed. - -The optional argument @var{precision} is a string specifying the type of -data to read and may be one of - -@table @code -@item "char" -@itemx "char*1" -@itemx "integer*1" -@itemx "int8" -Single character. - -@item "signed char" -@itemx "schar" -Signed character. - -@item "unsigned char" -@itemx "uchar" -Unsigned character. - -@item "short" -Short integer. - -@item "unsigned short" -@itemx "ushort" -Unsigned short integer. - -@item "int" -Integer. - -@item "unsigned int" -@itemx "uint" -Unsigned integer. - -@item "long" -Long integer. - -@item "unsigned long" -@itemx "ulong" -Unsigned long integer. +@DOCSTRING(fread) -@item "float" -@itemx "float32" -@itemx "real*4" -Single precision float. - -@item "double" -@itemx "float64" -@itemx "real*8" -Double precision float. - -@item "integer*2" -@itemx "int16" -Two byte integer. - -@item "integer*4" -@itemx "int32" -Four byte integer. -@end table - -@noindent -The default precision is @code{"uchar"}. - -The optional argument @var{skip} specifies the number of bytes to skip -before each element is read. If it is not specified, a value of 0 is -assumed. - -The optional argument @var{arch} is a string specifying the data format -for the file. Valid values are - -@table @code -@item "native" -The format of the current machine. - -@item "ieee-le" -IEEE big endian. - -@item "ieee-be" -IEEE little endian. - -@item "vaxd" -VAX D floating format. - -@item "vaxg" -VAX G floating format. - -@item "cray" -Cray floating format. -@end table - -@noindent -Conversions are currently only supported for @code{"ieee-be"} and -@code{"ieee-le"} formats. - -The data read from the file is returned in @var{val}, and the number of -values read is returned in @code{count} -@end deftypefn - -@deftypefn {Built-in Function} {@var{count} =} fwrite (@var{fid}, @var{data}, @var{precision}, @var{skip}, @var{arch}) -Write data in binary form of type @var{precision} to the specified file -ID @var{fid}, returning the number of values successfully written to the -file. - -The argument @var{data} is a matrix of values that are to be written to -the file. The values are extracted in column-major order. - -The remaining arguments @var{precision}, @var{skip}, and @var{arch} are -optional, and are interpreted as described for @code{fread}. - -The behavior of @code{fwrite} is undefined if the values in @var{data} -are too large to fit in the specified precision. -@end deftypefn +@DOCSTRING(fwrite) @node Temporary Files, EOF and Errors, Binary I/O, C-Style I/O Functions @subsection Temporary Files -@deftypefn {Built-in Function} {} tmpnam () -Return a unique temporary file name as a string. - -Since the named file is not opened, by @code{tmpnam}, it -is possible (though relatively unlikely) that it will not be available -by the time your program attempts to open it. -@end deftypefn +@DOCSTRING(tmpnam) @node EOF and Errors, File Positioning, Temporary Files, C-Style I/O Functions @subsection End of File and Errors -@deftypefn {Built-in Function} {} feof (@var{fid}) -Return 1 if an end-of-file condition has been encountered for a given -file and 0 otherwise. Note that it will only return 1 if the end of the -file has already been encountered, not if the next read operation will -result in an end-of-file condition. -@end deftypefn - -@deftypefn {Built-in Function} {} ferror (@var{fid}) -Return 1 if an error condition has been encountered for a given file -and 0 otherwise. Note that it will only return 1 if an error has -already been encountered, not if the next operation will result in an -error condition. -@end deftypefn +@DOCSTRING(feof) -@deftypefn {Built-in Function} {} freport () -Print a list of which files have been opened, and whether they are open -for reading, writing, or both. For example, - -@example -@group -freport () +@DOCSTRING(ferror) - @print{} number mode name - @print{} - @print{} 0 r stdin - @print{} 1 w stdout - @print{} 2 w stderr - @print{} 3 r myfile -@end group -@end example -@end deftypefn +@DOCSTRING(freport) @node File Positioning, , EOF and Errors, C-Style I/O Functions @subsection File Positioning @@ -1500,33 +829,14 @@ Three functions are available for setting and determining the position of the file pointer for a given file. -@deftypefn {Built-in Function} {} ftell (@var{fid}) -Return the position of the file pointer as the number of characters -from the beginning of the file @var{fid}. -@end deftypefn +@DOCSTRING(ftell) + +@DOCSTRING(fseek) -@deftypefn {Built-in Function} {} fseek (@var{fid}, @var{offset}, @var{origin}) -Set the file pointer to any location within the file @var{fid}. The -pointer is positioned @var{offset} characters from the @var{origin}, -which may be one of the predefined variables @code{SEEK_CUR} (current -position), @code{SEEK_SET} (beginning), or @code{SEEK_END} (end of -file). If @var{origin} is omitted, @code{SEEK_SET} is assumed. The -offset must be zero, or a value returned by @code{ftell} (in which case -@var{origin} must be @code{SEEK_SET}. -@end deftypefn +@DOCSTRING(SEEK_SET) -@defvr {Built-in Variable} SEEK_SET -@defvrx {Built-in Variable} SEEK_CUR -@defvrx {Built-in Variable} SEEK_END -These variables may be used as the optional third argument for the -function @code{fseek}. -@end defvr +@DOCSTRING(frewind) -@deftypefn {Built-in Function} {} frewind (@var{fid}) -Move the file pointer to the beginning of the file @var{fid}, returning -1 for success, and 0 if an error was encountered. It is equivalent to -@code{fseek (@var{fid}, 0, SEEK_SET)}. -@end deftypefn The following example stores the current file position in the variable @code{marker}, moves the pointer to the beginning of the file, reads
--- a/doc/interpreter/linalg.txi Sun Nov 21 17:31:10 1999 +0000 +++ b/doc/interpreter/linalg.txi Tue Nov 23 19:07:18 1999 +0000 @@ -19,888 +19,58 @@ @node Basic Matrix Functions, Matrix Factorizations, Linear Algebra, Linear Algebra @section Basic Matrix Functions -@deftypefn {Loadable Function} {@var{aa} =} balance (@var{a}, @var{opt}) -@deftypefnx {Loadable Function} {[@var{dd}, @var{aa}] =} balance (@var{a}, @var{opt}) -@deftypefnx {Loadable Function} {[@var{cc}, @var{dd}, @var{aa}, @var{bb]} =} balance (@var{a}, @var{b}, @var{opt}) - -@code{[dd, aa] = balance (a)} returns @code{aa = dd \ a * dd}. -@code{aa} is a matrix whose row and column norms are roughly equal in -magnitude, and @code{dd} = @code{p * d}, where @code{p} is a permutation -matrix and @code{d} is a diagonal matrix of powers of two. This allows -the equilibration to be computed without roundoff. Results of -eigenvalue calculation are typically improved by balancing first. - -@code{[cc, dd, aa, bb] = balance (a, b)} returns @code{aa = cc*a*dd} and -@code{bb = cc*b*dd)}, where @code{aa} and @code{bb} have non-zero -elements of approximately the same magnitude and @code{cc} and @code{dd} -are permuted diagonal matrices as in @code{dd} for the algebraic -eigenvalue problem. - -The eigenvalue balancing option @code{opt} is selected as follows: +DOCSTRING(balance) -@table @asis -@item @code{"N"}, @code{"n"} -No balancing; arguments copied, transformation(s) set to identity. - -@item @code{"P"}, @code{"p"} -Permute argument(s) to isolate eigenvalues where possible. - -@item @code{"S"}, @code{"s"} -Scale to improve accuracy of computed eigenvalues. +DOCSTRING(cond) -@item @code{"B"}, @code{"b"} -Permute and scale, in that order. Rows/columns of a (and b) -that are isolated by permutation are not scaled. This is the default -behavior. -@end table - -Algebraic eigenvalue balancing uses standard @sc{Lapack} routines. - -Generalized eigenvalue problem balancing uses Ward's algorithm -(SIAM Journal on Scientific and Statistical Computing, 1981). -@end deftypefn +DOCSTRING(det) -@deftypefn {} {} cond (@var{a}) -Compute the (two-norm) condition number of a matrix. @code{cond (a)} is -defined as @code{norm (a) * norm (inv (a))}, and is computed via a -singular value decomposition. -@end deftypefn - -@deftypefn {Loadable Function} {} det (@var{a}) -Compute the determinant of @var{a} using @sc{Linpack}. -@end deftypefn - -@deftypefn {Loadable Function} {@var{lambda} =} eig (@var{a}) -@deftypefnx {Loadable Function} {[@var{v}, @var{lambda}] =} eig (@var{a}) -The eigenvalues (and eigenvectors) of a matrix are computed in a several -step process which begins with a Hessenberg decomposition, followed by a -Schur decomposition, from which the eigenvalues are apparent. The -eigenvectors, when desired, are computed by further manipulations of the -Schur decomposition. -@end deftypefn +DOCSTRING(eig) -@deftypefn {Loadable Function} {@var{G} =} givens (@var{x}, @var{y}) -@deftypefnx {Loadable Function} {[@var{c}, @var{s}] =} givens (@var{x}, @var{y}) -@iftex -@tex -Return a $2\times 2$ orthogonal matrix -$$ - G = \left[\matrix{c & s\cr -s'& c\cr}\right] -$$ -such that -$$ - G \left[\matrix{x\cr y}\right] = \left[\matrix{\ast\cr 0}\right] -$$ -with $x$ and $y$ scalars. -@end tex -@end iftex -@ifinfo -Return a 2 by 2 orthogonal matrix -@code{@var{G} = [@var{c} @var{s}; -@var{s}' @var{c}]} such that -@code{@var{G} [@var{x}; @var{y}] = [*; 0]} with @var{x} and @var{y} scalars. -@end ifinfo +DOCSTRING(givens) -For example, - -@example -@group -givens (1, 1) - @result{} 0.70711 0.70711 - -0.70711 0.70711 -@end group -@end example -@end deftypefn +DOCSTRING(inv) -@deftypefn {Loadable Function} {} inv (@var{a}) -@deftypefnx {Loadable Function} {} inverse (@var{a}) -Compute the inverse of the square matrix @var{a}. -@end deftypefn - -@deftypefn {Function File} {} norm (@var{a}, @var{p}) -Compute the p-norm of the matrix @var{a}. If the second argument is -missing, @code{p = 2} is assumed. - -If @var{a} is a matrix: - -@table @asis -@item @var{p} = @code{1} -1-norm, the largest column sum of @var{a}. - -@item @var{p} = @code{2} -Largest singular value of @var{a}. - -@item @var{p} = @code{Inf} -@cindex infinity norm -Infinity norm, the largest row sum of @var{a}. +DOCSTRING(norm) -@item @var{p} = @code{"fro"} -@cindex Frobenius norm -Frobenius norm of @var{a}, @code{sqrt (sum (diag (@var{a}' * @var{a})))}. -@end table - -If @var{a} is a vector or a scalar: - -@table @asis -@item @var{p} = @code{Inf} -@code{max (abs (@var{a}))}. +DOCSTRING(null) -@item @var{p} = @code{-Inf} -@code{min (abs (@var{a}))}. - -@item other -p-norm of @var{a}, @code{(sum (abs (@var{a}) .^ @var{p})) ^ (1/@var{p})}. -@end table -@end deftypefn - -@deftypefn {Function File} {} null (@var{a}, @var{tol}) -Return an orthonormal basis of the null space of @var{a}. - -The dimension of the null space is taken as the number of singular -values of @var{a} not greater than @var{tol}. If the argument @var{tol} -is missing, it is computed as +DOCSTRING(orth) -@example -max (size (@var{a})) * max (svd (@var{a})) * eps -@end example -@end deftypefn - -@deftypefn {Function File} {} orth (@var{a}, @var{tol}) -Return an orthonormal basis of the range space of @var{a}. - -The dimension of the range space is taken as the number of singular -values of @var{a} greater than @var{tol}. If the argument @var{tol} is -missing, it is computed as - -@example -max (size (@var{a})) * max (svd (@var{a})) * eps -@end example -@end deftypefn - -@deftypefn {Function File} {} pinv (@var{x}, @var{tol}) -Return the pseudoinverse of @var{x}. Singular values less than -@var{tol} are ignored. - -If the second argument is omitted, it is assumed that +DOCSTRING(pinv) -@example -tol = max (size (@var{x})) * sigma_max (@var{x}) * eps, -@end example - -@noindent -where @code{sigma_max (@var{x})} is the maximal singular value of @var{x}. -@end deftypefn +DOCSTRING(rank) -@deftypefn {Function File} {} rank (@var{a}, @var{tol}) -Compute the rank of @var{a}, using the singular value decomposition. -The rank is taken to be the number of singular values of @var{a} that -are greater than the specified tolerance @var{tol}. If the second -argument is omitted, it is taken to be - -@example -tol = max (size (@var{a})) * sigma (1) * eps; -@end example - -@noindent -where @code{eps} is machine precision and @code{sigma} is the largest -singular value of @var{a}. -@end deftypefn - -@deftypefn {Function File} {} trace (@var{a}) -Compute the trace of @var{a}, @code{sum (diag (@var{a}))}. -@end deftypefn +DOCSTRING(trace) @node Matrix Factorizations, Functions of a Matrix, Basic Matrix Functions, Linear Algebra @section Matrix Factorizations -@deftypefn {Loadable Function} {} chol (@var{a}) -@cindex Cholesky factorization -Compute the Cholesky factor, @var{r}, of the symmetric positive definite -matrix @var{a}, where -@iftex -@tex -$ R^T R = A $. -@end tex -@end iftex -@ifinfo - -@example -r' * r = a. -@end example -@end ifinfo -@end deftypefn - -@deftypefn {Loadable Function} {@var{h} =} hess (@var{a}) -@deftypefnx {Loadable Function} {[@var{p}, @var{h}] =} hess (@var{a}) -@cindex Hessenberg decomposition -Compute the Hessenberg decomposition of the matrix @var{a}. - -The Hessenberg decomposition is usually used as the first step in an -eigenvalue computation, but has other applications as well (see Golub, -Nash, and Van Loan, IEEE Transactions on Automatic Control, 1979. The -Hessenberg decomposition is -@iftex -@tex -$$ -A = PHP^T -$$ -where $P$ is a square unitary matrix ($P^HP = I$), and $H$ -is upper Hessenberg ($H_{i,j} = 0, \forall i \ge j+1$). -@end tex -@end iftex -@ifinfo -@code{p * h * p' = a} where @code{p} is a square unitary matrix -(@code{p' * p = I}, using complex-conjugate transposition) and @code{h} -is upper Hessenberg (@code{i >= j+1 => h (i, j) = 0}). -@end ifinfo -@end deftypefn - -@deftypefn {Loadable Function} {[@var{l}, @var{u}, @var{p}] =} lu (@var{a}) -@cindex LU decomposition -Compute the LU decomposition of @var{a}, using subroutines from -@sc{Lapack}. The result is returned in a permuted form, according to -the optional return value @var{p}. For example, given the matrix -@code{a = [1, 2; 3, 4]}, - -@example -[l, u, p] = lu (a) -@end example - -@noindent -returns +DOCSTRING(chol) -@example -l = - - 1.00000 0.00000 - 0.33333 1.00000 - -u = - - 3.00000 4.00000 - 0.00000 0.66667 - -p = - - 0 1 - 1 0 -@end example -@end deftypefn - -@deftypefn {Loadable Function} {[@var{q}, @var{r}, @var{p}] =} qr (@var{a}) -@cindex QR factorization -Compute the QR factorization of @var{a}, using standard @sc{Lapack} -subroutines. For example, given the matrix @code{a = [1, 2; 3, 4]}, - -@example -[q, r] = qr (a) -@end example - -@noindent -returns - -@example -q = - - -0.31623 -0.94868 - -0.94868 0.31623 - -r = - - -3.16228 -4.42719 - 0.00000 -0.63246 -@end example - -The @code{qr} factorization has applications in the solution of least -squares problems -@iftex -@tex -$$ -\min_x \left\Vert A x - b \right\Vert_2 -$$ -@end tex -@end iftex -@ifinfo - -@example -@code{min norm(A x - b)} -@end example +DOCSTRING(hess) -@end ifinfo -for overdetermined systems of equations (i.e., -@iftex -@tex -$A$ -@end tex -@end iftex -@ifinfo -@code{a} -@end ifinfo - is a tall, thin matrix). The QR factorization is -@iftex -@tex -$QR = A$ where $Q$ is an orthogonal matrix and $R$ is upper triangular. -@end tex -@end iftex -@ifinfo -@code{q * r = a} where @code{q} is an orthogonal matrix and @code{r} is -upper triangular. -@end ifinfo - -The permuted QR factorization @code{[@var{q}, @var{r}, @var{p}] = -qr (@var{a})} forms the QR factorization such that the diagonal -entries of @code{r} are decreasing in magnitude order. For example, -given the matrix @code{a = [1, 2; 3, 4]}, - -@example -[q, r, pi] = qr(a) -@end example - -@noindent -returns - -@example -q = - - -0.44721 -0.89443 - -0.89443 0.44721 - -r = - - -4.47214 -3.13050 - 0.00000 0.44721 - -p = - - 0 1 - 1 0 -@end example - -The permuted @code{qr} factorization @code{[q, r, p] = qr (a)} -factorization allows the construction of an orthogonal basis of -@code{span (a)}. -@end deftypefn - - -@deftypefn {Function File} {@var{lambda} =} qz (@var{a}, @var{b}) -Generalized eigenvalue problem @math{A x = s B x}, -@var{QZ} decomposition. Three ways to call: -@enumerate -@item @code{lambda = qz(A,B)} - -Computes the generalized eigenvalues @var{lambda} of @math{(A - sB)}. - -@item @code{[AA, BB, Q, Z @{, V, W, lambda@}] = qz (A, B)} +DOCSTRING(lu) -Computes qz decomposition, generalized eigenvectors, and - generalized eigenvalues of @math{(A - sB)} -@example -@group - A V = B V diag(lambda) - W' A = diag(lambda) W' B - AA = Q'*A*Z, BB = Q'*B*Z with Q, Z orthogonal (unitary)= I -@end group -@end example - -@item @code{[AA,BB,Z@{,lambda@}] = qz(A,B,opt)} - -As in form [2], but allows ordering of generalized eigenpairs - for (e.g.) solution of discrete time algebraic Riccati equations. - Form 3 is not available for complex matrices and does not compute - the generalized eigenvectors V, W, nor the orthogonal matrix Q. -@table @var -@item opt - for ordering eigenvalues of the GEP pencil. The leading block - of the revised pencil contains all eigenvalues that satisfy: -@table @code -@item "N" - = unordered (default) - -@item "S" -= small: leading block has all |lambda| <=1 - -@item "B" - = big: leading block has all |lambda >= 1 - -@item "-" - = negative real part: leading block has all eigenvalues - in the open left half-plant - -@item "+" - = nonnegative real part: leading block has all eigenvalues - in the closed right half-plane -@end table -@end table -@end enumerate - -Note: qz performs permutation balancing, but not scaling (see balance). - Order of output arguments was selected for compatibility with MATLAB - -See also: balance, dare, eig, schur -@end deftypefn - -@deftypefn {Function File} {[@var{aa}, @var{bb}, @var{q}, @var{z}] =} qzhess (@var{a}, @var{b}) -Compute the Hessenberg-triangular decomposition of the matrix pencil -@code{(@var{a}, @var{b})}, returning -@code{@var{aa} = @var{q} * @var{a} * @var{z}}, -@code{@var{bb} = @var{q} * @var{b} * @var{z}}, with @var{q} and @var{z} -orthogonal. For example, - -@example -@group -[aa, bb, q, z] = qzhess ([1, 2; 3, 4], [5, 6; 7, 8]) - @result{} aa = [ -3.02244, -4.41741; 0.92998, 0.69749 ] - @result{} bb = [ -8.60233, -9.99730; 0.00000, -0.23250 ] - @result{} q = [ -0.58124, -0.81373; -0.81373, 0.58124 ] - @result{} z = [ 1, 0; 0, 1 ] -@end group -@end example - -The Hessenberg-triangular decomposition is the first step in -Moler and Stewart's QZ decomposition algorithm. - -Algorithm taken from Golub and Van Loan, @cite{Matrix Computations, 2nd -edition}. -@end deftypefn - -@deftypefn {Loadable Function} {} qzval (@var{a}, @var{b}) -Compute generalized eigenvalues of the matrix pencil -@iftex -@tex -$a - \lambda b$. -@end tex -@end iftex -@ifinfo -@code{@var{a} - lambda @var{b}}. -@end ifinfo - -The arguments @var{a} and @var{b} must be real matrices. -@end deftypefn +DOCSTRING(qr) -@deftypefn {Loadable Function} {@var{s} =} schur (@var{a}) -@deftypefnx {Loadable Function} {[@var{u}, @var{s}] =} schur (@var{a}, @var{opt}) -@cindex Schur decomposition -The Schur decomposition is used to compute eigenvalues of a -square matrix, and has applications in the solution of algebraic -Riccati equations in control (see @code{are} and @code{dare}). -@code{schur} always returns -@iftex -@tex -$S = U^T A U$ -@end tex -@end iftex -@ifinfo -@code{s = u' * a * u} -@end ifinfo -where -@iftex -@tex -$U$ -@end tex -@end iftex -@ifinfo -@code{u} -@end ifinfo - is a unitary matrix -@iftex -@tex -($U^T U$ is identity) -@end tex -@end iftex -@ifinfo -(@code{u'* u} is identity) -@end ifinfo -and -@iftex -@tex -$S$ -@end tex -@end iftex -@ifinfo -@code{s} -@end ifinfo -is upper triangular. The eigenvalues of -@iftex -@tex -$A$ (and $S$) -@end tex -@end iftex -@ifinfo -@code{a} (and @code{s}) -@end ifinfo -are the diagonal elements of -@iftex -@tex -$S$ -@end tex -@end iftex -@ifinfo -@code{s} -@end ifinfo -If the matrix -@iftex -@tex -$A$ -@end tex -@end iftex -@ifinfo -@code{a} -@end ifinfo -is real, then the real Schur decomposition is computed, in which the -matrix -@iftex -@tex -$U$ -@end tex -@end iftex -@ifinfo -@code{u} -@end ifinfo -is orthogonal and -@iftex -@tex -$S$ -@end tex -@end iftex -@ifinfo -@code{s} -@end ifinfo -is block upper triangular -with blocks of size at most -@iftex -@tex -$2\times 2$ -@end tex -@end iftex -@ifinfo -@code{2 x 2} -@end ifinfo -blocks along the diagonal. The diagonal elements of -@iftex -@tex -$S$ -@end tex -@end iftex -@ifinfo -@code{s} -@end ifinfo -(or the eigenvalues of the -@iftex -@tex -$2\times 2$ -@end tex -@end iftex -@ifinfo -@code{2 x 2} -@end ifinfo -blocks, when -appropriate) are the eigenvalues of -@iftex -@tex -$A$ -@end tex -@end iftex -@ifinfo -@code{a} -@end ifinfo -and -@iftex -@tex -$S$. -@end tex -@end iftex -@ifinfo -@code{s}. -@end ifinfo +DOCSTRING(qz) + +DOCSTRING(qzhess) -The eigenvalues are optionally ordered along the diagonal according to -the value of @code{opt}. @code{opt = "a"} indicates that all -eigenvalues with negative real parts should be moved to the leading -block of -@iftex -@tex -$S$ -@end tex -@end iftex -@ifinfo -@code{s} -@end ifinfo -(used in @code{are}), @code{opt = "d"} indicates that all eigenvalues -with magnitude less than one should be moved to the leading block of -@iftex -@tex -$S$ -@end tex -@end iftex -@ifinfo -@code{s} -@end ifinfo -(used in @code{dare}), and @code{opt = "u"}, the default, indicates that -no ordering of eigenvalues should occur. The leading -@iftex -@tex -$k$ -@end tex -@end iftex -@ifinfo -@code{k} -@end ifinfo -columns of -@iftex -@tex -$U$ -@end tex -@end iftex -@ifinfo -@code{u} -@end ifinfo -always span the -@iftex -@tex -$A$-invariant -@end tex -@end iftex -@ifinfo -@code{a}-invariant -@end ifinfo -subspace corresponding to the -@iftex -@tex -$k$ -@end tex -@end iftex -@ifinfo -@code{k} -@end ifinfo -leading eigenvalues of -@iftex -@tex -$S$. -@end tex -@end iftex -@ifinfo -@code{s}. -@end ifinfo -@end deftypefn +DOCSTRING(schur) -@deftypefn {Loadable Function} {@var{s} =} svd (@var{a}) -@deftypefnx {Loadable Function} {[@var{u}, @var{s}, @var{v}] =} svd (@var{a}) -@cindex singular value decomposition -Compute the singular value decomposition of @var{a} -@iftex -@tex -$$ - A = U\Sigma V^H -$$ -@end tex -@end iftex -@ifinfo - -@example -a = u * sigma * v' -@end example -@end ifinfo - -The function @code{svd} normally returns the vector of singular values. -If asked for three return values, it computes -@iftex -@tex -$U$, $S$, and $V$. -@end tex -@end iftex -@ifinfo -U, S, and V. -@end ifinfo -For example, - -@example -svd (hilb (3)) -@end example - -@noindent -returns - -@example -ans = - - 1.4083189 - 0.1223271 - 0.0026873 -@end example - -@noindent -and - -@example -[u, s, v] = svd (hilb (3)) -@end example - -@noindent -returns - -@example -u = - - -0.82704 0.54745 0.12766 - -0.45986 -0.52829 -0.71375 - -0.32330 -0.64901 0.68867 - -s = - - 1.40832 0.00000 0.00000 - 0.00000 0.12233 0.00000 - 0.00000 0.00000 0.00269 - -v = - - -0.82704 0.54745 0.12766 - -0.45986 -0.52829 -0.71375 - -0.32330 -0.64901 0.68867 -@end example - -If given a second argument, @code{svd} returns an economy-sized -decomposition, eliminating the unnecessary rows or columns of @var{u} or -@var{v}. -@end deftypefn +DOCSTRING(svd) @node Functions of a Matrix, , Matrix Factorizations, Linear Algebra @section Functions of a Matrix -@deftypefn {Loadable Function} {} expm (@var{a}) -Return the exponential of a matrix, defined as the infinite Taylor -series -@iftex -@tex -$$ - \exp (A) = I + A + {A^2 \over 2!} + {A^3 \over 3!} + \cdots -$$ -@end tex -@end iftex -@ifinfo - -@example -expm(a) = I + a + a^2/2! + a^3/3! + ... -@end example +DOCSTRING(expm) -@end ifinfo -The Taylor series is @emph{not} the way to compute the matrix -exponential; see Moler and Van Loan, @cite{Nineteen Dubious Ways to -Compute the Exponential of a Matrix}, SIAM Review, 1978. This routine -uses Ward's diagonal -@iftex -@tex -Pad\'e -@end tex -@end iftex -@ifinfo -Pade' -@end ifinfo -approximation method with three step preconditioning (SIAM Journal on -Numerical Analysis, 1977). Diagonal -@iftex -@tex -Pad\'e -@end tex -@end iftex -@ifinfo -Pade' -@end ifinfo - approximations are rational polynomials of matrices -@iftex -@tex -$D_q(a)^{-1}N_q(a)$ -@end tex -@end iftex -@ifinfo - -@example - -1 -D (a) N (a) -@end example +DOCSTRING(logm) -@end ifinfo - whose Taylor series matches the first -@iftex -@tex -$2 q + 1 $ -@end tex -@end iftex -@ifinfo -@code{2q+1} -@end ifinfo -terms of the Taylor series above; direct evaluation of the Taylor series -(with the same preconditioning steps) may be desirable in lieu of the -@iftex -@tex -Pad\'e -@end tex -@end iftex -@ifinfo -Pade' -@end ifinfo -approximation when -@iftex -@tex -$D_q(a)$ -@end tex -@end iftex -@ifinfo -@code{Dq(a)} -@end ifinfo -is ill-conditioned. -@end deftypefn - -@deftypefn {Loadable Function} {} logm (@var{a}) -Compute the matrix logarithm of the square matrix @var{a}. Note that -this is currently implemented in terms of an eigenvalue expansion and -needs to be improved to be more robust. -@end deftypefn - -@deftypefn {Loadable Function} {} sqrtm (@var{a}) -Compute the matrix square root of the square matrix @var{a}. Note that -this is currently implemented in terms of an eigenvalue expansion and -needs to be improved to be more robust. -@end deftypefn +DOCSTRING(sqrtm) -@deftypefn {Function File} {} kron (@var{a}, @var{b}) -Form the kronecker product of two matrices, defined block by block as - -@example -x = [a(i, j) b] -@end example - -For example, - -@example -@group -kron (1:4, ones (3, 1)) - @result{} 1 2 3 4 - 1 2 3 4 - 1 2 3 4 -@end group -@end example -@end deftypefn +DOCSTRING(kron) -@deftypefn {Loadable Function} {@var{x} =} syl (@var{a}, @var{b}, @var{c}) -Solve the Sylvester equation -@iftex -@tex -$$ - A X + X B + C = 0 -$$ -@end tex -@end iftex -@ifinfo - -@example -A X + X B + C = 0 -@end example -@end ifinfo -using standard @sc{Lapack} subroutines. For example, - -@example -@group -syl ([1, 2; 3, 4], [5, 6; 7, 8], [9, 10; 11, 12]) - @result{} [ -0.50000, -0.66667; -0.66667, -0.50000 ] -@end group -@end example -@end deftypefn +DOCSTRING(syl)
--- a/scripts/ChangeLog Sun Nov 21 17:31:10 1999 +0000 +++ b/scripts/ChangeLog Tue Nov 23 19:07:18 1999 +0000 @@ -1,3 +1,17 @@ +1999-11-23 John W. Eaton <jwe@bevo.che.wisc.edu> + + * linear-algebra/cond.m: Texinfoize doc string. + * linear-algebra/kron.m: Ditto. + * linear-algebra/norm.m: Ditto. + * linear-algebra/null.m: Ditto. + * linear-algebra/orth.m: Ditto. + * linear-algebra/rank.m: Ditto. + * linear-algebra/trace.m: Ditto. + * linear-algebra/qzhess.m: Ditto. + * miscellaneous/menu.m: Ditto. + * io/printf.m: Ditto. + * io/puts.m: Ditto. + 1999-11-21 John W. Eaton <jwe@bevo.che.wisc.edu> * special-matrix/hankel.m: Texinfoize doc string.
--- a/scripts/io/printf.m Sun Nov 21 17:31:10 1999 +0000 +++ b/scripts/io/printf.m Tue Nov 23 19:07:18 1999 +0000 @@ -17,10 +17,13 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: printf (fmt, ...) -## -## Formatted write to standard output. -## +## -*texinfo -*- +## @deftypefn {Function File} {} printf (@var{template}, @dots{}) +## The @code{printf} function prints the optional arguments under the +## control of the template string @var{template} to the stream +## @code{stdout}. +## @end deftypefn + ## See also: fprintf sprintf ## Author: jwe
--- a/scripts/io/puts.m Sun Nov 21 17:31:10 1999 +0000 +++ b/scripts/io/puts.m Tue Nov 23 19:07:18 1999 +0000 @@ -17,10 +17,11 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: puts (string) -## -## Write string to the standard output. -## +-*- texinfo -*-\n\ +## @deftypefn {Built-in Function} {} puts (@var{string}) +## Write a string to the standard output with no formatting. +## @end deftypefn + ## See also: fputs, printf, fprintf ## Author: jwe
--- a/scripts/linear-algebra/cond.m Sun Nov 21 17:31:10 1999 +0000 +++ b/scripts/linear-algebra/cond.m Tue Nov 23 19:07:18 1999 +0000 @@ -17,12 +17,13 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: cond (A) -## -## Return the condition number of A, computed using the singular values -## of A. If the maximum and minimum singular values of A are both zero, -## cond returns Inf rather than NaN. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} cond (@var{a}) +## Compute the (two-norm) condition number of a matrix. @code{cond (a)} is +## defined as @code{norm (a) * norm (inv (a))}, and is computed via a +## singular value decomposition. +## @end deftypefn + ## See also: norm, svd, rank ## Author: jwe
--- a/scripts/linear-algebra/kron.m Sun Nov 21 17:31:10 1999 +0000 +++ b/scripts/linear-algebra/kron.m Tue Nov 23 19:07:18 1999 +0000 @@ -17,12 +17,25 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## Usage: x = kron (a, b) -## -## Form the Kronecker product of two matrices, defined block by block -## as -## -## x = [a(i,j) b] +## -*- texinfo -*- +## @deftypefn {Function File} {} kron (@var{a}, @var{b}) +## Form the kronecker product of two matrices, defined block by block as +## +## @example +## x = [a(i, j) b] +## @end example +## +## For example, +## +## @example +## @group +## kron (1:4, ones (3, 1)) +## @result{} 1 2 3 4 +## 1 2 3 4 +## 1 2 3 4 +## @end group +## @end example +## @end deftypefn ## Author: A. S. Hodel <scotte@eng.auburn.edu> ## Created: August 1993
--- a/scripts/linear-algebra/norm.m Sun Nov 21 17:31:10 1999 +0000 +++ b/scripts/linear-algebra/norm.m Tue Nov 23 19:07:18 1999 +0000 @@ -17,30 +17,43 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: norm (x, p) -## -## Compute the p-norm of x. -## -## If x is a matrix: -## -## value of p norm returns -## ---------- ------------ -## 1 1-norm, the largest column sum of x -## 2 largest singular value of x -## Inf infinity norm, the largest row sum of x -## "inf" same as Inf -## "fro" Frobenius norm of x, sqrt (sum (diag (x' * x))) -## -## If x is a vector or a scalar: -## -## value of p norm returns -## ---------- ------------ -## Inf max (abs (x)) -## -Inf min (abs (x)) -## other p-norm of x, sum (abs (x) .^ p) ^ (1/p) -## -## If the second argument is missing, p = 2 is assumed. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} norm (@var{a}, @var{p}) +## Compute the p-norm of the matrix @var{a}. If the second argument is +## missing, @code{p = 2} is assumed. +## +## If @var{a} is a matrix: +## +## @table @asis +## @item @var{p} = @code{1} +## 1-norm, the largest column sum of @var{a}. +## +## @item @var{p} = @code{2} +## Largest singular value of @var{a}. +## +## @item @var{p} = @code{Inf} +## @cindex infinity norm +## Infinity norm, the largest row sum of @var{a}. +## +## @item @var{p} = @code{"fro"} +## @cindex Frobenius norm +## Frobenius norm of @var{a}, @code{sqrt (sum (diag (@var{a}' * @var{a})))}. +## @end table +## +## If @var{a} is a vector or a scalar: +## +## @table @asis +## @item @var{p} = @code{Inf} +## @code{max (abs (@var{a}))}. +## +## @item @var{p} = @code{-Inf} +## @code{min (abs (@var{a}))}. +## +## @item other +## p-norm of @var{a}, @code{(sum (abs (@var{a}) .^ @var{p})) ^ (1/@var{p})}. +## @end table +## @end deftypefn + ## See also: cond, svd ## Author: jwe
--- a/scripts/linear-algebra/null.m Sun Nov 21 17:31:10 1999 +0000 +++ b/scripts/linear-algebra/null.m Tue Nov 23 19:07:18 1999 +0000 @@ -17,15 +17,18 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: null (A, tol) -## null (A) -## -## Returns an orthonormal basis of the null space of A. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} null (@var{a}, @var{tol}) +## Return an orthonormal basis of the null space of @var{a}. +## ## The dimension of the null space is taken as the number of singular -## values of A not greater than tol; the default for tol is -## max (size (A)) * sigma_max (A) * eps, where sigma_max (A) is the -## maximal singular value of A. +## values of @var{a} not greater than @var{tol}. If the argument @var{tol} +## is missing, it is computed as +## +## @example +## max (size (@var{a})) * max (svd (@var{a})) * eps +## @end example +## @end deftypefn ## Author: KH <Kurt.Hornik@ci.tuwien.ac.at> ## Created: 24 December 1993.
--- a/scripts/linear-algebra/orth.m Sun Nov 21 17:31:10 1999 +0000 +++ b/scripts/linear-algebra/orth.m Tue Nov 23 19:07:18 1999 +0000 @@ -17,15 +17,18 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: orth (A, tol) -## orth (A) -## -## Returns an orthonormal basis of the range of A. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} orth (@var{a}, @var{tol}) +## Return an orthonormal basis of the range space of @var{a}. +## ## The dimension of the range space is taken as the number of singular -## values of A greater than tol; the default for tol is -## max (size (A)) * sigma_max (A) * eps, where sigma_max (A) is the -## maximal singular value of A. +## values of @var{a} greater than @var{tol}. If the argument @var{tol} is +## missing, it is computed as +## +## @example +## max (size (@var{a})) * max (svd (@var{a})) * eps +## @end example +## @end deftypefn ## Author: KH <Kurt.Hornik@ci.tuwien.ac.at> ## Created: 24 December 1993.
--- a/scripts/linear-algebra/qzhess.m Sun Nov 21 17:31:10 1999 +0000 +++ b/scripts/linear-algebra/qzhess.m Tue Nov 23 19:07:18 1999 +0000 @@ -17,18 +17,30 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## Usage: [aa, bb, q, z] = qzhess (a, b) -## -## Compute the qz decomposition of the matrix pencil (a - lambda b) -## -## result: (for Matlab compatibility): -## -## aa = q*a*z and bb = q*b*z, with q, z orthogonal, and -## v = matrix of generalized eigenvectors. -## -## This ought to be done in a compiled program -## -## Algorithm taken from Golub and Van Loan, Matrix Computations, 2nd ed. +## -*- texinfo -*- +## @deftypefn {Function File} {[@var{aa}, @var{bb}, @var{q}, @var{z}] =} qzhess (@var{a}, @var{b}) +## Compute the Hessenberg-triangular decomposition of the matrix pencil +## @code{(@var{a}, @var{b})}, returning +## @code{@var{aa} = @var{q} * @var{a} * @var{z}}, +## @code{@var{bb} = @var{q} * @var{b} * @var{z}}, with @var{q} and @var{z} +## orthogonal. For example, +## +## @example +## @group +## [aa, bb, q, z] = qzhess ([1, 2; 3, 4], [5, 6; 7, 8]) +## @result{} aa = [ -3.02244, -4.41741; 0.92998, 0.69749 ] +## @result{} bb = [ -8.60233, -9.99730; 0.00000, -0.23250 ] +## @result{} q = [ -0.58124, -0.81373; -0.81373, 0.58124 ] +## @result{} z = [ 1, 0; 0, 1 ] +## @end group +## @end example +## +## The Hessenberg-triangular decomposition is the first step in +## Moler and Stewart's QZ decomposition algorithm. +## +## Algorithm taken from Golub and Van Loan, @cite{Matrix Computations, 2nd +## edition}. +## @end deftypefn ## Author: A. S. Hodel <scotte@eng.auburn.edu> ## Created: August 1993
--- a/scripts/linear-algebra/rank.m Sun Nov 21 17:31:10 1999 +0000 +++ b/scripts/linear-algebra/rank.m Tue Nov 23 19:07:18 1999 +0000 @@ -17,17 +17,21 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: rank (a, tol) -## -## Return the rank of the matrix a. The rank is taken to be the number -## of singular values of a that are greater than tol. -## -## If the second argument is omitted, it is taken to be -## -## tol = max (size (a)) * sigma (1) * eps; -## -## where eps is machine precision and sigma is the largest singular -## value of a. +## -*- texinfo -*- +## @deftypefn {Function File} {} rank (@var{a}, @var{tol}) +## Compute the rank of @var{a}, using the singular value decomposition. +## The rank is taken to be the number of singular values of @var{a} that +## are greater than the specified tolerance @var{tol}. If the second +## argument is omitted, it is taken to be +## +## @example +## tol = max (size (@var{a})) * sigma (1) * eps; +## @end example +## +## @noindent +## where @code{eps} is machine precision and @code{sigma} is the largest +## singular value of @var{a}. +## @end deftypefn ## Author: jwe
--- a/scripts/linear-algebra/trace.m Sun Nov 21 17:31:10 1999 +0000 +++ b/scripts/linear-algebra/trace.m Tue Nov 23 19:07:18 1999 +0000 @@ -17,9 +17,10 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: trace (x) -## -## Returns the trace (the sum of the diagonal elements) of x. +## -*- texinfo -*- +## @deftypefn {Function File} {} trace (@var{a}) +## Compute the trace of @var{a}, @code{sum (diag (@var{a}))}. +## @end deftypefn ## Author: jwe
--- a/scripts/miscellaneous/menu.m Sun Nov 21 17:31:10 1999 +0000 +++ b/scripts/miscellaneous/menu.m Tue Nov 23 19:07:18 1999 +0000 @@ -17,8 +17,16 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: menu (title, opt1, ...) -## +## -*texinfo -*- +## @deftypefn {Function File} {} menu (@var{title}, @var{opt1}, @dots{}) +## Print a title string followed by a series of options. Each option will +## be printed along with a number. The return value is the number of the +## option selected by the user. This function is useful for interactive +## programs. There is no limit to the number of options that may be passed +## in, but it may be confusing to present more than will fit easily on one +## screen. +## @end deftypefn + ## See also: disp, printf, input ## Author: jwe
--- a/src/ChangeLog Sun Nov 21 17:31:10 1999 +0000 +++ b/src/ChangeLog Tue Nov 23 19:07:18 1999 +0000 @@ -1,3 +1,35 @@ +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. + * 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. + * load-save.cc (Fload, Fsave, Vdefault_save_format, + Vsave_precision): Ditto. + * file-io.cc (Ffflush, Ffopen, Ffclose, Ffputs, Ffgetl, Ffgets, + Ffprintf, Fsprintf, Fscanf, Ffscanf, Fsscanf, Ffread, Ffwrite, + Ffseek, Fftell, Ffeof, Fferror, Ffreport, Ftmpnam, Vstdin_file, + Vstdout_file, Vstderr_file, SEEK_SET, SEEK_CUR, SEEK_END): Ditto. + * pager.cc (Vpager_binary, Vpage_output_immediately, + Vpage_screen_output, Fmore): Ditto. + 1999-11-21 John W. Eaton <jwe@bevo.che.wisc.edu> * utils.cc (Vtreat_neg_dim_as_zero): Texinfoize doc string.
--- a/src/DLD-FUNCTIONS/balance.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/balance.cc Tue Nov 23 19:07:18 1999 +0000 @@ -62,23 +62,47 @@ } DEFUN_DLD (balance, args, nargout, - "AA = balance (A [, OPT]) or [[DD,] AA] = balance (A [, OPT])\n\ -\n\ -generalized eigenvalue problem:\n\ + "-*- texinfo -*- +@deftypefn {Loadable Function} {@var{aa} =} balance (@var{a}, @var{opt})\n\ +@deftypefnx {Loadable Function} {[@var{dd}, @var{aa}] =} balance (@var{a}, @var{opt})\n\ +@deftypefnx {Loadable Function} {[@var{cc}, @var{dd}, @var{aa}, @var{bb]} =} balance (@var{a}, @var{b}, @var{opt})\n\ \n\ - [cc, dd, aa, bb] = balance (a, b [, opt])\n\ +@code{[dd, aa] = balance (a)} returns @code{aa = dd \\ a * dd}.\n\ +@code{aa} is a matrix whose row and column norms are roughly equal in\n\ +magnitude, and @code{dd} = @code{p * d}, where @code{p} is a permutation\n\ +matrix and @code{d} is a diagonal matrix of powers of two. This allows\n\ +the equilibration to be computed without roundoff. Results of\n\ +eigenvalue calculation are typically improved by balancing first.\n\ \n\ -where OPT is an optional single character argument as follows: \n\ +@code{[cc, dd, aa, bb] = balance (a, b)} returns @code{aa = cc*a*dd} and\n\ +@code{bb = cc*b*dd)}, where @code{aa} and @code{bb} have non-zero\n\ +elements of approximately the same magnitude and @code{cc} and @code{dd}\n\ +are permuted diagonal matrices as in @code{dd} for the algebraic\n\ +eigenvalue problem.\n\ +\n\ +The eigenvalue balancing option @code{opt} is selected as follows:\n\ \n\ - N: no balancing; arguments copied, transformation(s) set to identity\n\ - P: permute argument(s) to isolate eigenvalues where possible\n\ - S: scale to improve accuracy of computed eigenvalues\n\ - B: (default) permute and scale, in that order. Rows/columns\n\ - of a (and b) that are isolated by permutation are not scaled\n\ +@table @asis\n\ +@item @code{\"N\"}, @code{\"n\"}\n\ +No balancing; arguments copied, transformation(s) set to identity.\n\ +\n\ +@item @code{\"P\"}, @code{\"p\"}\n\ +Permute argument(s) to isolate eigenvalues where possible.\n\ +\n\ +@item @code{\"S\"}, @code{\"s\"}\n\ +Scale to improve accuracy of computed eigenvalues.\n\ \n\ -[DD, AA] = balance (A, OPT) returns aa = inv(dd)*a*dd,\n\ +@item @code{\"B\"}, @code{\"b\"}\n\ +Permute and scale, in that order. Rows/columns of a (and b)\n\ +that are isolated by permutation are not scaled. This is the default\n\ +behavior.\n\ +@end table\n\ \n\ -[CC, DD, AA, BB] = balance (A, B, OPT) returns AA (BB) = CC*A*DD (CC*B*DD)") +Algebraic eigenvalue balancing uses standard @sc{Lapack} routines.\n\ +\n\ +Generalized eigenvalue problem balancing uses Ward's algorithm\n\ +(SIAM Journal on Scientific and Statistical Computing, 1981).\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/chol.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/chol.cc Tue Nov 23 19:07:18 1999 +0000 @@ -34,7 +34,23 @@ #include "utils.h" DEFUN_DLD (chol, args, nargout, - "[R, p] = chol (X): cholesky factorization") + "-*- texinfo -*- +@deftypefn {Loadable Function} {} chol (@var{a})\n\ +@cindex Cholesky factorization\n\ +Compute the Cholesky factor, @var{r}, of the symmetric positive definite\n\ +matrix @var{a}, where\n\ +@iftex\n\ +@tex\n\ +$ R^T R = A $.\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +\n\ +@example\n\ +r' * r = a.\n\ +@end example\n\ +@end ifinfo\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/det.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/det.cc Tue Nov 23 19:07:18 1999 +0000 @@ -34,7 +34,10 @@ #include "utils.h" DEFUN_DLD (det, args, , - "det (X): determinant of a square matrix") + "-*- texinfo -*- +@deftypefn {Loadable Function} {} det (@var{a})\n\ +Compute the determinant of @var{a} using @sc{Linpack}.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/eig.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/eig.cc Tue Nov 23 19:07:18 1999 +0000 @@ -33,7 +33,15 @@ #include "utils.h" DEFUN_DLD (eig, args, nargout, - "eig (X) or [V, D] = eig (X): compute eigenvalues and eigenvectors of X") + "-*- texinfo -*- +@deftypefn {Loadable Function} {@var{lambda} =} eig (@var{a})\n\ +@deftypefnx {Loadable Function} {[@var{v}, @var{lambda}] =} eig (@var{a})\n\ +The eigenvalues (and eigenvectors) of a matrix are computed in a several\n\ +step process which begins with a Hessenberg decomposition, followed by a\n\ +Schur decomposition, from which the eigenvalues are apparent. The\n\ +eigenvectors, when desired, are computed by further manipulations of the\n\ +Schur decomposition.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/expm.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/expm.cc Tue Nov 23 19:07:18 1999 +0000 @@ -33,7 +33,90 @@ #include "utils.h" DEFUN_DLD (expm, args, , - "expm (X): matrix exponential, e^A") + "-*- texinfo -*- +@deftypefn {Loadable Function} {} expm (@var{a})\n\ +Return the exponential of a matrix, defined as the infinite Taylor\n\ +series\n\ +@iftex\n\ +@tex\n\ +$$\n\ + \\exp (A) = I + A + {A^2 \\over 2!} + {A^3 \\over 3!} + \\cdots\n\ +$$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +\n\ +@example\n\ +expm(a) = I + a + a^2/2! + a^3/3! + ...\n\ +@end example\n\ +\n\ +@end ifinfo\n\ +The Taylor series is @emph{not} the way to compute the matrix\n\ +exponential; see Moler and Van Loan, @cite{Nineteen Dubious Ways to\n\ +Compute the Exponential of a Matrix}, SIAM Review, 1978. This routine\n\ +uses Ward's diagonal\n\ +@iftex\n\ +@tex\n\ +Pad\\'e\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +Pade'\n\ +@end ifinfo\n\ +approximation method with three step preconditioning (SIAM Journal on\n\ +Numerical Analysis, 1977). Diagonal\n\ +@iftex\n\ +@tex\n\ +Pad\\'e\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +Pade'\n\ +@end ifinfo\n\ + approximations are rational polynomials of matrices\n\ +@iftex\n\ +@tex\n\ +$D_q(a)^{-1}N_q(a)$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +\n\ +@example\n\ + -1\n\ +D (a) N (a)\n\ +@end example\n\ +\n\ +@end ifinfo\n\ + whose Taylor series matches the first\n\ +@iftex\n\ +@tex\n\ +$2 q + 1 $\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{2q+1}\n\ +@end ifinfo\n\ +terms of the Taylor series above; direct evaluation of the Taylor series\n\ +(with the same preconditioning steps) may be desirable in lieu of the\n\ +@iftex\n\ +@tex\n\ +Pad\\'e\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +Pade'\n\ +@end ifinfo\n\ +approximation when\n\ +@iftex\n\ +@tex\n\ +$D_q(a)$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{Dq(a)}\n\ +@end ifinfo\n\ +is ill-conditioned.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/givens.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/givens.cc Tue Nov 23 19:07:18 1999 +0000 @@ -31,12 +31,38 @@ #include "oct-obj.h" DEFUN_DLD (givens, args, nargout, - "G = givens (X, Y)\n\ + "-*- texinfo -*- +@deftypefn {Loadable Function} {@var{G} =} givens (@var{x}, @var{y})\n\ +@deftypefnx {Loadable Function} {[@var{c}, @var{s}] =} givens (@var{x}, @var{y})\n\ +@iftex\n\ +@tex\n\ +Return a $2\\times 2$ orthogonal matrix\n\ +$$\n\ + G = \\left[\\matrix{c & s\\cr -s'& c\\cr}\\right]\n\ +$$\n\ +such that\n\ +$$\n\ + G \\left[\\matrix{x\\cr y}\\right] = \\left[\\matrix{\\ast\\cr 0}\\right]\n\ +$$\n\ +with $x$ and $y$ scalars.\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +Return a 2 by 2 orthogonal matrix\n\ +@code{@var{G} = [@var{c} @var{s}; -@var{s}' @var{c}]} such that\n\ +@code{@var{G} [@var{x}; @var{y}] = [*; 0]} with @var{x} and @var{y} scalars.\n\ +@end ifinfo\n\ \n\ -compute orthogonal matrix G = [c s; -conj (s) c]\n\ -such that G [x; y] = [*; 0] (x, y scalars)\n\ +For example,\n\ \n\ -[c, s] = givens (x, y) returns the (c, s) values themselves.") +@example\n\ +@group\n\ +givens (1, 1)\n\ + @result{} 0.70711 0.70711\n\ + -0.70711 0.70711\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/hess.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/hess.cc Tue Nov 23 19:07:18 1999 +0000 @@ -34,7 +34,31 @@ #include "utils.h" DEFUN_DLD (hess, args, nargout, - "[P, H] = hess (A) or H = hess (A): Hessenberg decomposition") + "-*- texinfo -*- +@deftypefn {Loadable Function} {@var{h} =} hess (@var{a})\n\ +@deftypefnx {Loadable Function} {[@var{p}, @var{h}] =} hess (@var{a})\n\ +@cindex Hessenberg decomposition\n\ +Compute the Hessenberg decomposition of the matrix @var{a}.\n\ +\n\ +The Hessenberg decomposition is usually used as the first step in an\n\ +eigenvalue computation, but has other applications as well (see Golub,\n\ +Nash, and Van Loan, IEEE Transactions on Automatic Control, 1979. The\n\ +Hessenberg decomposition is\n\ +@iftex\n\ +@tex\n\ +$$\n\ +A = PHP^T\n\ +$$\n\ +where $P$ is a square unitary matrix ($P^HP = I$), and $H$\n\ +is upper Hessenberg ($H_{i,j} = 0, \\forall i \\ge j+1$).\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{p * h * p' = a} where @code{p} is a square unitary matrix\n\ +(@code{p' * p = I}, using complex-conjugate transposition) and @code{h}\n\ +is upper Hessenberg (@code{i >= j+1 => h (i, j) = 0}).\n\ +@end ifinfo\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/inv.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/inv.cc Tue Nov 23 19:07:18 1999 +0000 @@ -31,7 +31,11 @@ #include "utils.h" DEFUN_DLD (inv, args, , - "inv (X): inverse of a square matrix") + "-*- texinfo -*- +@deftypefn {Loadable Function} {} inv (@var{a})\n\ +@deftypefnx {Loadable Function} {} inverse (@var{a})\n\ +Compute the inverse of the square matrix @var{a}.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/log.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/log.cc Tue Nov 23 19:07:18 1999 +0000 @@ -36,7 +36,12 @@ // one... DEFUN_DLD (logm, args, , - "logm (X): matrix logarithm") + "-*- texinfo -*- +@deftypefn {Loadable Function} {} logm (@var{a})\n\ +Compute the matrix logarithm of the square matrix @var{a}. Note that\n\ +this is currently implemented in terms of an eigenvalue expansion and\n\ +needs to be improved to be more robust.\n\ +@end deftypefn") { octave_value_list retval; @@ -148,7 +153,12 @@ } DEFUN_DLD (sqrtm, args, , - "sqrtm (X): matrix sqrt") + "-*- texinfo -*- +@deftypefn {Loadable Function} {} sqrtm (@var{a})\n\ +Compute the matrix square root of the square matrix @var{a}. Note that\n\ +this is currently implemented in terms of an eigenvalue expansion and\n\ +needs to be improved to be more robust.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/lu.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/lu.cc Tue Nov 23 19:07:18 1999 +0000 @@ -34,7 +34,38 @@ #include "utils.h" DEFUN_DLD (lu, args, nargout, - "[L, U, P] = lu (A): LU factorization") + "-*- texinfo -*- +@deftypefn {Loadable Function} {[@var{l}, @var{u}, @var{p}] =} lu (@var{a})\n\ +@cindex LU decomposition\n\ +Compute the LU decomposition of @var{a}, using subroutines from\n\ +@sc{Lapack}. The result is returned in a permuted form, according to\n\ +the optional return value @var{p}. For example, given the matrix\n\ +@code{a = [1, 2; 3, 4]},\n\ +\n\ +@example\n\ +[l, u, p] = lu (a)\n\ +@end example\n\ +\n\ +@noindent\n\ +returns\n\ +\n\ +@example\n\ +l =\n\ +\n\ + 1.00000 0.00000\n\ + 0.33333 1.00000\n\ +\n\ +u =\n\ +\n\ + 3.00000 4.00000\n\ + 0.00000 0.66667\n\ +\n\ +p =\n\ +\n\ + 0 1\n\ + 1 0\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/pinv.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/pinv.cc Tue Nov 23 19:07:18 1999 +0000 @@ -32,14 +32,18 @@ DEFUN_DLD (pinv, args, , "-*- texinfo -*-\n\ -@deftypefn {Function File } { } pinv (@var{X}, @var{tol})\n\ -Returns the pseudoinverse of X; singular values less than tol are ignored.\n\ +@deftypefn {Loadable Function} {} pinv (@var{x}, @var{tol})\n\ +Return the pseudoinverse of @var{x}. Singular values less than\n\ +@var{tol} are ignored. \n\ +\n\ +If the second argument is omitted, it is assumed that\n\ \n\ -If the second arguement is ommited , it is assummed that\n\ @example\n\ -tol = max (size (X)) * sigma_max (X) * eps,\n\ +tol = max (size (@var{x})) * sigma_max (@var{x}) * eps,\n\ @end example\n\ -where sigma_max(X) is the maximal singular value of X.\n\ +\n\ +@noindent\n\ +where @code{sigma_max (@var{x})} is the maximal singular value of @var{x}.\n\ @end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/qr.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/qr.cc Tue Nov 23 19:07:18 1999 +0000 @@ -35,23 +35,118 @@ #include "oct-obj.h" #include "utils.h" +// [Q, R] = qr (X): form Q unitary and R upper triangular such +// that Q * R = X +// +// [Q, R] = qr (X, 0): form the economy decomposition such that if X is +// m by n then only the first n columns of Q are +// computed. +// +// [Q, R, P] = qr (X): form QRP factorization of X where +// P is a permutation matrix such that +// A * P = Q * R +// +// [Q, R, P] = qr (X, 0): form the economy decomposition with +// permutation vector P such that Q * R = X (:, P) +// +// qr (X) alone returns the output of the LAPACK routine dgeqrf, such +// that R = triu (qr (X)) + DEFUN_DLD (qr, args, nargout, - "[Q, R] = qr (X): form Q unitary and R upper triangular such\n\ - that Q * R = X\n\ + "-*- texinfo -*- +@deftypefn {Loadable Function} {[@var{q}, @var{r}, @var{p}] =} qr (@var{a})\n\ +@cindex QR factorization\n\ +Compute the QR factorization of @var{a}, using standard @sc{Lapack}\n\ +subroutines. For example, given the matrix @code{a = [1, 2; 3, 4]},\n\ \n\ -[Q, R] = qr (X, 0): form the economy decomposition such that if X is\n\ - m by n then only the first n columns of Q are\n\ - computed.\n\ +@example\n\ +[q, r] = qr (a)\n\ +@end example\n\ +\n\ +@noindent\n\ +returns\n\ +\n\ +@example\n\ +q =\n\ +\n\ + -0.31623 -0.94868\n\ + -0.94868 0.31623\n\ +\n\ +r =\n\ +\n\ + -3.16228 -4.42719\n\ + 0.00000 -0.63246\n\ +@end example\n\ +\n\ +The @code{qr} factorization has applications in the solution of least\n\ +squares problems\n\ +@iftex\n\ +@tex\n\ +$$\n\ +\\min_x \\left\\Vert A x - b \\right\\Vert_2\n\ +$$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ \n\ -[Q, R, P] = qr (X): form QRP factorization of X where\n\ - P is a permutation matrix such that\n\ - A * P = Q * R\n\ +@example\n\ +@code{min norm(A x - b)}\n\ +@end example\n\ +\n\ +@end ifinfo\n\ +for overdetermined systems of equations (i.e.,\n\ +@iftex\n\ +@tex\n\ +$A$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{a}\n\ +@end ifinfo\n\ + is a tall, thin matrix). The QR factorization is\n\ +@iftex\n\ +@tex\n\ +$QR = A$ where $Q$ is an orthogonal matrix and $R$ is upper triangular.\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{q * r = a} where @code{q} is an orthogonal matrix and @code{r} is\n\ +upper triangular.\n\ +@end ifinfo\n\ \n\ -[Q, R, P] = qr (X, 0): form the economy decomposition with \n\ - permutation vector P such that Q * R = X (:, P)\n\ +The permuted QR factorization @code{[@var{q}, @var{r}, @var{p}] =\n\ +qr (@var{a})} forms the QR factorization such that the diagonal\n\ +entries of @code{r} are decreasing in magnitude order. For example,\n\ +given the matrix @code{a = [1, 2; 3, 4]},\n\ +\n\ +@example\n\ +[q, r, pi] = qr(a)\n\ +@end example\n\ +\n\ +@noindent\n\ +returns\n\ +\n\ +@example\n\ +q = \n\ \n\ -qr (X) alone returns the output of the LAPACK routine dgeqrf, such\n\ -that R = triu (qr (X))") + -0.44721 -0.89443\n\ + -0.89443 0.44721\n\ +\n\ +r =\n\ +\n\ + -4.47214 -3.13050\n\ + 0.00000 0.44721\n\ +\n\ +p =\n\ +\n\ + 0 1\n\ + 1 0\n\ +@end example\n\ +\n\ +The permuted @code{qr} factorization @code{[q, r, p] = qr (a)}\n\ +factorization allows the construction of an orthogonal basis of\n\ +@code{span (a)}.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/qz.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/qz.cc Tue Nov 23 19:07:18 1999 +0000 @@ -178,42 +178,63 @@ } DEFUN_DLD (qz, args, nargout, -"Usage:\n\ - - lambda = qz (A, B) form [1]\n\ - [AA, BB, Q, Z {, V, W, lambda}] = qz (A, B) form [2]\n\ - [AA, BB, Z{, lambda}] = qz (A, B, opt) form [3]\n\ + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {@var{lambda} =} qz (@var{a}, @var{b})\n\ +Generalized eigenvalue problem @math{A x = s B x},\n\ +@var{QZ} decomposition. Three ways to call:\n\ +@enumerate\n\ +@item @code{lambda = qz(A,B)}\n\ \n\ -Generalized eigenvalue problem A x = s B x \n\ +Computes the generalized eigenvalues @var{lambda} of @math{(A - sB)}.\n\ +\n\ +@item @code{[AA, BB, Q, Z @{, V, W, lambda@}] = qz (A, B)}\n\ \n\ -Form [1]: Computes the generalized eigenvalues lambda of (A - sB).\n\ +Computes qz decomposition, generalized eigenvectors, and \n\ + generalized eigenvalues of @math{(A - sB)}\n\ +@example\n\ +@group\n\ + A V = B V diag(lambda)\n\ + W' A = diag(lambda) W' B\n\ + AA = Q'*A*Z, BB = Q'*B*Z with Q, Z orthogonal (unitary)= I\n\ +@end group\n\ +@end example\n\ \n\ -Form [2]: Computes qz decomposition, generalized eigenvectors, and \n\ - generalized eigenvalues of (A - sB)\n\ - A V = B V diag (lambda)\n\ - W' A = diag (lambda) W' B\n\ - AA = Q'*A*Z, BB = Q'*B*Z with Q, Z orthogonal (unitary)= I\n\ +@item @code{[AA,BB,Z@{,lambda@}] = qz(A,B,opt)}\n\ \n\ -Form [3]: As in form [2], but allows ordering of generalized eigenpairs\n\ - for (e.g.) solution of discrete time algebraic Riccati equations.\n\ - Form 3 is not available for complex matrices and does not compute\n\ - the generalized eigenvectors V, W, nor the orthogonal matrix Q.\n\ +As in form [2], but allows ordering of generalized eigenpairs\n\ + for (e.g.) solution of discrete time algebraic Riccati equations.\n\ + Form 3 is not available for complex matrices and does not compute\n\ + the generalized eigenvectors V, W, nor the orthogonal matrix Q.\n\ +@table @var\n\ +@item opt\n\ + for ordering eigenvalues of the GEP pencil. The leading block\n\ + of the revised pencil contains all eigenvalues that satisfy:\n\ +@table @code\n\ +@item \"N\"\n\ + = unordered (default) \n\ \n\ - opt: for ordering eigenvalues of the GEP pencil. The leading block\n\ - of the revised pencil contains all eigenvalues that satisfy:\n\ +@item \"S\"\n\ += small: leading block has all |lambda| <=1 \n\ \n\ - \"N\" = unordered (default) \n\ - \"S\" = small: leading block has all |lambda| <=1 \n\ - \"B\" = big: leading block has all |lambda >= 1 \n\ - \"-\" = negative real part: leading block has all eigenvalues\n\ +@item \"B\"\n\ + = big: leading block has all |lambda >= 1 \n\ +\n\ +@item \"-\"\n\ + = negative real part: leading block has all eigenvalues\n\ in the open left half-plant\n\ - \"+\" = nonnegative real part: leading block has all eigenvalues\n\ +\n\ +@item \"+\"\n\ + = nonnegative real part: leading block has all eigenvalues\n\ in the closed right half-plane\n\ +@end table\n\ +@end table\n\ +@end enumerate\n\ \n\ -Note: Permutation balancing is performed, but not scaling (see balance)\n\ +Note: qz performs permutation balancing, but not scaling (see balance).\n\ Order of output arguments was selected for compatibility with MATLAB\n\ \n\ -See also: balance, dare, eig, schur") +See also: balance, dare, eig, schur\n\ +@end deftypefn") { octave_value_list retval; int nargin = args.length ();
--- a/src/DLD-FUNCTIONS/schur.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/schur.cc Tue Nov 23 19:07:18 1999 +0000 @@ -36,17 +36,212 @@ #include "utils.h" DEFUN_DLD (schur, args, nargout, - "[U, S] = schur (A) or S = schur (A)\n\ -\n\ -or, for ordered Schur:\n\ + "-*- texinfo -*- +@deftypefn {Loadable Function} {@var{s} =} schur (@var{a})\n\ +@deftypefnx {Loadable Function} {[@var{u}, @var{s}] =} schur (@var{a}, @var{opt})\n\ +@cindex Schur decomposition\n\ +The Schur decomposition is used to compute eigenvalues of a\n\ +square matrix, and has applications in the solution of algebraic\n\ +Riccati equations in control (see @code{are} and @code{dare}).\n\ +@code{schur} always returns\n\ +@iftex\n\ +@tex\n\ +$S = U^T A U$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{s = u' * a * u}\n\ +@end ifinfo\n\ +where\n\ +@iftex\n\ +@tex\n\ +$U$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{u}\n\ +@end ifinfo\n\ + is a unitary matrix\n\ +@iftex\n\ +@tex\n\ +($U^T U$ is identity)\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +(@code{u'* u} is identity)\n\ +@end ifinfo\n\ +and\n\ +@iftex\n\ +@tex\n\ +$S$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{s}\n\ +@end ifinfo\n\ +is upper triangular. The eigenvalues of\n\ +@iftex\n\ +@tex\n\ +$A$ (and $S$)\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{a} (and @code{s})\n\ +@end ifinfo\n\ +are the diagonal elements of\n\ +@iftex\n\ +@tex\n\ +$S$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{s}\n\ +@end ifinfo\n\ +If the matrix\n\ +@iftex\n\ +@tex\n\ +$A$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{a}\n\ +@end ifinfo\n\ +is real, then the real Schur decomposition is computed, in which the\n\ +matrix\n\ +@iftex\n\ +@tex\n\ +$U$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{u}\n\ +@end ifinfo\n\ +is orthogonal and\n\ +@iftex\n\ +@tex\n\ +$S$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{s}\n\ +@end ifinfo\n\ +is block upper triangular\n\ +with blocks of size at most\n\ +@iftex\n\ +@tex\n\ +$2\\times 2$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{2 x 2}\n\ +@end ifinfo\n\ +blocks along the diagonal. The diagonal elements of\n\ +@iftex\n\ +@tex\n\ +$S$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{s}\n\ +@end ifinfo\n\ +(or the eigenvalues of the\n\ +@iftex\n\ +@tex\n\ +$2\\times 2$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{2 x 2}\n\ +@end ifinfo\n\ +blocks, when\n\ +appropriate) are the eigenvalues of\n\ +@iftex\n\ +@tex\n\ +$A$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{a}\n\ +@end ifinfo\n\ +and\n\ +@iftex\n\ +@tex\n\ +$S$.\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{s}.\n\ +@end ifinfo\n\ \n\ - [U, S] = schur (A, TYPE) or S = schur (A, TYPE)\n\ -where TYPE is a string that begins with one of the following\n\ -characters:\n\ -\n\ - A = continuous time poles\n\ - D = discrete time poles\n\ - U = unordered schur (default)") +The eigenvalues are optionally ordered along the diagonal according to\n\ +the value of @code{opt}. @code{opt = \"a\"} indicates that all\n\ +eigenvalues with negative real parts should be moved to the leading\n\ +block of\n\ +@iftex\n\ +@tex\n\ +$S$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{s}\n\ +@end ifinfo\n\ +(used in @code{are}), @code{opt = \"d\"} indicates that all eigenvalues\n\ +with magnitude less than one should be moved to the leading block of\n\ +@iftex\n\ +@tex\n\ +$S$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{s}\n\ +@end ifinfo\n\ +(used in @code{dare}), and @code{opt = \"u\"}, the default, indicates that\n\ +no ordering of eigenvalues should occur. The leading\n\ +@iftex\n\ +@tex\n\ +$k$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{k}\n\ +@end ifinfo\n\ +columns of\n\ +@iftex\n\ +@tex\n\ +$U$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{u}\n\ +@end ifinfo\n\ +always span the\n\ +@iftex\n\ +@tex\n\ +$A$-invariant\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{a}-invariant\n\ +@end ifinfo\n\ +subspace corresponding to the\n\ +@iftex\n\ +@tex\n\ +$k$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{k}\n\ +@end ifinfo\n\ +leading eigenvalues of\n\ +@iftex\n\ +@tex\n\ +$S$.\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +@code{s}.\n\ +@end ifinfo\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/svd.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/svd.cc Tue Nov 23 19:07:18 1999 +0000 @@ -35,13 +35,86 @@ #include "utils.h" DEFUN_DLD (svd, args, nargout, - "S = svd (X) or [U, S, V] = svd (X [, 0])\n\ + "-*- texinfo -*- +@deftypefn {Loadable Function} {@var{s} =} svd (@var{a})\n\ +@deftypefnx {Loadable Function} {[@var{u}, @var{s}, @var{v}] =} svd (@var{a})\n\ +@cindex singular value decomposition\n\ +Compute the singular value decomposition of @var{a}\n\ +@iftex\n\ +@tex\n\ +$$\n\ + A = U\\Sigma V^H\n\ +$$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +\n\ +@example\n\ +a = u * sigma * v'\n\ +@end example\n\ +@end ifinfo\n\ +\n\ +The function @code{svd} normally returns the vector of singular values.\n\ +If asked for three return values, it computes\n\ +@iftex\n\ +@tex\n\ +$U$, $S$, and $V$.\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +U, S, and V.\n\ +@end ifinfo\n\ +For example,\n\ +\n\ +@example\n\ +svd (hilb (3))\n\ +@end example\n\ +\n\ +@noindent\n\ +returns\n\ \n\ -Compute the singular value decomposition of X. Given a second input\n\ -argument, an `economy' sized factorization is computed that omits\n\ -unnecessary rows and columns of U and V.\n\ +@example\n\ +ans =\n\ +\n\ + 1.4083189\n\ + 0.1223271\n\ + 0.0026873\n\ +@end example\n\ +\n\ +@noindent\n\ +and\n\ +\n\ +@example\n\ +[u, s, v] = svd (hilb (3))\n\ +@end example\n\ +\n\ +@noindent\n\ +returns\n\ +\n\ +@example\n\ +u =\n\ \n\ -X may not contain any Inf or NaN values.") + -0.82704 0.54745 0.12766\n\ + -0.45986 -0.52829 -0.71375\n\ + -0.32330 -0.64901 0.68867\n\ +\n\ +s =\n\ +\n\ + 1.40832 0.00000 0.00000\n\ + 0.00000 0.12233 0.00000\n\ + 0.00000 0.00000 0.00269\n\ +\n\ +v =\n\ +\n\ + -0.82704 0.54745 0.12766\n\ + -0.45986 -0.52829 -0.71375\n\ + -0.32330 -0.64901 0.68867\n\ +@end example\n\ +\n\ +If given a second argument, @code{svd} returns an economy-sized\n\ +decomposition, eliminating the unnecessary rows or columns of @var{u} or\n\ +@var{v}.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/syl.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/DLD-FUNCTIONS/syl.cc Tue Nov 23 19:07:18 1999 +0000 @@ -33,7 +33,31 @@ #include "utils.h" DEFUN_DLD (syl, args, nargout, - "X = syl (A, B, C): solve the Sylvester equation A X + X B + C = 0") + "-*- texinfo -*- +@deftypefn {Loadable Function} {@var{x} =} syl (@var{a}, @var{b}, @var{c})\n\ +Solve the Sylvester equation\n\ +@iftex\n\ +@tex\n\ +$$\n\ + A X + X B + C = 0\n\ +$$\n\ +@end tex\n\ +@end iftex\n\ +@ifinfo\n\ +\n\ +@example\n\ +A X + X B + C = 0\n\ +@end example\n\ +@end ifinfo\n\ +using standard @sc{Lapack} subroutines. For example,\n\ +\n\ +@example\n\ +@group\n\ +syl ([1, 2; 3, 4], [5, 6; 7, 8], [9, 10; 11, 12])\n\ + @result{} [ -0.50000, -0.66667; -0.66667, -0.50000 ]\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/file-io.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/file-io.cc Tue Nov 23 19:07:18 1999 +0000 @@ -148,7 +148,12 @@ } DEFUN (fclose, args, , - "fclose (FILENUM): close a file") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} fclose (@var{fid})\n\ +Closes the specified file. If an error is encountered while trying to\n\ +close the file, an error message is printed and @code{fclose} returns\n\ +0. Otherwise, it returns 1.\n\ +@end deftypefn") { double retval = -1.0; @@ -164,7 +169,13 @@ } DEFUN (fflush, args, , - "fflush (FILENUM): flush buffered data to output file") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} fflush (@var{fid})\n\ +Flush output to @var{fid}. This is useful for ensuring that all\n\ +pending output makes it to the screen before some other event occurs.\n\ +For example, it is always a good idea to flush the standard output\n\ +stream before calling @code{input}.\n\ +@end deftypefn") { double retval = -1.0; @@ -197,9 +208,17 @@ } DEFUN (fgetl, args, , - "[STRING, LENGTH] = fgetl (FILENUM [, LENGTH])\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} fgetl (@var{fid}, @var{len})\n\ +Read characters from a file, stopping after a newline, or EOF,\n\ +or @var{len} characters have been read. The characters read, excluding\n\ +the possible trailing newline, are returned as a string.\n\ \n\ -read a string from a file") +If @var{len} is omitted, @code{fgetl} reads until the next newline\n\ +character.\n\ +\n\ +If there are no more characters to read, @code{fgetl} returns @minus{}1.\n\ +@end deftypefn") { octave_value_list retval; @@ -235,9 +254,17 @@ } DEFUN (fgets, args, , - "[STRING, LENGTH] = fgets (FILENUM [, LENGTH])\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} fgets (@var{fid}, @var{len})\n\ +Read characters from a file, stopping after a newline, or EOF,\n\ +or @var{len} characters have been read. The characters read, including\n\ +the possible trailing newline, are returned as a string.\n\ \n\ -read a string from a file") +If @var{len} is omitted, @code{fgets} reads until the next newline\n\ +character.\n\ +\n\ +If there are no more characters to read, @code{fgets} returns @minus{}1.\n\ +@end deftypefn") { octave_value_list retval; @@ -327,41 +354,94 @@ } DEFUN (fopen, args, , - "[FILENUM, ERRMSG] = fopen (FILENAME, MODE [, ARCH]): open a file\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{fid}, @var{msg}] =} fopen (@var{name}, @var{mode}, @var{arch})\n\ +@deftypefnx {Built-in Function} {@var{fid_list} =} fopen (\"all\")\n\ +@deftypefnx {Built-in Function} {@var{file} =} fopen (@var{fid})\n\ +The first form of the @code{fopen} function opens the named file with\n\ +the specified mode (read-write, read-only, etc.) and architecture\n\ +interpretation (IEEE big endian, IEEE little endian, etc.), and returns\n\ +an integer value that may be used to refer to the file later. If an\n\ +error occurs, @var{fid} is set to @minus{}1 and @var{msg} contains the\n\ +corresponding system error message. The @var{mode} is a one or two\n\ +character string that specifies whether the file is to be opened for\n\ +reading, writing, or both.\n\ \n\ - FILENAME is a string specifying the name of the file.\n\ +The second form of the @code{fopen} function returns a vector of file ids\n\ +corresponding to all the currently open files, excluding the\n\ +@code{stdin}, @code{stdout}, and @code{stderr} streams.\n\ \n\ - MODE is a string specifying whether the file should be opened for\n\ - reading, writing, or both. Valid values for MODE include:\n\ +The third form of the @code{fopen} function returns the name of a\n\ +currently open file given its file id.\n\ \n\ - r : open text file for reading\n\ - w : open text file for writing; discard previous contents if any\n\ - a : append; open or create text file for writing at end of file\n\ - r+ : open text file for update (i.e., reading and writing)\n\ - w+ : create text file for update; discard previous contents if any\n\ - a+ : append; open or create text file for update, writing at end\n\ +For example,\n\ +\n\ +@example\n\ +myfile = fopen (\"splat.dat\", \"r\", \"ieee-le\");\n\ +@end example\n\ \n\ - Update mode permits reading from and writing to the same file.\n\ +@noindent\n\ +opens the file @file{splat.dat} for reading. If necessary, binary\n\ +numeric values will be read assuming they are stored in IEEE format with\n\ +the least significant bit first, and then converted to the native\n\ +representation.\n\ \n\ - If MODE is missing, a value of \"r\" is assumed.\n\ +Opening a file that is already open simply opens it again and returns a\n\ +separate file id. It is not an error to open a file several times,\n\ +though writing to the same file through several different file ids may\n\ +produce unexpected results.\n\ +\n\ +The possible values @samp{mode} may have are\n\ +\n\ +@table @asis\n\ +@item @samp{r}\n\ +Open a file for reading.\n\ \n\ - ARCH is a string specifying the default data format for the file.\n\ - Valid values for ARCH are:\n\ +@item @samp{w}\n\ +Open a file for writing. The previous contents are discared.\n\ +\n\ +@item @samp{a}\n\ +Open or create a file for writing at the end of the file.\n\ +\n\ +@item @samp{r+}\n\ +Open an existing file for reading and writing.\n\ +\n\ +@item @samp{w+}\n\ +Open a file for reading or writing. The previous contents are\n\ +discarded.\n\ +\n\ +@item @samp{a+}\n\ +Open or create a file for reading or writing at the end of the\n\ +file.\n\ +@end table\n\ +\n\ +The parameter @var{arch} is a string specifying the default data format\n\ +for the file. Valid values for @var{arch} are:\n\ \n\ - native -- the format of the current machine (this is the default)\n\ - ieee-le -- IEEE big endian\n\ - ieee-be -- IEEE little endian\n\ - vaxd -- VAX D floating format\n\ - vaxg -- VAX G floating format\n\ - cray -- Cray floating format\n\ +@table @asis\n\ +@samp{native}\n\ +The format of the current machine (this is the default).\n\ +\n\ +@samp{ieee-le}\n\ +IEEE big endian format.\n\ +\n\ +@samp{ieee-be}\n\ +IEEE little endian format.\n\ \n\ - however, conversions are currently only supported for ieee-be, and\n\ - ieee-le formats.\n\ +@samp{vaxd}\n\ +VAX D floating format.\n\ \n\ +@samp{vaxg}\n\ +VAX G floating format.\n\ \n\ - FILENUM is a number that can be used to refer to the open file.\n\ - If fopen fails, FILENUM is set to -1 and ERRMSG contains a\n\ - system-dependent error message") +@samp{cray}\n\ +Cray floating format.\n\ +@end table\n\ +\n\ +@noindent\n\ +however, conversions are currently only supported for @samp{native}\n\ +@samp{ieee-be}, and @samp{ieee-le} formats.\n\ +@end deftypefn") { octave_value_list retval; @@ -433,7 +513,24 @@ } DEFUN (freport, args, , - "freport (): list open files and their status") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} freport ()\n\ +Print a list of which files have been opened, and whether they are open\n\ +for reading, writing, or both. For example,\n\ +\n\ +@example\n\ +@group\n\ +freport ()\n\ +\n\ + @print{} number mode name\n\ + @print{} \n\ + @print{} 0 r stdin\n\ + @print{} 1 w stdout\n\ + @print{} 2 w stderr\n\ + @print{} 3 r myfile\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval; @@ -448,7 +545,12 @@ } DEFUN (frewind, args, , - "frewind (FILENUM): set file position at beginning of file") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} frewind (@var{fid})\n\ +Move the file pointer to the beginning of the file @var{fid}, returning\n\ +1 for success, and 0 if an error was encountered. It is equivalent to\n\ +@code{fseek (@var{fid}, 0, SEEK_SET)}.\n\ +@end deftypefn") { double retval = -1.0; @@ -468,15 +570,16 @@ } DEFUN (fseek, args, , - "fseek (FILENUM, OFFSET [, ORIGIN])\n\ -\n\ -set file position for reading or writing.\n\ -\n\ -ORIGIN may be one of:\n\ -\n\ - SEEK_SET : offset is relative to the beginning of the file (default)\n\ - SEEK_CUR : offset is relative to the current position\n\ - SEEK_END : offset is relative to the end of the file") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} fseek (@var{fid}, @var{offset}, @var{origin})\n\ +Set the file pointer to any location within the file @var{fid}. The\n\ +pointer is positioned @var{offset} characters from the @var{origin},\n\ +which may be one of the predefined variables @code{SEEK_CUR} (current\n\ +position), @code{SEEK_SET} (beginning), or @code{SEEK_END} (end of\n\ +file). If @var{origin} is omitted, @code{SEEK_SET} is assumed. The\n\ +offset must be zero, or a value returned by @code{ftell} (in which case\n\ +@var{origin} must be @code{SEEK_SET}.\n\ +@end deftypefn") { double retval = -1.0; @@ -501,7 +604,11 @@ } DEFUN (ftell, args, , - "POSITION = ftell (FILENUM): returns the current file position") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} ftell (@var{fid})\n\ +Return the position of the file pointer as the number of characters\n\ +from the beginning of the file @var{fid}.\n\ +@end deftypefn") { double retval = -1.0; @@ -521,7 +628,11 @@ } DEFUN (fprintf, args, , - "fprintf (FILENUM, FORMAT, ...)") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} fprintf (@var{fid}, @var{template}, @dots{})\n\ +This function is just like @code{printf}, except that the output is\n\ +written to the stream @var{fid} instead of @code{stdout}.\n\ +@end deftypefn") { double retval = -1.0; @@ -569,7 +680,10 @@ } DEFUN (fputs, args, , - "fputs (FILENUM, STRING)") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} fputs (@var{fid}, @var{string})\n\ +Write a string to a file with no formatting.\n\ +@end deftypefn") { double retval = -1.0; @@ -589,7 +703,14 @@ } DEFUN (sprintf, args, , - "[s, errmsg, status] = sprintf (FORMAT, ...)") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} sprintf (@var{template}, @dots{})\n\ +This is like @code{printf}, except that the output is returned as a\n\ +string. Unlike the C library function, which requires you to provide a\n\ +suitably sized string as an argument, Octave's @code{sprintf} function\n\ +returns the string, automatically sized to hold all of the items\n\ +converted.\n\ +@end deftypefn") { octave_value_list retval; @@ -638,27 +759,46 @@ } DEFUN (fscanf, args, , - "[A, COUNT] = fscanf (FILENUM, FORMAT [, SIZE])\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{val}, @var{count}] =} fscanf (@var{fid}, @var{template}, @var{size})\n\ +@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}] = } fscanf (@var{fid}, @var{template}, \"C\")\n\ +In the first form, read from @var{fid} according to @var{template},\n\ +returning the result in the matrix @var{val}.\n\ \n\ -Read from FILENUM according to FORMAT, returning the result in the\n\ -matrix A. SIZE is optional. If present, it can be one of\n\ +The optional argument @var{size} specifies the amount of data to read\n\ +and may be one of\n\ +\n\ +@table @code\n\ +@item Inf\n\ +Read as much as possible, returning a column vector.\n\ +\n\ +@item @var{nr}\n\ +Read up to @var{nr} elements, returning a column vector.\n\ \n\ - Inf : read as much as possible, returning a column vector\n\ - (unless doing all character conversions, in which case a\n\ - string is returned)\n\ - NR : read up to NR elements, returning a column vector\n\ - [NR, NC] : read up to NR x NC elements, returning a matrix with NR rows\n\ - [NR, Inf] : read as much as possible, returning a matrix with NR rows\n\ +@item [@var{nr}, Inf]\n\ +Read as much as possible, returning a matrix with @var{nr} rows. If the\n\ +number of elements read is not an exact multiple of @var{nr}, the last\n\ +column is padded with zeros.\n\ +\n\ +@item [@var{nr}, @var{nc}]\n\ +Read up to @code{@var{nr} * @var{nc}} elements, returning a matrix with\n\ +@var{nr} rows. If the number of elements read is not an exact multiple\n\ +of @var{nr}, the last column is padded with zeros.\n\ +@end table\n\ \n\ -If it is omitted, a value of Inf is assumed.\n\ +@noindent\n\ +If @var{size} is omitted, a value of @code{Inf} is assumed.\n\ \n\ -The number of items successfully read is returned in COUNT.\n\ +A string is returned if @var{template} specifies only character\n\ +conversions.\n\ \n\ -[A, B, ...] = fscanf (FILENUM, FORMAT, \"C\")\n\ +The number of items successfully read is returned in @var{count}.\n\ \n\ -Read from FILENUM according to FORMAT, with each conversion specifier\n\ -in FORMAT corresponding to a single scalar return value. This form is\n\ -more `C-like', and also compatible with previous versions of Octave") +In the second form, read from @var{fid} according to @var{template},\n\ +with each conversion specifier in @var{template} corresponding to a\n\ +single scalar return value. This form is more `C-like', and also\n\ +compatible with previous versions of Octave.\n\ +@end deftypefn") { octave_value_list retval; @@ -720,30 +860,13 @@ } DEFUN (sscanf, args, , - "[A, COUNT, ERRMSG, INDEX] = sscanf (STRING, FORMAT, SIZE)\n\ -\n\ -Read from STRING according to FORMAT, returning the result in the\n\ -matrix A. SIZE is optional. If present, it can be one of\n\ -\n\ - Inf : read as much as possible, returning a column vector\n\ - (unless doing all character conversions, in which case a\n\ - string is returned)\n\ - NR : read up to NR elements, returning a column vector\n\ - [NR, NC] : read up to NR x NC elements, returning a matrix with NR rows\n\ - [NR, Inf] : read as much as possible, returning a matrix with NR rows\n\ -\n\ -If it is omitted, a value of Inf is assumed.\n\ -\n\ -The number of items successfully read is returned in COUNT. If an\n\ -error occurs, ERRMSG contains the text of the corresponding error\n\ -message. INDEX contains the index of the next character to be read\n\ -from STRING\n\ -\n\ -[A, B, ...] = sscanf (STRING, FORMAT, \"C\")\n\ -\n\ -Read from STRING according to FORMAT, with each conversion specifier\n\ -in FORMAT corresponding to a single scalar return value. This form is\n\ -more `C-like', and also compatible with previous versions of Octave") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{val}, @var{count}] =} sscanf (@var{string}, @var{template}, @var{size})\n\ +@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}] = } sscanf (@var{string}, @var{template}, \"C\")\n\ +This is like @code{fscanf}, except that the characters are taken from the\n\ +string @var{string} instead of from a stream. Reaching the end of the\n\ +string is treated as an end-of-file condition.\n\ +@end deftypefn") { octave_value_list retval; @@ -829,7 +952,14 @@ } DEFUN (scanf, args, nargout, - "scanf (FORMAT) is equivalent to fscanf (stdin, FORMAT)") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{val}, @var{count}] =} scanf (@var{template}, @var{size})\n\ +@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}] = } scanf (@var{template}, \"C\")\n\ +This is equivalent to calling @code{fscanf} with @var{fid} = @code{stdin}.\n\ +\n\ +It is currently not useful to call @code{scanf} in interactive\n\ +programs.\n\ +@end deftypefn") { int nargin = args.length (); @@ -897,52 +1027,130 @@ } DEFUN (fread, args, , - "[DATA, COUNT] = fread (FILENUM [, SIZE] [, PRECISION] [, SKIP] [, ARCH])\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{val}, @var{count}] =} fread (@var{fid}, @var{size}, @var{precision}, @var{skip}, @var{arch})\n\ +Read binary data of type @var{precision} from the specified file ID\n\ +@var{fid}.\n\ +\n\ +The optional argument @var{size} specifies the amount of data to read\n\ +and may be one of\n\ +\n\ +@table @code\n\ +@item Inf\n\ +Read as much as possible, returning a column vector.\n\ \n\ -Reads data in binary form of type PRECISION from a file.\n\ +@item @var{nr}\n\ +Read up to @var{nr} elements, returning a column vector.\n\ +\n\ +@item [@var{nr}, Inf]\n\ +Read as much as possible, returning a matrix with @var{nr} rows. If the\n\ +number of elements read is not an exact multiple of @var{nr}, the last\n\ +column is padded with zeros.\n\ +\n\ +@item [@var{nr}, @var{nc}]\n\ +Read up to @code{@var{nr} * @var{nc}} elements, returning a matrix with\n\ +@var{nr} rows. If the number of elements read is not an exact multiple\n\ +of @var{nr}, the last column is padded with zeros.\n\ +@end table\n\ +\n\ +@noindent\n\ +If @var{size} is omitted, a value of @code{Inf} is assumed.\n\ \n\ - FILENUM : file number from fopen\n\ +The optional argument @var{precision} is a string specifying the type of\n\ +data to read and may be one of\n\ +\n\ +@table @code\n\ +@item \"char\"\n\ +@itemx \"char*1\"\n\ +@itemx \"integer*1\"\n\ +@itemx \"int8\"\n\ +Single character.\n\ +\n\ +@item \"signed char\"\n\ +@itemx \"schar\"\n\ +Signed character.\n\ \n\ - SIZE : size specification for the data matrix\n\ +@item \"unsigned char\"\n\ +@itemx \"uchar\"\n\ +Unsigned character.\n\ +\n\ +@item \"short\"\n\ +Short integer.\n\ \n\ - PRECISION : string specifying type of data to read, valid types are\n\ +@item \"unsigned short\"\n\ +@itemx \"ushort\"\n\ +Unsigned short integer.\n\ +\n\ +@item \"int\"\n\ +Integer.\n\ +\n\ +@item \"unsigned int\"\n\ +@itemx \"uint\"\n\ +Unsigned integer.\n\ \n\ - char, char*1, integer*1, int8 -- character\n\ - schar, signed char -- signed character\n\ - uchar, unsigned char -- unsigned character (default)\n\ - short -- short integer\n\ - ushort, unsigned short -- unsigned short integer\n\ - int -- integer\n\ - uint, unsigned int -- unsigned integer\n\ - long -- long integer\n\ - ulong, unsigned long -- unsigned long integer\n\ - float, float32, real*4 -- single precision float\n\ - double, float64, real*8 -- double precision float\n\ - int16, integer*2 -- two byte integer\n\ - uint16 -- two byte unsigned integer\n\ - int32, integer*4 -- four byte integer\n\ - uint32 -- four byte unsigned integer\n\ +@item \"long\"\n\ +Long integer.\n\ +\n\ +@item \"unsigned long\"\n\ +@itemx \"ulong\"\n\ +Unsigned long integer.\n\ +\n\ +@item \"float\"\n\ +@itemx \"float32\"\n\ +@itemx \"real*4\"\n\ +Single precision float.\n\ +\n\ +@item \"double\"\n\ +@itemx \"float64\"\n\ +@itemx \"real*8\"\n\ +Double precision float.\n\ +\n\ +@item \"integer*2\"\n\ +@itemx \"int16\"\n\ +Two byte integer.\n\ +\n\ +@item \"integer*4\"\n\ +@itemx \"int32\"\n\ +Four byte integer.\n\ +@end table\n\ +\n\ +@noindent\n\ +The default precision is @code{\"uchar\"}.\n\ \n\ - SKIP : number of bytes to skip after each element is read\n\ - (default is 0)\n\ +The optional argument @var{skip} specifies the number of bytes to skip\n\ +before each element is read. If it is not specified, a value of 0 is\n\ +assumed.\n\ +\n\ +The optional argument @var{arch} is a string specifying the data format\n\ +for the file. Valid values are\n\ \n\ - ARCH : string specifying the data format for the file. Valid\n\ - values are\n\ +@table @code\n\ +@item \"native\"\n\ +The format of the current machine.\n\ +\n\ +@item \"ieee-le\"\n\ +IEEE big endian.\n\ +\n\ +@item \"ieee-be\"\n\ +IEEE little endian.\n\ \n\ - native -- the format of the current machine (default)\n\ - ieee-be -- IEEE big endian\n\ - ieee-le -- IEEE little endian\n\ - vaxd -- VAX D floating format\n\ - vaxg -- VAX G floating format\n\ - cray -- Cray floating format\n\ +@item \"vaxd\"\n\ +VAX D floating format.\n\ +\n\ +@item \"vaxg\"\n\ +VAX G floating format.\n\ \n\ - however, conversions are currently only supported for\n\ - ieee-be and ieee-le formats.\n\ -\n\ +@item \"cray\"\n\ +Cray floating format.\n\ +@end table\n\ \n\ - DATA : matrix in which the data is stored\n\ +@noindent\n\ +Conversions are currently only supported for @code{\"ieee-be\"} and\n\ +@code{\"ieee-le\"} formats.\n\ \n\ - COUNT : number of elements read") +The data read from the file is returned in @var{val}, and the number of\n\ +values read is returned in @code{count}\n\ +@end deftypefn") { octave_value_list retval; @@ -1029,49 +1237,21 @@ } DEFUN (fwrite, args, , - "COUNT = fwrite (FILENUM, DATA [, PRECISION] [, SKIP] [, ARCH])\n\ -\n\ - Writes data to a file in binary form of size PRECISION\n\ -\n\ - FILENUM : file number from fopen\n\ -\n\ - DATA : matrix of elements to be written\n\ -\n\ - PRECISION : string specifying type of data to write, valid types are\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {@var{count} =} fwrite (@var{fid}, @var{data}, @var{precision}, @var{skip}, @var{arch})\n\ +Write data in binary form of type @var{precision} to the specified file\n\ +ID @var{fid}, returning the number of values successfully written to the\n\ +file.\n\ \n\ - char, char*1, integer*1, int8 -- character\n\ - schar, signed char -- signed character\n\ - uchar, unsigned char -- unsigned character (default)\n\ - short -- short integer\n\ - ushort, unsigned short -- unsigned short integer\n\ - int -- integer\n\ - uint, unsigned int -- unsigned integer\n\ - long -- long integer\n\ - ulong, unsigned long -- unsigned long integer\n\ - float, float32, real*4 -- single precision float\n\ - double, float64, real*8 -- double precision float\n\ - int16, integer*2 -- two byte integer\n\ - uint16 -- two byte unsigned integer\n\ - int32, integer*4 -- four byte integer\n\ - uint32 -- four byte unsigned integer\n\ +The argument @var{data} is a matrix of values that are to be written to\n\ +the file. The values are extracted in column-major order.\n\ \n\ - SKIP : number of bytes to skip before each element is written\n\ - (the default is 0)\n\ -\n\ - ARCH : string specifying the data format for the file. Valid\n\ - values are\n\ +The remaining arguments @var{precision}, @var{skip}, and @var{arch} are\n\ +optional, and are interpreted as described for @code{fread}.\n\ \n\ - native -- the format of the current machine (default)\n\ - ieee-le -- IEEE big endian\n\ - ieee-be -- IEEE little endian\n\ - vaxd -- VAX D floating format\n\ - vaxg -- VAX G floating format\n\ - cray -- Cray floating format\n\ -\n\ - however, conversions are currently only supported for ieee-be, and\n\ - ieee-le formats.\n\ -\n\ - COUNT : number of elements written") +The behavior of @code{fwrite} is undefined if the values in @var{data}\n\ +are too large to fit in the specified precision.\n\ +@end deftypefn") { octave_value retval = -1.0; @@ -1106,10 +1286,13 @@ } DEFUN (feof, args, , - "ERROR = feof (FILENUM)\n\ -\n\ - Returns a non zero value for an end of file condition for the\n\ - file specified by FILENUM from fopen") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} feof (@var{fid})\n\ +Return 1 if an end-of-file condition has been encountered for a given\n\ +file and 0 otherwise. Note that it will only return 1 if the end of the\n\ +file has already been encountered, not if the next read operation will\n\ +result in an end-of-file condition.\n\ +@end deftypefn") { double retval = -1.0; @@ -1129,10 +1312,13 @@ } DEFUN (ferror, args, , - "ERROR = ferror (FILENUM, [\"clear\"])\n\ -\n\ - Returns a non zero value for an error condition on the\n\ - file specified by FILENUM from fopen") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} ferror (@var{fid})\n\ +Return 1 if an error condition has been encountered for a given file\n\ +and 0 otherwise. Note that it will only return 1 if an error has\n\ +already been encountered, not if the next operation will result in an\n\ +error condition.\n\ +@end deftypefn") { octave_value_list retval; @@ -1265,8 +1451,14 @@ } DEFUN (tmpnam, args, , - "tmpnam (DIR, PREFIX)\n\ -Return unique temporary file name.") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} tmpnam ()\n\ +Return a unique temporary file name as a string.\n\ +\n\ +Since the named file is not opened, by @code{tmpnam}, it\n\ +is possible (though relatively unlikely) that it will not be available\n\ +by the time your program attempts to open it.\n\ +@end deftypefn") { octave_value retval; @@ -1371,22 +1563,54 @@ // this way for Matlab compatibility. DEFCONSTX ("SEEK_SET", SBV_SEEK_SET, -1.0, - "used with fseek to position file relative to the beginning"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} SEEK_SET\n\ +@defvrx {Built-in Variable} SEEK_CUR\n\ +@defvrx {Built-in Variable} SEEK_END\n\ +These variables may be used as the optional third argument for the\n\ +function @code{fseek}.\n\ +\n\ +@table @code\n\ +@item SEEK_SET\n\ +Position file relative to the beginning.\n\ +\n\ +@item SEEK_CUR\n\ +Position file relative to the current position.\n\ +\n\ +@item SEEK_END\n\ +used with fseek to position file relative to the end.\n\ +@end table\n\ +@end defvr"); DEFCONSTX ("SEEK_CUR", SBV_SEEK_CUR, 0.0, - "used with fseek to position file relative to the current position"); + "See SEEK_SET"); DEFCONSTX ("SEEK_END", SBV_SEEK_END, 1.0, - "used with fseek to position file relative to the end"); + "See SEEK_SET"); DEFCONSTX ("stdin", SBV_stdin, stdin_file, - "file number of the standard input stream"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} stdin\n\ +The standard input stream (file id 0). When Octave is used\n\ +interactively, this is filtered through the command line editing\n\ +functions.\n\ +@end defvr"); DEFCONSTX ("stdout", SBV_stdout, stdout_file, - "file number of the standard output stream"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} stdout\n\ +The standard output stream (file id 1). Data written to the\n\ +standard output is normally filtered through the pager.\n\ +@end defvr"); DEFCONSTX ("stderr", SBV_stderr, stderr_file, - "file number of the standard error stream"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} stderr\n\ +The standard error stream (file id 2). Even if paging is turned on,\n\ +the standard error is not sent to the pager. It is useful for error\n\ +messages and prompts.\n\ +@end defvr"); + } /*
--- a/src/input.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/input.cc Tue Nov 23 19:07:18 1999 +0000 @@ -589,10 +589,40 @@ } DEFUN (input, args, nargout, - "input (PROMPT [, S])\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} input (@var{prompt})\n\ +@deftypefnx {Built-in Function} {} input (@var{prompt}, \"s\")\n\ +Print a prompt and wait for user input. For example,\n\ +\n\ +@example\n\ +input (\"Pick a number, any number! \")\n\ +@end example\n\ +\n\ +@noindent\n\ +prints the prompt\n\ +\n\ +@example\n\ +Pick a number, any number!\n\ +@end example\n\ \n\ -Prompt user for input. If the second argument is present, return\n\ -value as a string.") +@noindent\n\ +and waits for the user to enter a value. The string entered by the user\n\ +is evaluated as an expression, so it may be a literal constant, a\n\ +variable name, or any other valid expression.\n\ +\n\ +Currently, @code{input} only returns one value, regardless of the number\n\ +of values produced by the evaluation of the expression.\n\ +\n\ +If you are only interested in getting a literal string value, you can\n\ +call @code{input} with the character string @code{\"s\"} as the second\n\ +argument. This tells Octave to return the string entered by the user\n\ +directly, without evaluating it first.\n\ +\n\ +Because there may be output waiting to be displayed by the pager, it is\n\ +a good idea to always call @code{fflush (stdout)} before calling\n\ +@code{input}. This will ensure that all pending output is written to\n\ +the screen before your prompt. @xref{Input and Output}.\n\ +@end deftypefn") { octave_value_list retval; @@ -613,9 +643,19 @@ } DEFUN (keyboard, args, , - "keyboard (PROMPT)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} keyboard (@var{prompt})\n\ +This function is normally used for simple debugging. When the\n\ +@code{keyboard} function is executed, Octave prints a prompt and waits\n\ +for user input. The input strings are then evaluated and the results\n\ +are printed. This makes it possible to examine the values of variables\n\ +within a function, and to assign new values to variables. No value is\n\ +returned from the @code{keyboard} function, and it continues to prompt\n\ +for input until the user types @samp{quit}, or @samp{exit}.\n\ \n\ -maybe help in debugging function files") +If @code{keyboard} is invoked without any arguments, a default prompt of\n\ +@samp{debug> } is used.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/load-save.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/load-save.cc Tue Nov 23 19:07:18 1999 +0000 @@ -1689,16 +1689,51 @@ } DEFUN_TEXT (load, args, nargout, - "load [-force] [-ascii] [-binary] [-mat-binary] file [pattern ...]\n\ + "-*- texinfo -*-\n\ +@deffn {Command} load options file v1 v2 @dots{}\n\ +Load the named variables from the file @var{file}. As with @code{save},\n\ +you may specify a list of variables and @code{load} will only extract\n\ +those variables with names that match. For example, to restore the\n\ +variables saved in the file @file{data}, use the command\n\ +\n\ +@example\n\ +load data\n\ +@end example\n\ \n\ -Load variables from a file.\n\ +Octave will refuse to overwrite existing variables unless you use the\n\ +option @samp{-force}.\n\ +\n\ +If a variable that is not marked as global is loaded from a file when a\n\ +global symbol with the same name already exists, it is loaded in the\n\ +global symbol table. Also, if a variable is marked as global in a file\n\ +and a local symbol exists, the local symbol is moved to the global\n\ +symbol table and given the value from the file. Since it seems that\n\ +both of these cases are likely to be the result of some sort of error,\n\ +they will generate warnings.\n\ \n\ -If no argument is supplied to select a format, load tries to read the\n\ -named file as an Octave binary, then as a .mat file, and then as an\n\ -Octave text file.\n\ +The @code{load} command can read data stored in Octave's text and\n\ +binary formats, and @sc{Matlab}'s binary format. It will automatically\n\ +detect the type of file and do conversion from different floating point\n\ +formats (currently only IEEE big and little endian, though other formats\n\ +may added in the future).\n\ +\n\ +Valid options for @code{load} are listed in the following table.\n\ \n\ -If the option -force is given, variables with the same names as those\n\ -found in the file will be replaced with the values read from the file.") +@table @code\n\ +@item -force\n\ +Force variables currently in memory to be overwritten by variables with\n\ +the same name found in the file.\n\ +\n\ +@item -ascii\n\ +Force Octave to assume the file is in Octave's text format.\n\ +\n\ +@item -binary\n\ +Force Octave to assume the file is in Octave's binary format.\n\ +\n\ +@item -mat-binary\n\ +Force Octave to assume the file is in @sc{Matlab}'s binary format.\n\ +@end table\n\ +@end deffn") { octave_value_list retval; @@ -2522,10 +2557,67 @@ } DEFUN_TEXT (save, args, , - "save [-append] [-ascii] [-binary] [-float-binary] [-mat-binary] \n\ - [-save-builtins] file [pattern ...]\n\ + "-*- texinfo -*-\n\ +@deffn {Command} save options file v1 v2 @dots{}\n\ +Save the named variables @var{v1}, @var{v2}, @dots{} in the file\n\ +@var{file}. The special filename @samp{-} can be used to write the\n\ +output to your terminal. If no variable names are listed, Octave saves\n\ +all the variables in the current scope. Valid options for the\n\ +@code{save} command are listed in the following table. Options that\n\ +modify the output format override the format specified by the built-in\n\ +variable @code{default_save_format}.\n\ +\n\ +@table @code\n\ +@item -ascii\n\ +Save the data in Octave's text data format.\n\ +\n\ +@item -binary\n\ +Save the data in Octave's binary data format.\n\ +\n\ +@item -float-binary\n\ +Save the data in Octave's binary data format but only using single\n\ +precision. You should use this format only if you know that all the\n\ +values to be saved can be represented in single precision.\n\ +\n\ +@item -mat-binary\n\ +Save the data in @sc{Matlab}'s binary data format.\n\ +\n\ +@item -save-builtins\n\ +Force Octave to save the values of built-in variables too. By default,\n\ +Octave does not save built-in variables.\n\ +@end table\n\ \n\ -save variables in a file") +The list of variables to save may include wildcard patterns containing\n\ +the following special characters:\n\ +@table @code\n\ +@item ?\n\ +Match any single character.\n\ +\n\ +@item *\n\ +Match zero or more characters.\n\ +\n\ +@item [ @var{list} ]\n\ +Match the list of characters specified by @var{list}. If the first\n\ +character is @code{!} or @code{^}, match all characters except those\n\ +specified by @var{list}. For example, the pattern @samp{[a-zA-Z]} will\n\ +match all lower and upper case alphabetic characters. \n\ +@end table\n\ +\n\ +Except when using the @sc{Matlab} binary data file format, saving global\n\ +variables also saves the global status of the variable, so that if it is\n\ +restored at a later time using @samp{load}, it will be restored as a\n\ +global variable.\n\ +\n\ +The command\n\ +\n\ +@example\n\ +save -binary data a b*\n\ +@end example\n\ +\n\ +@noindent\n\ +saves the variable @samp{a} and all variables beginning with @samp{b} to\n\ +the file @file{data} in Octave's binary format.\n\ +@end deffn") { octave_value_list retval; @@ -2750,14 +2842,29 @@ symbols_of_load_save (void) { DEFVAR (crash_dumps_octave_core, 1.0, crash_dumps_octave_core, - "write octave-core file if Octave crashes or is killed by a signal"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} crash_dumps_octave_core\n\ +If this variable is set to a nonzero value, Octave tries to save all\n\ +current variables the the file \"octave-core\" if it crashes or receives a\n\ +hangup, terminate or similar signal. The default value is 1.\n\ +@end defvr"); DEFVAR (default_save_format, "ascii", default_save_format, - "default format for files created with save, may be one of\n\ -\"binary\", \"text\", or \"mat-binary\""); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} default_save_format\n\ +This variable specifies the default format for the @code{save} command.\n\ +It should have one of the following values: @code{\"ascii\"},\n\ +@code{\"binary\"}, @code{float-binary}, or @code{\"mat-binary\"}. The\n\ +initial default save format is Octave's text format.\n\ +@end defvr"); DEFVAR (save_precision, 15.0, save_precision, - "number of significant figures kept by the ASCII save command"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} save_precision\n\ +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/ov.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/ov.cc Tue Nov 23 19:07:18 1999 +0000 @@ -1567,7 +1567,12 @@ @end defvr"); DEFVAR (print_answer_id_name, 1.0, print_answer_id_name, - "set output style to print `var_name = ...'"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} print_answer_id_name\n\ +If the value of @code{print_answer_id_name} is nonzero, variable\n\ +names are printed along with the result. Otherwise, only the result\n\ +values are printed. The default value is 1.\n\ +@end defvr"); DEFVAR (propagate_empty_matrices, 1.0, propagate_empty_matrices, "-*- texinfo -*-\n\
--- a/src/pager.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/pager.cc Tue Nov 23 19:07:18 1999 +0000 @@ -429,10 +429,13 @@ } DEFUN_TEXT (more, args, , - "more on\n\ -more off\n\ -\n\ -Turn output pagination on or off.") + "-*- texinfo -*-\n\ +@deffn {Command} more\n\ +@deffnx {Command} more on\n\ +@deffnx {Command} more off\n\ +Turn output pagination on or off. Without an argument, @code{more}\n\ +toggles the current state.\n\ +@end deffn") { octave_value_list retval; @@ -523,13 +526,36 @@ symbols_of_pager (void) { DEFVAR (PAGER, default_pager (), pager_binary, - "path to pager binary"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} PAGER\n\ +The default value is normally @code{\"less\"}, @code{\"more\"}, or\n\ +@code{\"pg\"}, depending on what programs are installed on your system.\n\ +@xref{Installation}.\n\ +\n\ +When running interactively, Octave sends any output intended for your\n\ +terminal that is more than one screen long to the program named by the\n\ +value of the variable @code{PAGER}.\n\ +@end defvr"); DEFVAR (page_output_immediately, 0.0, page_output_immediately, - "if paging output, start sending it as soon as it is available"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} page_output_immediately\n\ +If the value of @code{page_output_immediately} is nonzero, Octave sends\n\ +output to the pager as soon as it is available. Otherwise, Octave\n\ +buffers its output and waits until just before the prompt is printed to\n\ +flush it to the pager. The default value is 0.\n\ +@end defvr"); DEFVAR (page_screen_output, 1.0, page_screen_output, - "if possible, send output intended for the screen through the pager"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} page_screen_output\n\ +If the value of @code{page_screen_output} is nonzero, all output\n\ +intended for the screen that is longer than one page is sent through a\n\ +pager. This allows you to view one screenful at a time. Some pagers\n\ +(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 Sun Nov 21 17:31:10 1999 +0000 +++ b/src/pr-output.cc Tue Nov 23 19:07:18 1999 +0000 @@ -1649,7 +1649,20 @@ } DEFUN (disp, args, , - "disp (X): display value without name tag") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} disp (@var{x})\n\ +Display the value of @var{x}. For example,\n\ +\n\ +@example\n\ +disp (\"The value of pi is:\"), disp (pi)\n\ +\n\ + @print{} the value of pi is:\n\ + @print{} 3.1416\n\ +@end example\n\ +\n\ +@noindent\n\ +Note that the output from @code{disp} always ends with a newline.\n\ +@end deftypefn") { octave_value_list retval; @@ -1808,9 +1821,93 @@ } DEFUN_TEXT (format, args, , - "format [style]\n\ + "-*- texinfo -*-\n\ +@deffn {Command} format options\n\ +Control the format of the output produced by @code{disp} and Octave's\n\ +normal echoing mechanism. Valid options are listed in the following\n\ +table.\n\ +\n\ +@table @code\n\ +@item short\n\ +Octave will try to print numbers with at\n\ +least 3 significant figures within a field that is a maximum of 8\n\ +characters wide.\n\ +\n\ +If Octave is unable to format a matrix so that columns line up on the\n\ +decimal point and all the numbers fit within the maximum field width,\n\ +it switches to an @samp{e} format.\n\ +\n\ +@item long\n\ +Octave will try to print numbers with at least 15 significant figures\n\ +within a field that is a maximum of 24 characters wide.\n\ +\n\ +As will the @samp{short} format, Octave will switch to an @samp{e}\n\ +format if it is unable to format a matrix so that columns line up on the\n\ +decimal point and all the numbers fit within the maximum field width.\n\ +\n\ +@item long e\n\ +@itemx short e\n\ +The same as @samp{format long} or @samp{format short} but always display\n\ +output with an @samp{e} format. For example, with the @samp{short e}\n\ +format, pi is displayed as @code{3.14e+00}.\n\ +\n\ +@item long E\n\ +@itemx short E\n\ +The same as @samp{format long e} or @samp{format short e} but always\n\ +display output with an uppercase @samp{E} format. For example, with\n\ +the @samp{long E} format, pi is displayed as\n\ +@code{3.14159265358979E+00}.\n\ +\n\ +@item free\n\ +@itemx none\n\ +Print output in free format, without trying to line up columns of\n\ +matrices on the decimal point. This also causes complex numbers to be\n\ +formatted like this @samp{(0.604194, 0.607088)} instead of like this\n\ +@samp{0.60419 + 0.60709i}.\n\ \n\ -set output formatting style") +@item bank\n\ +Print in a fixed format with two places to the right of the decimal\n\ +point.\n\ +\n\ +@item +\n\ +Print a @samp{+} symbol for nonzero matrix elements and a space for zero\n\ +matrix elements. This format can be very useful for examining the\n\ +structure of a large matrix.\n\ +\n\ +@item hex\n\ +Print the hexadecimal representation numbers as they are stored in\n\ +memory. For example, on a workstation which stores 8 byte real values\n\ +in IEEE format with the least significant byte first, the value of\n\ +@code{pi} when printed in @code{hex} format is @code{400921fb54442d18}.\n\ +This format only works for numeric values.\n\ +\n\ +@item bit\n\ +Print the bit representation of numbers as stored in memory.\n\ +For example, the value of @code{pi} is\n\ +\n\ +@example\n\ +@group\n\ +01000000000010010010000111111011\n\ +01010100010001000010110100011000\n\ +@end group\n\ +@end example\n\ +\n\ +(shown here in two 32 bit sections for typesetting purposes) when\n\ +printed in bit format on a workstation which stores 8 byte real values\n\ +in IEEE format with the least significant byte first. This format only\n\ +works for numeric types.\n\ +@end table\n\ +\n\ +By default, Octave will try to print numbers with at least 5 significant\n\ +figures within a field that is a maximum of 10 characters wide.\n\ +\n\ +If Octave is unable to format a matrix so that columns line up on the\n\ +decimal point and all the numbers fit within the maximum field width,\n\ +it switches to an @samp{e} format.\n\ +\n\ +If @code{format} is invoked without any options, the default format\n\ +state is restored.\n\ +@end deffn") { octave_value_list retval;
--- a/src/sysdep.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/sysdep.cc Tue Nov 23 19:07:18 1999 +0000 @@ -395,8 +395,21 @@ return retval; } +// XXX FIXME XXX -- perhaps kbhit should also be able to print a prompt? + DEFUN (kbhit, , , - "kbhit: get a single character from the terminal") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} kbhit ()\n\ +Read a single keystroke from the keyboard. For example,\n\ +\n\ +@example\n\ +x = kbhit ();\n\ +@end example\n\ +\n\ +@noindent\n\ +will set @var{x} to the next character typed at the keyboard as soon as\n\ +it is typed.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/variables.cc Sun Nov 21 17:31:10 1999 +0000 +++ b/src/variables.cc Tue Nov 23 19:07:18 1999 +0000 @@ -1308,7 +1308,18 @@ symbols_of_variables (void) { DEFVAR (ans, , 0, - ""); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} ans\n\ +This variable holds the most recently computed result that was not\n\ +explicitly assigned to a variable. For example, after the expression\n\ +\n\ +@example\n\ +3^2 + 4^2\n\ +@end example\n\ +\n\ +@noindent\n\ +is evaluated, the value of @code{ans} is 25.\n\ +@end defvr"); DEFVAR (ignore_function_time_stamp, "system", ignore_function_time_stamp, "-*- texinfo -*-\n\