   Copyright (C) 1996, 1997 John W. Eaton.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

   This manual documents how to run, install and port GNU Octave, as
well as its new features and incompatibilities, and how to report bugs.
It corresponds to GNU Octave version 2.1.x.

Error Handling

Debugging

Preface
*******

   Octave was originally intended to be companion software for an
undergraduate-level textbook on chemical reactor design being written by
James B. Rawlings of the University of Wisconsin-Madison and John G.
Ekerdt of the University of Texas.

   Clearly, Octave is now much more than just another `courseware'
package with limited utility beyond the classroom.  Although our
initial goals were somewhat vague, we knew that we wanted to create
something that would enable students to solve realistic problems, and
that they could use for many things other than chemical reactor design
problems.

   There are those who would say that we should be teaching the students
Fortran instead, because that is the computer language of engineering,
but every time we have tried that, the students have spent far too much
time trying to figure out why their Fortran code crashes and not enough
time learning about chemical engineering.  With Octave, most students
pick up the basics quickly, and are using it confidently in just a few
hours.

   Although it was originally intended to be used to teach reactor
design, it has been used in several other undergraduate and graduate
courses in the Chemical Engineering Department at the University of
Texas, and the math department at the University of Texas has been using
it for teaching differential equations and linear algebra as well.  If
you find it useful, please let us know.  We are always interested to
find out how Octave is being used in other places.

   Virtually everyone thinks that the name Octave has something to do
with music, but it is actually the name of a former professor of mine
who wrote a famous textbook on chemical reaction engineering, and who
was also well known for his ability to do quick `back of the envelope'
calculations.  We hope that this software will make it possible for many
people to do more ambitious computations just as easily.

   Everyone is encouraged to share this software with others under the
terms of the GNU General Public License (see Copying) as described
at the beginning of this manual.  You are also encouraged to help make
Octave more useful by writing and contributing additional functions for
it, and by reporting any problems you may have.

Acknowledgements
================

   Many people have already contributed to Octave's development.  In
