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

[Rüdiger Sonderfeld]

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  <address@hidden>
+
+       * 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  <address@hidden>
 
        * .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-*-
address@hidden %**start of header
address@hidden ../../info/octave-mode
address@hidden Octave Mode
address@hidden %**end of header
+
address@hidden copied from GNU Octave's macros.texi.
address@hidden The following macro works around the Info/plain text expansion 
of @code{XXX}
address@hidden which is `XXX'.  This looks particularly bad when the macro body 
is
address@hidden single or double-quoted text, such as a property value 
`"position"'
address@hidden
address@hidden qcode{arg}
+\arg\
address@hidden macro
address@hidden ifinfo
address@hidden
address@hidden qcode{arg}
address@hidden
address@hidden macro
address@hidden ifnotinfo
+
address@hidden
+Copyright @copyright{} 1996--2013 Free Software Foundation, Inc.
+
address@hidden
+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.''
address@hidden quotation
address@hidden copying
+
address@hidden Emacs editing modes
address@hidden
+* Octave mode: (octave-mode).         Emacs mode for editing GNU Octave files.
address@hidden direntry
+
address@hidden
+
address@hidden
address@hidden Octave Mode
address@hidden An Emacs mode for programming in GNU Octave
+
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
+
address@hidden
address@hidden Top
address@hidden Octave Mode
+
address@hidden
address@hidden ifnottex
+
address@hidden
+* Overview::
+* Using Octave Mode::
+* Running Octave from Within Emacs::
address@hidden * Using the Emacs Info Reader for Octave::
+* Index::
address@hidden menu
+
address@hidden Overview
address@hidden 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.
+
address@hidden Using Octave Mode
address@hidden Using Octave Mode
+
+In Octave mode, the following special Emacs commands can be used in
+addition to the standard Emacs commands.
+
address@hidden @kbd
address@hidden C-h m
+Describe the features of Octave mode.
+
address@hidden 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 address@hidden
+
address@hidden TAB
+Indents current Octave line based on its contents and on previous
+lines (@code{indent-according-to-mode}).
+
address@hidden ;
+Insert an ``electric'' semicolon (@code{octave-electric-semi}).  If
address@hidden is address@hidden, reindent the current line.
+If @code{octave-auto-newline} is address@hidden, automagically insert a
+newline and indent the new line.
+
address@hidden `
+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.
+
address@hidden M-LFD
+Break line at point and insert continuation marker and alignment
+(@code{octave-split-line}).
+
address@hidden 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}).
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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}).
+
address@hidden M-C-q
+Properly indents the Octave function which contains point
+(@code{octave-indent-defun}).
+
address@hidden 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.
+
address@hidden C-c ;
+Puts the comment character @samp{#} (more precisely, the string value of
address@hidden) 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
address@hidden means use @var{N} comment characters.
+
address@hidden C-c :
+Uncomments every line in the region (@code{octave-uncomment-region}).
+
address@hidden 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
address@hidden, move that many code lines backward (forward if @var{N} is
+negative).
+
address@hidden 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).
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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).
+
address@hidden 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).
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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}).
+
address@hidden 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
address@hidden,} (@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
address@hidden
+(setq octave-help-files '("octave" "octave-LG"))
address@hidden lisp
address@hidden
+in one of your Emacs startup files.
address@hidden 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
address@hidden) 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
address@hidden
+(define-key octave-mode-map "\C-m"
+  'octave-reindent-then-newline-and-indent)
address@hidden lisp
address@hidden
+to one of your Emacs startup files.  Another, more generally applicable
+solution is
address@hidden
+(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)
address@hidden lisp
address@hidden
+(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
address@hidden, ``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.
+
address@hidden @code
address@hidden octave-auto-indent
address@hidden means auto-indent the current line after a semicolon or
+space.  Default is @code{nil}.
+
address@hidden octave-auto-newline
address@hidden means auto-insert a newline and indent after semicolons
+are typed.  The default value is @code{nil}.
+
address@hidden octave-blink-matching-block
address@hidden 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.
+
address@hidden octave-block-offset
+Extra indentation applied to statements in block structures.
+Default is 2.
+
address@hidden octave-continuation-offset
+Extra indentation applied to Octave continuation lines.
+Default is 4.
+
address@hidden octave-continuation-string
+String used for Octave continuation lines.
+Normally @samp{\}.
+
address@hidden octave-font-lock-texinfo-comment
+Highlight texinfo comment blocks.  The default value is @code{t}.
+
address@hidden table
+
+If Font Lock mode is enabled, Octave mode will display
+
address@hidden @bullet
address@hidden
+strings in @code{font-lock-string-face}
+
address@hidden
+comments in @code{font-lock-comment-face}
+
address@hidden
+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}
+
address@hidden
+the built-in operators (@samp{&&}, @samp{==}, @dots{}) using
address@hidden
+
address@hidden
+and the function names in function declarations in
address@hidden
address@hidden itemize
+
+There is also rudimentary support for Imenu (currently, function names
+can be indexed).
+
address@hidden TAGS
address@hidden Emacs TAGS files
address@hidden @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
address@hidden, 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.
+
address@hidden Running Octave from Within Emacs
address@hidden Running Octave from Within Emacs
+
+The package @file{octave} provides commands for running an inferior
+Octave process in a special Emacs buffer.  Use
address@hidden
+M-x run-octave
address@hidden lisp
address@hidden
+to directly start an inferior Octave process.  If Emacs does not know
+about this command, add the line
address@hidden
+(autoload 'run-octave "octave-inf" nil t)
address@hidden lisp
address@hidden
+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
address@hidden"*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
address@hidden 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.
+
address@hidden @kbd
address@hidden 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 address@hidden, go to the
+next unsent code line.
+
address@hidden C-c C-i b
+Send the current block to the inferior Octave process
+(@code{octave-send-block}).
+
address@hidden C-c C-i f
+Send the current function to the inferior Octave process
+(@code{octave-send-defun}).
+
address@hidden C-c C-i r
+Send the region to the inferior Octave process
+(@code{octave-send-region}).
+
address@hidden C-c C-i a
+Send the entire buffer to the inferior Octave process
+(@code{octave-send-buffer}).
+
address@hidden C-c C-i s
+Make sure that `inferior-octave-buffer' is displayed
+(@code{octave-show-process-buffer}).
+
address@hidden C-c C-i q
+Delete all windows that display the inferior Octave buffer
+(@code{octave-hide-process-buffer}).
+
address@hidden C-c C-i k
+Kill the inferior Octave process and its buffer
+(@code{octave-kill-process}).
+
address@hidden 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
address@hidden function.
+
address@hidden 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}).
+
address@hidden C-h d
+Display the documentation for function (@code{octave-help}).
+
address@hidden 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.
+
address@hidden table
+
+The effect of the commands which send code to the Octave process can be
+customized by the following variables.
+
address@hidden @code
address@hidden octave-send-echo-input
address@hidden means echo input sent to the inferior Octave process.
+Default is @code{t}.
+
address@hidden octave-send-show-buffer
address@hidden means display the buffer running the Octave process after
+sending a command (but without selecting it).
+Default is @code{t}.
address@hidden 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
address@hidden/.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
address@hidden
+
+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
address@hidden
+(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)))
address@hidden lisp
address@hidden
+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.
+
address@hidden
address@hidden 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.
address@hidden quotation
+
address@hidden Index
address@hidden Index
+
address@hidden cp
+
address@hidden
+
address@hidden Using the Emacs Info Reader for Octave
address@hidden 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
address@hidden
+(autoload 'octave-help "octave-hlp" nil t)
+(require 'gnuserv)
+(gnuserv-start)
address@hidden lisp
address@hidden
+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