doc/misc/octave-mode.texi

   1 \input texinfo                  @c -*-texinfo-*-
   2 @c %**start of header
   3 @setfilename ../../info/octave-mode
   4 @settitle Octave Mode
   5 @c %**end of header
   6
   7 @copying
   8 Copyright @copyright{} 1996--2013 Free Software Foundation, Inc.
   9
  10 @quotation
  11 Permission is granted to copy, distribute and/or modify this document
  12 under the terms of the GNU Free Documentation License, Version 1.3 or
  13 any later version published by the Free Software Foundation; with no
  14 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
  15 and with the Back-Cover Texts as in (a) below.  A copy of the license
  16 is included in the section entitled ``GNU Free Documentation License.''
  17
  18 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
  19 modify this GNU manual.''
  20 @end quotation
  21 @end copying
  22
  23 @dircategory Emacs editing modes
  24 @direntry
  25 * Octave mode: (octave-mode).         Emacs mode for editing GNU Octave files.
  26 @end direntry
  27
  28 @finalout
  29
  30 @titlepage
  31 @title Octave Mode
  32 @subtitle An Emacs mode for programming in GNU Octave
  33
  34 @page
  35 @vskip 0pt plus 1filll
  36 @insertcopying
  37 @end titlepage
  38
  39 @contents
  40
  41 @ifnottex
  42 @node Top
  43 @top Octave Mode
  44
  45 @insertcopying
  46 @end ifnottex
  47
  48 @menu
  49 * Overview::
  50 * Using Octave Mode::
  51 * Running Octave from Within Emacs::
  52 * GNU Free Documentation License::
  53 * Key Index::
  54 * Variable Index::
  55 * Lisp Function Index::
  56 * Concept Index::
  57 @end menu
  58
  59 @node Overview
  60 @chapter Overview
  61
  62 The development of Octave code can greatly be facilitated using Emacs
  63 with Octave mode, a major mode for editing Octave files which can
  64 e.g.@: automatically indent the code, do some of the typing (with
  65 Abbrev mode) and show keywords, comments, strings, etc.@: in different
  66 faces (with Font-lock mode on devices that support it).
  67
  68 It is also possible to run Octave from within Emacs, either by
  69 directly entering commands at the prompt in a buffer in Inferior
  70 Octave mode, or by interacting with Octave from within a file with
  71 Octave code.  This is useful in particular for debugging Octave code.
  72
  73 @node Using Octave Mode
  74 @chapter Using Octave Mode
  75 @cindex Using Octave Mode
  76
  77 In Octave mode, the following special Emacs commands can be used in
  78 addition to the standard Emacs commands.
  79
  80 @table @kbd
  81 @item C-M-j
  82 @kindex C-M-j
  83 @findex octave-indent-new-comment-line
  84 @vindex octave-continuation-string
  85 Break Octave line at point, continuing comment if within one.  Insert
  86 @code{octave-continuation-string} before breaking the line unless
  87 inside a list.  Signal an error if within a single-quoted string.
  88
  89 @item C-c ;
  90 @kindex C-c ;
  91 @findex octave-update-function-file-comment
  92 Query replace function names in function file comment.
  93
  94 @item C-c C-p
  95 @kindex C-c C-p
  96 @findex octave-previous-code-line
  97 Move one line of Octave code backward, skipping empty and comment
  98 lines (@code{octave-previous-code-line}).  With numeric prefix
  99 argument @var{n}, move that many code lines backward (forward if
 100 @var{n} is negative).
 101
 102 @item C-c C-n
 103 @kindex C-c C-n
 104 @findex octave-next-code-line
 105 Move one line of Octave code forward, skipping empty and comment lines
 106 (@code{octave-next-code-line}).  With numeric prefix argument @var{n},
 107 move that many code lines forward (backward if @var{n} is negative).
 108
 109 @item C-c C-a
 110 @kindex C-c C-a
 111 @findex octave-beginning-of-line
 112 Move to the beginning of the physical line
 113 (@code{octave-beginning-of-line}).  If point is in an empty or comment
 114 line, simply go to its beginning; otherwise, move backwards to the
 115 beginning of the first code line which is not inside a continuation
 116 statement, i.e., which does not follow a code line ending in
 117 @samp{...}  or @samp{\}, or is inside an open parenthesis list.
 118
 119 @item C-c C-e
 120 @kindex C-c C-e
 121 @findex octave-end-of-line
 122 Move to the end of the physical line (@code{octave-end-of-line}).  If
 123 point is in a code line, move forward to the end of the first Octave
 124 code line which does not end in @samp{...} or @samp{\} or is inside an
 125 open parenthesis list.  Otherwise, simply go to the end of the current
 126 line.
 127
 128 @item C-c M-C-h
 129 @kindex C-c M-C-h
 130 @findex octave-mark-block
 131 Put point at the beginning of this block, mark at the end
 132 (@code{octave-mark-block}).  The block marked is the one that contains
 133 point or follows point.
 134
 135 @item C-c ]
 136 @kindex C-c ]
 137 Close the current block on a separate line (@code{smie-close-block}).
 138 An error is signaled if no block to close is found.
 139
 140 @item C-c C-f
 141 @kindex C-c C-f
 142 @findex octave-insert-defun
 143 Insert a function skeleton, prompting for the function's name, arguments
 144 and return values which have to be entered without parentheses
 145 (@code{octave-insert-defun}).
 146 @noindent
 147 in one of your Emacs startup files.
 148 @end table
 149
 150 A common problem is that the @key{RET} key does @emph{not} indent the
 151 line to where the new text should go after inserting the newline.  This
 152 is because the standard Emacs convention is that @key{RET} (aka
 153 @kbd{C-m}) just adds a newline, whereas @key{LFD} (aka @kbd{C-j}) adds a
 154 newline and indents it.  This is particularly inconvenient for users with
 155 keyboards which do not have a special @key{LFD} key at all; in such
 156 cases, it is typically more convenient to use @key{RET} as the @key{LFD}
 157 key (rather than typing @kbd{C-j}).
 158
 159 You can make @key{RET} do this by adding
 160 @lisp
 161 (define-key octave-mode-map "\C-m"
 162   'octave-reindent-then-newline-and-indent)
 163 @end lisp
 164 @noindent
 165 to one of your Emacs startup files.  Another, more generally applicable
 166 solution is
 167 @lisp
 168 (defun RET-behaves-as-LFD ()
 169   (let ((x (key-binding "\C-j")))
 170     (local-set-key "\C-m" x)))
 171 (add-hook 'octave-mode-hook 'RET-behaves-as-LFD)
 172 @end lisp
 173 @noindent
 174 (this works for all modes by adding to the startup hooks, without
 175 having to know the particular binding of @key{RET} in that mode!).
 176 Similar considerations apply for using @key{M-RET} as @key{M-LFD}.  As
 177 @email{bwarsaw@@cnri.reston.va.us, Barry A. Warsaw} says in the
 178 documentation for his @code{cc-mode}, ``This is a very common
 179 question.  @code{:-)} If you want this to be the default behavior,
 180 don't lobby me, lobby RMS!''
 181
 182 The following variables can be used to customize Octave mode.
 183
 184 @vtable @code
 185 @item octave-blink-matching-block
 186 Non-@code{nil} means show matching begin of block when inserting a space,
 187 newline or @samp{;} after an else or end keyword.  Default is @code{t}.
 188 This is an extremely useful feature for automatically verifying that the
 189 keywords match---if they don't, an error message is displayed.
 190
 191 @item octave-block-offset
 192 Extra indentation applied to statements in block structures.
 193 Default is 2.
 194
 195 @item octave-continuation-offset
 196 Extra indentation applied to Octave continuation lines.
 197 Default is 4.
 198
 199 @item octave-font-lock-texinfo-comment
 200 Highlight texinfo comment blocks.  The default value is @code{t}.
 201 @end vtable
 202
 203 If Font Lock mode is enabled, Octave mode will display
 204
 205 @itemize @bullet
 206 @item
 207 strings in @code{font-lock-string-face}
 208
 209 @item
 210 comments in @code{font-lock-comment-face}
 211
 212 @item
 213 the Octave reserved words (such as all block keywords) and the text
 214 functions (such as @samp{cd} or @samp{who}) which are also reserved
 215 using @code{font-lock-keyword-face}
 216
 217 @item
 218 the built-in operators (@samp{&&}, @samp{==}, @dots{}) using
 219 @code{font-lock-reference-face}
 220
 221 @item
 222 and the function names in function declarations in
 223 @code{font-lock-function-name-face}.
 224
 225 @item
 226 Function comments blocks in @code{octave-function-comment-block}
 227 @end itemize
 228
 229 @cindex Imenu Support
 230 There is also rudimentary support for Imenu (@pxref{Imenu,,, emacs,
 231 The GNU Emacs Manual}).  Currently, function names can be indexed.
 232
 233 @cindex ElDoc Mode Support
 234 @vindex octave-eldoc-message-style
 235 ElDoc mode (@pxref{Lisp Doc,,, emacs, The GNU Emacs Manual}) is
 236 supported.  By customizing @code{octave-eldoc-message-style} it can be
 237 changed from displaying one or multi line hints.
 238
 239 @c @cindex TAGS
 240 @c @cindex Emacs TAGS files
 241 @c @cindex @file{octave-tags}
 242 @c You can generate TAGS files for Emacs from Octave @file{.m} files using
 243 @c the shell script @file{octave-tags} that is installed alongside your copy of
 244 @c Octave.
 245 @c
 246 @vindex octave-mode-hook
 247 Customization of Octave mode can be performed by modification of the
 248 variable @code{octave-mode-hook}.
 249
 250 @node Running Octave from Within Emacs
 251 @chapter Running Octave from Within Emacs
 252 @cindex Inferior Octave Mode
 253
 254 Octave mode provides commands for running an inferior
 255 Octave process in a special Emacs buffer.  Use
 256 @lisp
 257 M-x run-octave
 258 @end lisp
 259 @noindent
 260 to directly start an inferior Octave process.
 261
 262 @vindex inferior-octave-buffer
 263 This will start Octave in a special buffer the name of which is
 264 specified by the variable @code{inferior-octave-buffer} and defaults
 265 to @file{*Inferior Octave*}.  From within this buffer, you can
 266 interact with the inferior Octave process `as usual', i.e., by
 267 entering Octave commands at the prompt.  The buffer is in Inferior
 268 Octave mode, which is derived from the standard Comint mode, a major
 269 mode for interacting with an inferior interpreter.  See the
 270 documentation for @code{comint-mode} for more details, and use
 271 @kbd{C-h b} to find out about available special keybindings.
 272
 273 You can also communicate with an inferior Octave process from within
 274 files with Octave code (i.e., buffers in Octave mode), using the
 275 following commands.
 276
 277 @table @kbd
 278 @item C-c C-i l
 279 @kindex C-c C-i l
 280 @findex octave-send-line
 281 @vindex octave-send-line-auto-forward
 282 Send the current line to the inferior Octave process
 283 (@code{octave-send-line}).  With positive prefix argument @var{n},
 284 send that many lines.  If @code{octave-send-line-auto-forward} is
 285 non-@code{nil}, go to the next unsent code line.
 286
 287 @item C-c C-i b
 288 @kindex C-c C-i b
 289 @findex octave-send-block
 290 Send the current block to the inferior Octave process
 291 (@code{octave-send-block}).
 292
 293 @item C-c C-i f
 294 @kindex C-c C-i f
 295 @findex octave-send-defun
 296 Send the current function to the inferior Octave process
 297 (@code{octave-send-defun}).
 298
 299 @item C-c C-i r
 300 @kindex C-c C-i r
 301 @findex octave-send-region
 302 Send the region to the inferior Octave process
 303 (@code{octave-send-region}).
 304
 305 @item C-c C-i a
 306 @kindex C-c C-i a
 307 @findex octave-send-buffer
 308 Send the entire buffer to the inferior Octave process
 309 (@code{octave-send-buffer}).  If the buffer is associated with a file
 310 then sourcing the buffer by using @kbd{C-c C-l}
 311 (@code{octave-source-file}) should be preferred.
 312
 313 @item C-c C-i s
 314 @kindex C-c C-i s
 315 @findex octave-show-process-buffer
 316 Make sure that `inferior-octave-buffer' is displayed
 317 (@code{octave-show-process-buffer}).
 318
 319 @item C-c C-i q
 320 @kindex C-c C-i q
 321 @findex octave-hide-process-buffer
 322 Delete all windows that display the inferior Octave buffer
 323 (@code{octave-hide-process-buffer}).
 324
 325 @item C-c C-i k
 326 @kindex C-c C-i k
 327 @findex octave-kill-process
 328 Kill the inferior Octave process and its buffer
 329 (@code{octave-kill-process}).
 330
 331 @item C-c C-l
 332 @kindex C-c C-l
 333 @findex octave-source-file
 334 Parse and execute the current file in the inferior Octave buffer
 335 (@code{octave-source-file}).  This is done using Octave's
 336 @code{source} function.
 337
 338 @item M-.
 339 @kindex M-.
 340 @findex octave-find-definition
 341 @vindex octave-source-directories
 342 Find the definition of a function or variable.  Functions implemented
 343 in C++ can be found if variable @code{octave-source-directories} is
 344 set correctly (@code{octave-find-definition}).
 345
 346 @item C-h d
 347 @kindex C-h d
 348 @findex octave-help
 349 @vindex octave-help-buffer
 350 Display the documentation for function (@code{octave-help}).  The
 351 buffer name can be changed by customizing @code{octave-help-buffer}.
 352
 353 @item C-h a
 354 @kindex C-h a
 355 @findex octave-lookfor
 356 Search for a given string in all the first sentence of function help
 357 strings (@code{octave-lookfor}).  With a @code{universal-argument} the
 358 entire help string is searched.
 359
 360 @end table
 361
 362 The effect of the commands which send code to the Octave process can be
 363 customized by the following variables.
 364
 365 @vtable @code
 366 @item octave-send-echo-input
 367 Non-@code{nil} means echo input sent to the inferior Octave process.
 368 Default is @code{t}.
 369
 370 @item octave-send-show-buffer
 371 Non-@code{nil} means display the buffer running the Octave process after
 372 sending a command (but without selecting it).
 373 Default is @code{t}.
 374 @end vtable
 375
 376 If you send code and there is no inferior Octave process yet, it will
 377 be started automatically.
 378
 379 @vindex inferior-octave-startup-args
 380 The startup of the inferior Octave process is highly customizable.
 381 The variable @code{inferior-octave-startup-args} can be used for
 382 specifying command lines arguments to be passed to Octave on startup
 383 as a list of strings.  For example, to suppress the startup message
 384 and use `traditional' mode, set this to @code{("-q" "--traditional")}.
 385 You can also specify a startup file of Octave commands to be loaded on
 386 startup; note that these commands will not produce any visible output
 387 in the process buffer.  Which file to use is controlled by the
 388 variable @code{inferior-octave-startup-file}.  The default is
 389 @file{~/.emacs-octave} or if this file is not found
 390 @file{~/.emacs.d/init_octave.m}.
 391
 392 @vindex inferior-octave-prompt-read-only
 393 By customizing @code{inferior-octave-prompt-read-only} the prompt can
 394 be changed to be read only.  The default value is the same as
 395 @code{comint-prompt-read-only}.
 396
 397 @vindex inferior-octave-mode-hook
 398 And finally, @code{inferior-octave-mode-hook} is run after starting
 399 the process and putting its buffer into Inferior Octave mode.  Hence,
 400 if you like the up and down arrow keys to behave in the interaction
 401 buffer as in the shell, and you want this buffer to use nice colors,
 402 add
 403 @lisp
 404 (add-hook 'inferior-octave-mode-hook
 405           (lambda ()
 406             (define-key inferior-octave-mode-map [up]
 407               'comint-previous-input)
 408             (define-key inferior-octave-mode-map [down]
 409               'comint-next-input)))
 410 @end lisp
 411 @noindent
 412 to your @file{.emacs} or @file{init.el} file.  You could also swap the
 413 roles of @kbd{C-a} (@code{beginning-of-line}) and @code{C-c C-a}
 414 (@code{comint-bol}) using this hook.
 415
 416 @vindex inferior-octave-prompt
 417 @quotation
 418 @strong{Note} that if you set your Octave prompts to something different
 419 from the defaults, make sure that @code{inferior-octave-prompt} matches
 420 them.  Otherwise, @emph{nothing} will work, because Emacs will not know
 421 when Octave is waiting for input, or done sending output.
 422 @end quotation
 423
 424 @node GNU Free Documentation License
 425 @chapter GNU Free Documentation License
 426 @include doclicense.texi
 427
 428 @node Key Index
 429 @unnumbered Key Index
 430
 431 @printindex ky
 432
 433 @node Variable Index
 434 @unnumbered Variable Index
 435
 436 @printindex vr
 437
 438 @node Lisp Function Index
 439 @unnumbered Function Index
 440
 441 @printindex fn
 442
 443 @node Concept Index
 444 @unnumbered Concept Index
 445
 446 @printindex cp
 447
 448
 449 @bye
 450
 451 @c TODO Update
 452
 453 @c @node Using the Emacs Info Reader for Octave
 454 @c @chapter Using the Emacs Info Reader for Octave
 455
 456 @c You may also use the Emacs Info reader with Octave's @code{doc} function.
 457
 458 @c If @file{gnuserv} is installed, add the lines
 459 @c @lisp
 460 @c (autoload 'octave-help "octave-hlp" nil t)
 461 @c (require 'gnuserv)
 462 @c (gnuserv-start)
 463 @c @end lisp
 464 @c @noindent
 465 @c to your @file{.emacs} file.
 466
 467 @c You can use either `plain' Emacs Info or the function @code{octave-help}
 468 @c as your Octave info reader (for @samp{help -i}).  In the former case,
 469 @c use @code{info_program ("info-emacs-info")}.
 470 @c The latter is perhaps more attractive because it allows to look up keys
 471 @c in the indices of @emph{several} info files related to Octave (provided
 472 @c that the Emacs variable @code{octave-help-files} is set correctly).  In
 473 @c this case, use @code{info_program ("info-emacs-octave-help")}.
 474
 475 @c If you use Octave from within Emacs, it is best to add these settings to
 476 @c your @file{~/.emacs-octave} startup file (or the file pointed to by the
 477 @c Emacs variable @code{inferior-octave-startup-file}).