home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / octa21eb.zip / octave / doc / octave.i12 < prev    next >
Encoding:
GNU Info File  |  1999-05-13  |  39.1 KB  |  1,023 lines
  1. This is Info file octave, produced by Makeinfo-1.64 from the input file
  2. octave.tex.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * Octave: (octave).    Interactive language for numerical computations.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    Copyright (C) 1996, 1997 John W. Eaton.
  9.  
  10.    Permission is granted to make and distribute verbatim copies of this
  11. manual provided the copyright notice and this permission notice are
  12. preserved on all copies.
  13.  
  14.    Permission is granted to copy and distribute modified versions of
  15. this manual under the conditions for verbatim copying, provided that
  16. the entire resulting derived work is distributed under the terms of a
  17. permission notice identical to this one.
  18.  
  19.    Permission is granted to copy and distribute translations of this
  20. manual into another language, under the above conditions for modified
  21. versions.
  22.  
  23. 
  24. File: octave,  Node: Installation,  Next: Emacs,  Prev: Trouble,  Up: Top
  25.  
  26. Installing Octave
  27. *****************
  28.  
  29.    Here is the procedure for installing Octave from scratch on a Unix
  30. system.  For instructions on how to install the binary distributions of
  31. Octave, see *Note Binary Distributions::.
  32.  
  33.    * Run the shell script `configure'.  This will determine the features
  34.      your system has (or doesn't have) and create a file named
  35.      `Makefile' from each of the files named `Makefile.in'.
  36.  
  37.      Here is a summary of the configure options that are most
  38.      frequently used when building Octave:
  39.  
  40.     `--prefix=PREFIX'
  41.           Install Octave in subdirectories below PREFIX.  The default
  42.           value of PREFIX is `/usr/local'.
  43.  
  44.     `--srcdir=DIR'
  45.           Look for Octave sources in the directory DIR.
  46.  
  47.     `--with-f2c'
  48.           Use `f2c' even if a Fortran compiler is available.
  49.  
  50.     `--with-g77'
  51.           Use `g77' to compile Fortran code.
  52.  
  53.     `--enable-shared'
  54.           Create shared libraries.  If you are planning to use
  55.           `--enable-lite-kernelel' or the dynamic loading features, you
  56.           will probably want to use this option.  It will make your
  57.           `.oct' files much smaller and on some systems it may be
  58.           necessary to build shared libraries in order to use
  59.           dynamically linked functions.
  60.  
  61.           You may also want to build a shared version of `libstdc++',
  62.           if your system doesn't already have one.  Note that a patch
  63.           is needed to build shared versions of version 2.7.2 of
  64.           `libstdc++' on the HP-PA architecture.  You can find the
  65.           patch at
  66.           (ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix).
  67.  
  68.     `--enable-dl'
  69.           Use `dlopen' and friends to make Octave capable of dynamically
  70.           linking externally compiled functions.  This only works on
  71.           systems that actually have these functions.  If you plan on
  72.           using this feature, you should probably also use
  73.           `--enable-shared' to reduce the size of your `.oct' files.
  74.  
  75.     `--enable-shl'
  76.           Use `shl_load' and friends to make Octave capable of
  77.           dynamically linking externally compiled functions.  This only
  78.           works on systems that actually have these functions (only
  79.           HP-UX systems).  If you plan on using this feature, you
  80.           should probably also use `--enable-shared' to reduce the size
  81.           of your `.oct' files.
  82.  
  83.     `--enable-lite-kernel'
  84.           Compile smaller kernel.  This currently requires the dynamic
  85.           linking functions `dlopen' or `shl_load' and friends so that
  86.           Octave can load functions at run time that are not loaded at
  87.           compile time.
  88.  
  89.     `--help'
  90.           Print a summary of the options recognized by the configure
  91.           script.
  92.  
  93.      See the file `INSTALL' for more information about the command line
  94.      options used by configure.  That file also contains instructions
  95.      for compiling in a directory other than where the source is
  96.      located.
  97.  
  98.    * Run make.
  99.  
  100.      You will need a recent version of GNU Make.  Modifying Octave's
  101.      makefiles to work with other make programs is probably not worth
  102.      your time.  We recommend you get and compile GNU Make instead.
  103.  
  104.      For plotting, you will need to have gnuplot installed on your
  105.      system.  Gnuplot is a command-driven interactive function plotting
  106.      program.  Gnuplot is copyrighted, but freely distributable.  The
  107.      `gnu' in gnuplot is a coincidence--it is not related to the GNU
  108.      project or the FSF in any but the most peripheral sense.
  109.  
  110.      To compile Octave, you will need a recent version of GNU Make.  You
  111.      will also need `g++' 2.7.2 or later.  Version 2.8.0 or `egcs'
  112.      1.0.x should work.  Later versions may work, but C++ is still
  113.      evolving, so don't be too surprised if you run into some trouble.
  114.  
  115.      It is no longer necessary to have `libg++', but you do need to have
  116.      the GNU implementation of `libstdc++'.  If you are using `g++'
  117.      2.7.2, `libstdc++' is distributed along with `libg++', but for
  118.      later versions, `libstdc++' is distributed separately.  For
  119.      `egcs', `libstdc++' is included with the compiler distribution.
  120.  
  121.      If you plan to modify the parser you will also need GNU `bison' and
  122.      `flex'.  If you modify the documentation, you will need GNU
  123.      Texinfo, along with the patch for the `makeinfo' program that is
  124.      distributed with Octave.
  125.  
  126.      GNU Make, `gcc', and `libstdc++', `gnuplot', `bison', `flex', and
  127.      Texinfo are all available from many anonymous ftp archives.  The
  128.      primary site is (ftp.gnu.org), but it is often very busy.  A list
  129.      of sites that mirror the software on (ftp.gnu.org) is available by
  130.      anonymous ftp from (ftp://ftp.gnu.org/pub/gnu/GNUinfo/FTP).
  131.  
  132.      If you don't have a Fortran compiler, or if your Fortran compiler
  133.      doesn't work like the traditional Unix f77, you will need to have
  134.      the Fortran to C translator `f2c'.  You can get `f2c' from any
  135.      number of anonymous ftp archives.  The most recent version of `f2c'
  136.      is always available from (netlib.att.com).
  137.  
  138.      On an otherwise idle Pentium 133 running Linux, it will take
  139.      somewhere between 1-1/2 to 3 hours to compile everything,
  140.      depending on whether you are building shared libraries.  You will
  141.      need about 100 megabytes of disk storage to work with
  142.      (considerably less if you don't compile with debugging symbols).
  143.      To do that, use the command
  144.  
  145.           make CFLAGS=-O CXXFLAGS=-O LDFLAGS=
  146.  
  147.      instead of just `make'.
  148.  
  149.    * If you encounter errors while compiling Octave, first check the
  150.      list of known problems below to see if there is a workaround or
  151.      solution for your problem.  If not, see *Note Trouble::, for
  152.      information about how to report bugs.
  153.  
  154.    * Once you have successfully compiled Octave, run `make install'.
  155.  
  156.      This will install a copy of octave, its libraries, and its
  157.      documentation in the destination directory.  As distributed,
  158.      Octave is installed in the following directories.  In the table
  159.      below, PREFIX defaults to `/usr/local', VERSION stands for the
  160.      current version number of the interpreter, and ARCH is the type of
  161.      computer on which Octave is installed (for example,
  162.      `i586-unknown-gnu').
  163.  
  164.     `PREFIX/bin'
  165.           Octave and other binaries that people will want to run
  166.           directly.
  167.  
  168.     `PREFIX/lib'
  169.           Libraries like libcruft.a and liboctave.a.
  170.  
  171.     `PREFIX/share'
  172.           Architecture-independent data files.
  173.  
  174.     `PREFIX/include/octave'
  175.           Include files distributed with Octave.
  176.  
  177.     `PREFIX/man/man1'
  178.           Unix-style man pages describing Octave.
  179.  
  180.     `PREFIX/info'
  181.           Info files describing Octave.
  182.  
  183.     `PREFIX/share/octave/VERSION/m'
  184.           Function files distributed with Octave.  This includes the
  185.           Octave version, so that multiple versions of Octave may be
  186.           installed at the same time.
  187.  
  188.     `PREFIX/lib/octave/VERSION/exec/ARCH'
  189.           Executables to be run by Octave rather than the user.
  190.  
  191.     `PREFIX/lib/octave/VERSION/oct/ARCH'
  192.           Object files that will be dynamically loaded.
  193.  
  194.     `PREFIX/share/octave/VERSION/imagelib'
  195.           Image files that are distributed with Octave.
  196.  
  197. * Menu:
  198.  
  199. * Installation Problems::
  200. * Binary Distributions::
  201.  
  202. 
  203. File: octave,  Node: Installation Problems,  Next: Binary Distributions,  Prev: Installation,  Up: Installation
  204.  
  205. Installation Problems
  206. =====================
  207.  
  208.    This section contains a list of problems (and some apparent problems
  209. that don't really mean anything is wrong) that may show up during
  210. installation of Octave.
  211.  
  212.    * On some SCO systems, `info' fails to compile if `HAVE_TERMIOS_H'
  213.      is defined int `config.h'.  Simply removing the definition from
  214.      `info/config.h' should allow it to compile.
  215.  
  216.    * If `configure' finds `dlopen', `dlsym', `dlclose', and `dlerror',
  217.      but not the header file `dlfcn.h', you need to find the source for
  218.      the header file and install it in the directory `usr/include'.
  219.      This is reportedly a problem with Slackware 3.1.  For Linux/GNU
  220.      systems, the source for `dlfcn.h' is in the `ldso' package.
  221.  
  222.    * Building `.oct' files doesn't work.
  223.  
  224.      You should probably have a shared version of `libstdc++'.  A patch
  225.      is needed to build shared versions of version 2.7.2 of `libstdc++'
  226.      on the HP-PA architecture.  You can find the patch at
  227.      (ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix).
  228.  
  229.    * On FreeBSD systems Octave may hang while initializing some internal
  230.      constants.  The fix appears to be to use
  231.  
  232.           options      GPL_MATH_EMULATE
  233.  
  234.      rather than
  235.  
  236.           options      MATH_EMULATE
  237.  
  238.      in the kernel configuration files (typically found in the directory
  239.      `/sys/i386/conf'.  After making this change, you'll need to rebuild
  240.      the kernel, install it, and reboot.
  241.  
  242.    * If you encounter errors like
  243.  
  244.           passing `void (*)()' as argument 2 of
  245.             `octave_set_signal_handler(int, void (*)(int))'
  246.  
  247.      or
  248.  
  249.           warning: ANSI C++ prohibits conversion from `(int)' to `(...)'
  250.  
  251.      while compiling `sighandlers.cc', you may need to edit some files
  252.      in the `gcc' include subdirectory to add proper prototypes for
  253.      functions there.  For example, Ultrix 4.2 needs proper
  254.      declarations for the `signal' function and the `SIG_IGN' macro in
  255.      the file `signal.h'.
  256.  
  257.      On some systems the `SIG_IGN' macro is defined to be something like
  258.      this:
  259.  
  260.           #define  SIG_IGN  (void (*)())1
  261.  
  262.      when it should really be something like:
  263.  
  264.           #define  SIG_IGN  (void (*)(int))1
  265.  
  266.      to match the prototype declaration for the `signal' function.  This
  267.      change should also be made for the `SIG_DFL' and `SIG_ERR'
  268.      symbols. It may be necessary to change the definitions in
  269.      `sys/signal.h' as well.
  270.  
  271.      The `gcc' `fixincludes' and `fixproto' scripts should probably fix
  272.      these problems when `gcc' installs its modified set of header
  273.      files, but I don't think that's been done yet.
  274.  
  275.      *You should not change the files in `/usr/include'*.  You can find
  276.      the `gcc' include directory tree by running the command
  277.  
  278.           gcc -print-libgcc-file-name
  279.  
  280.      The directory of `gcc' include files normally begins in the same
  281.      directory that contains the file `libgcc.a'.
  282.  
  283.    * Some of the Fortran subroutines may fail to compile with older
  284.      versions of the Sun Fortran compiler.  If you get errors like
  285.  
  286.           zgemm.f:
  287.               zgemm:
  288.           warning: unexpected parent of complex expression subtree
  289.           zgemm.f, line 245: warning: unexpected parent of complex
  290.             expression subtree
  291.           warning: unexpected parent of complex expression subtree
  292.           zgemm.f, line 304: warning: unexpected parent of complex
  293.             expression subtree
  294.           warning: unexpected parent of complex expression subtree
  295.           zgemm.f, line 327: warning: unexpected parent of complex
  296.             expression subtree
  297.           pcc_binval: missing IR_CONV in complex op
  298.           make[2]: *** [zgemm.o] Error 1
  299.  
  300.      when compiling the Fortran subroutines in the `libcruft'
  301.      subdirectory, you should either upgrade your compiler or try
  302.      compiling with optimization turned off.
  303.  
  304.    * On NeXT systems, if you get errors like this:
  305.  
  306.           /usr/tmp/cc007458.s:unknown:Undefined local symbol LBB7656
  307.           /usr/tmp/cc007458.s:unknown:Undefined local symbol LBE7656
  308.  
  309.      when compiling `Array.cc' and `Matrix.cc', try recompiling these
  310.      files without `-g'.
  311.  
  312.    * Some people have reported that calls to shell_cmd and the pager do
  313.      not work on SunOS systems.  This is apparently due to having
  314.      `G_HAVE_SYS_WAIT' defined to be 0 instead of 1 when compiling
  315.      `libg++'.
  316.  
  317.    * On NeXT systems, linking to `libsys_s.a' may fail to resolve the
  318.      following functions
  319.  
  320.           _tcgetattr
  321.           _tcsetattr
  322.           _tcflow
  323.  
  324.      which are part of `libposix.a'.  Unfortunately, linking Octave with
  325.      `-posix' results in the following undefined symbols.
  326.  
  327.           .destructors_used
  328.           .constructors_used
  329.           _objc_msgSend
  330.           _NXGetDefaultValue
  331.           _NXRegisterDefaults
  332.           .objc_class_name_NXStringTable
  333.           .objc_class_name_NXBundle
  334.  
  335.      One kluge around this problem is to extract `termios.o' from
  336.      `libposix.a', put it in Octave's `src' directory, and add it to
  337.      the list of files to link together in the makefile.  Suggestions
  338.      for better ways to solve this problem are welcome!
  339.  
  340.    * If Octave crashes immediately with a floating point exception, it
  341.      is likely that it is failing to initialize the IEEE floating point
  342.      values for infinity and NaN.
  343.  
  344.      If your system actually does support IEEE arithmetic, you should
  345.      be able to fix this problem by modifying the function
  346.      `octave_ieee_init' in the file `lo-ieee.cc' to correctly
  347.      initialize Octave's internal infinity and NaN variables.
  348.  
  349.      If your system does not support IEEE arithmetic but Octave's
  350.      configure script incorrectly determined that it does, you can work
  351.      around the problem by editing the file `config.h' to not define
  352.      `HAVE_ISINF', `HAVE_FINITE', and `HAVE_ISNAN'.
  353.  
  354.      In any case, please report this as a bug since it might be
  355.      possible to modify Octave's configuration script to automatically
  356.      determine the proper thing to do.
  357.  
  358.    * After installing the binary distribution of Octave in an alternate
  359.      directory, the Emacs command `run-octave' doesn't work.  Emacs
  360.      hangs in `accept-process-output' in `inferior-octave-startup'.
  361.  
  362.      This seems to be a problem with executing a shell script using the
  363.      comint package.  You can avoid the problem by changing the way
  364.      Octave is installed to eliminate the need for the shell script.
  365.      You can either compile and install Octave using the source
  366.      distribution, reinstall the binary distribution in the default
  367.      directory, or copy the commands in the octave shell script wrapper
  368.      to your shell startup files (and the shell startup files for
  369.      anyone else who is using Octave) and then rename the file
  370.      `octave.bin' to be `octave'.
  371.  
  372. 
  373. File: octave,  Node: Binary Distributions,  Prev: Installation Problems,  Up: Installation
  374.  
  375. Binary Distributions
  376. ====================
  377.  
  378.    Although Octave is not very difficult to build from its sources, it
  379. is a relatively large program that does require a significant amount of
  380. time and disk space to compile and install.  Because of this, many
  381. people want to be able to obtain binary distributions so they can start
  382. using Octave immediately, without having to bother with the details of
  383. compiling it first.  This is understandable, so I try to maintain a
  384. current collection of binary distributions at
  385. (ftp://ftp.che.wisc.edu/pub/octave/BINARIES).
  386.  
  387.    Please understand, however, that there is only a limited amount of
  388. time available to devote to making binaries, so binaries may not be
  389. immediately available for some platforms.  (Please contact
  390. (bug-octave@bevo.che.wisc.edu) if you are interested in helping make a
  391. binary distribution available for your system.)
  392.  
  393.    Also, binary distributions are limited to static binaries that do not
  394. support dynamic linking.  For earlier versions of Octave, I tried
  395. distributing dynamically linked binaries but that proved to be too much
  396. trouble to support.  If you want to have a copy of Octave that includes
  397. all the features described in this manual, you will have to build it
  398. from the sources yourself, or find someone else who is willing to do it
  399. for you.
  400.  
  401. * Menu:
  402.  
  403. * Installing Octave from a Binary Distribution::
  404. * Creating a Binary Distribution::
  405.  
  406. 
  407. File: octave,  Node: Installing Octave from a Binary Distribution,  Next: Creating a Binary Distribution,  Prev: Binary Distributions,  Up: Binary Distributions
  408.  
  409. Installing Octave from a Binary Distribution
  410. --------------------------------------------
  411.  
  412.    To install Octave from a binary distribution, execute the command
  413.  
  414.      sh ./install-octave
  415.  
  416. in the top level directory of the distribution.
  417.  
  418.    Binary distributions are normally compiled assuming that Octave will
  419. be installed in the following subdirectories of `/usr/local'.
  420.  
  421. `bin'
  422.      Octave and other binaries that people will want to run directly.
  423.  
  424. `lib'
  425.      Shared libraries that Octave needs in order to run.  These files
  426.      are not included if you are installing a statically linked version
  427.      of Octave.
  428.  
  429. `man/man1'
  430.      Unix-style man pages describing Octave.
  431.  
  432. `info'
  433.      Info files describing Octave.
  434.  
  435. `share/octave/VERSION/m'
  436.      Function files distributed with Octave.  This includes the Octave
  437.      version, so that multiple versions of Octave may be installed at
  438.      the same time.
  439.  
  440. `libexec/octave/VERSION/exec/ARCH'
  441.      Executables to be run by Octave rather than the user.
  442.  
  443. `libexec/octave/VERSION/oct/ARCH'
  444.      Object files that will be dynamically loaded.
  445.  
  446. `share/octave/VERSION/imagelib'
  447.      Image files that are distributed with Octave.
  448.  
  449. where VERSION stands for the current version number of the interpreter,
  450. and ARCH is the type of computer on which Octave is installed (for
  451. example, `i486-pc-os/2').
  452.  
  453.    If these directories don't exist, the script `install-octave' will
  454. create them for you.  The installation script also creates the following
  455. subdirectories of `/usr/local' that are intended for locally installed
  456. functions:
  457.  
  458. `share/octave/site/m'
  459.      Locally installed M-files.
  460.  
  461. `libexec/octave/site/exec/ARCH'
  462.      Locally installed binaries intended to be run by Octave rather
  463.      than by the user.
  464.  
  465. `libexec/octave/site/octave/ARCH'
  466.      Local object files that will be dynamically linked.
  467.  
  468.    If it is not possible for you to install Octave in `/usr/local', or
  469. if you would prefer to install it in a different directory, you can
  470. specify the name of the top level directory as an argument to the
  471. `install-octave' script.  For example:
  472.  
  473.      sh ./install-octave /some/other/directory
  474.  
  475. will install Octave in subdirectories of the directory
  476. `/some/other/directory'.
  477.  
  478. 
  479. File: octave,  Node: Creating a Binary Distribution,  Prev: Installing Octave from a Binary Distribution,  Up: Binary Distributions
  480.  
  481. Creating a Binary Distribution
  482. ------------------------------
  483.  
  484.    Here is how to build a binary distribution for others to use.  If you
  485. want to make a binary distribution for your system available along with
  486. the Octave sources and binaries on (ftp.che.wisc.edu), please follow
  487. this procedure.  For directions explaining how to make the binary
  488. available on the ftp site, please contact
  489. (bug-octave@bevo.che.wisc.edu).
  490.  
  491.    * Unpack the source distribution:
  492.  
  493.           gunzip -c octave-2.1.14.tar.gz | tar xf -
  494.  
  495.    * Change your current directory to the top-level directory of the
  496.      source distribution:
  497.  
  498.           cd octave-2.1.14
  499.  
  500.    * Make the binary distribution:
  501.  
  502.           make binary-dist
  503.  
  504.      This will create a compressed tar file ready for distribution.  It
  505.      will contain statically linked binaries and have a name like
  506.      `octave-2.1.14-i486-pc-os/2.tar.gz'
  507.  
  508. 
  509. File: octave,  Node: Emacs,  Next: Grammar,  Prev: Installation,  Up: Top
  510.  
  511. Emacs Octave Support
  512. ********************
  513.  
  514.    The development of Octave code can greatly be facilitated using Emacs
  515. with Octave mode, a major mode for editing Octave files which can e.g.
  516. automatically indent the code, do some of the typing (with Abbrev mode)
  517. and show keywords, comments, strings, etc. in different faces (with
  518. Font-lock mode on devices that support it).
  519.  
  520.    It is also possible to run Octave from within Emacs, either by
  521. directly entering commands at the prompt in a buffer in Inferior Octave
  522. mode, or by interacting with Octave from within a file with Octave
  523. code.  This is useful in particular for debugging Octave code.
  524.  
  525.    Finally, you can convince Octave to use the Emacs info reader for
  526. `help -i'.
  527.  
  528.    All functionality is provided by the Emacs Lisp package EOS (for
  529. "Emacs Octave Support").  This chapter describes how to set up and use
  530. this package.
  531.  
  532.    Please contact <Kurt.Hornik@ci.tuwien.ac.at> if you have any
  533. questions or suggestions on using EOS.
  534.  
  535. * Menu:
  536.  
  537. * Installing EOS::
  538. * Using Octave Mode::
  539. * Running Octave From Within Emacs::
  540. * Using the Emacs Info Reader for Octave::
  541.  
  542. 
  543. File: octave,  Node: Installing EOS,  Next: Using Octave Mode,  Prev: Emacs,  Up: Emacs
  544.  
  545. Installing EOS
  546. ==============
  547.  
  548.    The Emacs package EOS consists of the three files `octave-mod.el',
  549. `octave-inf.el', and `octave-hlp.el'.  These files, or better yet their
  550. byte-compiled versions, should be somewhere in your Emacs load-path.
  551.  
  552.    If you have GNU Emacs with a version number at least as high as
  553. 19.35, you are all set up, because EOS is respectively will be part of
  554. GNU Emacs as of version 19.35.
  555.  
  556.    Otherwise, copy the three files from the `emacs' subdirectory of the
  557. Octave distribution to a place where Emacs can find them (this depends
  558. on how your Emacs was installed).  Byte-compile them for speed if you
  559. want.
  560.  
  561. 
  562. File: octave,  Node: Using Octave Mode,  Next: Running Octave From Within Emacs,  Prev: Installing EOS,  Up: Emacs
  563.  
  564. Using Octave Mode
  565. =================
  566.  
  567.    If you are lucky, your sysadmins have already arranged everything so
  568. that Emacs automatically goes into Octave mode whenever you visit an
  569. Octave code file as characterized by its extension `.m'.  If not,
  570. proceed as follows.
  571.  
  572.   1. To begin using Octave mode for all `.m' files you visit, add the
  573.      following lines to a file loaded by Emacs at startup time,
  574.      typically your `~/.emacs' file:
  575.  
  576.           (autoload 'octave-mode "octave-mod" nil t)
  577.           (setq auto-mode-alist
  578.                 (cons '("\\.m$" . octave-mode) auto-mode-alist))
  579.  
  580.   2. Finally, to turn on the abbrevs, auto-fill and font-lock features
  581.      automatically, also add the following lines to one of the Emacs
  582.      startup files:
  583.           (add-hook 'octave-mode-hook
  584.                     (lambda ()
  585.                       (abbrev-mode 1)
  586.                       (auto-fill-mode 1)
  587.                       (if (eq window-system 'x)
  588.                           (font-lock-mode 1))))
  589.      See the Emacs manual for more information about how to customize
  590.      Font-lock mode.
  591.  
  592.    In Octave mode, the following special Emacs commands can be used in
  593. addition to the standard Emacs commands.
  594.  
  595. `C-h m'
  596.      Describe the features of Octave mode.
  597.  
  598. `LFD'
  599.      Reindent the current Octave line, insert a newline and indent the
  600.      new line (`octave-reindent-then-newline-and-indent').  An abbrev
  601.      before point is expanded if `abbrev-mode' is non-`nil'.
  602.  
  603. `TAB'
  604.      Indents current Octave line based on its contents and on previous
  605.      lines (`indent-according-to-mode').
  606.  
  607. `;'
  608.      Insert an "electric" semicolon (`octave-electric-semi').  If
  609.      `octave-auto-indent' is non-`nil', reindent the current line.  If
  610.      `octave-auto-newline' is non-`nil', automagically insert a newline
  611.      and indent the new line.
  612.  
  613. ``'
  614.      Start entering an abbreviation (`octave-abbrev-start').  If Abbrev
  615.      mode is turned on, typing ``C-h' or ``?' lists all abbrevs.  Any
  616.      other key combination is executed normally.  Note that all Octave
  617.      abbrevs start with a grave accent.
  618.  
  619. `M-LFD'
  620.      Break line at point and insert continuation marker and alignment
  621.      (`octave-split-line').
  622.  
  623. `M-TAB'
  624.      Perform completion on Octave symbol preceding point, comparing that
  625.      symbol against Octave's reserved words and builtin variables
  626.      (`octave-complete-symbol').
  627.  
  628. `M-C-a'
  629.      Move backward to the beginning of a function
  630.      (`octave-beginning-of-defun').  With prefix argument N, do it that
  631.      many times if N is positive;  otherwise, move forward to the N-th
  632.      following beginning of a function.
  633.  
  634. `M-C-e'
  635.      Move forward to the end of a function (`octave-end-of-defun').
  636.      With prefix argument N, do it that many times if N is positive;
  637.      otherwise, move back to the N-th preceding end of a function.
  638.  
  639. `M-C-h'
  640.      Puts point at beginning and mark at the end of the current Octave
  641.      function, i.e., the one containing point or following point
  642.      (`octave-mark-defun').
  643.  
  644. `M-C-q'
  645.      Properly indents the Octave function which contains point
  646.      (`octave-indent-defun').
  647.  
  648. `M-;'
  649.      If there is no comment already on this line, create a code-level
  650.      comment (started by two comment characters) if the line is empty,
  651.      or an in-line comment (started by one comment character) otherwise
  652.      (`octave-indent-for-comment').  Point is left after the start of
  653.      the comment which is properly aligned.
  654.  
  655. `C-c ;'
  656.      Puts the comment character `#' (more precisely, the string value of
  657.      `octave-comment-start') at the beginning of every line in the
  658.      region (`octave-comment-region').  With just `C-u' prefix
  659.      argument, uncomment each line in the region.  A numeric prefix
  660.      argument N means use N comment characters.
  661.  
  662. `C-c :'
  663.      Uncomments every line in the region (`octave-uncomment-region').
  664.  
  665. `C-c C-p'
  666.      Move one line of Octave code backward, skipping empty and comment
  667.      lines (`octave-previous-code-line').  With numeric prefix argument
  668.      N, move that many code lines backward (forward if N is negative).
  669.  
  670. `C-c C-n'
  671.      Move one line of Octave code forward, skipping empty and comment
  672.      lines (`octave-next-code-line').  With numeric prefix argument N,
  673.      move that many code lines forward (backward if N is negative).
  674.  
  675. `C-c C-a'
  676.      Move to the `real' beginning of the current line
  677.      (`octave-beginning-of-line').  If point is in an empty or comment
  678.      line, simply go to its beginning;  otherwise, move backwards to the
  679.      beginning of the first code line which is not inside a continuation
  680.      statement,  i.e., which does not follow a code line ending in `...'
  681.      or `\', or is inside an open parenthesis list.
  682.  
  683. `C-c C-e'
  684.      Move to the `real' end of the current line (`octave-end-of-line').
  685.      If point is in a code line, move forward to the end of the first
  686.      Octave code line which does not end in `...' or `\' or is inside an
  687.      open parenthesis list.  Otherwise, simply go to the end of the
  688.      current line.
  689.  
  690. `C-c M-C-n'
  691.      Move forward across one balanced begin-end block of Octave code
  692.      (`octave-forward-block').  With numeric prefix argument N, move
  693.      forward across N such blocks (backward if N is negative).
  694.  
  695. `C-c M-C-p'
  696.      Move back across one balanced begin-end block of Octave code
  697.      (`octave-backward-block').  With numeric prefix argument N, move
  698.      backward across N such blocks (forward if N is negative).
  699.  
  700. `C-c M-C-d'
  701.      Move forward down one begin-end block level of Octave code
  702.      (`octave-down-block').  With numeric prefix argument, do it that
  703.      many times;  a negative argument means move backward, but still go
  704.      down one level.
  705.  
  706. `C-c M-C-u'
  707.      Move backward out of one begin-end block level of Octave code
  708.      (`octave-backward-up-block').  With numeric prefix argument, do it
  709.      that many times; a negative argument means move forward, but still
  710.      to a less deep spot.
  711.  
  712. `C-c M-C-h'
  713.      Put point at the beginning of this block, mark at the end
  714.      (`octave-mark-block').  The block marked is the one that contains
  715.      point or follows point.
  716.  
  717. `C-c ]'
  718.      Close the current block on a separate line (`octave-close-block').
  719.      An error is signaled if no block to close is found.
  720.  
  721. `C-c f'
  722.      Insert a function skeleton, prompting for the function's name,
  723.      arguments and return values which have to be entered without parens
  724.      (`octave-insert-defun').
  725.  
  726. `C-c C-h'
  727.      Search the function, operator and variable indices of all info
  728.      files with documentation for Octave for entries (`octave-help').
  729.      If used interactively, the entry is prompted for with completion.
  730.      If multiple matches are found, one can cycle through them using
  731.      the standard `,' (`Info-index-next') command of the Info reader.
  732.  
  733.      The variable `octave-help-files' is a list of files to search
  734.      through and defaults to `'("octave")'.  If there is also an Octave
  735.      Local Guide with corresponding info file, say, `octave-LG', you can
  736.      have `octave-help' search both files by
  737.           (setq octave-help-files '("octave" "octave-LG"))
  738.  
  739.      in one of your Emacs startup files.
  740.  
  741.    A common problem is that the RET key does *not* indent the line to
  742. where the new text should go after inserting the newline.  This is
  743. because the standard Emacs convention is that RET (aka `C-m') just adds
  744. a newline, whereas LFD (aka `C-j') adds a newline and indents it.  This
  745. is particularly inconvenient for users with keyboards which do not have
  746. a special LFD key at all;  in such cases, it is typically more
  747. convenient to use RET as the LFD key (rather than typing `C-j').
  748.  
  749.    You can make RET do this by adding
  750.      (define-key octave-mode-map "\C-m"
  751.        'octave-reindent-then-newline-and-indent)
  752.  
  753. to one of your Emacs startup files.  Another, more generally applicable
  754. solution is
  755.      (defun RET-behaves-as-LFD ()
  756.        (let ((x (key-binding "\C-j")))
  757.          (local-set-key "\C-m" x)))
  758.      (add-hook 'octave-mode-hook 'RET-behaves-as-LFD)
  759.  
  760. (this works for all modes by adding to the startup hooks, without having
  761. to know the particular binding of RET in that mode!).  Similar
  762. considerations apply for using M-RET as M-LFD.  As Barry A. Warsaw
  763. <bwarsaw@cnri.reston.va.us> says in the documentation for his
  764. `cc-mode', "This is a very common question. `:-)' If you want this to
  765. be the default behavior, don't lobby me, lobby RMS!"
  766.  
  767.    The following variables can be used to customize Octave mode.
  768.  
  769. `octave-auto-indent'
  770.      Non-`nil' means auto-indent the current line after a semicolon or
  771.      space.  Default is `nil'.
  772.  
  773. `octave-auto-newline'
  774.      Non-`nil' means auto-insert a newline and indent after semicolons
  775.      are typed.  The default value is `nil'.
  776.  
  777. `octave-blink-matching-block'
  778.      Non-`nil' means show matching begin of block when inserting a
  779.      space, newline or `;' after an else or end keyword.  Default is
  780.      `t'.  This is an extremely useful feature for automatically
  781.      verifying that the keywords match--if they don't, an error message
  782.      is displayed.
  783.  
  784. `octave-block-offset'
  785.      Extra indentation applied to statements in block structures.
  786.      Default is 2.
  787.  
  788. `octave-continuation-offset'
  789.      Extra indentation applied to Octave continuation lines.  Default
  790.      is 4.
  791.  
  792. `octave-continuation-string'
  793.      String used for Octave continuation lines.  Normally `\'.
  794.  
  795. `octave-mode-startup-message'
  796.      If `t' (default), a startup message is displayed when Octave mode
  797.      is called.
  798.  
  799.    If Font Lock mode is enabled, Octave mode will display
  800.    * strings in `font-lock-string-face'
  801.  
  802.    * comments in `font-lock-comment-face'
  803.  
  804.    * the Octave reserved words (such as all block keywords) and the text
  805.      functions (such as `cd' or `who') which are also reserved using
  806.      `font-lock-keyword-face'
  807.  
  808.    * the builtin operators (`&&', `<>', ...) using
  809.      `font-lock-reference-face'
  810.  
  811.    * the builtin variables (such as `prefer_column_vectors', `NaN' or
  812.      `LOADPATH') in `font-lock-variable-name-face'
  813.  
  814.    * and the function names in function declarations in
  815.      `font-lock-function-name-face'.
  816.  
  817.    There is also rudimentary support for Imenu (currently, function
  818. names can be indexed).
  819.  
  820.    You can generate TAGS files for Emacs from Octave `.m' files using
  821. the shell script `otags' that is installed alongside your copy of
  822. Octave.
  823.  
  824.    Customization of Octave mode can be performed by modification of the
  825. variable `octave-mode-hook'.  It the value of this variable is
  826. non-`nil', turning on Octave mode calls its value.
  827.  
  828.    If you discover a problem with Octave mode, you can conveniently
  829. send a bug report using `C-c C-b' (`octave-submit-bug-report').  This
  830. automatically sets up a mail buffer with version information already
  831. added.  You just need to add a description of the problem, including a
  832. reproducible test case and send the message.
  833.  
  834. 
  835. File: octave,  Node: Running Octave From Within Emacs,  Next: Using the Emacs Info Reader for Octave,  Prev: Using Octave Mode,  Up: Emacs
  836.  
  837. Running Octave From Within Emacs
  838. ================================
  839.  
  840.    The package `octave' provides commands for running an inferior
  841. Octave process in a special Emacs buffer.  Use
  842.      M-x run-octave
  843.  
  844. to directly start an inferior Octave process.  If Emacs does not know
  845. about this command, add the line
  846.      (autoload 'run-octave "octave-inf" nil t)
  847.  
  848. to your `.emacs' file.
  849.  
  850.    This will start Octave in a special buffer the name of which is
  851. specified by the variable `inferior-octave-buffer' and defaults to
  852. `"*Inferior Octave*"'.  From within this buffer, you can interact with
  853. the inferior Octave process `as usual', i.e., by entering Octave
  854. commands at the prompt.  The buffer is in Inferior Octave mode, which
  855. is derived from the standard Comint mode, a major mode for interacting
  856. with an inferior interpreter.  See the documentation for `comint-mode'
  857. for more details, and use `C-h b' to find out about available special
  858. keybindings.
  859.  
  860.    You can also communicate with an inferior Octave process from within
  861. files with Octave code (i.e., buffers in Octave mode), using the
  862. following commands.
  863.  
  864. `C-c i l'
  865.      Send the current line to the inferior Octave process
  866.      (`octave-send-line').  With positive prefix argument N, send that
  867.      many lines.  If `octave-send-line-auto-forward' is non-`nil', go
  868.      to the next unsent code line.
  869.  
  870. `C-c i b'
  871.      Send the current block to the inferior Octave process
  872.      (`octave-send-block').
  873.  
  874. `C-c i f'
  875.      Send the current function to the inferior Octave process
  876.      (`octave-send-defun').
  877.  
  878. `C-c i r'
  879.      Send the region to the inferior Octave process
  880.      (`octave-send-region').
  881.  
  882. `C-c i s'
  883.      Make sure that `inferior-octave-buffer' is displayed
  884.      (`octave-show-process-buffer').
  885.  
  886. `C-c i h'
  887.      Delete all windows that display the inferior Octave buffer
  888.      (`octave-hide-process-buffer').
  889.  
  890. `C-c i k'
  891.      Kill the inferior Octave process and its buffer
  892.      (`octave-kill-process').
  893.  
  894.    The effect of the commands which send code to the Octave process can
  895. be customized by the following variables.
  896. `octave-send-echo-input'
  897.      Non-`nil' means echo input sent to the inferior Octave process.
  898.      Default is `t'.
  899.  
  900. `octave-send-show-buffer'
  901.      Non-`nil' means display the buffer running the Octave process after
  902.      sending a command (but without selecting it).  Default is `t'.
  903.  
  904.    If you send code and there is no inferior Octave process yet, it
  905. will be started automatically.
  906.  
  907.    The startup of the inferior Octave process is highly customizable.
  908. The variable `inferior-octave-startup-args' can be used for specifying
  909. command lines arguments to be passed to Octave on startup as a list of
  910. strings.  For example, to suppress the startup message and use
  911. `traditional' mode, set this to `'("-q" "--traditional")'.  You can
  912. also specify a startup file of Octave commands to be loaded on startup;
  913. note that these commands will not produce any visible output in the
  914. process buffer.  Which file to use is controlled by the variable
  915. `inferior-octave-startup-file'.  If this is `nil', the file
  916. `~/.emacs-octave' is used if it exists.
  917.  
  918.    And finally, `inferior-octave-mode-hook' is run after starting the
  919. process and putting its buffer into Inferior Octave mode.  Hence, if you
  920. like the up and down arrow keys to behave in the interaction buffer as
  921. in the shell, and you want this buffer to use nice colors, add
  922.      (add-hook 'inferior-octave-mode-hook
  923.                (lambda ()
  924.                  (turn-on-font-lock)
  925.                  (define-key inferior-octave-mode-map [up]
  926.                    'comint-previous-input)
  927.                  (define-key inferior-octave-mode-map [down]
  928.                    'comint-next-input)))
  929.  
  930. to your `.emacs' file.  You could also swap the roles of `C-a'
  931. (`beginning-of-line') and `C-c C-a' (`comint-bol') using this hook.
  932.  
  933.      *Note:* If you set your Octave prompts to something different from
  934.      the defaults, make sure that `inferior-octave-prompt' matches them.
  935.      Otherwise, *nothing* will work, because Emacs will have no idea
  936.      when Octave is waiting for input, or done sending output.
  937.  
  938. 
  939. File: octave,  Node: Using the Emacs Info Reader for Octave,  Prev: Running Octave From Within Emacs,  Up: Emacs
  940.  
  941. Using the Emacs Info Reader for Octave
  942. ======================================
  943.  
  944.    You can also set up the Emacs Info reader for dealing with the
  945. results of Octave's `help -i'.  For this, the package `gnuserv' needs
  946. to be installed, which unfortunately still does not come with GNU Emacs
  947. (it does with XEmacs).  It can be retrieved from any GNU Emacs Lisp Code
  948. Directory archive, e.g.
  949. (ftp://ftp.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive), in the
  950. `packages' subdirectory.  The alpha version of an enhanced version of
  951. gnuserv is available at
  952. (ftp://ftp.wellfleet.com/netman/psmith/emacs/gnuserv-2.1alpha.tar.gz).
  953.  
  954.    If `gnuserv' is installed, add the lines
  955.      (autoload 'octave-help "octave-hlp" nil t)
  956.      (require 'gnuserv)
  957.      (gnuserv-start)
  958.  
  959. to your `.emacs' file.
  960.  
  961.    You can use either `plain' Emacs Info or the function `octave-help'
  962. as your Octave info reader (for `help -i').  In the former case, set
  963. the Octave variable `INFO_PROGRAM' to `"info-emacs-info"'.  The latter
  964. is perhaps more attractive because it allows to look up keys in the
  965. indices of *several* info files related to Octave (provided that the
  966. Emacs variable `octave-help-files' is set correctly).  In this case,
  967. set `INFO_PROGRAM' to `"info-emacs-octave-help"'.
  968.  
  969.    If you use Octave from within Emacs, these settings are best done in
  970. the `~/.emacs-octave' startup file (or the file pointed to by the Emacs
  971. variable `inferior-octave-startup-file').
  972.  
  973. 
  974. File: octave,  Node: Grammar,  Next: Copying,  Prev: Emacs,  Up: Top
  975.  
  976. Grammar
  977. *******
  978.  
  979.    Someday I hope to expand this to include a semi-formal description of
  980. Octave's language.
  981.  
  982. * Menu:
  983.  
  984. * Keywords::
  985.  
  986. 
  987. File: octave,  Node: Keywords,  Prev: Grammar,  Up: Grammar
  988.  
  989. Keywords
  990. ========
  991.  
  992.    The following identifiers are keywords, and may not be used as
  993. variable or function names:
  994.  
  995.      all_va_args             endwhile
  996.      break                   for
  997.      case                    function
  998.      catch                   global
  999.      continue                gplot
  1000.      else                    gsplot
  1001.      elseif                  if
  1002.      end                     otherwise
  1003.      end_try_catch           return
  1004.      end_unwind_protect      switch
  1005.      endfor                  try
  1006.      endfunction             unwind_protect
  1007.      endif                   unwind_protect_cleanup
  1008.      endswitch               while
  1009.  
  1010.    The following command-like functions are also speical.  They may be
  1011. used as simple variable names, but not as formal parameters for
  1012. functions, or as the names of structure variables.  Failed assignments
  1013. leave them undefined (you can recover the orginal definition as a
  1014. function using clear).
  1015.  
  1016.      casesen       echo          load          show
  1017.      cd            edit_history  ls            type
  1018.      chdir         format        more          which
  1019.      clear         help          run_history   who
  1020.      diary         history       save          whos
  1021.      dir           hold          set
  1022.  
  1023.