This is Info file octave, produced by Makeinfo version 1.68 from the
input file octave.tex.

START-INFO-DIR-ENTRY
* Octave: (octave).	Interactive language for numerical computations.
END-INFO-DIR-ENTRY

   Copyright (C) 1996, 1997 John W. Eaton.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: octave,  Node: Reporting Bugs,  Next: Bug Criteria,  Prev: Actual Bugs,  Up: Trouble

Reporting Bugs
==============

   Your bug reports play an essential role in making Octave reliable.

   When you encounter a problem, the first thing to do is to see if it
is already known.  *Note Trouble::.  If it isn't known, then you should
report the problem.

   Reporting a bug may help you by bringing a solution to your problem,
or it may not.  In any case, the principal function of a bug report is
to help the entire community by making the next version of Octave work
better.  Bug reports are your contribution to the maintenance of Octave.

   In order for a bug report to serve its purpose, you must include the
information that makes it possible to fix the bug.

   If you have Octave working at all, the easiest way to prepare a
complete bug report is to use the Octave function `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.

* Menu:

* Bug Criteria::
* Where: Bug Lists.             Where to send your bug report.
* Reporting: Bug Reporting.     How to report a bug effectively.
* Patches: Sending Patches.     How to send a patch for Octave.


File: octave,  Node: Bug Criteria,  Next: Bug Lists,  Prev: Reporting Bugs,  Up: Trouble

Have You Found a Bug?
=====================

   If you are not sure whether you have found a bug, here are some
guidelines:

   * If Octave gets a fatal signal, for any input whatever, that is a
     bug.  Reliable interpreters never crash.

   * If Octave produces incorrect results, for any input whatever, that
     is a bug.

   * Some output may appear to be incorrect when it is in fact due to a
     program whose behavior is undefined, which happened by chance to
     give the desired results on another system.  For example, the
     range operator may produce different results because of
     differences in the way floating point arithmetic is handled on
     various systems.

   * If Octave produces an error message for valid input, that is a bug.

   * If Octave does not produce an error message for invalid input,
     that is a bug.  However, you should note that your idea of
     "invalid input" might be my idea of "an extension" or "support for
     traditional practice".

   * If you are an experienced user of programs like Octave, your
     suggestions for improvement are welcome in any case.


File: octave,  Node: Bug Lists,  Next: Bug Reporting,  Prev: Bug Criteria,  Up: Trouble

Where to Report Bugs
====================

   If you have Octave working at all, the easiest way to prepare a
complete bug report is to use the Octave function `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.

   If for some reason you cannot use Octave's `bug_report' function,
