all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
blob 2efe9f9d1c4321fcd67911dcf4b295b816d5a9cc 15588 bytes (raw)
name: doc/misc/octave-mode.texi 	 # note: path name is non-authoritative(*)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
 
\input texinfo                  @c -*-texinfo-*-
@c %**start of header
@setfilename ../../info/octave-mode
@settitle Octave Mode
@c %**end of header

@copying
Copyright @copyright{} 1996--2013 Free Software Foundation, Inc.

@quotation
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.''
@end quotation
@end copying

@dircategory Emacs editing modes
@direntry
* Octave mode: (octave-mode).         Emacs mode for editing GNU Octave files.
@end direntry

@finalout

@titlepage
@title Octave Mode
@subtitle An Emacs mode for programming in GNU Octave

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Octave Mode

@insertcopying
@end ifnottex

@menu
* Overview::
* Using Octave Mode::
* Running Octave from Within Emacs::
* GNU Free Documentation License::
* Key Index::
* Variable Index::
* Lisp Function Index::
* Concept Index::
@end menu

@node Overview
@chapter 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.

@node Using Octave Mode
@chapter Using Octave Mode
@cindex Using Octave Mode

In Octave mode, the following special Emacs commands can be used in
addition to the standard Emacs commands.

@table @kbd
@item C-M-j
@kindex C-M-j
@findex octave-indent-new-comment-line
@vindex octave-continuation-string
Break Octave line at point, continuing comment if within one.  Insert
@code{octave-continuation-string} before breaking the line unless
inside a list.  Signal an error if within a single-quoted string.

@item C-c ;
@kindex C-c ;
@findex octave-update-function-file-comment
Query replace function names in function file comment.

@item C-c C-p
@kindex C-c C-p
@findex 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
@var{n} is negative).

@item C-c C-n
@kindex C-c C-n
@findex 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).

@item C-c C-a
@kindex C-c C-a
@findex 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
@samp{...}  or @samp{\}, or is inside an open parenthesis list.

@item C-c C-e
@kindex C-c C-e
@findex 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.

@item C-c M-C-h
@kindex C-c M-C-h
@findex 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.

@item C-c ]
@kindex 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.

