octave-lyh: doc/faq/OctaveFAQ.texi comparison

comparison doc/faq/OctaveFAQ.texi @ 12479:c741c1f2789e

Minor proofreading in FAQ

author	Jordi Gutiérrez Hermoso <jordigh@gmail.com>
date	Fri, 25 Feb 2011 15:11:26 -0600
parents	b4138a75eecc
children	30f2a3b1d236

comparison

equal deleted inserted replaced

-:b4138a75eecc
+:c741c1f2789e
 * OctaveFAQ: (OctaveFAQ).  Frequently asked questions about Octave
 @end direntry
 @titlepage
 @title Octave FAQ
 @subtitle Frequently asked questions about Octave
-@subtitle September 2008
+@subtitle @today{}
 @sp 1
 @author John W. Eaton and David Bateman
 @page
 @end titlepage
 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 ...?::
 * @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,
+@sc{Matlab}.@footnote{@sc{Matlab} is a registered trademark of The
-Inc.}
+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.
 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
+The Octave distribution includes a 590+ page Texinfo manual. Access to
-to the complete text of the manual is available via the help command
+the complete text of the manual is available via the @code{doc} 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
+the University of Texas. John W. Eaton was the original author of
-Octave, starting full-time development in February 1992.  He is still
+Octave, starting full-time development in February 1992. He is still the
-the primary maintainer.  The community
+primary maintainer. The community of users/developers has in addition
-of users/developers has in addition contributed some code and fuels the
+contributed some code and fuels the discussion on the mailing lists
-discussion on the mailing lists @email{help@@octave.org} (user forum),
+@email{help@@octave.org} (user forum), @email{maintainers@@octave.org}
-@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?
 @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
+@url{http://www.octave.org/download.html}. It is recommended to use the
-recommended to use the ``testing'' version of octave for general use,
+``testing'' version of octave for general use, and the ``development''
-and the ``development'' version if you want the latest features.
+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.
 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.
+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
+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
+under the terms of the GNU General Public License, version 3, as
-Free Software Foundation.
+published by the Free Software Foundation, or at your option any later
+version.
 @node Licensing Issues
 @chapter Licensing Issues
 @menu
 @item many many other minor features and compatibility changes
 @end itemize
-Here are some features that have been around since 2.1.N
+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
+3.2.N release in the future. This series brings the following new
+features:
 @itemize
 @item OpenGL graphics toolkit
-An experimental OpenGL graphics toolkit to replace the gnuplot.
+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
 @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 @sc{Matlab} R2008b and Octave 2.1.51.
 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 @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
 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
 @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 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
 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
+is not adequately explained, indexed, or cross-referenced, please report
-a bug report to @email{bug@@octave.org}.
+it on @url{http://bugs.octave.org}.
 @node Getting additional help
 @section Getting additional help
 @cindex Additional help
 @node Getting Octave
 @chapter Getting Octave
 @menu
 * Source code::
 * Pre-compiled binary packages::
 * Octave for other platforms::
 @end menu
 @node Source code
 @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}.
+@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.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 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.
 @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
+@quotation
-Octave.  Is there anything I should watch out for?''
+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
-``I wrote some code in Octave, and want to share it with @sc{Matlab}
+@quotation
-users.  Is there anything I should watch out for?''
+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 @email{bug@@octave.org}.
+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.
 @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
 @sc{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.
 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.
+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,
+@c this is no longer true, condest is now implemented in Octave
 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.
 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
 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 @sc{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
+@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
 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 abd function handles saved by
 @sc{Matlab}, it can not yet save them.
 Finally, Some multi-byte unicode characters aren't yet treated in
 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.
+@c TODO: Update this to mention how it's now enabled in Octave
 @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
 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, @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
 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

Mercurial > hg > octave-lyh

comparison doc/faq/OctaveFAQ.texi @ 12479:c741c1f2789e