Mercurial > octave-libtiff
annotate doc/interpreter/intro.txi @ 31185:a1145ac2ce9b
Tiff: populated TagID from the C++ map to avoid having two copies
* __tiff__.cc (F__tiff_make_tagid__): implemented internal function as
initializer for TagID.
* Tiff.m: changed the initialization for TagID to use the internal function.
| author | magedrifaat <magedrifaat@gmail.com> |
|---|---|
| date | Thu, 18 Aug 2022 17:23:43 +0200 |
| parents | 796f54d4ddbf |
| children |
| rev | line source |
|---|---|
|
30564
796f54d4ddbf
update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents:
28159
diff
changeset
|
1 @c Copyright (C) 1996-2022 The Octave Project Developers |
| 7018 | 2 @c |
| 3 @c This file is part of Octave. | |
| 4 @c | |
|
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
23220
diff
changeset
|
5 @c Octave is free software: you can redistribute it and/or modify it |
|
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
6 @c under the terms of the GNU General Public License as published by |
|
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
23220
diff
changeset
|
7 @c the Free Software Foundation, either version 3 of the License, or |
|
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
8 @c (at your option) any later version. |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
9 @c |
|
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
10 @c Octave is distributed in the hope that it will be useful, but |
|
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
11 @c WITHOUT ANY WARRANTY; without even the implied warranty of |
|
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
12 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
|
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
13 @c GNU General Public License for more details. |
|
19593
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 | |
|
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
23220
diff
changeset
|
17 @c <https://www.gnu.org/licenses/>. |
| 3294 | 18 |
| 4167 | 19 @node Introduction |
| 3294 | 20 @chapter A Brief Introduction to Octave |
| 21 @cindex introduction | |
| 22 | |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
23 GNU Octave is a high-level language primarily intended for numerical |
|
19593
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 |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
29 The current version of Octave executes in a graphical user interface |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
30 (GUI). The GUI hosts an Integrated Development Environment (IDE) |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
31 which includes a code editor with syntax highlighting, built-in |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
32 debugger, documentation browser, as well as the interpreter for the |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
33 language itself. A command-line interface for Octave is also available. |
| 3294 | 34 |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
35 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
|
36 it and/or modify it under the terms of the GNU General Public License |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
37 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
|
38 this manual, @pxref{Copying}. |
| 3294 | 39 |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
40 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
|
41 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
|
42 to report bugs and help contribute code. |
| 3294 | 43 |
| 44 This document corresponds to Octave version @value{VERSION}. | |
| 45 | |
| 46 @menu | |
|
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
47 * Running Octave:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
48 * Simple Examples:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
49 * Conventions:: |
| 3294 | 50 @end menu |
| 51 | |
| 4167 | 52 @node Running Octave |
| 3294 | 53 @section Running Octave |
| 54 | |
|
17957
e5566719e0a1
doc: Mention GUI in introduction. Update figure root properties.
Michael Godfrey <michaeldgodfrey@gmail.com>
parents:
17757
diff
changeset
|
55 On most systems, Octave is started with the shell command @samp{octave}. |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
56 This starts the graphical user interface. The central window in the GUI |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
57 is the Octave command-line interface. In this window Octave displays an |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
58 initial message and then a prompt indicating it is ready to accept |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
59 input. If you have chosen the traditional command-line interface then |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
60 only the command prompt appears in the same window that was running |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
61 a shell. In either case, you can immediately begin typing Octave |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
62 commands. |
| 3294 | 63 |
| 64 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
|
65 @kbd{Control-C} (written @kbd{C-c} for short). @kbd{C-c} gets |
| 3294 | 66 its name from the fact that you type it by holding down @key{CTRL} and |
| 67 then pressing @key{c}. Doing this will normally return you to Octave's | |
| 68 prompt. | |
| 69 | |
| 70 @cindex exiting octave | |
| 71 @cindex quitting octave | |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
72 To exit Octave, type @kbd{quit} or @kbd{exit} at the Octave prompt. |
| 3294 | 73 |
| 74 On systems that support job control, you can suspend Octave by sending | |
| 75 it a @code{SIGTSTP} signal, usually by typing @kbd{C-z}. | |
| 76 | |
| 4167 | 77 @node Simple Examples |
| 3294 | 78 @section Simple Examples |
| 79 | |
| 80 The following chapters describe all of Octave's features in detail, but | |
| 81 before doing that, it might be helpful to give a sampling of some of its | |
| 82 capabilities. | |
| 83 | |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
84 If you are new to Octave, we recommend that you try these examples to |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
85 begin learning Octave by using it. Lines marked like so, |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
86 @samp{octave:13>}, are lines you type, ending each with a carriage |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
87 return. Octave will respond with an answer, or by displaying a graph. |
| 3294 | 88 |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
89 @subsection Elementary Calculations |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
90 |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
91 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
|
92 knows about arithmetic operations (+,-,*,/), exponentiation (^), |
|
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
93 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
|
94 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
|
95 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
|
96 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
|
97 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
|
98 |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
99 @noindent |
|
21315
ea2c2e08ceda
doc: Periodic spellcheck of documentation.
Rik <rik@octave.org>
parents:
20672
diff
changeset
|
100 For example, to verify @nospell{Euler's} Identity, |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
101 @tex |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
102 $$e^{\imath\pi} = -1$$ |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
103 @end tex |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
104 @ifnottex |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
105 @display |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
106 |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
107 i*pi |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
108 e = -1 |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
109 @end display |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
110 @end ifnottex |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
111 |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
112 @noindent |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
113 type the following which will evaluate to @code{-1} within the |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
114 tolerance of the calculation. |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
115 |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
116 @example |
|
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
117 octave:1> exp (i*pi) |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
118 @end example |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
119 |
| 6623 | 120 @subsection Creating a Matrix |
| 3294 | 121 |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
122 Vectors and matrices are the basic building blocks for numerical |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
123 analysis. To create a new matrix and store it in a variable so that you |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
124 can refer to it later, type the command |
| 3294 | 125 |
| 126 @example | |
| 6620 | 127 octave:1> A = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ] |
| 3294 | 128 @end example |
| 129 | |
| 130 @noindent | |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
131 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
|
132 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
|
133 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
|
134 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
|
135 of the command. For example, |
| 3294 | 136 |
| 137 @example | |
| 6620 | 138 octave:2> B = rand (3, 2); |
| 3294 | 139 @end example |
| 140 | |
| 141 @noindent | |
| 142 will create a 3 row, 2 column matrix with each element set to a random | |
| 143 value between zero and one. | |
| 144 | |
|
9033
c7d60ac7a3e6
Documentation cleanup of preface and intro
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
145 To display the value of a variable, simply type the name of the |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
146 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
|
147 matrix @code{B}, type the command |
| 3294 | 148 |
| 149 @example | |
| 6620 | 150 octave:3> B |
| 3294 | 151 @end example |
| 152 | |
| 6623 | 153 @subsection Matrix Arithmetic |
| 3294 | 154 |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
155 Octave uses standard mathematical notation with the advantage over |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
156 low-level languages that operators may act on scalars, vector, matrices, |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
157 or N-dimensional arrays. For example, to multiply the matrix @code{A} |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
158 by a scalar value, type the command |
| 3294 | 159 |
| 160 @example | |
| 6620 | 161 octave:4> 2 * A |
| 3294 | 162 @end example |
| 163 | |
| 6620 | 164 @noindent |
|
8476
4998c6c78632
[docs] fix case to match example
Brian Gough <bjg@gnu.org>
parents:
7490
diff
changeset
|
165 To multiply the two matrices @code{A} and @code{B}, type the command |
| 3294 | 166 |
| 167 @example | |
| 6620 | 168 octave:5> A * B |
| 3294 | 169 @end example |
| 170 | |
| 6620 | 171 @noindent |
| 172 and to form the matrix product | |
| 3294 | 173 @tex |
| 6620 | 174 $@code{A}^T@code{A}$, |
| 3294 | 175 @end tex |
| 6620 | 176 @ifnottex |
| 177 @code{transpose (A) * A}, | |
| 178 @end ifnottex | |
| 3294 | 179 type the command |
| 180 | |
| 181 @example | |
| 6620 | 182 octave:6> A' * A |
| 3294 | 183 @end example |
| 184 | |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
185 @subsection Solving Systems of Linear Equations |
| 3294 | 186 |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
187 Systems of linear equations are ubiquitous in numerical analysis. |
| 6620 | 188 To solve the set of linear equations @code{A@var{x} = b}, |
| 3294 | 189 use the left division operator, @samp{\}: |
| 190 | |
| 191 @example | |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
192 @var{x} = A \ b |
| 3294 | 193 @end example |
| 194 | |
| 195 @noindent | |
| 196 This is conceptually equivalent to | |
| 197 @tex | |
| 6620 | 198 $@code{A}^{-1}@code{b}$, |
| 3294 | 199 @end tex |
| 6620 | 200 @ifnottex |
|
20672
77b104cad58e
intro.txi change a to A to match the previous comments
Doug Stewart <doug.dastew@gmail.com
parents:
20194
diff
changeset
|
201 @code{inv (A) * b}, |
| 6620 | 202 @end ifnottex |
| 3294 | 203 but avoids computing the inverse of a matrix directly. |
| 204 | |
| 205 If the coefficient matrix is singular, Octave will print a warning | |
| 206 message and compute a minimum norm solution. | |
| 207 | |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
208 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
|
209 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
|
210 produce water. |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
211 @tex |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
212 $$ {\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
|
213 @end tex |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
214 @ifnottex |
|
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 @example |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
217 H2 + O2 --> H2O |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
218 @end example |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10719
diff
changeset
|
219 |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
220 @end ifnottex |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
221 @noindent |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
222 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
|
223 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
|
224 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
|
225 individual equations for hydrogen and oxygen one finds: |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
226 @tex |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
227 \vbox{ |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
228 $$ 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
|
229 $$ {\rm H:}\quad 2x_{1} + 0x_{2} \rightarrow 2 $$ |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
230 $$ {\rm O:}\quad 0x_{1} + 2x_{2} \rightarrow 1 $$ |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
231 } |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
232 @end tex |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
233 @ifnottex |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10719
diff
changeset
|
234 |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
235 @example |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
236 @group |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
237 x1*H2 + x2*O2 --> H2O |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
238 H: 2*x1 + 0*x2 --> 2 |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
239 O: 0*x1 + 2*x2 --> 1 |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
240 @end group |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
241 @end example |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10719
diff
changeset
|
242 |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
243 @end ifnottex |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
244 @noindent |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
245 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
|
246 |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
247 @example |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
248 @group |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
249 octave:1> A = [ 2, 0; 0, 2 ]; |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
250 octave:2> b = [ 2; 1 ]; |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
251 octave:3> x = A \ b |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
252 @end group |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
253 @end example |
|
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
254 |
| 6623 | 255 @subsection Integrating Differential Equations |
| 3294 | 256 |
| 257 Octave has built-in functions for solving nonlinear differential | |
| 258 equations of the form | |
| 259 @tex | |
| 260 $$ | |
| 261 {dx \over dt} = f(x,t), \qquad x(t=t_0) = x_0 | |
| 262 $$ | |
| 263 @end tex | |
| 6620 | 264 @ifnottex |
| 3294 | 265 |
| 266 @example | |
| 267 @group | |
| 268 dx | |
| 269 -- = f (x, t) | |
| 270 dt | |
| 271 @end group | |
| 272 @end example | |
| 273 | |
| 274 @noindent | |
| 275 with the initial condition | |
| 276 | |
| 277 @example | |
| 278 x(t = t0) = x0 | |
| 279 @end example | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10719
diff
changeset
|
280 |
| 6620 | 281 @end ifnottex |
| 3294 | 282 @noindent |
| 283 For Octave to integrate equations of this form, you must first provide a | |
| 284 definition of the function | |
| 285 @tex | |
| 286 $f (x, t)$. | |
| 287 @end tex | |
| 6620 | 288 @ifnottex |
| 3294 | 289 @code{f(x,t)}. |
| 6620 | 290 @end ifnottex |
| 3294 | 291 This is straightforward, and may be accomplished by entering the |
| 292 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
|
293 commands define the right-hand side function for an interesting pair of |
| 3294 | 294 nonlinear differential equations. Note that while you are entering a |
| 295 function, Octave responds with a different prompt, to indicate that it | |
| 296 is waiting for you to complete your input. | |
| 297 | |
| 298 @example | |
| 299 @group | |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17957
diff
changeset
|
300 octave:1> function xdot = f (x, t) |
| 3294 | 301 > |
| 302 > r = 0.25; | |
| 303 > k = 1.4; | |
| 304 > a = 1.5; | |
| 305 > b = 0.16; | |
| 306 > c = 0.9; | |
| 307 > d = 0.8; | |
| 308 > | |
| 309 > xdot(1) = r*x(1)*(1 - x(1)/k) - a*x(1)*x(2)/(1 + b*x(1)); | |
| 310 > xdot(2) = c*a*x(1)*x(2)/(1 + b*x(1)) - d*x(2); | |
| 311 > | |
| 312 > endfunction | |
| 313 @end group | |
| 314 @end example | |
| 315 | |
| 316 @noindent | |
| 317 Given the initial condition | |
| 318 | |
| 319 @example | |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
320 octave:2> x0 = [1; 2]; |
| 3294 | 321 @end example |
| 322 | |
| 323 @noindent | |
| 324 and the set of output times as a column vector (note that the first | |
| 325 output time corresponds to the initial condition given above) | |
| 326 | |
| 327 @example | |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
328 octave:3> t = linspace (0, 50, 200)'; |
| 3294 | 329 @end example |
| 330 | |
| 331 @noindent | |
| 332 it is easy to integrate the set of differential equations: | |
| 333 | |
| 334 @example | |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
335 octave:4> x = lsode ("f", x0, t); |
| 3294 | 336 @end example |
| 337 | |
| 338 @noindent | |
| 339 The function @code{lsode} uses the Livermore Solver for Ordinary | |
|
19040
0850b5212619
doc: Add @nospell macro around proper names in documentation.
Rik <rik@octave.org>
parents:
17957
diff
changeset
|
340 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
|
341 @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
|
342 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
|
343 1983, pages 55--64. |
| 3294 | 344 |
| 6623 | 345 @subsection Producing Graphical Output |
| 3294 | 346 |
| 347 To display the solution of the previous example graphically, use the | |
| 348 command | |
| 349 | |
| 350 @example | |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
351 octave:1> plot (t, x) |
| 3294 | 352 @end example |
| 353 | |
| 6620 | 354 @noindent |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
355 Octave will automatically create a separate window to display the plot. |
| 6331 | 356 |
| 6620 | 357 To save a plot once it has been displayed on the screen, use the print |
| 6331 | 358 command. For example, |
| 3294 | 359 |
| 360 @example | |
|
28159
54d6f1b5fab2
doc: Simplify print command in Intro chapter of manual.
Rik <rik@octave.org>
parents:
26376
diff
changeset
|
361 print foo.pdf |
| 3294 | 362 @end example |
| 363 | |
| 364 @noindent | |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
365 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:
19697
diff
changeset
|
366 the current plot in Portable Document Format. The command |
| 3294 | 367 |
| 368 @example | |
| 6331 | 369 help print |
| 3294 | 370 @end example |
| 371 | |
| 372 @noindent | |
| 6331 | 373 explains more options for the @code{print} command and provides a list |
| 6620 | 374 of additional output file formats. |
| 3294 | 375 |
| 6623 | 376 @subsection Help and Documentation |
| 3294 | 377 |
| 378 Octave has an extensive help facility. The same documentation that is | |
| 379 available in printed form is also available from the Octave prompt, | |
| 380 because both forms of the documentation are created from the same input | |
| 381 file. | |
| 382 | |
| 383 In order to get good help you first need to know the name of the command | |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
384 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
|
385 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
|
386 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
|
387 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
|
388 alternative is to search the documentation using the @code{lookfor} |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
389 function (described in @ref{Getting Help}). |
| 6620 | 390 |
| 391 Once you know the name of the function you wish to use, you can get more | |
| 392 help on the function by simply including the name as an argument to help. | |
| 393 For example, | |
| 3294 | 394 |
| 395 @example | |
| 396 help plot | |
| 397 @end example | |
| 398 | |
| 399 @noindent | |
| 400 will display the help text for the @code{plot} function. | |
| 401 | |
| 402 The part of Octave's help facility that allows you to read the complete | |
| 403 text of the printed manual from within Octave normally uses a separate | |
| 404 program called Info. When you invoke Info you will be put into a menu | |
| 405 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
|
406 Info is provided in this manual, @pxref{Getting Help}. |
| 3294 | 407 |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
408 @subsection Editing What You Have Typed |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
409 |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
410 At the Octave prompt, you can recall, edit, and reissue previous |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
411 commands using Emacs- or vi-style editing commands. The default |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
412 keybindings use Emacs-style commands. For example, to recall the |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
413 previous command, press @kbd{Control-p} (written @kbd{C-p} for |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
414 short). Doing this will normally bring back the previous line of input. |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
415 @kbd{C-n} will bring up the next line of input, @kbd{C-b} will move |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
416 the cursor backward on the line, @kbd{C-f} will move the cursor forward |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
417 on the line, etc. |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
418 |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
419 A complete description of the command line editing capability is given |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
420 in this manual, @pxref{Command Line Editing}. |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
421 |
| 4167 | 422 @node Conventions |
| 3294 | 423 @section Conventions |
| 424 | |
|
21315
ea2c2e08ceda
doc: Periodic spellcheck of documentation.
Rik <rik@octave.org>
parents:
20672
diff
changeset
|
425 This section explains the notation conventions that are used in this |
| 3294 | 426 manual. You may want to skip this section and refer back to it later. |
| 427 | |
| 428 @menu | |
|
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
429 * Fonts:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
430 * Evaluation Notation:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
431 * Printing Notation:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
432 * Error Messages:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
433 * Format of Descriptions:: |
| 3294 | 434 @end menu |
| 435 | |
| 4167 | 436 @node Fonts |
| 3294 | 437 @subsection Fonts |
|
9089
0b08eaf77dd6
Detailed review of intro.texi
Rik <rdrider0-list@yahoo.com>
parents:
9033
diff
changeset
|
438 @cindex documentation fonts |
| 3294 | 439 |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
440 Examples of Octave code appear in this font or form: @w{@code{svd (a)}}. |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
441 Names that represent variables or function arguments appear in this font |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
442 or form: @var{first-number}. Commands that you type at the shell prompt |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
443 appear in this font or form: @w{@samp{octave --no-init-file}}. Commands |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
444 that you type at the Octave prompt sometimes appear in this font or |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
445 form: @w{@kbd{foo --bar --baz}}. Specific keys on your keyboard appear |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
446 in this font or form: @key{RET}. |
| 3294 | 447 |
| 4167 | 448 @node Evaluation Notation |
| 3294 | 449 @subsection Evaluation Notation |
| 450 @cindex evaluation notation | |
| 451 @cindex documentation notation | |
| 452 | |
| 453 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
|
454 evaluate are indicated with @samp{@result{}}. For example: |
| 3294 | 455 |
| 456 @example | |
| 457 @group | |
| 458 sqrt (2) | |
| 459 @result{} 1.4142 | |
| 460 @end group | |
| 461 @end example | |
| 462 | |
| 463 @noindent | |
| 464 You can read this as ``@code{sqrt (2)} evaluates to 1.4142''. | |
| 465 | |
| 466 In some cases, matrix values that are returned by expressions are | |
| 467 displayed like this | |
| 468 | |
| 469 @example | |
| 470 @group | |
| 471 [1, 2; 3, 4] == [1, 3; 2, 4] | |
| 472 @result{} [ 1, 0; 0, 1 ] | |
| 473 @end group | |
| 474 @end example | |
| 475 | |
| 476 @noindent | |
| 477 and in other cases, they are displayed like this | |
| 478 | |
| 479 @example | |
| 480 @group | |
| 481 eye (3) | |
| 482 @result{} 1 0 0 | |
| 483 0 1 0 | |
| 484 0 0 1 | |
| 485 @end group | |
| 486 @end example | |
| 487 | |
| 488 @noindent | |
| 489 in order to clearly show the structure of the result. | |
| 490 | |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
491 Sometimes to help describe one expression, another expression is shown |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
492 that produces identical results. The exact equivalence of expressions |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
493 is indicated with @samp{@equiv{}}. For example: |
| 3294 | 494 |
| 495 @example | |
| 496 @group | |
| 497 rot90 ([1, 2; 3, 4], -1) | |
| 498 @equiv{} | |
| 499 rot90 ([1, 2; 3, 4], 3) | |
| 500 @equiv{} | |
| 501 rot90 ([1, 2; 3, 4], 7) | |
| 502 @end group | |
| 503 @end example | |
| 504 | |
| 4167 | 505 @node Printing Notation |
| 3294 | 506 @subsection Printing Notation |
| 507 @cindex printing notation | |
| 508 | |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
509 Many of the examples in this manual print text when they are evaluated. |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
510 In this manual the printed text resulting from an example is indicated |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
511 by @samp{@print{}}. The value that is returned by evaluating the |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
512 expression is displayed with @samp{@result{}} (@code{1} in the next |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
513 example) and follows on a separate line. |
| 3294 | 514 |
| 515 @example | |
| 516 @group | |
| 517 printf ("foo %s\n", "bar") | |
| 518 @print{} foo bar | |
| 519 @result{} 1 | |
| 520 @end group | |
| 521 @end example | |
| 522 | |
| 4167 | 523 @node Error Messages |
| 3294 | 524 @subsection Error Messages |
| 525 @cindex error message notation | |
| 526 | |
| 527 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
|
528 on your terminal. Error messages are shown on a line beginning with |
| 3294 | 529 @code{error:}. |
| 530 | |
| 531 @example | |
| 532 @group | |
| 7490 | 533 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
|
534 error: fieldnames: Invalid input argument |
| 3294 | 535 @end group |
| 536 @end example | |
| 537 | |
| 4167 | 538 @node Format of Descriptions |
| 3294 | 539 @subsection Format of Descriptions |
| 540 @cindex description format | |
| 541 | |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
542 Functions and commands are described in this manual in a uniform format. |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
543 The first line of a description contains the name of the item followed |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
544 by its arguments, if any. If there are multiple ways to invoke the |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
545 function then each allowable form is listed. |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
546 |
| 3294 | 547 The description follows on succeeding lines, sometimes with examples. |
| 548 | |
| 549 @menu | |
|
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
550 * A Sample Function Description:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17145
diff
changeset
|
551 * A Sample Command Description:: |
| 3294 | 552 @end menu |
| 553 | |
| 4167 | 554 @node A Sample Function Description |
| 3294 | 555 @subsubsection A Sample Function Description |
| 556 @cindex function descriptions | |
| 557 | |
| 558 In a function description, the name of the function being described | |
| 559 appears first. It is followed on the same line by a list of parameters. | |
| 560 The names used for the parameters are also used in the body of the | |
| 561 description. | |
| 562 | |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
563 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:
19697
diff
changeset
|
564 concise one-sentence summary of the function. |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
565 |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
566 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:
19697
diff
changeset
|
567 examples of function usage, notes about the algorithm used, and references |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
568 to related functions. |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
569 |
| 3294 | 570 Here is a description of an imaginary function @code{foo}: |
| 571 | |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
572 @need 4000 |
|
21319
8880d93010d8
Remove further uses of CLASS field in @deftypefn macro.
Rik <rik@octave.org>
parents:
21315
diff
changeset
|
573 @deftypefn {} {} foo (@var{x}) |
|
8880d93010d8
Remove further uses of CLASS field in @deftypefn macro.
Rik <rik@octave.org>
parents:
21315
diff
changeset
|
574 @deftypefnx {} {} foo (@var{x}, @var{y}) |
|
8880d93010d8
Remove further uses of CLASS field in @deftypefn macro.
Rik <rik@octave.org>
parents:
21315
diff
changeset
|
575 @deftypefnx {} {} foo (@var{x}, @var{y}, @dots{}) |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
576 Subtract @var{x} from @var{y}, then add any remaining arguments to the |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
577 result. |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
578 |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
579 The input @var{x} must be a numeric scalar, vector, or array. |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
580 |
|
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
581 The optional input @var{y} defaults to 19 if it is not supplied. |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
582 |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
583 Example: |
| 3294 | 584 |
| 585 @example | |
| 586 @group | |
| 587 foo (1, [3, 5], 3, 9) | |
| 588 @result{} [ 14, 16 ] | |
| 589 foo (5) | |
| 590 @result{} 14 | |
| 591 @end group | |
| 592 @end example | |
| 593 | |
| 594 More generally, | |
| 595 | |
| 596 @example | |
| 597 @group | |
| 598 foo (@var{w}, @var{x}, @var{y}, @dots{}) | |
| 599 @equiv{} | |
| 600 @var{x} - @var{w} + @var{y} + @dots{} | |
| 601 @end group | |
| 602 @end example | |
|
20194
b0f7ee81d974
doc: Remove extra spaces at start of docstring which show up in Info format.
Rik <rik@octave.org>
parents:
20177
diff
changeset
|
603 |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
604 @b{See also:} bar |
| 3294 | 605 @end deftypefn |
| 606 | |
| 607 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
|
608 @var{integer} or @var{matrix}) is expected to be of that |
| 3294 | 609 type. Parameters named @var{object} may be of any type. Parameters |
| 610 with other sorts of names (e.g., @var{new_file}) are discussed | |
| 611 specifically in the description of the function. In some sections, | |
| 612 features common to parameters of several functions are described at the | |
| 613 beginning. | |
| 614 | |
| 4167 | 615 @node A Sample Command Description |
| 3294 | 616 @subsubsection A Sample Command Description |
| 617 @cindex command descriptions | |
| 618 | |
|
21531
32101a071a9c
doc: Remove Function Category from documentation about function descriptions.
Rik <rik@octave.org>
parents:
21319
diff
changeset
|
619 Commands are functions that may be called without surrounding their arguments |
|
32101a071a9c
doc: Remove Function Category from documentation about function descriptions.
Rik <rik@octave.org>
parents:
21319
diff
changeset
|
620 in parentheses. Command descriptions have a format similar to function |
|
32101a071a9c
doc: Remove Function Category from documentation about function descriptions.
Rik <rik@octave.org>
parents:
21319
diff
changeset
|
621 descriptions. For example, here is the description for Octave's @code{diary} |
|
32101a071a9c
doc: Remove Function Category from documentation about function descriptions.
Rik <rik@octave.org>
parents:
21319
diff
changeset
|
622 command: |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
623 |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
624 @need 4000 |
|
21319
8880d93010d8
Remove further uses of CLASS field in @deftypefn macro.
Rik <rik@octave.org>
parents:
21315
diff
changeset
|
625 @deftypefn {} {} diary |
|
8880d93010d8
Remove further uses of CLASS field in @deftypefn macro.
Rik <rik@octave.org>
parents:
21315
diff
changeset
|
626 @deftypefnx {} {} diary on |
|
8880d93010d8
Remove further uses of CLASS field in @deftypefn macro.
Rik <rik@octave.org>
parents:
21315
diff
changeset
|
627 @deftypefnx {} {} diary off |
|
8880d93010d8
Remove further uses of CLASS field in @deftypefn macro.
Rik <rik@octave.org>
parents:
21315
diff
changeset
|
628 @deftypefnx {} {} diary @var{filename} |
|
22854
e3e52ba95250
doc: Update Introduction chapter to use newest version of diary() Texinfo.
Rik <rik@octave.org>
parents:
22853
diff
changeset
|
629 @deftypefnx {} {[@var{status}, @var{diaryfile}] =} diary |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
630 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:
19697
diff
changeset
|
631 together just as they appear on the terminal. |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
632 |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
633 Valid options are: |
| 3294 | 634 |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
635 @table @asis |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
636 @item on |
|
22854
e3e52ba95250
doc: Update Introduction chapter to use newest version of diary() Texinfo.
Rik <rik@octave.org>
parents:
22853
diff
changeset
|
637 Start recording a session in a file called @file{diary} in the current working |
|
e3e52ba95250
doc: Update Introduction chapter to use newest version of diary() Texinfo.
Rik <rik@octave.org>
parents:
22853
diff
changeset
|
638 directory. |
|
20177
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
639 |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
640 @item off |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
641 Stop recording the session in the diary file. |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
642 |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
643 @item @var{filename} |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
644 Record the session in the file named @var{filename}. |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
645 @end table |
|
4951982f8a2c
intro.txi: Improve documentation in introductory chapter.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
646 |
|
22854
e3e52ba95250
doc: Update Introduction chapter to use newest version of diary() Texinfo.
Rik <rik@octave.org>
parents:
22853
diff
changeset
|
647 With no input or output arguments, @code{diary} toggles the current diary |
|
e3e52ba95250
doc: Update Introduction chapter to use newest version of diary() Texinfo.
Rik <rik@octave.org>
parents:
22853
diff
changeset
|
648 state. |
|
e3e52ba95250
doc: Update Introduction chapter to use newest version of diary() Texinfo.
Rik <rik@octave.org>
parents:
22853
diff
changeset
|
649 |
|
e3e52ba95250
doc: Update Introduction chapter to use newest version of diary() Texinfo.
Rik <rik@octave.org>
parents:
22853
diff
changeset
|
650 If output arguments are requested, @code{diary} ignores inputs and returns |
|
e3e52ba95250
doc: Update Introduction chapter to use newest version of diary() Texinfo.
Rik <rik@octave.org>
parents:
22853
diff
changeset
|
651 the current status. The boolean @var{status} indicates whether recording is on |
|
e3e52ba95250
doc: Update Introduction chapter to use newest version of diary() Texinfo.
Rik <rik@octave.org>
parents:
22853
diff
changeset
|
652 or off, and @var{diaryfile} is the name of the file where the session is |
|
22910
23847979b91e
maint: Strip trailing whitespace from source files.
John W. Eaton <jwe@octave.org>
parents:
22854
diff
changeset
|
653 stored. |
|
22852
efdb5d9dface
doc: Rewrite parts of Introduction chapter.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
654 @seealso{history, evalc} |
| 11547 | 655 @end deftypefn |