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