@c Copyright (C) 1996, 1997, 1999, 2002, 2003, 2005, 2007 Kurt Hornik
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@c Written by Kurt Hornik <Kurt.Hornik@wu-wien.ac.at> on 1996/05/17.
@c Last updated by KH on 1997/07/31.

@node Emacs
@chapter Emacs Octave Support

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

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

Finally, you can convince Octave to use the Emacs info reader for
@kbd{help -i}.

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

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

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

@node Installing EOS
@section Installing EOS

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

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

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

@node Using Octave Mode
@section Using Octave Mode

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

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

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

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

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

@table @kbd
@item C-h m
Describe the features of Octave mode.

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

@item TAB
Indents current Octave line based on its contents and on previous
lines (@code{indent-according-to-mode}). 

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

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

@item M-LFD
Break line at point and insert continuation marker and alignment
(@code{octave-split-line}).

@item M-TAB
Perform completion on Octave symbol preceding point, comparing that
symbol against Octave's reserved words and built-in variables
(@code{octave-complete-symbol}). 

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

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

@item 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
(@code{octave-mark-defun}).

@item M-C-q
Properly indents the Octave function which contains point
(@code{octave-indent-defun}).

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

@item C-c ;
Puts the comment character @samp{#} (more precisely, the string value of
@code{octave-comment-start}) at the beginning of every line in the
region (@code{octave-comment-region}).  With just @kbd{C-u} prefix
argument, uncomment each line in the region.  A numeric prefix argument
@var{N} means use @var{N} comment characters.

@item C-c :
Uncomments every line in the region (@code{octave-uncomment-region}).

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

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

@item C-c C-a
Move to the `real' beginning of the current line
(@code{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 @samp{...}
or @samp{\}, or is inside an open parenthesis list.

@item C-c C-e
Move to the `real' end of the current line (@code{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 @samp{...} or @samp{\} or is inside an
open parenthesis list.  Otherwise, simply go to the end of the current
line.

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

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

