--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/faq/OctaveFAQ.texi	Tue Nov 10 15:02:25 2009 -0500
@@ -0,0 +1,1236 @@
+% Copyright (C) 1997, 1998, 1999, 2001, 2003, 2004, 2005, 2007, 2008, 2009
+%               John W. Eaton
+%
+% This file is part of Octave.
+%
+% Octave is 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; either version 3 of the License, or (at
+% your option) any later version.
+% 
+% Octave is distributed in the hope that it will be useful, but WITHOUT
+% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+% for more details.
+% 
+% You should have received a copy of the GNU General Public License
+% along with Octave; see the file COPYING.  If not, see
+% <http://www.gnu.org/licenses/>.
+
+\input texinfo.tex      @c -*-texinfo-*-
+
+@setfilename OctaveFAQ.info
+@settitle Frequently asked questions about Octave (with answers)
+
+@setchapternewpage off
+@direntry
+* OctaveFAQ: (OctaveFAQ).  Frequently asked questions about Octave
+@end direntry
+@titlepage
+@title Octave FAQ
+@subtitle Frequently asked questions about Octave
+@subtitle September 2008
+@sp 1
+@author John W. Eaton and David Bateman
+@page
+@end titlepage
+
+@ifnottex
+@node Top
+@top
+@unnumbered Preface
+@cindex FAQ for Octave, latest version
+@end ifnottex
+
+This is a list of frequently asked questions (FAQ) for Octave users.
+
+We are always looking for new questions (@emph{with} answers), better
+answers, or both.  Please send suggestions to @email{bug@@octave.org}.
+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
+@email{help@@octave.org} mailing list.
+
+This FAQ is intended to supplement, not replace, the Octave manual.
+Before posting a question to the @email{help@@octave.org} mailing list,
+you should first check to see if the topic is covered in the manual.
+
+@menu
+* What is Octave?::  
+* Licensing Issues::
+* How can I cite Octave?::  
+* Series 3.0.N::  
+* Octave Features::  
+* Learning more about Octave:: 
+* Getting Octave::  
+* Installation::  
+* Common problems::             
+* How do I ...?::  
+* MATLAB compatibility:: 
+* Index::                       
+@end menu
+
+@node What is Octave?
+@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, complex or integer-valued 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 590+ page Texinfo manual.  Access
+to the complete text of the manual is available via the help command
+@c really, the *complete* text?
+at the Octave prompt.
+
+@menu
+* Who develops Octave?::  
+* Why GNU Octave?::  
+* What version should I use?::  
+* On what platforms does Octave run?::  
+@end menu
+
+@node Who develops Octave?
+@section Who develops Octave?
+
+Discussions about writing the software that would eventually become
+Octave started in about 1988 with James B. Rawlings and John W. Eaton at
+the University of Texas.  John W. Eaton was the original author of
+Octave, starting full-time development in February 1992.  He is still
+the primary maintainer.  The community
+of users/developers has in addition contributed some code and fuels the
+discussion on the mailing lists @email{help@@octave.org} (user forum),
+@email{bug@@octave.org} (bug reports), @email{maintainers@@octave.org}
+(development issues), and @email{octave-dev@@lists.sourceforge.net} (all
+things related to the Octave Forge repository of user-contributed
+functions).
+
+@node Why GNU Octave?
+@section Why GNU Octave?
+
+The GNU Project was launched in 1984 to develop a complete Unix-like
+operating system which is free software: the GNU system.
+
+GNU is a recursive acronym for ``GNU's Not Unix''; it is pronounced
+guh-noo, approximately like canoe.
+
+The Free Software Foundation (FSF) is the principal organizational
+sponsor of the GNU Project.
+
+Octave became GNU Octave in 1997 (beginning with version 2.0.6).  This
+meant agreeing to consider Octave a part of the GNU Project and support
+the efforts of the FSF.  However, Octave is not and has never been
+developed by the FSF.
+
+For more information about the GNU project, see @url{www.gnu.org}.
+
+@cindex FSF [Free Software Foundation]
+@cindex GNU [GNU's not unix]
+
+@node What version should I use?
+@section What version should I use?
+
+In general, you will find the latest version on 
+@url{http://www.octave.org/download.html}.  It is
+recommended to use the ``testing'' version of octave for general use,
+and the ``development'' version if you want the latest features.
+
+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 On what platforms does Octave run?
+@section On what platforms does Octave run?
+
+Octave runs on various Unices---at least Linux and Solaris, Mac OS X,
+Windows and anything you can compile it on.  Binary distributions exist
+at least for Debian, Suse, Fedora and RedHat Linuxes (Intel and AMD
+CPUs, at least), for Mac Os X and Windows' 98, 2000 and XP.
+
+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 Licensing Issues
+@chapter Licensing Issues
+
+@menu
+* If I write code using Octave do I have to release it under the GPL?: GPL
+* Since the MEX interface allows plugins to be distributed under terms that are incompatible with the GPL, does this mean that you are encouraging people to to write non-free software for Octave?: Licensing MEX Files
+* I wrote a program that links with Octave libraries and I don't want to release it under the terms of the GPL.  Will you change the license of the Octave libraries for me?: Requesting License Changes
+@end menu
+
+@node GPL
+@section If I write code using Octave do I have to release it under the GPL?
+
+The answer depends on precisely how the code is written and how it works.
+
+Code written entirely in the scripting language of Octave
+(interpreted code in .m files) may be released under the terms of
+whatever license you choose.
+
+Code written using Octave's native plug-in interface (also known
+as a .oct file) necessarily links with Octave internals and is
+considered a derivative work of Octave and therefore must be
+released under terms that are compatible with the GPL.
+
+Code written using Octave's implementation of the Matlab MEX
+interface may be released under the terms of whatever license you
+choose, provided that the following conditions are met:
+
+@enumerate
+@item
+The plugin should not use any bindings that are specific to Octave.  In
+other words, the MEX file must use the MEX interface only, and not also
+call on other Octave internals.  It should be possible in principle to
+use the MEX file with other programs that implement the MEX interface
+(e.g., Matlab).
+
+@item
+The MEX file should not be distributed together with Octave in such a
+way that they effectively create a single work.  For example, you should
+not distribute the MEX file and Octave together in a single package such
+that Octave automatically loads and runs the MEX file when it starts up.
+There are other possible ways that you might effectively create a single
+work; this is just one example.
+@end enumerate
+
+A program that embeds the Octave interpreter (e.g., by calling the
+"octave_main" function), or that calls functions from Octave's
+libraries (e.g., liboctinterp, liboctave, or libcruft) is
+considered a derivative work of Octave and therefore must be
+released under terms that are compatible with the GPL.
+
+@node Licensing MEX Files
+@section Since the MEX interface allows plugins to be distributed under terms that are incompatible with the GPL, does this mean that you are encouraging people to to write non-free software for Octave?
+
+No.  The original reason for implementing the MEX interface for Octave
+was to allow Octave to run free software that uses MEX files (the
+particular goal was to run SundialsTB in Octave).  The intent was to
+liberate that software from Matlab and increase the amount of free
+software available to Octave users, not to enable people to write
+proprietary code for Octave.  For the good of the community, we strongly
+encourage users of Octave to release the code they write for Octave
+under terms that are compatible with the GPL.
+
+@node Requesting License Changes
+@section I wrote a program that links with Octave libraries and I don't want to release it under the terms of the GPL.  Will you change the license of the Octave libraries for me?
+
+No.  Instead of asking us to change the licensing terms for Octave, we
+recommend that you release your program under terms that are compatible
+with the GPL so that the free software community can benefit from your
+work the same as you have benefitted from the work of all the people who
+have contributed to Octave.
+
+@node How can I cite Octave?
+@chapter How can I cite Octave?
+
+Pointing to @url{http://www.octave.org} is good, because that gives
+people a direct way to find out more.  If citation of a URL is not
+allowed by a publisher, or if you also want to point to a traditional
+reference, then you can cite the Octave manual:
+
+@example
+@group
+@@BOOK@{eaton:2008,
+  author =     "John W. Eaton and David Bateman and Søren Hauberg",
+  title =      "GNU Octave Manual Version 3",
+  publisher =  "Network Theory Limited",
+  year =       "2008",
+  isbn =       "0-9546120-6-X"
+@}
+@end group
+@end example
+
+@node Series 3.0.N
+@chapter What's new in version series 3.0.N and 3.1.N of Octave
+
+The 3.0.N series has enough new features to justify a major version
+number change. The 3.0.N series brings
+
+@itemize @bullet
+
+@item integer types
+
+@item fixed point arithmetic
+
+@item sparse matrices
+
+@item Linear programming code based on GLPK
+
+@item 64-bit compilation support
+
+@item gzipped files and stream and consequently support of matlab v7 files
+
+@item better support for both msvc and mingw
+
+@item a fully compatible MEX interface
+
+@item many many other minor features and compatibility changes
+
+@end itemize
+
+Here are some features that have been around since 2.1.N
+
+@itemize @bullet
+
+@item NDarrays 
+
+@item cells
+
+@end itemize
+
+The 3.1.N series is the current development release and will become a
+3.2.N release in the future. This series brings the new features
+
+@itemize
+@item OpenGL backend
+
+An experimental OpenGL graphics backend to replace the gnuplot
+
+@item Object Orient Programming
+
+@item Block comments
+
+@item imwrite and imread 
+
+The functions are based on the GraphicsMagick library.
+
+@item Lazy transpose
+
+Special treatment in the parser of things like "a' * b", where the
+transpose is never explicitly formed but a flag is rather passed to the
+underlying LAPACK code.
+
+@item Single precision type
+
+@item Improved array indexing
+The underlying code used for indexing of arrays has been completely
+rewritten and so the indexing of arrays is now significantly faster.
+@end itemize
+
+
+@node Octave Features
+@chapter What features are unique to Octave?
+
+@menu
+* Functions defined on the command-line::
+* Comments with #::            
+* Strings delimitted by double quotes "::
+* Line continuation by backslash::
+* Informative block closing::
+* Coherent syntax::             
+* Exclamation mark as not operator::
+* Increment and decrement operators::  
+* Unwind-protect::              
+* Built-in ODE and DAE solvers::
+@end menu
+
+This section refers to Matlab R2008b and Octave 2.1.51.
+
+@node Functions defined on the command-line
+@section Functions defined on the command-line
+
+Functions can be defined by entering code on the command line, a
+feature not supported by the other leading brand.  For example, you may
+type:
+
+@example
+@group
+octave:1> function s = hello_string (to_who)
+> ## Say hello 
+> if nargin<1, to_who = "World"; end
+> s = ["Hello ",\
+>      to_who];
+> endfunction
+octave:2> hello_string ("Moon")
+ans = Hello Moon
+@end group
+@end example
+
+@node Comments with #           
+@section Comments with #
+
+The pound character, @samp{#}, may be used to start comments, in addition
+to @samp{%}.  See the previous example.  The major advantage of this is
+that as @samp{#} is also a comment character for unix script files, any
+file that starts with a string like @samp{#! /usr/bin/octave -q} will be
+treated as an octave script and be executed by octave.
+
+@node Strings delimitted by double quotes " 
+@section Strings delimitted by double quotes " 
+The double quote, @samp{"}, may be used to delimit strings, in addition to
+the single quote @samp{'}.  See the previous example.  Also, double-quoted
+strings include backslash interpretation (like C++, C, and Perl) while
+single quoted are uninterpreted (like Matlab and Perl).
+ 
+@node Line continuation by backslash 
+@section Line continuation by backslash 
+
+Lines can be continued with a backslash, @samp{\}, in addition to three
+points @samp{@dots{}}.  See the previous example.
+
+@node Informative block closing
+@section Informative block closing
+
+You may close @code{function}, @code{for}, @code{while}, @code{if},
+@dots{} blocks with @code{endfunction}, @code{endfor}, @code{endwhile},
+@dots{} keywords in addition to using @code{end}.  As with Matlab, the
+@code{end} (or @code{endfunction}) keyword that marks the end of a
+function defined in a @file{.m} file is optional.
+
+@node Coherent syntax
+@section Coherent syntax
+
+Indexing other things than variables is possible, as in:
+@example
+@group
+octave:1> [3 1 4 1 5 9](3)
+ans = 4
+octave:2> cos([0 pi pi/4 7])(3)
+ans = 0.70711
+@end group
+@end example
+
+@node Exclamation mark as not operator
+@section Exclamation mark as not operator
+
+The exclamation mark '!' (aka ``Bang!'') is a negation operator, just
+like the tilde '~':
+
+@example
+@group
+octave:1> if ! strcmp (program_name, "octave"),
+>   "It's an error"
+> else
+>   "It works!"
+> end
+ans = It works!
+@end group
+@end example
+
+@node Increment and decrement operators
+@section Increment and decrement operators
+
+@cindex Increment operators
+@cindex Decrement operators
+@cindex Operators, increment
+@cindex Operators, decrement
+
+If you like the @samp{++}, @samp{+=} etc operators, rejoice!
+Octave includes the C-like increment and decrement operators @samp{++}
+and @samp{--} in both their prefix and postfix forms, in addition to
+@samp{+=}, @samp{-=}, @samp{*=}, @samp{/=}, @samp{^=}, @samp{.*=},
+@samp{./=}, and @samp{.^=}.
+
+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{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{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.
+
+
+@node Unwind-protect
+@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.
+
+Matlab can be made to do something similar with their @code{OnCleanUp}
+function that was introduced in 2008a.
+
+@node Built-in ODE and DAE solvers
+@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 Learning more about Octave
+@chapter What documentation exists for Octave?
+
+@menu
+* Documentation::
+* Getting additional help::            
+* User community::
+* Bug reports::
+@end menu
+
+
+@node Documentation
+@section What documentation exists for Octave?
+
+@cindex Octave, documentation
+
+The Octave distribution includes a 590+ page manual that is also
+distributed under the terms of the GNU GPL.
+It is available on the web at
+@url{http://www.octave.org/docs.html} and you will also
+find there instructions on how to order a paper version.
+
+The complete text of the Octave manual is also available 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.
+
+If you have problems using this documentation, or find that some topic
+is not adequately explained, indexed, or cross-referenced, please send
+a bug report to @email{bug@@octave.org}.
+
+
+@node Getting additional help
+@section Getting additional help
+
+@cindex Additional help
+@cindex Mailing lists, help-octave
+
+If you can't find an answer to your question, the
+@email{help@@octave.org} mailing list is available for questions related
+to using, installing, and porting Octave that are not adequately
+answered by the Octave manual or by this document.
+
+@node User community
+@section User community
+
+To subscribe to the list, go to @url{www.octave.org/archive.html} and
+follow the link to the subscription page for the list.
+
+@strong{Please do not} send requests to be added or removed from 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 @url{http://www.octave.org/archive.html}.
+
+You will also find some user advice and code spread over the web.  Good
+starting points are the Octave Wiki @url{http://wiki.octave.org} and
+Octave-Forge @url{http://octave.sourceforge.net}
+
+@node Bug reports
+@section 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.
+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 (in a unix-like
+operating system).
+
+@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 @email{bug@@octave.org}.  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 Getting Octave
+@chapter Getting Octave
+
+@menu
+* Source code::  
+* Pre-compiled binary packages::
+* Octave for other platforms::
+@end menu
+
+@node Source code
+@section Source code
+@cindex Source code
+
+Source code is available on the Octave development site, where you are
+sure to get the latest version.
+
+@itemize @bullet
+@item @url{http://www.octave.org/download.html}
+@item @url{ftp://ftp.octave.org/pub/octave/}
+@end itemize
+
+Since Octave is distrubted under the terms of the GPL, 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).
+
+@node Pre-compiled binary packages
+@section Pre-compiled binary packages
+@cindex  Pre-compiled binary packages
+@cindex  Binaries
+
+The Octave project does not distribute binary packages, but other
+projects do.  For an up-to-date listing of packagers, see:
+
+@itemize @bullet
+@item @url{http://www.octave.org/download.html}
+@item @url{http://wiki.octave.org/wiki.pl?CategoryInstall}
+@end itemize
+
+As of today, Octave binaries are available at least on Debian, RedHat,
+Suse and Fedora Linuxes, Mac OS X, Windows' 98, 2000 and XP.
+
+@node Octave for other platforms
+@section How do I get a copy of Octave for (some other platform)?
+
+@cindex VMS support
+@cindex VAX
+@cindex MS-DOS support
+@cindex Windows support
+@cindex DJGPP
+@cindex EMX
+@cindex OS/2 support
+
+Octave currently runs on Unix-like systems, Mac OS X, and Windows.
+It should be possible to make Octave work on other systems as well.  
+If you are interested in porting Octave to other systems, please contact
+@email{bug@@octave.org}.
+
+@c @menu
+@c * Octave for Unix::             
+@c * Octave for other platforms::  
+@c * latest versions::             
+@c @end menu
+
+@c @cindex Octave, ordering
+@c @cindex Octave, getting a copy
+
+@node Installation
+@chapter Installation Issues and Problems
+
+@cindex Octave, building 
+
+Octave 3.2 require approximately 800MB of disk storage to unpack
+and compile from source (considerably less if you don't compile with
+debugging symbols).  Once installed, Octave requires approximately 200MB
+of disk space (again, considerably less if you don't compile with
+debugging symbols).
+
+@menu
+* What else do I need?::        
+* Other C++ compilers?::        
+@end menu
+
+@node What else do I need?
+@section What else do I need?
+
+@cindex GNU gcc
+@cindex GNU g++
+@cindex libg++
+@cindex GNU Make
+@cindex Flex
+@cindex GNU Bison
+
+To compile Octave, you will need a recent version of GNU Make.  You
+will also need GCC 3.3 or later, although GCC 4.1 or later is 
+recommended.
+
+@strong{You must have GNU Make to compile octave}.  Octave's Makefiles
+use features of GNU Make that are not present in other versions of make.
+GNU Make is very portable and easy to install.
+
+@node Other C++ compilers?
+@section Can I compile Octave with another C++ compiler?
+
+Yes, but development is done primarily with GCC, so you may hit some
+incompatibilities.  Octave is intended to be portable to any standard
+conforming compiler.  If you have difficulties that you think are bugs,
+please report them to the @email{bug@@octave.org} mailing list, or ask
+for help on the @email{help@@octave.org} mailing list.
+
+@node Common problems
+@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 uses the @code{genpath} function to recursively add directories
+to the list of directories searched for function files.  Check the list
+of directories with the @code{path} command. If the path list is very
+long check your use of the @code{genpath} function.
+
+@item
+When plotting Octave occasionally gives me errors like @samp{gnuplot> 9 0.735604
+line 26317: invalid command}.
+
+There is a known bug in gnuplot 4.2 that can cause an off by one error
+while piping data to gnuplot. The relevant gnuplot bug report can be
+found at @url{http://sourceforge.net/tracker/index.php?func=detail&aid=1716556&group_id=2055&atid=102055}
+
+If you have obtained your copy of Octave from a distribution please file
+a bug report requesting that the fix reported in the above bug report be
+included.
+
+@item
+I cannot install a package. Octave complains about a missing @code{mkoctfile}.
+
+Most distributions split Octave into several packages. The script
+@code{mkoctfile} is then part of a separate package:
+@itemize @minus
+@item
+Debian/Ubuntu
+
+@code{aptitude install octave3.0-headers}
+
+@item
+Fedora
+
+@code{yum install octave-devel}
+
+@end itemize
+@end itemize
+
+@node How do I ...?
+@chapter  How do I ...?
+
+@menu
+* How do I set the number of displayed decimals?::
+@end menu
+
+@cindex Tips and tricks
+@cindex How do I @dots{} ?
+
+@node How do I set the number of displayed decimals?
+@section How do I set the number of displayed decimals?
+
+@example
+@group
+octave:1> format long
+octave:2> pi
+pi = 3.14159265358979
+octave:3> format short
+octave:4> pi
+pi = 3.1416
+@end group
+@end example
+
+@node MATLAB compatibility
+@chapter Porting programs from @sc{Matlab} to Octave
+
+@cindex @sc{Matlab} compatibility
+@cindex Compatibility with @sc{Matlab}
+
+People often ask
+
+``I wrote some code for @sc{Matlab}, and I want to get it running under
+Octave.  Is there anything I should watch out for?''
+
+or alternatively
+
+``I wrote some code in Octave, and want to share it with @sc{Matlab}
+users.  Is there anything I should watch out for?''
+
+which is not quite the same thing.  There are still a number of
+differences between Octave and @sc{Matlab}, however in general
+differences between the two are considered as bugs.  Octave might
+consider that the bug is in @sc{Matlab} and do nothing about it, but
+generally functionality is almost identical.  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 @email{bug@@octave.org}.
+
+Furthermore, Octave adds a few syntactical extensions to Matlab that
+might cause some issues when exchanging files between Matlab and Octave
+users. As both Octave and @sc{Matlab} are under constant development the
+information in this section is subject to change at anytime.
+
+You should also look at the page
+@url{http://octave.sourceforge.net/packages.html} and
+@url{http://octave.sourceforge.net/doc/} that has a function reference
+that is up to date. You can use this function reference to see the
+number of octave function that are available and their @sc{Matlab}
+compatibility.
+
+The major differences between Octave 3.2.N and  @sc{Matlab} R2008a are:
+
+@itemize @bullet
+@item Nested Functions
+
+Octave doesn't yet have nested functions. That is
+
+@example
+@group
+function y = foo (x)
+  y = bar(x)
+  function y = bar (x)
+    y = @dots{};
+  end
+end
+@end group
+@end example
+
+There was discussion in Octave of having these even prior to @sc{Matlab},
+and the decision was made not to have these in Octave at the time for
+compatibility.  The above written with sub-functions functions would be
+
+@example
+@group
+function y = foo (x)
+   y = bar(x)
+end
+function y = bar (x)
+   y = @dots{};
+end
+@end group
+@end example
+
+Now that @sc{Matlab} has recently introduced nested functions, Octave will
+probably have them soon as well.  Until then nested functions in Octave
+are treated as sub-functions with the same scoping rules as
+sub-functions.  
+
+The authors of Octave consider the nested function scoping rules of
+Matlab to be more problems than they are worth as they introduce
+diffiult to find bugs as inadvertantly modifying a variable in a
+nested function that is also used in the parent is particularly easy.
+
+@item Differences in core syntax
+There a few core @sc{Matlab} syntaxes that are not accepted by Octave,
+these being
+
+@itemize @bullet
+@item
+Some limitations on the use of function handles. The major difference is
+related to nested function scoping rules (as above) and their use with
+function handles.
+
+@item
+Some limitations of variable argument lists on the LHS of an expression,
+though the most common types are accepted.
+
+@item
+@sc{Matlab} classdef object oriented programming is not yet supportted,
+though work is underway and when development more on to Octave 3.3 this
+will be included in teh development tree.
+@end itemize
+
+@item Differences in core functions
+A large number of the @sc{Matlab} core functions (ie those that are in
+the core and not a toolbox) are implemented, and certainly all of the
+commonly used ones. There are a few functions that aren't implemented,
+for example @code{condest} or to do with specific missing Octave functionality
+(gui, dll, java, activex, dde, web, and serial functions). Some of the
+core functions have limitations that aren't in the @sc{Matlab}
+version.  For example the @code{sprandn} function can not force a
+particular condition number for the matrix like @sc{Matlab} can.
+
+@item Just-In-Time compiler
+@sc{Matlab} includes a "Just-In-Time" compiler. This compiler allows the
+acceleration of for-loops in @sc{Matlab} to almost native performance with
+certain restrictions. The JIT must know the return type of all functions
+called in the loops and so you can't include user functions in the loop
+of JIT optimized loops.  Octave doesn't have a JIT and so to some might
+seem slower than @sc{Matlab}.  For this reason you must vectorize your code as
+much as possible.  The MathWorks themselves have a good document
+discussing vectorization at
+@url{http://www.mathworks.com/support/tech-notes/1100/1109.html}.
+
+@item Compiler
+On a related point, there is no Octave compiler, and so you can't
+convert your Octave code into a binary for additional speed or
+distribution.  There is an example of how to do this at
+@url{http://www.stud.tu-ilmenau.de/~rueckn/}, but this is a very early
+example code and would need lots of work to complete it.
+
+@item Graphic Handles
+Up to Octave 2.9.9 there was no support for graphic handles in Octave
+itself.  In the 3.2.N versions of Octave the support for graphics
+handles is converging towards full compatibility. The @code{patch}
+function is currently limited to 2-D patches, due to an underlying
+limitation in gnuplot.
+
+@item GUI 
+There are no @sc{Matlab} compatible GUI functions.  There are a number of
+bindings from Octave to Tcl/Tk, Vtk and zenity included in the
+Octave Forge project (@url{http://octave.sourceforge.net}) for example
+that can be used for a GUI, but these are not @sc{Matlab}
+compatible. Work on a matlab compatible GUI is in an alpha stage in the
+JHandles package (@url{http://octave.sourceforge.net/jhandles/index.html}).
+This might be an issue if you intend to exchange Octave code with 
+@sc{Matlab} users.
+
+@item Simulink
+Octave itself includes no Simulink support. Typically the simulink
+models lag research and are less flexible, so shouldn't really be used
+in a research environment.  However, some @sc{Matlab} users that try to
+use Octave complain about this lack.  There is a similar package to
+simulink for the Octave and R projects available at
+@url{http://www.scicraft.org/}
+
+@item Mex-Files
+Octave includes an API to the matlab MEX interface. However, as MEX is
+an API to the internals of @sc{Matlab} and the internals of Octave
+differ from @sc{Matlab}, there is necessarily a manipulation of the data
+to convert from a MEX interface to the Octave equivalent. This is
+notable for all complex matrices, where @sc{Matlab} stores complex
+arrays as real and imaginary parts, whereas Octave respects the C99/C++
+standards of co-locating the real/imag parts in memory.  Also due to the
+way @sc{Matlab} allows access to the arrays passed through a pointer,
+the MEX interface might require copies of arrays (even non complex
+ones).
+
+@item Block comments
+Block comments denoted by "%@{" and "%@}" markers are supported by
+Octave with some limitations. The major limitation is that block
+comments are not supported within [] or @{@}.
+
+@item Mat-File format
+There are some differences in the mat v5 file format accepted by
+Octave. @sc{Matlab} recently introduced the "-V7.3" save option which is
+an HDF5 format which is particularly useful for 64-bit platforms where
+the standard matlab format can not correctly save variables.. Octave
+accepts HDF5 files, but is not yet compatible with the "-v7.3" versions
+produced by @sc{Matlab}. 
+
+Although Octave can load inline abd function handles saved by
+@sc{Matlab}, it can not yet save them.
+
+Finally, Some multi-byte unicode characters aren't yet treated in
+mat-files.
+
+@item Profiler
+Octave doesn't have a profiler. Though there is a patch for a flat
+profiler, that might become a real profiler sometime in the future. see
+the thread
+
+@url{http://www.cae.wisc.edu/pipermail/octave-maintainers/2007-January/001685.html}
+
+for more details
+
+@item Toolboxes
+Octave is a community project and so the toolboxes that exist are
+donated by those interested in them through the Octave Forge website
+(@url{http://octave.sourceforge.net}). These might be lacking in certain
+functionality relative to the @sc{Matlab} toolboxes, and might not
+exactly duplicate the matlab functionality or interface.
+
+@item Short-circuit & and | operators
+The @code{&} and @code{|} operators in @sc{Matlab} short-circuit when
+included in an if statemant and not otherwise.  In Octave only the
+@code{&&} and @code{||} short circuit.  Note that this means that
+
+@example
+@group
+  if (a | b)
+    @dots{}
+  end
+@end group
+@end example
+
+and
+  
+@example
+@group
+  t = a | b;
+  if t
+    @dots{}
+  end
+@end group
+@end example
+
+@noindent
+are different in @sc{Matlab}. This is really a @sc{Matlab} bug, but
+there is too much code out there that relies on this behavior to change
+it. Prefer the || and && operators in if statements if possible.
+
+Note that the difference is also significant when either argument is a
+function with side effects or if the first argument is a scalar and the
+second argument is an empty matrix.  For example, note the difference
+between
+
+@example
+@group
+  t = 1 | [];          ## results in [], so...
+  if (t) 1, end        ## in if ([]), this is false.
+@end group
+@end example
+
+and
+
+@example
+  if (1 | []) 1, end   ## short circuits so condition is true.
+@end example
+
+Another case that is documented in the @sc{Matlab} manuals is that
+
+@example
+@group
+  t = [1, 1] | [1, 2, 3];          ## error
+  if ([1, 1] | [1, 2, 3]) 1, end   ## OK
+@end group
+@end example
+
+Also @sc{Matlab} requires the operands of && and || to be scalar values but
+Octave does not (it just applies the rule that for an operand to be
+considered true, every element of the object must be nonzero or
+logically true).
+
+Finally, note the inconsistence of thinking of the condition of an if
+statement as being equivalent to @code{all(X(:))} when @var{X} is a
+matrix.  This is true for all cases EXCEPT empty matrices:
+
+@example
+@group
+  if ([0, 1]) == if (all ([0, 1]))   ==>  i.e., condition is false.
+  if ([1, 1]) == if (all ([1, 1]))   ==>  i.e., condition is true.
+@end group
+@end example
+
+However,
+
+@example
+  if ([]) != if (all ([]))
+@end example
+
+because @code{samp ([]) == 1} (because, despite the name, it is really
+returning true if none of the elements of the matrix are zero, and since
+there are no elements, well, none of them are zero).  But, somewhere
+along the line, someone decided that if @code{([])} should be false.
+Mathworks probably thought it just looks wrong to have @code{[]} be true
+in this context even if you can use logical gymnastics to convince
+yourself that "all" the elements of a matrix that doesn't actually have
+any elements are nonzero. Octave however duplicates this behavior for if
+statements containing empty matrices.
+
+@item Solvers for singular, under- and over-determined matrices
+
+Matlab's solvers as used by the operators mldivide (\) and mrdivide (/),
+use a different approach than Octave's in the case of singular, under-, 
+or over-determined matrices. In the case of a singular matrix, Matlab
+returns the result given by the LU decomposition, even though the underlying
+solver has flagged the result as erroneous. Octave has made the choice
+of falling back to a minimum norm solution of matrices that have been
+flagged as singular which arguably is a better result for these cases.
+
+In the case of under- or over-determined matrices, Octave continues to
+use a minimum norm solution, whereas Matlab uses an approach that is
+equivalent to
+
+@example
+@group
+function x = mldivide (A, b)
+  [Q, R, E] = qr(A);
+  x = [A \ b, E(:, 1:m) * (R(:, 1:m) \ (Q' * b))]
+end
+@end group
+@end example
+
+@noindent
+While this approach is certainly faster and uses less memory than
+Octave's minimum norm approach, this approach seems to be inferior in
+other ways.
+
+A numerical question arises: how big can the null space component become,
+relative to the minimum-norm solution? Can it be nicely bounded, or can it be
+arbitrarily big? Consider this example:
+
+@example
+@group
+m = 10; 
+n = 10000; 
+A = ones(m, n) + 1e-6 * randn(m,n); 
+b = ones(m, 1) + 1e-6 * randn(m,1); 
+norm(A \ b)
+@end group
+@end example
+
+@noindent
+while Octave's minimum-norm values are around 3e-2, Matlab's results
+are 50-times larger. For another issue, try this code:
+
+@example
+@group
+m = 5; 
+n = 100; 
+j = floor(m * rand(1, n)) + 1; 
+b = ones(m, 1);
+A = zeros(m, n);
+A(sub2ind(size(A),j,1:n)) = 1;
+x = A \ b; 
+[dummy,p] = sort(rand(1,n)); 
+y = A(:,p)\b; 
+norm(x(p)-y)
+@end group
+@end example
+
+@noindent
+It shows that unlike in Octave, mldivide in Matlab is not invariant
+with respect to column permutations. If there are multiple columns of
+the same norm, permuting columns of the matrix gets you different
+result than permuting the solution vector. This will surprise many
+users.
+
+Since the mldivide (\) and mrdivide (/) operators are often part of a more 
+complex expression, where there is no room to react to warnings or flags, it 
+should prefer intelligence (robustness) to speed, and so the Octave developers
+are firmly of the opinion that Octave's approach for singular, under- and
+over-determined matrices is a better choice that Matlab's
+
+@item Octave extensions
+The extensions in Octave over @sc{Matlab} syntax are
+very useful, but might cause issues when sharing with @sc{Matlab} users.
+A list of the major extensions that should be avoided to be compatible
+with @sc{Matlab} are
+
+@itemize @bullet
+@item
+Comments in octave can be marked with @samp{#}. This allows POSIX
+systems to have the first line as @samp{#! octave -q} and mark the script
+itself executable. @sc{Matlab} doesn't have this feature due to the
+absence of comments starting with @samp{#}".
+
+@item
+Code blocks like if, for, while, etc can be terminated with block
+specific terminations like "endif". @sc{Matlab} doesn't have this and
+all blocks must be terminated with "end"
+
+@item
+Octave has a lisp like unwind_protect block that allows blocks of
+code that terminate in an error to ensure that the variables that
+are touched are restored. You can do something similar with
+@code{try}/@code{catch} combined with @samp{rethrow (lasterror ())} in
+@sc{Matlab}, however rethrow and lasterror are only available in Octave 2.9.10 and later.
+
+Note that using @code{try}/@code{catch} combined with @samp{rethrow
+(lasterror ())} can not guarantee that global variables will be
+correctly reset, as it won't catch user interrupts with Ctrl-C. For
+example
+
+@example
+@group
+  global a
+  a = 1;
+  try
+    _a = a;
+    a = 2
+    while true
+    end
+  catch
+    fprintf ('caught interrupt\n');
+    a = _a;
+    rethrow (lasterror());
+  end
+@end group
+@end example
+
+@noindent
+compared to
+
+@example
+@group
+  global a
+  a = 1;
+  unwind_protect
+    _a = a;
+    a = 2
+    while true
+    end
+  unwind_protect_cleanup
+    fprintf ('caught interrupt\n');
+    a = _a;
+  end
+@end group
+@end example
+
+Typing Ctrl-C in the first case returns the user directly to the
+prompt, and the variable "a" is not reset to the saved value. In the
+second case the variable "a" is reset correctly.  Therefore @sc{Matlab}
+gives no save way of temporarily changing global variables.
+
+@item
+Indexing can be applied to all objects in Octave and not just
+variable. Therefore @code{sin(x)(1:10);} for example is perfectly valid
+in Octave but not @sc{Matlab}. To do the same in @sc{Matlab} you must do
+@code{y = sin(x); y = y([1:10]);}
+
+@item
+Octave has the operators "++", "--", "-=", "+=", "*=", etc.  As
+@sc{Matlab} doesn't, if you are sharing code these should be avoided.
+
+@item
+Character strings in Octave can be denoted with double or single
+quotes. There is a subtle difference between the two in that escaped
+characters like @code{\n} (newline), @code{\t} (tab), etc are
+interpreted in double quoted strings but not single quoted strings. This
+difference is important on Windows platforms where the "\" character is
+used in path names, and so single quoted strings should be used in
+paths. @sc{Matlab} doesn't have double quoted strings and so they should
+be avoided if the code will be transfered to a @sc{Matlab} user.
+@end itemize
+
+@end itemize
+
+@node Index
+@appendix Concept Index
+
+@printindex cp
+
+@page
+@contents
+@bye