addition to John W. Eaton, the following people have helped write parts
of Octave or helped out in various other ways.

   * Thomas Baier <baier@ci.tuwien.ac.at> wrote the original versions
     of `popen', `pclose', `execute', `sync_system', and `async_system'.

   * Karl Berry <karl@cs.umb.edu> wrote the `kpathsea' library that
     allows Octave to recursively search directory paths for function
     and script files.

   * Georg Beyerle <gbeyerle@awi-potsdam.de> contributed code to save
     values in MATLAB's `.mat'-file format, and has provided many
     useful bug reports and suggestions.

   * John Campbell <jcc@bevo.che.wisc.edu> wrote most of the file and
     C-style input and output functions.

   * Dirk Eddelbuettel <edd@debian.org> makes Octave easy to install
     for users of Debian GNU/Linux.

   * Brian Fox <bfox@gnu.org> wrote the `readline' library used for
     command history editing, and the portion of this manual that
     documents it.

   * Klaus Gebhardt <gebhardt@crunch.ikp.physik.th-darmstadt.de> ported
     Octave to OS/2.

   * Kai Habel <kai.habel@gmx.de> implemted functions for performing
     coordinate transformations.

   * A. Scottedward Hodel <A.S.Hodel@eng.auburn.edu> contributed a
     number of functions including `expm', `qzval', `qzhess', `syl',
     `lyap', and `balance'.

   * Kurt Hornik <Kurt.Hornik@ci.tuwien.ac.at> provided the `corrcoef',
     `cov', `fftconv', `fftfilt', `gcd', `lcd', `kurtosis', `null',
     `orth', `poly', `polyfit', `roots', and `skewness' functions,
     supplied documentation for these and numerous other functions,
     rewrote the Emacs mode for editing Octave code and provided its
     documentation, and has helped tremendously with testing.  He has
     also been a constant source of new ideas for improving Octave.

   * Cai Jianming <caijianming@yahoo.co.uk> contributed the inital cell
     array implementation.

   * Phil Johnson <johnsonp@nicco.sscnet.ucla.edu> has helped to make
     Linux releases available.

   * Steven G. Johnson <stevenj@alum.mit.edu> added support for ATLAS,
     saving data in HDF5 files, and ported Octave's configure script to
     Autoconf 2.50.

   * Mumit Khan <khan@nanotech.wisc.edu> helped make it possible for
     Octave to be compiled by ISO standard C++ compilers other than GCC.

   * Paul Kienzle <pkienzle@users.sf.net> has provided many
     enhancements to improve Octave's compatibility with MATLAB, and
     also maintains the collection of conributed code at
     <http://octave.sf.net>.

   * Bill Lash <lash@tellabs.com> provided the `unwrap' function.

   * Dirk Laurie <dirk@calvyn.puk.ac.za> rewrote `invhilb' to be faster
     and more accurate.

   * Friedrich Leisch <leisch@ci.tuwien.ac.at> provided the
     `mahalanobis' function.

   * Ken Neighbors <wkn@leland.stanford.edu> has provided many useful
     bug reports and comments on MATLAB compatibility.

   * Rick Niles <niles@axp745.gsfc.nasa.gov> rewrote Octave's plotting
     functions to add line styles and the ability to specify an
     unlimited number of lines in a single call.  He also continues to
     track down odd incompatibilities and bugs.

   * Mark Odegard <meo@getech.com> provided the initial implementation
     of `fread', `fwrite', `feof', and `ferror'.

   * Gabriele Pannocchia  <pannocchia@ing.unipi.it> provided the
     `dkalman.m' function and added support for singular system matrices
     to `dlqe' and `dlqr'.

   * Tony Richardson <arichard@stark.cc.oh.us> wrote Octave's image
     processing functions as well as most of the original polynomial
     functions.

   * Ben Sapp <bsapp@lanl.gov> implemented the debugger functions and
     added Texinfo markup commands to the internal doc strings.

   * R. Bruce Tenison <btenison@rstc.cc.al.us> wrote the `hess' and
     `schur' functions.

   * Teresa Twaroch <twaroch@ci.tuwien.ac.at> provided the functions
     `gls' and `ols'.

   * James R. Van Zandt <jrv@vanzandt.mv.com> added support for reading
     and writing MATLAB version 5 binary data files.

   * Andreas Weingessel <Andreas.Weingessel@ci.tuwien.ac.at> wrote the
     audio functions `lin2mu', `loadaudio', `mu2lin', `playaudio',
     `record', `saveaudio', and `setaudio'.

   * Fook Fah Yap <ffy@eng.cam.ac.uk> provided the `fft' and `ifft'
     functions and valuable bug reports for early versions.

   Special thanks to the following people and organizations for
