2333
|
1 @c Copyright (C) 1996 John W. Eaton |
|
2 @c Written by Kurt Hornik <Kurt.Hornik@ci.tuwien.ac.at> on 1996/05/17 |
|
3 @c Updated for octave.el version 0.8.3 by KH on 1996/07/02 |
|
4 @c This is part of the Octave manual. |
|
5 @c For copying conditions, see the file gpl.texi. |
|
6 |
2449
|
7 @node Emacs, Installation, Amusements, Top |
2333
|
8 @chapter Using Emacs With Octave |
|
9 |
|
10 The development of Octave code can greatly be facilitated using Emacs |
|
11 with Octave mode, a major mode for editing Octave files which can e.g.@: |
|
12 automatically indent the code, do some of the typing (with Abbrev mode) |
|
13 and show keywords, comments, strings, etc.@: in different faces (with |
|
14 Font-lock mode on devices that support it). |
|
15 |
|
16 It is also possible to run Octave from within Emacs, either by directly |
|
17 entering commands at the prompt in a buffer in Inferior Octave mode, or |
|
18 by interacting with Octave from within a file with Octave code. This is |
|
19 useful in particular for debugging Octave code. |
|
20 |
|
21 Finally, you can convince Octave to use the Emacs info reader for |
|
22 @kbd{help -i}. |
|
23 |
|
24 All functionality is provided by the Emacs Lisp package @file{octave}. |
|
25 This chapter describes how to set up and use this package. |
|
26 |
|
27 Please contact <Kurt.Hornik@@ci.tuwien.ac.at> if you have any questions |
|
28 or suggestions on using Emacs with Octave. |
|
29 |
|
30 @menu |
|
31 * Setting Up Octave Mode:: |
|
32 * Using Octave Mode:: |
|
33 * Running Octave From Within Emacs:: |
|
34 * Using the Emacs Info Reader for Octave:: |
|
35 @end menu |
|
36 |
|
37 @node Setting Up Octave Mode, Using Octave Mode, Emacs, Emacs |
|
38 @section Setting Up Octave Mode |
|
39 |
|
40 If you are lucky, your sysadmins have already arranged everything so |
|
41 that Emacs automatically goes into Octave mode whenever you visit an |
|
42 Octave code file as characterized by its extension @file{.m}. If not, |
|
43 proceed as follows. |
|
44 |
|
45 @enumerate |
|
46 @item |
|
47 Make sure that the file @file{octave.el} (or even better, its |
|
48 byte-compiled version @file{octave.elc}) from the Octave distribution is |
|
49 somewhere in your load-path. |
|
50 |
|
51 @quotation |
|
52 @strong{Note:} The current version of @file{octave.el} was developed, |
|
53 tested and byte-compiled under GNU Emacs 19.31. It may not work under |
|
54 other Emacs versions, in particular under XEmacs. |
|
55 @end quotation |
|
56 |
|
57 @item |
|
58 To begin using Octave mode for all @file{.m} files you visit, add the |
|
59 following lines to a file loaded by Emacs at startup time, typically |
|
60 your @file{~/.emacs} file: |
|
61 |
|
62 @lisp |
|
63 (autoload 'octave-mode "octave" nil t) |
|
64 (setq auto-mode-alist |
|
65 (cons '(\"\\\\.m$\" . octave-mode) auto-mode-alist)) |
|
66 @end lisp |
|
67 |
|
68 @item |
|
69 Finally, to turn on the abbrevs, auto-fill and font-lock features |
|
70 automatically, also add the following lines to one of the Emacs startup |
|
71 files: |
|
72 @lisp |
|
73 (add-hook 'octave-mode-hook |
|
74 (lambda () |
|
75 (abbrev-mode 1) |
|
76 (auto-fill-mode 1) |
|
77 (if (eq window-system 'x) |
|
78 (font-lock-mode 1)))) |
|
79 @end lisp |
|
80 See the Emacs manual for more information about how to customize |
|
81 Font-lock mode. |
|
82 @end enumerate |
|
83 |
|
84 @node Using Octave Mode, Running Octave From Within Emacs, Setting Up Octave Mode, Emacs |
|
85 @section Using Octave Mode |
|
86 |
|
87 In Octave mode, the following special Emacs commands can be used in |
|
88 addition to the standard Emacs commands. |
|
89 |
|
90 @table @kbd |
|
91 @item C-h m |
|
92 Describe the features of Octave mode. |
|
93 |
|
94 @item LFD |
|
95 Reindent the current Octave line, insert a newline and indent the new |
|
96 line (@code{octave-reindent-then-newline-and-indent}). An abbrev before |
|
97 point is expanded if @code{abbrev-mode} is non-@code{nil}. |
|
98 |
|
99 @item TAB |
|
100 Indents current Octave line based on its contents and on previous |
|
101 lines (@code{indent-according-to-mode}). |
|
102 |
|
103 @item ; |
|
104 Insert an ``electric'' semicolon (@code{octave-electric-semi}). If |
|
105 @code{octave-auto-indent} is non-@code{nil}, typing a @samp{;} |
|
106 automatically reindents the current line, inserts a newline and indents |
|
107 the new line. |
|
108 |
|
109 @item ` |
|
110 Start entering an abbreviation (@code{octave-abbrev-start}). If Abbrev |
|
111 mode is turned on, typing @kbd{`C-h} or @kbd{`?} lists all abbrevs. |
|
112 Any other key combination is executed normally. |
|
113 |
|
114 @item M-LFD |
|
115 Break line at point and insert continuation marker and alignment |
|
116 (@code{octave-split-line}). |
|
117 |
|
118 @item M-TAB |
|
119 Perform completion on Octave symbol preceding point, comparing that |
|
120 symbol against Octave's reserved words and builtin variables |
|
121 (@code{octave-complete-symbol}). |
|
122 |
|
123 @item M-C-a |
|
124 Move backward to the beginning of a function |
|
125 (@code{octave-beginning-of-defun}). |
|
126 With prefix argument @var{N}, do it that many times if @var{N} is |
|
127 positive; otherwise, move forward to the @var{N}-th following beginning |
|
128 of a function. |
|
129 |
|
130 @item M-C-e |
|
131 Move forward to the end of a function (@code{octave-end-of-defun}). |
|
132 With prefix argument @var{N}, do it that many times if @var{N} is |
|
133 positive; otherwise, move back to the @var{N}-th preceding end of a |
|
134 function. |
|
135 |
|
136 @item M-C-h |
|
137 Puts point at beginning and mark at the end of the current Octave |
|
138 function, i.e., the one containing point or following point |
|
139 (@code{octave-mark-defun}). |
|
140 |
|
141 @item M-C-q |
|
142 Properly indents the Octave function which contains point |
|
143 (@code{octave-indent-defun}). |
|
144 |
|
145 @item C-c ; |
|
146 Puts the first character of @code{octave-comment-start} (usually |
|
147 @samp{#}) at the beginning of every line in the region |
|
148 (@code{octave-comment-region}). With just @kbd{C-u} prefix argument, |
|
149 uncomment each line in the region. |
|
150 |
|
151 @item C-c : |
|
152 Uncomments every line in the region (@code{octave-uncomment-region}). |
|
153 |
|
154 @item C-c C-p |
|
155 Move one line of Octave code backward, skipping empty and comment lines |
|
156 (@code{octave-previous-code-line}). With numeric prefix argument |
|
157 @var{N}, move that many code lines backward (forward if @var{N} is |
|
158 negative). |
|
159 |
|
160 @item C-c C-n |
|
161 Move one line of Octave code forward, skipping empty and comment lines |
|
162 (@code{octave-next-code-line}). With numeric prefix argument @var{N}, |
|
163 move that many code lines forward (backward if @var{N} is negative). |
|
164 |
|
165 @item C-c C-a |
|
166 Move to the `real' beginning of the current line |
|
167 (@code{octave-beginning-of-line}). If point is in an empty or comment |
|
168 line, simply go to its beginning; otherwise, move backwards to the |
|
169 beginning of the first code line which is not inside a continuation |
|
170 statement, i.e., which does not follow a code line ending in @samp{...} |
|
171 or @samp{\}, or is inside an open parenthesis list. |
|
172 |
|
173 @item C-c C-e |
|
174 Move to the `real' end of the current line (@code{octave-end-of-line}). |
|
175 If point is in a code line, move forward to the end of the first Octave |
|
176 code line which does not end in @samp{...} or @samp{\} or is inside an |
|
177 open parenthesis list. Otherwise, simply go to the end of the current |
|
178 line. |
|
179 |
|
180 @item C-c M-C-n |
|
181 Move forward across one balanced begin-end block of Octave code |
|
182 (@code{octave-forward-block}). With numeric prefix argument @var{N}, |
|
183 move forward across @var{n} such blocks (backward if @var{N} is |
|
184 negative). |
|
185 |
|
186 @item C-c M-C-p |
|
187 Move back across one balanced begin-end block of Octave code |
|
188 (@code{octave-backward-block}). With numeric prefix argument @var{N}, |
|
189 move backward across @var{N} such blocks (forward if @var{N} is |
|
190 negative). |
|
191 |
|
192 @item C-c M-C-d |
|
193 Move forward down one begin-end block level of Octave code |
|
194 (@code{octave-down-block}). With numeric prefix argument, do it that |
|
195 many times; a negative argument means move backward, but still go down |
|
196 one level. |
|
197 |
|
198 @item C-c M-C-u |
|
199 Move backward out of one begin-end block level of Octave code |
|
200 (@code{octave-backward-up-block}). With numeric prefix argument, do it |
|
201 that many times; a negative argument means move forward, but still to a |
|
202 less deep spot. |
|
203 |
|
204 @item C-c M-C-h |
|
205 Put point at the beginning of this block, mark at the end |
|
206 (@code{octave-mark-block}). |
|
207 The block marked is the one that contains point or follows point. |
|
208 |
|
209 @item C-c ] |
|
210 Close the current block on a separate line (@code{octave-close-block}). |
|
211 An error is signaled if no block to close is found. |
|
212 |
|
213 @item C-c f |
|
214 Insert a function skeleton, prompting for the function's name, arguments |
|
215 and return values which have to be entered without parens |
|
216 (@code{octave-insert-defun}). |
|
217 |
|
218 @item C-c C-h |
|
219 Search the function, operator and variable indices of all info files |
|
220 with documentation for Octave for entries (@code{octave-help}). If used |
|
221 interactively, the entry is prompted for with completion. If multiple |
|
222 matches are found, one can cycle through them using the standard |
|
223 @samp{,} (@code{Info-index-next}) command of the Info reader. |
|
224 |
|
225 The variable @code{octave-help-files} is a list of files to search |
|
226 through and defaults to @code{'("octave")}. If there is also an Octave |
|
227 Local Guide with corresponding info file @file{octave-LG} (for example), |
|
228 you can have @code{octave-help} search both files by |
|
229 @lisp |
|
230 (setq octave-help-files '("octave" "octave-LG")) |
|
231 @end lisp |
|
232 @noindent |
|
233 in one of your Emacs startup files. |
|
234 |
|
235 @end table |
|
236 |
|
237 A common problem is that the @key{RET} key does @emph{not} indent the |
|
238 line to where the new text should go after inserting the newline. This |
|
239 is because the standard Emacs convention is that @key{RET} (aka |
|
240 @kbd{C-m}) just adds a newline, whereas @key{LFD} (aka @kbd{C-j}) adds a |
|
241 newline and indents it. This is particularly inconvenient for users with |
|
242 keyboards which do not have a special @key{LFD} key at all; in such |
|
243 cases, it is typically more convenient to use @key{RET} as the @key{LFD} |
|
244 key (rather than typing @kbd{C-j}). |
|
245 |
|
246 You can make @key{RET} do this by adding |
|
247 @lisp |
|
248 (define-key octave-mode-map "\C-m" |
|
249 'octave-reindent-then-newline-and-indent) |
|
250 @end lisp |
|
251 @noindent |
|
252 to one of your Emacs startup files. Another, more generally applicable |
|
253 solution is |
|
254 @lisp |
|
255 (defun RET-behaves-as-LFD () |
|
256 (let ((x (key-binding "\C-j"))) |
|
257 (local-set-key "\C-m" x))) |
|
258 (add-hook 'octave-mode-hook 'return-behaves-as-LFD) |
|
259 @end lisp |
|
260 @noindent |
|
261 (this works for all modes by adding to the startup hooks, without having |
|
262 to know the particular binding of @key{RET} in that mode!). Similar |
|
263 considerations apply for using @key{M-RET} as @key{M-LFD}. As Barry |
|
264 A. Warsaw <bwarsaw@@cnri.reston.va.us> says in the documentation for his |
|
265 @code{cc-mode}, ``This is a very common question. @code{:-)} If you want |
|
266 this to be the default behavior, don't lobby me, lobby RMS!'' |
|
267 |
|
268 The following variables can be used to customize Octave mode. |
|
269 |
|
270 @table @code |
|
271 @item octave-auto-newline |
|
272 Non-@code{nil} means auto-insert a newline and indent after semicolons |
|
273 are typed. The default value is @code{nil}. |
|
274 |
|
275 @item octave-blink-matching-block |
|
276 Non-@code{nil} means show matching begin of block when inserting a space, |
|
277 newline or @samp{;} after an else or end keyword. Default is @code{t}. |
|
278 This is an extremely useful feature for automatically verifying that the |
|
279 keywords match---if they don't, an error message is displayed. |
|
280 |
|
281 @item octave-block-offset |
|
282 Extra indentation applied to statements in block structures. |
|
283 Default is 2. |
|
284 |
|
285 @item octave-comment-column |
|
286 Column to indent right-margin comments to. |
|
287 Default is 32. |
|
288 (Such comments are created using @key{M-;} (@code{indent-for-comment}).) |
|
289 |
|
290 @item octave-comment-start |
|
291 Delimiter inserted to start new comment. |
|
292 Default value is @samp{# }. |
|
293 |
|
294 @item octave-continuation-offset |
|
295 Extra indentation applied to Octave continuation lines. |
|
296 Default is 4. |
|
297 |
|
298 @item octave-continuation-string |
|
299 String used for Octave continuation lines. |
|
300 Normally @samp{\}. |
|
301 |
|
302 @item octave-fill-column |
|
303 Column beyond which automatic line-wrapping should happen. |
|
304 Default is 72. |
|
305 |
|
306 @item octave-inhibit-startup-message |
|
307 If @code{t}, no startup message is displayed when Octave mode is |
|
308 called. |
|
309 Default is @code{nil}. |
|
310 |
|
311 @end table |
|
312 |
|
313 If Font Lock mode is enabled, Octave mode will display |
|
314 @itemize @bullet |
|
315 @item |
|
316 strings in @code{font-lock-string-face} |
|
317 @item |
|
318 comments in @code{font-lock-comment-face} |
|
319 @item |
|
320 the Octave reserved words (such as all block keywords) and the text |
|
321 functions (such as @samp{cd} or @samp{who}) which are also reserved |
|
322 using @code{font-lock-keyword-face} |
|
323 @item |
|
324 the builtin operators (@samp{&&}, @samp{<>}, @dots{}) using |
|
325 @code{font-lock-reference-face} |
|
326 @item |
|
327 the builtin variables (such as @samp{prefer_column_vectors}, @samp{NaN} |
|
328 or @samp{LOADPATH}) in @code{font-lock-variable-name-face} |
|
329 @item |
|
330 and the function names in function declarations in |
|
331 @code{font-lock-function-name-face}. |
|
332 @end itemize |
|
333 |
|
334 There is also rudimentary support for Imenu (currently, function names |
|
335 can be indexed). |
|
336 |
|
337 Customization of Octave mode can be performed by modification of the |
|
338 variable @code{octave-mode-hook}. It the value of this variable is |
|
339 non-@code{nil}, turning on Octave mode calls its value. |
|
340 |
|
341 If you discover a problem with Octave mode, you can conveniently send a |
|
342 bug report using @kbd{C-c C-b} (@code{octave-submit-bug-report}). This |
|
343 automatically sets up a mail buffer with version information already |
|
344 added. You just need to add a description of the problem, including a |
|
345 reproducible test case and send the message. |
|
346 |
|
347 @node Running Octave From Within Emacs, Using the Emacs Info Reader for Octave, Using Octave Mode, Emacs |
|
348 @section Running Octave From Within Emacs |
|
349 |
|
350 The package @file{octave} provides commands for running an inferior |
|
351 Octave process in a special Emacs buffer. Use |
|
352 @lisp |
|
353 M-x run-octave |
|
354 @end lisp |
|
355 @noindent |
|
356 to directly start an inferior Octave process. If Emacs does not know |
|
357 about this command, add the line |
|
358 @lisp |
|
359 (autoload 'run-octave "octave" nil t) |
|
360 @end lisp |
|
361 @noindent |
|
362 to your @file{.emacs} file. |
|
363 |
|
364 This will start Octave in a special buffer the name of which is |
|
365 specified by the variable @code{inferior-octave-buffer} and defaults to |
|
366 @code{"*Octave Interaction*"}. From within this buffer, you can |
|
367 interact with the inferior Octave process `as usual', i.e., by entering |
|
368 Octave commands at the prompt. |
|
369 |
|
370 You can also communicate with an inferior Octave process from within |
|
371 files with Octave code (i.e., buffers in Octave mode), using the |
|
372 following commands. |
|
373 |
|
374 @table @kbd |
|
375 @item C-c i l |
|
376 Send the current line to the inferior Octave process |
|
377 (@code{octave-send-line}). |
|
378 With positive prefix argument @var{N}, send that many lines. |
|
379 If @code{octave-send-line-auto-forward} is non-@code{nil}, go to the |
|
380 next unsent code line. |
|
381 @item C-c i b |
|
382 Send the current block to the inferior Octave process |
|
383 (@code{octave-send-block}). |
|
384 @item C-c i f |
|
385 Send the current function to the inferior Octave process |
|
386 (@code{octave-send-defun}). |
|
387 @item C-c i r |
|
388 Send the region to the inferior Octave process |
|
389 (@code{octave-send-region}). |
|
390 @item C-c i s |
|
391 Make sure that `inferior-octave-buffer' is displayed |
|
392 (@code{octave-show-process-buffer}). |
|
393 @item C-c i h |
|
394 Delete all windows that display @file{inferior-octave-buffer} |
|
395 (@code{octave-hide-process-buffer}). |
|
396 @item C-c i k |
|
397 Kill the inferior Octave process and its buffer |
|
398 (@code{octave-kill-process}). |
|
399 @end table |
|
400 |
|
401 The effect of the commands which send code to the Octave process can be |
|
402 customized by the following variables. |
|
403 @table @code |
|
404 @item octave-send-echo-input |
|
405 Non-@code{nil} means echo input sent to the inferior Octave process. |
|
406 Default is @code{t}. |
|
407 |
|
408 @item octave-send-show-buffer |
|
409 Non-@code{nil} means display the buffer running the Octave process after |
|
410 sending a command (but without selecting it). |
|
411 Default is @code{t}. |
|
412 @end table |
|
413 |
|
414 If you send code and there is no inferior Octave process yet, it will be |
|
415 started automatically. |
|
416 |
|
417 The startup of the inferior Octave process is highly customizable. |
|
418 The variable @code{inferior-octave-startup-args} can be used for |
|
419 specifying command lines arguments to be passed to Octave on startup |
|
420 as a list of strings. For example, to suppress the startup message and |
|
421 use `traditional' mode, set this to @code{'("-q" "--traditional")}. |
|
422 You can also specify a startup file of Octave commands to be loaded on |
|
423 startup; note that these commands will not produce any visible output |
|
424 in the process buffer. Which file to use is controlled by the variable |
|
425 @code{inferior-octave-startup-file}. If this is @code{nil}, the file |
|
426 @file{~/.emacs_octave} is used if it exists. |
|
427 |
|
428 And finally, @code{inferior-octave-mode-hook} is run after starting the |
|
429 process and putting its buffer into Inferior Octave mode. Hence, if you |
|
430 like the up and down arrow keys to behave in the interaction buffer as |
|
431 in the shell, and you want this buffer to use nice colors, add |
|
432 @lisp |
|
433 (add-hook 'inferior-octave-mode-hook |
|
434 (lambda () |
|
435 (turn-on-font-lock) |
|
436 (define-key inferior-octave-mode-map [up] |
|
437 'comint-previous-input) |
|
438 (define-key inferior-octave-mode-map [down] |
|
439 'comint-next-input))) |
|
440 @end lisp |
|
441 @noindent |
|
442 to your @file{.emacs} file. You could also swap the roles of @kbd{C-a} |
|
443 (@code{beginning-of-line}) and @code{C-c C-a} (@code{comint-bol}) using |
|
444 this hook. |
|
445 |
|
446 @quotation |
|
447 @strong{Note:} |
|
448 If you set your Octave prompts to something different from the defaults, |
|
449 make sure that @code{inferior-octave-prompt} matches them. |
|
450 Otherwise, @emph{nothing} will work, because Emacs will have no idea |
|
451 when Octave is waiting for input, or done sending output. |
|
452 @end quotation |
|
453 |
|
454 @node Using the Emacs Info Reader for Octave, , Running Octave From Within Emacs, Emacs |
|
455 @section Using the Emacs Info Reader for Octave |
|
456 |
|
457 You can also set up the Emacs Info reader for dealing with the results |
|
458 of Octave's @samp{help -i}. For this, the package @file{gnuserv} needs |
|
459 to be installed, which unfortunately still does not come with GNU Emacs |
|
460 (it does with XEmacs). It can be retrieved from any GNU Emacs Lisp Code |
|
461 Directory archive, e.g.@: |
|
462 @file{ftp://ftp.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive}, |
|
463 in the @file{packages} subdirectory. There is also a newer version |
|
464 around (use archie to look for @file{gnuserv-2.1alpha.tar.gz}). |
|
465 |
|
466 If @file{gnuserv} is installed, add the lines |
|
467 @lisp |
|
468 (autoload 'octave-help "octave" nil t) |
|
469 (require 'gnuserv) |
|
470 (gnuserv-start) |
|
471 @end lisp |
|
472 @noindent |
|
473 to your @file{.emacs} file. |
|
474 |
|
475 You can use either `plain' Emacs Info or the function @code{octave-help} |
|
476 as your Octave info reader (for @samp{help -i}). In the former case, |
|
477 set the Octave variable @code{INFO_PROGRAM} to @code{"info-emacs-info"}. |
|
478 The latter is perhaps more attractive because it allows to look up keys |
|
479 in the indices of @emph{several} info files related to Octave (provided |
|
480 that the Emacs variable @code{octave-help-files} is set correctly). In |
|
481 this case, set @code{INFO_PROGRAM} to @code{"info-emacs-octave-help"}. |
|
482 |
|
483 If you use Octave from within Emacs, these settings are best done in the |
|
484 @file{~/.emacs_octave} startup file (or the file pointed to by the Emacs |
|
485 variable @code{inferior-octave-startup-file}). |
|
486 |
|
487 @c Local Variables: |
|
488 @c TeX-command-default: "Texinfo" |
|
489 @c End: |