new file mode 100644
--- /dev/null
+++ b/doc/interpreter/intro.txi
@@ -0,0 +1,599 @@
+@c Copyright (C) 1996, 1997 John W. Eaton
+@c This is part of the Octave manual.
+@c For copying conditions, see the file gpl.texi.
+
+@node Introduction, Getting Started, Preface, Top
+@chapter A Brief Introduction to Octave
+@cindex introduction
+
+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 @ref{Copying}.
+
+This document corresponds to Octave version @value{VERSION}.
+
+@c XXX FIXME XXX -- add explanation about how and why Octave was written.
+@c
+@c XXX FIXME XXX -- add a sentence or two explaining that we could
+@c                  always use more funding.
+
+@menu
+* Running Octave::              
+* Simple Examples::             
+* Conventions::                 
+@end menu
+
+@node Running Octave, Simple Examples, Introduction, Introduction
+@section Running Octave
+
+On most systems, the way to invoke Octave is with the shell command
+@samp{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
+@kbd{Control-C} (usually written @kbd{C-c} for short).  @kbd{C-c} gets
+its name from the fact that you type it by holding down @key{CTRL} and
+then pressing @key{c}.  Doing this will normally return you to Octave's
+prompt.
+
+@cindex exiting octave
+@cindex quitting octave
+To exit Octave, type @kbd{quit}, or @kbd{exit} at the Octave prompt.
+
+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, Conventions, Running Octave, Introduction
+@section 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 @samp{octave:13>}
+are lines you type, ending each with a carriage return.  Octave will
+respond with an answer, or by displaying a graph.
+
+@unnumberedsubsec 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
+
+@example
+octave:1> a = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ]
+@end example
+
+@noindent
+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
+
+@example
+octave:2> b = rand (3, 2);
+@end example
+
+@noindent
+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
+@code{b}, type the command
+
+@example
+octave:3> b
+@end example
+
+@unnumberedsubsec Matrix Arithmetic
+
+Octave has a convenient operator notation for performing matrix
+arithmetic.  For example, to multiply the matrix @code{a} by a scalar
+value, type the command
+
+@example
+octave:4> 2 * a
+@end example
+
+To multiply the two matrices @code{a} and @code{b}, type the command
+
+@example
+octave:5> a * b
+@end example
+
+To form the matrix product
+@iftex
+@tex
+$@code{a}^T@code{a}$,
+@end tex
+@end iftex
+@ifinfo
+@code{transpose (a) * a},
+@end ifinfo
+type the command
+
+@example
+octave:6> a' * a
+@end example
+
+@unnumberedsubsec Solving Linear Equations
+
+To solve the set of linear equations @code{a@var{x} = b},
+use the left division operator, @samp{\}:
+
+@example
+octave:7> a \ b
+@end example
+
+@noindent
+This is conceptually equivalent to
+@iftex
+@tex
+$@code{a}^{-1}@code{b}$,
+@end tex
+@end iftex
+@ifinfo
+@code{inv (a) * b},
+@end ifinfo
+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.
+
+@unnumberedsubsec Integrating Differential Equations
+
+Octave has built-in functions for solving nonlinear differential
+equations of the form
+@iftex
+@tex
+$$
+ {dx \over dt} = f(x,t), \qquad x(t=t_0) = x_0
+$$
+@end tex
+@end iftex
+@ifinfo
+
+@example
+@group
+dx
+-- = f (x, t)
+dt
+@end group
+@end example
+
+@noindent
+with the initial condition
+
+@example
+x(t = t0) = x0
+@end example
+@end ifinfo
+
+@noindent
+For Octave to integrate equations of this form, you must first provide a
+definition of the function
+@iftex
+@tex
+$f (x, t)$.
+@end tex
+@end iftex
+@ifinfo
+@code{f(x,t)}.
+@end ifinfo
+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.
+
+@example
+@group
+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
+@end group
+@end example
+
+@noindent
+Given the initial condition
+
+@example
+x0 = [1; 2];
+@end example
+
+@noindent
+and the set of output times as a column vector (note that the first
+output time corresponds to the initial condition given above)
+
+@example
+t = linspace (0, 50, 200)';
+@end example
+
+@noindent
+it is easy to integrate the set of differential equations:
+
+@example
+x = lsode ("f", x0, t);
+@end example
+
+@noindent
+The function @code{lsode} uses the Livermore Solver for Ordinary
+Differential Equations, described in A. C. Hindmarsh, @cite{ODEPACK, a
+Systematized Collection of ODE Solvers}, in: Scientific Computing, R. S.
+Stepleman et al. (Eds.), North-Holland, Amsterdam, 1983, pages 55--64.
+
+@unnumberedsubsec Producing Graphical Output
+
+To display the solution of the previous example graphically, use the
+command
+
+@example
+plot (t, x)
+@end example
+
+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
+
+@example
+gset term
+@end example
+
+@noindent
+to see a list of the supported terminal types.  Octave uses
+@code{gnuplot} to display graphics, and can display graphics on any
+terminal that is supported by @code{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
+
+@example
+@group
+gset term postscript
+gset output "foo.ps"
+replot
+@end group
+@end example
+
+@noindent
+This will work for other types of output devices as well.  Octave's
+@code{gset} command is really just piped to the @code{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
+
+@example
+@group
+gset term postscript
+gset output "|lpr -Pname_of_your_graphics_printer"
+replot
+@end group
+@end example
+
+@unnumberedsubsec 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 @kbd{Control-p} (usually written @kbd{C-p} for
+short).  @kbd{C-p} gets its name from the fact that you type it by
+holding down @key{CTRL} and then pressing @key{p}.  Doing this will
+normally bring back the previous line of input.  @kbd{C-n} will bring up
+the next line of input, @kbd{C-b} will move the cursor backward on the
+line, @kbd{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 @ref{Command Line Editing}.
+
+@unnumberedsubsec Getting Help
+
+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 @code{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,
+
+@example
+help plot
+@end example
+
+@noindent
+will display the help text for the @code{plot} function.
+
+Octave sends output that is too long to fit on one screen through a
+pager like @code{less} or @code{more}.  Type a @key{RET} to advance one
+line, a @key{SPC} to advance one page, and @key{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 @ref{Getting Help}.
+
+@node Conventions,  , Simple Examples, Introduction
+@section 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.
+
+@menu
+* Fonts::                       
+* Evaluation Notation::         
+* Printing Notation::           
+* Error Messages::              
+* Format of Descriptions::      
+@end menu
+
+@node Fonts, Evaluation Notation, Conventions, Conventions
+@subsection Fonts
+@cindex fonts
+
+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}.  Commands that you type at the
+shell prompt sometimes appear in this font or form:
+@samp{octave --no-init-file}.  Commands that you type at the Octave
+prompt sometimes appear in this font or form: @kbd{foo --bar --baz}.
+Specific keys on your keyboard appear in this font or form: @key{ANY}.
+@cindex any key
+
+@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
+@group
+sqrt (2)
+     @result{} 1.4142
+@end group
+@end example
+
+@noindent
+You can read this as ``@code{sqrt (2)} evaluates to 1.4142''.
+
+In some cases, matrix values that are returned by expressions are
+displayed like this
+
+@example
+@group
+[1, 2; 3, 4] == [1, 3; 2, 4]
+     @result{} [ 1, 0; 0, 1 ]
+@end group
+@end example
+
+@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
+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
+@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
+
+@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
+@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
+@code{error:}.
+
+@example
+@group
+struct_elements ([1, 2; 3, 4])
+error: struct_elements: wrong type argument `matrix'
+@end group
+@end example
+
+@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.
+
+@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
+
+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 @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
+@group
+foo (1, [3, 5], 3, 9)
+     @result{} [ 14, 16 ]
+foo (5)
+     @result{} 14
+@end group
+@end example
+
+More generally,
+
+@example
+@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
+@cindex built-in function
+The function described is written in a language like C++, C, or Fortran,
+and is part of the compiled Octave binary.
+
+@item Loadable Function
+@cindex 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
+@cindex function file
+The function described is defined using Octave commands stored in a text
+file.  @xref{Function Files}.
+
+@item Mapping Function
+@cindex mapping function
+The function described works element-by-element for matrix and vector
+arguments.
+@end table
+
+@node A Sample Command Description, A Sample Variable Description, A Sample Function Description, Format of Descriptions
+@subsubsection A Sample Command 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 may 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,
+@kbd{cd ~/octave} 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
+
+@node A Sample Variable Description,  , A Sample Command Description, Format of Descriptions
+@subsubsection A Sample Variable Description
+@cindex variable descriptions
+
+A @dfn{variable} is a name that can hold a value.  Although any variable
+can be set by the user, @dfn{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 @dfn{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
+@code{do_what_i_mean_not_what_i_say}.
+
+@defvr {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.
+@end defvr
+
+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.