\input texinfo                  @c -*-texinfo-*-
@c %**start of header
@setfilename ../../info/octave-mode
@settitle Octave Mode
@c %**end of header

@c copied from GNU Octave's macros.texi.
@c The following macro works around the Info/plain text expansion of @code{XXX}
@c which is `XXX'.  This looks particularly bad when the macro body is
@c single or double-quoted text, such as a property value `"position"'
@ifinfo
@macro qcode{arg}
\arg\
@end macro
@end ifinfo
@ifnotinfo
@macro qcode{arg}
@code{\arg\}
@end macro
@end ifnotinfo

@copying
Copyright @copyright{} 1996--2013 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License.''

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.''
@end quotation
@end copying

@dircategory Emacs editing modes
@direntry
* Octave mode: (octave-mode).         Emacs mode for editing GNU Octave files.
@end direntry

@finalout

@titlepage
@title Octave Mode
@subtitle An Emacs mode for programming in GNU Octave

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Octave Mode

@insertcopying
@end ifnottex

@menu
* Overview::
* Using Octave Mode::
* Running Octave from Within Emacs::
@c * Using the Emacs Info Reader for Octave::
* Index::
@end menu

@node Overview
@chapter Overview

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

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

@node Using Octave Mode
@chapter Using Octave Mode

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 C-f
Insert a function skeleton, prompting for the function's name, arguments
and return values which have to be entered without parentheses
(@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 @qcode{'("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 @email{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-font-lock-texinfo-comment
Highlight texinfo comment blocks.  The default value is @code{t}.

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

@cindex TAGS
@cindex Emacs TAGS files
@cindex @code{octave-tags}
You can generate TAGS files for Emacs from Octave @file{.m} files using
the shell script @code{octave-tags} that is installed alongside your copy of
Octave.

Customization of Octave mode can be performed by modification of the
variable @code{octave-mode-hook}.  If 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
@chapter 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
@qcode{"*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 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 C-i b
Send the current block to the inferior Octave process
(@code{octave-send-block}).

@item C-c C-i f
Send the current function to the inferior Octave process
(@code{octave-send-defun}).

@item C-c C-i r
Send the region to the inferior Octave process
(@code{octave-send-region}).

@item C-c C-i a
Send the entire buffer to the inferior Octave process
(@code{octave-send-buffer}).

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

@item C-c C-i q
Delete all windows that display the inferior Octave buffer
(@code{octave-hide-process-buffer}).

@item C-c C-i k
Kill the inferior Octave process and its buffer
(@code{octave-kill-process}).

@item C-c C-l
Parse and execute the current file in the inferior Octave buffer
(@code{octave-source-file}).  This is done using Octave's
@code{source} function.

@item M-.
Find the definition of a function or variable.  Functions implemented
in C++ can be found if variable @code{octave-source-directories} is
set correctly (@code{octave-find-definition}).

@item C-h d
Display the documentation for function (@code{octave-help}).

@item C-h a
Search for a given string in all the first sentence of function help
strings (@code{octave-lookfor}).  With a @code{universal-argument} the
entire help string is searched.

@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 @qcode{'("-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}.
The default is @file{~/.emacs-octave} or if this file is not found
@file{~/.emacs.d/init_octave.m}.

By customizing @code{inferior-octave-prompt-read-only} the prompt can
be changed to be read only.  The default value is the same as
@code{comint-prompt-read-only}.

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} that 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 not know
when Octave is waiting for input, or done sending output.
@end quotation

@node Index
@unnumbered Index

@printindex cp

@bye

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

You may also use the Emacs Info reader with Octave's @code{doc} function.

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,
use @code{info_program ("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, use @code{info_program ("info-emacs-octave-help")}.

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