@item C-c M-C-d
Move forward down one begin-end block level of Octave code
(@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.

@item C-c M-C-u
Move backward out of one begin-end block level of Octave code
(@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.

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

@item C-c ]
Close the current block on a separate line (@code{octave-close-block}).
An error is signaled if no block to close is found.

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

@item C-c C-h
Search the function, operator and variable indices of all info files
with documentation for Octave for entries (@code{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
@samp{,} (@code{Info-index-next}) command of the Info reader.

The variable @code{octave-help-files} is a list of files to search
through and defaults to @code{'("octave")}.  If there is also an Octave
Local Guide with corresponding info file, say, @file{octave-LG}, you can
have @code{octave-help} search both files by 
@lisp
(setq octave-help-files '("octave" "octave-LG"))
@end lisp
@noindent
in one of your Emacs startup files.

@end table

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

You can make @key{RET} do this by adding
@lisp
(define-key octave-mode-map "\C-m"
  'octave-reindent-then-newline-and-indent)
@end lisp
@noindent
to one of your Emacs startup files.  Another, more generally applicable
solution is
@lisp
(defun RET-behaves-as-LFD ()
  (let ((x (key-binding "\C-j")))
    (local-set-key "\C-m" x)))
(add-hook 'octave-mode-hook 'RET-behaves-as-LFD)
@end lisp
@noindent
(this works for all modes by adding to the startup hooks, without having
to know the particular binding of @key{RET} in that mode!).  Similar
considerations apply for using @key{M-RET} as @key{M-LFD}.  As Barry
A. Warsaw <bwarsaw@@cnri.reston.va.us> says in the documentation for his
@code{cc-mode}, ``This is a very common question. @code{:-)} 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.

@table @code
@item octave-auto-indent
Non-@code{nil} means auto-indent the current line after a semicolon or
space.  Default is @code{nil}.

@item octave-auto-newline
Non-@code{nil} means auto-insert a newline and indent after semicolons
are typed.  The default value is @code{nil}.

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

@item octave-block-offset
Extra indentation applied to statements in block structures.
Default is 2.

@item octave-continuation-offset
Extra indentation applied to Octave continuation lines.
Default is 4. 

@item octave-continuation-string
String used for Octave continuation lines.
Normally @samp{\}.

@item octave-mode-startup-message
If @code{t} (default), a startup message is displayed when Octave mode
is called.

@end table

If Font Lock mode is enabled, Octave mode will display
@itemize @bullet
@item
strings in @code{font-lock-string-face}
@item
comments in @code{font-lock-comment-face}
@item
the Octave reserved words (such as all block keywords) and the text
functions (such as @samp{cd} or @samp{who}) which are also reserved
using @code{font-lock-keyword-face}
@item
the built-in operators (@samp{&&}, @samp{==}, @dots{}) using
@code{font-lock-reference-face}
@item
and the function names in function declarations in
@code{font-lock-function-name-face}.
@end itemize

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 @code{octave-mode-hook}.  It the value of this variable is
non-@code{nil}, turning on Octave mode calls its value.

If you discover a problem with Octave mode, you can conveniently send a
bug report using @kbd{C-c C-b} (@code{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.

@node Running Octave From Within Emacs
@section Running Octave From Within Emacs

The package @file{octave} provides commands for running an inferior
Octave process in a special Emacs buffer.  Use 
@lisp
M-x run-octave
@end lisp
@noindent
to directly start an inferior Octave process.  If Emacs does not know
about this command, add the line
@lisp
(autoload 'run-octave "octave-inf" nil t)
@end lisp
@noindent
to your @file{.emacs} file.

This will start Octave in a special buffer the name of which is
specified by the variable @code{inferior-octave-buffer} and defaults to
@code{"*Inferior Octave*"}.  From within this buffer, you can
interact with the inferior Octave process `as usual', i.e., by entering
Octave commands at the prompt.  The buffer is in Inferior Octave mode,
which is derived from the standard Comint mode, a major mode for
interacting with an inferior interpreter.  See the documentation for
@code{comint-mode} for more details, and use @kbd{C-h b} to find out
about available special keybindings.

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.

@table @kbd
@item C-c i l
Send the current line to the inferior Octave process
(@code{octave-send-line}).
With positive prefix argument @var{N}, send that many lines.
If @code{octave-send-line-auto-forward} is non-@code{nil}, go to the
next unsent code line.
@item C-c i b
Send the current block to the inferior Octave process
(@code{octave-send-block}).
@item C-c i f
Send the current function to the inferior Octave process
(@code{octave-send-defun}).
@item C-c i r
Send the region to the inferior Octave process
(@code{octave-send-region}).
@item C-c i s
Make sure that `inferior-octave-buffer' is displayed
(@code{octave-show-process-buffer}).
@item C-c i h
Delete all windows that display the inferior Octave buffer
(@code{octave-hide-process-buffer}).
@item C-c i k
Kill the inferior Octave process and its buffer
(@code{octave-kill-process}).
@end table

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

@item octave-send-show-buffer
Non-@code{nil} means display the buffer running the Octave process after
sending a command (but without selecting it).
Default is @code{t}.
@end table

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 @code{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 @code{'("-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
@code{inferior-octave-startup-file}.  If this is @code{nil}, the file
@file{~/.emacs-octave} is used if it exists.

And finally, @code{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
@lisp
(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)))
@end lisp
@noindent
to your @file{.emacs} file.  You could also swap the roles of @kbd{C-a}
(@code{beginning-of-line}) and @code{C-c C-a} (@code{comint-bol}) using
this hook.

@quotation
@strong{Note:}
If you set your Octave prompts to something different from the defaults,
make sure that @code{inferior-octave-prompt} matches them.
Otherwise, @emph{nothing} will work, because Emacs will have no idea
when Octave is waiting for input, or done sending output.
@end quotation

@node Using the Emacs Info Reader for Octave
@section Using the Emacs Info Reader for Octave

You can also set up the Emacs Info reader for dealing with the results
of Octave's @samp{help -i}.  For this, the package @file{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.@:
@url{ftp://ftp.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive},
in the @file{packages} subdirectory.  The alpha version of an enhanced
version of gnuserv is available at 
@url{ftp://ftp.wellfleet.com/netman/psmith/emacs/gnuserv-2.1alpha.tar.gz}.

If @file{gnuserv} is installed, add the lines
@lisp
(autoload 'octave-help "octave-hlp" nil t)
(require 'gnuserv)
(gnuserv-start)
@end lisp
@noindent
to your @file{.emacs} file.

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

If you use Octave from within Emacs, these settings are best done in the
@file{~/.emacs-octave} startup file (or the file pointed to by the Emacs
variable @code{inferior-octave-startup-file}).