[Emacs-diffs] trunk r115456: Import `octave-mode' manual from GNU Octave.

[Rüdiger Sonderfeld]

------------------------------------------------------------
revno: 115456
revision-id: address@hidden
parent: address@hidden
committer: Rüdiger Sonderfeld <address@hidden>
branch nick: trunk
timestamp: Wed 2013-12-11 14:50:46 +0100
message:
  Import `octave-mode' manual from GNU Octave.
  
  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.
added:
  doc/misc/octave-mode.texi      
docmiscoctavemode.te-20131211135130-mke18k9sh7x9vmyx-1
modified:
  ChangeLog                      changelog-20091113204419-o5vbwnq5f7feedwu-1538
  doc/misc/Makefile.in           
makefile.in-20091113204419-o5vbwnq5f7feedwu-6287
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/progmodes/octave.el       
octavemod.el-20091113204419-o5vbwnq5f7feedwu-1028

=== modified file 'ChangeLog'
--- a/ChangeLog 2013-12-11 05:37:30 +0000
+++ b/ChangeLog 2013-12-11 13:50:46 +0000
@@ -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-11  Paul Eggert  <address@hidden>
 
        Remove the option of using libcrypto.

=== modified file 'doc/misc/Makefile.in'
--- a/doc/misc/Makefile.in      2013-11-30 18:34:58 +0000
+++ b/doc/misc/Makefile.in      2013-12-11 13:50:46 +0000
@@ -67,7 +67,7 @@
        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.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)

=== added file 'doc/misc/octave-mode.texi'
--- a/doc/misc/octave-mode.texi 1970-01-01 00:00:00 +0000
+++ b/doc/misc/octave-mode.texi 2013-12-11 13:50:46 +0000
@@ -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}).

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2013-12-11 01:11:24 +0000
+++ b/lisp/ChangeLog    2013-12-11 13:50:46 +0000
@@ -1,3 +1,8 @@
+2013-12-11  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-11  Juri Linkov  <address@hidden>
 
        * delsel.el (delete-active-region): Let-bind `this-command'

=== modified file 'lisp/progmodes/octave.el'
--- a/lisp/progmodes/octave.el  2013-12-06 04:26:17 +0000
+++ b/lisp/progmodes/octave.el  2013-12-11 13:50:46 +0000
@@ -528,8 +528,14 @@
 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 @@
   (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)