# HG changeset patch # User John W. Eaton # Date 1349212859 14400 # Node ID c5749d4eab58224e682291ed5e5f84a6a5c5e9d4 # Parent bf0857c789f4e4e05a9ba6e75fc545e797f27359 remove FAQ from sources * configure.ac (AC_CONFIG_FILES): Remove doc/faq/Makefile from the list. * doc/Makefile.am (SUBDIRS): Remove faq from the list. * doc/faq/Makefile.am, OctaveFAQ.texi: Delete. diff --git a/configure.ac b/configure.ac --- a/configure.ac +++ b/configure.ac @@ -2456,7 +2456,6 @@ AC_CONFIG_FILES([ Makefile doc/Makefile - doc/faq/Makefile doc/icons/Makefile doc/interpreter/Makefile doc/liboctave/Makefile diff --git a/doc/Makefile.am b/doc/Makefile.am --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -29,5 +29,5 @@ texinfo.tex \ texmf.cnf -SUBDIRS = faq icons interpreter liboctave refcard +SUBDIRS = icons interpreter liboctave refcard diff --git a/doc/faq/Makefile.am b/doc/faq/Makefile.am deleted file mode 100644 --- a/doc/faq/Makefile.am +++ /dev/null @@ -1,38 +0,0 @@ -# Makefile for Octave's doc/faq directory -# -# Copyright (C) 1996-2012 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 -# . - -include $(top_srcdir)/build-aux/common.mk - -TEXINFO_TEX = ../texinfo.tex - -info_TEXINFOS = OctaveFAQ.texi - -all-local: dvi html pdf ps - -## The texi2dvi script (used to create both PDF and DVI output formats) -## uses some fixed temporary file names. In order to avoid a race condition -## the DVI and PDF builds are forced to run serially through a Makefile rule. -OctaveFAQ.pdf: OctaveFAQ.dvi - -EXTRA_DIST = OctaveFAQ.dvi OctaveFAQ.html OctaveFAQ.pdf OctaveFAQ.ps - -clean-local: - rm -rf t2d_cache - diff --git a/doc/faq/OctaveFAQ.texi b/doc/faq/OctaveFAQ.texi deleted file mode 100644 --- a/doc/faq/OctaveFAQ.texi +++ /dev/null @@ -1,1314 +0,0 @@ -% Copyright (C) 1997-2012 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 -% . - -\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 @today{} -@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 -@url{http://bugs.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.4.N:: -* Octave Features:: -* Learning more about Octave:: -* Getting Octave:: -* Installation:: -* Common problems:: -* Using Octave:: -* @sc{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 650+ page Texinfo manual. Access to -the complete text of the manual is available via the @code{doc} command -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{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 -``stable'' 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 -@c Does Vista work? I get the feeling that even Windows users are trying -@c to forget Vista like a bad nightmare. Tatsuro only confirmed XP and -@c 7. I am tentatively assuming that Vista also works. -CPUs, at least), for Mac OS X and Windows' 98, 2000, XP, Vista, and 7. - -Two and three dimensional plotting is fully supported using gnuplot and -an experimental OpenGL backend. - -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, version 3, as -published by the Free Software Foundation, or at your option any later -version. - -@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 @sc{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., @sc{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 or liboctave) 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 @sc{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 benefited 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.4.N -@chapter What's new in version series 3.4.N and 3.5.N of Octave - -The 3.4.N series has enough new features to justify a minor version -number change. The full details are in the @file{NEWS} file, but in -brief 3.4.N series brings: - -@c This list is distilled from the NEWS file. Does it have enough -@c things? Does it have too many? -@itemize @bullet - -@item ARPACK now distributed with Octave - -@item Indexing optimisations - -@item FTP object using @file{libcurl} - -@item Better consistency with ismatrix, issquare, and issymetric - -@item Function handles aware of overloaded functions - -@item More efficient matrix division by making a single LAPACK call - -@item Other optimisations in matrix operations - -@item @code{bsxfun} optimised for basic arithmetic functions - -@item @sc{Matlab}-style ignoring of output arguments using @samp{~} - -@item Many optimisations of the @code{accumarray} function - -@item Sparse matrix indexing has been rewritten for speed - -@item Configuration pseudo-variables like @code{page_screen_output} -accept a ``local'' option argument to limit their scope to function -scope - -@item The @code{pkg} command now accepts a @code{-forge} option to pull -packages directly from Octave-forge - -@item Several @code{dlmread} improvements - -@item Octave now uses gnulib for better cross-platform compatibility - -@end itemize - -Here are some features that have been around since 3.2.N - -@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 @sc{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 - -@item OpenGL graphics toolkit - -An experimental OpenGL graphics toolkit to replace 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 - -Here are some older features that have been around since 2.1.N: - -@itemize @bullet - -@item NDarrays - -@item cells - -@end itemize - -The 3.5.N series is the current development release and will become a -3.6.N release in the future. This series brings the following new -features: - -@itemize -@item Perl-compatible regular expressions are now part of Octave -@end itemize - - -@node Octave Features -@chapter What features are unique to Octave? - -@menu -* Functions defined on the command-line:: -* Comments with #:: -* Strings delimited 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 @sc{Matlab} R2010b and Octave 3.4.0. - -@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 @sc{Matlab}. 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 delimited by double quotes " -@section Strings delimited 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 @sc{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 @sc{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 @samp{!} (aka ``Bang!'') is a negation operator, just -like the tilde @samp{~}: - -@example -@group -octave:1> if ! strcmp (program_name, "octave"), -> "It's an error" -> else -> "It works!" -> end -ans = It works! -@end group -@end example - -@noindent -Note however that @sc{Matlab} uses the @samp{!} operator for shell -escapes, for which Octave requires using the @code{system} command. - -@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 modeled 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. - -@sc{Matlab} can be made to do something similar with their -@code{OnCleanUp} function that was introduced in 2008a. Octave also has -@code{onCleanup} since version 3.4.0. - -@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 650+ 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{doc} 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 report -it on @url{http://bugs.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{http://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 and -configuration details of your operating system so that the Octave -maintainers can duplicate your bug. - -@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 distributed under the terms of the GPL, you can get -Octave from a friend who has a copy, or from the Octave website. - -@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, Ubuntu, -RedHat, Suse and Fedora GNU/Linuxen, Mac OS X, Windows' 98, 2000 and XP, -Vista, and 7. - -@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{maintainers@@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.4 require approximately 1.3 GB of disk storage to unpack and -compile from source (considerably less if you don't compile with -debugging symbols). Once installed, Octave requires approximately 355 MB -of disk space (again, considerably less if you don't compile with -debugging symbols, approximately 50 MB). - -@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 4.3 or later, although GCC 4.4 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 @url{http://bugs.octave.org} bug tracker, 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. It has been fixed in gnuplot 4.4. - -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 - -@c This will work once we upload the Octave packages without a version -@c in their name to Debian. -@code{aptitude install octave-headers} - -@item -Fedora - -@code{yum install octave-devel} - -@end itemize -@end itemize - -@node Using Octave -@chapter Using Octave - -@menu -* How do I set the number of displayed decimals?:: -* How does Octave solve linear systems?:: -@end menu - -@cindex Tips and tricks -@cindex Using Octave - -@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 How does Octave solve linear systems? -@section How does Octave solve linear systems? - -@cindex backslash operator - -In addition to consulting Octave's source for the precise details, the -Octave manual contains a complete high-level description of the -algorithm that Octave uses to decide how to solve a particular linear -system, e.g. how the backslash operator @code{A\x} will be interpreted. -Sections ``Techniques Used for Linear Algebra'' and ``Linear Algebra on -Sparse Matrices'' from the manual describe this procedure. - -@node @sc{Matlab} compatibility -@chapter Porting programs from @sc{Matlab} to Octave - -@cindex @sc{Matlab} compatibility -@cindex Compatibility with @sc{Matlab} - -People often ask - -@quotation -I wrote some code for @sc{Matlab}, and I want to get it running under -Octave. Is there anything I should watch out for? -@end quotation - -@noindent -or alternatively - -@quotation -I wrote some code in Octave, and want to share it with @sc{Matlab} -users. Is there anything I should watch out for? -@end quotation - -@noindent -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 @url{http://bugs.octave.org}. - -Furthermore, Octave adds a few syntactical extensions to @sc{Matlab} -that might cause some issues when exchanging files between @sc{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.4.N and @sc{Matlab} R2010b are: - -@itemize @bullet -@item Nested Functions - -Octave has limited support for 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 - -is equivalent to - -@example -@group -function y = foo (x) - y = bar (x) -end -function y = bar (x) - y = @dots{}; -end -@end group -@end example - -The main difference with @sc{Matlab} is a matter of scope. While nested -functions have access to the parent function's scope in @sc{Matlab}, no -such thing is available in Octave, due to how Octave essentially -``un-nests'' nested functions. - -The authors of Octave consider the nested function scoping rules of -@sc{Matlab} to be more problems than they are worth as they introduce -difficult to find bugs as inadvertently 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 supported, -though work is underway and when development more on to Octave 3.5 this -will be included in the 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, -usually 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 -@c It would be nice if we had our own guide for this instead of relying -@c on Matlab documentation. -@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 have been several aborted attempts at creating an -Octave compiler. Should the JIT compiler above ever be implemented, an -Octave compiler should be more feasible. -@c Should we mention here any of the efforts to create a compiler? There -@c used to be a dead link here to http://www.stud.tu-ilmenau.de/~rueckn/ - -@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 and beyond 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, but the experimental OpenGL backend is -starting to see an implementation of 3-D patches. - -@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 -@c Is it too early to mention here the nascent fltk UI buttons? -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 -@sc{Matlab} compatible GUI is in an alpha stage in the JHandles package -@c Is Jhandles still usable? I thought Michael Goffioul had more or less -@c already disowned it. -(@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 -@c is this project in any state of usability? -@url{http://www.scicraft.org/} - -@item Mex-Files -Octave includes an API to the @sc{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 @sc{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 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 - -@c Did this idea go anywhere? Should it be mentioned? -@url{http://octave.1599824.n4.nabble.com/Octave-profiler-td1641945.html#a1641947} - -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 @sc{Matlab} functionality or interface. - -@item Short-circuit & and | operators -The @code{&} and @code{|} operators in @sc{Matlab} short-circuit when -included in an if statement 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 behaviour to change -it. Prefer the || and && operators in if statements if possible. If you -need to use code written for @sc{Matlab} that depends on this buggy -behaviour, you can enable it since Octave 3.4.0 with the following -command: - -@example -@group - do_braindead_shortcircuit_evaluation (1) -@end group -@end example - -Note that the difference with @sc{Matlab} 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. This is an example -of vacuous truth. 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 - -@sc{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, -@sc{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 @sc{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: -OctaveFAQ.texi -@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, @sc{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 @sc{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 -@sc{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 @code{if}, @code{for}, @code{while}, etc can be -terminated with block specific terminations like @code{endif}. -@sc{Matlab} doesn't have this and all blocks must be terminated with -@code{end}. - -@item -Octave has a lisp like @code{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. @sc{Matlab} 2008a also introduced @code{OnCleanUp} -that is similar to @code{unwind_protect}, except that the object created -by this function has to be explicitly cleared in order for the cleanup -code to run. - -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 safe way of temporarily changing global variables. - -@item -Indexing can be applied to all objects in Octave and not just a -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 transferred to a @sc{Matlab} user. -@end itemize - -@end itemize - -@node Index -@appendix Concept Index - -@printindex cp - -@page -@contents -@bye