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