changeset 2866:ef2e333f469c

[project @ 1997-04-18 07:39:43 by jwe]
author jwe
date Fri, 18 Apr 1997 07:39:53 +0000
parents 2d9047854387
children 0629c4974ce9
files doc/faq/FAQ.texi doc/faq/Octave-FAQ.texi
diffstat 2 files changed, 763 insertions(+), 763 deletions(-) [+]
line wrap: on
line diff
deleted file mode 100644
--- a/doc/faq/FAQ.texi
+++ /dev/null
@@ -1,763 +0,0 @@
-\input texinfo.tex      @c -*-texinfo-*-
-
-@setfilename FAQ.info
-@settitle Frequently asked questions about Octave (with answers)
-
-@setchapternewpage off
-
-@titlepage
-@title Octave FAQ
-@subtitle Frequently asked questions about Octave
-@subtitle December 14, 1996
-@sp 1
-@author John W. Eaton
-@page
-@end titlepage
-
-@ifinfo
-@node Top, What is Octave?, (dir), (dir)
-@top
-@unnumbered Preface
-@cindex FAQ for Octave, latest version
-@end ifinfo
-
-This is a list of frequently asked questions (FAQ) for Octave users.
-
-Some information in this FAQ was written for earlier versions of
-Octave and may now be obsolete.
-
-I'm looking for new questions (@emph{with} answers), better answers,
-or both.  Please send suggestions to bug-octave@@bevo.che.wisc.edu.
-If you have general questions about Octave, or need help for something
-that is not covered by the Octave manual or the FAQ, please use the
-help-octave@@bevo.che.wisc.edu mailing list.
-
-This FAQ is intended to supplement, not replace, the Octave manual.
-Before posting a question to the help-octave mailing list, you should
-first check to see if the topic is covered in the manual.
-
-@menu
-* What is Octave?::             
-* Version 2.0::               
-* Octave Features::             
-* Documentation::               
-* Getting Octave::              
-* Installation::                
-* Common problems::             
-* Getting additional help::     
-* Bug reports::                 
-* MATLAB compatibility::        
-* Index::                       
-@end menu
-
-@node What is Octave?, Version 2.0, Top, Top
-@chapter What is Octave?
-
-Octave is a high-level interactive language, primarily intended for
-numerical computations that is mostly compatible with
-@sc{Matlab}.@footnote{@sc{Matlab} is a registered trademark of The MathWorks,
-Inc.}
-
-Octave can do arithmetic for real and complex scalars and matrices,
-solve sets of nonlinear algebraic equations, integrate functions over
-finite and infinite intervals, and integrate systems of ordinary
-differential and differential-algebraic equations.
-
-Octave uses the GNU readline library to handle reading and editing
-input.  By default, the line editing commands are similar to the
-cursor movement commands used by GNU Emacs, and a vi-style line
-editing interface is also available.  At the end of each session, the
-command history is saved, so that commands entered during previous
-sessions are not lost.
-
-The Octave distribution includes a 200+ page Texinfo manual.  Access
-to the complete text of the manual is available via the help command
-at the Octave prompt.
-
-Two and three dimensional plotting is fully supported using gnuplot.
-
-The underlying numerical solvers are currently standard Fortran ones
-like Lapack, Linpack, Odepack, the Blas, etc., packaged in a library
-of C++ classes.  If possible, the Fortran subroutines are compiled
-with the system's Fortran compiler, and called directly from the C++
-functions.  If that's not possible, you can still compile Octave if
-you have the free Fortran to C translator f2c.
-
-Octave is also free software; you can redistribute it and/or modify it
-under the terms of the GNU General Public License as published by the
-Free Software Foundation.
-
-@node Version 2.0, Octave Features, What is Octave?, Top
-@chapter What's new in version 2.0 of Octave
-
-The long-awaited version 2.0 of Octave has now been released.  Many
-bugs have been fixed and lots of new features added.  Octave is now much
-more compatible with @sc{Matlab}.
-
-Version 2.0 fixes many bugs, but as with any ``x.y.0'' release there
-will be a few glitches.  There will probably be a 2.0.1 release to fix
-most of these problems.  You can help contribute to the quality of
-Octave by using it and submitting bug reports for the problems you
-encounter.
-
-A list of user-visible changes in recent versions of Octave may be found
-in the file NEWS, distributed in both source and binary releases of
-Octave.
-
-@node Octave Features, Documentation, Version 2.0, Top
-@chapter What features are unique to Octave?
-
-@menu
-* Command and variable name completion::  
-* Command history::             
-* Data structures::             
-* Short-circuit boolean operators::  
-* Increment and decrement operators::  
-* Unwind-protect::              
-* Variable-length argument lists::  
-* Variable-length return lists::  
-* Built-in ODE and DAE solvers::  
-@end menu
-
-@node Command and variable name completion, Command history, Octave Features, Octave Features
-@section Command and variable name completion
-
-@cindex Command completion
-@cindex Function name completion
-@cindex Variable name completion
-@cindex Name completion
-
-Typing a TAB character (ASCII code 9) on the command line causes Octave
-to attempt to complete variable, function, and file names.  Octave uses
-the text before the cursor as the initial portion of the name to
-complete.
-
-For example, if you type @samp{fu} followed by TAB at the Octave prompt,
-Octave will complete the rest of the name @samp{function} on the command
-line (unless you have other variables or functions defined that begin
-with the characters @samp{fu}).  If there is more than one possible
-completion, Octave will ring the terminal bell to let you know that your
-initial sequence of characters is not enough to specify a unique name.
-To complete the name, you may either edit the initial character sequence
-(usually adding more characters until completion is possible) or type
-another TAB to cause Octave to display the list of possible completions.
-
-@node Command history, Data structures, Command and variable name completion, Octave Features
-@section Command history
-
-@cindex Command history
-@cindex History
-
-When running interactively, Octave saves the commands you type in an
-internal buffer so that you can recall and edit them.  Emacs and vi
-editing modes are available with Emacs keybindings enabled by default.
-
-When Octave exits, the current command history is saved to the file
-@file{~/.octave_hist}, and each time Octave starts, it inserts the
-contents of the @file{~/.octave_hist} file in the history list so that
-it is easy to begin working where you left off.
-
-@node Data structures, Short-circuit boolean operators, Command history, Octave Features
-@section Data structures
-
-@cindex Data structures
-@cindex Structures
-
-Octave includes a limited amount of support for organizing data in
-structures.  The current implementation uses an associative array
-with indices limited to strings, but the syntax is more like C-style
-structures.  Here are some examples of using data structures in Octave.
-
-@itemize @bullet
-@item Elements of structures can be of any value type.
-
-@example
-@group
-octave:1> x.a = 1; x.b = [1, 2; 3, 4]; x.c = "string";
-octave:2> x.a
-x.a = 1
-octave:3> x.b
-x.b =
-
-  1  2
-  3  4
-
-octave:4> x.c
-x.c = string
-@end group
-@end example
-
-@item Structures may be copied.
-
-@example
-@group
-octave:1> y = x
-y =
-@{
-  a = 1
-  b =
-
-    1  2
-    3  4
-
-  c = string
-  s =
-
-    0.00000  0.00000  0.00000
-    0.00000  5.46499  0.00000
-    0.00000  0.00000  0.36597
-
-  u =
-
-    -0.40455  -0.91451
-    -0.91451   0.40455
-
-  v =
-
-    -0.57605   0.81742
-    -0.81742  -0.57605
-@}
-@end group
-@end example
-
-@item Structure elements may reference other structures.
-
-@example
-@group
-octave:1> x.b.d = 3
-x.b.d = 3
-octave:2> x.b
-ans =
-@{
-  d = 3
-@}
-octave:3> x.b.d
-ans = 3
-@end group
-@end example
-
-@item Functions can return structures.
-
-@example
-@group
-octave:1> function y = f (x)
-> y.re = real (x);
-> y.im = imag (x);
-> endfunction
-
-octave:2> f (rand + rand*I);
-ans =
-@{
-  im = 0.18033
-  re = 0.19069
-@}
-@end group
-@end example
-
-@item Function return lists can include structure elements, and they may
-be indexed like any other variable.
-
-@example
-@group
-octave:1> [x.u, x.s(2:3,2:3), x.v] = svd ([1, 2; 3, 4]);
-octave:2> x
-x =
-@{
-  s =
-
-    0.00000  0.00000  0.00000
-    0.00000  5.46499  0.00000
-    0.00000  0.00000  0.36597
-
-  u =
-
-    -0.40455  -0.91451
-    -0.91451   0.40455
-
-  v =
-
-    -0.57605   0.81742
-    -0.81742  -0.57605
-@}
-@end group
-@end example
-
-@item You can also use the function @code{is_struct} to determine
-whether a given value is a data structure.  For example
-
-@example
-is_struct (x)
-@end example
-
-@noindent
-returns 1 if the value of the variable @var{x} is a data structure.
-@end itemize
-
-This feature should be considered experimental, but you should expect it
-to work.  Suggestions for ways to improve it are welcome.
-
-@node Short-circuit boolean operators, Increment and decrement operators, Data structures, Octave Features
-@section Short-circuit boolean operators
-
-@cindex Boolean operators, short-circuit
-@cindex Logical operators, short-circuit
-@cindex Short-circuit boolean operators
-@cindex Operators, boolean
-
-Octave's @samp{&&} and @samp{||} logical operators are evaluated in
-a short-circuit fashion (like the corresponding operators in the C
-language) and work differently than the element by element operators
-@samp{&} and @samp{|}.
-
-@node Increment and decrement operators, Unwind-protect, Short-circuit boolean operators, Octave Features
-@section Increment and decrement operators
-
-@cindex Increment operators
-@cindex Decrement operators
-@cindex Operators, increment
-@cindex Operators, decrement
-
-Octave includes the C-like increment and decrement operators @samp{++}
-and @samp{--} in both their prefix and postfix forms.
-
-For example, to pre-increment the variable @var{x}, you would write
-@code{++@var{x}}.  This would add one to @var{x} and then return the new
-value of @var{x} as the result of the expression.  It is exactly the
-same as the expression @code{@var{x} = @var{x} + 1}.
-
-To post-increment a variable @var{x}, you would write @code{@var{x}++}.
-This adds one to the variable @var{x}, but returns the value that
-@var{x} had prior to incrementing it.  For example, if @var{x} is equal
-to 2, the result of the expression @code{@var{x}++} is 2, and the new
-value of @var{x} is 3.
-
-For matrix and vector arguments, the increment and decrement operators
-work on each element of the operand.
-
-It is not currently possible to increment index expressions.  For
-example, you might expect that the expression @code{@var{v}(4)++} would
-increment the fourth element of the vector @var{v}, but instead it
-results in a parse error.  This problem may be fixed in a future
-release of Octave.
-
-@node Unwind-protect, Variable-length argument lists, Increment and decrement operators, Octave Features
-@section Unwind-protect
-
-@cindex Unwind-protect
-
-Octave supports a limited form of exception handling modelled after the
-unwind-protect form of Lisp.  The general form of an
-@code{unwind_protect} block looks like this:
-
-@example
-@group
-unwind_protect
-  @var{body}
-unwind_protect_cleanup
-  @var{cleanup}
-end_unwind_protect
-@end group
-@end example
-
-@noindent
-Where @var{body} and @var{cleanup} are both optional and may contain any
-Octave expressions or commands.  The statements in @var{cleanup} are 
-guaranteed to be executed regardless of how control exits @var{body}.
-
-The @code{unwind_protect} statement is often used to reliably restore
-the values of global variables that need to be temporarily changed.
-
-@node Variable-length argument lists, Variable-length return lists, Unwind-protect, Octave Features
-@section Variable-length argument lists
-
-@cindex Variable-length argument lists
-@cindex Argument lists, variable-length
-
-Octave has a real mechanism for handling functions that take an
-unspecified number of arguments, so it is no longer necessary to place
-an upper bound on the number of optional arguments that a function can
-accept.
-
-Here is an example of a function that uses the new syntax to print a
-header followed by an unspecified number of values:
-
-@example
-@group
-function foo (heading, ...)
-  disp (heading);
-  va_start ();
-  while (--nargin)
-    disp (va_arg ());
-  endwhile
-endfunction
-@end group
-@end example
-
-Calling @code{va_start()} positions an internal pointer to the first
-unnamed argument and allows you to cycle through the arguments more than
-once.  It is not necessary to call @code{va_start()} if you do not plan
-to cycle through the arguments more than once.
-
-The function @code{va_arg()} returns the value of the next available
-argument and moves the internal pointer to the next argument.  It is an
-error to call @code{va_arg()} when there are no more arguments
-available.
-
-It is also possible to use the keyword @var{all_va_args} to pass all
-unnamed arguments to another function.
-
-@node Variable-length return lists, Built-in ODE and DAE solvers, Variable-length argument lists, Octave Features
-@section Variable-length return lists
-
-@cindex Variable-length return lists
-@cindex Return lists, variable-length
-
-Octave also has a real mechanism for handling functions that return an
-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
-@samp{N} values:
-
-@example
-@group
-function [...] = foo (n)
-  for i = 1:n
-    vr_val (i);
-  endfor
-endfunction
-@end group
-@end example
-
-@node Built-in ODE and DAE solvers,  , Variable-length return lists, Octave Features
-@section Built-in ODE and DAE solvers
-
-@cindex DASSL
-@cindex LSODE
-
-Octave includes LSODE and DASSL for solving systems of stiff ordinary
-differential and differential-algebraic equations.  These functions are
-built in to the interpreter.
-
-@node Documentation, Getting Octave, Octave Features, Top
-@chapter What documentation exists for Octave?
-
-@cindex Octave, documentation
-
-The Octave distribution includes a 220+ page manual that is also
-distributed under the terms of the GNU GPL.
-
-The Octave manual is intended to be a complete reference for Octave, but
-it is not a finished document.  If you have problems using it, or find
-that some topic is not adequately explained, indexed, or
-cross-referenced, please send a bug report to bug-octave@@bevo.che.wisc.edu.
-
-Because the Octave manual is written using Texinfo, the complete text of
-the Octave manual is also available on line using the GNU Info system
-via the GNU Emacs, info, or xinfo programs, or by using the @samp{help -i} 
-command to start the GNU info browser directly from the Octave prompt.
-
-It is also possible to use your favorite WWW browser to read the Octave
-manual (or any other Info file) by using Roar Smith's info2www program
-to convert GNU Info files to HTML.  The source for info2www is available
-from @url{ftp://ftp.che.wisc.edu/pub/www}.
-
-@node Getting Octave, Installation, Documentation, Top
-@chapter Obtaining Source Code
-
-@cindex Source code
-
-@menu
-* Octave for Unix::             
-* Octave for other platforms::  
-* latest versions::             
-@end menu
-
-@node Octave for Unix, Octave for other platforms, Getting Octave, Getting Octave
-@section How do I get a copy of Octave for Unix?
-
-You can get Octave from a friend who has a copy, by anonymous FTP, or by
-ordering a tape or CD-ROM from the Free Software Foundation (FSF).
-
-@cindex Octave, ordering
-@cindex Octave, getting a copy
-
-Octave was not developed by the FSF, but the FSF does distribute Octave,
-and the developers of Octave support the efforts of the FSF by
-encouraging users of Octave to order Octave on tape or CD directly from
-the FSF.
-
-The FSF is a nonprofit organization that distributes software and
-manuals to raise funds for more GNU development.  Buying a tape or CD
-from the FSF contributes directly to paying staff to develop GNU
-software.  CD-ROMs cost $400 if an organization is buying, or $100 if an
-individual is buying.  Tapes cost around $200 depending on media type.
-
-The FSF only makes new CD releases a few times a year, so if you are
-interested specifically in Octave, I recommend asking for the latest
-release on tape.
-
-@cindex FSF [Free Software Foundation]
-@cindex GNU [GNU's not unix]
-
-For more information about ordering from the FSF, contact
-gnu@@prep.ai.mit.edu, phone (617) 542-5942 or anonymous ftp file
-@file{/pub/gnu/GNUinfo/ORDERS} from prep.ai.mit.edu or one of the sites
-listed below.
-
-@cindex FSF, contact <gnu@@prep.ai.mit.edu>
-@cindex GNUware, anonymous FTP sites
-
-If you are on the Internet, you can copy the latest distribution
-version of Octave from the file @file{/pub/octave/octave-M.N.tar.gz}, on
-the host @file{ftp.che.wisc.edu}.  This tar file has been compressed
-with GNU gzip, so be sure to use binary mode for the transfer.  @samp{M}
-and @samp{N} stand for version numbers; look at a listing of the
-directory through ftp to see what version is available.  After you
-unpack the distribution, be sure to look at the files @file{README} and
-@file{INSTALL}.
-
-Binaries for several popular systems are also available.  If you would
-like help out by making binaries available for other systems, please
-contact bug-octave@@bevo.che.wisc.edu.
-
-A list of user-visible changes since the last release is available in
-the file @file{NEWS}.  The file @file{ChangeLog} in the source
-distribution contains a more detailed record of changes made since the
-last release.
-
-@node Octave for other platforms, latest versions, Octave for Unix, Getting Octave
-@section How do I get a copy of Octave for (some other platform)?
-
-@cindex VMS support
-@cindex VAX
-@cindex MS-DOS support
-@cindex DJGPP
-@cindex EMX
-@cindex OS/2 support
-
-Octave currently runs on Unix-like systems only.  It should be possible
-to make Octave work on other systems.  If you are interested in porting
-Octave to other systems, please contact bug-octave@@bevo.che.wisc.edu.
-
-@node latest versions,  , Octave for other platforms, Getting Octave
-@section What is the latest version of Octave
-
-@cindex Octave, version date
-
-The latest version of Octave is 2.0, released December 1996.
-
-@node Installation, Common problems, Getting Octave, Top
-@chapter Installation Issues and Problems
-
-@cindex Octave, building 
-
-Octave requires approximately 50MB of disk storage to unpack and
-install (significantly less if you don't compile with debugging
-symbols).
-
-Octave has been compiled and tested with g++ and libg++ on a
-SPARCstation 2 running SunOS 4.1.2, an IBM RS/6000 running AIX 3.2.5,
-DEC Alpha systems running OSF/1 1.3 and 3.0, a DECstation 5000/240
-running Ultrix 4.2a, and i486 systems running Linux.  It should work on
-most other Unix systems that have a working port of g++ and libg++.
-
-@menu
-* What else do I need?::        
-* Other C++ compilers?::        
-@end menu
-
-@node What else do I need?, Other C++ compilers?, Installation, Installation
-@section What else do I need?
-
-@cindex GNU gcc
-@cindex GNU g++
-@cindex libg++
-@cindex GNU Make
-@cindex Flex
-@cindex GNU Bison
-
-  In order to build Octave, you will need a current version
-of g++, libg++, and GNU make.  If you don't have these tools, you can
-get them from many anonymous ftp archives, including ftp.che.wisc.edu,
-ftp.uu.net, prep.ai.mit.edu, and wuarchive.wustl.edu, or by writing to
-the FSF at 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
-
-@node Other C++ compilers?,  , What else do I need?, Installation
-@section Can I compile Octave with another C++ compiler?
-
-Currently, Octave can only be compiled with the GNU C++ compiler.  It
-would be nice to make it possible to compile Octave with other C++
-compilers, but the maintainers do not have sufficient time to devote to
-this.  If you are interested in working to make Octave portable to other
-compilers, please contact bug-octave@@bevo.che.wisc.edu.
-
-@node Common problems, Getting additional help, Installation, Top
-@chapter Common problems
-
-This list is probably far too short.  Feel free to suggest additional
-questions (preferably with answers!)
-
-@itemize @bullet
-@item
-Octave takes a long time to find symbols.
-
-Octave is probably spending this time recursively searching directories
-for function files.  Check the value of your LOADPATH.  For those
-elements that end in @samp{//}, do any name a very large directory tree?
-Does it contain directories that have a mixture of files and
-directories?  In order for the recursive directory searching code to
-work efficiently, directories that are to be searched recursively should
-have either function files only, or subdirectories only, but not a
-mixture of both.  Check to make sure that Octave's standard set of
-function files is installed this way.
-@end itemize
-
-@node Getting additional help, Bug reports, Common problems, Top
-@chapter Getting additional help
-
-@cindex Additional help
-@cindex Mailing lists, help-octave
-
-The mailing list
-
-@example
-help-octave@@bevo.che.wisc.edu
-@end example
-
-@noindent
-is available for questions related to using, installing, and porting
-Octave that are not adequately answered by the Octave manual or by this
-document.
-
-If you would like to join the discussion and receive all messages sent
-to the list, please send a short note to
-
-@example
-@group
-help-octave-request@@bevo.che.wisc.edu
-            ^^^^^^^
-@end group
-@end example
-
-@strong{Please do not} send requests to be added or removed from the the
-mailing list, or other administrative trivia to the list itself.
-
-An archive of old postings to the help-octave mailing list is maintained
-on ftp.che.wisc.edu in the directory @file{/pub/octave/MAILING-LISTS}.
-
-@node Bug reports, MATLAB compatibility, Getting additional help, Top
-@chapter I think I have found a bug in Octave.
-
-@cindex Bug in Octave, newly found
-
-``I think I have found a bug in Octave, but I'm not sure.  How do I know,
-and who should I tell?''
-
-@cindex Manual, for Octave
-
-First, see the section on bugs and bug reports in the Octave manual.
-The Octave manual is included in the Octave distribution.
-
-When you report a bug, make sure to describe the type of computer you
-are using, the version of the operating system it is running, and the
-version of Octave that you are using.  Also provide enough code so that
-the Octave maintainers can duplicate your bug.
-
-If you have Octave working at all, the easiest way to do this is to use
-the Octave function @code{bug_report}.  When you execute this function,
-Octave will prompt you for a subject and then invoke the editor on a
-file that already contains all the configuration information.  When you
-exit the editor, Octave will mail the bug report for you.
-
-@cindex Octave bug report
-@cindex Mailing lists, bug-octave
-
-If for some reason you cannot use Octave's @code{bug_report} function,
-mail your bug report to "bug-octave@@bevo.che.wisc.edu".  Your message
-needs to include enough information to allow the maintainers of Octave
-to fix the bug.  Please read the section on bugs and bug reports in the
-Octave manual for a list of things that should be included in every bug
-report.
-
-@node MATLAB compatibility, Index, Bug reports, Top
-@chapter Porting programs from @sc{Matlab} to Octave
-
-@cindex @sc{Matlab} compatibility
-@cindex Compatibility with @sc{Matlab}
-
-``I wrote some code for @sc{Matlab}, and I want to get it running under
-Octave.  Is there anything I should watch out for?''
-
-The differences between Octave and @sc{Matlab} typically fall into one of
-three categories:
-
-@enumerate
-@item
-Irrelevant.
-
-@item
-Known differences, perhaps configurable with a user preference variable.
-
-@item
-Unknown differences.
-@end enumerate
-
-The first category, irrelevant differences, do not affect computations
-and most likely do not affect the execution of function files.
-
-The differences of the second category are usually because the authors
-of Octave decided on a better (subjective) implementation that the way
-@sc{Matlab} does it, and so introduced ``user preference variables'' so that
-you can customize Octave's behavior to be either @sc{Matlab}-compatible or
-to use Octave's new features.  To make Octave more @sc{Matlab}-compatible,
-put the following statements in your @file{~/.octaverc} file, or use the
-command line option @samp{--traditional}, which implies all of these
-settings.  Note that this list may not be complete, because some new
-variables may have been introduced since this document was last updated.
-
-@example
-@group
-  PS1 = ">> ";
-  PS2 = "";
-  beep_on_error = 1;
-  default_save_format = "mat-binary";
-  define_all_return_values = 1;
-  do_fortran_indexing = 1;
-  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;
-  prefer_zero_one_indexing = 1;
-  print_empty_dimensions = 0;
-  treat_neg_dim_as_zero = 1;
-  warn_function_name_clash = 0;
-  whitespace_in_literal_matrix = "traditional";
-@end group
-@end example
-
-Some other known differences are:
-
-@itemize @bullet
-@item
-The Octave plotting functions are mostly compatible with the ones from
-@sc{Matlab} 3.x, but not from @sc{Matlab} 4.x.
-@end itemize
-
-The third category of differences is (hopefully) shrinking.  If you find
-a difference between Octave behavior and @sc{Matlab}, then you should send a
-description of this difference (with code illustrating the difference,
-if possible) to bug-octave@@bevo.che.wisc.edu.
-
-An archive of old postings to the Octave mailing lists is maintained
-on ftp.che.wisc.edu in the directory @file{/pub/octave/MAILING-LISTS}.
-
-@node Index,  , MATLAB compatibility, Top
-@appendix Concept Index
-
-@printindex cp
-
-@page
-@contents
-@bye
new file mode 100644
--- /dev/null
+++ b/doc/faq/Octave-FAQ.texi
@@ -0,0 +1,763 @@
+\input texinfo.tex      @c -*-texinfo-*-
+
+@setfilename FAQ.info
+@settitle Frequently asked questions about Octave (with answers)
+
+@setchapternewpage off
+
+@titlepage
+@title Octave FAQ
+@subtitle Frequently asked questions about Octave
+@subtitle December 14, 1996
+@sp 1
+@author John W. Eaton
+@page
+@end titlepage
+
+@ifinfo
+@node Top, What is Octave?, (dir), (dir)
+@top
+@unnumbered Preface
+@cindex FAQ for Octave, latest version
+@end ifinfo
+
+This is a list of frequently asked questions (FAQ) for Octave users.
+
+Some information in this FAQ was written for earlier versions of
+Octave and may now be obsolete.
+
+I'm looking for new questions (@emph{with} answers), better answers,
+or both.  Please send suggestions to bug-octave@@bevo.che.wisc.edu.
+If you have general questions about Octave, or need help for something
+that is not covered by the Octave manual or the FAQ, please use the
+help-octave@@bevo.che.wisc.edu mailing list.
+
+This FAQ is intended to supplement, not replace, the Octave manual.
+Before posting a question to the help-octave mailing list, you should
+first check to see if the topic is covered in the manual.
+
+@menu
+* What is Octave?::             
+* Version 2.0::               
+* Octave Features::             
+* Documentation::               
+* Getting Octave::              
+* Installation::                
+* Common problems::             
+* Getting additional help::     
+* Bug reports::                 
+* MATLAB compatibility::        
+* Index::                       
+@end menu
+
+@node What is Octave?, Version 2.0, Top, Top
+@chapter What is Octave?
+
+Octave is a high-level interactive language, primarily intended for
+numerical computations that is mostly compatible with
+@sc{Matlab}.@footnote{@sc{Matlab} is a registered trademark of The MathWorks,
+Inc.}
+
+Octave can do arithmetic for real and complex scalars and matrices,
+solve sets of nonlinear algebraic equations, integrate functions over
+finite and infinite intervals, and integrate systems of ordinary
+differential and differential-algebraic equations.
+
+Octave uses the GNU readline library to handle reading and editing
+input.  By default, the line editing commands are similar to the
+cursor movement commands used by GNU Emacs, and a vi-style line
+editing interface is also available.  At the end of each session, the
+command history is saved, so that commands entered during previous
+sessions are not lost.
+
+The Octave distribution includes a 200+ page Texinfo manual.  Access
+to the complete text of the manual is available via the help command
+at the Octave prompt.
+
+Two and three dimensional plotting is fully supported using gnuplot.
+
+The underlying numerical solvers are currently standard Fortran ones
+like Lapack, Linpack, Odepack, the Blas, etc., packaged in a library
+of C++ classes.  If possible, the Fortran subroutines are compiled
+with the system's Fortran compiler, and called directly from the C++
+functions.  If that's not possible, you can still compile Octave if
+you have the free Fortran to C translator f2c.
+
+Octave is also free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation.
+
+@node Version 2.0, Octave Features, What is Octave?, Top
+@chapter What's new in version 2.0 of Octave
+
+The long-awaited version 2.0 of Octave has now been released.  Many
+bugs have been fixed and lots of new features added.  Octave is now much
+more compatible with @sc{Matlab}.
+
+Version 2.0 fixes many bugs, but as with any ``x.y.0'' release there
+will be a few glitches.  There will probably be a 2.0.1 release to fix
+most of these problems.  You can help contribute to the quality of
+Octave by using it and submitting bug reports for the problems you
+encounter.
+
+A list of user-visible changes in recent versions of Octave may be found
+in the file NEWS, distributed in both source and binary releases of
+Octave.
+
+@node Octave Features, Documentation, Version 2.0, Top
+@chapter What features are unique to Octave?
+
+@menu
+* Command and variable name completion::  
+* Command history::             
+* Data structures::             
+* Short-circuit boolean operators::  
+* Increment and decrement operators::  
+* Unwind-protect::              
+* Variable-length argument lists::  
+* Variable-length return lists::  
+* Built-in ODE and DAE solvers::  
+@end menu
+
+@node Command and variable name completion, Command history, Octave Features, Octave Features
+@section Command and variable name completion
+
+@cindex Command completion
+@cindex Function name completion
+@cindex Variable name completion
+@cindex Name completion
+
+Typing a TAB character (ASCII code 9) on the command line causes Octave
+to attempt to complete variable, function, and file names.  Octave uses
+the text before the cursor as the initial portion of the name to
+complete.
+
+For example, if you type @samp{fu} followed by TAB at the Octave prompt,
+Octave will complete the rest of the name @samp{function} on the command
+line (unless you have other variables or functions defined that begin
+with the characters @samp{fu}).  If there is more than one possible
+completion, Octave will ring the terminal bell to let you know that your
+initial sequence of characters is not enough to specify a unique name.
+To complete the name, you may either edit the initial character sequence
+(usually adding more characters until completion is possible) or type
+another TAB to cause Octave to display the list of possible completions.
+
+@node Command history, Data structures, Command and variable name completion, Octave Features
+@section Command history
+
+@cindex Command history
+@cindex History
+
+When running interactively, Octave saves the commands you type in an
+internal buffer so that you can recall and edit them.  Emacs and vi
+editing modes are available with Emacs keybindings enabled by default.
+
+When Octave exits, the current command history is saved to the file
+@file{~/.octave_hist}, and each time Octave starts, it inserts the
+contents of the @file{~/.octave_hist} file in the history list so that
+it is easy to begin working where you left off.
+
+@node Data structures, Short-circuit boolean operators, Command history, Octave Features
+@section Data structures
+
+@cindex Data structures
+@cindex Structures
+
+Octave includes a limited amount of support for organizing data in
+structures.  The current implementation uses an associative array
+with indices limited to strings, but the syntax is more like C-style
+structures.  Here are some examples of using data structures in Octave.
+
+@itemize @bullet
+@item Elements of structures can be of any value type.
+
+@example
+@group
+octave:1> x.a = 1; x.b = [1, 2; 3, 4]; x.c = "string";
+octave:2> x.a
+x.a = 1
+octave:3> x.b
+x.b =
+
+  1  2
+  3  4
+
+octave:4> x.c
+x.c = string
+@end group
+@end example
+
+@item Structures may be copied.
+
+@example
+@group
+octave:1> y = x
+y =
+@{
+  a = 1
+  b =
+
+    1  2
+    3  4
+
+  c = string
+  s =
+
+    0.00000  0.00000  0.00000
+    0.00000  5.46499  0.00000
+    0.00000  0.00000  0.36597
+
+  u =
+
+    -0.40455  -0.91451
+    -0.91451   0.40455
+
+  v =
+
+    -0.57605   0.81742
+    -0.81742  -0.57605
+@}
+@end group
+@end example
+
+@item Structure elements may reference other structures.
+
+@example
+@group
+octave:1> x.b.d = 3
+x.b.d = 3
+octave:2> x.b
+ans =
+@{
+  d = 3
+@}
+octave:3> x.b.d
+ans = 3
+@end group
+@end example
+
+@item Functions can return structures.
+
+@example
+@group
+octave:1> function y = f (x)
+> y.re = real (x);
+> y.im = imag (x);
+> endfunction
+
+octave:2> f (rand + rand*I);
+ans =
+@{
+  im = 0.18033
+  re = 0.19069
+@}
+@end group
+@end example
+
+@item Function return lists can include structure elements, and they may
+be indexed like any other variable.
+
+@example
+@group
+octave:1> [x.u, x.s(2:3,2:3), x.v] = svd ([1, 2; 3, 4]);
+octave:2> x
+x =
+@{
+  s =
+
+    0.00000  0.00000  0.00000
+    0.00000  5.46499  0.00000
+    0.00000  0.00000  0.36597
+
+  u =
+
+    -0.40455  -0.91451
+    -0.91451   0.40455
+
+  v =
+
+    -0.57605   0.81742
+    -0.81742  -0.57605
+@}
+@end group
+@end example
+
+@item You can also use the function @code{is_struct} to determine
+whether a given value is a data structure.  For example
+
+@example
+is_struct (x)
+@end example
+
+@noindent
+returns 1 if the value of the variable @var{x} is a data structure.
+@end itemize
+
+This feature should be considered experimental, but you should expect it
+to work.  Suggestions for ways to improve it are welcome.
+
+@node Short-circuit boolean operators, Increment and decrement operators, Data structures, Octave Features
+@section Short-circuit boolean operators
+
+@cindex Boolean operators, short-circuit
+@cindex Logical operators, short-circuit
+@cindex Short-circuit boolean operators
+@cindex Operators, boolean
+
+Octave's @samp{&&} and @samp{||} logical operators are evaluated in
+a short-circuit fashion (like the corresponding operators in the C
+language) and work differently than the element by element operators
+@samp{&} and @samp{|}.
+
+@node Increment and decrement operators, Unwind-protect, Short-circuit boolean operators, Octave Features
+@section Increment and decrement operators
+
+@cindex Increment operators
+@cindex Decrement operators
+@cindex Operators, increment
+@cindex Operators, decrement
+
+Octave includes the C-like increment and decrement operators @samp{++}
+and @samp{--} in both their prefix and postfix forms.
+
+For example, to pre-increment the variable @var{x}, you would write
+@code{++@var{x}}.  This would add one to @var{x} and then return the new
+value of @var{x} as the result of the expression.  It is exactly the
+same as the expression @code{@var{x} = @var{x} + 1}.
+
+To post-increment a variable @var{x}, you would write @code{@var{x}++}.
+This adds one to the variable @var{x}, but returns the value that
+@var{x} had prior to incrementing it.  For example, if @var{x} is equal
+to 2, the result of the expression @code{@var{x}++} is 2, and the new
+value of @var{x} is 3.
+
+For matrix and vector arguments, the increment and decrement operators
+work on each element of the operand.
+
+It is not currently possible to increment index expressions.  For
+example, you might expect that the expression @code{@var{v}(4)++} would
+increment the fourth element of the vector @var{v}, but instead it
+results in a parse error.  This problem may be fixed in a future
+release of Octave.
+
+@node Unwind-protect, Variable-length argument lists, Increment and decrement operators, Octave Features
+@section Unwind-protect
+
+@cindex Unwind-protect
+
+Octave supports a limited form of exception handling modelled after the
+unwind-protect form of Lisp.  The general form of an
+@code{unwind_protect} block looks like this:
+
+@example
+@group
+unwind_protect
+  @var{body}
+unwind_protect_cleanup
+  @var{cleanup}
+end_unwind_protect
+@end group
+@end example
+
+@noindent
+Where @var{body} and @var{cleanup} are both optional and may contain any
+Octave expressions or commands.  The statements in @var{cleanup} are 
+guaranteed to be executed regardless of how control exits @var{body}.
+
+The @code{unwind_protect} statement is often used to reliably restore
+the values of global variables that need to be temporarily changed.
+
+@node Variable-length argument lists, Variable-length return lists, Unwind-protect, Octave Features
+@section Variable-length argument lists
+
+@cindex Variable-length argument lists
+@cindex Argument lists, variable-length
+
+Octave has a real mechanism for handling functions that take an
+unspecified number of arguments, so it is no longer necessary to place
+an upper bound on the number of optional arguments that a function can
+accept.
+
+Here is an example of a function that uses the new syntax to print a
+header followed by an unspecified number of values:
+
+@example
+@group
+function foo (heading, ...)
+  disp (heading);
+  va_start ();
+  while (--nargin)
+    disp (va_arg ());
+  endwhile
+endfunction
+@end group
+@end example
+
+Calling @code{va_start()} positions an internal pointer to the first
+unnamed argument and allows you to cycle through the arguments more than
+once.  It is not necessary to call @code{va_start()} if you do not plan
+to cycle through the arguments more than once.
+
+The function @code{va_arg()} returns the value of the next available
+argument and moves the internal pointer to the next argument.  It is an
+error to call @code{va_arg()} when there are no more arguments
+available.
+
+It is also possible to use the keyword @var{all_va_args} to pass all
+unnamed arguments to another function.
+
+@node Variable-length return lists, Built-in ODE and DAE solvers, Variable-length argument lists, Octave Features
+@section Variable-length return lists
+
+@cindex Variable-length return lists
+@cindex Return lists, variable-length
+
+Octave also has a real mechanism for handling functions that return an
+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
+@samp{N} values:
+
+@example
+@group
+function [...] = foo (n)
+  for i = 1:n
+    vr_val (i);
+  endfor
+endfunction
+@end group
+@end example
+
+@node Built-in ODE and DAE solvers,  , Variable-length return lists, Octave Features
+@section Built-in ODE and DAE solvers
+
+@cindex DASSL
+@cindex LSODE
+
+Octave includes LSODE and DASSL for solving systems of stiff ordinary
+differential and differential-algebraic equations.  These functions are
+built in to the interpreter.
+
+@node Documentation, Getting Octave, Octave Features, Top
+@chapter What documentation exists for Octave?
+
+@cindex Octave, documentation
+
+The Octave distribution includes a 220+ page manual that is also
+distributed under the terms of the GNU GPL.
+
+The Octave manual is intended to be a complete reference for Octave, but
+it is not a finished document.  If you have problems using it, or find
+that some topic is not adequately explained, indexed, or
+cross-referenced, please send a bug report to bug-octave@@bevo.che.wisc.edu.
+
+Because the Octave manual is written using Texinfo, the complete text of
+the Octave manual is also available on line using the GNU Info system
+via the GNU Emacs, info, or xinfo programs, or by using the @samp{help -i} 
+command to start the GNU info browser directly from the Octave prompt.
+
+It is also possible to use your favorite WWW browser to read the Octave
+manual (or any other Info file) by using Roar Smith's info2www program
+to convert GNU Info files to HTML.  The source for info2www is available
+from @url{ftp://ftp.che.wisc.edu/pub/www}.
+
+@node Getting Octave, Installation, Documentation, Top
+@chapter Obtaining Source Code
+
+@cindex Source code
+
+@menu
+* Octave for Unix::             
+* Octave for other platforms::  
+* latest versions::             
+@end menu
+
+@node Octave for Unix, Octave for other platforms, Getting Octave, Getting Octave
+@section How do I get a copy of Octave for Unix?
+
+You can get Octave from a friend who has a copy, by anonymous FTP, or by
+ordering a tape or CD-ROM from the Free Software Foundation (FSF).
+
+@cindex Octave, ordering
+@cindex Octave, getting a copy
+
+Octave was not developed by the FSF, but the FSF does distribute Octave,
+and the developers of Octave support the efforts of the FSF by
+encouraging users of Octave to order Octave on tape or CD directly from
+the FSF.
+
+The FSF is a nonprofit organization that distributes software and
+manuals to raise funds for more GNU development.  Buying a tape or CD
+from the FSF contributes directly to paying staff to develop GNU
+software.  CD-ROMs cost $400 if an organization is buying, or $100 if an
+individual is buying.  Tapes cost around $200 depending on media type.
+
+The FSF only makes new CD releases a few times a year, so if you are
+interested specifically in Octave, I recommend asking for the latest
+release on tape.
+
+@cindex FSF [Free Software Foundation]
+@cindex GNU [GNU's not unix]
+
+For more information about ordering from the FSF, contact
+gnu@@prep.ai.mit.edu, phone (617) 542-5942 or anonymous ftp file
+@file{/pub/gnu/GNUinfo/ORDERS} from prep.ai.mit.edu or one of the sites
+listed below.
+
+@cindex FSF, contact <gnu@@prep.ai.mit.edu>
+@cindex GNUware, anonymous FTP sites
+
+If you are on the Internet, you can copy the latest distribution
+version of Octave from the file @file{/pub/octave/octave-M.N.tar.gz}, on
+the host @file{ftp.che.wisc.edu}.  This tar file has been compressed
+with GNU gzip, so be sure to use binary mode for the transfer.  @samp{M}
+and @samp{N} stand for version numbers; look at a listing of the
+directory through ftp to see what version is available.  After you
+unpack the distribution, be sure to look at the files @file{README} and
+@file{INSTALL}.
+
+Binaries for several popular systems are also available.  If you would
+like help out by making binaries available for other systems, please
+contact bug-octave@@bevo.che.wisc.edu.
+
+A list of user-visible changes since the last release is available in
+the file @file{NEWS}.  The file @file{ChangeLog} in the source
+distribution contains a more detailed record of changes made since the
+last release.
+
+@node Octave for other platforms, latest versions, Octave for Unix, Getting Octave
+@section How do I get a copy of Octave for (some other platform)?
+
+@cindex VMS support
+@cindex VAX
+@cindex MS-DOS support
+@cindex DJGPP
+@cindex EMX
+@cindex OS/2 support
+
+Octave currently runs on Unix-like systems only.  It should be possible
+to make Octave work on other systems.  If you are interested in porting
+Octave to other systems, please contact bug-octave@@bevo.che.wisc.edu.
+
+@node latest versions,  , Octave for other platforms, Getting Octave
+@section What is the latest version of Octave
+
+@cindex Octave, version date
+
+The latest version of Octave is 2.0, released December 1996.
+
+@node Installation, Common problems, Getting Octave, Top
+@chapter Installation Issues and Problems
+
+@cindex Octave, building 
+
+Octave requires approximately 50MB of disk storage to unpack and
+install (significantly less if you don't compile with debugging
+symbols).
+
+Octave has been compiled and tested with g++ and libg++ on a
+SPARCstation 2 running SunOS 4.1.2, an IBM RS/6000 running AIX 3.2.5,
+DEC Alpha systems running OSF/1 1.3 and 3.0, a DECstation 5000/240
+running Ultrix 4.2a, and i486 systems running Linux.  It should work on
+most other Unix systems that have a working port of g++ and libg++.
+
+@menu
+* What else do I need?::        
+* Other C++ compilers?::        
+@end menu
+
+@node What else do I need?, Other C++ compilers?, Installation, Installation
+@section What else do I need?
+
+@cindex GNU gcc
+@cindex GNU g++
+@cindex libg++
+@cindex GNU Make
+@cindex Flex
+@cindex GNU Bison
+
+  In order to build Octave, you will need a current version
+of g++, libg++, and GNU make.  If you don't have these tools, you can
+get them from many anonymous ftp archives, including ftp.che.wisc.edu,
+ftp.uu.net, prep.ai.mit.edu, and wuarchive.wustl.edu, or by writing to
+the FSF at 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+
+@node Other C++ compilers?,  , What else do I need?, Installation
+@section Can I compile Octave with another C++ compiler?
+
+Currently, Octave can only be compiled with the GNU C++ compiler.  It
+would be nice to make it possible to compile Octave with other C++
+compilers, but the maintainers do not have sufficient time to devote to
+this.  If you are interested in working to make Octave portable to other
+compilers, please contact bug-octave@@bevo.che.wisc.edu.
+
+@node Common problems, Getting additional help, Installation, Top
+@chapter Common problems
+
+This list is probably far too short.  Feel free to suggest additional
+questions (preferably with answers!)
+
+@itemize @bullet
+@item
+Octave takes a long time to find symbols.
+
+Octave is probably spending this time recursively searching directories
+for function files.  Check the value of your LOADPATH.  For those
+elements that end in @samp{//}, do any name a very large directory tree?
+Does it contain directories that have a mixture of files and
+directories?  In order for the recursive directory searching code to
+work efficiently, directories that are to be searched recursively should
+have either function files only, or subdirectories only, but not a
+mixture of both.  Check to make sure that Octave's standard set of
+function files is installed this way.
+@end itemize
+
+@node Getting additional help, Bug reports, Common problems, Top
+@chapter Getting additional help
+
+@cindex Additional help
+@cindex Mailing lists, help-octave
+
+The mailing list
+
+@example
+help-octave@@bevo.che.wisc.edu
+@end example
+
+@noindent
+is available for questions related to using, installing, and porting
+Octave that are not adequately answered by the Octave manual or by this
+document.
+
+If you would like to join the discussion and receive all messages sent
+to the list, please send a short note to
+
+@example
+@group
+help-octave-request@@bevo.che.wisc.edu
+            ^^^^^^^
+@end group
+@end example
+
+@strong{Please do not} send requests to be added or removed from the the
+mailing list, or other administrative trivia to the list itself.
+
+An archive of old postings to the help-octave mailing list is maintained
+on ftp.che.wisc.edu in the directory @file{/pub/octave/MAILING-LISTS}.
+
+@node Bug reports, MATLAB compatibility, Getting additional help, Top
+@chapter I think I have found a bug in Octave.
+
+@cindex Bug in Octave, newly found
+
+``I think I have found a bug in Octave, but I'm not sure.  How do I know,
+and who should I tell?''
+
+@cindex Manual, for Octave
+
+First, see the section on bugs and bug reports in the Octave manual.
+The Octave manual is included in the Octave distribution.
+
+When you report a bug, make sure to describe the type of computer you
+are using, the version of the operating system it is running, and the
+version of Octave that you are using.  Also provide enough code so that
+the Octave maintainers can duplicate your bug.
+
+If you have Octave working at all, the easiest way to do this is to use
+the Octave function @code{bug_report}.  When you execute this function,
+Octave will prompt you for a subject and then invoke the editor on a
+file that already contains all the configuration information.  When you
+exit the editor, Octave will mail the bug report for you.
+
+@cindex Octave bug report
+@cindex Mailing lists, bug-octave
+
+If for some reason you cannot use Octave's @code{bug_report} function,
+mail your bug report to "bug-octave@@bevo.che.wisc.edu".  Your message
+needs to include enough information to allow the maintainers of Octave
+to fix the bug.  Please read the section on bugs and bug reports in the
+Octave manual for a list of things that should be included in every bug
+report.
+
+@node MATLAB compatibility, Index, Bug reports, Top
+@chapter Porting programs from @sc{Matlab} to Octave
+
+@cindex @sc{Matlab} compatibility
+@cindex Compatibility with @sc{Matlab}
+
+``I wrote some code for @sc{Matlab}, and I want to get it running under
+Octave.  Is there anything I should watch out for?''
+
+The differences between Octave and @sc{Matlab} typically fall into one of
+three categories:
+
+@enumerate
+@item
+Irrelevant.
+
+@item
+Known differences, perhaps configurable with a user preference variable.
+
+@item
+Unknown differences.
+@end enumerate
+
+The first category, irrelevant differences, do not affect computations
+and most likely do not affect the execution of function files.
+
+The differences of the second category are usually because the authors
+of Octave decided on a better (subjective) implementation that the way
+@sc{Matlab} does it, and so introduced ``user preference variables'' so that
+you can customize Octave's behavior to be either @sc{Matlab}-compatible or
+to use Octave's new features.  To make Octave more @sc{Matlab}-compatible,
+put the following statements in your @file{~/.octaverc} file, or use the
+command line option @samp{--traditional}, which implies all of these
+settings.  Note that this list may not be complete, because some new
+variables may have been introduced since this document was last updated.
+
+@example
+@group
+  PS1 = ">> ";
+  PS2 = "";
+  beep_on_error = 1;
+  default_save_format = "mat-binary";
+  define_all_return_values = 1;
+  do_fortran_indexing = 1;
+  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;
+  prefer_zero_one_indexing = 1;
+  print_empty_dimensions = 0;
+  treat_neg_dim_as_zero = 1;
+  warn_function_name_clash = 0;
+  whitespace_in_literal_matrix = "traditional";
+@end group
+@end example
+
+Some other known differences are:
+
+@itemize @bullet
+@item
+The Octave plotting functions are mostly compatible with the ones from
+@sc{Matlab} 3.x, but not from @sc{Matlab} 4.x.
+@end itemize
+
+The third category of differences is (hopefully) shrinking.  If you find
+a difference between Octave behavior and @sc{Matlab}, then you should send a
+description of this difference (with code illustrating the difference,
+if possible) to bug-octave@@bevo.che.wisc.edu.
+
+An archive of old postings to the Octave mailing lists is maintained
+on ftp.che.wisc.edu in the directory @file{/pub/octave/MAILING-LISTS}.
+
+@node Index,  , MATLAB compatibility, Top
+@appendix Concept Index
+
+@printindex cp
+
+@page
+@contents
+@bye