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

[Rüdiger Sonderfeld]

Hello Eli,
thanks for your comments.  I'm not very familiar with texinfo, yet.
So your comments were very helpful.  I hope I have fixed all the issues.

I have removed some more obsolete parts as well.  I have also updated
octave.el to reference the manual.

> Something's wrong here with the encoding.  (I received the mail
> encoded in UTF-8, so it's not the Latin-vs-UTF messup.  The mail in
> mbox format has "R=C3=83=C2=BCdiger", which looks wrong.)

I guess that's what I get for not sending the E-Mail from Emacs.  It
seems to be an issue between my mail client, imap, and git.  It seems
correct in the repo, so it should be correct when I push it.

> Anything after "@bye" will be ignored, so this last node will not be
> in the output.  Is this what you meant?

Yes.  The section is outdated.  GNU Octave calls the info(1) program
which will fail in `comint-mode'.  The section described how to work
around it by using the old `gnuserv' support and a shell script.  I
have an updated version of that shell script.  It basically emulates
info(1) by calling emacsclient with the proper flags.  But I'm not
sure how and if it should be distributed within GNU Emacs and maybe if
emacsclient one day supports elisp defined arguments it could be done
completely from emacsclient.  That's why I have commented out the
node.  I have now added literal @c's to make it more clear.

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.
* lisp/progmodes/octave.el (octave-mode, inferior-octave-mode): Link
  to info manual and show keybindings and set `:group' keyword.
---
 ChangeLog                 |   6 +
 doc/misc/Makefile.in      |  14 +-
 doc/misc/octave-mode.texi | 477 ++++++++++++++++++++++++++++++++++++++++++++++
 lisp/ChangeLog            |   5 +
 lisp/progmodes/octave.el  |  18 +-
 5 files changed, 517 insertions(+), 3 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..4c72aaa 100644
--- a/doc/misc/Makefile.in
+++ b/doc/misc/Makefile.in
@@ -67,7 +67,7 @@ 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 \
+       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
@@ -564,6 +564,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_mode_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..2efe9f9
--- /dev/null
+++ b/doc/misc/octave-mode.texi
@@ -0,0 +1,477 @@
+\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
+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::
+* GNU Free Documentation License::
+* Key Index::
+* Variable Index::
+* Lisp Function Index::
+* Concept 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
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-M-j
address@hidden C-M-j
address@hidden octave-indent-new-comment-line
address@hidden octave-continuation-string
+Break Octave line at point, continuing comment if within one.  Insert
address@hidden before breaking the line unless
+inside a list.  Signal an error if within a single-quoted string.
+
address@hidden C-c ;
address@hidden C-c ;
address@hidden octave-update-function-file-comment
+Query replace function names in function file comment.
+
address@hidden C-c C-p
address@hidden C-c C-p
address@hidden octave-previous-code-line
+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
address@hidden is negative).
+
address@hidden C-c C-n
address@hidden C-c C-n
address@hidden octave-next-code-line
+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
address@hidden C-c C-a
address@hidden octave-beginning-of-line
+Move to the beginning of the physical 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
address@hidden  or @samp{\}, or is inside an open parenthesis list.
+
address@hidden C-c C-e
address@hidden C-c C-e
address@hidden octave-end-of-line
+Move to the end of the physical 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-h
address@hidden C-c M-C-h
address@hidden octave-mark-block
+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 ]
address@hidden C-c ]
+Close the current block on a separate line (@code{smie-close-block}).
+An error is signaled if no block to close is found.
+
address@hidden C-c C-f
address@hidden C-c C-f
address@hidden octave-insert-defun
+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
+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
address@hidden@@cnri.reston.va.us, Barry A. Warsaw} 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.
+
address@hidden @code
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-font-lock-texinfo-comment
+Highlight texinfo comment blocks.  The default value is @code{t}.
address@hidden vtable
+
+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
+Function comments blocks in @code{octave-function-comment-block}
address@hidden itemize
+
address@hidden Imenu Support
+There is also rudimentary support for Imenu (@pxref{Imenu,,, emacs,
+The GNU Emacs Manual}).  Currently, function names can be indexed.
+
address@hidden ElDoc Mode Support
address@hidden octave-eldoc-message-style
+ElDoc mode (@pxref{Lisp Doc,,, emacs, The GNU Emacs Manual}) is
+supported.  By customizing @code{octave-eldoc-message-style} it can be
+changed from displaying one or multi line hints.
+
address@hidden @cindex TAGS
address@hidden @cindex Emacs TAGS files
address@hidden @cindex @file{octave-tags}
address@hidden You can generate TAGS files for Emacs from Octave @file{.m} 
files using
address@hidden the shell script @file{octave-tags} that is installed alongside 
your copy of
address@hidden Octave.
address@hidden
address@hidden octave-mode-hook
+Customization of Octave mode can be performed by modification of the
+variable @code{octave-mode-hook}.
+
address@hidden Running Octave from Within Emacs
address@hidden Running Octave from Within Emacs
address@hidden Inferior Octave Mode
+
+Octave mode 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.
+
address@hidden inferior-octave-buffer
+This will start Octave in a special buffer the name of which is
+specified by the variable @code{inferior-octave-buffer} and defaults
+to @file{*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
address@hidden 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
address@hidden C-c C-i l
address@hidden octave-send-line
address@hidden octave-send-line-auto-forward
+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
address@hidden C-c C-i b
address@hidden octave-send-block
+Send the current block to the inferior Octave process
+(@code{octave-send-block}).
+
address@hidden C-c C-i f
address@hidden C-c C-i f
address@hidden octave-send-defun
+Send the current function to the inferior Octave process
+(@code{octave-send-defun}).
+
address@hidden C-c C-i r
address@hidden C-c C-i r
address@hidden octave-send-region
+Send the region to the inferior Octave process
+(@code{octave-send-region}).
+
address@hidden C-c C-i a
address@hidden C-c C-i a
address@hidden octave-send-buffer
+Send the entire buffer to the inferior Octave process
+(@code{octave-send-buffer}).  If the buffer is associated with a file
+then sourcing the buffer by using @kbd{C-c C-l}
+(@code{octave-source-file}) should be preferred.
+
address@hidden C-c C-i s
address@hidden C-c C-i s
address@hidden octave-show-process-buffer
+Make sure that `inferior-octave-buffer' is displayed
+(@code{octave-show-process-buffer}).
+
address@hidden C-c C-i q
address@hidden C-c C-i q
address@hidden octave-hide-process-buffer
+Delete all windows that display the inferior Octave buffer
+(@code{octave-hide-process-buffer}).
+
address@hidden C-c C-i k
address@hidden C-c C-i k
address@hidden octave-kill-process
+Kill the inferior Octave process and its buffer
+(@code{octave-kill-process}).
+
address@hidden C-c C-l
address@hidden C-c C-l
address@hidden octave-source-file
+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-.
address@hidden M-.
address@hidden octave-find-definition
address@hidden octave-source-directories
+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
address@hidden C-h d
address@hidden octave-help
address@hidden octave-help-buffer
+Display the documentation for function (@code{octave-help}).  The
+buffer name can be changed by customizing @code{octave-help-buffer}.
+
address@hidden C-h a
address@hidden C-h a
address@hidden octave-lookfor
+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 vtable
+
+If you send code and there is no inferior Octave process yet, it will
+be started automatically.
+
address@hidden inferior-octave-startup-args
+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}.  The default is
address@hidden/.emacs-octave} or if this file is not found
address@hidden/.emacs.d/init_octave.m}.
+
address@hidden inferior-octave-prompt-read-only
+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
+
address@hidden inferior-octave-mode-hook
+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 ()
+            (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} or @file{init.el} 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 inferior-octave-prompt
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 GNU Free Documentation License
address@hidden GNU Free Documentation License
address@hidden doclicense.texi
+
address@hidden Key Index
address@hidden Key Index
+
address@hidden ky
+
address@hidden Variable Index
address@hidden Variable Index
+
address@hidden vr
+
address@hidden Lisp Function Index
address@hidden Function Index
+
address@hidden fn
+
address@hidden Concept Index
address@hidden Concept Index
+
address@hidden cp
+
+
address@hidden
+
address@hidden TODO Update
+
address@hidden @node Using the Emacs Info Reader for Octave
address@hidden @chapter Using the Emacs Info Reader for Octave
+
address@hidden You may also use the Emacs Info reader with Octave's @code{doc} 
function.
+
address@hidden If @file{gnuserv} is installed, add the lines
address@hidden @lisp
address@hidden (autoload 'octave-help "octave-hlp" nil t)
address@hidden (require 'gnuserv)
address@hidden (gnuserv-start)
address@hidden @end lisp
address@hidden @noindent
address@hidden to your @file{.emacs} file.
+
address@hidden You can use either `plain' Emacs Info or the function 
@code{octave-help}
address@hidden as your Octave info reader (for @samp{help -i}).  In the former 
case,
address@hidden use @code{info_program ("info-emacs-info")}.
address@hidden The latter is perhaps more attractive because it allows to look 
up keys
address@hidden in the indices of @emph{several} info files related to Octave 
(provided
address@hidden that the Emacs variable @code{octave-help-files} is set 
correctly).  In
address@hidden this case, use @code{info_program ("info-emacs-octave-help")}.
+
address@hidden If you use Octave from within Emacs, it is best to add these 
settings to
address@hidden your @file{~/.emacs-octave} startup file (or the file pointed to 
by the
address@hidden Emacs variable @code{inferior-octave-startup-file}).
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 5899f52..25f1d8c 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,8 @@
+2013-12-07  Rüdiger Sonderfeld  <address@hidden>
+
+       * progmodes/octave.el (octave-mode, inferior-octave-mode): Link to
+       info manual and show keybindings and set `:group' keyword.
+
 2013-12-06  Michael Albinus  <address@hidden>
 
        * progmodes/compile.el (compilation-start):
diff --git a/lisp/progmodes/octave.el b/lisp/progmodes/octave.el
index 778659c..d551d0d 100644
--- a/lisp/progmodes/octave.el
+++ b/lisp/progmodes/octave.el
@@ -528,8 +528,14 @@ (define-derived-mode octave-mode prog-mode "Octave"
 Octave is a high-level language, primarily intended for numerical
 computations.  It provides a convenient command line interface
 for solving linear and nonlinear problems numerically.  Function
-definitions can also be stored in files and used in batch mode."
+definitions can also be stored in files and used in batch mode.
+
+See Info node `(octave-mode) Using Octave Mode' for more details.
+
+Key bindings:
+\\{octave-mode-map}"
   :abbrev-table octave-abbrev-table
+  :group 'octave
 
   (smie-setup octave-smie-grammar #'octave-smie-rules
               :forward-token  #'octave-smie-forward-token
@@ -705,8 +711,16 @@ (defun inferior-octave-process-live-p ()
   (process-live-p inferior-octave-process))
 
 (define-derived-mode inferior-octave-mode comint-mode "Inferior Octave"
-  "Major mode for interacting with an inferior Octave process."
+  "Major mode for interacting with an inferior Octave process.
+
+See Info node `(octave-mode) Running Octave from Within Emacs' for more
+details.
+
+Key bindings:
+\\{inferior-octave-mode-map}"
   :abbrev-table octave-abbrev-table
+  :group 'octave
+
   (setq comint-prompt-regexp inferior-octave-prompt)
 
   (setq-local comment-use-syntax t)
-- 
1.8.5