[PATCH] Import `octave-mode' manual from GNU Octave.

["Rüdiger Sonderfeld" <ruediger@c-plusplus.de>]

If this is acceptable I'll push it to trunk.  I'm not sure if I should
put Kurt Hornik as the author of the change.

Regards,
Rüdiger

-- 8< ------------------------------------------------------------- >8 --

The manual was written by Kurt Hornik.  He agreed to assign the
copyright for it to the FSF.  I have updated and modified the manual.

* doc/misc/octave-mode.texi: Imported from GNU Octave
  (doc/interpreter/emacs.txi).
* doc/misc/Makefile.in: Add octave-mode.texi.
---
 ChangeLog                 |   6 +
 doc/misc/Makefile.in      |  27 ++-
 doc/misc/octave-mode.texi | 530 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 555 insertions(+), 8 deletions(-)
 create mode 100644 doc/misc/octave-mode.texi

diff --git a/ChangeLog b/ChangeLog
index 01c16d0..209eba9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2013-12-06  Rüdiger Sonderfeld  <ruediger@c-plusplus.de>
+
+	* doc/misc/octave-mode.texi: Imported from GNU Octave
+	  (doc/interpreter/emacs.txi).
+	* doc/misc/Makefile.in: Add octave-mode.texi.
+
 2013-12-01  Dmitry Gutov  <dgutov@yandex.ru>
 
 	* .dir-locals.el (log-edit-move): Add the "Author: " header.
diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in
index 70fb05e..869f2fd 100644
--- a/doc/misc/Makefile.in
+++ b/doc/misc/Makefile.in
@@ -63,14 +63,13 @@ MAKEINFO_OPTS = --force -I$(emacsdir)
 DOCMISC_W32 = @DOCMISC_W32@
 
 ## Info files to build and install on all platforms.
-INFO_COMMON = ada-mode auth autotype bovine calc ccmode cl \
-	dbus dired-x ebrowse ede ediff edt eieio \
-	emacs-mime epa erc ert eshell eudc efaq \
-	flymake forms gnus emacs-gnutls htmlfontify idlwave ido info.info \
-	mairix-el message mh-e newsticker nxml-mode \
-	org pcl-cvs pgg rcirc remember reftex sasl \
-	sc semantic ses sieve smtpmail speedbar srecode todo-mode tramp \
-	url vip viper widget wisent woman
+INFO_COMMON = ada-mode auth autotype bovine calc ccmode cl dbus		\
+	dired-x ebrowse ede ediff edt eieio emacs-mime epa erc ert	\
+	eshell eudc efaq flymake forms gnus emacs-gnutls htmlfontify	\
+	idlwave ido info.info mairix-el message mh-e newsticker		\
+	nxml-mode octave-mode org pcl-cvs pgg rcirc remember reftex	\
+	sasl sc semantic ses sieve smtpmail speedbar srecode		\
+	todo-mode tramp url vip viper widget wisent woman
 
 ## Info files to install on current platform.
 INFO_INSTALL = $(INFO_COMMON) $(DOCMISC_INFO_W32)
@@ -564,6 +563,18 @@ nxml-mode.pdf: $(nxml_mode_deps)
 nxml-mode.html: $(nxml_mode_deps)
 	$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/nxml-mode.texi
 
+octave_mode-deps = ${srcdir}/octave-mode.texi ${gfdl}
+octave-mode : $(buildinfodir)/octave-mode$(INFO_EXT)
+$(buildinfodir)/octave-mode$(INFO_EXT): $(octave_deps)
+	$(mkinfodir)
+	$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/octave-mode.texi
+octave-mode.dvi: $(octave_mode_deps)
+	$(ENVADD) $(TEXI2DVI) ${srcdir}/octave-mode.texi
+octave-mode.pdf: $(octave_mode_deps)
+	$(ENVADD) $(TEXI2PDF) ${srcdir}/octave-mode.texi
+octave-mode.html: $(octave_mode_deps)
+	$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/octave-mode.texi
+
 org_deps = ${srcdir}/org.texi ${gfdl}
 org : $(buildinfodir)/org$(INFO_EXT)
 $(buildinfodir)/org$(INFO_EXT): $(org_deps)
diff --git a/doc/misc/octave-mode.texi b/doc/misc/octave-mode.texi
new file mode 100644
index 0000000..d9efd28
--- /dev/null
+++ b/doc/misc/octave-mode.texi
@@ -0,0 +1,530 @@
+\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}).
-- 
1.8.5