@item C-c C-f
@kindex C-c C-f
@findex 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}).
@noindent
in one of your Emacs startup files.
@end 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
@kbd{C-m}) 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
@lisp
(define-key octave-mode-map "\C-m"
  'octave-reindent-then-newline-and-indent)
@end lisp
@noindent
to one of your Emacs startup files.  Another, more generally applicable
solution is
@lisp
(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)
@end lisp
@noindent
(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
@email{bwarsaw@@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.

@vtable @code
@item octave-blink-matching-block
Non-@code{nil} 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.

@item octave-block-offset
Extra indentation applied to statements in block structures.
Default is 2.

@item octave-continuation-offset
Extra indentation applied to Octave continuation lines.
Default is 4.

@item octave-font-lock-texinfo-comment
Highlight texinfo comment blocks.  The default value is @code{t}.
@end vtable

If Font Lock mode is enabled, Octave mode will display

@itemize @bullet
@item
strings in @code{font-lock-string-face}

@item
comments in @code{font-lock-comment-face}

@item
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}

@item
the built-in operators (@samp{&&}, @samp{==}, @dots{}) using
@code{font-lock-reference-face}

@item
and the function names in function declarations in
@code{font-lock-function-name-face}.

@item
Function comments blocks in @code{octave-function-comment-block}
@end itemize

@cindex Imenu Support
There is also rudimentary support for Imenu (@pxref{Imenu,,, emacs,
The GNU Emacs Manual}).  Currently, function names can be indexed.

@cindex ElDoc Mode Support
@vindex 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.

@c @cindex TAGS
@c @cindex Emacs TAGS files
@c @cindex @file{octave-tags}
@c You can generate TAGS files for Emacs from Octave @file{.m} files using
@c the shell script @file{octave-tags} that is installed alongside your copy of
@c Octave.
@c
@vindex octave-mode-hook
Customization of Octave mode can be performed by modification of the
variable @code{octave-mode-hook}.

@node Running Octave from Within Emacs
@chapter Running Octave from Within Emacs
@cindex Inferior Octave Mode

Octave mode provides commands for running an inferior
Octave process in a special Emacs buffer.  Use
@lisp
M-x run-octave
@end lisp
@noindent
to directly start an inferior Octave process.

@vindex 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
@kbd{C-h 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.

@table @kbd
@item C-c C-i l
@kindex C-c C-i l
@findex octave-send-line
@vindex 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
non-@code{nil}, go to the next unsent code line.

@item C-c C-i b
@kindex C-c C-i b
@findex octave-send-block
Send the current block to the inferior Octave process
(@code{octave-send-block}).

@item C-c C-i f
@kindex C-c C-i f
@findex octave-send-defun
Send the current function to the inferior Octave process
(@code{octave-send-defun}).

@item C-c C-i r
@kindex C-c C-i r
@findex octave-send-region
Send the region to the inferior Octave process
(@code{octave-send-region}).

@item C-c C-i a
@kindex C-c C-i a
@findex 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.

@item C-c C-i s
@kindex C-c C-i s
@findex octave-show-process-buffer
Make sure that `inferior-octave-buffer' is displayed
(@code{octave-show-process-buffer}).

@item C-c C-i q
@kindex C-c C-i q
@findex octave-hide-process-buffer
Delete all windows that display the inferior Octave buffer
(@code{octave-hide-process-buffer}).

@item C-c C-i k
@kindex C-c C-i k
@findex octave-kill-process
Kill the inferior Octave process and its buffer
(@code{octave-kill-process}).

@item C-c C-l
@kindex C-c C-l
@findex octave-source-file
Parse and execute the current file in the inferior Octave buffer
(@code{octave-source-file}).  This is done using Octave's
@code{source} function.

@item M-.
@kindex M-.
@findex octave-find-definition
@vindex 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}).

@item C-h d
@kindex C-h d
@findex octave-help
@vindex octave-help-buffer
Display the documentation for function (@code{octave-help}).  The
buffer name can be changed by customizing @code{octave-help-buffer}.

@item C-h a
@kindex C-h a
@findex 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.

@end table

The effect of the commands which send code to the Octave process can be
customized by the following variables.

@vtable @code
@item octave-send-echo-input
Non-@code{nil} means echo input sent to the inferior Octave process.
Default is @code{t}.

@item octave-send-show-buffer
Non-@code{nil} means display the buffer running the Octave process after
sending a command (but without selecting it).
Default is @code{t}.
@end vtable

If you send code and there is no inferior Octave process yet, it will
be started automatically.

@vindex 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
@file{~/.emacs-octave} or if this file is not found
@file{~/.emacs.d/init_octave.m}.

@vindex 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
@code{comint-prompt-read-only}.

@vindex 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
@lisp
(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)))
@end lisp
@noindent
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.

@vindex inferior-octave-prompt
@quotation
@strong{Note} 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.
@end quotation

@node GNU Free Documentation License
@chapter GNU Free Documentation License
@include doclicense.texi

@node Key Index
@unnumbered Key Index

@printindex ky

@node Variable Index
@unnumbered Variable Index

@printindex vr

@node Lisp Function Index
@unnumbered Function Index

@printindex fn

@node Concept Index
@unnumbered Concept Index

@printindex cp


@bye

@c TODO Update

@c @node Using the Emacs Info Reader for Octave
@c @chapter Using the Emacs Info Reader for Octave

@c You may also use the Emacs Info reader with Octave's @code{doc} function.

@c If @file{gnuserv} is installed, add the lines
@c @lisp
@c (autoload 'octave-help "octave-hlp" nil t)
@c (require 'gnuserv)
@c (gnuserv-start)
@c @end lisp
@c @noindent
@c to your @file{.emacs} file.

@c You can use either `plain' Emacs Info or the function @code{octave-help}
@c as your Octave info reader (for @samp{help -i}).  In the former case,
@c use @code{info_program ("info-emacs-info")}.
@c The latter is perhaps more attractive because it allows to look up keys
@c in the indices of @emph{several} info files related to Octave (provided
@c that the Emacs variable @code{octave-help-files} is set correctly).  In
@c this case, use @code{info_program ("info-emacs-octave-help")}.

@c If you use Octave from within Emacs, it is best to add these settings to
@c your @file{~/.emacs-octave} startup file (or the file pointed to by the
@c Emacs variable @code{inferior-octave-startup-file}).

debug log:

solving 2efe9f9 ...
found 2efe9f9 in https://git.savannah.gnu.org/cgit/emacs.git

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.