Mercurial > octave-nkf
annotate doc/interpreter/intro.txi @ 20595:c1a6c31ac29a
eliminate more simple uses of error_state
* ov-classdef.cc: Eliminate simple uses of error_state.
author | John W. Eaton <jwe@octave.org> |
---|---|
date | Tue, 06 Oct 2015 00:20:02 -0400 |
parents | b0f7ee81d974 |
children |
rev | line source |
---|---|
19731
4197fc428c7d
maint: Update copyright notices for 2015.
John W. Eaton <jwe@octave.org>
parents:
19630
diff
changeset
|
1 @c Copyright (C) 1996-2015 John W. Eaton |
7018 | 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. | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
9 @c |
7018 | 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. | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
14 @c |
7018 | 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/>. | |
3294 | 18 |
4167 | 19 @node Introduction |
3294 | 20 @chapter A Brief Introduction to Octave |
21 @cindex introduction | |
22 | |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
23 GNU Octave is a high-level language, primarily intended for numerical |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
24 computations. It is typically used for such problems as solving |
17957
e5566719e0a1
doc: Mention GUI in introduction. Update figure root properties.
Michael Godfrey <michaeldgodfrey@gmail.com>
parents:
17757
diff
changeset
|
25 linear and nonlinear equations, numerical linear algebra, statistical |
e5566719e0a1
doc: Mention GUI in introduction. Update figure root properties.
Michael Godfrey <michaeldgodfrey@gmail.com>
parents:
17757
diff
changeset
|
26 analysis, and for performing other numerical experiments. It may also |
e5566719e0a1
doc: Mention GUI in introduction. Update figure root properties.
Michael Godfrey <michaeldgodfrey@gmail.com>
parents:
17757
diff
changeset
|
27 be used as a batch-oriented language for automated data processing. |
e5566719e0a1
doc: Mention GUI in introduction. Update figure root properties.
Michael Godfrey <michaeldgodfrey@gmail.com>
parents:
17757
diff
changeset
|
28 |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
29 Until recently GNU Octave provided a command-line interface only with |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
30 graphical plots displayed in separate windows. However, by default |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
31 the current version runs with a graphical user interface. |
3294 | 32 |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
33 GNU Octave is freely redistributable software. You may redistribute |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
34 it and/or modify it under the terms of the GNU General Public License |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
35 as published by the Free Software Foundation. The GPL is included in |
17097
e7a059a9a644
doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer.
Rik <rik@octave.org>
parents:
16867
diff
changeset
|
36 this manual, @pxref{Copying}. |
3294 | 37 |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
38 This manual provides comprehensive documentation on how to install, |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
39 run, use, and extend GNU Octave. Additional chapters describe how |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
40 to report bugs and help contribute code. |
3294 | 41 |
42 This document corresponds to Octave version @value{VERSION}. | |
43 | |
44 @menu | |
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
45 * Running Octave:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
46 * Simple Examples:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
47 * Conventions:: |
3294 | 48 @end menu |
49 | |
4167 | 50 @node Running Octave |
3294 | 51 @section Running Octave |
52 | |
17957
e5566719e0a1
doc: Mention GUI in introduction. Update figure root properties.
Michael Godfrey <michaeldgodfrey@gmail.com>
parents:
17757
diff
changeset
|
53 On most systems, Octave is started with the shell command @samp{octave}. |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
54 This starts the graphical user interface (GUI). The central window in |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
55 the GUI is the Octave command-line interface. In this window Octave |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
56 displays an initial message and then a prompt indicating it is ready to |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
57 accept input. If you have chosen the traditional command-line interface |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
58 then only the command prompt appears in the same window that was running |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
59 a shell. In any case, you can immediately begin typing Octave commands. |
3294 | 60 |
61 If you get into trouble, you can usually interrupt Octave by typing | |
9033
c7d60ac7a3e6
Documentation cleanup of preface and intro
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
62 @kbd{Control-C} (written @kbd{C-c} for short). @kbd{C-c} gets |
3294 | 63 its name from the fact that you type it by holding down @key{CTRL} and |
64 then pressing @key{c}. Doing this will normally return you to Octave's | |
65 prompt. | |
66 | |
67 @cindex exiting octave | |
68 @cindex quitting octave | |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
69 To exit Octave, type @kbd{quit} or @kbd{exit} at the Octave prompt. |
3294 | 70 |
71 On systems that support job control, you can suspend Octave by sending | |
72 it a @code{SIGTSTP} signal, usually by typing @kbd{C-z}. | |
73 | |
4167 | 74 @node Simple Examples |
3294 | 75 @section Simple Examples |
76 | |
77 The following chapters describe all of Octave's features in detail, but | |
78 before doing that, it might be helpful to give a sampling of some of its | |
79 capabilities. | |
80 | |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
81 If you are new to Octave, we recommend that you try these examples to |
10719
e54152088b0a
Clarify documentation wording. Bug #30165.
Rik <octave@nomad.inbox5.com>
parents:
10668
diff
changeset
|
82 begin learning Octave by using it. Lines marked like so, @samp{octave:13>}, |
3294 | 83 are lines you type, ending each with a carriage return. Octave will |
84 respond with an answer, or by displaying a graph. | |
85 | |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
86 @subsection Elementary Calculations |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
87 |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
88 Octave can easily be used for basic numerical calculations. Octave |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
89 knows about arithmetic operations (+,-,*,/), exponentiation (^), |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
90 natural logarithms/exponents (log, exp), and the trigonometric |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
91 functions (sin, cos, @dots{}). Moreover, Octave calculations work |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
92 on real or imaginary numbers (i,j). In addition, some mathematical |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
93 constants such as the base of the natural logarithm (e) and the ratio |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
94 of a circle's circumference to its diameter (pi) are pre-defined. |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
95 |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
96 @noindent |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
97 For example, to verify Euler's Identity, |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
98 @tex |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
99 $$e^{\imath\pi} = -1$$ |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
100 @end tex |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
101 @ifnottex |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
102 @display |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
103 |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
104 i*pi |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
105 e = -1 |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
106 @end display |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
107 @end ifnottex |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
108 |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
109 @noindent |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
110 type the following which will evaluate to @code{-1} within the |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
111 tolerance of the calculation. |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
112 |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
113 @example |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
114 octave:1> exp (i*pi) |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
115 @end example |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
116 |
6623 | 117 @subsection Creating a Matrix |
3294 | 118 |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
119 Vectors and matrices are the basic building blocks for numerical analysis. |
9033
c7d60ac7a3e6
Documentation cleanup of preface and intro
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
120 To create a new matrix and store it in a variable so that you can |
3294 | 121 refer to it later, type the command |
122 | |
123 @example | |
6620 | 124 octave:1> A = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ] |
3294 | 125 @end example |
126 | |
127 @noindent | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
128 Octave will respond by printing the matrix in neatly aligned columns. |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
129 Octave uses a comma or space to separate entries in a row, and a |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
130 semicolon or carriage return to separate one row from the next. |
9033
c7d60ac7a3e6
Documentation cleanup of preface and intro
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
131 Ending a command with a semicolon tells Octave not to print the result |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
132 of the command. For example, |
3294 | 133 |
134 @example | |
6620 | 135 octave:2> B = rand (3, 2); |
3294 | 136 @end example |
137 | |
138 @noindent | |
139 will create a 3 row, 2 column matrix with each element set to a random | |
140 value between zero and one. | |
141 | |
9033
c7d60ac7a3e6
Documentation cleanup of preface and intro
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
142 To display the value of a variable, simply type the name of the |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
143 variable at the prompt. For example, to display the value stored in the |
9033
c7d60ac7a3e6
Documentation cleanup of preface and intro
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
144 matrix @code{B}, type the command |
3294 | 145 |
146 @example | |
6620 | 147 octave:3> B |
3294 | 148 @end example |
149 | |
6623 | 150 @subsection Matrix Arithmetic |
3294 | 151 |
152 Octave has a convenient operator notation for performing matrix | |
8476
4998c6c78632
[docs] fix case to match example
Brian Gough <bjg@gnu.org>
parents:
7490
diff
changeset
|
153 arithmetic. For example, to multiply the matrix @code{A} by a scalar |
3294 | 154 value, type the command |
155 | |
156 @example | |
6620 | 157 octave:4> 2 * A |
3294 | 158 @end example |
159 | |
6620 | 160 @noindent |
8476
4998c6c78632
[docs] fix case to match example
Brian Gough <bjg@gnu.org>
parents:
7490
diff
changeset
|
161 To multiply the two matrices @code{A} and @code{B}, type the command |
3294 | 162 |
163 @example | |
6620 | 164 octave:5> A * B |
3294 | 165 @end example |
166 | |
6620 | 167 @noindent |
168 and to form the matrix product | |
3294 | 169 @tex |
6620 | 170 $@code{A}^T@code{A}$, |
3294 | 171 @end tex |
6620 | 172 @ifnottex |
173 @code{transpose (A) * A}, | |
174 @end ifnottex | |
3294 | 175 type the command |
176 | |
177 @example | |
6620 | 178 octave:6> A' * A |
3294 | 179 @end example |
180 | |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
181 @subsection Solving Systems of Linear Equations |
3294 | 182 |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
183 Systems of linear equations are ubiquitous in numerical analysis. |
6620 | 184 To solve the set of linear equations @code{A@var{x} = b}, |
3294 | 185 use the left division operator, @samp{\}: |
186 | |
187 @example | |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
188 @var{x} = A \ b |
3294 | 189 @end example |
190 | |
191 @noindent | |
192 This is conceptually equivalent to | |
193 @tex | |
6620 | 194 $@code{A}^{-1}@code{b}$, |
3294 | 195 @end tex |
6620 | 196 @ifnottex |
3294 | 197 @code{inv (a) * b}, |
6620 | 198 @end ifnottex |
3294 | 199 but avoids computing the inverse of a matrix directly. |
200 | |
201 If the coefficient matrix is singular, Octave will print a warning | |
202 message and compute a minimum norm solution. | |
203 | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
204 A simple example comes from chemistry and the need to obtain balanced |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
205 chemical equations. Consider the burning of hydrogen and oxygen to |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
206 produce water. |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
207 @tex |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
208 $$ {\rm H_{2}} + {\rm O_{2}} \rightarrow {\rm H_{2}O} $$ |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
209 @end tex |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
210 @ifnottex |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10719
diff
changeset
|
211 |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
212 @example |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
213 H2 + O2 --> H2O |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
214 @end example |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10719
diff
changeset
|
215 |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
216 @end ifnottex |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
217 @noindent |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
218 The equation above is not accurate. The Law of Conservation of Mass requires |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
219 that the number of molecules of each type balance on the left- and right-hand |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
220 sides of the equation. Writing the variable overall reaction with |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
221 individual equations for hydrogen and oxygen one finds: |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
222 @tex |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
223 \vbox{ |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
224 $$ x_{1}{\rm H_{2}} + x_{2}{\rm O_{2}} \rightarrow {\rm H_{2}O} $$ |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
225 $$ {\rm H:}\quad 2x_{1} + 0x_{2} \rightarrow 2 $$ |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
226 $$ {\rm O:}\quad 0x_{1} + 2x_{2} \rightarrow 1 $$ |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
227 } |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
228 @end tex |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
229 @ifnottex |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10719
diff
changeset
|
230 |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
231 @example |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
232 @group |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
233 x1*H2 + x2*O2 --> H2O |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
234 H: 2*x1 + 0*x2 --> 2 |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
235 O: 0*x1 + 2*x2 --> 1 |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
236 @end group |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
237 @end example |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10719
diff
changeset
|
238 |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
239 @end ifnottex |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
240 @noindent |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
241 The solution in Octave is found in just three steps. |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
242 |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
243 @example |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
244 @group |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
245 octave:1> A = [ 2, 0; 0, 2 ]; |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
246 octave:2> b = [ 2; 1 ]; |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
247 octave:3> x = A \ b |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
248 @end group |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
249 @end example |
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
250 |
6623 | 251 @subsection Integrating Differential Equations |
3294 | 252 |
253 Octave has built-in functions for solving nonlinear differential | |
254 equations of the form | |
255 @tex | |
256 $$ | |
257 {dx \over dt} = f(x,t), \qquad x(t=t_0) = x_0 | |
258 $$ | |
259 @end tex | |
6620 | 260 @ifnottex |
3294 | 261 |
262 @example | |
263 @group | |
264 dx | |
265 -- = f (x, t) | |
266 dt | |
267 @end group | |
268 @end example | |
269 | |
270 @noindent | |
271 with the initial condition | |
272 | |
273 @example | |
274 x(t = t0) = x0 | |
275 @end example | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10719
diff
changeset
|
276 |
6620 | 277 @end ifnottex |
3294 | 278 @noindent |
279 For Octave to integrate equations of this form, you must first provide a | |
280 definition of the function | |
281 @tex | |
282 $f (x, t)$. | |
283 @end tex | |
6620 | 284 @ifnottex |
3294 | 285 @code{f(x,t)}. |
6620 | 286 @end ifnottex |
3294 | 287 This is straightforward, and may be accomplished by entering the |
288 function body directly on the command line. For example, the following | |
9033
c7d60ac7a3e6
Documentation cleanup of preface and intro
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
289 commands define the right-hand side function for an interesting pair of |
3294 | 290 nonlinear differential equations. Note that while you are entering a |
291 function, Octave responds with a different prompt, to indicate that it | |
292 is waiting for you to complete your input. | |
293 | |
294 @example | |
295 @group | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
296 octave:1> function xdot = f (x, t) |
3294 | 297 > |
298 > r = 0.25; | |
299 > k = 1.4; | |
300 > a = 1.5; | |
301 > b = 0.16; | |
302 > c = 0.9; | |
303 > d = 0.8; | |
304 > | |
305 > xdot(1) = r*x(1)*(1 - x(1)/k) - a*x(1)*x(2)/(1 + b*x(1)); | |
306 > xdot(2) = c*a*x(1)*x(2)/(1 + b*x(1)) - d*x(2); | |
307 > | |
308 > endfunction | |
309 @end group | |
310 @end example | |
311 | |
312 @noindent | |
313 Given the initial condition | |
314 | |
315 @example | |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
316 octave:2> x0 = [1; 2]; |
3294 | 317 @end example |
318 | |
319 @noindent | |
320 and the set of output times as a column vector (note that the first | |
321 output time corresponds to the initial condition given above) | |
322 | |
323 @example | |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
324 octave:3> t = linspace (0, 50, 200)'; |
3294 | 325 @end example |
326 | |
327 @noindent | |
328 it is easy to integrate the set of differential equations: | |
329 | |
330 @example | |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
331 octave:4> x = lsode ("f", x0, t); |
3294 | 332 @end example |
333 | |
334 @noindent | |
335 The function @code{lsode} uses the Livermore Solver for Ordinary | |
19074
0850b5212619
doc: Add @nospell macro around proper names in documentation.
Rik <rik@octave.org>
parents:
17957
diff
changeset
|
336 Differential Equations, described in @nospell{A. C. Hindmarsh}, |
0850b5212619
doc: Add @nospell macro around proper names in documentation.
Rik <rik@octave.org>
parents:
17957
diff
changeset
|
337 @cite{ODEPACK, a Systematized Collection of ODE Solvers}, in: Scientific |
0850b5212619
doc: Add @nospell macro around proper names in documentation.
Rik <rik@octave.org>
parents:
17957
diff
changeset
|
338 Computing, @nospell{R. S. Stepleman} et al. (Eds.), North-Holland, Amsterdam, |
0850b5212619
doc: Add @nospell macro around proper names in documentation.
Rik <rik@octave.org>
parents:
17957
diff
changeset
|
339 1983, pages 55--64. |
3294 | 340 |
6623 | 341 @subsection Producing Graphical Output |
3294 | 342 |
343 To display the solution of the previous example graphically, use the | |
344 command | |
345 | |
346 @example | |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
347 octave:1> plot (t, x) |
3294 | 348 @end example |
349 | |
6620 | 350 @noindent |
351 If you are using a graphical user interface, Octave will automatically create | |
6331 | 352 a separate window to display the plot. |
353 | |
6620 | 354 To save a plot once it has been displayed on the screen, use the print |
6331 | 355 command. For example, |
3294 | 356 |
357 @example | |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
358 print -dpdf foo.pdf |
3294 | 359 @end example |
360 | |
361 @noindent | |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
362 will create a file called @file{foo.pdf} that contains a rendering of |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
363 the current plot in Portable Document Format. The command |
3294 | 364 |
365 @example | |
6331 | 366 help print |
3294 | 367 @end example |
368 | |
369 @noindent | |
6331 | 370 explains more options for the @code{print} command and provides a list |
6620 | 371 of additional output file formats. |
3294 | 372 |
6623 | 373 @subsection Editing What You Have Typed |
3294 | 374 |
375 At the Octave prompt, you can recall, edit, and reissue previous | |
376 commands using Emacs- or vi-style editing commands. The default | |
377 keybindings use Emacs-style commands. For example, to recall the | |
9033
c7d60ac7a3e6
Documentation cleanup of preface and intro
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
378 previous command, press @kbd{Control-p} (written @kbd{C-p} for |
c7d60ac7a3e6
Documentation cleanup of preface and intro
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
379 short). Doing this will normally bring back the previous line of input. |
6620 | 380 @kbd{C-n} will bring up the next line of input, @kbd{C-b} will move |
381 the cursor backward on the line, @kbd{C-f} will move the cursor forward | |
382 on the line, etc. | |
3294 | 383 |
384 A complete description of the command line editing capability is given | |
17097
e7a059a9a644
doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer.
Rik <rik@octave.org>
parents:
16867
diff
changeset
|
385 in this manual, @pxref{Command Line Editing}. |
3294 | 386 |
6623 | 387 @subsection Help and Documentation |
3294 | 388 |
389 Octave has an extensive help facility. The same documentation that is | |
390 available in printed form is also available from the Octave prompt, | |
391 because both forms of the documentation are created from the same input | |
392 file. | |
393 | |
394 In order to get good help you first need to know the name of the command | |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
395 that you want to use. The name of this function may not always be |
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
396 obvious, but a good place to start is to type @code{help --list}. |
11565
21c3e1370b82
implement --list option for help function
John W. Eaton <jwe@octave.org>
parents:
11547
diff
changeset
|
397 This will show you all the operators, keywords, built-in functions, |
21c3e1370b82
implement --list option for help function
John W. Eaton <jwe@octave.org>
parents:
11547
diff
changeset
|
398 and loadable functions available in the current session of Octave. An |
21c3e1370b82
implement --list option for help function
John W. Eaton <jwe@octave.org>
parents:
11547
diff
changeset
|
399 alternative is to search the documentation using the @code{lookfor} |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
400 function (described in @ref{Getting Help}). |
6620 | 401 |
402 Once you know the name of the function you wish to use, you can get more | |
403 help on the function by simply including the name as an argument to help. | |
404 For example, | |
3294 | 405 |
406 @example | |
407 help plot | |
408 @end example | |
409 | |
410 @noindent | |
411 will display the help text for the @code{plot} function. | |
412 | |
413 Octave sends output that is too long to fit on one screen through a | |
414 pager like @code{less} or @code{more}. Type a @key{RET} to advance one | |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
415 line, a @key{SPC} to advance one page, and @key{q} to quit the pager. |
3294 | 416 |
417 The part of Octave's help facility that allows you to read the complete | |
418 text of the printed manual from within Octave normally uses a separate | |
419 program called Info. When you invoke Info you will be put into a menu | |
420 driven program that contains the entire Octave manual. Help for using | |
17097
e7a059a9a644
doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer.
Rik <rik@octave.org>
parents:
16867
diff
changeset
|
421 Info is provided in this manual, @pxref{Getting Help}. |
3294 | 422 |
4167 | 423 @node Conventions |
3294 | 424 @section Conventions |
425 | |
426 This section explains the notational conventions that are used in this | |
427 manual. You may want to skip this section and refer back to it later. | |
428 | |
429 @menu | |
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
430 * Fonts:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
431 * Evaluation Notation:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
432 * Printing Notation:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
433 * Error Messages:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
434 * Format of Descriptions:: |
3294 | 435 @end menu |
436 | |
4167 | 437 @node Fonts |
3294 | 438 @subsection Fonts |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
439 @cindex documentation fonts |
3294 | 440 |
441 Examples of Octave code appear in this font or form: @code{svd (a)}. | |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
442 Names that represent variables or function arguments appear |
3294 | 443 in this font or form: @var{first-number}. Commands that you type at the |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
444 shell prompt appear in this font or form: @samp{octave --no-init-file}. |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
445 Commands that you type at the Octave prompt sometimes appear in this font |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
446 or form: @kbd{foo --bar --baz}. Specific keys on your keyboard appear |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
447 in this font or form: @key{RET}. |
3294 | 448 |
4167 | 449 @node Evaluation Notation |
3294 | 450 @subsection Evaluation Notation |
451 @cindex evaluation notation | |
452 @cindex documentation notation | |
453 | |
454 In the examples in this manual, results from expressions that you | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10719
diff
changeset
|
455 evaluate are indicated with @samp{@result{}}. For example: |
3294 | 456 |
457 @example | |
458 @group | |
459 sqrt (2) | |
460 @result{} 1.4142 | |
461 @end group | |
462 @end example | |
463 | |
464 @noindent | |
465 You can read this as ``@code{sqrt (2)} evaluates to 1.4142''. | |
466 | |
467 In some cases, matrix values that are returned by expressions are | |
468 displayed like this | |
469 | |
470 @example | |
471 @group | |
472 [1, 2; 3, 4] == [1, 3; 2, 4] | |
473 @result{} [ 1, 0; 0, 1 ] | |
474 @end group | |
475 @end example | |
476 | |
477 @noindent | |
478 and in other cases, they are displayed like this | |
479 | |
480 @example | |
481 @group | |
482 eye (3) | |
483 @result{} 1 0 0 | |
484 0 1 0 | |
485 0 0 1 | |
486 @end group | |
487 @end example | |
488 | |
489 @noindent | |
490 in order to clearly show the structure of the result. | |
491 | |
492 Sometimes to help describe one expression, another expression is | |
493 shown that produces identical results. The exact equivalence of | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10719
diff
changeset
|
494 expressions is indicated with @samp{@equiv{}}. For example: |
3294 | 495 |
496 @example | |
497 @group | |
498 rot90 ([1, 2; 3, 4], -1) | |
499 @equiv{} | |
500 rot90 ([1, 2; 3, 4], 3) | |
501 @equiv{} | |
502 rot90 ([1, 2; 3, 4], 7) | |
503 @end group | |
504 @end example | |
505 | |
4167 | 506 @node Printing Notation |
3294 | 507 @subsection Printing Notation |
508 @cindex printing notation | |
509 | |
510 Many of the examples in this manual print text when they are | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
511 evaluated. In this manual the printed text resulting from an example |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
512 is indicated by @samp{@print{}}. The value that is returned by |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
513 evaluating the expression is displayed with @samp{@result{}} |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
514 (@code{1} in the next example) and follows on a separate line. |
3294 | 515 |
516 @example | |
517 @group | |
518 printf ("foo %s\n", "bar") | |
519 @print{} foo bar | |
520 @result{} 1 | |
521 @end group | |
522 @end example | |
523 | |
4167 | 524 @node Error Messages |
3294 | 525 @subsection Error Messages |
526 @cindex error message notation | |
527 | |
528 Some examples signal errors. This normally displays an error message | |
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
529 on your terminal. Error messages are shown on a line beginning with |
3294 | 530 @code{error:}. |
531 | |
532 @example | |
533 @group | |
7490 | 534 fieldnames ([1, 2; 3, 4]) |
17757
dae2230227a7
doc: Use double-quote in preference to single quote in code examples.
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
535 error: fieldnames: Invalid input argument |
3294 | 536 @end group |
537 @end example | |
538 | |
4167 | 539 @node Format of Descriptions |
3294 | 540 @subsection Format of Descriptions |
541 @cindex description format | |
542 | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
543 Functions and commands are described in this manual in a |
3294 | 544 uniform format. The first line of a description contains the name of |
545 the item followed by its arguments, if any. | |
10668
72585f1ca7a2
Replace @ifinfo with @ifnottex.
Rik <octave@nomad.inbox5.com>
parents:
9209
diff
changeset
|
546 @ifnottex |
17145
f7fd413dcf4a
doc: Remove subnode on built-in variables which no longer exist.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
547 The category---function, command, or whatever---appears at the |
3294 | 548 beginning of the line. |
10668
72585f1ca7a2
Replace @ifinfo with @ifnottex.
Rik <octave@nomad.inbox5.com>
parents:
9209
diff
changeset
|
549 @end ifnottex |
3294 | 550 @iftex |
17145
f7fd413dcf4a
doc: Remove subnode on built-in variables which no longer exist.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
551 The category---function, command, or whatever---is printed next to the |
3294 | 552 right margin. |
553 @end iftex | |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
554 If there are multiple ways to invoke the function then each allowable |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
555 form is listed. |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
556 |
3294 | 557 The description follows on succeeding lines, sometimes with examples. |
558 | |
559 @menu | |
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
560 * A Sample Function Description:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
561 * A Sample Command Description:: |
3294 | 562 @end menu |
563 | |
4167 | 564 @node A Sample Function Description |
3294 | 565 @subsubsection A Sample Function Description |
566 @cindex function descriptions | |
567 | |
568 In a function description, the name of the function being described | |
569 appears first. It is followed on the same line by a list of parameters. | |
570 The names used for the parameters are also used in the body of the | |
571 description. | |
572 | |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
573 After all of the calling forms have been enumerated, the next line is a |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
574 concise one-sentence summary of the function. |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
575 |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
576 After the summary there may be documentation on the inputs and outputs, |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
577 examples of function usage, notes about the algorithm used, and references |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
578 to related functions. |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
579 |
3294 | 580 Here is a description of an imaginary function @code{foo}: |
581 | |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
582 @need 4000 |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14034
diff
changeset
|
583 @deftypefn {Function File} {} foo (@var{x}) |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14034
diff
changeset
|
584 @deftypefnx {Function File} {} foo (@var{x}, @var{y}) |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14034
diff
changeset
|
585 @deftypefnx {Function File} {} foo (@var{x}, @var{y}, @dots{}) |
3294 | 586 The function @code{foo} subtracts @var{x} from @var{y}, then adds the |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
587 remaining arguments to the result. |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
588 |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
589 If @var{y} is not supplied, then the number 19 is used by default. |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
590 |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
591 Example: |
3294 | 592 |
593 @example | |
594 @group | |
595 foo (1, [3, 5], 3, 9) | |
596 @result{} [ 14, 16 ] | |
597 foo (5) | |
598 @result{} 14 | |
599 @end group | |
600 @end example | |
601 | |
602 More generally, | |
603 | |
604 @example | |
605 @group | |
606 foo (@var{w}, @var{x}, @var{y}, @dots{}) | |
607 @equiv{} | |
608 @var{x} - @var{w} + @var{y} + @dots{} | |
609 @end group | |
610 @end example | |
20229
b0f7ee81d974
doc: Remove extra spaces at start of docstring which show up in Info format.
Rik <rik@octave.org>
parents:
20212
diff
changeset
|
611 |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
612 @b{See also:} bar |
3294 | 613 @end deftypefn |
614 | |
615 Any parameter whose name contains the name of a type (e.g., | |
9033
c7d60ac7a3e6
Documentation cleanup of preface and intro
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
616 @var{integer} or @var{matrix}) is expected to be of that |
3294 | 617 type. Parameters named @var{object} may be of any type. Parameters |
618 with other sorts of names (e.g., @var{new_file}) are discussed | |
619 specifically in the description of the function. In some sections, | |
620 features common to parameters of several functions are described at the | |
621 beginning. | |
622 | |
623 Functions in Octave may be defined in several different ways. The | |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
624 category name for functions may include a tag that indicates the |
3294 | 625 way that the function is defined. These additional tags include |
626 | |
627 @table @asis | |
6620 | 628 @item Function File |
629 @cindex function file | |
630 The function described is defined using Octave commands stored in a text | |
631 file. @xref{Function Files}. | |
632 | |
3294 | 633 @item Built-in Function |
634 @cindex built-in function | |
635 The function described is written in a language like C++, C, or Fortran, | |
636 and is part of the compiled Octave binary. | |
637 | |
638 @item Loadable Function | |
639 @cindex loadable function | |
640 The function described is written in a language like C++, C, or Fortran. | |
641 On systems that support dynamic linking of user-supplied functions, it | |
642 may be automatically linked while Octave is running, but only if it is | |
16867
be41c30bcb44
Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents:
15467
diff
changeset
|
643 needed. @xref{External Code Interface}. |
3294 | 644 |
645 @item Mapping Function | |
646 @cindex mapping function | |
647 The function described works element-by-element for matrix and vector | |
648 arguments. | |
649 @end table | |
650 | |
4167 | 651 @node A Sample Command Description |
3294 | 652 @subsubsection A Sample Command Description |
653 @cindex command descriptions | |
654 | |
655 Command descriptions have a format similar to function descriptions, | |
9033
c7d60ac7a3e6
Documentation cleanup of preface and intro
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
656 except that the word `Function' is replaced by `Command'. Commands are |
7001 | 657 functions that may be called without surrounding their arguments in |
3294 | 658 parentheses. For example, here is the description for Octave's |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
659 @code{diary} command: |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
660 |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
661 @need 4000 |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
662 @deftypefn {Command} {} diary |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
663 @deftypefnx {Command} {} diary on |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
664 @deftypefnx {Command} {} diary off |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
665 @deftypefnx {Command} {} diary @var{filename} |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
666 Record a list of all commands @emph{and} the output they produce, mixed |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
667 together just as they appear on the terminal. |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
668 |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
669 Valid options are: |
3294 | 670 |
20212
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
671 @table @asis |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
672 @item on |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
673 Start recording a session in a file called @file{diary} in the |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
674 current working directory. |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
675 |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
676 @item off |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
677 Stop recording the session in the diary file. |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
678 |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
679 @item @var{filename} |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
680 Record the session in the file named @var{filename}. |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
681 @end table |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
682 |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
683 With no arguments, @code{diary} toggles the current diary state. |
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
684 @seealso{history} |
11547 | 685 @end deftypefn |