|
2670
|
1 @c Copyright (C) 1996, 1997 John W. Eaton |
|
2333
|
2 @c This is part of the Octave manual. |
|
|
3 @c For copying conditions, see the file gpl.texi. |
|
|
4 |
|
2670
|
5 @node Introduction, Getting Started, Preface, Top |
|
2333
|
6 @chapter A Brief Introduction to Octave |
|
|
7 @cindex introduction |
|
|
8 |
|
2993
|
9 This manual documents how to run, install and port GNU Octave, and how |
|
|
10 to report bugs. |
|
2333
|
11 |
|
2993
|
12 GNU Octave is a high-level language, primarily intended for numerical |
|
2333
|
13 computations. It provides a convenient command line interface for |
|
|
14 solving linear and nonlinear problems numerically, and for performing |
|
|
15 other numerical experiments. It may also be used as a batch-oriented |
|
|
16 language. |
|
|
17 |
|
2993
|
18 GNU Octave is also freely redistributable software. You may |
|
|
19 redistribute it and/or modify it under the terms of the GNU General |
|
|
20 Public License as published by the Free Software Foundation. The GPL is |
|
|
21 included in this manual in @ref{Copying}. |
|
2449
|
22 |
|
2333
|
23 This document corresponds to Octave version @value{VERSION}. |
|
|
24 |
|
|
25 @c XXX FIXME XXX -- add explanation about how and why Octave was written. |
|
|
26 @c |
|
|
27 @c XXX FIXME XXX -- add a sentence or two explaining that we could |
|
|
28 @c always use more funding. |
|
|
29 |
|
|
30 @menu |
|
|
31 * Running Octave:: |
|
|
32 * Simple Examples:: |
|
2653
|
33 * Conventions:: |
|
2333
|
34 @end menu |
|
|
35 |
|
|
36 @node Running Octave, Simple Examples, Introduction, Introduction |
|
|
37 @section Running Octave |
|
|
38 |
|
|
39 On most systems, the way to invoke Octave is with the shell command |
|
2993
|
40 @samp{octave}. Octave displays an initial message and then a prompt |
|
2333
|
41 indicating it is ready to accept input. You can begin typing Octave |
|
|
42 commands immediately afterward. |
|
|
43 |
|
|
44 If you get into trouble, you can usually interrupt Octave by typing |
|
|
45 @kbd{Control-C} (usually written @kbd{C-c} for short). @kbd{C-c} gets |
|
2670
|
46 its name from the fact that you type it by holding down @key{CTRL} and |
|
|
47 then pressing @key{c}. Doing this will normally return you to Octave's |
|
|
48 prompt. |
|
2333
|
49 |
|
2449
|
50 @cindex exiting octave |
|
|
51 @cindex quitting octave |
|
2689
|
52 To exit Octave, type @kbd{quit}, or @kbd{exit} at the Octave prompt. |
|
2333
|
53 |
|
|
54 On systems that support job control, you can suspend Octave by sending |
|
|
55 it a @code{SIGTSTP} signal, usually by typing @kbd{C-z}. |
|
|
56 |
|
2653
|
57 @node Simple Examples, Conventions, Running Octave, Introduction |
|
2333
|
58 @section Simple Examples |
|
|
59 |
|
|
60 The following chapters describe all of Octave's features in detail, but |
|
|
61 before doing that, it might be helpful to give a sampling of some of its |
|
|
62 capabilities. |
|
|
63 |
|
|
64 If you are new to Octave, I recommend that you try these examples to |
|
|
65 begin learning Octave by using it. Lines marked with @samp{octave:13>} |
|
|
66 are lines you type, ending each with a carriage return. Octave will |
|
|
67 respond with an answer, or by displaying a graph. |
|
|
68 |
|
|
69 @unnumberedsubsec Creating a Matrix |
|
|
70 |
|
|
71 To create a new matrix and store it in a variable so that it you can |
|
|
72 refer to it later, type the command |
|
|
73 |
|
|
74 @example |
|
|
75 octave:1> a = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ] |
|
|
76 @end example |
|
|
77 |
|
|
78 @noindent |
|
|
79 Octave will respond by printing the matrix in neatly aligned columns. |
|
|
80 Ending a command with a semicolon tells Octave to not print the result |
|
|
81 of a command. For example |
|
|
82 |
|
|
83 @example |
|
|
84 octave:2> b = rand (3, 2); |
|
|
85 @end example |
|
|
86 |
|
|
87 @noindent |
|
|
88 will create a 3 row, 2 column matrix with each element set to a random |
|
|
89 value between zero and one. |
|
|
90 |
|
|
91 To display the value of any variable, simply type the name of the |
|
|
92 variable. For example, to display the value stored in the matrix |
|
2689
|
93 @code{b}, type the command |
|
2333
|
94 |
|
|
95 @example |
|
|
96 octave:3> b |
|
|
97 @end example |
|
|
98 |
|
|
99 @unnumberedsubsec Matrix Arithmetic |
|
|
100 |
|
|
101 Octave has a convenient operator notation for performing matrix |
|
2689
|
102 arithmetic. For example, to multiply the matrix @code{a} by a scalar |
|
2333
|
103 value, type the command |
|
|
104 |
|
|
105 @example |
|
|
106 octave:4> 2 * a |
|
|
107 @end example |
|
|
108 |
|
2689
|
109 To multiply the two matrices @code{a} and @code{b}, type the command |
|
2333
|
110 |
|
|
111 @example |
|
|
112 octave:5> a * b |
|
|
113 @end example |
|
|
114 |
|
|
115 To form the matrix product |
|
|
116 @iftex |
|
|
117 @tex |
|
2689
|
118 $@code{a}^T@code{a}$, |
|
2333
|
119 @end tex |
|
|
120 @end iftex |
|
|
121 @ifinfo |
|
2689
|
122 @code{transpose (a) * a}, |
|
2333
|
123 @end ifinfo |
|
|
124 type the command |
|
|
125 |
|
|
126 @example |
|
|
127 octave:6> a' * a |
|
|
128 @end example |
|
|
129 |
|
|
130 @unnumberedsubsec Solving Linear Equations |
|
|
131 |
|
2689
|
132 To solve the set of linear equations @code{a@var{x} = b}, |
|
2333
|
133 use the left division operator, @samp{\}: |
|
|
134 |
|
|
135 @example |
|
|
136 octave:7> a \ b |
|
|
137 @end example |
|
|
138 |
|
|
139 @noindent |
|
|
140 This is conceptually equivalent to |
|
|
141 @iftex |
|
|
142 @tex |
|
2689
|
143 $@code{a}^{-1}@code{b}$, |
|
2333
|
144 @end tex |
|
|
145 @end iftex |
|
|
146 @ifinfo |
|
2689
|
147 @code{inv (a) * b}, |
|
2333
|
148 @end ifinfo |
|
|
149 but avoids computing the inverse of a matrix directly. |
|
|
150 |
|
|
151 If the coefficient matrix is singular, Octave will print a warning |
|
|
152 message and compute a minimum norm solution. |
|
|
153 |
|
|
154 @unnumberedsubsec Integrating Differential Equations |
|
|
155 |
|
|
156 Octave has built-in functions for solving nonlinear differential |
|
|
157 equations of the form |
|
|
158 @iftex |
|
|
159 @tex |
|
|
160 $$ |
|
2689
|
161 {dx \over dt} = f(x,t), \qquad x(t=t_0) = x_0 |
|
2333
|
162 $$ |
|
|
163 @end tex |
|
|
164 @end iftex |
|
|
165 @ifinfo |
|
|
166 |
|
|
167 @example |
|
2449
|
168 @group |
|
2333
|
169 dx |
|
|
170 -- = f (x, t) |
|
|
171 dt |
|
2449
|
172 @end group |
|
2333
|
173 @end example |
|
|
174 |
|
|
175 @noindent |
|
|
176 with the initial condition |
|
|
177 |
|
|
178 @example |
|
|
179 x(t = t0) = x0 |
|
|
180 @end example |
|
|
181 @end ifinfo |
|
|
182 |
|
|
183 @noindent |
|
|
184 For Octave to integrate equations of this form, you must first provide a |
|
|
185 definition of the function |
|
|
186 @iftex |
|
|
187 @tex |
|
|
188 $f (x, t)$. |
|
|
189 @end tex |
|
|
190 @end iftex |
|
|
191 @ifinfo |
|
|
192 @code{f(x,t)}. |
|
|
193 @end ifinfo |
|
|
194 This is straightforward, and may be accomplished by entering the |
|
|
195 function body directly on the command line. For example, the following |
|
|
196 commands define the right hand side function for an interesting pair of |
|
|
197 nonlinear differential equations. Note that while you are entering a |
|
|
198 function, Octave responds with a different prompt, to indicate that it |
|
|
199 is waiting for you to complete your input. |
|
|
200 |
|
|
201 @example |
|
2449
|
202 @group |
|
2333
|
203 octave:8> function xdot = f (x, t) |
|
|
204 > |
|
|
205 > r = 0.25; |
|
|
206 > k = 1.4; |
|
|
207 > a = 1.5; |
|
|
208 > b = 0.16; |
|
|
209 > c = 0.9; |
|
|
210 > d = 0.8; |
|
|
211 > |
|
|
212 > xdot(1) = r*x(1)*(1 - x(1)/k) - a*x(1)*x(2)/(1 + b*x(1)); |
|
|
213 > xdot(2) = c*a*x(1)*x(2)/(1 + b*x(1)) - d*x(2); |
|
|
214 > |
|
|
215 > endfunction |
|
2449
|
216 @end group |
|
2333
|
217 @end example |
|
|
218 |
|
|
219 @noindent |
|
|
220 Given the initial condition |
|
|
221 |
|
|
222 @example |
|
|
223 x0 = [1; 2]; |
|
|
224 @end example |
|
|
225 |
|
|
226 @noindent |
|
|
227 and the set of output times as a column vector (note that the first |
|
|
228 output time corresponds to the initial condition given above) |
|
|
229 |
|
|
230 @example |
|
|
231 t = linspace (0, 50, 200)'; |
|
|
232 @end example |
|
|
233 |
|
|
234 @noindent |
|
|
235 it is easy to integrate the set of differential equations: |
|
|
236 |
|
|
237 @example |
|
|
238 x = lsode ("f", x0, t); |
|
|
239 @end example |
|
|
240 |
|
|
241 @noindent |
|
2689
|
242 The function @code{lsode} uses the Livermore Solver for Ordinary |
|
2333
|
243 Differential Equations, described in A. C. Hindmarsh, @cite{ODEPACK, a |
|
|
244 Systematized Collection of ODE Solvers}, in: Scientific Computing, R. S. |
|
|
245 Stepleman et al. (Eds.), North-Holland, Amsterdam, 1983, pages 55--64. |
|
|
246 |
|
|
247 @unnumberedsubsec Producing Graphical Output |
|
|
248 |
|
|
249 To display the solution of the previous example graphically, use the |
|
|
250 command |
|
|
251 |
|
|
252 @example |
|
|
253 plot (t, x) |
|
|
254 @end example |
|
|
255 |
|
|
256 If you are using the X Window System, Octave will automatically create |
|
|
257 a separate window to display the plot. If you are using a terminal that |
|
|
258 supports some other graphics commands, you will need to tell Octave what |
|
|
259 kind of terminal you have. Type the command |
|
|
260 |
|
|
261 @example |
|
2689
|
262 gset term |
|
2333
|
263 @end example |
|
|
264 |
|
|
265 @noindent |
|
|
266 to see a list of the supported terminal types. Octave uses |
|
|
267 @code{gnuplot} to display graphics, and can display graphics on any |
|
|
268 terminal that is supported by @code{gnuplot}. |
|
|
269 |
|
|
270 To capture the output of the plot command in a file rather than sending |
|
|
271 the output directly to your terminal, you can use a set of commands like |
|
|
272 this |
|
|
273 |
|
|
274 @example |
|
|
275 @group |
|
2689
|
276 gset term postscript |
|
|
277 gset output "foo.ps" |
|
2333
|
278 replot |
|
|
279 @end group |
|
|
280 @end example |
|
|
281 |
|
|
282 @noindent |
|
|
283 This will work for other types of output devices as well. Octave's |
|
2689
|
284 @code{gset} command is really just piped to the @code{gnuplot} |
|
2333
|
285 subprocess, so that once you have a plot on the screen that you like, |
|
|
286 you should be able to do something like this to create an output file |
|
|
287 suitable for your graphics printer. |
|
|
288 |
|
|
289 Or, you can eliminate the intermediate file by using commands like this |
|
|
290 |
|
|
291 @example |
|
|
292 @group |
|
2689
|
293 gset term postscript |
|
|
294 gset output "|lpr -Pname_of_your_graphics_printer" |
|
2333
|
295 replot |
|
|
296 @end group |
|
|
297 @end example |
|
|
298 |
|
|
299 @unnumberedsubsec Editing What You Have Typed |
|
|
300 |
|
|
301 At the Octave prompt, you can recall, edit, and reissue previous |
|
|
302 commands using Emacs- or vi-style editing commands. The default |
|
|
303 keybindings use Emacs-style commands. For example, to recall the |
|
2670
|
304 previous command, type @kbd{Control-p} (usually written @kbd{C-p} for |
|
|
305 short). @kbd{C-p} gets its name from the fact that you type it by |
|
|
306 holding down @key{CTRL} and then pressing @key{p}. Doing this will |
|
|
307 normally bring back the previous line of input. @kbd{C-n} will bring up |
|
|
308 the next line of input, @kbd{C-b} will move the cursor backward on the |
|
|
309 line, @kbd{C-f} will move the cursor forward on the line, etc. |
|
2333
|
310 |
|
|
311 A complete description of the command line editing capability is given |
|
|
312 in this manual in @ref{Command Line Editing}. |
|
|
313 |
|
|
314 @unnumberedsubsec Getting Help |
|
|
315 |
|
|
316 Octave has an extensive help facility. The same documentation that is |
|
|
317 available in printed form is also available from the Octave prompt, |
|
|
318 because both forms of the documentation are created from the same input |
|
|
319 file. |
|
|
320 |
|
|
321 In order to get good help you first need to know the name of the command |
|
|
322 that you want to use. This name of the function may not always be |
|
|
323 obvious, but a good place to start is to just type @code{help}. |
|
|
324 This will show you all the operators, reserved words, functions, |
|
|
325 built-in variables, and function files. You can then get more |
|
|
326 help on anything that is listed by simply including the name as an |
|
|
327 argument to help. For example, |
|
|
328 |
|
|
329 @example |
|
|
330 help plot |
|
|
331 @end example |
|
|
332 |
|
|
333 @noindent |
|
|
334 will display the help text for the @code{plot} function. |
|
|
335 |
|
|
336 Octave sends output that is too long to fit on one screen through a |
|
2689
|
337 pager like @code{less} or @code{more}. Type a @key{RET} to advance one |
|
|
338 line, a @key{SPC} to advance one page, and @key{q} to exit the pager. |
|
2333
|
339 |
|
|
340 The part of Octave's help facility that allows you to read the complete |
|
2653
|
341 text of the printed manual from within Octave normally uses a separate |
|
|
342 program called Info. When you invoke Info you will be put into a menu |
|
|
343 driven program that contains the entire Octave manual. Help for using |
|
2670
|
344 Info is provided in this manual in @ref{Getting Help}. |
|
2333
|
345 |
|
2653
|
346 @node Conventions, , Simple Examples, Introduction |
|
|
347 @section Conventions |
|
2333
|
348 |
|
2653
|
349 This section explains the notational conventions that are used in this |
|
|
350 manual. You may want to skip this section and refer back to it later. |
|
2333
|
351 |
|
2653
|
352 @menu |
|
|
353 * Fonts:: |
|
|
354 * Evaluation Notation:: |
|
|
355 * Printing Notation:: |
|
|
356 * Error Messages:: |
|
|
357 * Format of Descriptions:: |
|
|
358 @end menu |
|
2333
|
359 |
|
2653
|
360 @node Fonts, Evaluation Notation, Conventions, Conventions |
|
|
361 @subsection Fonts |
|
|
362 @cindex fonts |
|
2333
|
363 |
|
2653
|
364 Examples of Octave code appear in this font or form: @code{svd (a)}. |
|
|
365 Names that represent arguments or metasyntactic variables appear |
|
2993
|
366 in this font or form: @var{first-number}. Commands that you type at the |
|
|
367 shell prompt sometimes appear in this font or form: |
|
|
368 @samp{octave --no-init-file}. Commands that you type at the Octave |
|
|
369 prompt sometimes appear in this font or form: @kbd{foo --bar --baz}. |
|
|
370 Specific keys on your keyboard appear in this font or form: @key{ANY}. |
|
2759
|
371 @cindex any key |
|
2333
|
372 |
|
2653
|
373 @node Evaluation Notation, Printing Notation, Fonts, Conventions |
|
|
374 @subsection Evaluation Notation |
|
|
375 @cindex evaluation notation |
|
|
376 @cindex documentation notation |
|
|
377 |
|
|
378 In the examples in this manual, results from expressions that you |
|
|
379 evaluate are indicated with @samp{@result{}}. For example, |
|
2333
|
380 |
|
|
381 @example |
|
2653
|
382 @group |
|
|
383 sqrt (2) |
|
|
384 @result{} 1.4142 |
|
|
385 @end group |
|
2333
|
386 @end example |
|
|
387 |
|
|
388 @noindent |
|
2653
|
389 You can read this as ``@code{sqrt (2)} evaluates to 1.4142''. |
|
2333
|
390 |
|
2653
|
391 In some cases, matrix values that are returned by expressions are |
|
|
392 displayed like this |
|
2449
|
393 |
|
|
394 @example |
|
|
395 @group |
|
2653
|
396 [1, 2; 3, 4] == [1, 3; 2, 4] |
|
|
397 @result{} [ 1, 0; 0, 1 ] |
|
|
398 @end group |
|
|
399 @end example |
|
2449
|
400 |
|
2653
|
401 @noindent |
|
|
402 and in other cases, they are displayed like this |
|
|
403 |
|
|
404 @example |
|
|
405 @group |
|
|
406 eye (3) |
|
|
407 @result{} 1 0 0 |
|
|
408 0 1 0 |
|
|
409 0 0 1 |
|
2449
|
410 @end group |
|
|
411 @end example |
|
|
412 |
|
|
413 @noindent |
|
2653
|
414 in order to clearly show the structure of the result. |
|
|
415 |
|
|
416 Sometimes to help describe one expression, another expression is |
|
|
417 shown that produces identical results. The exact equivalence of |
|
|
418 expressions is indicated with @samp{@equiv{}}. For example, |
|
2449
|
419 |
|
|
420 @example |
|
2653
|
421 @group |
|
|
422 rot90 ([1, 2; 3, 4], -1) |
|
|
423 @equiv{} |
|
|
424 rot90 ([1, 2; 3, 4], 3) |
|
|
425 @equiv{} |
|
|
426 rot90 ([1, 2; 3, 4], 7) |
|
|
427 @end group |
|
2449
|
428 @end example |
|
|
429 |
|
2653
|
430 @node Printing Notation, Error Messages, Evaluation Notation, Conventions |
|
|
431 @subsection Printing Notation |
|
|
432 @cindex printing notation |
|
|
433 |
|
|
434 Many of the examples in this manual print text when they are |
|
|
435 evaluated. Examples in this manual indicate printed text with |
|
|
436 @samp{@print{}}. The value that is returned by evaluating the |
|
|
437 expression (here @code{1}) is displayed with @samp{@result{}} and |
|
|
438 follows on a separate line. |
|
2449
|
439 |
|
|
440 @example |
|
2653
|
441 @group |
|
|
442 printf ("foo %s\n", "bar") |
|
|
443 @print{} foo bar |
|
|
444 @result{} 1 |
|
|
445 @end group |
|
|
446 @end example |
|
|
447 |
|
|
448 @node Error Messages, Format of Descriptions, Printing Notation, Conventions |
|
|
449 @subsection Error Messages |
|
|
450 @cindex error message notation |
|
|
451 |
|
|
452 Some examples signal errors. This normally displays an error message |
|
|
453 on your terminal. Error messages are shown on a line starting with |
|
2670
|
454 @code{error:}. |
|
2653
|
455 |
|
|
456 @example |
|
2670
|
457 @group |
|
2653
|
458 struct_elements ([1, 2; 3, 4]) |
|
2670
|
459 error: struct_elements: wrong type argument `matrix' |
|
|
460 @end group |
|
2449
|
461 @end example |
|
|
462 |
|
2653
|
463 @node Format of Descriptions, , Error Messages, Conventions |
|
|
464 @subsection Format of Descriptions |
|
|
465 @cindex description format |
|
|
466 |
|
|
467 Functions, commands, and variables are described in this manual in a |
|
|
468 uniform format. The first line of a description contains the name of |
|
|
469 the item followed by its arguments, if any. |
|
|
470 @ifinfo |
|
|
471 The category---function, variable, or whatever---appears at the |
|
|
472 beginning of the line. |
|
|
473 @end ifinfo |
|
|
474 @iftex |
|
|
475 The category---function, variable, or whatever---is printed next to the |
|
|
476 right margin. |
|
|
477 @end iftex |
|
|
478 The description follows on succeeding lines, sometimes with examples. |
|
2449
|
479 |
|
2653
|
480 @menu |
|
|
481 * A Sample Function Description:: |
|
|
482 * A Sample Command Description:: |
|
|
483 * A Sample Variable Description:: |
|
|
484 @end menu |
|
|
485 |
|
|
486 @node A Sample Function Description, A Sample Command Description, Format of Descriptions, Format of Descriptions |
|
|
487 @subsubsection A Sample Function Description |
|
|
488 @cindex function descriptions |
|
2333
|
489 |
|
2653
|
490 In a function description, the name of the function being described |
|
|
491 appears first. It is followed on the same line by a list of parameters. |
|
|
492 The names used for the parameters are also used in the body of the |
|
|
493 description. |
|
2333
|
494 |
|
2653
|
495 Here is a description of an imaginary function @code{foo}: |
|
|
496 |
|
|
497 @deftypefn {Function} {} foo (@var{x}, @var{y}, @dots{}) |
|
|
498 The function @code{foo} subtracts @var{x} from @var{y}, then adds the |
|
|
499 remaining arguments to the result. If @var{y} is not supplied, then the |
|
|
500 number 19 is used by default. |
|
2333
|
501 |
|
|
502 @example |
|
2653
|
503 @group |
|
|
504 foo (1, [3, 5], 3, 9) |
|
|
505 @result{} [ 14, 16 ] |
|
|
506 foo (5) |
|
|
507 @result{} 14 |
|
|
508 @end group |
|
2333
|
509 @end example |
|
|
510 |
|
2653
|
511 More generally, |
|
2333
|
512 |
|
|
513 @example |
|
2653
|
514 @group |
|
|
515 foo (@var{w}, @var{x}, @var{y}, @dots{}) |
|
|
516 @equiv{} |
|
|
517 @var{x} - @var{w} + @var{y} + @dots{} |
|
|
518 @end group |
|
|
519 @end example |
|
|
520 @end deftypefn |
|
|
521 |
|
|
522 Any parameter whose name contains the name of a type (e.g., |
|
|
523 @var{integer}, @var{integer1} or @var{matrix}) is expected to be of that |
|
|
524 type. Parameters named @var{object} may be of any type. Parameters |
|
|
525 with other sorts of names (e.g., @var{new_file}) are discussed |
|
|
526 specifically in the description of the function. In some sections, |
|
|
527 features common to parameters of several functions are described at the |
|
|
528 beginning. |
|
|
529 |
|
|
530 Functions in Octave may be defined in several different ways. The |
|
|
531 catagory name for functions may include another name that indicates the |
|
|
532 way that the function is defined. These additional tags include |
|
|
533 |
|
|
534 @table @asis |
|
|
535 @item Built-in Function |
|
2670
|
536 @cindex built-in function |
|
2653
|
537 The function described is written in a language like C++, C, or Fortran, |
|
|
538 and is part of the compiled Octave binary. |
|
2333
|
539 |
|
2653
|
540 @item Loadable Function |
|
2670
|
541 @cindex loadable function |
|
2653
|
542 The function described is written in a language like C++, C, or Fortran. |
|
|
543 On systems that support dynamic linking of user-supplied functions, it |
|
|
544 may be automatically linked while Octave is running, but only if it is |
|
|
545 needed. @xref{Dynamically Linked Functions}. |
|
|
546 |
|
|
547 @item Function File |
|
2670
|
548 @cindex function file |
|
2653
|
549 The function described is defined using Octave commands stored in a text |
|
|
550 file. @xref{Function Files}. |
|
2689
|
551 |
|
|
552 @item Mapping Function |
|
|
553 @cindex mapping function |
|
|
554 The function described works element-by-element for matrix and vector |
|
|
555 arguments. |
|
2653
|
556 @end table |
|
|
557 |
|
|
558 @node A Sample Command Description, A Sample Variable Description, A Sample Function Description, Format of Descriptions |
|
2670
|
559 @subsubsection A Sample Command Description |
|
2653
|
560 @cindex command descriptions |
|
|
561 |
|
|
562 Command descriptions have a format similar to function descriptions, |
|
|
563 except that the word `Function' is replaced by `Command. Commands are |
|
2703
|
564 functions that may called without surrounding their arguments in |
|
2653
|
565 parentheses. For example, here is the description for Octave's |
|
|
566 @code{cd} command: |
|
|
567 |
|
|
568 @deffn {Command} cd dir |
|
|
569 @deffnx {Command} chdir dir |
|
|
570 Change the current working directory to @var{dir}. For example, |
|
2670
|
571 @kbd{cd ~/octave} changes the current working directory to |
|
|
572 @file{~/octave}. If the directory does not exist, an error message is |
|
|
573 printed and the working directory is not changed. |
|
2653
|
574 @end deffn |
|
2333
|
575 |
|
2653
|
576 @node A Sample Variable Description, , A Sample Command Description, Format of Descriptions |
|
|
577 @subsubsection A Sample Variable Description |
|
|
578 @cindex variable descriptions |
|
2333
|
579 |
|
2653
|
580 A @dfn{variable} is a name that can hold a value. Although any variable |
|
2670
|
581 can be set by the user, @dfn{built-in variables} typically exist |
|
|
582 specifically so that users can change them to alter the way Octave |
|
|
583 behaves (built-in variables are also sometimes called @dfn{user |
|
|
584 options}). Ordinary variables and built-in variables are described |
|
|
585 using a format like that for functions except that there are no |
|
|
586 arguments. |
|
2333
|
587 |
|
2689
|
588 Here is a description of the imaginary variable |
|
2653
|
589 @code{do_what_i_mean_not_what_i_say}. |
|
2333
|
590 |
|
2670
|
591 @defvr {Built-in Variable} do_what_i_mean_not_what_i_say |
|
2653
|
592 If the value of this variable is nonzero, Octave will do what you |
|
|
593 actually wanted, even if you have typed a completely different and |
|
|
594 meaningless list of commands. |
|
|
595 @end defvr |
|
2333
|
596 |
|
2670
|
597 Other variable descriptions have the same format, but `Built-in |
|
|
598 Variable' is replaced by `Variable', for ordinary variables, or |
|
|
599 `Constant' for symbolic constants whose values cannot be changed. |