supporting the development of Octave:

   * The National Science Foundation, through grant numbers CTS-0105360,
     CTS-9708497, CTS-9311420, and CTS-8957123.

   * The industrial members of the Texas-Wisconsin Modeling and Control
     Consortium (TWMCC (http://www.che.utexas.edu/twmcc)).

   * The Paul A. Elfers Endowed Chair in Chemical Engineering at the
     University of Wisconsin-Madison.

   * Digital Equipment Corporation, for an equipment grant as part of
     their External Research Program.

   * Sun Microsystems, Inc., for an Academic Equipment grant.

   * International Business Machines, Inc., for providing equipment as
     part of a grant to the University of Texas College of Engineering.

   * Texaco Chemical Company, for providing funding to continue the
     development of this software.

   * The University of Texas College of Engineering, for providing a
     Challenge for Excellence Research Supplement, and for providing an
     Academic Development Funds grant.

   * The State of Texas, for providing funding through the Texas
     Advanced Technology Program under Grant No. 003658-078.

   * Noel Bell, Senior Engineer, Texaco Chemical Company, Austin Texas.

   * James B. Rawlings, Professor, University of Wisconsin-Madison,
     Department of Chemical Engineering.

   * Richard Stallman, for writing GNU.

   This project would not have been possible without the GNU software
used in and used to produce Octave.

How You Can Contribute to Octave
================================

   There are a number of ways that you can contribute to help make
Octave a better system.  Perhaps the most important way to contribute
is to write high-quality code for solving new problems, and to make
your code freely available for others to use.

   If you find Octave useful, consider providing additional funding to
continue its development.  Even a modest amount of additional funding
could make a significant difference in the amount of time that is
available for development and support.

   If you cannot provide funding or contribute code, you can still help
make Octave better and more reliable by reporting any bugs you find and
by offering suggestions for ways to improve Octave.  See Trouble,
for tips on how to write useful bug reports.

Distribution
============

   Octave is "free" software.  This means that everyone is free to use
it and free to redistribute it on certain conditions.  Octave is not in
the public domain.  It is copyrighted and there are restrictions on its
distribution, but the restrictions are designed to ensure that others
will have the same freedom to use and redistribute Octave that you
have.  The precise conditions can be found in the GNU General Public
License that comes with Octave and that also appears in Copying.

   Octave is available on CD-ROM with various collections of other free
software, and from the Free Software Foundation.  Ordering a copy of
Octave from the Free Software Foundation helps to fund the development
of more free software.  For more information, write to

     Free Software Foundation
     59 Temple Place--Suite 330
     Boston, MA 02111-1307
     USA

   Octave is also available on the Internet from
<ftp://ftp.che.wisc.edu/pub/octave>, and additional information is
available from <http://www.che.wisc.edu/octave>.

A Brief Introduction to Octave
******************************

   This manual documents how to run, install and port GNU Octave, and
how to report bugs.

   GNU Octave is a high-level language, primarily intended for numerical
computations.  It provides a convenient command line interface for
solving linear and nonlinear problems numerically, and for performing
other numerical experiments.  It may also be used as a batch-oriented
language.

   GNU Octave is also freely redistributable software.  You may
redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation.  The GPL is
included in this manual in Copying.

   This document corresponds to Octave version 2.1.x.

Running Octave
==============

   On most systems, the way to invoke Octave is with the shell command
`octave'.  Octave displays an initial message and then a prompt
indicating it is ready to accept input.  You can begin typing Octave
commands immediately afterward.

   If you get into trouble, you can usually interrupt Octave by typing
`Control-C' (usually written `C-c' for short).  `C-c' gets its name
from the fact that you type it by holding down <CTRL> and then pressing
<c>.  Doing this will normally return you to Octave's prompt.

   To exit Octave, type `quit', or `exit' at the Octave prompt.

   On systems that support job control, you can suspend Octave by
sending it a `SIGTSTP' signal, usually by typing `C-z'.

Simple Examples
===============

   The following chapters describe all of Octave's features in detail,
but before doing that, it might be helpful to give a sampling of some
of its capabilities.

   If you are new to Octave, I recommend that you try these examples to
begin learning Octave by using it.  Lines marked with `octave:13>' are
lines you type, ending each with a carriage return.  Octave will
respond with an answer, or by displaying a graph.

Creating a Matrix
-----------------

   To create a new matrix and store it in a variable so that it you can
refer to it later, type the command

     octave:1> a = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ]

Octave will respond by printing the matrix in neatly aligned columns.
Ending a command with a semicolon tells Octave to not print the result
of a command.  For example

     octave:2> b = rand (3, 2);

will create a 3 row, 2 column matrix with each element set to a random
value between zero and one.

   To display the value of any variable, simply type the name of the
variable.  For example, to display the value stored in the matrix `b',
type the command

     octave:3> b

Matrix Arithmetic
-----------------

   Octave has a convenient operator notation for performing matrix
arithmetic.  For example, to multiply the matrix `a' by a scalar value,
type the command

     octave:4> 2 * a

   To multiply the two matrices `a' and `b', type the command

     octave:5> a * b

   To form the matrix product `transpose (a) * a', type the command

     octave:6> a' * a

Solving Linear Equations
------------------------

   To solve the set of linear equations `aX = b', use the left division
operator, `\':

     octave:7> a \ b

This is conceptually equivalent to `inv (a) * b', but avoids computing
the inverse of a matrix directly.

   If the coefficient matrix is singular, Octave will print a warning
message and compute a minimum norm solution.

Integrating Differential Equations
----------------------------------

   Octave has built-in functions for solving nonlinear differential
equations of the form

     dx
     -- = f (x, t)
     dt

with the initial condition

     x(t = t0) = x0

For Octave to integrate equations of this form, you must first provide a
definition of the function `f(x,t)'.  This is straightforward, and may
be accomplished by entering the function body directly on the command
line.  For example, the following commands define the right hand side
function for an interesting pair of nonlinear differential equations.
Note that while you are entering a function, Octave responds with a
different prompt, to indicate that it is waiting for you to complete
your input.

     octave:8> function xdot = f (x, t)
     >
     >  r = 0.25;
     >  k = 1.4;
     >  a = 1.5;
     >  b = 0.16;
     >  c = 0.9;
     >  d = 0.8;
     >
     >  xdot(1) = r*x(1)*(1 - x(1)/k) - a*x(1)*x(2)/(1 + b*x(1));
     >  xdot(2) = c*a*x(1)*x(2)/(1 + b*x(1)) - d*x(2);
     >
     > endfunction

Given the initial condition

     x0 = [1; 2];

and the set of output times as a column vector (note that the first
output time corresponds to the initial condition given above)

     t = linspace (0, 50, 200)';

it is easy to integrate the set of differential equations:

     x = lsode ("f", x0, t);

The function `lsode' uses the Livermore Solver for Ordinary
Differential Equations, described in A. C. Hindmarsh, `ODEPACK, a
Systematized Collection of ODE Solvers', in: Scientific Computing, R. S.
Stepleman et al. (Eds.), North-Holland, Amsterdam, 1983, pages 55-64.

Producing Graphical Output
--------------------------

   To display the solution of the previous example graphically, use the
command

     plot (t, x)

   If you are using the X Window System, Octave will automatically
create a separate window to display the plot.  If you are using a
terminal that supports some other graphics commands, you will need to
tell Octave what kind of terminal you have.  Type the command

     gset term

to see a list of the supported terminal types.  Octave uses `gnuplot'
to display graphics, and can display graphics on any terminal that is
supported by `gnuplot'.

   To capture the output of the plot command in a file rather than
sending the output directly to your terminal, you can use a set of
commands like this

     gset term postscript
     gset output "foo.ps"
     replot

This will work for other types of output devices as well.  Octave's
`gset' command is really just piped to the `gnuplot' subprocess, so
that once you have a plot on the screen that you like, you should be
able to do something like this to create an output file suitable for
your graphics printer.

   Or, you can eliminate the intermediate file by using commands like
this

     gset term postscript
     gset output "|lpr -Pname_of_your_graphics_printer"
     replot

Editing What You Have Typed
---------------------------

   At the Octave prompt, you can recall, edit, and reissue previous
commands using Emacs- or vi-style editing commands.  The default
keybindings use Emacs-style commands.  For example, to recall the
previous command, type `Control-p' (usually written `C-p' for short).
`C-p' gets its name from the fact that you type it by holding down
<CTRL> and then pressing <p>.  Doing this will normally bring back the
previous line of input.  `C-n' will bring up the next line of input,
`C-b' will move the cursor backward on the line, `C-f' will move the
cursor forward on the line, etc.

   A complete description of the command line editing capability is
given in this manual in Command Line Editing.

Help and Documentation
----------------------

   Octave has an extensive help facility.  The same documentation that
is available in printed form is also available from the Octave prompt,
because both forms of the documentation are created from the same input
file.

   In order to get good help you first need to know the name of the
command that you want to use.  This name of the function may not always
be obvious, but a good place to start is to just type `help'.  This
will show you all the operators, reserved words, functions, built-in
variables, and function files.  You can then get more help on anything
that is listed by simply including the name as an argument to help.
For example,

     help plot

will display the help text for the `plot' function.

   Octave sends output that is too long to fit on one screen through a
pager like `less' or `more'.  Type a <RET> to advance one line, a <SPC>
to advance one page, and <q> to exit the pager.

   The part of Octave's help facility that allows you to read the
complete 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 Getting Help.

Conventions
===========

   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.

Fonts
-----

   Examples of Octave code appear in this font or form: `svd (a)'.
Names that represent arguments or metasyntactic variables appear in
this font or form: FIRST-NUMBER.  Commands that you type at the shell
prompt sometimes appear in this font or form: `octave --no-init-file'.
Commands that you type at the Octave prompt sometimes appear in this
font or form: `foo --bar --baz'.  Specific keys on your keyboard appear
in this font or form: <ANY>.

Evaluation Notation
-------------------

   In the examples in this manual, results from expressions that you
evaluate are indicated with `=>'.  For example,

     sqrt (2)
          => 1.4142

You can read this as "`sqrt (2)' evaluates to 1.4142".

   In some cases, matrix values that are returned by expressions are
displayed like this

     [1, 2; 3, 4] == [1, 3; 2, 4]
          => [ 1, 0; 0, 1 ]

and in other cases, they are displayed like this

     eye (3)
          =>  1  0  0
              0  1  0
              0  0  1

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 `=='.  For example,

     rot90 ([1, 2; 3, 4], -1)
     ==
     rot90 ([1, 2; 3, 4], 3)
     ==
     rot90 ([1, 2; 3, 4], 7)

Printing Notation
-----------------

   Many of the examples in this manual print text when they are
evaluated.  Examples in this manual indicate printed text with `-|'.
The value that is returned by evaluating the expression (here `1') is
displayed with `=>' and follows on a separate line.

     printf ("foo %s\n", "bar")
          -| foo bar
          => 1

Error Messages
--------------

   Some examples signal errors.  This normally displays an error message
on your terminal.  Error messages are shown on a line starting with
`error:'.

     struct_elements ([1, 2; 3, 4])
     error: struct_elements: wrong type argument `matrix'

Format of Descriptions
----------------------

   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.  The category--function,
variable, or whatever--appears at the beginning of the line.  The
description follows on succeeding lines, sometimes with examples.

A Sample Function Description
.............................

   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.

   Here is a description of an imaginary function `foo':

 - Function:  foo (X, Y, ...)
     The function `foo' subtracts X from Y, then adds the remaining
     arguments to the result.  If Y is not supplied, then the number 19
     is used by default.

          foo (1, [3, 5], 3, 9)
               => [ 14, 16 ]
          foo (5)
               => 14

     More generally,

          foo (W, X, Y, ...)
          ==
          X - W + Y + ...

   Any parameter whose name contains the name of a type (e.g., INTEGER,
INTEGER1 or MATRIX) is expected to be of that type.  Parameters named
OBJECT may be of any type.  Parameters with other sorts of names (e.g.,
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

Built-in Function
     The function described is written in a language like C++, C, or
     Fortran, and is part of the compiled Octave binary.

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.  See Dynamically Linked Functions.

Function File
     The function described is defined using Octave commands stored in
     a text file.  See Function Files.

Mapping Function
     The function described works element-by-element for matrix and
     vector arguments.

A Sample Command Description
............................

   Command descriptions have a format similar to function descriptions,
except that the word `Function' is replaced by `Command.  Commands are
functions that may called without surrounding their arguments in
parentheses.  For example, here is the description for Octave's `cd'
command:

 - Command: cd dir
 - Command: chdir dir
     Change the current working directory to DIR.  For example, `cd
     ~/octave' changes the current working directory to `~/octave'.  If
     the directory does not exist, an error message is printed and the
     working directory is not changed.

A Sample Variable Description
.............................

   A "variable" is a name that can hold a value.  Although any variable
can be set by the user, "built-in variables" typically exist
specifically so that users can change them to alter the way Octave
behaves (built-in variables are also sometimes called "user options").
Ordinary variables and built-in variables are described using a format
like that for functions except that there are no arguments.

   Here is a description of the imaginary variable
`do_what_i_mean_not_what_i_say'.

 - Built-in Variable: 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.

   Other variable descriptions have the same format, but `Built-in
Variable' is replaced by `Variable', for ordinary variables, or
`Constant' for symbolic constants whose values cannot be changed.

Getting Started
***************

   This chapter explains some of Octave's basic features, including how
to start an Octave session, get help at the command prompt, edit the
command line, and write Octave programs that can be executed as commands
from your shell.

Invoking Octave
===============

   Normally, Octave is used interactively by running the program
`octave' without any arguments.  Once started, Octave reads commands
from the terminal until you tell it to exit.

   You can also specify the name of a file on the command line, and
Octave will read and execute the commands from the named file and then
exit when it is finished.

   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 `octave --help' to display all
available options and briefly describe their use (`octave -h' is a
shorter equivalent).

Command Line Options
--------------------

   Here is a complete list of all the command line options that Octave
accepts.

`--debug'
`-d'
     Enter parser debugging mode.  Using this option will cause Octave's
     parser to print a lot of information about the commands it reads,
     and is probably only useful if you are actually trying to debug
     the parser.

`--echo-commands'
`-x'
     Echo commands as they are executed.

`--exec-path PATH'
     Specify the path to search for programs to run.  The value of PATH
     specified on the command line will override any value of
     `OCTAVE_EXEC_PATH' found in the environment, but not any commands
     in the system or user startup files that set the built-in variable
     `EXEC_PATH'.

`--help'
`-h'
`-?'
     Print short help message and exit.

`--info-file FILENAME'
     Specify the name of the info file to use.  The value of FILENAME
     specified on the command line will override any value of
     `OCTAVE_INFO_FILE' found in the environment, but not any commands
     in the system or user startup files that set the built-in variable
     `INFO_FILE'.

`--info-program PROGRAM'
     Specify the name of the info program to use.  The value of PROGRAM
     specified on the command line will override any value of
     `OCTAVE_INFO_PROGRAM' found in the environment, but not any
     commands in the system or user startup files that set the built-in
     variable `INFO_PROGRAM'.

`--interactive'
`-i'
     Force interactive behavior.  This can be useful for running Octave
     via a remote shell command or inside an Emacs shell buffer.  For
     another way to run Octave within Emacs, see Emacs.

`--no-history'
`-H'
     Disable command-line history.

`--no-init-file'
     Don't read the `~/.octaverc' or `.octaverc' files.

`--no-line-editing'
     Disable command-line editing.

`--no-site-file'
     Don't read the site-wide `octaverc' file.

`--norc'
`-f'
     Don't read any of the system or user initialization files at
     startup.  This is equivalent to using both of the options
     `--no-init-file' and `--no-site-file'.

`--path PATH'
`-p PATH'
     Specify the path to search for function files.  The value of PATH
     specified on the command line will override any value of
     `OCTAVE_PATH' found in the environment, but not any commands in the
     system or user startup files that set the built-in variable
     `LOADPATH'.

`--silent'
`--quiet'
`-q'
     Don't print the usual greeting and version message at startup.

`--traditional'
`--braindead'
     Set initial values for user-preference variables to the following
     values for compatibility with MATLAB.

          PS1                           = ">> "
          PS2                           = ""
          beep_on_error                 = 1
          default_save_format           = "mat-binary"
          define_all_return_values      = 1
          do_fortran_indexing           = 1
          crash_dumps_octave_core       = 0
          empty_list_elements_ok        = 1
          implicit_str_to_num_ok        = 1
          ok_to_lose_imaginary_part     = 1
          page_screen_output            = 0
          prefer_column_vectors         = 0
          print_empty_dimensions        = 0
          treat_neg_dim_as_zero         = 1
          warn_function_name_clash      = 0
          whitespace_in_literal_matrix  = "traditional"

`--verbose'
`-V'
     Turn on verbose output.

`--version'
`-v'
     Print the program version number and exit.

`FILE'
     Execute commands from FILE.

   Octave also includes several built-in variables that contain
information about the command line, including the number of arguments
and all of the options.

 - 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

          octave --no-line-editing --silent

     `argv' would be a cell array of strings with the elements
     `--no-line-editing' and `--silent'.

     If you write an executable Octave script, `argv' will contain the
     list of arguments passed to the script.  See Executable Octave Programs,
     for an example of how to create an executable Octave
     script.

 - Built-in Variable: program_invocation_name
 - Built-in Variable: program_name
     When Octave starts, the value of the built-in variable
     `program_invocation_name' is automatically set to the name that was
     typed at the shell prompt to run Octave, and the value of
     `program_name' is automatically set to the final component of
     `program_invocation_name'.  For example, if you typed
     `/usr/local/bin/octave' to start Octave, `program_invocation_name'
     would have the value `"/usr/local/bin/octave"', and `program_name'
     would have the value `"octave"'.

     If executing a script from the command line (e.g., `octave foo.m')
     or using an executable Octave script, the program name is set to
     the name of the script.  See Executable Octave Programs, for
     an example of how to create an executable Octave script.

   Here is an example of using these variables to reproduce Octave's
command line.

     printf ("%s", program_name);
     for i = 1:nargin
       printf (" %s", nth (argv, i));
     endfor
     printf ("\n");

See Index Expressions, for an explanation of how to properly index
arrays of strings and substrings in Octave, and Defining Functions,
for information about the variable `nargin'.

Startup Files
-------------

   When Octave starts, it looks for commands to execute from the
following files:

`OCTAVE-HOME/share/octave/site/m/startup/octaverc'
     Where OCTAVE-HOME is the directory in which all of Octave is
     installed (the default is `/usr/local').  This file is provided so
     that changes to the default Octave environment can be made
     globally for all users at your site for all versions of Octave you
     have installed.  Some care should be taken when making changes to
     this file, since all users of Octave at your site will be affected.

`OCTAVE-HOME/share/octave/VERSION/m/startup/octaverc'
     Where OCTAVE-HOME is the directory in which all of Octave is
     installed (the default is `/usr/local'), and VERSION is the
     version number of Octave.  This file is provided so that changes
     to the default Octave environment can be made globally for all
     users for a particular version of Octave.  Some care should be
     taken when making changes to this file, since all users of Octave
     at your site will be affected.

`~/.octaverc'
     This file is normally used to make personal changes to the default
     Octave environment.

`.octaverc'
     This file can be used to make changes to the default Octave
     environment for a particular project.  Octave searches for this
     file in the current directory after it reads `~/.octaverc'.  Any
     use of the `cd' command in the `~/.octaverc' file will affect the
     directory that Octave searches for the file `.octaverc'.

     If you start Octave in your home directory, commands from from the
     file `~/.octaverc' will only be executed once.

   A message will be displayed as each of the startup files is read if
you invoke Octave with the `--verbose' option but without the
`--silent' option.

   Startup files may contain any valid Octave commands, including
function definitions.

Quitting Octave
===============

 - Built-in Function:  exit (STATUS)
 - Built-in Function:  quit (STATUS)
     Exit the current Octave session.  If the optional integer value
     STATUS is supplied, pass that value to the operating system as the
     Octave's exit status.

 - Built-in Function:  atexit (FCN)
     Register a function to be called when Octave exits.  For example,

          function print_fortune ()
            printf ("\n%s\n", system ("fortune"));
            fflush (stdout);
          endfunction
          atexit ("print_fortune");

     will print a message when Octave exits.

Commands for Getting Help
=========================

   The entire text of this manual is available from the Octave prompt
via the command `help -i'.  In addition, the documentation for
individual user-written functions and variables is also available via
the `help' command.  This section describes the commands used for
reading the manual and the documentation strings for user-supplied
functions and variables.  See Function Files, for more information
about how to document the functions you write.

 - Command: help
     Octave's `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, `help' prints a list of all the
     available operators, functions, and built-in variables.  If the
     first argument is `-i', the `help' command searches the index of
     the on-line version of this manual for the given topics.

     For example, the command `help help' prints a short message
     describing the `help' command, and `help -i help' starts the GNU
     Info browser at this node in the on-line version of the manual.

     Once the GNU Info browser is running, help for using it is
     available using the command `C-h'.

   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 `help comma' or `help semicolon'.

 - Built-in Variable: INFO_FILE
     The variable `INFO_FILE' names the location of the Octave info
     file.  The default value is `"OCTAVE-HOME/info/octave.info"', in
     which OCTAVE-HOME is the directory where all of Octave is
     installed.

 - Built-in Variable: INFO_PROGRAM
     The variable `INFO_PROGRAM' names the info program to run.  Its
     default initial value is
     `"OCTAVE-HOME/libexec/octave/VERSION/exec/ARCH/info"' in which
     OCTAVE-HOME is the directory where all of Octave is installed,
     VERSION is the Octave version number, and ARCH is the system type
     (for example, `i686-pc-linux-gnu').  The default initial value may
     be overridden by the environment variable `OCTAVE_INFO_PROGRAM',
     or the command line argument `--info-program NAME', or by setting
     the value of `INFO_PROGRAM' in a startup script

 - Built-in Variable: MAKEINFO_PROGRAM
     The variable `MAKEINFO_PROGRAM' names the makeinfo program that
     Octave runs to format help text that contains Texinfo markup
     commands.  Its default initial value is `"makeinfo"'.

 - Built-in Variable: suppress_verbose_help_message
     If the value of `suppress_verbose_help_message' is nonzero, Octave
     will not add additional help information to the end of the output
     from the `help' command and usage messages for built-in commands.

Command Line Editing
====================

   Octave uses the GNU readline library to provide an extensive set of
command-line editing and history features.  Only the most common
features are described in this manual.  Please see The GNU Readline
Library manual for more information.

   To insert printing characters (letters, digits, symbols, etc.),
simply type the character.  Octave will insert the character at the
cursor and advance the cursor forward.

   Many of the command-line editing functions operate using control
characters.  For example, the character `Control-a' moves the cursor to
the beginning of the line.  To type `C-a', hold down <CTRL> and then
press <a>.  In the following sections, control characters such as
`Control-a' are written as `C-a'.

   Another set of command-line editing functions use Meta characters.
On some terminals, you type `M-u' by holding down <META> and pressing
<u>.  If your terminal does not have a <META> key, you can still type
Meta charcters using two-character sequences starting with `ESC'.
Thus, to enter `M-u', you could type <ESC><u>.  The `ESC' character
sequences are also allowed on terminals with real Meta keys.  In the
following sections, Meta characters such as `Meta-u' are written as
`M-u'.

Cursor Motion
-------------

   The following commands allow you to position the cursor.

`C-b'
     Move back one character.

`C-f'
     Move forward one character.

`<DEL>'
     Delete the character to the left of the cursor.

`C-d'
     Delete the character underneath the cursor.

`M-f'
     Move forward a word.

`M-b'
     Move backward a word.

`C-a'
     Move to the start of the line.

`C-e'
     Move to the end of the line.

`C-l'
     Clear the screen, reprinting the current line at the top.

`C-_'
`C-/'
     Undo the last thing that you did.  You can undo all the way back
     to an empty line.

`M-r'
     Undo all changes made to this line.  This is like typing the `undo'
     command enough times to get back to the beginning.

   The above table describes the most basic possible keystrokes that
you need in order to do editing of the input line.  On most terminals,
you can also use the arrow keys in place of `C-f' and `C-b' to move
forward and backward.

   Notice how `C-f' moves forward a character, while `M-f' moves
forward a word.  It is a loose convention that control keystrokes
operate on characters while meta keystrokes operate on words.

   There is also a function available so that you can clear the screen
from within Octave programs.

 - Built-in Function:  clc ()
 - Built-in Function:  home ()
     Clear the terminal screen and move the cursor to the upper left
     corner.