Mercurial > octave
changeset 2653:e7908588548a
[project @ 1997-02-01 16:53:52 by jwe]
line wrap: on
line diff
--- a/doc/interpreter/Makefile.in Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/Makefile.in Sat Feb 01 16:57:10 1997 +0000 @@ -20,16 +20,14 @@ SOURCES = -TEXINFO = amuse.texi arith.texi audio.texi bugs.texi \ +TEXINFO = amuse.texi arith.texi audio.texi basics.texi bugs.texi \ control.texi cp-idx.texi diffeq.texi emacs.texi expr.texi \ - extend.texi fn-idx.texi func.texi gnuinfo.texi help.texi \ - history.texi hsuser.texi image.texi in-idx.texi install.texi \ - intro.texi invoke.texi io.texi linalg.texi \ - matrix.texi nonlin.texi octave.texi op-idx.texi optim.texi \ - plot.texi poly.texi preface.texi program.texi quad.texi \ - rd-idx.texi rluser.texi set.texi signal.texi special.texi \ - stats.texi stmt.texi strings.texi system.texi var.texi \ - vr-idx.texi + extend.texi fn-idx.texi func.texi image.texi install.texi \ + intro.texi invoke.texi io.texi linalg.texi matrix.texi \ + nonlin.texi octave.texi op-idx.texi optim.texi plot.texi \ + poly.texi preface.texi program.texi quad.texi set.texi \ + signal.texi special.texi stats.texi stmt.texi strings.texi \ + system.texi var.texi vr-idx.texi FORMATTED = octave.dvi octave.ps octave.info octave.info octave.info-[0-9]*
--- a/doc/interpreter/arith.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/arith.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Arithmetic, Linear Algebra, Built-in Variables, Top +@node Arithmetic, Linear Algebra, String Functions, Top @chapter Arithmetic Unless otherwise noted, all of the functions described in this chapter @@ -30,9 +30,9 @@ complex, return @code{ceil (real (@var{x})) + ceil (imag (@var{x})) * I}. @end deftypefn -@deftypefn {Mapping Function} {} floor (@var{x}) -Return the largest integer not greater than @var{x}. If @var{x} is -complex, return @code{floor (real (@var{x})) + floor (imag (@var{x})) * I}. +@deftypefn {Mapping Function} {} exp (@var{x}) +Compute the exponential of @var{x}. To compute the matrix exponential, +see @ref{Linear Algebra}. @end deftypefn @deftypefn {Mapping Function} {} fix (@var{x}) @@ -40,35 +40,9 @@ @code{fix (real (@var{x})) + fix (imag (@var{x})) * I}. @end deftypefn -@deftypefn {Mapping Function} {} round (@var{x}) -Return the integer nearest to @var{x}. If @var{x} is complex, return -@code{round (real (@var{x})) + round (imag (@var{x})) * I}. -@end deftypefn - -@deftypefn {Mapping Function} {} sign (@var{x}) -Compute the @dfn{signum} function, which is defined as -@iftex -@tex -$$ -{\rm sign} (@var{x}) = \cases{1,&$x>0$;\cr 0,&$x=0$;\cr -1,&$x<0$.\cr} -$$ -@end tex -@end iftex -@ifinfo - -@example - -1, x < 0; -sign (x) = 0, x = 0; - 1, x > 0. -@end example -@end ifinfo - -For complex arguments, @code{sign} returns @code{x ./ abs (@var{x})}. -@end deftypefn - -@deftypefn {Mapping Function} {} exp (@var{x}) -Compute the exponential of @var{x}. To compute the matrix exponential, -see @ref{Linear Algebra}. +@deftypefn {Mapping Function} {} floor (@var{x}) +Return the largest integer not greater than @var{x}. If @var{x} is +complex, return @code{floor (real (@var{x})) + floor (imag (@var{x})) * I}. @end deftypefn @deftypefn {Mapping Function} {} gcd (@var{x}, @code{...}) @@ -115,6 +89,10 @@ see @ref{Linear Algebra}. @end deftypefn +@deftypefn {Mapping Function} {} log10 (@var{x}) +Compute the base-10 logarithm of @var{x}. +@end deftypefn + @deftypefn {Mapping Function} {@var{y} =} log2 (@var{x}) @deftypefnx {Mapping Function} {[@var{f}, @var{e}]} log2 (@var{x}) Compute the base-2 logarithm of @var{x}. With two outputs, returns @@ -129,8 +107,37 @@ @end ifinfo @end deftypefn -@deftypefn {Mapping Function} {} log10 (@var{x}) -Compute the base-10 logarithm of @var{x}. +@deftypefn {Loadable Function} {} max (@var{x}) +For a vector argument, return the maximum value. For a matrix argument, +return the maximum value from each column, as a row vector. Thus, + +@example +max (max (@var{x})) +@end example + +@noindent +returns the largest element of @var{x}. + +For complex arguments, the magnitude of the elements are used for +comparison. +@end deftypefn + +@deftypefn {Loadable Function} {} min (@var{x}) +Like @code{max}, but return the minimum value. +@end deftypefn + +@deftypefn {Function File} {} nextpow2 (@var{x}) +If @var{x} is a scalar, returns the first integer @var{n} such that +@iftex +@tex + $2^n \ge |x|$. +@end tex +@end iftex +@ifinfo + 2^n >= abs (x). +@end ifinfo + +If @var{x} is a vector, return @code{nextpow2 (length (@var{x}))}. @end deftypefn @deftypefn {Mapping Function} {} pow2 (@var{x}) @@ -155,44 +162,6 @@ @end ifinfo @end deftypefn -@deftypefn {Function File} {} nextpow2 (@var{x}) -If @var{x} is a scalar, returns the first integer @var{n} such that -@iftex -@tex - $2^n \ge |x|$. -@end tex -@end iftex -@ifinfo - 2^n >= abs (x). -@end ifinfo - -If @var{x} is a vector, return @code{nextpow2 (length (@var{x}))}. -@end deftypefn - -@deftypefn {Mapping Function} {} sqrt (@var{x}) -Compute the square root of @var{x}. To compute the matrix square root, -see @ref{Linear Algebra}. -@end deftypefn - -@deftypefn {Loadable Function} {} max (@var{x}) -For a vector argument, return the maximum value. For a matrix argument, -return the maximum value from each column, as a row vector. Thus, - -@example -max (max (@var{x})) -@end example - -@noindent -returns the largest element of @var{x}. - -For complex arguments, the magnitude of the elements are used for -comparison. -@end deftypefn - -@deftypefn {Loadable Function} {} min (@var{x}) -Like @code{max}, but return the minimum value. -@end deftypefn - @deftypefn {Mapping Function} {} rem (@var{x}, @var{y}) Return the remainder of @code{@var{x} / @var{y}}, computed using the expression @@ -205,6 +174,38 @@ agree, or if either of the arguments is complex. @end deftypefn +@deftypefn {Mapping Function} {} round (@var{x}) +Return the integer nearest to @var{x}. If @var{x} is complex, return +@code{round (real (@var{x})) + round (imag (@var{x})) * I}. +@end deftypefn + +@deftypefn {Mapping Function} {} sign (@var{x}) +Compute the @dfn{signum} function, which is defined as +@iftex +@tex +$$ +{\rm sign} (@var{x}) = \cases{1,&$x>0$;\cr 0,&$x=0$;\cr -1,&$x<0$.\cr} +$$ +@end tex +@end iftex +@ifinfo + +@example + -1, x < 0; +sign (x) = 0, x = 0; + 1, x > 0. +@end example +@end ifinfo + +For complex arguments, @code{sign} returns @code{x ./ abs (@var{x})}. +@end deftypefn + +@deftypefn {Mapping Function} {} sqrt (@var{x}) +Compute the square root of @var{x}. If @var{x} is negative, a complex +result is returned. To compute the matrix square root, see +@ref{Linear Algebra}. +@end deftypefn + @deftypefn {Mapping Function} {} xor (@var{x}, @var{y}) Return the `exclusive or' of the entries of @var{x} and @var{y}. For boolean expressions @var{x} and @var{y}, @@ -287,6 +288,7 @@ @example @group sin ([1, 2; 3, 4]) + @result{} 0.84147 0.90930 0.14112 -0.75680 @end group @@ -328,6 +330,7 @@ @example @group cumsum ([1, 2; 3, 4]) + @result{} 1 2 4 6 @end group @@ -340,6 +343,7 @@ @example @group cumprod ([1, 2; 3, 4]) + @result{} 1 2 3 8 @end group
--- a/doc/interpreter/audio.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/audio.texi Sat Feb 01 16:57:10 1997 +0000 @@ -3,7 +3,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Audio Processing, Input and Output, Image Processing, Top +@node Audio Processing, System Utilities, Image Processing, Top @chapter Audio Processing Octave provides a few functions for dealing with audio data. An audio
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/basics.texi Sat Feb 01 16:57:10 1997 +0000 @@ -0,0 +1,530 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Basics, Expressions, Invoking Octave, Top +@chapter Basics + +@menu +* Comments:: +* Executable Octave Programs:: +* Errors:: +* Help:: +* Command Line Editing:: +* Command History Functions:: +@end menu + +@node Comments, Executable Octave Programs, Basics, Basics +@section Comments in Octave Programs +@cindex @samp{#} +@cindex @samp{%} +@cindex comments +@cindex use of comments +@cindex documenting Octave programs +@cindex programs + +A @dfn{comment} is some text that is included in a program for the sake +of human readers, and that is not really part of the program. Comments +can explain what the program does, and how it works. Nearly all +programming languages have provisions for comments, because programs are +typically hard to understand without them. + +In the Octave language, a comment starts with either the sharp sign +character, @samp{#}, or the percent symbol @samp{%} and continues to the +end of the line. The Octave interpreter ignores the rest of a +line following a sharp sign or percent symbol. For example, we could +have put the following into the function @code{f}: + +@smallexample +function xdot = f (x, t) + +# usage: f (x, t) +# +# This function defines the right-hand-side functions for a set of +# nonlinear differential equations. + + r = 0.25 + + and so on... + +endfunction +@end smallexample + +The @code{help} command (@pxref{Help}) is able to find the first block +of comments in a function (even those that are composed directly on the +command line). This means that users of Octave can use the same +commands to get help for built-in functions, and for functions that you +have defined. For example, after defining the function @code{f} above, +the command + +@example +help f +@end example + +@noindent +produces the output + +@smallexample + usage: f (x, t) + + This function defines the right-hand-side functions for a set of + nonlinear differential equations. +@end smallexample + +Although it is possible to put comment lines into keyboard-composed +throw-away Octave programs, it usually isn't very useful, because the +purpose of a comment is to help you or another person understand the +program at a later time. + +@node Executable Octave Programs, Errors, Comments, Basics +@section Executable Octave Programs +@cindex executable scripts +@cindex scripts +@cindex self contained programs +@cindex program, self contained +@cindex @samp{#!} + +Once you have learned Octave, you may want to write self-contained +Octave scripts, using the @samp{#!} script mechanism. You can do this +on GNU systems and on many Unix systems @footnote{The @samp{#!} +mechanism works on Unix systems derived from Berkeley Unix, System V +Release 4, and some System V Release 3 systems.} + +For example, you could create a text file named @file{hello}, containing +the following lines: + +@example +@group +#! @value{OCTAVEHOME}/bin/octave -qf + +# a sample Octave program +printf ("Hello, world!\n"); +@end group +@end example + +@noindent +After making this file executable (with the @code{chmod} command), you +can simply type: + +@example +hello +@end example + +@noindent +at the shell, and the system will arrange to run Octave as if you had +typed: + +@example +octave hello +@end example + +The line beginning with @samp{#!} lists the full file name of an +interpreter to be run, and an optional initial command line argument to +pass to that interpreter. The operating system then runs the +interpreter with the given argument and the full argument list of the +executed program. The first argument in the list is the full file name +of the Octave program. The rest of the argument list will either be +options to Octave, or data files, or both. The @code{-qf} option is +usually specified in stand-alone Octave programs to prevent them from +printing the normal startup message, and to keep them from behaving +differently depending on the contents of a particular user's +@file{~/.octaverc} file. @xref{Invoking Octave}. Note that some +operating systems may place a limit on the number of characters that are +recognized after @samp{#!}. + +Self-contained Octave scripts are useful when you want to write a +program which users can invoke without knowing that the program is +written in the Octave language. + +If you invoke an executable Octave script with command line arguments, +the arguments are available in the built-in variable @var{argv}. +@xref{Command Line Options}. For example, the following program will +reproduce the command line that is used to execute it. + +@example +@group +#! @value{OCTAVEHOME}/bin/octave -qf + +printf ("%s", program_name); +for i = 1:nargin + printf (" %s", argv(i,:)); +endfor +printf ("\n"); +@end group +@end example + +@node Errors, Help, Executable Octave Programs, Basics +@section Errors + +There are two classes of errors that Octave produces when it encounters +input that it is unable to understand +an action. + +A @dfn{parse error} occurs if Octave cannot understand something you +have typed. For example, if you misspell a keyword, + +@example +octave:13> functon y = f (x) y = x^2; endfunction +@end example + +@noindent +Octave will respond immediately with a message like this: + +@example +parse error: + + functon y = f (x) y = x^2; endfunction + ^ +@end example + +@noindent +For most parse errors, Octave uses a caret (@samp{^}) to mark the point +on the line where it was unable to make sense of your input. In this +case, Octave generated an error message because the keyword +@code{function} was misspelled. Instead of seeing @samp{function f}, +Octave saw two consecutive variable names, which is invalid in this +context. It marked the error at the @code{y} because the first name by +itself was accepted as valid input. + +Another class of error message occurs occurs at evaluation time. These +errors are called @dfn{run-time errors}, or sometimes +@dfn{evaluation errors} because they occur when your program is being +@dfn{run}, or @dfn{evaluated}. For example, if after correcting the +mistake in the previous function definition, you type + +@example +octave:13> f () +@end example + +@noindent +Octave will respond with + +@example +@group +error: `x' undefined near line 1 column 24 +error: evaluating expression near line 1, column 24 +error: evaluating assignment expression near line 1, column 22 +error: called from `f' +@end group +@end example + +This error message has several parts, and gives you quite a bit of +information to help you locate the source of the error. The messages +are generated from the point of the innermost error, and provide a +traceback of enclosing expressions and function calls. + +In the example above, the first line indicates that a variable named +@samp{x} was found to be undefined near line 1 and column 24 of some +function or expression. For errors occurring within functions, lines +from the beginning of the file containing the function definition. For +errors occurring at the top level, the line number indicates the input +line number, which is usually displayed in the prompt string. + +The second and third lines in the example indicate that the error +occurred within an assignment expression, and the last line of the error +message indicates that the error occurred within the function @samp{f}. +If the function @samp{f} had been called from another function, for +example, @samp{g}, the list of errors would have ended with one more +line: + +@example +error: called from `g' +@end example + +These lists of function calls usually make it fairly easy to trace the +path your program took before the error occurred, and to correct the +error before trying again. + +@node Help, Command Line Editing, Errors, Basics +@section Help + +@deffn {Command} help +Octave's @code{help} command can be used to print brief usage-style +messages, or to display information directly from an on-line version of +the printed manual, using the GNU Info browser. If invoked without any +arguments, @code{help} prints a list of all the available operators, +functions, and built-in variables. If the first argument is @code{-i}, +the @code{help} command searches the index of the on-line version of +this manual for the given topics. + +For example, the command + +@example +help help +@end example + +@noindent +prints a short message describing the @code{help} command, and + +@example +help -i help +@end example + +@noindent +starts the GNU Info browser at this node in the on-line version of the +manual. +@end deffn + +The help command can give you information about operators, but not the +comma and semicolons that are used as command separators. To get help +for those, you must type @code{help comma} or @code{help semicolon}. + +@defvr {Built-in Variable} INFO_FILE +The variable @code{INFO_FILE} names the location of the Octave info file. +The default value is @code{"@value{OCTAVEHOME}/info/octave.info"}. +@end defvr + +@defvr {Built-in Variable} INFO_PROGRAM +The variable @code{INFO_PROGRAM} names the info program to run. Its +initial value is +@code{@value{OCTAVEHOME}/libexec/octave/VERSION/exec/ARCH/info}, but +that value can be overridden by the environment variable +@code{OCTAVE_INFO_PROGRAM}, or the command line argument +@code{--info-program NAME}, or by setting the value of +@code{INFO_PROGRAM} in a startup script. +@end defvr + +@defvr {Built-in Variable} suppress_verbose_help_message +If the value of @code{suppress_verbose_help_message} is nonzero, Octave +will not add additional help information to the end of the output from +the @code{help} command and usage messages for built-in commands. +@end defvr + +@node Command Line Editing, Command History Functions, Help, Basics +@section Command Line Editing + +@defvr {Built-in Variable} PS1 +The primary prompt string. When executing interactively, Octave +displays the primary prompt @code{PS1} when it is ready to read a +command. Octave allows the prompt to be customized by inserting a +number of backslash-escaped special characters that are decoded as +follows: + +@table @samp +@item \t +The time. +@item \d +The date. +@item \n +Begins a new line by printing the equivalent of a carriage return +followed by a line feed. +@item \s +The name of the program (usually just @code{octave}). +@item \w +The current working directory. +@item \W +The basename of the current working directory. +@item \u +The username of the current user. +@item \h +The hostname. +@item \H +The hostname, up to the first `.'. +@item \# +The command number of this command, counting from when Octave starts. +@item \! +The history number of this command. This differs from @samp{\#} by the +number of commands in the history list when Octave starts. +@item \$ +If the effective UID is 0, a #, otherwise a $. +@item \nnn +The character whose character code in octal is @samp{nnn}. +@item \\ +A backslash. +@end table + +The default value of @code{PS1} is @code{"\s:\#> "}. To change it, use a +command like + +@example +octave:13> PS1 = "\\u@@\\H> " +@end example + +@noindent +which will result in the prompt @samp{boris@@kremvax> } for the user +@samp{boris} logged in on the host @samp{kremvax.kgb.su}. Note that two +backslashes are required to enter a backslash into a string. +@xref{String Constants}. +@end defvr + +@defvr {Built-in Variable} PS2 +The secondary prompt string, which is printed when Octave is +expecting additional input to complete a command. For example, when +defining a function over several lines, Octave will print the value of +@code{PS1} at the beginning of each line after the first. Octave allows +@code{PS2} to be customized in the same way as @code{PS1}. The default +value of @code{PS2} is @code{"> "}. +@end defvr + +@defvr {Built-in Variable} PS4 +If Octave is invoked with the @code{--echo-input} option, the value of +@code{PS4} is printed before each line of input that is echoed. Octave +allows @code{PS4} to be customized in the same way as @code{PS1}. The +default value of @code{PS4} is @code{"+ "}. @xref{Invoking Octave}, for +a description of @code{--echo-input}. +@end defvr + +@defvr {Built-in Variable} completion_append_char +The value of @code{completion_append_char} is used as the character to +append to successful command-line completion attempts. The default +value is @code{" "} (a single space). +@end defvr + +@node Command History Functions, , Command Line Editing, Basics +@section Command History Functions + +Octave provides three functions for viewing, editing, and re-running +chunks of commands from the history list. + +@deffn {Command} history options +If invoked with no arguments, @code{history} displays a list of commands +that you have executed. Valid options are: + +@table @code +@item -w file +Write the current history to the named file. If the name is omitted, +use the default history file (normally @file{~/.octave_hist}). + +@item -r file +Read the named file, replacing the current history list with its +contents. If the name is omitted, use the default history file +(normally @file{~/.octave_hist}). + +@item N +Only display the most recent @code{N} lines of history. + +@item -q +Don't number the displayed lines of history. This is useful for cutting +and pasting commands if you are using the X Window System. +@end table + +For example, to display the five most recent commands that you have +typed without displaying line numbers, use the command +@samp{history -q 5}. +@end deffn + +@deffn {Command} edit_history options +If invoked with no arguments, @code{edit_history} allows you to edit the +history list using the editor named by the variable @code{EDITOR}. The +commands to be edited are first copied to a temporary file. When you +exit the editor, Octave executes the commands that remain in the file. +It is often more convenient to use @code{edit_history} to define functions +rather than attempting to enter them directly on the command line. +By default, the block of commands is executed as soon as you exit the +editor. To avoid executing any commands, simply delete all the lines +from the buffer before exiting the editor. + +The @code{edit_history} command takes two optional arguments specifying +the history numbers of first and last commands to edit. For example, +the command + +@example +edit_history 13 +@end example + +@noindent +extracts all the commands from the 13th through the last in the history +list. The command + +@example +edit_history 13 169 +@end example + +@noindent +only extracts commands 13 through 169. Specifying a larger number for +the first command than the last command reverses the list of commands +before placing them in the buffer to be edited. If both arguments are +omitted, the previous command in the history list is used. +@end deffn + +@defvr {Built-in Variable} EDITOR +A string naming the editor to use with the @code{edit_history} command. +If the environment variable @code{EDITOR} is set when Octave starts, its +value is used as the default. Otherwise, @code{EDITOR} is set to +@code{"vi"}. +@end defvr + +@deffn {Command} run_history +Similar to @code{edit_history}, except that the editor is not invoked, +and the commands are simply executed as they appear in the history list. +@end deffn + +@defvr {Built-in Variable} history_file +This variable specifies the name of the file used to store command +history. The default value is @code{"~/.octave_hist"}, but may be +overridden by the environment variable @code{OCTAVE_HISTFILE}. +@end defvr + +@defvr {Built-in Variable} history_size +This variable specifies how many entries to store in the history file. +The default value is @code{1024}, but may be overridden by the +environment variable @code{OCTAVE_HISTSIZE}. +@end defvr + +@defvr {Built-in Variable} saving_history +If the value of @code{saving_history} is @code{"true"}, command entered +on the command line are saved in the file specified by the variable +@code{history_file}. +@end defvr + +@deffn {Command} diary +The @code{diary} command allows you to create a list of all commands +@emph{and} the output they produce, mixed together just as you see them +on your terminal. + +For example, the command + +@example +diary on +@end example + +@noindent +tells Octave to start recording your session in a file called +@file{diary} in your current working directory. To give Octave the name +of the file write to, use the a command like + +@example +diary my-diary.txt +@end example + +@noindent +Then Octave will write all of your commands to the file +@file{my-diary.txt}. + +To stop recording your session, use the command + +@example +diary off +@end example + +@noindent +Without any arguments, @code{diary} toggles the current diary state. +@end deffn + +@deffn {Command} echo options +Control whether commands are displayed as they are executed. Valid +options are: + +@table @code +@item on +Enable echoing of commands as they are executed in script files. + +@item off +Disable echoing of commands as they are executed in script files. + +@item on all +Enable echoing of commands as they are executed in script files and +functions. + +@item off all +Disable echoing of commands as they are executed in script files and +functions. +@end table + +@noindent +If invoked without any arguments, @code{echo} toggles the current echo +state. +@end deffn + +@defvr {Built-in Variable} echo_executing_commands +@end defvr
--- a/doc/interpreter/bugs.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/bugs.texi Sat Feb 01 16:57:10 1997 +0000 @@ -6,7 +6,7 @@ @c in the Octave distribution, as well as in the Octave manual. @ifclear BUGSONLY -@node Trouble, Command Line Editing, Installation, Top +@node Trouble, Copying, Installation, Top @appendix Known Causes of Trouble with Octave @end ifclear @@ -20,7 +20,7 @@ modify it freely as long as you preserve this copyright notice and permission notice. -@node Trouble, Trouble, Trouble, (dir) +@node Trouble, , Trouble @chapter Known Causes of Trouble with Octave @end ifset
--- a/doc/interpreter/control.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/control.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Control Theory, Signal Processing, Quadrature, Top +@node Control Theory, Signal Processing, Polynomial Manipulations, Top @chapter Control Theory @deftypefn {Function File} {} abcddim (@var{a}, @var{b}, @var{c}, @var{d})
--- a/doc/interpreter/diffeq.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/diffeq.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Differential Equations, Optimization, Nonlinear Equations, Top +@node Differential Equations, Optimization, Quadrature, Top @chapter Differential Equations Octave has two built-in functions for solving differential equations.
--- a/doc/interpreter/emacs.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/emacs.texi Sat Feb 01 16:57:10 1997 +0000 @@ -267,7 +267,7 @@ (defun RET-behaves-as-LFD () (let ((x (key-binding "\C-j"))) (local-set-key "\C-m" x))) -(add-hook 'octave-mode-hook 'return-behaves-as-LFD) +(add-hook 'octave-mode-hook 'RET-behaves-as-LFD) @end lisp @noindent (this works for all modes by adding to the startup hooks, without having
--- a/doc/interpreter/expr.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/expr.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Expressions, Statements, Invoking Octave, Top +@node Expressions, Statements, Basics, Top @chapter Expressions @cindex expressions @@ -58,8 +58,8 @@ The simplest form of a numeric constant, a scalar, is a single number that can be an integer, a decimal fraction, a number in scientific (exponential) notation, or a complex number. Note that all numeric -values are represented within Octave in double-precision floating point -format (complex constants are stored as pairs of double-precision +constants are represented within Octave in double-precision floating +point format (complex constants are stored as pairs of double-precision floating point values). Here are some examples of real-valued numeric constants, which all have the same value: @@ -297,19 +297,6 @@ (assuming that this expression was entered as the first thing on line 13, of course). -Commas and semicolons are not always required to separate matrix -elements and rows. The expression - -@example -@group -a = [ 1 2 - 3 4 ] -@end group -@end example - -@noindent -is equivalent to the one above. - Inside the square brackets that delimit a matrix expression, Octave looks at the surrounding context to determine whether spaces and newline characters should be converted into element and row separators, or @@ -324,8 +311,8 @@ @example @group -octave:13> a = [ 1 2 -> 3 4 ] +a = [ 1 2 + 3 4 ] @end group @end example @@ -610,6 +597,10 @@ The default value is @code{"warn"}. @end defvr +When Octave parses a matrix expression, it examines the elements of the +list to determine whether they are all constants. If they are, it +replaces the list with a single matrix constant. + @node Ranges, Variables, Matrices, Expressions @section Ranges @cindex range expressions @@ -618,7 +609,7 @@ @opindex : A @dfn{range} is a convenient way to write a row vector with evenly -spaced elements. A range constant is defined by the value of the first +spaced elements. A range expression is defined by the value of the first element in the range, an optional value for the increment between elements, and a maximum value which the elements of the range will not exceed. The base, increment, and limit are separated by colons (the @@ -643,7 +634,7 @@ Although a range constant specifies a row vector, Octave does @emph{not} convert range constants to vectors unless it is necessary to do so. This allows you to write a constant like @samp{1 : 10000} without using -up 80,000 bytes of storage on a typical 32-bit workstation. +80,000 bytes of storage on a typical 32-bit workstation. Note that the upper (or lower, if the increment is negative) bound on the range is not always included in the set of values, and that ranges @@ -653,6 +644,10 @@ number of elements is known, you should use the @code{linspace} function instead (@pxref{Special Matrices}). +When Octave parses a range expression, it examines the elements of the +expression to determine whether they are all constants. If they are, it +replaces the range expression with a single range constant. + @node Variables, Index Expressions, Ranges, Expressions @section Variables @cindex variables, user-defined @@ -867,19 +862,59 @@ @example for i = 1:10 - a (i) = i; + a (i) = sqrt (i); endfor @end example @noindent (for @samp{a} previously undefined) result in the variable @samp{a} -being resized to be just large enough to hold the new value. Otherwise -uninitialized elements are set to zero. If the value of -@code{resize_on_range_error} is 0, an error message is -printed and control is returned to the top level. The default value is -1. +being resized to be just large enough to hold the new value. New +elements that have not been given a value are set to zero. If the value +of @code{resize_on_range_error} is 0, an error message is printed and +control is returned to the top level. The default value is 1. @end defvr +Note that it is quite inefficient to create a vector using a loop like +the one shown in the example above. In this particular case, it would +have been much more efficient to use the expression + +@example +a = sqrt (1:10); +@end example + +@noindent +thus avoiding the loop entirely. In cases where a loop is still +required, or a number of values must be combined to form a larger +matrix, it is generally much faster to set the size of the matrix first, +and then insert elements using indexing commands. For example, given a +matrix @samp{a}, + +@example +@group +[nr, nc] = size (a); +x = zeros (nr, n * nc); +for i = 1:n + x(:,(i-1)*n+1:i*n) = a; +endfor +@end group +@end example + +@noindent +is considerably faster than + +@example +@group +x = a; +for i = 1:n-1 + x = [x, a]; +endfor +@end group +@end example + +@noindent +particularly for large matrices because Octave does not have to +repeatedly resize the result. + @node Data Structures, Calling Functions, Index Expressions, Expressions @section Data Structures @cindex structures @@ -890,15 +925,19 @@ strings, but the syntax is more like C-style structures. Here are some examples of using data structures in Octave. -Elements of structures can be of any value type. For example, the list -of statements +Elements of structures can be of any value type. For example, the three +expressions @example -octave:1> x.a = 1; x.b = [1, 2; 3, 4]; x.c = "string"; +@group +x.a = 1 +x.b = [1, 2; 3, 4] +x.c = "string" +@end group @end example @noindent -creates a structure with three elements. To print the value of the +create a structure with three elements. To print the value of the structure, you can type its name, just as for any other variable: @example @@ -1055,8 +1094,8 @@ a loop, using a special form of the @code{for} statement (@pxref{The for Statement}) -The following functions and variableare available to -give you information about structures. +The following functions are available to give you information about +structures. @deftypefn {Built-in Function} {} is_struct (@var{expr}) Returns 1 if the value of the expression @var{expr} is a structure. @@ -1213,7 +1252,7 @@ With some restrictions@footnote{Some of Octave's function are implemented in terms of functions that cannot be called recursively. For example, the ODE solver @code{lsode} is ultimiately implemented in a -Fortran subroutine which cannot be called recursively, so @code{lsode} +Fortran subroutine that cannot be called recursively, so @code{lsode} should not be called either directly or indirectly from within the user-supplied function that @code{lsode} requires. Doing so will result in undefined behavior.}, recursive function calls are allowed. A @@ -1298,23 +1337,36 @@ @end example Passing a global variable in a function parameter list will -make a local copy and not modify the global value. For example: +make a local copy and not modify the global value. For example, given +the function @example @group -octave:1> function f (x) -> x = 3 -> endfunction -octave:2> global x = 0 -octave:3> x # This is the value of the global variable. -x = 0 -octave:4> f (x) -x = 3 # The value of the local variable x is 3. -octave:5> x # But it was a *copy* so the global variable -x = 0 # remains unchanged. +function f (x) + x = 0 +endfunction @end group @end example +@noindent +and the definition of @samp{x} as a global variable at the top level, + +@example +global x = 13 +@end example + +@noindent +the expression + +@example +f (x) +@end example + +@noindent +will display the value of @samp{x} from inside the function as @samp{0}, +but the value of @samp{x} at the top level remains unchanged, because +the function works with a @emph{copy} of its argument. + @defvr {Built-in Variable} warn_comma_in_global_decl If the value of @code{warn_comma_in_global_decl} is nonzero, a warning is issued for statements like @@ -1424,8 +1476,8 @@ Element by element subtraction. This operator is equivalent to @code{-}. @item @var{x} * @var{y} -Matrix multiplication. The number of columns of @samp{x} must agree -with the number of rows of @samp{y}. +Matrix multiplication. The number of columns of @var{x} must agree +with the number of rows of @var{y}. @item @var{x} .* @var{y} Element by element multiplication. If both operands are matrices, the @@ -1439,7 +1491,7 @@ @end example @noindent -but it is computed without forming the inverse of @samp{y'}. +but it is computed without forming the inverse of @var{y'}. If the system is not square, or if the coefficient matrix is singular, a minimum norm solution is computed. @@ -1455,14 +1507,14 @@ @end example @noindent -but it is computed without forming the inverse of @samp{x}. +but it is computed without forming the inverse of @var{x}. If the system is not square, or if the coefficient matrix is singular, a minimum norm solution is computed. @item @var{x} .\ @var{y} -Element by element left division. Each element of @samp{y} is divided -by each corresponding element of @samp{x}. +Element by element left division. Each element of @var{y} is divided +by each corresponding element of @var{x}. @item @var{x} ^ @var{y} @itemx @var{x} ** @var{y} @@ -1558,29 +1610,24 @@ @dfn{Comparison operators} compare numeric values for relationships such as equality. They are written using -@emph{relational operators}, which are a superset of those in C. +@emph{relational operators}. All of Octave's comparison operators return a value of 1 if the comparison is true, or 0 if it is false. For matrix values, they all -work on an element-by-element basis. For example, evaluating the -expression - -@example -[1, 2; 3, 4] == [1, 3; 2, 4] -@end example - -@noindent -returns the result +work on an element-by-element basis. For example, @example @group -ans = +[1, 2; 3, 4] == [1, 3; 2, 4] - 1 0 - 0 1 + @result{} [ 1, 0; 0, 1 ] @end group @end example +If one operand is a scalar and the other is a matrix, the scalar is +compared to each element of the matrix in turn, and the result is the +same size as the matrix. + @table @code @item @var{x} < @var{y} True if @var{x} is less than @var{y}. @@ -1603,13 +1650,8 @@ True if @var{x} is not equal to @var{y}. @end table -For matrix and vector arguments, the above table should be read as -``an element of the result matrix (vector) is true if the corresponding -elements of the argument matrices (vectors) satisfy the specified -condition'' - -String comparisons should be performed with the @code{strcmp} function, -not with the comparison operators listed above. +String comparisons may also be performed with the @code{strcmp} +function, not with the comparison operators listed above. @xref{String Functions}. @node Boolean Expressions, Assignment Ops, Comparison Ops, Expressions @@ -1641,7 +1683,7 @@ @opindex ! An @dfn{element-by-element boolean expression} is a combination of -comparison expressions or matching expressions, using the boolean +comparison expressions using the boolean operators ``or'' (@samp{|}), ``and'' (@samp{&}), and ``not'' (@samp{!}), along with parentheses to control nesting. The truth of the boolean expression is computed by combining the truth values of the @@ -1650,10 +1692,7 @@ Element-by-element boolean expressions can be used wherever comparison expressions can be used. They can be used in @code{if} and @code{while} -statements. However, before being used in the condition of an @code{if} -or @code{while} statement, an implicit conversion from a matrix value to -a scalar value occurs using the equivalent of -@code{all (all (@var{x}))}. That is, a value used as the condition in an +statements. However, if a matrix value used as the condition in an @code{if} or @code{while} statement is only true if @emph{all} of its elements are nonzero. @@ -1728,20 +1767,20 @@ @item @var{boolean1} && @var{boolean2} The expression @var{boolean1} is evaluated and converted to a scalar using the equivalent of the operation @code{all (all (@var{boolean1}))}. -If it is false, the result of the expression is 0. If it is true, the -expression @var{boolean2} is evaluated and converted to a scalar -using the equivalent of the operation @code{all (all (@var{boolean1}))}. -If it is true, the result of the expression is 1. Otherwise, the result -of the expression is 0. +If it is false, the result of the overall expression is 0. If it is +true, the expression @var{boolean2} is evaluated and converted to a +scalar using the equivalent of the operation @code{all (all +(@var{boolean1}))}. If it is true, the result of the overall expression +is 1. Otherwise, the result of the overall expression is 0. @item @var{boolean1} || @var{boolean2} The expression @var{boolean1} is evaluated and converted to a scalar using the equivalent of the operation @code{all (all (@var{boolean1}))}. -If it is true, the result of the expression is 1. If it is false, the -expression @var{boolean2} is evaluated and converted to a scalar -using the equivalent of the operation @code{all (all (@var{boolean1}))}. -If it is true, the result of the expression is 1. Otherwise, the result -of the expression is 0. +If it is true, the result of the overall expression is 1. If it is +false, the expression @var{boolean2} is evaluated and converted to a +scalar using the equivalent of the operation @code{all (all +(@var{boolean1}))}. If it is true, the result of the overall expression +is 1. Otherwise, the result of the overall expression is 0. @end table The fact that both operands may not be evaluated before determining the @@ -1769,7 +1808,8 @@ @noindent instead of having to use two @code{if} statements to avoid attempting to -evaluate an argument that doesn't exist. +evaluate an argument that doesn't exist. For example, without hte +short-circuit feature, it would be necessary to write @example @group @@ -1799,6 +1839,7 @@ After this expression is executed, the variable @code{z} has the value 1. Whatever old value @code{z} had before the assignment is forgotten. +The @samp{=} sign is called an @dfn{assignment operator}. Assignments can store string values also. For example, the following expression would store the value @code{"this food is good"} in the @@ -1815,10 +1856,6 @@ @noindent (This also illustrates concatenation of strings.) -The @samp{=} sign is called an @dfn{assignment operator}. It is the -simplest assignment operator because the value of the right-hand -operand is stored unchanged. - @cindex side effect Most operators (addition, concatenation, and so on) have no effect except to compute a value. If you ignore the value, you might as well @@ -2016,7 +2053,7 @@ any such mistake. When operators of equal precedence are used together, the leftmost -operator groups first, except for the assignment, and exponentiation +operator groups first, except for the assignment and exponentiation operators, which group in the opposite order. Thus, the expression @code{a - b + c} groups as @code{(a - b) + c}, but the expression @code{a = b = c} groups as @code{a = (b = c)}.
--- a/doc/interpreter/extend.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/extend.texi Sat Feb 01 16:57:10 1997 +0000 @@ -6,7 +6,7 @@ @chapter Adding New Functions @cindex Functions -The following is not complete, but should help get you started and +The following is not complete give you some idea about why things are they way they are. Here's what you need to do to add a new function (I'll use svd() as an
--- a/doc/interpreter/foo.texi Fri Jan 31 20:30:22 1997 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,6 +0,0 @@ -\input texinfo -@setfilename foo.info -@settitle Foo -@node A, B, C, D -@chapter A -@bye
--- a/doc/interpreter/func.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/func.texi Sat Feb 01 16:57:10 1997 +0000 @@ -12,7 +12,7 @@ Complicated Octave programs can often be simplified by defining functions. Functions can be defined directly on the command line during interactive Octave sessions, or in external files, and can be called just -like built-in ones. +like built-in functions. @menu * Defining Functions:: @@ -218,8 +218,8 @@ @defvr {Automatic Variable} nargin When a function is called, this local variable is automatically initialized to the number of arguments passed to the function. At the -top level, it holds the number of command line arguments that were -passed to Octave. +top level, @code{nargin} holds the number of command line arguments that +were passed to Octave. @end defvr @defvr {Automatic Variable} nargout @@ -228,11 +228,22 @@ example, @example -@group -f () # nargout is 0 -[s, t] = f () # nargout is 2 -@end group +f () @end example + +@noindent +will result in @code{nargout} being set to 0 inside the function +@code{f} and + +@example +[s, t] = f () +@end example + +@noindent +will result in @code{nargout} being set to 2 inside the function +@code{f}. + +At the top level, @code{nargout} is undefined. @end defvr @defvr {Built-in Variable} silent_functions @@ -347,7 +358,8 @@ @noindent provided that the built-in variable @code{define_all_return_values} is -nonzero. @xref{Built-in Variables}. +nonzero and the value of @code{default_return_value} is @samp{[]}. +@xref{Built-in Variables}. @defvr {Built-in Variable} default_return_value The value given to otherwise unitialized return values if @@ -372,6 +384,9 @@ upper bound on the number of optional arguments that a function can accept. +@c XXX FIXME XXX -- should we add a note about why this feature is not +@c compatible with Matlab 5? + Here is an example of a function that uses the new syntax to print a header followed by an unspecified number of values: @@ -405,35 +420,28 @@ Sometimes it is useful to be able to pass all unnamed arguments to another function. The keyword @var{all_va_args} makes this very easy to -do. For example, given the functions +do. For example, @example +@group function f (...) while (nargin--) disp (va_arg ()) endwhile endfunction + function g (...) f ("begin", all_va_args, "end") endfunction -@end example -@noindent -the statement - -@example g (1, 2, 3) -@end example -@noindent -prints - -@example -begin -1 -2 -3 -end + @print{} begin + @print{} 1 + @print{} 2 + @print{} 3 + @print{} end +@end group @end example @defvr {Keyword} all_va_args @@ -453,15 +461,23 @@ unspecified number of values, so it is no longer necessary to place an upper bound on the number of outputs that a function can produce. -Here is an example of a function that uses the new syntax to produce -@var{n} values: +Here is an example of a function that uses a variable-length return list +to produce @var{n} values: @example -function [...] = foo (n, x) +@group +function [...] = f (n, x) for i = 1:n vr_val (i * x); endfor endfunction + +[dos, quatro] = f (2, 2) + + @result{} dos = 2 + + @result{} quatro = 4 +@end group @end example As with variable argument lists, the ellipsis that marks the variable @@ -520,10 +536,10 @@ does contain a nonzero element. @defvr {Keyword} return -When Octave encounters the keyword return, it returns control to be -calling function immediately. It is only valid within a function and -will result in an error if used at the top level. A @code{return} -statement is assumed at the end of every function definition. +When Octave encounters the keyword @code{return} inside a function or +script, it returns control to be caller immediately. At the top level, +the return statement is ignored. A @code{return} statement is assumed +at the end of every function definition. @end defvr @defvr {Built-in Variable} return_last_computed_value @@ -541,8 +557,9 @@ @end example @noindent -will either return nothing, if @code{return_last_computed_value} is -0, or 4, if it is nonzero. +will either return nothing, if the value of +@code{return_last_computed_value} is 0, or 4, if the value of +@code{return_last_computed_value} is nonzero. @end defvr @node Function Files, Script Files, Returning From a Function, Functions and Scripts @@ -596,6 +613,8 @@ @code{"system"} gives the default behavior. If you set it to anything else, Octave will check the time stamps on all function files. +@c XXX FIXME XXX -- note about time stamps on files in NFS environments? + @defvr {Built-in Variable} LOADPATH A colon separated list of directories in which to search for function files. @xref{Functions and Scripts}. The value of @code{LOADPATH} @@ -638,10 +657,11 @@ @end defvr @defvr {Built-in Variable} warn_function_name_clash -If the value of @code{warn_function_name_clash} is nonzero, a -warning is issued when Octave finds that the name of a function defined -in a function file differs from the name of the file. If the value is -0, the warning is omitted. The default value is 1. +If the value of @code{warn_function_name_clash} is nonzero, a warning is +issued when Octave finds that the name of a function defined in a +function file differs from the name of the file. (If the names +disagree, the name delcared inside the file is ignored.) If the value +is 0, the warning is omitted. The default value is 1. @end defvr @node Script Files, Dynamically Linked Functions, Function Files, Functions and Scripts @@ -760,57 +780,141 @@ features work on other systems using system-specific dynamic linking facilities. -Here is an example of how to write a C++ function that Octave can load. +Here is an example of how to write a C++ function that Octave can load, +with commentary. The source for this function is distributed with +Octave, in the file @file{examples/hello.cc}. + +To use this file, your version of Octave must support dynamic +linking. To find out if it does, type the command + +@example +x = octave_config_info; x.DEFS +@end example + +@noindent +at the Octave prompt. Support for dynamic linking is included if +the output contains the string @code{-DWITH_DYNAMIC_LINKING=1}. + +To compile this file, type the command + +@example +mkoctfile hello.cc +@end example + +@noindent +at the shell prompt. The script @file{mkoctfile} should have been +installed along with Octave. Running it will create a file called +@file{hello.oct} that can be loaded by Octave. To test the +@file{hello.oct} file, start Octave and type the command @example -#include <iostream.h> +hello ("easy as", 1, 2, 3) +@end example + +@noindent +at the Octave prompt. Octave should respond by printing -#include "defun-dld.h" -#include "tree-const.h" +@example +Hello, world! +easy as +1 +2 +3 +ans = 3 +@end example -DEFUN_DLD ("hello", Fhello, Shello, -1, -1, - "hello (...)\n\ -\n\ -Print greeting followed by the values of all the arguments passed.\n\ -Returns all the arguments passed.") -@{ - Octave_object retval; - cerr << "Hello, world!\n"; - int nargin = args.length (); - for (int i = 1; i < nargin; i++) - retval (nargin-i-1) = args(i).eval (1); - return retval; -@} +Additional examples are available in the files in the src directory +of the Octave distribution that use the macro @code{DEFUN_DLD_BUILTIN}. +Currently, this includes the files + +@example +@group +balance.cc fft.cc hess.cc lu.cc schur.cc +chol.cc fft2.cc ifft.cc minmax.cc sort.cc +colloc.cc filter.cc ifft2.cc pinv.cc svd.cc +dassl.cc find.cc inv.cc qr.cc syl.cc +det.cc fsolve.cc log.cc quad.cc +eig.cc fsqp.cc lsode.cc qzval.cc +expm.cc givens.cc lu.cc rand.cc +@end group @end example -Octave's dynamic linking features currently have the following -limitations. +The difference between @code{DEFUN_DLD} and @code{DEFUN_DLD_BUILTIN} is +that @code{DEFUN_DLD_BUILTIN} can define a built-in function that is not +dynamically loaded if the operating system does not support dynamic +linking. To define your own dynamically linked functions you should use +@code{DEFUN_DLD}. + +@example +@group +#include <octave/config.h> + +#include <iostream.h> -@itemize @bullet -@item -Dynamic linking only works on systems that support the GNU dynamic -linker, @code{dld}. -@item -Clearing dynamically linked functions doesn't work. +#include <octave/defun-dld.h> +#include <octave/error.h> +#include <octave/oct-obj.h> +#include <octave/pager.h> +#include <octave/symtab.h> +#include <octave/variables.h> +@end group +@end example + +@code{DEFUN_DLD} and the macros that it depends on are defined in the +files @file{defun-dld.h}, @file{defun.h}, and @file{defun-int.h}. + +Note that the third parameter (@code{nargout}) is not used, so it is +omitted from the list of arguments to @code{DEFUN_DLD} in order to avoid +the warning from gcc about an unused function parameter. -@item -Configuring Octave with @code{--enable-lite-kernel} seems to mostly work -to make nonessential built-in functions dynamically loaded, but there -also seem to be some problems. For example, fsolve seems to always -return @code{info == 3}. This is difficult to debug since @code{gdb} -won't seem to allow breakpoints to be set inside dynamically loaded -functions. +@example +@group +DEFUN_DLD (hello, args, , + "[...] = hello (...)\n\ +\n\ +Print greeting followed by the values of all the arguments passed.\n\ +Returns all arguments in reverse order.") +@{ +@end group +@end example + +The list of values to return. See the declaration in @file{oct-obj.h}. + +@example + octave_value_list retval; +@end example + +This stream is normally connected to the pager. + +@example + octave_stdout << "Hello, world!\n"; +@end example -@item -Octave uses a lot of memory if the dynamically linked functions are -compiled to include debugging symbols. This appears to be a limitation -with @code{dld}, and can be avoided by not using @code{-g} to compile -functions that will be linked dynamically. -@end itemize +The arguments to this function are available in @samp{args}. + +@example + int nargin = args.length (); +@end example + +The @code{octave_value_list} class is a zero-based array of +@code{octave_value} objects. The declaration for the +@code{octave_value} class is in the file @code{pt-const.h}. The +@code{print()} method will send its output to @code{octave_stdout}, so +it will also end up going through the pager. -If you would like to volunteer to help improve Octave's ability to -dynamically link externally compiled functions, please contact -@code{bug-octave@@bevo.che.wisc.edu}. +@example +@group + for (int i = 0; i < nargin; i++) + @{ + octave_value tmp = args (i); + tmp.print (); + retval (nargin-i-1) = tmp; + @} + + return retval; +@} +@end group +@end example @node Organization of Functions, , Dynamically Linked Functions, Functions and Scripts @section Organization of Functions Distributed with Octave @@ -824,6 +928,9 @@ types of functions you will find there. @table @file +@item audio +Functions for playing and recording sounds. + @item control Functions for design and simulation of automatic control systems. @@ -838,6 +945,9 @@ @item image Image processing tools. These functions require the X Window System. +@item io +Input-ouput functions. + @item linear-algebra Functions for linear algebra. @@ -870,4 +980,7 @@ @item strings Miscellaneous string-handling functions. + +@item time +Functions related to time keeping. @end table
--- a/doc/interpreter/gnuinfo.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/gnuinfo.texi Sat Feb 01 16:57:10 1997 +0000 @@ -10,7 +10,7 @@ @c This file documents the use of the standalone GNU Info program, @c versions 2.7 and later. -@node Using Info, Copying, Command Line Editing, Top +@node Using Info @appendix Using Info @menu @@ -44,7 +44,7 @@ * Info Variables:: How to change the default behavior of Info. @end menu -@node Cursor Commands, Scrolling Commands, Using Info, Using Info +@node Cursor Commands @appendixsec Moving the Cursor @cindex cursor, moving Many people find that reading screens of text page by page is made @@ -135,7 +135,7 @@ moves the cursor to the start of the @var{n}th line in the window. @end table -@node Scrolling Commands, Node Commands, Cursor Commands, Using Info +@node Scrolling Commands @appendixsec Moving Text Within a Window @cindex scrolling, in Info windows @@ -201,7 +201,7 @@ invisible. @end table -@node Node Commands, Searching Commands, Scrolling Commands, Using Info +@node Node Commands @appendixsec Selecting a New Node @cindex nodes, selection of in Info windows @@ -351,7 +351,7 @@ created. @end table -@node Searching Commands, Xref Commands, Node Commands, Using Info +@node Searching Commands @appendixsec Searching an Info File @cindex searching @@ -403,7 +403,7 @@ string is looked up while you are typing it, instead of waiting until the entire search string has been specified. -@node Xref Commands, Window Commands, Searching Commands, Using Info +@node Xref Commands @appendixsec Selecting Cross References We have already discussed the @samp{Next}, @samp{Prev}, and @samp{Up} @@ -417,7 +417,7 @@ * Selecting Xrefs:: Commands for selecting menu or note items. @end menu -@node Parts of an Xref, Selecting Xrefs, Xref Commands, Xref Commands +@node Parts of an Xref @appendixsubsec Parts of an Xref Cross references have two major parts: the first part is called the @@ -465,7 +465,7 @@ Manual}, for more information on creating your own texinfo cross references. -@node Selecting Xrefs, , Parts of an Xref, Xref Commands +@node Selecting Xrefs @appendixsubsec Selecting Xrefs The following table lists the Info commands which operate on menu items. @@ -532,7 +532,7 @@ Selects the menu item or note reference appearing on this line. @end table -@node Window Commands, Printing Nodes, Xref Commands, Using Info +@node Window Commands @appendixsec Manipulating Multiple Windows @cindex windows, manipulating @@ -553,7 +553,7 @@ * The Echo Area:: Used for displaying errors and reading input. @end menu -@node The Mode Line, Basic Windows, Window Commands, Window Commands +@node The Mode Line @appendixsubsec The Mode Line A @dfn{mode line} is a line of inverse video which appears at the bottom @@ -593,7 +593,7 @@ -----Info: *Completions*, 7 lines --All-------------------------------- @end smallexample -@node Basic Windows, The Echo Area, The Mode Line, Window Commands +@node Basic Windows @appendixsubsec Window Commands It can be convenient to view more than one node at a time. To allow @@ -668,7 +668,7 @@ @xref{Info Variables, , @code{automatic-tiling}}. @end table -@node The Echo Area, , Basic Windows, Window Commands +@node The Echo Area @appendixsubsec The Echo Area @cindex echo area @@ -844,7 +844,7 @@ window if not. @end table -@node Printing Nodes, Other Info Commands, Window Commands, Using Info +@node Printing Nodes @appendixsec Printing Out Nodes @cindex printing @@ -863,7 +863,7 @@ exist, the node is simply piped to @code{lpr}. @end table -@node Other Info Commands, Info Variables, Printing Nodes, Using Info +@node Other Info Commands @appendixsec Miscellaneous Info Commands GNU Info contains several commands which self-document GNU Info: @@ -989,7 +989,7 @@ @xref{Info Variables, , @code{automatic-footnotes}}. @end table -@node Info Variables, , Other Info Commands, Using Info +@node Info Variables @appendixsec Manipulating Variables GNU Info contains several @dfn{variables} whose values are looked at by various
--- a/doc/interpreter/gpl.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/gpl.texi Sat Feb 01 16:57:10 1997 +0000 @@ -4,7 +4,7 @@ @cindex warranty @cindex copyright -@node Copying, Concept Index, Using Info, Top +@node Copying, Concept Index, Trouble, Top @appendix GNU GENERAL PUBLIC LICENSE @center Version 2, June 1991
--- a/doc/interpreter/help.texi Fri Jan 31 20:30:22 1997 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,61 +0,0 @@ -@c Copyright (C) 1996 John W. Eaton -@c This is part of the Octave manual. -@c For copying conditions, see the file gpl.texi. - -@node Help, Programming Utilities, Command History Functions, Top -@chapter Help - -@deffn {Command} help -Octave's @code{help} command can be used to print brief usage-style -messages, or to display information directly from an on-line version of -the printed manual, using the GNU Info browser. If invoked without any -arguments, @code{help} prints a list of all the available operators, -functions, and built-in variables. If the first argument is @code{-i}, -the @code{help} command searches the index of the on-line version of -this manual for the given topics. - -For example, the command - -@example -help help -@end example - -@noindent -prints a short message describing the @code{help} command, and - -@example -help -i help -@end example - -@noindent -starts the GNU Info browser at this node in the on-line version of the -manual. - -@xref{Using Info}, for complete details about how to use the GNU Info -browser to read the on-line version of the manual. -@end deffn - -The help command can give you information about operators, but not the -comma and semicolons that are used as command separators. To get help -for those, you must type @code{help comma} or @code{help semicolon}. - -@defvr {Built-in Variable} INFO_FILE -The variable @code{INFO_FILE} names the location of the Octave info file. -The default value is @code{"@value{OCTAVEHOME}/info/octave.info"}. -@end defvr - -@defvr {Built-in Variable} INFO_PROGRAM -The variable @code{INFO_PROGRAM} names the info program to run. Its -initial value is -@code{@value{OCTAVEHOME}/libexec/octave/VERSION/exec/ARCH/info}, but -that value can be overridden by the environment variable -@code{OCTAVE_INFO_PROGRAM}, or the command line argument -@code{--info-program NAME}, or by setting the value of -@code{INFO_PROGRAM} in a startup script. -@end defvr - -@defvr {Built-in Variable} suppress_verbose_help_message -If the value of @code{suppress_verbose_help_message} is nonzero, Octave -will not add additional help information to the end of the output from -the @code{help} command and usage messages for built-in commands. -@end defvr
--- a/doc/interpreter/history.texi Fri Jan 31 20:30:22 1997 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,162 +0,0 @@ -@c Copyright (C) 1996 John W. Eaton -@c This is part of the Octave manual. -@c For copying conditions, see the file gpl.texi. - -@node Command History Functions, Help, System Utilities, Top -@chapter Command History Functions - -Octave provides three functions for viewing, editing, and re-running -chunks of commands from the history list. - -@deffn {Command} history options -If invoked with no arguments, @code{history} displays a list of commands -that you have executed. Valid options are: - -@table @code -@item -w file -Write the current history to the named file. If the name is omitted, -use the default history file (normally @file{~/.octave_hist}). - -@item -r file -Read the named file, replacing the current history list with its -contents. If the name is omitted, use the default history file -(normally @file{~/.octave_hist}). - -@item N -Only display the most recent @code{N} lines of history. - -@item -q -Don't number the displayed lines of history. This is useful for cutting -and pasting commands if you are using the X Window System. -@end table - -For example, to display the five most recent commands that you have -typed without displaying line numbers, use the command -@samp{history -q 5}. -@end deffn - -@deffn {Command} edit_history options -If invoked with no arguments, @code{edit_history} allows you to edit the -history list using the editor named by the variable @code{EDITOR}. The -commands to be edited are first copied to a temporary file. When you -exit the editor, Octave executes the commands that remain in the file. -It is often more convenient to use @code{edit_history} to define functions -rather than attempting to enter them directly on the command line. -By default, the block of commands is executed as soon as you exit the -editor. To avoid executing any commands, simply delete all the lines -from the buffer before exiting the editor. - -The @code{edit_history} command takes two optional arguments specifying -the history numbers of first and last commands to edit. For example, -the command - -@example -edit_history 13 -@end example - -@noindent -extracts all the commands from the 13th through the last in the history -list. The command - -@example -edit_history 13 169 -@end example - -@noindent -only extracts commands 13 through 169. Specifying a larger number for -the first command than the last command reverses the list of commands -before placing them in the buffer to be edited. If both arguments are -omitted, the previous command in the history list is used. -@end deffn - -@defvr {Built-in Variable} EDITOR -A string naming the editor to use with the @code{edit_history} command. -If the environment variable @code{EDITOR} is set when Octave starts, its -value is used as the default. Otherwise, @code{EDITOR} is set to -@code{"vi"}. -@end defvr - -@deffn {Command} run_history -Similar to @code{edit_history}, except that the editor is not invoked, -and the commands are simply executed as they appear in the history list. -@end deffn - -@defvr {Built-in Variable} history_file -This variable specifies the name of the file used to store command -history. The default value is @code{"~/.octave_hist"}, but may be -overridden by the environment variable @code{OCTAVE_HISTFILE}. -@end defvr - -@defvr {Built-in Variable} history_size -This variable specifies how many entries to store in the history file. -The default value is @code{1024}, but may be overridden by the -environment variable @code{OCTAVE_HISTSIZE}. -@end defvr - -@defvr {Built-in Variable} saving_history -If the value of @code{saving_history} is @code{"true"}, command entered -on the command line are saved in the file specified by the variable -@code{history_file}. -@end defvr - -@deffn {Command} diary -The @code{diary} command allows you to create a list of all commands -@emph{and} the output they produce, mixed together just as you see them -on your terminal. - -For example, the command - -@example -diary on -@end example - -@noindent -tells Octave to start recording your session in a file called -@file{diary} in your current working directory. To give Octave the name -of the file write to, use the a command like - -@example -diary my-diary.txt -@end example - -@noindent -Then Octave will write all of your commands to the file -@file{my-diary.txt}. - -To stop recording your session, use the command - -@example -diary off -@end example - -@noindent -Without any arguments, @code{diary} toggles the current diary state. -@end deffn - -@deffn {Command} echo options -Control whether commands are displayed as they are executed. Valid -options are: - -@table @code -@item on -Enable echoing of commands as they are executed in script files. - -@item off -Disable echoing of commands as they are executed in script files. - -@item on all -Enable echoing of commands as they are executed in script files and -functions. - -@item off all -Disable echoing of commands as they are executed in script files and -functions. -@end table - -@noindent -If invoked without any arguments, @code{echo} toggles the current echo -state. -@end deffn - -@defvr {Built-in Variable} echo_executing_commands -@end defvr
--- a/doc/interpreter/hsuser.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/hsuser.texi Sat Feb 01 16:57:10 1997 +0000 @@ -23,7 +23,7 @@ into another language, under the above conditions for modified versions. @end ignore -@node Using History Interactively, Installation, Command Line Editing, Top +@node Using History Interactively @chapter Using History Interactively This chapter describes how to use the GNU History Library interactively, @@ -36,7 +36,7 @@ * History Interaction:: What it feels like using History as a user. @end menu -@node History Interaction, , , Using History Interactively +@node History Interaction @section History Interaction @cindex expansion @@ -59,7 +59,7 @@ * Modifiers:: Modifying the results of substitution. @end menu -@node Event Designators, Word Designators, , History Interaction +@node Event Designators @subsection Event Designators @cindex event designators @@ -89,7 +89,7 @@ @end table -@node Word Designators, Modifiers, Event Designators, History Interaction +@node Word Designators @subsection Word Designators A @key{:} separates the event specification from the word designator. It @@ -124,7 +124,7 @@ @end table -@node Modifiers, , Word Designators, History Interaction +@node Modifiers @subsection Modifiers After the optional word designator, you can add a sequence of one or more
--- a/doc/interpreter/image.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/image.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Image Processing, Audio Processing, Plotting, Top +@node Image Processing, Audio Processing, Signal Processing, Top @chapter Image Processing To display images using these functions, you must be using Octave with
--- a/doc/interpreter/in-idx.texi Fri Jan 31 20:30:22 1997 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,8 +0,0 @@ -@c Copyright (C) 1996 John W. Eaton -@c This is part of the Octave manual. -@c For copying conditions, see the file gpl.texi. - -@node Info Index, , Readline Index, Top -@unnumbered Info Index - -@printindex in
--- a/doc/interpreter/install.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/install.texi Sat Feb 01 16:57:10 1997 +0000 @@ -19,7 +19,7 @@ under the terms of the GNU General Public License as published by the Free Software Foundation. -@node Installation, Installation, Installation, (dir) +@node Installation, , Installation @chapter Installing Octave @end ifset
--- a/doc/interpreter/intro.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/intro.texi Sat Feb 01 16:57:10 1997 +0000 @@ -6,8 +6,8 @@ @chapter A Brief Introduction to Octave @cindex introduction -This manual documents how to run, install and port Octave, and how -to report bugs. +This manual documents how to run, install and port Octave, and how to +report bugs. Octave is a high-level language, primarily intended for numerical computations. It provides a convenient command line interface for @@ -30,9 +30,7 @@ @menu * Running Octave:: * Simple Examples:: -* Comments:: -* Executable Octave Programs:: -* Errors:: +* Conventions:: @end menu @node Running Octave, Simple Examples, Introduction, Introduction @@ -53,17 +51,10 @@ @cindex quitting octave To exit Octave, type @samp{quit}, or @samp{exit} at the Octave prompt. -@deftypefn {Built-in Function} {} exit (@var{status}) -@deftypefnx {Built-in Function} {} quit (@var{status}) -Exit the current Octave session. If the optional integer value -@var{status} is supplied, pass that value to the operating system as the -Octave's exit status. -@end deftypefn - On systems that support job control, you can suspend Octave by sending it a @code{SIGTSTP} signal, usually by typing @kbd{C-z}. -@node Simple Examples, Comments, Running Octave, Introduction +@node Simple Examples, Conventions, Running Octave, Introduction @section Simple Examples The following chapters describe all of Octave's features in detail, but @@ -355,211 +346,261 @@ advance one line, a space character to advance one page, and @samp{q} to exit the pager. -@unnumberedsubsubsec Help via Info - The part of Octave's help facility that allows you to read the complete -text of the printed manual from within Octave uses a program called -Info. When you invoke Info you will be put into a menu driven program -that contains the entire Octave manual. Help for using Info is provided -in this manual in @ref{Using Info}. +text of the printed manual from within Octave normally uses a separate +program called Info. When you invoke Info you will be put into a menu +driven program that contains the entire Octave manual. Help for using +Info is provided in this manual in @ref{Help}. -@node Comments, Executable Octave Programs, Simple Examples, Introduction -@section Comments in Octave Programs -@cindex @samp{#} -@cindex @samp{%} -@cindex comments -@cindex use of comments -@cindex documenting Octave programs -@cindex programs, documenting +@node Conventions, , Simple Examples, Introduction +@section Conventions -A @dfn{comment} is some text that is included in a program for the sake -of human readers, and that is not really part of the program. Comments -can explain what the program does, and how it works. Nearly all -programming languages have provisions for comments, because programs are -typically hard to understand without them. +This section explains the notational conventions that are used in this +manual. You may want to skip this section and refer back to it later. -In the Octave language, a comment starts with either the sharp sign -character, @samp{#}, or the percent symbol @samp{%} and continues to the -end of the line. The Octave interpreter ignores the rest of a -line following a sharp sign or percent symbol. For example, we could -have put the following into the function @code{f}: +@menu +* Fonts:: +* Evaluation Notation:: +* Printing Notation:: +* Error Messages:: +* Format of Descriptions:: +@end menu -@smallexample -function xdot = f (x, t) - -# usage: f (x, t) -# -# This function defines the right-hand-side functions for a set of -# nonlinear differential equations. +@node Fonts, Evaluation Notation, Conventions, Conventions +@subsection Fonts +@cindex fonts - r = 0.25 - - and so on... - -endfunction -@end smallexample +Examples of Octave code appear in this font or form: @code{svd (a)}. +Names that represent arguments or metasyntactic variables appear +in this font or form: @var{first-number}. -The @code{help} command (@pxref{Help}) is able to find the first block -of comments in a function (even those that are composed directly on the -command line). This means that users of Octave can use the same -commands to get help for built-in functions, and for functions that you -have defined. For example, after defining the function @code{f} above, -the command +@node Evaluation Notation, Printing Notation, Fonts, Conventions +@subsection Evaluation Notation +@cindex evaluation notation +@cindex documentation notation + +In the examples in this manual, results from expressions that you +evaluate are indicated with @samp{@result{}}. For example, @example -help f +@group +sqrt (2) + + @result{} 1.4142 +@end group @end example @noindent -produces the output - -@smallexample - usage: f (x, t) - - This function defines the right-hand-side functions for a set of - nonlinear differential equations. -@end smallexample - -Although it is possible to put comment lines into keyboard-composed -throw-away Octave programs, it usually isn't very useful, because the -purpose of a comment is to help you or another person understand the -program at a later time. +You can read this as ``@code{sqrt (2)} evaluates to 1.4142''. -@node Executable Octave Programs, Errors, Comments, Introduction -@section Executable Octave Programs -@cindex executable scripts -@cindex scripts, executable -@cindex self contained programs -@cindex program, self contained -@cindex @samp{#!} - -Once you have learned Octave, you may want to write self-contained -Octave scripts, using the @samp{#!} script mechanism. You can do this -on GNU systems and on many Unix systems @footnote{The @samp{#!} -mechanism works on Unix systems derived from Berkeley Unix, System V -Release 4, and some System V Release 3 systems.} - -For example, you could create a text file named @file{hello}, containing -the following lines: +In some cases, matrix values that are returned by expressions are +displayed like this @example @group -#! @value{OCTAVEHOME}/bin/octave -qf +[1, 2; 3, 4] == [1, 3; 2, 4] + + @result{} [ 1, 0; 0, 1 ] +@end group +@end example -# a sample Octave program -printf ("Hello, world!\n"); +@noindent +and in other cases, they are displayed like this + +@example +@group +eye (3) + + @result{} 1 0 0 + 0 1 0 + 0 0 1 @end group @end example @noindent -After making this file executable (with the @code{chmod} command), you -can simply type: +in order to clearly show the structure of the result. + +Sometimes to help describe one expression, another expression is +shown that produces identical results. The exact equivalence of +expressions is indicated with @samp{@equiv{}}. For example, @example -hello +@group +rot90 ([1, 2; 3, 4], -1) +@equiv{} +rot90 ([1, 2; 3, 4], 3) +@equiv{} +rot90 ([1, 2; 3, 4], 7) +@end group @end example -@noindent -at the shell, and the system will arrange to run Octave @footnote{The -line beginning with @samp{#!} lists the full file name of an interpreter -to be run, and an optional initial command line argument to pass to that -interpreter. The operating system then runs the interpreter with the -given argument and the full argument list of the executed program. The -first argument in the list is the full file name of the Octave program. -The rest of the argument list will either be options to Octave, or data -files, or both. The @code{-qf} option is usually specified in -stand-alone Octave programs to prevent them from printing the normal -startup message, and to keep them from behaving differently depending on -the contents of a particular user's @file{~/.octaverc} file. -@xref{Invoking Octave}.} as if you had typed: +@node Printing Notation, Error Messages, Evaluation Notation, Conventions +@subsection Printing Notation +@cindex printing notation + +Many of the examples in this manual print text when they are +evaluated. Examples in this manual indicate printed text with +@samp{@print{}}. The value that is returned by evaluating the +expression (here @code{1}) is displayed with @samp{@result{}} and +follows on a separate line. @example -octave hello +@group +printf ("foo %s\n", "bar") + + @print{} foo bar + + @result{} 1 +@end group +@end example + +@node Error Messages, Format of Descriptions, Printing Notation, Conventions +@subsection Error Messages +@cindex error message notation + +Some examples signal errors. This normally displays an error message +on your terminal. Error messages are shown on a line starting with +@samp{@error{}}. Note that @samp{@error{}} itself does not appear on +your terminal. + +@example +struct_elements ([1, 2; 3, 4]) +@error{} struct_elements: wrong type argument `matrix' @end example -@noindent -Self-contained Octave scripts are useful when you want to write a -program which users can invoke without knowing that the program is -written in the Octave language. +@node Format of Descriptions, , Error Messages, Conventions +@subsection Format of Descriptions +@cindex description format + +Functions, commands, and variables are described in this manual in a +uniform format. The first line of a description contains the name of +the item followed by its arguments, if any. +@ifinfo +The category---function, variable, or whatever---appears at the +beginning of the line. +@end ifinfo +@iftex +The category---function, variable, or whatever---is printed next to the +right margin. +@end iftex +The description follows on succeeding lines, sometimes with examples. -@node Errors, , Executable Octave Programs, Introduction -@section Errors +@menu +* A Sample Function Description:: +* A Sample Command Description:: +* A Sample Variable Description:: +@end menu + +@node A Sample Function Description, A Sample Command Description, Format of Descriptions, Format of Descriptions +@subsubsection A Sample Function Description +@cindex function descriptions -There are two classes of errors that Octave produces when it encounters -input that it is unable to understand, or when it is unable to perform -an action. +In a function description, the name of the function being described +appears first. It is followed on the same line by a list of parameters. +The names used for the parameters are also used in the body of the +description. -A @dfn{parse error} occurs if Octave cannot understand something you -have typed. For example, if you misspell a keyword, +Here is a description of an imaginary function @code{foo}: + +@deftypefn {Function} {} foo (@var{x}, @var{y}, @dots{}) +The function @code{foo} subtracts @var{x} from @var{y}, then adds the +remaining arguments to the result. If @var{y} is not supplied, then the +number 19 is used by default. @example -octave:13> functon y = f (x) y = x^2; endfunction +@group +foo (1, [3, 5], 3, 9) + + @result{} [ 14, 16 ] + +foo (5) + + @result{} 14 +@end group @end example -@noindent -Octave will respond immediately with a message like this: +More generally, @example -parse error: +@group +foo (@var{w}, @var{x}, @var{y}, @dots{}) +@equiv{} +@var{x} - @var{w} + @var{y} + @dots{} +@end group +@end example +@end deftypefn + +Any parameter whose name contains the name of a type (e.g., +@var{integer}, @var{integer1} or @var{matrix}) is expected to be of that +type. Parameters named @var{object} may be of any type. Parameters +with other sorts of names (e.g., @var{new_file}) are discussed +specifically in the description of the function. In some sections, +features common to parameters of several functions are described at the +beginning. + +Functions in Octave may be defined in several different ways. The +catagory name for functions may include another name that indicates the +way that the function is defined. These additional tags include + +@table @asis +@item Built-in Function +The function described is written in a language like C++, C, or Fortran, +and is part of the compiled Octave binary. - functon y = f (x) y = x^2; endfunction - ^ +@item Loadable Function +The function described is written in a language like C++, C, or Fortran. +On systems that support dynamic linking of user-supplied functions, it +may be automatically linked while Octave is running, but only if it is +needed. @xref{Dynamically Linked Functions}. + +@item Function File +The function described is defined using Octave commands stored in a text +file. @xref{Function Files}. +@end table + +@node A Sample Command Description, A Sample Variable Description, A Sample Function Description, Format of Descriptions +@subsubsection A Sample Function Description +@cindex command descriptions + +Command descriptions have a format similar to function descriptions, +except that the word `Function' is replaced by `Command. Commands are +functions that are called without surrounding their arguments in +parentheses. For example, here is the description for Octave's +@code{cd} command: + +@deffn {Command} cd dir +@deffnx {Command} chdir dir +Change the current working directory to @var{dir}. For example, + +@example +cd ~/octave @end example @noindent -For most parse errors, Octave uses a caret (@samp{^}) to mark the point -on the line where it was unable to make sense of your input. In this -case, Octave generated an error message because the keyword -@code{function} was misspelled. Instead of seeing @samp{function f}, -Octave saw two consecutive variable names, which is invalid in this -context. It marked the error at the @code{y} because the first name by -itself was accepted as valid input. +Changes the current working directory to @file{~/octave}. If the +directory does not exist, an error message is printed and the working +directory is not changed. +@end deffn -Another class of error message occurs occurs at evaluation time. These -errors are called @dfn{run-time errors}, or sometimes -@dfn{evaluation errors} because they occur when your program is being -@dfn{run}, or @dfn{evaluated}. For example, if after correcting the -mistake in the previous function definition, you type - -@example -octave:13> f () -@end example - -@noindent -Octave will respond with +@node A Sample Variable Description, , A Sample Command Description, Format of Descriptions +@subsubsection A Sample Variable Description +@cindex variable descriptions -@example -@group -error: `x' undefined near line 1 column 24 -error: evaluating expression near line 1, column 24 -error: evaluating assignment expression near line 1, column 22 -error: called from `f' -@end group -@end example +A @dfn{variable} is a name that can hold a value. Although any variable +can be set by the user, certain variables that exist specifically so +that users can change them are called @dfn{user options}. Ordinary +variables and user options are described using a format like that for +functions except that there are no arguments. -This error message has several parts, and gives you quite a bit of -information to help you locate the source of the error. The messages -are generated from the point of the innermost error, and provide a -traceback of enclosing expressions and function calls. +Here is a description of the imaginary user option +@code{do_what_i_mean_not_what_i_say}. -In the example above, the first line indicates that a variable named -@samp{x} was found to be undefined near line 1 and column 24 of some -function or expression. For errors occurring within functions, lines -from the beginning of the file containing the function definition. For -errors occurring at the top level, the line number indicates the input -line number, which is usually displayed in the prompt string. +@defvr {User Option} do_what_i_mean_not_what_i_say +If the value of this variable is nonzero, Octave will do what you +actually wanted, even if you have typed a completely different and +meaningless list of commands. +@end defvr -The second and third lines in the example indicate that the error -occurred within an assignment expression, and the last line of the error -message indicates that the error occurred within the function @samp{f}. -If the function @samp{f} had been called from another function, for -example, @samp{g}, the list of errors would have ended with one more -line: - -@example -error: called from `g' -@end example - -These lists of function calls usually make it fairly easy to trace the -path your program took before the error occurred, and to correct the -error before trying again. +Other variable descriptions have the same format, but `User Option' is +replaced by `Variable', for ordinary variables, or `Constant' for +symbolic constants whose values cannot be changed.
--- a/doc/interpreter/invoke.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/invoke.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Invoking Octave, Expressions, Introduction, Top +@node Invoking Octave, Basics, Introduction, Top @chapter Invoking Octave Normally, Octave is used interactively by running the program @@ -13,7 +13,7 @@ will read and execute the commands from the named file and then exit when it is finished. -You can further control how Octave starts up by using the command-line +You can further control how Octave starts by using the command-line options described in the next section, and Octave itself can remind you of the options available. Type @@ -36,6 +36,9 @@ @cindex command options @cindex options, Octave command +Here is a complete list of all the command line options that Octave +accepts. + @table @code @item --debug @itemx -d @@ -169,6 +172,10 @@ Execute commands from @var{file}. @end table +Octave also includes several built-in variables that contain information +about the command line, including the number of arguments and all of the +options. + @defvr {Built-in Variable} argv The command line arguments passed to Octave are available in this variable. For example, if you invoked Octave using the command @@ -180,6 +187,9 @@ @noindent @code{argv} would be a string vector with the elements @code{--no-line-editing} and @code{--silent}. + +If you write an executable Octave script, @var{argv} will contain the +list of arguments passed to the script. @pxref{Executable Octave Programs}. @end defvr @defvr {Built-in Variable} nargin @@ -211,7 +221,7 @@ @example printf ("%s", program_name); for i = 1:nargin - printf (" %s", i, argv(i,:)); + printf (" %s", argv(i,:)); endfor printf ("\n"); @end example @@ -269,5 +279,5 @@ invoke Octave with the @code{--verbose} option but without the @code{--silent} option. -Startup files may contain any valid Octave commands, including multiple -function definitions. +Startup files may contain any valid Octave commands, including function +definitions.
--- a/doc/interpreter/io.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/io.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,43 +2,50 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Input and Output, Special Matrices, Audio Processing, Top +@node Input and Output, Plotting, Built-in Variables, Top @chapter Input and Output There are two distinct classes of input and output functions. The first set are modeled after the functions available in @sc{Matlab}. The second set are modeled after the standard I/O library used by the C -programming language. The C-style I/O functions offer more flexibility -and control over the output, but are not quite as easy to use as the -simpler @sc{Matlab}-style I/O functions. +programming language and offer more flexibility and control over the +output. When running interactively, Octave normally sends any output intended for your terminal that is more than one screen long to a paging program, -such as @code{less} or @code{more}. This avoids the problem of having -a large volume of output stream by before you can read it. With -@code{less} (and some versions of @code{more}) it also allows you to -scan forward and backward, and search for specific items. +such as @code{less} or @code{more}. This avoids the problem of having a +large volume of output stream by before you can read it. With +@code{less} (and some versions of @code{more}) you can also scan forward +and backward, and search for specific items. -No output is displayed by the pager until just before Octave is ready to -print the top level prompt, or read from the standard input (for -example, by using the @code{fscanf} or @code{scanf} functions). This -means that there may be some delay before any output appears on your -screen if you have asked Octave to perform a significant amount of work -with a single command statement. The function @code{fflush} may be used -to force output to be sent to the pager immediately. @xref{C-Style I/O -Functions}. +Normally, no output is displayed by the pager until just before Octave +is ready to print the top level prompt, or read from the standard input +(for example, by using the @code{fscanf} or @code{scanf} functions). +This means that there may be some delay before any output appears on +your screen if you have asked Octave to perform a significant amount of +work with a single command statement. The function @code{fflush} may be +used to force output to be sent to the pager immediately. @xref{C-Style +I/O Functions}. You can select the program to run as the pager by setting the variable @code{PAGER}, and you can turn paging off by setting the value of the variable @code{page_screen_output} to 0. @deffn {Command} more -Turn output pagination on or off. +@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 @defvr {Built-in Variable} PAGER -The default value is @code{"less"}, or, if @code{less} is not available -on your system, @code{"more"}. @xref{Installation}. +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 @defvr {Built-in Variable} page_screen_output @@ -54,6 +61,13 @@ 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. + +@c XXX FIXME XXX -- maybe this would be a good place to describe the +@c following message: +@c +@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 @@ -91,6 +105,18 @@ 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 @samp{25}. +@end defvr + @deftypefn {Built-in Function} {} disp (@var{x}) Display the value of @var{x}. For example, the following expression @@ -194,9 +220,20 @@ @end table @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 + @node Terminal Input, Simple File I/O, Terminal Output, Basic Input and Output @subsection Terminal Input +Octave has two functions that make it easy to get input from the +terminal. The @code{input} function is normally 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, @@ -251,34 +288,36 @@ @subsection Simple File I/O The @code{save} and @code{load} commands allow data to be written to and -read from disk files in various formats. +read from disk files in various formats. The default format of files +written by the @code{save} command can be controlled using the built-in +variables @code{default_save_format} and @code{save_precision}. + +Note that Octave can not 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. +@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. Using this flag overrides -the value of the built-in variable @code{default_save_format}. +Save the data in Octave's text data format. @item -binary -Save the data in Octave's binary data format. Using this flag overrides -the value of the built-in variable @code{default_save_format}. +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. Using this flag overrides the value of the built-in variable -@code{default_save_format}. You should use this format only if you -know that all the values to be saved can be represented in single -precision. +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. Using this flag overrides -the value of the built-in variable @code{default_save_format}. +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, @@ -301,9 +340,10 @@ match all lower and upper case alphabetic characters. @end table -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. +Except when using hte @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 @@ -383,39 +423,40 @@ argument lists for some of the input functions are slightly different, however, because Octave has no way of passing arguments by reference. -In the following, @var{file} refers either to an integer file number -(as returned by @file{fopen}) or a file name. +In the following, @var{file} refers to a file name and @code{fid} returs +to an integer file number, as returned by @code{fopen}. -There are three files that are always available: +There are three files that are always available. Although these files +can be accessed using their corresponding numeric file ids, you should +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 number 0). When Octave is used +The standard input stream (file id 0). When Octave is used interactively, this is filtered through the command line editing functions. @end defvr @defvr {Built-in Variable} stdout -The standard output stream (file number 1). Data written to the +The standard output stream (file id 1). Data written to the standard output is normally filtered through the pager. @end defvr @defvr {Built-in Variable} stderr -The standard error stream (file number 2). Even if paging is turned on, +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 -You should always use the symbolic names given in the table above, -rather than referring to these files by number, since it will make -your programs clearer. - @menu * Opening and Closing Files:: * Formatted Output:: +* Output Conversion for Matrices:: * Output Conversion Syntax:: * Table of Output Conversions:: * Integer Conversions:: -* Floating-Point Conversions:: +* Floating-Point Conversions:: Other Output Conversions:: * Other Output Conversions:: * Formatted Input:: * Input Conversion Syntax:: @@ -429,19 +470,41 @@ @node Opening and Closing Files, Formatted Output, C-Style I/O Functions, C-Style I/O Functions @subsection Opening and Closing Files -@deftypefn {Built-in Function} {fid =} fopen (@var{name}, @var{mode}) -Opens the named file with the specified mode. Returns an integer value -that may be used to refer to the file later. The @var{mode} is a -one or two character string that specifies whether the file is to be -opened for reading, writing, or both. For example, +@deftypefn {Built-in Function} {[fid, msg] =} fopen (@var{name}, @var{mode}, @var{arch}) +@deftypefnx {Built-in Function} {fid_list =} fopen ("all") +@deftypefnx {Built-in Function} {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 -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"); +myfile = fopen ("splat.dat", "r", "ieee-le"); @end example @noindent -opens the file @file{splat.dat} for reading. Opening a file that is -already open has no effect. +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 @@ -458,7 +521,7 @@ @item @samp{r+} Open an existing file for reading and writing. -@item @samp{w+} +item @samp{w+} Open a file for reading or writing. The previous contents are discared. @@ -466,6 +529,33 @@ 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}) @@ -474,13 +564,15 @@ 0. Otherwise, it returns 1. @end deftypefn -@node Formatted Output, Output Conversion Syntax, Opening and Closing Files, C-Style I/O Functions +@node Formatted Output, Output Conversion for Matrices, Opening and Closing Files, C-Style I/O Functions @subsection Formatted Output This section describes how to call @code{printf} and related functions. The following functions are available for formatted output. They are -modelled after the C language functions of the same name. +modelled after the C language functions of the same name, but they +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 @@ -494,7 +586,7 @@ @end deftypefn @deftypefn {Built-in Function} {} sprintf (@var{template}, @dots{}) -This is like @code{printf}, except that the output is written to a +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 @@ -554,7 +646,10 @@ interpretation vary depending on the particular conversion. They're all described in more detail in the following sections. -@node Output Conversion Syntax, Table of Output Conversions, Formatted Output, C-Style I/O Functions +@node Output Conversion for Matrices, Output Conversion Syntax, Formatted Output, C-Style I/O Functions +@subsection Output Conversion for Matrices + +@node Output Conversion Syntax, Table of Output Conversions, Output Conversion for Matrices, C-Style I/O Functions @subsection Output Conversion Syntax This section provides details about the precise syntax of conversion @@ -836,7 +931,7 @@ @end smallexample @noindent -prints @samp{ nowhere }. +prints @samp{ nowhere } (note the leading and trailing spaces). @node Formatted Input, Input Conversion Syntax, Other Output Conversions, C-Style I/O Functions @subsection Formatted Input @@ -845,17 +940,20 @@ input. @deftypefn {Built-in Function} {} scanf (@var{template}) +@deftypefnx {Built-in Function} {} scanf (@var{template}, "C") The @code{scanf} function reads formatted input from the stream @code{stdin} under the control of the template string @var{template}. The resulting values are returned. @end deftypefn @deftypefn {Built-in Function} {} fscanf (@var{fid}, @var{template}) +@deftypefnx {Built-in Function} {} fscanf (@var{fid}, @var{template}, "C") This function is just like @code{scanf}, except that the input is read from the stream @var{fid} instead of @code{stdin}. @end deftypefn @deftypefn {Built-in Function} {} sscanf (@var{string}, @var{template}) +@deftypefnx {Built-in Function} {} sscanf (@var{string}, @var{template}, "C") This is like @code{scanf}, 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. @@ -1061,9 +1159,9 @@ They are @code{fread} and @code{fwrite} and are patterned after the standard C functions with the same names. -@deftypefn {Built-in Function} {} fread (@var{fid}, @var{size}, @var{precision}) +@deftypefn {Built-in Function} {} fread (@var{fid}, @var{size}, @var{precision}, @var{arch}) This function reads data in binary form of type @var{precision} from the -specified @var{fid}, which may be either a file name, or a file number +specified @var{fid}, which may be either a file name, or a file id as returned from @code{fopen}. The argument @var{size} specifies the size of the matrix to return. It @@ -1084,9 +1182,9 @@ elements read. @end deftypefn -@deftypefn {Built-in Function} {} fwrite (@var{fid}, @var{data}, @var{precision}) +@deftypefn {Built-in Function} {} fwrite (@var{fid}, @var{data}, @var{precision}, @var{arch}) This function writes data in binary form of type @var{precision} to the -specified @var{fid}, which may be either a file name, or a file number +specified @var{fid}, which may be either a file name, or a file id as returned from @code{fopen}. The argument @var{data} is a matrix of values that are to be written to @@ -1107,13 +1205,16 @@ @node Other I/O Functions, , Binary I/O, C-Style I/O Functions @subsection Other I/O Functions -@deftypefn {Built-in Function} {} fgetl (@var{fid}, @var{len}) -Read @samp{len} characters from a file. -@end deftypefn +@menu +* Miscellaneous Output Functions:: +* Miscellaneous Input Functions:: +* File Positioning Functions:: +* File Status Functions:: +* Subprocesses Communication:: +@end menu -@deftypefn {Built-in Function} {} fgets (@var{fid}, @var{len}) -Read @samp{len} characters from a file. -@end deftypefn +@node Miscellaneous Output Functions, Miscellaneous Input Functions, Other I/O Functions, Other I/O Functions +@subsubsection Miscellaneous Output Functions @deftypefn {Built-in Function} {} fflush (@var{fid}) Flush output to @var{fid}. This is useful for ensuring that all @@ -1122,6 +1223,56 @@ stream before calling @code{input}. @end deftypefn +@deftypefn {Built-in Function} {} fputs (@var{fid}, @var{string}) +Write a string to a file with no formatting. +@end deftypefn + +@deftypefn {Built-in Function} {} puts (@var{string}) +Write a string to the standard output with no formatting. +@end deftypefn + +@node Miscellaneous Input Functions, File Positioning Functions, Miscellaneous Output Functions, Other I/O Functions +@subsubsection Miscellaneous Input Functions + +@deftypefn {Built-in Function} {} fgetl (@var{fid}, @var{len}) +Read characters from a file, stopping at the first newline character +that is encountered or after @var{len} characters have been read, and +returning the characters as a string. The newline is not included in +the returned value. + +If @var{len} is omitted, @code{fgetl} reads until the next newline +character. + +If there are no more characters to read, @code{fgetl} returns -1. +@end deftypefn + +@deftypefn {Built-in Function} {} fgets (@var{fid}, @var{len}) +Read characters from a file, stopping at the first newline character +that is encountered or after @var{len} characters have been read, and +returning the characters as a string. The newline is included in the +returned value. + +If @var{len} is omitted, @code{fgets} reads until the next newline +character. + +If there are no more characters to read, @code{fgets} returns -1. +@end deftypefn + +@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, without +requiring a carriage return to be typed. +@end deftypefn + +@node File Positioning Functions, File Status Functions, Miscellaneous Input Functions, Other I/O Functions +@subsubsection File Positioning Functions + Three functions are available for setting and determining the position of the file pointer for a given file. @@ -1164,6 +1315,9 @@ fseek (myfile, marker, SEEK_SET); @end example +@node File Status Functions, Subprocesses Communication, File Positioning Functions, Other I/O Functions +@subsubsection File Status Functions + @deftypefn {Built-in Function} {} feof (@var{fid}) Returns 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 @@ -1178,18 +1332,6 @@ error condition. @end deftypefn -@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, without -requiring a carriage return to be typed. -@end deftypefn - @deftypefn {Built-in Function} {} freport () Finally, it is often useful to know exactly which files have been opened, and whether they are open for reading, writing, or both. The @@ -1198,25 +1340,20 @@ @example @group -octave:13> freport - - number mode name +freport () - 0 r stdin - 1 w stdout - 2 w stderr - 3 r myfile + @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 -@deftypefn {Built-in Function} {} fputs (@var{fid}, @var{string}) -Write a string to a file with no formatting. -@end deftypefn - -@deftypefn {Built-in Function} {} puts (@var{string}) -Write a string to the standard output with no formatting. -@end deftypefn +@node Subprocesses Communication, , File Status Functions, Other I/O Functions +@subsubsection Communication with Subprocesses @deftypefn {Built-in Function} {[@var{in}, @var{out}, @var{pid}] =} popen2 (@var{command}, @var{args}) Start a subprocess with 2-way communication.
--- a/doc/interpreter/linalg.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/linalg.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,11 +2,11 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Linear Algebra, Polynomial Manipulations, Arithmetic, Top +@node Linear Algebra, Nonlinear Equations, Arithmetic, Top @chapter Linear Algebra This chapter documents the linear algebra functions of Octave. -Reference material for many of these options may be found in +Reference material for many of these functions may be found in Golub and Van Loan, @cite{Matrix Computations, 2nd Ed.}, Johns Hopkins, 1989, and in @cite{LAPACK Users' Guide}, SIAM, 1992. @@ -148,7 +148,7 @@ @end deftypefn @deftypefn {Function File} {} orth (@var{a}, @var{tol}) -Returns an orthonormal basis of the range of @var{a}. +Returns 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
--- a/doc/interpreter/lp-foo.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/lp-foo.texi Sat Feb 01 16:57:10 1997 +0000 @@ -1,6 +1,6 @@ @c ------------------------------------------------------------------------ -@node Linear Programming, Quadratic Programming, Quadrature, Top +@node Linear Programming @chapter Linear Programming @cindex LP @cindex linear programming
--- a/doc/interpreter/matrix.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/matrix.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Matrix Manipulation, String Functions, Special Matrices, Top +@node Matrix Manipulation, Special Matrices, Plotting, Top @chapter Matrix Manipulation There are a number of functions available for checking to see if the @@ -85,9 +85,12 @@ @example @group [errorcode, a, b] = common_size ([1 2; 3 4], 5) + @result{} errorcode = 0 - @result{} a = [1 2, 3 4] - @result{} b = [5 5; 5 5] + + @result{} a = [ 1, 2; 3, 4 ] + + @result{} b = [ 5, 5; 5, 5 ] @end group @end example @@ -252,7 +255,9 @@ @example @group rot90 ([1, 2; 3, 4], -1) +@equiv{} rot90 ([1, 2; 3, 4], 3) +@equiv{} rot90 ([1, 2; 3, 4], 7) @end group @end example
--- a/doc/interpreter/nonlin.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/nonlin.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Nonlinear Equations, Differential Equations, Polynomial Manipulations, Top +@node Nonlinear Equations, Quadrature, Linear Algebra, Top @chapter Nonlinear Equations @cindex nonlinear equations @cindex equations, nonlinear
--- a/doc/interpreter/octave.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/octave.texi Sat Feb 01 16:57:10 1997 +0000 @@ -106,45 +106,41 @@ * Preface:: * Introduction:: A brief introduction to Octave. * Invoking Octave:: Command options supported by Octave. +* Basics:: * Expressions:: Expressions. * Statements:: Looping and program flow control. * Functions and Scripts:: * Built-in Variables:: Descriptions of all built-in variables. +* Input and Output:: +* Plotting:: +* Matrix Manipulation:: +* Special Matrices:: +* String Functions:: * Arithmetic:: * Linear Algebra:: -* Polynomial Manipulations:: * Nonlinear Equations:: +* Quadrature:: * Differential Equations:: * Optimization:: -* Quadrature:: +* Statistics:: +* Sets:: +* Polynomial Manipulations:: * Control Theory:: * Signal Processing:: -* Sets:: -* Statistics:: -* Plotting:: * Image Processing:: * Audio Processing:: -* Input and Output:: -* Special Matrices:: -* Matrix Manipulation:: -* String Functions:: * System Utilities:: -* Command History Functions:: -* Help:: * Programming Utilities:: * Amusements:: * Emacs:: * Installation:: How to configure, compile and install Octave. * Trouble:: If you have trouble installing Octave. -* Command Line Editing:: Command history and editing. -* Using Info:: * Copying:: The GNU General Public License. * Concept Index:: An item for each concept. * Variable Index:: An item for each documented variable. * Function Index:: An item for each documented function. * Operator Index:: An item for each documented operator. -* Readline Index:: An index for readline commands. -* Info Index:: An index for info commands. + --- The Detailed Node Listing --- @@ -152,15 +148,36 @@ * Running Octave:: * Simple Examples:: -* Comments:: -* Executable Octave Programs:: -* Errors:: +* Conventions:: + +Conventions + +* Fonts:: +* Evaluation Notation:: +* Printing Notation:: +* Error Messages:: +* Format of Descriptions:: + +Format of Descriptions + +* A Sample Function Description:: +* A Sample Command Description:: +* A Sample Variable Description:: Invoking Octave * Command Line Options:: * Startup Files:: +Basics + +* Comments:: +* Executable Octave Programs:: +* Errors:: +* Help:: +* Command Line Editing:: +* Command History Functions:: + Expressions * Constant Expressions:: @@ -230,6 +247,60 @@ * Miscellaneous Built-in Variables:: * Summary of Preference Variables:: +Input and Output + +* Basic Input and Output:: +* C-Style I/O Functions:: + +Basic Input and Output + +* Terminal Output:: +* Terminal Input:: +* Simple File I/O:: + +C-Style I/O Functions + +* Opening and Closing Files:: +* Formatted Output:: +* Output Conversion for Matrices:: +* Output Conversion Syntax:: +* Table of Output Conversions:: +* Integer Conversions:: +* Floating-Point Conversions:: Other Output Conversions:: +* Other Output Conversions:: +* Formatted Input:: +* Input Conversion Syntax:: +* Table of Input Conversions:: +* Numeric Input Conversions:: +* String Input Conversions:: +* Binary I/O:: +* Other I/O Functions:: + +Other I/O Functions + +* Miscellaneous Output Functions:: +* Miscellaneous Input Functions:: +* File Positioning Functions:: +* File Status Functions:: +* Subprocesses Communication:: + +Plotting + +* Two-Dimensional Plotting:: +* Three-Dimensional Plotting:: +* Multiple Plots on One Page:: +* Miscellaneous Plotting Functions:: + +Matrix Manipulation + +* Finding Elements and Checking Conditions:: +* Rearranging Matrices:: + +Special Matrices + +* Special Utility Matrices:: +* Famous Matrices:: + Arithmetic * Utility Functions:: @@ -245,6 +316,11 @@ * Matrix Factorizations:: * Functions of a Matrix:: +Quadrature + +* Functions of one Variable:: +* Orthogonal Collocation:: + Differential Equations * Ordinary Differential Equations:: @@ -256,56 +332,6 @@ * Nonlinear Programming:: * Linear Least Squares:: -Quadrature - -* Functions of one Variable:: -* Orthogonal Collocation:: - -Plotting - -* Two-Dimensional Plotting:: -* Three-Dimensional Plotting:: -* Multiple Plots on One Page:: -* Miscellaneous Plotting Functions:: - -Input and Output - -* Basic Input and Output:: -* C-Style I/O Functions:: - -Basic Input and Output - -* Terminal Output:: -* Terminal Input:: -* Simple File I/O:: - -C-Style I/O Functions - -* Opening and Closing Files:: -* Formatted Output:: -* Output Conversion Syntax:: -* Table of Output Conversions:: -* Integer Conversions:: -* Floating-Point Conversions:: -* Other Output Conversions:: -* Formatted Input:: -* Input Conversion Syntax:: -* Table of Input Conversions:: -* Numeric Input Conversions:: -* String Input Conversions:: -* Binary I/O:: -* Other I/O Functions:: - -Special Matrices - -* Special Utility Matrices:: -* Famous Matrices:: - -Matrix Manipulation - -* Finding Elements and Checking Conditions:: -* Rearranging Matrices:: - System Utilities * Timing Utilities:: @@ -354,105 +380,35 @@ * Where: Bug Lists. Where to send your bug report. * Reporting: Bug Reporting. How to report a bug effectively. * Patches: Sending Patches. How to send a patch for Octave. - -Command Line Editing - -* Introduction and Notation:: Notation used in this text. -* Readline Interaction:: The minimum set of commands for editing a line. -* Readline Bare Essentials:: -* Readline Movement Commands:: -* Readline Killing Commands:: -* Readline Arguments:: -* Readline Init File:: Customizing Readline from a user's view. -* Readline Init Syntax:: -* Readline Vi Mode:: - -Readline Interaction - -* Readline Bare Essentials:: The least you need to know about Readline. -* Readline Movement Commands:: Moving about the input line. -* Readline Killing Commands:: How to delete text, and how to get it back! -* Readline Arguments:: Giving numeric arguments to commands. - -Readline Init File - -* Readline Init Syntax:: Syntax for the commands in @file{~/.inputrc}. -* Readline Vi Mode:: Switching to @code{vi} mode in Readline. - -Readline Init Syntax - -* Commands For Moving:: Moving about the line. -* Commands For History:: Getting at previous lines. -* Commands For Text:: Commands for changing text. -* Commands For Killing:: Commands for killing and yanking. -* Numeric Arguments:: Specifying numeric arguments, repeat counts. -* Commands For Completion:: Getting Readline to do the typing for you. -* Miscellaneous Commands:: Other miscellaneous commands. - -Using Info - -* Cursor Commands:: -* Scrolling Commands:: -* Node Commands:: -* Searching Commands:: -* Xref Commands:: -* Window Commands:: -* Printing Nodes:: -* Other Info Commands:: -* Info Variables:: - -Using Info - -* Cursor Commands:: Commands which move the cursor within a node. -* Scrolling Commands:: Commands for moving the node around in a window. -* Node Commands:: Commands for selecting a new node. -* Searching Commands:: Commands for searching an info file. -* Xref Commands:: Commands for selecting cross references. -* Window Commands:: Commands which manipulate multiple windows. -* Printing Nodes:: How to print out the contents of a node. -* Other Info Commands:: A few commands that defy categories. -* Info Variables:: How to change the default behavior of Info. - -Selecting Cross References - -* Parts of an Xref:: What a cross reference is made of. -* Selecting Xrefs:: Commands for selecting menu or note items. - -Manipulating Multiple Windows - -* The Mode Line:: What appears in the mode line? -* Basic Windows:: Manipulating windows in Info. -* The Echo Area:: Used for displaying errors and reading input. @end menu @include preface.texi @include intro.texi @include invoke.texi +@include basics.texi @include expr.texi @include stmt.texi @include func.texi @include var.texi +@include io.texi +@include plot.texi +@include matrix.texi +@include special.texi +@include strings.texi @include arith.texi @include linalg.texi -@include poly.texi @include nonlin.texi +@include quad.texi @include diffeq.texi @include optim.texi -@include quad.texi +@include stats.texi +@include set.texi +@include poly.texi @include control.texi @include signal.texi -@include set.texi -@include stats.texi -@include plot.texi @include image.texi @include audio.texi -@include io.texi -@include special.texi -@include matrix.texi -@include strings.texi @include system.texi -@include history.texi -@include help.texi @include program.texi @include amuse.texi @@ -464,33 +420,12 @@ @include emacs.texi @include install.texi @include bugs.texi - -@c Make a separate index for all readline commands, functions, and -@c concepts. -@defindex rd -@syncodeindex cp rd -@syncodeindex fn rd -@syncodeindex ky rd -@syncodeindex vr rd - -@include rluser.texi - -@c Make a separate index for all Info commands, functions, and concepts. -@defindex in -@syncodeindex cp in -@syncodeindex fn in -@syncodeindex ky in -@syncodeindex vr in - -@include gnuinfo.texi @include gpl.texi @include cp-idx.texi @include vr-idx.texi @include fn-idx.texi @include op-idx.texi -@include rd-idx.texi -@include in-idx.texi @contents
--- a/doc/interpreter/op-idx.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/op-idx.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Operator Index, Readline Index, Function Index, Top +@node Operator Index, , Function Index, Top @unnumbered Operator Index @printindex op
--- a/doc/interpreter/optim.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/optim.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Optimization, Quadrature, Differential Equations, Top +@node Optimization, Statistics, Differential Equations, Top @chapter Optimization @menu
--- a/doc/interpreter/plot.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/plot.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Plotting, Image Processing, Statistics, Top +@node Plotting, Matrix Manipulation, Input and Output, Top @chapter Plotting All of Octave's plotting functions use @code{gnuplot} to handle the
--- a/doc/interpreter/poly.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/poly.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Polynomial Manipulations, Nonlinear Equations, Linear Algebra, Top +@node Polynomial Manipulations, Control Theory, Sets, Top @chapter Polynomial Manipulations In Octave, a polynomial is represented by its coefficients (arranged @@ -195,26 +195,22 @@ imaginary part is discarded. If two poles are farther apart than @var{tol} they are distinct. For example, -Example: +@example +@group + b = [1, 1, 1]; -@example - b = [1, 1, 1]; a = [1, -5, 8, -4]; - [r, p, k, e] = residue (b, a) -@end example + [r, p, k, e] = residue (b, a); -@noindent -returns + @result{} r = [-2, 7, 3] -@example -r = [-2, 7, 3] + @result{} p = [2, 2, 1] -p = [2, 2, 1] + @result{} k = [](0x0) -k = [](0x0) - -e = [1, 2, 1] + @result{} e = [1, 2, 1] +@end group @end example @noindent
--- a/doc/interpreter/program.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/program.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Programming Utilities, Amusements, Help, Top +@node Programming Utilities, Amusements, System Utilities, Top @chapter Programming Utilities @menu @@ -73,7 +73,7 @@ @cindex Fordyce, A. P. @findex newtroot Here is a simple-minded function using @code{feval} that finds the root -of a user-supplied function of one variable. +of a user-supplied function of one variable using Newton's method. @example @group @@ -201,7 +201,7 @@ the number of columns, or both are zero). Otherwise, return 0. @end deftypefn -@deffn {Command} clear pattern @dots{} +@deffn {Command} clear options pattern @dots{} Delete the names matching the given patterns from the symbol table. The pattern may contain the following special characters: @table @code @@ -395,7 +395,7 @@ @end example @end deftypefn -@deftypefn {Built-in Function} completion_matches (@var{hint}) +@deftypefn {Built-in Function} {} completion_matches (@var{hint}) Generate possible completions given @var{hint}. This function is provided for the benefit of programs like Emacs which @@ -421,8 +421,7 @@ by the time your program attempts to open it. @end deftypefn -@deffn {Command} type name @dots{} -@deffnx {Command} type [-q] name @dots{} +@deffn {Command} type options name @dots{} Display the definition of each @var{name} that refers to a function. Normally also displays if each @var{name} is user-defined or builtin; @@ -442,7 +441,7 @@ function file, the full name of the file is also displayed. @end deffn -@deftypefn {Built-in Function} octave_config_info () +@deftypefn {Built-in Function} {} octave_config_info () Return a structure containing configuration and installation information. @end deftypefn
--- a/doc/interpreter/quad.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/quad.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Quadrature, Control Theory, Optimization, Top +@node Quadrature, Differential Equations, Nonlinear Equations, Top @chapter Quadrature @menu
--- a/doc/interpreter/rd-idx.texi Fri Jan 31 20:30:22 1997 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,8 +0,0 @@ -@c Copyright (C) 1996 John W. Eaton -@c This is part of the Octave manual. -@c For copying conditions, see the file gpl.texi. - -@node Readline Index, Info Index, Operator Index, Top -@unnumbered Readline Index - -@printindex rd
--- a/doc/interpreter/rluser.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/rluser.texi Sat Feb 01 16:57:10 1997 +0000 @@ -33,7 +33,7 @@ into another language, under the above conditions for modified versions. @end ignore -@node Command Line Editing, Using Info, Trouble, Top +@node Command Line Editing @appendix Command Line Editing This text describes GNU's command line editing interface. It is @@ -53,7 +53,7 @@ * Readline Vi Mode:: @end menu -@node Introduction and Notation, Readline Interaction, Command Line Editing, Command Line Editing +@node Introduction and Notation @appendixsec Introduction to Line Editing The following paragraphs describe the notation we use to represent @@ -76,7 +76,7 @@ stand for themselves when seen in this text, or in an init file (@pxref{Readline Init File}, for more info). -@node Readline Interaction, Readline Bare Essentials, Introduction and Notation, Command Line Editing +@node Readline Interaction @appendixsec Readline Interaction @cindex interaction, readline @@ -98,7 +98,7 @@ * Readline Arguments:: Giving numeric arguments to commands. @end menu -@node Readline Bare Essentials, Readline Movement Commands, Readline Interaction, Command Line Editing +@node Readline Bare Essentials @appendixsec Readline Bare Essentials In order to enter characters into the line, simply type them. The typed @@ -135,7 +135,7 @@ empty line. @end table -@node Readline Movement Commands, Readline Killing Commands, Readline Bare Essentials, Command Line Editing +@node Readline Movement Commands @appendixsec Readline Movement Commands @@ -162,7 +162,7 @@ forward a word. It is a loose convention that control keystrokes operate on characters while meta keystrokes operate on words. -@node Readline Killing Commands, Readline Arguments, Readline Movement Commands, Command Line Editing +@node Readline Killing Commands @appendixsec Readline Killing Commands @dfn{Killing} text means to delete the text from the line, but to save @@ -210,7 +210,7 @@ typed line is available to be yanked back later, when you are typing another line. -@node Readline Arguments, Readline Init File, Readline Killing Commands, Command Line Editing +@node Readline Arguments @appendixsec Readline Arguments You can pass numeric arguments to Readline commands. Sometimes the @@ -228,7 +228,7 @@ the @key{C-d} command an argument of 10, you could type @key{M-1 0 C-d}. -@node Readline Init File, Readline Init Syntax, Readline Arguments, Command Line Editing +@node Readline Init File @appendixsec Readline Init File Although the Readline library comes with a set of Emacs-like @@ -248,7 +248,7 @@ * Readline Vi Mode:: Switching to @code{vi} mode in Readline. @end menu -@node Readline Init Syntax, Readline Vi Mode, Readline Init File, Command Line Editing +@node Readline Init Syntax @appendixsec Readline Init Syntax There are only four constructs allowed in the @file{~/.inputrc} @@ -354,7 +354,7 @@ * Miscellaneous Commands:: Other miscellaneous commands. @end menu -@node Commands For Moving, Commands For History, Readline Init Syntax, Readline Init Syntax +@node Commands For Moving @appendixsubsec Commands For Moving @ftable @code @item beginning-of-line (@key{C-a}) @@ -380,7 +380,7 @@ @end ftable -@node Commands For History, Commands For Text, Commands For Moving, Readline Init Syntax +@node Commands For History @appendixsubsec Commands For Manipulating The History @ftable @code @@ -411,7 +411,7 @@ @end ftable -@node Commands For Text, Commands For Killing, Commands For History, Readline Init Syntax +@node Commands For Text @appendixsubsec Commands For Changing Text @ftable @code @@ -457,7 +457,7 @@ @end ftable -@node Commands For Killing, Numeric Arguments, Commands For Text, Readline Init Syntax +@node Commands For Killing @appendixsubsec Killing And Yanking @ftable @code @@ -492,7 +492,7 @@ the prior command is yank or yank-pop. @end ftable -@node Numeric Arguments, Commands For Completion, Commands For Killing, Readline Init Syntax +@node Numeric Arguments @appendixsubsec Specifying Numeric Arguments @ftable @code @@ -505,7 +505,7 @@ @end ftable -@node Commands For Completion, Miscellaneous Commands, Numeric Arguments, Readline Init Syntax +@node Commands For Completion @appendixsubsec Letting Readline Type For You @ftable @code @@ -521,7 +521,7 @@ List the possible completions of the text before point. @end ftable -@node Miscellaneous Commands, , Commands For Completion, Readline Init Syntax +@node Miscellaneous Commands @appendixsubsec Some Miscellaneous Commands @ftable @code @@ -548,7 +548,7 @@ command enough times to get back to the beginning. @end ftable -@node Readline Vi Mode, , Readline Init Syntax, Command Line Editing +@node Readline Vi Mode @appendixsec Readline Vi Mode While the Readline library does not have a full set of Vi editing
--- a/doc/interpreter/set.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/set.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Sets, Statistics, Signal Processing, Top +@node Sets, Polynomial Manipulations, Statistics, Top @chapter Sets Octave has a limited set of functions for managing sets of data, where a
--- a/doc/interpreter/signal.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/signal.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Signal Processing, Sets, Control Theory, Top +@node Signal Processing, Image Processing, Control Theory, Top @chapter Signal Processing I hope that someday Octave will include more signal processing
--- a/doc/interpreter/special.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/special.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Special Matrices, Matrix Manipulation, Input and Output, Top +@node Special Matrices, String Functions, Matrix Manipulation, Top @chapter Special Matrices Octave provides a number of functions for creating special matrix forms. @@ -41,7 +41,9 @@ @example @group eye (2) +@equiv{} eye (2, 2) +@equiv{} eye (size ([1, 2; 3, 4]) @end group @end example @@ -237,6 +239,20 @@ in order to be compatible with the corresponding @sc{Matlab} function. @end deftypefn +@defvr {Built-in Variable} treat_neg_dim_as_zero +If the value of @code{treat_neg_dim_as_zero} is nonzero, expressions +like + +@example +eye (-1) +@end example + +@noindent +produce an empty matrix (i.e., row and column dimensions are zero). +Otherwise, an error message is printed and control is returned to the +top level. The default value is 0. +@end defvr + @node Famous Matrices, , Special Utility Matrices, Special Matrices @section Famous Matrices
--- a/doc/interpreter/stats.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/stats.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Statistics, Plotting, Sets, Top +@node Statistics, Sets, Optimization, Top @chapter Statistics I hope that someday Octave will include more statistics functions. If
--- a/doc/interpreter/stmt.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/stmt.texi Sat Feb 01 16:57:10 1997 +0000 @@ -268,8 +268,8 @@ with the condition in an @code{if} statement, the condition in a @code{while} statement is considered true if its value is non-zero, and false if its value is zero. If the value of the conditional expression -in an @code{if} statement is a vector or a matrix, it is considered true -only if @emph{all} of the elements are non-zero. +in a @code{while} statement is a vector or a matrix, it is considered +true only if @emph{all} of the elements are non-zero. Octave's @code{while} statement looks like this: @@ -351,8 +351,8 @@ The assignment expression in the @code{for} statement works a bit differently than Octave's normal assignment statement. Instead of assigning the complete result of the expression, it assigns each column -of the expression to @var{var} in turn. If @var{expression} is either -a row vector or a scalar, the value of @var{var} will be a scalar each +of the expression to @var{var} in turn. If @var{expression} is a range, +a row vector, or a scalar, the value of @var{var} will be a scalar each time the loop body is executed. If @var{var} is a column vector or a matrix, @var{var} will be a column vector each time the loop body is executed. @@ -414,25 +414,24 @@ @example @group -octave:1> x.a = 1; x.b = [1, 2; 3, 4]; x.c = "string"; -octave:2> for [val, key] = x; key, val, endfor -@end group -@end example - -@noindent will print +x.a = 1 +x.b = [1, 2; 3, 4] +x.c = "string" +for [val, key] = x + key + val +endfor -@example -@group -key = a -val = 1 -key = b -val = - - 1 2 - 3 4 - -key = c -val = string + @print{} key = a + @print{} val = 1 + @print{} key = b + @print{} val = + @print{} + @print{} 1 2 + @print{} 3 4 + @print{} + @print{} key = c + @print{} val = string @end group @end example @@ -670,29 +669,30 @@ @example @group -x = long_variable_name ... % comment one - + longer_variable_name \ % comment two - - 42 % last comment +x = long_variable_name ... # comment one + + longer_variable_name \ # comment two + - 42 # last comment @end group @end example @noindent -is equivalent to the one shown above. +is equivalent to the one shown above. Inside string constants, the +continuation marker must appear at the end of the line just before the +newline character. -In some cases, Octave will allow you to continue lines without having to -specify continuation characters. For example, it is possible to write -statements like +Input that occurs inside parentheses can be continued to the next line +without having to use a continuation marker. For example, it is +possible to write statements like @example @group -if (big_long_variable_name == other_long_variable_name - || not_so_short_variable_name > 4 - && y > x) - some (code, here); +if (fine_dining_destination == on_a_boat + || fine_dining_destination == on_a_train + suess (i, will, not, eat, them, sam, i, am, i, + will, not, eat, green, eggs, and, ham); endif @end group @end example @noindent -without having to clutter up the if statement with continuation -characters. +without having to add to the clutter with continuation markers.
--- a/doc/interpreter/strings.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/strings.texi Sat Feb 01 16:57:10 1997 +0000 @@ -4,7 +4,7 @@ @cindex strings -@node String Functions, System Utilities, Matrix Manipulation, Top +@node String Functions, Arithmetic, Special Matrices, Top @chapter String Functions @deftypefn {Function File} {} strcmp (@var{s1}, @var{s2}) @@ -28,14 +28,10 @@ character. For example, @example +@group setstr ([97, 98, 99]) -@end example - -@noindent -creates the string - -@example -abc + @result{} "abc" +@end group @end example @end deftypefn @@ -79,11 +75,11 @@ @example bin2dec ("1110") - @result{} 14 + @result{} 14 @end example @end deftypefn -@deftypefn {Function File} {} blanks (var{n}) +@deftypefn {Function File} {} blanks (@var{n}) Returns a string of @var{n} blanks. @end deftypefn @@ -97,7 +93,7 @@ @example dec2bin (14) - @result{} "1110" + @result{} "1110" @end example @end deftypefn @@ -107,7 +103,7 @@ @example dec2hex (2748) - @result{} "abc" + @result{} "abc" @end example @end deftypefn @@ -119,9 +115,9 @@ @example findstr ("ababab", "a") - @result{} [1 3 5] + @result{} [1 3 5] findstr ("abababa", "aba", 0) - @result{} [1, 5] + @result{} [1, 5] @end example @end deftypefn @@ -131,9 +127,9 @@ @example hex2dec ("12B") - @result{} 299 + @result{} 299 hex2dec ("12b") - @result{} 299 + @result{} 299 @end example @end deftypefn @@ -143,7 +139,7 @@ @example index ("Teststring", "t") - @result{} 4 + @result{} 4 @end example @strong{Note:} This function does not work for arrays of strings. @@ -155,7 +151,7 @@ @example rindex ("Teststring", "t") - @result{} 6 + @result{} 6 @end example @strong{Note:} This function does not work for arrays of strings. @@ -168,9 +164,9 @@ @example split ("Test string", "t") - @result{} Tes - s - ring + @result{} Tes + s + ring @end example @end deftypefn @@ -199,7 +195,7 @@ @example strrep ("This is a test string", "is", "&%$") - @result{} Th&%$ &%$ a test string + @result{} Th&%$ &%$ a test string @end example @end deftypefn @@ -209,7 +205,7 @@ @example substr ("This is a test string", 6, 9) - @result{} is a test + @result{} is a test @end example @quotation @@ -226,7 +222,7 @@ @example tolower ("MiXeD cAsE 123") - @result{} "mixed case 123" + @result{} "mixed case 123" @end example @end deftypefn @@ -238,7 +234,7 @@ @example @group toupper ("MiXeD cAsE 123") - @result{} "MIXED CASE 123" + @result{} "MIXED CASE 123" @end group @end example @end deftypefn @@ -249,7 +245,7 @@ @example @group toascii ("ASCII") - @result{} [ 65, 83, 67, 73, 73 ] + @result{} [ 65, 83, 67, 73, 73 ] @end group @end example @@ -261,49 +257,52 @@ was true for the corresponding character in the string array. @deftypefn {Mapping Function} {} isalnum (@var{s}) -letter or a digit +Returns true for characters that are letters or digits (@code{isalpha +(@var{a})} or @code{isdigit (@var{})} is true). @end deftypefn @deftypefn {Mapping Function} {} isalpha (@var{s}) -letter +Returns true for characters that are letters (@code{isupper (@var{a})} +or @code{islower (@var{})} is true). @end deftypefn @deftypefn {Mapping Function} {} isascii (@var{s}) -ascii +Returns true for characters that are ASCII (in the range 0 to 127 decimal). @end deftypefn @deftypefn {Mapping Function} {} iscntrl (@var{s}) -control character +Returns true for control characters. @end deftypefn @deftypefn {Mapping Function} {} isdigit (@var{s}) -digit +Returns true for characters that are decimal digits. @end deftypefn @deftypefn {Mapping Function} {} isgraph (@var{s}) -printable (but not space character) +Returns true for printable characters (but not the space character). @end deftypefn @deftypefn {Mapping Function} {} islower (@var{s}) -lower case +Returns true for characters that are lower case letters. @end deftypefn @deftypefn {Mapping Function} {} isprint (@var{s}) -printable (including space character) +Returns true for printable characters (including the space character). @end deftypefn @deftypefn {Mapping Function} {} ispunct (@var{s}) -punctuation +Returns true for punctuation characters. @end deftypefn @deftypefn {Mapping Function} {} isspace (@var{s}) -whitespace +Returns true for whitespace characters (space, formfeed, newline, +carriage return, tab, and vertical tab). @end deftypefn @deftypefn {Mapping Function} {} isupper (@var{s}) -upper case +Returns true for upper case letters. @end deftypefn @deftypefn {Mapping Function} {} isxdigit (@var{s}) -hexadecimal digit +Returns true for characters that are hexadecimal digits. @end deftypefn
--- a/doc/interpreter/system.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/system.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node System Utilities, Command History Functions, String Functions, Top +@node System Utilities, Programming Utilities, Audio Processing, Top @chapter System Utilities This chapter describes the functions that are available to allow you to @@ -30,7 +30,7 @@ 1970. @end deftypefn -Several of Octave's time functions a data structure for time that +Several of Octave's time functions use a data structure for time that includes the following elements: @table @code @@ -120,10 +120,10 @@ Numeric modifiers (a nonstandard extension): @table @code -@item - +@item - (dash) Do not pad the field. -@item _ +@item _ (underscore) Pad the field with spaces. @end table @@ -256,21 +256,6 @@ @end example @end deftypefn -@deftypefn {Function File} {} tic () -@deftypefnx {Function File} {} toc () -These functions set and check a wall-clock timer. For example, - -@example -tic (); -# many computations later... -elapsed_time = toc (); -@end example - -@noindent -will set the variable @code{elapsed_time} to the number of seconds since -the most recent call to the function @code{tic}. -@end deftypefn - @deftypefn {Function File} {} etime (@var{t1}, @var{t2}) Return the difference (in seconds) between two time values returned from @code{clock}. For example: @@ -293,6 +278,9 @@ executing in user mode and the number of CPU seconds spent executing in system mode, respectively. If your system does not have a way to report CPU time usage, @code{cputime} returns 0 for each of its output values. +Note that because Octave used some CPU time to start, it is reasonable +to check to see if @code{cputime} works by checking to see if the total +CPU time used is nonzero. @end deftypefn @deftypefn {Function File} {} is_leap_year (@var{year}) @@ -306,6 +294,40 @@ @end example @end deftypefn +@deftypefn {Function File} {} tic () +@deftypefnx {Function File} {} toc () +These functions set and check a wall-clock timer. For example, + +@example +tic (); +# many computations later... +elapsed_time = toc (); +@end example + +@noindent +will set the variable @code{elapsed_time} to the number of seconds since +the most recent call to the function @code{tic}. + +If you are more interested in the CPU time that your process used, you +should use the @code{cputime} function instead. The @code{tic} and +@code{toc} functions report the actual wall clock time that elapsed +between the calls. This may include time spent processing other jobs or +doing nothing at all. For example, + +@example +@group +tic (); sleep (5); toc () + @result{} 5 +t = cputime (); sleep (5); cputime () - t + @result{} 0 +@end group +@end example + +@noindent +(This example also illustrates that the CPU timer may have a fairly +coarse resolution.) +@end deftypefn + @node Filesystem Utilities, Interacting with the OS, Timing Utilities, System Utilities @section Filesystem Utilities @@ -436,8 +458,41 @@ Create a FIFO special file. @end deftypefn -@deftypefn {Built-in Function} {} waitpid -Check the status of or wait for subprocesses. +@deftypefn {Built-in Function} {} waitpid (@var{pid}, @var{options}) +Wait for process @var{pid} to terminate. The @var{pid} argument can be: + +@table @asis +@item -1 +Wait for any child process. + +@item 0 +Wait for any child process whose process group ID is equal to that of +the Octave interpreter process. + +@item > 0 +Wait for termination of the child process with ID @var{PID}. +@end table + +The @var{options} argument can be: + +@table @asis +@item 0 +Wait until signal is received or a child process exits (this is the +default if the @var{options} argument is missing). + +@item 1 +Do not hang if status is not immediately available. + +@item 2 +Report the status of any child processes that are stopped, and whose +status has not yet been reported since they stopped. + +@item 3 +Implies both 1 and 2. +@end table + +If the return value is greater than 0, it is the process ID of the child +process that exited. If an error occurs, -1 is returned. @end deftypefn @deftypefn {Built-in Function} {} atexit (@var{fcn}) @@ -551,8 +606,8 @@ command. @end defvr -@deffn {Command} ls -@deffnx {Command} dir +@deffn {Command} ls options +@deffnx {Command} dir options List directory contents. For example, @example @@ -775,3 +830,23 @@ @end group @end example @end deftypefn + +@deftypefn {Built-in Function} {} sleep (@var{seconds}) +Suspend the execution of the program. +@end deftypefn + +@deftypefn {Built-in Function} {} usleep (@var{microseconds}) +Suspend the execution of the program. +@end deftypefn + +@c XXX FIXME XXX -- not really sure where these should go. + +@cindex exiting octave +@cindex quitting octave + +@deftypefn {Built-in Function} {} exit (@var{status}) +@deftypefnx {Built-in Function} {} quit (@var{status}) +Exit the current Octave session. If the optional integer value +@var{status} is supplied, pass that value to the operating system as the +Octave's exit status. +@end deftypefn
--- a/doc/interpreter/using.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/using.texi Sat Feb 01 16:57:10 1997 +0000 @@ -9,7 +9,7 @@ @cindex Octave language @cindex @code{octave} program -@node Using this Manual, Introduction, Acknowledgements, Top +@node Using this Manual @chapter Using the Manual The term Octave refers to a particular program, and to the language you
--- a/doc/interpreter/var.texi Fri Jan 31 20:30:22 1997 +0000 +++ b/doc/interpreter/var.texi Sat Feb 01 16:57:10 1997 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Built-in Variables, Arithmetic, Functions and Scripts, Top +@node Built-in Variables, Input and Output, Functions and Scripts, Top @chapter Built-in Variables @cindex variables @cindex built-in variables @@ -45,95 +45,6 @@ The version number of Octave, as a string. @end defvr -@defvr {Built-in Variable} PS1 -The primary prompt string. When executing interactively, Octave -displays the primary prompt @code{PS1} when it is ready to read a -command. Octave allows the prompt to be customized by inserting a -number of backslash-escaped special characters that are decoded as -follows: - -@table @samp -@item \t -The time. -@item \d -The date. -@item \n -Begins a new line by printing the equivalent of a carriage return -followed by a line feed. -@item \s -The name of the program (usually just @code{octave}). -@item \w -The current working directory. -@item \W -The basename of the current working directory. -@item \u -The username of the current user. -@item \h -The hostname. -@item \H -The hostname, up to the first `.'. -@item \# -The command number of this command, counting from when Octave starts. -@item \! -The history number of this command. This differs from @samp{\#} by the -number of commands in the history list when Octave starts. -@item \$ -If the effective UID is 0, a #, otherwise a $. -@item \nnn -The character whose character code in octal is @samp{nnn}. -@item \\ -A backslash. -@end table - -The default value of @code{PS1} is @code{"\s:\#> "}. To change it, use a -command like - -@example -octave:13> PS1 = "\\u@@\\H> " -@end example - -@noindent -which will result in the prompt @samp{boris@@kremvax> } for the user -@samp{boris} logged in on the host @samp{kremvax.kgb.su}. Note that two -backslashes are required to enter a backslash into a string. -@xref{String Constants}. -@end defvr - -@defvr {Built-in Variable} PS2 -The secondary prompt string, which is printed when Octave is -expecting additional input to complete a command. For example, when -defining a function over several lines, Octave will print the value of -@code{PS1} at the beginning of each line after the first. Octave allows -@code{PS2} to be customized in the same way as @code{PS1}. The default -value of @code{PS2} is @code{"> "}. -@end defvr - -@defvr {Built-in Variable} PS4 -If Octave is invoked with the @code{--echo-input} option, the value of -@code{PS4} is printed before each line of input that is echoed. Octave -allows @code{PS4} to be customized in the same way as @code{PS1}. The -default value of @code{PS4} is @code{"+ "}. @xref{Invoking Octave}, for -a description of @code{--echo-input}. -@end defvr - -@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 @samp{25}. -@end defvr - -@defvr {Built-in Variable} completion_append_char -The value of @code{completion_append_char} is used as the character to -append to successful command-line completion attempts. The default -value is @code{" "} (a single space). -@end defvr - @defvr {Built-in Variable} ok_to_lose_imaginary_part If the value of @code{ok_to_lose_imaginary_part} is nonzero, implicit conversions of complex numbers to real numbers are allowed (for @@ -142,12 +53,6 @@ control is returned to the top level. The default value is @code{"warn"}. @end defvr -@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 - @defvr {Built-in Variable} propagate_empty_matrices If the value of @code{propagate_empty_matrices} is nonzero, functions like @code{inverse} and @code{svd} will return an empty matrix @@ -155,20 +60,6 @@ @xref{Empty Matrices}. @end defvr -@defvr {Built-in Variable} treat_neg_dim_as_zero -If the value of @code{treat_neg_dim_as_zero} is nonzero, expressions -like - -@example -eye (-1) -@end example - -@noindent -produce an empty matrix (i.e., row and column dimensions are zero). -Otherwise, an error message is printed and control is returned to the -top level. The default value is 0. -@end defvr - @node Summary of Preference Variables, , Miscellaneous Built-in Variables, Built-in Variables @section Summary of Preference Variables @@ -179,55 +70,136 @@ system for which Octave was compiled (for example, @code{alpha-dec-osf3.2}). -@smallexample -EDITOR "vi" -EXEC_PATH ":$PATH" -INFO_FILE "OCT_HOME/info/octave.info" -INFO_PROGRAM "OCT_HOME/libexec/octave/VERSION/exec/SYS/info" -LOADPATH ".:OCT_HOME/lib/VERSION" -PAGER "less", or "more" -PS1 "\s:\#> " -PS2 "> " -PS4 "+ " -automatic_replot 0 +@table @code +@item EDITOR +Default value: @code{"vi"}. + +@item EXEC_PATH +Default value: @code{":$PATH"}. + +@item INFO_FILE +Default value: @code{"OCT_HOME/info/octave.info"}. + +@item INFO_PROGRAM +Default value: @code{"OCT_HOME/libexec/octave/VERSION/exec/SYS/info"}. + +@item LOADPATH +Default value: @code{".:OCT_HOME/lib/VERSION"}. + +@item PAGER +Default value: @code{"less", or "more"}. + +@item PS1 +Default value: @code{"\s:\#> "}. + +@item PS2 +Default value: @code{"> "}. + +@item PS4 +Default value: @code{"+ "}. + +@item automatic_replot +Default value: 0. -beep_on_error 0 -completion_append_char " " -default_return_value [] -do_fortran_indexing 0 -define_all_return_values 0 -empty_list_elements_ok "warn" -gnuplot_binary "gnuplot" -history_file "~/.octave_hist" -history_size 1024 -ignore_function_time_stamp "system" +@item beep_on_error +Default value: 0. + +@item completion_append_char +Default value: @code{" "}. + +@item default_return_value +Default value: @code{[]}. + +@item do_fortran_indexing +Default value: 0. + +@item define_all_return_values +Default value: 0. + +@item empty_list_elements_ok +Default value: @code{"warn"}. + +@item gnuplot_binary +Default value: @code{"gnuplot"}. + +@item history_file +Default value: @code{"~/.octave_hist"}. + +@item history_size +Default value: 1024. + +@item ignore_function_time_stamp +Default value: @code{"system"}. + +@item implicit_str_to_num_ok +Default value: 0. -implicit_str_to_num_ok 0 -ok_to_lose_imaginary_part "warn" -output_max_field_width 10 -output_precision 5 -page_screen_output 1 -prefer_column_vectors 0 -prefer_zero_one_indexing 0 -print_answer_id_name 1 -print_empty_dimensions 1 -resize_on_range_error 1 +@item ok_to_lose_imaginary_part +Default value: @code{"warn"}. + +@item output_max_field_width +Default value: 10. + +@item output_precision +Default value: 5. + +@item page_screen_output +Default value: 1. + +@item prefer_column_vectors +Default value: 0. + +@item prefer_zero_one_indexing +Default value: 0. + +@item print_answer_id_name +Default value: 1. + +@item print_empty_dimensions +Default value: 1. + +@item resize_on_range_error +Default value: 1. + +@item return_last_computed_value +Default value: 0. + +@item save_precision +Default value: 17. -return_last_computed_value 0 -save_precision 17 -saving_history 1 -silent_functions 0 -split_long_rows 1 -struct_levels_to_print 2 -suppress_verbose_help_message 1 -treat_neg_dim_as_zero 0 -warn_assign_as_truth_value 1 -warn_comma_in_global_decl 1 +@item saving_history +Default value: 1. + +@item silent_functions +Default value: 0. + +@item split_long_rows +Default value: 1. + +@item struct_levels_to_print +Default value: 2. + +@item suppress_verbose_help_message +Default value: 1. -warn_divide_by_zero 1 -warn_function_name_clash 1 -whitespace_in_literal_matrix "" -@end smallexample +@item treat_neg_dim_as_zero +Default value: 0. + +@item warn_assign_as_truth_value +Default value: 1. + +@item warn_comma_in_global_decl +Default value: 1. + +@item warn_divide_by_zero +Default value: 1. + +@item warn_function_name_clash +Default value: 1. + +@item whitespace_in_literal_matrix +Default value: @code{""}. +@end table The following variables may be set from the environment or by a command line option.