send bug reports for Octave to (bug-octave@bevo.che.wisc.edu).

   *Do not send bug reports to `help-octave'*.  Most users of Octave do
not want to receive bug reports.  Those that do have asked to be on the
mailing list.

   As a last resort, send bug reports on paper to:

     Octave Bugs c/o John W. Eaton
     University of Wisconsin-Madison
     Department of Chemical Engineering
     1415 Engineering Drive
     Madison, Wisconsin 53706  USA


File: octave,  Node: Bug Reporting,  Next: Sending Patches,  Prev: Bug Lists,  Up: Trouble

How to Report Bugs
==================

   Send bug reports for Octave to one of the addresses listed in *Note
Bug Lists::.

   The fundamental principle of reporting bugs usefully is this:
*report all the facts*.  If you are not sure whether to state a fact or
leave it out, state it!

   Often people omit facts because they think they know what causes the
problem and they conclude that some details don't matter.  Thus, you
might assume that the name of the variable you use in an example does
not matter.  Well, probably it doesn't, but one cannot be sure.
Perhaps the bug is a stray memory reference which happens to fetch from
the location where that name is stored in memory; perhaps, if the name
were different, the contents of that location would fool the
interpreter into doing the right thing despite the bug.  Play it safe
and give a specific, complete example.

   Keep in mind that the purpose of a bug report is to enable someone to
fix the bug if it is not known. Always write your bug reports on the
assumption that the bug is not known.

   Sometimes people give a few sketchy facts and ask, "Does this ring a
bell?"  This cannot help us fix a bug.  It is better to send a complete
bug report to begin with.

   Try to make your bug report self-contained.  If we have to ask you
for more information, it is best if you include all the previous
information in your response, as well as the information that was
missing.

   To enable someone to investigate the bug, you should include all
these things:

   * The version of Octave.  You can get this by noting the version
     number that is printed when Octave starts, or running it with the
     `-v' option.

   * A complete input file that will reproduce the bug.

     A single statement may not be enough of an example--the bug might
     depend on other details that are missing from the single statement
     where the error finally occurs.

   * The command arguments you gave Octave to execute that example and
     observe the bug.  To guarantee you won't omit something important,
     list all the options.

     If we were to try to guess the arguments, we would probably guess
     wrong and then we would not encounter the bug.

   * The type of machine you are using, and the operating system name
     and version number.

   * The command-line arguments you gave to the `configure' command when
     you installed the interpreter.

   * A complete list of any modifications you have made to the
     interpreter source.

     Be precise about these changes--show a context diff for them.

   * Details of any other deviations from the standard procedure for
     installing Octave.

   * A description of what behavior you observe that you believe is
     incorrect.  For example, "The interpreter gets a fatal signal,"
     or, "The output produced at line 208 is incorrect."

     Of course, if the bug is that the interpreter gets a fatal signal,
     then one can't miss it.  But if the bug is incorrect output, we
     might not notice unless it is glaringly wrong.

     Even if the problem you experience is a fatal signal, you should
     still say so explicitly.  Suppose something strange is going on,
     such as, your copy of the interpreter is out of synch, or you have
     encountered a bug in the C library on your system.  Your copy
     might crash and the copy here would not.  If you said to expect a
     crash, then when the interpreter here fails to crash, we would
     know that the bug was not happening.  If you don't say to expect a
     crash, then we would not know whether the bug was happening.  We
     would not be able to draw any conclusion from our observations.

     Often the observed symptom is incorrect output when your program
     is run.  Unfortunately, this is not enough information unless the
     program is short and simple.  It is very helpful if you can
     include an explanation of the expected output, and why the actual
     output is incorrect.

   * If you wish to suggest changes to the Octave source, send them as
     context diffs.  If you even discuss something in the Octave source,
     refer to it by context, not by line number, because the line
     numbers in the development sources probably won't match those in
     your sources.

   Here are some things that are not necessary:

   * A description of the envelope of the bug.

     Often people who encounter a bug spend a lot of time investigating
     which changes to the input file will make the bug go away and
     which changes will not affect it.  Such information is usually not
     necessary to enable us to fix bugs in Octave, but if you can find
     a simpler example to report *instead* of the original one, that is
     a convenience.  Errors in the output will be easier to spot,
     running under the debugger will take less time, etc. Most Octave
     bugs involve just one function, so the most straightforward way to
     simplify an example is to delete all the function definitions
     except the one in which the bug occurs.

     However, simplification is not vital; if you don't want to do
     this, report the bug anyway and send the entire test case you used.

   * A patch for the bug.  Patches can be helpful, but if you find a
     bug, you should report it, even if you cannot send a fix for the
     problem.


File: octave,  Node: Sending Patches,  Next: Service,  Prev: Bug Reporting,  Up: Trouble

Sending Patches for Octave
==========================

   If you would like to write bug fixes or improvements for Octave,
that is very helpful.  When you send your changes, please follow these
guidelines to avoid causing extra work for us in studying the patches.

   If you don't follow these guidelines, your information might still be
useful, but using it will take extra work.  Maintaining Octave is a lot
of work in the best of circumstances, and we can't keep up unless you do
your best to help.

   * Send an explanation with your changes of what problem they fix or
     what improvement they bring about.  For a bug fix, just include a
     copy of the bug report, and explain why the change fixes the bug.

   * Always include a proper bug report for the problem you think you
     have fixed.  We need to convince ourselves that the change is
     right before installing it.  Even if it is right, we might have
     trouble judging it if we don't have a way to reproduce the problem.

   * Include all the comments that are appropriate to help people
     reading the source in the future understand why this change was
     needed.

   * Don't mix together changes made for different reasons.  Send them
     *individually*.

     If you make two changes for separate reasons, then we might not
     want to install them both.  We might want to install just one.

   * Use `diff -c' to make your diffs.  Diffs without context are hard
     for us to install reliably.  More than that, they make it hard for
     us to study the diffs to decide whether we want to install them.
     Unidiff format is better than contextless diffs, but not as easy
     to read as `-c' format.

     If you have GNU diff, use `diff -cp', which shows the name of the
     function that each change occurs in.

   * Write the change log entries for your changes.

     Read the `ChangeLog' file to see what sorts of information to put
     in, and to learn the style that we use.  The purpose of the change
     log is to show people where to find what was changed.  So you need
     to be specific about what functions you changed; in large
     functions, it's often helpful to indicate where within the
     function the change was made.

     On the other hand, once you have shown people where to find the
     change, you need not explain its purpose. Thus, if you add a new
     function, all you need to say about it is that it is new.  If you
     feel that the purpose needs explaining, it probably does--but the
     explanation will be much more useful if you put it in comments in
     the code.

     If you would like your name to appear in the header line for who
     made the change, send us the header line.


File: octave,  Node: Service,  Prev: Sending Patches,  Up: Trouble

How To Get Help with Octave
===========================

   The mailing list (help-octave@bevo.che.wisc.edu) exists for the
discussion of matters related to using and installing Octave.  If would
like to join the discussion, please send a short note to
(help-octave*-request*@bevo.che.wisc.edu).

   *Please do not* send requests to be added or removed from the
mailing list, or other administrative trivia to the list itself.

   If you think you have found a bug in the installation procedure,
however, you should send a complete bug report for the problem to
(bug-octave@bevo.che.wisc.edu).  *Note Bug Reporting:: for information
that will help you to submit a useful report.


File: octave,  Node: Installation,  Next: Emacs,  Prev: Trouble,  Up: Top

Installing Octave
*****************

   Here is the procedure for installing Octave from scratch on a Unix
system.  For instructions on how to install the binary distributions of
Octave, see *Note Binary Distributions::.

   * Run the shell script `configure'.  This will determine the features
     your system has (or doesn't have) and create a file named
     `Makefile' from each of the files named `Makefile.in'.

     Here is a summary of the configure options that are most
     frequently used when building Octave:

    `--prefix=PREFIX'
          Install Octave in subdirectories below PREFIX.  The default
          value of PREFIX is `/usr/local'.

    `--srcdir=DIR'
          Look for Octave sources in the directory DIR.

    `--with-f2c'
          Use `f2c' even if a Fortran compiler is available.

    `--with-g77'
          Use `g77' to compile Fortran code.

    `--enable-shared'
          Create shared libraries.  If you are planning to use
          `--enable-lite-kernelel' or the dynamic loading features, you
          will probably want to use this option.  It will make your
          `.oct' files much smaller and on some systems it may be
          necessary to build shared libraries in order to use
          dynamically linked functions.

          You may also want to build a shared version of `libstdc++',
          if your system doesn't already have one.  Note that a patch
          is needed to build shared versions of version 2.7.2 of
          `libstdc++' on the HP-PA architecture.  You can find the
          patch at
          (ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix).

    `--enable-dl'
          Use `dlopen' and friends to make Octave capable of dynamically
          linking externally compiled functions.  This only works on
          systems that actually have these functions.  If you plan on
          using this feature, you should probably also use
          `--enable-shared' to reduce the size of your `.oct' files.

    `--enable-shl'
          Use `shl_load' and friends to make Octave capable of
          dynamically linking externally compiled functions.  This only
          works on systems that actually have these functions (only
          HP-UX systems).  If you plan on using this feature, you
          should probably also use `--enable-shared' to reduce the size
          of your `.oct' files.

    `--enable-lite-kernel'
          Compile smaller kernel.  This currently requires the dynamic
          linking functions `dlopen' or `shl_load' and friends so that
          Octave can load functions at run time that are not loaded at
          compile time.

    `--help'
          Print a summary of the options recognized by the configure
          script.

     See the file `INSTALL' for more information about the command line
     options used by configure.  That file also contains instructions
     for compiling in a directory other than where the source is
     located.

   * Run make.

     You will need a recent version of GNU Make.  Modifying Octave's
     makefiles to work with other make programs is probably not worth
     your time.  We recommend you get and compile GNU Make instead.

     For plotting, you will need to have gnuplot installed on your
     system.  Gnuplot is a command-driven interactive function plotting
     program.  Gnuplot is copyrighted, but freely distributable.  The
     `gnu' in gnuplot is a coincidence--it is not related to the GNU
     project or the FSF in any but the most peripheral sense.

     To compile Octave, you will need a recent version of GNU Make.  You
     will also need `g++' 2.7.2 or later.  Version 2.8.0 or `egcs'
     1.0.x should work.  Later versions may work, but C++ is still
     evolving, so don't be too surprised if you run into some trouble.

     It is no longer necessary to have `libg++', but you do need to have
     the GNU implementation of `libstdc++'.  If you are using `g++'
     2.7.2, `libstdc++' is distributed along with `libg++', but for
     later versions, `libstdc++' is distributed separately.  For
     `egcs', `libstdc++' is included with the compiler distribution.

     If you plan to modify the parser you will also need GNU `bison' and
     `flex'.  If you modify the documentation, you will need GNU
     Texinfo, along with the patch for the `makeinfo' program that is
     distributed with Octave.

     GNU Make, `gcc', and `libstdc++', `gnuplot', `bison', `flex', and
     Texinfo are all available from many anonymous ftp archives.  The
     primary site is (ftp.gnu.org), but it is often very busy.  A list
     of sites that mirror the software on (ftp.gnu.org) is available by
     anonymous ftp from (ftp://ftp.gnu.org/pub/gnu/GNUinfo/FTP).

     If you don't have a Fortran compiler, or if your Fortran compiler
     doesn't work like the traditional Unix f77, you will need to have
     the Fortran to C translator `f2c'.  You can get `f2c' from any
     number of anonymous ftp archives.  The most recent version of `f2c'
     is always available from (netlib.att.com).

     On an otherwise idle Pentium 133 running Linux, it will take
     somewhere between 1-1/2 to 3 hours to compile everything,
     depending on whether you are building shared libraries.  You will
     need about 100 megabytes of disk storage to work with
     (considerably less if you don't compile with debugging symbols).
     To do that, use the command

          make CFLAGS=-O CXXFLAGS=-O LDFLAGS=

     instead of just `make'.

   * If you encounter errors while compiling Octave, first check the
     list of known problems below to see if there is a workaround or
     solution for your problem.  If not, see *Note Trouble::, for
     information about how to report bugs.

   * Once you have successfully compiled Octave, run `make install'.

     This will install a copy of octave, its libraries, and its
     documentation in the destination directory.  As distributed,
     Octave is installed in the following directories.  In the table
     below, PREFIX defaults to `/usr/local', VERSION stands for the
     current version number of the interpreter, and ARCH is the type of
     computer on which Octave is installed (for example,
     `i586-unknown-gnu').

    `PREFIX/bin'
          Octave and other binaries that people will want to run
          directly.

    `PREFIX/lib'
          Libraries like libcruft.a and liboctave.a.

    `PREFIX/share'
          Architecture-independent data files.

    `PREFIX/include/octave'
          Include files distributed with Octave.

    `PREFIX/man/man1'
          Unix-style man pages describing Octave.

    `PREFIX/info'
          Info files describing Octave.

    `PREFIX/share/octave/VERSION/m'
          Function files distributed with Octave.  This includes the
          Octave version, so that multiple versions of Octave may be
          installed at the same time.

    `PREFIX/lib/octave/VERSION/exec/ARCH'
          Executables to be run by Octave rather than the user.

    `PREFIX/lib/octave/VERSION/oct/ARCH'
          Object files that will be dynamically loaded.

    `PREFIX/share/octave/VERSION/imagelib'
          Image files that are distributed with Octave.

* Menu:

* Notes::
* Installation Problems::
* Binary Distributions::


File: octave,  Node: Notes,  Next: Installation Problems,  Prev: Installation,  Up: Installation

Notes
=====

   * You must use the version of GNU Info distributed with Octave,
     because it includes some changes to allow Octave to search the
     indices of the info files.  If you would like, you should be able
     to replace other copies of the Info browser that you have with the
     one distributed with Octave.  Patches relative to a recent release
     of the GNU Info browser are included in the file `INFO.PATCH' in
     the Octave source distribution.  This modification has been
     submitted to the GNU Info maintainer, and should appear in some
     future release.  Once that happens, the GNU Info browser will no
     longer be distributed with Octave.


File: octave,  Node: Installation Problems,  Next: Binary Distributions,  Prev: Notes,  Up: Installation

Installation Problems
=====================

   This section contains a list of problems (and some apparent problems
that don't really mean anything is wrong) that may show up during
installation of Octave.

   * On some SCO systems, `info' fails to compile if `HAVE_TERMIOS_H'
     is defined int `config.h'.  Simply removing the definition from
     `info/config.h' should allow it to compile.

   * If `configure' finds `dlopen', `dlsym', `dlclose', and `dlerror',
     but not the header file `dlfcn.h', you need to find the source for
     the header file and install it in the directory `usr/include'.
     This is reportedly a problem with Slackware 3.1.  For Linux/GNU
     systems, the source for `dlfcn.h' is in the `ldso' package.

   * Building `.oct' files doesn't work.

     You should probably have a shared version of `libstdc++'.  A patch
     is needed to build shared versions of version 2.7.2 of `libstdc++'
     on the HP-PA architecture.  You can find the patch at
     (ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix).

   * On some alpha systems there may be a problem with the `libdxml'
     library, resulting in floating point errors and/or segmentation
     faults in the linear algebra routines called by Octave.  If you
     encounter such problems, then you should modify the configure
     script so that `SPECIAL_MATH_LIB' is not set to `-ldxml'.

   * On FreeBSD systems Octave may hang while initializing some internal
     constants.  The fix appears to be to use

          options      GPL_MATH_EMULATE

     rather than

          options      MATH_EMULATE

     in the kernel configuration files (typically found in the directory
     `/sys/i386/conf'.  After making this change, you'll need to rebuild
     the kernel, install it, and reboot.

   * If you encounter errors like

          passing `void (*)()' as argument 2 of
            `octave_set_signal_handler(int, void (*)(int))'

     or

          warning: ANSI C++ prohibits conversion from `(int)' to `(...)'

     while compiling `sighandlers.cc', you may need to edit some files
     in the `gcc' include subdirectory to add proper prototypes for
     functions there.  For example, Ultrix 4.2 needs proper
     declarations for the `signal' function and the `SIG_IGN' macro in
     the file `signal.h'.

     On some systems the `SIG_IGN' macro is defined to be something like
     this:

          #define  SIG_IGN  (void (*)())1

     when it should really be something like:

          #define  SIG_IGN  (void (*)(int))1

     to match the prototype declaration for the `signal' function.  This
     change should also be made for the `SIG_DFL' and `SIG_ERR'
     symbols. It may be necessary to change the definitions in
     `sys/signal.h' as well.

     The `gcc' `fixincludes' and `fixproto' scripts should probably fix
     these problems when `gcc' installs its modified set of header
     files, but I don't think that's been done yet.

     *You should not change the files in `/usr/include'*.  You can find
     the `gcc' include directory tree by running the command

          gcc -print-libgcc-file-name

     The directory of `gcc' include files normally begins in the same
     directory that contains the file `libgcc.a'.

   * There is a bug with the `makeinfo' program that is distributed with
     Texinfo (through version 3.9) that causes the indices in Octave's
     on-line manual to be generated incorrectly.  If you need to
     recreate the on-line documentation, you should get the `makeinfo'
     program that is distributed with texinfo-3.9 and apply the patch
     for `makeinfo' that is distributed with Octave.  See the file
     `MAKEINFO.PATCH' for more details.

   * Some of the Fortran subroutines may fail to compile with older
     versions of the Sun Fortran compiler.  If you get errors like

          zgemm.f:
          	zgemm:
          warning: unexpected parent of complex expression subtree
          zgemm.f, line 245: warning: unexpected parent of complex
            expression subtree
          warning: unexpected parent of complex expression subtree
          zgemm.f, line 304: warning: unexpected parent of complex
            expression subtree
          warning: unexpected parent of complex expression subtree
          zgemm.f, line 327: warning: unexpected parent of complex
            expression subtree
          pcc_binval: missing IR_CONV in complex op
          make[2]: *** [zgemm.o] Error 1

     when compiling the Fortran subroutines in the `libcruft'
     subdirectory, you should either upgrade your compiler or try
     compiling with optimization turned off.

   * On NeXT systems, if you get errors like this:

          /usr/tmp/cc007458.s:unknown:Undefined local symbol LBB7656
          /usr/tmp/cc007458.s:unknown:Undefined local symbol LBE7656

     when compiling `Array.cc' and `Matrix.cc', try recompiling these
     files without `-g'.

   * Some people have reported that calls to shell_cmd and the pager do
     not work on SunOS systems.  This is apparently due to having
     `G_HAVE_SYS_WAIT' defined to be 0 instead of 1 when compiling
     `libstdc++'.

   * On NeXT systems, linking to `libsys_s.a' may fail to resolve the
     following functions

          _tcgetattr
          _tcsetattr
          _tcflow

     which are part of `libposix.a'.  Unfortunately, linking Octave with
     `-posix' results in the following undefined symbols.

          .destructors_used
          .constructors_used
          _objc_msgSend
          _NXGetDefaultValue
          _NXRegisterDefaults
          .objc_class_name_NXStringTable
          .objc_class_name_NXBundle

     One kluge around this problem is to extract `termios.o' from
     `libposix.a', put it in Octave's `src' directory, and add it to
     the list of files to link together in the makefile.  Suggestions
     for better ways to solve this problem are welcome!

   * If Octave crashes immediately with a floating point exception, it
     is likely that it is failing to initialize the IEEE floating point
     values for infinity and NaN.

     If your system actually does support IEEE arithmetic, you should
     be able to fix this problem by modifying the function
     `octave_ieee_init' in the file `lo-ieee.cc' to correctly
     initialize Octave's internal infinity and NaN variables.

     If your system does not support IEEE arithmetic but Octave's
     configure script incorrectly determined that it does, you can work
     around the problem by editing the file `config.h' to not define
     `HAVE_ISINF', `HAVE_FINITE', and `HAVE_ISNAN'.

     In any case, please report this as a bug since it might be
     possible to modify Octave's configuration script to automatically
     determine the proper thing to do.

   * After installing the binary distribution of Octave in an alternate
     directory, the Emacs command `run-octave' doesn't work.  Emacs
     hangs in `accept-process-output' in `inferior-octave-startup'.

     This seems to be a problem with executing a shell script using the
     comint package.  You can avoid the problem by changing the way
     Octave is installed to eliminate the need for the shell script.
     You can either compile and install Octave using the source
     distribution, reinstall the binary distribution in the default
     directory, or copy the commands in the octave shell script wrapper
     to your shell startup files (and the shell startup files for
     anyone else who is using Octave) and then rename the file
     `octave.bin' to be `octave'.


File: octave,  Node: Binary Distributions,  Prev: Installation Problems,  Up: Installation

Binary Distributions
====================

   Although Octave is not very difficult to build from its sources, it
is a relatively large program that does require a significant amount of
time and disk space to compile and install.  Because of this, many
people want to be able to obtain binary distributions so they can start
using Octave immediately, without having to bother with the details of
compiling it first.  This is understandable, so I try to maintain a
current collection of binary distributions at
(ftp://ftp.che.wisc.edu/pub/octave/BINARIES).

   Please understand, however, that there is only a limited amount of
time available to devote to making binaries, so binaries may not be
immediately available for some platforms.  (Please contact
(bug-octave@bevo.che.wisc.edu) if you are interested in helping make a
binary distribution available for your system.)

   Also, binary distributions are limited to static binaries that do not
support dynamic linking.  For earlier versions of Octave, I tried
distributing dynamically linked binaries but that proved to be too much
trouble to support.  If you want to have a copy of Octave that includes
all the features described in this manual, you will have to build it
from the sources yourself, or find someone else who is willing to do it
for you.

* Menu:

* Installing Octave from a Binary Distribution::
* Creating a Binary Distribution::


File: octave,  Node: Installing Octave from a Binary Distribution,  Next: Creating a Binary Distribution,  Prev: Binary Distributions,  Up: Binary Distributions

Installing Octave from a Binary Distribution
--------------------------------------------

   To install Octave from a binary distribution, execute the command

     sh ./install-octave

in the top level directory of the distribution.

   Binary distributions are normally compiled assuming that Octave will
be installed in the following subdirectories of `/usr/local'.

`bin'
     Octave and other binaries that people will want to run directly.

`lib'
     Shared libraries that Octave needs in order to run.  These files
     are not included if you are installing a statically linked version
     of Octave.

`man/man1'
     Unix-style man pages describing Octave.

`info'
     Info files describing Octave.

`share/octave/VERSION/m'
     Function files distributed with Octave.  This includes the Octave
     version, so that multiple versions of Octave may be installed at
     the same time.

`libexec/octave/VERSION/exec/ARCH'
     Executables to be run by Octave rather than the user.

`libexec/octave/VERSION/oct/ARCH'
     Object files that will be dynamically loaded.

`share/octave/VERSION/imagelib'
     Image files that are distributed with Octave.

where VERSION stands for the current version number of the interpreter,
and ARCH is the type of computer on which Octave is installed (for
example, `i486-OS/2').

   If these directories don't exist, the script `install-octave' will
create them for you.  The installation script also creates the following
subdirectories of `/usr/local' that are intended for locally installed
functions:

`share/octave/site/m'
     Locally installed M-files.

`libexec/octave/site/exec/ARCH'
     Locally installed binaries intended to be run by Octave rather
     than by the user.

`libexec/octave/site/octave/ARCH'
     Local object files that will be dynamically linked.

   If it is not possible for you to install Octave in `/usr/local', or
if you would prefer to install it in a different directory, you can
specify the name of the top level directory as an argument to the
`install-octave' script.  For example:

     sh ./install-octave /some/other/directory

will install Octave in subdirectories of the directory
`/some/other/directory'.


File: octave,  Node: Creating a Binary Distribution,  Prev: Installing Octave from a Binary Distribution,  Up: Binary Distributions

Creating a Binary Distribution
------------------------------

   Here is how to build a binary distribution for others to use.  If you
want to make a binary distribution for your system available along with
the Octave sources and binaries on (ftp.che.wisc.edu), please follow
this procedure.  For directions explaining how to make the binary
available on the ftp site, please contact
(bug-octave@bevo.che.wisc.edu).

   * Unpack the source distribution:

          gunzip -c octave-2.0.17.tar.gz | tar xf -

   * Change your current directory to the top-level directory of the
     source distribution:

          cd octave-2.0.17

   * Make the binary distribution:

          make binary-dist

     This will create a compressed tar file ready for distribution.  It
     will contain statically linked binaries and have a name like
     `octave-2.0.17-i486-OS/2.tar.gz'


File: octave,  Node: Emacs,  Next: Grammar,  Prev: Installation,  Up: Top

Emacs Octave Support
********************

   The development of Octave code can greatly be facilitated using Emacs
with Octave mode, a major mode for editing Octave files which can e.g.
automatically indent the code, do some of the typing (with Abbrev mode)
and show keywords, comments, strings, etc. in different faces (with
Font-lock mode on devices that support it).

   It is also possible to run Octave from within Emacs, either by
directly entering commands at the prompt in a buffer in Inferior Octave
mode, or by interacting with Octave from within a file with Octave
code.  This is useful in particular for debugging Octave code.

   Finally, you can convince Octave to use the Emacs info reader for
`help -i'.

   All functionality is provided by the Emacs Lisp package EOS (for
"Emacs Octave Support").  This chapter describes how to set up and use
this package.

   Please contact <Kurt.Hornik@ci.tuwien.ac.at> if you have any
questions or suggestions on using EOS.

* Menu:

* Installing EOS::
* Using Octave Mode::
* Running Octave From Within Emacs::
* Using the Emacs Info Reader for Octave::


File: octave,  Node: Installing EOS,  Next: Using Octave Mode,  Prev: Emacs,  Up: Emacs

Installing EOS
==============

   The Emacs package EOS consists of the three files `octave-mod.el',
`octave-inf.el', and `octave-hlp.el'.  These files, or better yet their
byte-compiled versions, should be somewhere in your Emacs load-path.

   If you have GNU Emacs with a version number at least as high as
19.35, you are all set up, because EOS is respectively will be part of
GNU Emacs as of version 19.35.

   Otherwise, copy the three files from the `emacs' subdirectory of the
Octave distribution to a place where Emacs can find them (this depends
on how your Emacs was installed).  Byte-compile them for speed if you
want.


File: octave,  Node: Using Octave Mode,  Next: Running Octave From Within Emacs,  Prev: Installing EOS,  Up: Emacs

Using Octave Mode
=================

   If you are lucky, your sysadmins have already arranged everything so
that Emacs automatically goes into Octave mode whenever you visit an
Octave code file as characterized by its extension `.m'.  If not,
proceed as follows.

  1. To begin using Octave mode for all `.m' files you visit, add the
     following lines to a file loaded by Emacs at startup time,
     typically your `~/.emacs' file:

          (autoload 'octave-mode "octave-mod" nil t)
          (setq auto-mode-alist
                (cons '("\\.m$" . octave-mode) auto-mode-alist))

  2. Finally, to turn on the abbrevs, auto-fill and font-lock features
     automatically, also add the following lines to one of the Emacs
     startup files:
          (add-hook 'octave-mode-hook
                    (lambda ()
                      (abbrev-mode 1)
                      (auto-fill-mode 1)
                      (if (eq window-system 'x)
                          (font-lock-mode 1))))
     See the Emacs manual for more information about how to customize
     Font-lock mode.

   In Octave mode, the following special Emacs commands can be used in
addition to the standard Emacs commands.

`C-h m'
     Describe the features of Octave mode.

`LFD'
     Reindent the current Octave line, insert a newline and indent the
     new line (`octave-reindent-then-newline-and-indent').  An abbrev
     before point is expanded if `abbrev-mode' is non-`nil'.

`TAB'
     Indents current Octave line based on its contents and on previous
     lines (`indent-according-to-mode').

`;'
     Insert an "electric" semicolon (`octave-electric-semi').  If
     `octave-auto-indent' is non-`nil', reindent the current line.  If
     `octave-auto-newline' is non-`nil', automagically insert a newline
     and indent the new line.

``'
     Start entering an abbreviation (`octave-abbrev-start').  If Abbrev
     mode is turned on, typing ``C-h' or ``?' lists all abbrevs.  Any
     other key combination is executed normally.  Note that all Octave
     abbrevs start with a grave accent.

`M-LFD'
     Break line at point and insert continuation marker and alignment
     (`octave-split-line').

`M-TAB'
     Perform completion on Octave symbol preceding point, comparing that
     symbol against Octave's reserved words and builtin variables
     (`octave-complete-symbol').

`M-C-a'
     Move backward to the beginning of a function
     (`octave-beginning-of-defun').  With prefix argument N, do it that
     many times if N is positive;  otherwise, move forward to the N-th
     following beginning of a function.

`M-C-e'
     Move forward to the end of a function (`octave-end-of-defun').
     With prefix argument N, do it that many times if N is positive;
     otherwise, move back to the N-th preceding end of a function.

`M-C-h'
     Puts point at beginning and mark at the end of the current Octave
     function, i.e., the one containing point or following point
     (`octave-mark-defun').

`M-C-q'
     Properly indents the Octave function which contains point
     (`octave-indent-defun').

`M-;'
     If there is no comment already on this line, create a code-level
     comment (started by two comment characters) if the line is empty,
     or an in-line comment (started by one comment character) otherwise
     (`octave-indent-for-comment').  Point is left after the start of
     the comment which is properly aligned.

`C-c ;'
     Puts the comment character `#' (more precisely, the string value of
     `octave-comment-start') at the beginning of every line in the
     region (`octave-comment-region').  With just `C-u' prefix
     argument, uncomment each line in the region.  A numeric prefix
     argument N means use N comment characters.

`C-c :'
     Uncomments every line in the region (`octave-uncomment-region').

`C-c C-p'
     Move one line of Octave code backward, skipping empty and comment
     lines (`octave-previous-code-line').  With numeric prefix argument
     N, move that many code lines backward (forward if N is negative).

`C-c C-n'
     Move one line of Octave code forward, skipping empty and comment
     lines (`octave-next-code-line').  With numeric prefix argument N,
     move that many code lines forward (backward if N is negative).

`C-c C-a'
     Move to the `real' beginning of the current line
     (`octave-beginning-of-line').  If point is in an empty or comment
     line, simply go to its beginning;  otherwise, move backwards to the
     beginning of the first code line which is not inside a continuation
     statement,  i.e., which does not follow a code line ending in `...'
     or `\', or is inside an open parenthesis list.

`C-c C-e'
     Move to the `real' end of the current line (`octave-end-of-line').
     If point is in a code line, move forward to the end of the first
     Octave code line which does not end in `...' or `\' or is inside an
     open parenthesis list.  Otherwise, simply go to the end of the
     current line.

`C-c M-C-n'
     Move forward across one balanced begin-end block of Octave code
     (`octave-forward-block').  With numeric prefix argument N, move
     forward across N such blocks (backward if N is negative).

`C-c M-C-p'
     Move back across one balanced begin-end block of Octave code
     (`octave-backward-block').  With numeric prefix argument N, move
     backward across N such blocks (forward if N is negative).

`C-c M-C-d'
     Move forward down one begin-end block level of Octave code
     (`octave-down-block').  With numeric prefix argument, do it that
     many times;  a negative argument means move backward, but still go
     down one level.

`C-c M-C-u'
     Move backward out of one begin-end block level of Octave code
     (`octave-backward-up-block').  With numeric prefix argument, do it
     that many times; a negative argument means move forward, but still
     to a less deep spot.

`C-c M-C-h'
     Put point at the beginning of this block, mark at the end
     (`octave-mark-block').  The block marked is the one that contains
     point or follows point.

`C-c ]'
     Close the current block on a separate line (`octave-close-block').
     An error is signaled if no block to close is found.

`C-c f'
     Insert a function skeleton, prompting for the function's name,
     arguments and return values which have to be entered without parens
     (`octave-insert-defun').

`C-c C-h'
     Search the function, operator and variable indices of all info
     files with documentation for Octave for entries (`octave-help').
     If used interactively, the entry is prompted for with completion.
     If multiple matches are found, one can cycle through them using
     the standard `,' (`Info-index-next') command of the Info reader.

     The variable `octave-help-files' is a list of files to search
     through and defaults to `'("octave")'.  If there is also an Octave
     Local Guide with corresponding info file, say, `octave-LG', you can
     have `octave-help' search both files by
          (setq octave-help-files '("octave" "octave-LG"))

     in one of your Emacs startup files.

   A common problem is that the <RET> key does *not* indent the line to
where the new text should go after inserting the newline.  This is
because the standard Emacs convention is that <RET> (aka `C-m') just
adds a newline, whereas <LFD> (aka `C-j') adds a newline and indents
it.  This is particularly inconvenient for users with keyboards which
do not have a special <LFD> key at all;  in such cases, it is typically
more convenient to use <RET> as the <LFD> key (rather than typing
`C-j').

   You can make <RET> do this by adding
     (define-key octave-mode-map "\C-m"
       'octave-reindent-then-newline-and-indent)

to one of your Emacs startup files.  Another, more generally applicable
solution is
     (defun RET-behaves-as-LFD ()
       (let ((x (key-binding "\C-j")))
         (local-set-key "\C-m" x)))
     (add-hook 'octave-mode-hook 'RET-behaves-as-LFD)

(this works for all modes by adding to the startup hooks, without having
to know the particular binding of <RET> in that mode!).  Similar
considerations apply for using <M-RET> as <M-LFD>.  As Barry A. Warsaw
<bwarsaw@cnri.reston.va.us> says in the documentation for his
`cc-mode', "This is a very common question. `:-)' If you want this to
be the default behavior, don't lobby me, lobby RMS!"

   The following variables can be used to customize Octave mode.

`octave-auto-indent'
     Non-`nil' means auto-indent the current line after a semicolon or
     space.  Default is `nil'.

`octave-auto-newline'
     Non-`nil' means auto-insert a newline and indent after semicolons
     are typed.  The default value is `nil'.

`octave-blink-matching-block'
     Non-`nil' means show matching begin of block when inserting a
     space, newline or `;' after an else or end keyword.  Default is
     `t'.  This is an extremely useful feature for automatically
     verifying that the keywords match--if they don't, an error message
     is displayed.

`octave-block-offset'
     Extra indentation applied to statements in block structures.
     Default is 2.

`octave-continuation-offset'
     Extra indentation applied to Octave continuation lines.  Default
     is 4.

`octave-continuation-string'
     String used for Octave continuation lines.  Normally `\'.

`octave-mode-startup-message'
     If `t' (default), a startup message is displayed when Octave mode
     is called.

   If Font Lock mode is enabled, Octave mode will display
   * strings in `font-lock-string-face'

   * comments in `font-lock-comment-face'

   * the Octave reserved words (such as all block keywords) and the text
     functions (such as `cd' or `who') which are also reserved using
     `font-lock-keyword-face'

   * the builtin operators (`&&', `<>', ...) using
     `font-lock-reference-face'

   * the builtin variables (such as `prefer_column_vectors', `NaN' or
     `LOADPATH') in `font-lock-variable-name-face'

   * and the function names in function declarations in
     `font-lock-function-name-face'.

   There is also rudimentary support for Imenu (currently, function
names can be indexed).

   You can generate TAGS files for Emacs from Octave `.m' files using
the shell script `otags' that is installed alongside your copy of
Octave.

   Customization of Octave mode can be performed by modification of the
variable `octave-mode-hook'.  If the value of this variable is
non-`nil', turning on Octave mode calls its value.

   If you discover a problem with Octave mode, you can conveniently
send a bug report using `C-c C-b' (`octave-submit-bug-report').  This
automatically sets up a mail buffer with version information already
added.  You just need to add a description of the problem, including a
reproducible test case and send the message.

