This is Info file octave, produced by Makeinfo-1.64 from the input file
octave.tex.

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

   Copyright (C) 1996 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: Using Octave Mode,  Next: Running Octave From Within Emacs,  Prev: Setting Up Octave Mode,  Up: Emacs

Using Octave 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', typing a `;' automatically
     reindents the current line, inserts a newline and indents 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.

`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').

`C-c ;'
     Puts the first character of `octave-comment-start' (usually `#')
     at the beginning of every line in the region
     (`octave-comment-region').  With just `C-u' prefix argument,
     uncomment each line in the region.

`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 `octave-LG' (for example),
     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 'return-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-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-comment-column'
     Column to indent right-margin comments to.  Default is 32.  (Such
     comments are created using M-; (`indent-for-comment').)

`octave-comment-start'
     Delimiter inserted to start new comment.  Default value is `# '.

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

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

`octave-fill-column'
     Column beyond which automatic line-wrapping should happen.
     Default is 72.

`octave-inhibit-startup-message'
     If `t', no startup message is displayed when Octave mode is called.
     Default is `nil'.

   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).

   Customization of Octave mode can be performed by modification of the
variable `octave-mode-hook'.  It 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.


File: octave,  Node: Running Octave From Within Emacs,  Next: Using the Emacs Info Reader for Octave,  Prev: Using Octave Mode,  Up: Emacs

Running Octave From Within Emacs
================================

   The package `octave' provides commands for running an inferior
Octave process in a special Emacs buffer.  Use
     M-x run-octave

to directly start an inferior Octave process.  If Emacs does not know
about this command, add the line
     (autoload 'run-octave "octave" nil t)

to your `.emacs' file.

   This will start Octave in a special buffer the name of which is
specified by the variable `inferior-octave-buffer' and defaults to
`"*Octave Interaction*"'.  From within this buffer, you can interact
with the inferior Octave process `as usual', i.e., by entering Octave
commands at the prompt.

   You can also communicate with an inferior Octave process from within
files with Octave code (i.e., buffers in Octave mode), using the
following commands.

`C-c i l'
     Send the current line to the inferior Octave process
     (`octave-send-line').  With positive prefix argument N, send that
     many lines.  If `octave-send-line-auto-forward' is non-`nil', go
     to the next unsent code line.

`C-c i b'
     Send the current block to the inferior Octave process
     (`octave-send-block').

`C-c i f'
     Send the current function to the inferior Octave process
     (`octave-send-defun').

`C-c i r'
     Send the region to the inferior Octave process
     (`octave-send-region').

`C-c i s'
     Make sure that `inferior-octave-buffer' is displayed
     (`octave-show-process-buffer').

`C-c i h'
     Delete all windows that display `inferior-octave-buffer'
     (`octave-hide-process-buffer').

`C-c i k'
     Kill the inferior Octave process and its buffer
     (`octave-kill-process').

   The effect of the commands which send code to the Octave process can
be customized by the following variables.
`octave-send-echo-input'
     Non-`nil' means echo input sent to the inferior Octave process.
     Default is `t'.

`octave-send-show-buffer'
     Non-`nil' means display the buffer running the Octave process after
     sending a command (but without selecting it).  Default is `t'.

   If you send code and there is no inferior Octave process yet, it
will be started automatically.

   The startup of the inferior Octave process is highly customizable.
The variable `inferior-octave-startup-args' can be used for specifying
command lines arguments to be passed to Octave on startup as a list of
strings.  For example, to suppress the startup message and use
`traditional' mode, set this to `'("-q" "--traditional")'.  You can
also specify a startup file of Octave commands to be loaded on startup;
note that these commands will not produce any visible output in the
process buffer.  Which file to use is controlled by the variable
`inferior-octave-startup-file'.  If this is `nil', the file
`~/.emacs_octave' is used if it exists.

   And finally, `inferior-octave-mode-hook' is run after starting the
process and putting its buffer into Inferior Octave mode.  Hence, if you
like the up and down arrow keys to behave in the interaction buffer as
in the shell, and you want this buffer to use nice colors, add
     (add-hook 'inferior-octave-mode-hook
               (lambda ()
                 (turn-on-font-lock)
                 (define-key inferior-octave-mode-map [up]
                   'comint-previous-input)
                 (define-key inferior-octave-mode-map [down]
                   'comint-next-input)))

to your `.emacs' file.  You could also swap the roles of `C-a'
(`beginning-of-line') and `C-c C-a' (`comint-bol') using this hook.

     *Note:* If you set your Octave prompts to something different from
     the defaults, make sure that `inferior-octave-prompt' matches them.
     Otherwise, *nothing* will work, because Emacs will have no idea
     when Octave is waiting for input, or done sending output.


File: octave,  Node: Using the Emacs Info Reader for Octave,  Prev: Running Octave From Within Emacs,  Up: Emacs

Using the Emacs Info Reader for Octave
======================================

   You can also set up the Emacs Info reader for dealing with the
results of Octave's `help -i'.  For this, the package `gnuserv' needs
to be installed, which unfortunately still does not come with GNU Emacs
(it does with XEmacs).  It can be retrieved from any GNU Emacs Lisp Code
Directory archive, e.g.
`ftp://ftp.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive', in the
`packages' subdirectory.  There is also a newer version around (use
archie to look for `gnuserv-2.1alpha.tar.gz').

   If `gnuserv' is installed, add the lines
     (autoload 'octave-help "octave" nil t)
     (require 'gnuserv)
     (gnuserv-start)

to your `.emacs' file.

   You can use either `plain' Emacs Info or the function `octave-help'
as your Octave info reader (for `help -i').  In the former case, set
the Octave variable `INFO_PROGRAM' to `"info-emacs-info"'.  The latter
is perhaps more attractive because it allows to look up keys in the
indices of *several* info files related to Octave (provided that the
Emacs variable `octave-help-files' is set correctly).  In this case,
set `INFO_PROGRAM' to `"info-emacs-octave-help"'.

   If you use Octave from within Emacs, these settings are best done in
the `~/.emacs_octave' startup file (or the file pointed to by the Emacs
variable `inferior-octave-startup-file').


File: octave,  Node: Installation,  Next: Trouble,  Prev: Emacs,  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 Fortran compiler is available.

    `--enable-dld'
          Use DLD to make Octave capable of dynamically linking
          externally compiled functions.  This only works on systems
          that have a working port of DLD.

    `--enable-lite-kernel'
          Compile smaller kernel.  This currently requires DLD 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.

     For version 1.91, you must have the GNU C++ compiler (gcc) version
     2.6.3 or later to compile Octave.  You will also need version
     2.6.1 of the GNU C++ class library (libg++).  If you plan to
     modify the parser you will also need GNU bison and fles.  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 libg++, gnuplot, bison, flex, and Texinfo are
     all available from many anonymous ftp archives.  The primary site
     is prep.ai.mit.edu, but it is often very busy.  A list of sites
     that mirror the software on prep is available by anonymous ftp
     from prep.ai.mit.edu in the file /pub/gnu/GNUinfo/FTP, or by
     fingering fsf@prep.ai.mit.edu.

     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 SPARCstation II, it will take somewhere
     between 60 and 90 minutes to compile everything, depending on
     whether you are compiling the Fortran libraries with f2c or using
     the Fortran compiler directly.  You will need about 50 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 HOST_TYPE 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/HOST_TYPE'
          Executables to be run by Octave rather than the user.

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

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

* Menu:

* Installation Problems::
* Binary Distributions::


File: octave,  Node: Installation Problems,  Next: Binary Distributions,  Prev: Installation,  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.

   * If `configure' fails when trying to create its output files, you
     may have found a limitation in the version of `sed' on your
     system.  Using GNU `sed' avoids the problem.

   * You may need to edit some files in the gcc include subdirectory to
     add prototypes for functions there.  For example, Ultrix 4.2 needs
     proper declarations for the `signal()' 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 `signal()'.

     The gcc fixincludes/fixproto script should probably fix this when
     gcc installs its modified set of header files, but I don't think
     that's been done yet.

   * There is a bug with the makeinfo program that is distributed with
     texinfo-3.1 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.1 and apply the patch for makeinfo that
     is distributed with Octave.  See the file MAKEINFO.PATCH for more
     details.

   * If you don't have NPSOL but you still want to be able to solve
     NLPs, or if you don't have QPSOL but you still want to solve QPs,
     you'll need to find replacements or order them from Stanford.  If
     you know of a freely redistributable replacement, please let us
     know--we might be interested in distributing it with Octave.

     You can get more information about NPSOL and QPSOL from

          Stanford Business Sofrtware, Inc.
          2680 Bayshore Parkway, Suite 304
          Mountain View, CA 94043
          Tel: (415) 962-8719
          Fax: (415) 962-1869

     Octave may soon support FSQP, an NLP solver from Andre Tits
     (andre@src.umd.edu) of the University of Maryland.  FSQP is
     available free of charge to academic sites, but can not be
     redistributed to third parties.

   * 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
     libg++.

   * 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 kludge 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!

   * With g++ 2.6.3 (and possibly other 2.6.x versions) on some Intel
     x86 systems, compiling `Array-d.cc' fails with the messages like

          as: /tmp/cc005254.s:4057: Local symbol LBB103 never defined.
          as: /tmp/cc005254.s:4057: Local symbol LBE103 never defined.

     A possible workaround for this is to compile without `-g'.

   * 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 `sysdep.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.

   * Using the -O flag with old versions of the Sun Fortran compiler
     apparently prevents if from compiling some of the Fortran
     subroutines that Octave uses.  The workaround is to not use -O for
     those subroutines.


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

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

   This section contains instructions for creating and installing a
binary distribution.

* 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 ./doinstall.sh

     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.

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

    `info'
          Info files describing Octave.

    `lib/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.

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

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

     where VERSION stands for the current version number of the
     interpreter, and HOST_TYPE is the type of computer on which Octave
     is installed (for example, `i486-unknown-gnu').

     If these directories don't exist, the script `doinstall.sh' will
     create them for you.

     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
     doinstall.sh script.  For example:

          sh ./doinstall.sh /some/other/directory

     Octave will then be installed 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.

   * Build Octave in the same directory as the source.  This is required
     since the `binary-dist' targets in the Makefiles will not work if
     you compile outside the source tree.

   * Use `CFLAGS=-O CXXFLAGS=-O LDFLAGS=' as arguments for Make because
     most people who get the binary distributions are probably not
     going to be interested in debugging Octave.

   * Type `make binary-dist'.  This will build everything and then pack
     it up for distribution.


File: octave,  Node: Trouble,  Next: Command Line Editing,  Prev: Installation,  Up: Top

Known Causes of Trouble with Octave
***********************************

   This section describes known problems that affect users of Octave.
Most of these are not Octave bugs per se--if they were, we would fix
them.  But the result for a user may be like the result of a bug.

   Some of these problems are due to bugs in other software, some are
missing features that are too much work to add, and some are places
where people's opinions differ as to what is best.

* Menu:

* Actual Bugs::                 Bugs we will fix later.
* Reporting Bugs::
* Bug Criteria::
* Bug Lists::
* Bug Reporting::
* Sending Patches::
* Service::


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

Actual Bugs We Haven't Fixed Yet
================================

   * Output that comes directly from Fortran functions is not sent
     through the pager and may appear out of sequence with other output
     that is sent through the pager.  One way to avoid this is to force
     pending output to be flushed before calling a function that will
     produce output from within Fortran functions.  To do this, use the
     command

          fflush (stdout)

     Another possible workaround is to use the command

          page_screen_output = "false"

     to turn the pager off.

   * Control-C doesn't work properly in the pager on DEC Alpha systems
     running OSF/1 3.0.

     This appears to be a bug in the OSF/1 3.0 Bourne shell.  The
     problem doesn't appear on systems running OSF/1 1.3.

   * If you get messages like

          Input line too long

     when trying to plot many lines on one graph, you have probably
     generated a plot command that is too larger for `gnuplot''s
     fixed-length buffer for commands.  Splitting up the plot command
     doesn't help because replot is implemented in gnuplot by simply
     appending the new plotting commands to the old command line and
     then evaluating it again.

     You can demonstrate this `feature' by running gnuplot and doing
     something like

            plot sin (x), sin (x), sin (x), ... lots more ..., sin (x)

     and then

            replot sin (x), sin (x), sin (x), ... lots more ..., sin (x)

     after repeating the replot command a few times, gnuplot will give
     you an error.

     Also, it doesn't help to use backslashes to enter a plot command
     over several lines, because the limit is on the overall command
     line length, once the backslashed lines are all pasted together.

     Because of this, Octave tries to use as little of the command-line
     length as possible by using the shortest possible abbreviations for
     all the plot commands and options.  Unfortunately, the length of
     the temporary file names is probably what is taking up the most
     space on the command line.

     You can buy a little bit of command line space by setting the
     environment variable `TMPDIR' to be "." before starting Octave, or
     you can increase the maximum command line length in gnuplot by
     changing the following limits in the file plot.h in the gnuplot
     distribution and recompiling gnuplot.

          #define MAX_LINE_LEN 32768  /* originally 1024 */
          #define MAX_TOKENS 8192     /* originally 400 */

     Of course, this doesn't really fix the problem, but it does make it
     much less likely that you will run into trouble unless you are
     putting a very large number of lines on a given plot.

   * String handling could use some work.

   A list of ideas for future enhancements is distributed with Octave.
See the file `PROJECTS' in the top level directory in the source
distribution.


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
`bug-octave'.

   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
==================

   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 probalby 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
===========================

   If you need help installing, using or changing Octave, the mailing
list

     help-octave@bevo.che.wisc.edu

   exists for the discussion of Octave matters related to using,
installing, and porting Octave.  If you 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 the
mailing list, or other administrative trivia to the list itself.

