--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/interpreter/eos.txi	Tue Oct 19 10:08:42 1999 +0000
@@ -0,0 +1,497 @@
+@c Copyright (C) 1996, 1997 John W. Eaton
+@c Written by Kurt Hornik <Kurt.Hornik@ci.tuwien.ac.at> on 1996/05/17.
+@c Last updated by KH on 1997/07/31.
+@c This is part of the Octave manual.
+@c For copying conditions, see the file gpl.texi.
+
+@node Emacs
+@chapter Emacs Octave Support
+
+The development of Octave code can greatly be facilitated using Emacs
+with Octave mode, a major mode for editing Octave files which can e.g.@:
+automatically indent the code, do some of the typing (with Abbrev mode)
+and show keywords, comments, strings, etc.@: in different faces (with
+Font-lock mode on devices that support it).
+
+It is also possible to run Octave from within Emacs, either by directly
+entering commands at the prompt in a buffer in Inferior Octave mode, or
+by interacting with Octave from within a file with Octave code.  This is
+useful in particular for debugging Octave code.
+
+Finally, you can convince Octave to use the Emacs info reader for
+@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@@ci.tuwien.ac.at> if you have any questions
+or suggestions on using EOS.
+
+@menu
+* Installing EOS::              
+* Using Octave Mode::           
+* Running Octave From Within Emacs::  
+* Using the Emacs Info Reader for Octave::  
+@end menu
+
+@node Installing EOS, Using Octave Mode, Emacs, Emacs
+@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, Running Octave From Within Emacs, Installing EOS, Emacs
+@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 builtin 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 builtin operators (@samp{&&}, @samp{<>}, @dots{}) using
+@code{font-lock-reference-face}
+@item
+the builtin variables (such as @samp{prefer_column_vectors}, @samp{NaN}
+or @samp{LOADPATH}) in @code{font-lock-variable-name-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, Using the Emacs Info Reader for Octave, Using Octave Mode, 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,  , Running Octave From Within Emacs, Emacs
+@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}).
+
+@c Local Variables:
+@c TeX-command-default: "Texinfo"
+@c End: