Mercurial > hg > octave-lyh
changeset 10828:322f43e0e170
Grammarcheck .txi documentation files.
line wrap: on
line diff
--- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,19 @@ +2010-07-28 Rik <octave@nomad.inbox5.com> + + * interpreter/arith.txi, interpreter/audio.txi, interpreter/basics.txi, + interpreter/container.txi, interpreter/contrib.txi, + interpreter/debug.txi, interpreter/diagperm.txi, + interpreter/diffeq.txi, interpreter/dynamic.txi, interpreter/emacs.txi, + interpreter/errors.txi, interpreter/eval.txi, interpreter/expr.txi, + interpreter/func.txi, interpreter/image.txi, interpreter/install.txi, + interpreter/interp.txi, interpreter/intro.txi, interpreter/io.txi, + interpreter/linalg.txi, interpreter/matrix.txi, interpreter/nonlin.txi, + interpreter/numbers.txi, interpreter/optim.txi, + interpreter/package.txi, interpreter/plot.txi, interpreter/poly.txi, + interpreter/quad.txi, interpreter/sparse.txi, interpreter/stmt.txi, + interpreter/strings.txi, interpreter/testfun.txi, interpreter/tips.txi, + interpreter/var.txi: Grammarcheck .txi documentation files. + 2010-07-21 Jaroslav Hajek <highegg@gmail.com> * interpreter/tips.txi: Update some tips.
--- a/doc/interpreter/arith.txi +++ b/doc/interpreter/arith.txi @@ -23,7 +23,7 @@ Unless otherwise noted, all of the functions described in this chapter will work for real and complex scalar, vector, or matrix arguments. Functions described as @dfn{mapping functions} apply the given operation individually to -each element when given a matrix argument. For example, +each element when given a matrix argument. For example: @example @group @@ -150,6 +150,7 @@ specified in degrees. These functions produce true zeros at the appropriate intervals rather than the small round-off error that occurs when using radians. For example: + @example @group cosd (90)
--- a/doc/interpreter/audio.txi +++ b/doc/interpreter/audio.txi @@ -24,7 +24,7 @@ Octave provides a few functions for dealing with audio data. An audio `sample' is a single output value from an A/D converter, i.e., a small integer number (usually 8 or 16 bits), and audio data is just a series -of such samples. It can be characterized by three parameters: the +of such samples. It can be characterized by three parameters: the sampling rate (measured in samples per second or Hz, e.g., 8000 or 44100), the number of bits per sample (e.g., 8 or 16), and the number of channels (1 for mono, 2 for stereo, etc.).
--- a/doc/interpreter/basics.txi +++ b/doc/interpreter/basics.txi @@ -80,7 +80,7 @@ @cindex @code{--doc-cache-file @var{filename}} Specify the name of the doc cache file to use. The value of @var{filename} specified on the command line will override any value of -@w{@code{OCTAVE_DOC_CACHE_FILE}} found in the environment, but not any commands +@w{@env{OCTAVE_DOC_CACHE_FILE}} found in the environment, but not any commands in the system or user startup files that use the @code{doc_cache_file} function. @@ -91,16 +91,16 @@ Echo commands as they are executed. @item --eval @var{code} -Evaluate @var{code} and exit when finished unless @code{--persist} is also +Evaluate @var{code} and exit when finished unless @option{--persist} is also specified. @item --exec-path @var{path} @cindex @code{--exec-path @var{path}} Specify the path to search for programs to run. The value of @var{path} specified on the command line will override any value of -@w{@code{OCTAVE_EXEC_PATH}} found in the environment, but not any commands +@w{@env{OCTAVE_EXEC_PATH}} found in the environment, but not any commands in the system or user startup files that set the built-in variable -@w{@code{EXEC_PATH}}. +@w{@env{EXEC_PATH}}. @item --help @itemx -h @@ -114,15 +114,15 @@ @cindex @code{--image-path @var{path}} Add path to the head of the search path for images. The value of @var{path} specified on the command line will override any value of -@w{@code{OCTAVE_IMAGE_PATH}} found in the environment, but not any commands +@w{@env{OCTAVE_IMAGE_PATH}} found in the environment, but not any commands in the system or user startup files that set the built-in variable -@w{@code{IMAGE_PATH}}. +@w{@env{IMAGE_PATH}}. @item --info-file @var{filename} @cindex @code{--info-file @var{filename}} Specify the name of the info file to use. The value of @var{filename} specified on the command line will override any value of -@w{@code{OCTAVE_INFO_FILE}} found in the environment, but not any commands +@w{@env{OCTAVE_INFO_FILE}} found in the environment, but not any commands in the system or user startup files that use the @code{info_file} function. @@ -130,7 +130,7 @@ @cindex @code{--info-program @var{program}} Specify the name of the info program to use. The value of @var{program} specified on the command line will override any value of -@w{@code{OCTAVE_INFO_PROGRAM}} found in the environment, but not any +@w{@env{OCTAVE_INFO_PROGRAM}} found in the environment, but not any commands in the system or user startup files that use the @code{info_program} function. @@ -174,8 +174,8 @@ @cindex @code{--norc} @cindex @code{-f} Don't read any of the system or user initialization files at startup. -This is equivalent to using both of the options @code{--no-init-file} -and @code{--no-site-file}. +This is equivalent to using both of the options @option{--no-init-file} +and @option{--no-site-file}. @item --path @var{path} @itemx -p @var{path} @@ -183,13 +183,13 @@ @cindex @code{-p @var{path}} Add path to the head of the search path for function files. The value of @var{path} specified on the command line will override any value -of @w{@code{OCTAVE_PATH}} found in the environment, but not any commands in the +of @w{@env{OCTAVE_PATH}} found in the environment, but not any commands in the system or user startup files that set the internal load path through one of the path functions. @item --persist @cindex @code{--persist} -Go to interactive mode after @code{--eval} or reading from a file +Go to interactive mode after @option{--eval} or reading from a file named on the command line. @item --silent @@ -225,6 +225,7 @@ @noindent and disable the following warnings + @example @group Octave:abbreviated-property-match @@ -248,7 +249,7 @@ @item @var{file} Execute commands from @var{file}. Exit when done unless -@code{--persist} is also specified. +@option{--persist} is also specified. @end table Octave also includes several functions which return information @@ -300,7 +301,7 @@ can be made globally for all users at your site for all versions of Octave you have installed. Care should be taken when making changes to this file since all users of Octave at your site will be affected. The default file -may be overridden by the environment variable @w{@code{OCTAVE_SITE_INITFILE}}. +may be overridden by the environment variable @w{@env{OCTAVE_SITE_INITFILE}}. @item @var{octave-home}/share/octave/@var{version}/m/startup/octaverc @cindex version startup file @@ -311,7 +312,7 @@ a particular version of Octave. Care should be taken when making changes to this file since all users of Octave at your site will be affected. The default file may be overridden by the environment variable -@w{@code{OCTAVE_VERSION_INITFILE}}. +@w{@env{OCTAVE_VERSION_INITFILE}}. @item ~/.octaverc @cindex personal startup file @@ -333,8 +334,8 @@ @end table A message will be displayed as each of the startup files is read if you -invoke Octave with the @code{--verbose} option but without the -@code{--silent} option. +invoke Octave with the @option{--verbose} option but without the +@option{--silent} option. @node Quitting Octave @section Quitting Octave @@ -993,6 +994,7 @@ end of the line. Any text following the sharp sign or percent symbol is ignored by the Octave interpreter and not executed. The following example shows whole line and partial line comments. + @example @group function countdown @@ -1015,6 +1017,7 @@ Entire blocks of code can be commented by enclosing the code between matching @samp{#@{} and @samp{#@}} or @samp{%@{} and @samp{%@}} markers. For example, + @example @group function quick_countdown @@ -1044,6 +1047,7 @@ string. This means that the same commands used to get help on built-in functions are available for properly formatted user-defined functions. For example, after defining the function @code{f} below, + @example @group function xdot = f (x, t)
--- a/doc/interpreter/container.txi +++ b/doc/interpreter/container.txi @@ -136,7 +136,7 @@ @end example Note that when Octave prints the value of a structure that contains -other structures, only a few levels are displayed. For example, +other structures, only a few levels are displayed. For example: @example @group @@ -201,7 +201,7 @@ @end example Function return lists can include structure elements, and they may be -indexed like any other variable. For example, +indexed like any other variable. For example: @example [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4]); @@ -285,7 +285,7 @@ Furthermore, the structure array can return a comma separated list of field values (@pxref{Comma Separated Lists}), if indexed by one of its -own field names. For example +own field names. For example: @example @group @@ -309,7 +309,8 @@ @end group @end example -Just as for numerical arrays, it is possible to use vectors as indices (@pxref{Index Expressions}): +Just as for numerical arrays, it is possible to use vectors as indices +(@pxref{Index Expressions}): @example @group @@ -367,7 +368,7 @@ with the @code{struct} command. @code{struct} takes pairs of arguments, where the first argument in the pair is the fieldname to include in the structure and the second is a scalar or cell array, representing the -values to include in the structure or structure array. For example +values to include in the structure or structure array. For example: @example @group @@ -382,7 +383,7 @@ If the values passed to @code{struct} are a mix of scalar and cell arrays, then the scalar arguments are expanded to create a -structure array with a consistent dimension. For example +structure array with a consistent dimension. For example: @example @group @@ -600,7 +601,7 @@ @end group @end example -Just like numerical arrays, cell arrays can be multidimensional. The +Just like numerical arrays, cell arrays can be multi-dimensional. The @code{cell} function accepts any number of positive integers to describe the size of the returned cell array. It is also possible to set the size of the cell array through a vector of positive integers. In the @@ -664,7 +665,7 @@ array. Using the @samp{(} and @samp{)} operators, indexing works for cell -arrays like for multidimensional arrays. As an example, all the rows +arrays like for multi-dimensional arrays. As an example, all the rows of the first and third column of a cell array can be set to @code{0} with the following command: @@ -988,7 +989,7 @@ @subsection Comma Separated Lists Generated from Structure Arrays Structure arrays can equally be used to create comma separated lists. This is done by addressing one of the fields of a structure -array. For example +array. For example: @example @group
--- a/doc/interpreter/contrib.txi +++ b/doc/interpreter/contrib.txi @@ -50,6 +50,7 @@ also find help how to install Mercurial. A simple contribution sequence could look like this: + @example @group hg clone http://www.octave.org/hg/octave @@ -71,6 +72,7 @@ Here is a slightly less simple example using Mercurial queues, where you work on two unrelated changesets in parallel and update one of the changesets after discussion in the maintainers mailing list: + @example hg qnew nasty_bug # create a new patch # change sources@dots{} @@ -159,10 +161,10 @@ @node Octave Sources (m-files) @section Octave Sources (m-files) -Don't use tabs. Tabs cause trouble. If you are used to them, set up your editor -so that it converts tabs to spaces. Indent the bodies of the statement blocks. -Recommended indent is 2 spaces. When calling functions, put spaces after commas -and before the calling parentheses, like this: +Don't use tabs. Tabs cause trouble. If you are used to them, set up your +editor so that it converts tabs to spaces. Indent the bodies of the statement +blocks. Recommended indent is 2 spaces. When calling functions, put spaces +after commas and before the calling parentheses, like this: @example x = max (sin (y+3), 2); @@ -178,8 +180,9 @@ @noindent Here, putting spaces after @code{sin}, @code{cos} would result in a parse error. In indexing expression, do not put a space after the identifier (this -differentiates indexing and function calls nicely). The space after comma is not -necessary if index expressions are simple, i.e., you may write +differentiates indexing and function calls nicely). The space after comma is +not necessary if index expressions are simple, i.e., you may write + @example A(:,i,j) @end example @@ -222,8 +225,8 @@ @node C++ Sources @section C++ Sources -Don't use tabs. Tabs cause trouble. If you are used to them, set up your editor -so that it converts tabs to spaces. Format function headers like this: +Don't use tabs. Tabs cause trouble. If you are used to them, set up your +editor so that it converts tabs to spaces. Format function headers like this: @example @group @@ -261,9 +264,9 @@ clarification. Split long expressions in such a way that a continuation line starts with an -operator rather than identifier. If the split occurs inside braces, continuation -should be aligned with the first char after the innermost braces enclosing the -split. Example: +operator rather than identifier. If the split occurs inside braces, +continuation should be aligned with the first char after the innermost braces +enclosing the split. Example: @example @group @@ -320,9 +323,9 @@ to be compilable with the f2c and g77 compilers, without special flags if possible. This usually means that non-legacy compilers also accept the sources. -The M4 macro language is mainly used for Autoconf configuration files. You should -follow normal M4 rules when contributing to these files. Some M4 files come -from external source, namely the Autoconf archive +The M4 macro language is mainly used for Autoconf configuration files. You +should follow normal M4 rules when contributing to these files. Some M4 files +come from external source, namely the Autoconf archive @url{http://autoconf-archive.cryp.to}. If you give a code example in the documentation written in Texinfo with the
--- a/doc/interpreter/debug.txi +++ b/doc/interpreter/debug.txi @@ -84,7 +84,7 @@ set a breakpoint immediately on entering a function, the breakpoint should be set to line 1. The leading comment block will be ignored and the breakpoint will be set to the first executable statement in the -function. For example +function. For example: @example @group @@ -107,7 +107,8 @@ @DOCSTRING(dbclear) @noindent -These functions can be used to clear all the breakpoints in a function. For example, +These functions can be used to clear all the breakpoints in a function. For +example: @example dbclear ("asind", dbstatus ("asind"));
--- a/doc/interpreter/diagperm.txi +++ b/doc/interpreter/diagperm.txi @@ -30,21 +30,21 @@ @node Basic Usage @section Creating and Manipulating Diagonal and Permutation Matrices -A diagonal matrix is defined as a matrix that has zero entries outside the main diagonal; -that is, +A diagonal matrix is defined as a matrix that has zero entries outside the main +diagonal; that is, @tex $D_{ij} = 0$ if $i \neq j$ @end tex @ifnottex @code{D(i,j) == 0} if @code{i != j}. @end ifnottex -Most often, square diagonal matrices are considered; however, the definition can equally -be applied to non-square matrices, in which case we usually speak of a rectangular diagonal -matrix. +Most often, square diagonal matrices are considered; however, the definition can +equally be applied to non-square matrices, in which case we usually speak of a +rectangular diagonal matrix. -A permutation matrix is defined as a square matrix that has a single element equal to unity -in each row and each column; all other elements are zero. That is, there exists a -permutation (vector) +A permutation matrix is defined as a square matrix that has a single element +equal to unity in each row and each column; all other elements are zero. That +is, there exists a permutation (vector) @tex $p$ such that $P_{ij}=1$ if $j = p_i$ and $P_{ij}=0$ otherwise. @@ -54,10 +54,10 @@ @code{P(i,j) == 0} otherwise. @end ifnottex -Octave provides special treatment of real and complex rectangular diagonal matrices, -as well as permutation matrices. They are stored as special objects, using efficient -storage and algorithms, facilitating writing both readable and efficient matrix algebra -expressions in the Octave language. +Octave provides special treatment of real and complex rectangular diagonal +matrices, as well as permutation matrices. They are stored as special objects, +using efficient storage and algorithms, facilitating writing both readable and +efficient matrix algebra expressions in the Octave language. @menu * Creating Diagonal Matrices:: @@ -68,19 +68,21 @@ @node Creating Diagonal Matrices @subsection Creating Diagonal Matrices -The most common and easiest way to create a diagonal matrix is using the built-in -function @dfn{diag}. The expression @code{diag (v)}, with @var{v} a vector, -will create a square diagonal matrix with elements on the main diagonal given -by the elements of @var{v}, and size equal to the length of @var{v}. +The most common and easiest way to create a diagonal matrix is using the +built-in function @dfn{diag}. The expression @code{diag (v)}, with @var{v} a +vector, will create a square diagonal matrix with elements on the main diagonal +given by the elements of @var{v}, and size equal to the length of @var{v}. @code{diag (v, m, n)} can be used to construct a rectangular diagonal matrix. The result of these expressions will be a special diagonal matrix object, rather than a general matrix object. Diagonal matrix with unit elements can be created using @dfn{eye}. -Some other built-in functions can also return diagonal matrices. Examples include +Some other built-in functions can also return diagonal matrices. Examples +include @dfn{balance} or @dfn{inv}. Example: + @example diag (1:4) @result{} @@ -110,19 +112,25 @@ rather overrides an existing syntax: permutation matrices can be conveniently created by indexing an identity matrix by permutation vectors. That is, if @var{q} is a permutation vector of length @var{n}, the expression + @example P = eye (n) (:, q); @end example + will create a permutation matrix - a special matrix object. + @example eye (n) (q, :) @end example + will also work (and create a row permutation matrix), as well as + @example eye (n) (q1, q2). @end example For example: + @example @group eye (4) ([1,3,2,4],:) @@ -172,21 +180,22 @@ @end group @end example -Some other built-in functions can also return permutation matrices. Examples include +Some other built-in functions can also return permutation matrices. Examples +include @dfn{inv} or @dfn{lu}. @node Explicit and Implicit Conversions @subsection Explicit and Implicit Conversions -The diagonal and permutation matrices are special objects in their own right. A number -of operations and built-in functions are defined for these matrices to use special, -more efficient code than would be used for a full matrix in the same place. Examples -are given in further sections. +The diagonal and permutation matrices are special objects in their own right. A +number of operations and built-in functions are defined for these matrices to +use special, more efficient code than would be used for a full matrix in the +same place. Examples are given in further sections. To facilitate smooth mixing with full matrices, backward compatibility, and -compatibility with @sc{matlab}, the diagonal and permutation matrices should allow -any operation that works on full matrices, and will either treat it specially, -or implicitly convert themselves to full matrices. +compatibility with @sc{matlab}, the diagonal and permutation matrices should +allow any operation that works on full matrices, and will either treat it +specially, or implicitly convert themselves to full matrices. Instances include matrix indexing, except for extracting a single element or a leading submatrix, indexed assignment, or applying most mapper functions, @@ -222,22 +231,28 @@ $$S_{ij} = D_{ii} M_{ij}$$ @end tex @ifnottex + @example S(i,j) = D(i,i) * M(i,j). @end example + @end ifnottex Similarly, @code{M*D} will do a column scaling. The matrix @var{D} may also be rectangular, m-by-n where @code{m != n}. If @code{m < n}, then the expression @code{D*M} is equivalent to + @example D(:,1:m) * M(1:m,:), @end example + i.e., trailing @code{n-m} rows of @var{M} are ignored. If @code{m > n}, then @code{D*M} is equivalent to + @example [D(1:n,n) * M; zeros(m-n, columns (M))], @end example + i.e., null rows are appended to the result. The situation for right-multiplication @code{M*D} is analogous. @@ -259,10 +274,11 @@ Multiplication and division by diagonal matrices works efficiently also when combined with sparse matrices, i.e., @code{D*S}, where @var{D} is a diagonal matrix and @var{S} is a sparse matrix scales the rows of the sparse matrix and -returns a sparse matrix. The expressions @code{S*D}, @code{D\S}, @code{S/D} work -analogically. +returns a sparse matrix. The expressions @code{S*D}, @code{D\S}, @code{S/D} +work analogically. If @var{D1} and @var{D2} are both diagonal matrices, then the expressions + @example @group D1 + D2 @@ -272,23 +288,29 @@ D1 \ D2 @end group @end example -again produce diagonal matrices, provided that normal -dimension matching rules are obeyed. The relations used are same as described above. -Also, a diagonal matrix @var{D} can be multiplied or divided by a scalar, or raised -to a scalar power if it is square, producing diagonal matrix result in all cases. +again produce diagonal matrices, provided that normal +dimension matching rules are obeyed. The relations used are same as described +above. + +Also, a diagonal matrix @var{D} can be multiplied or divided by a scalar, or +raised to a scalar power if it is square, producing diagonal matrix result in +all cases. -A diagonal matrix can also be transposed or conjugate-transposed, giving the expected -result. Extracting a leading submatrix of a diagonal matrix, i.e., @code{D(1:m,1:n)}, -will produce a diagonal matrix, other indexing expressions will implicitly convert to -full matrix. +A diagonal matrix can also be transposed or conjugate-transposed, giving the +expected result. Extracting a leading submatrix of a diagonal matrix, i.e., +@code{D(1:m,1:n)}, will produce a diagonal matrix, other indexing expressions +will implicitly convert to full matrix. -Adding a diagonal matrix to a full matrix only operates on the diagonal elements. Thus, +Adding a diagonal matrix to a full matrix only operates on the diagonal +elements. Thus, + @example A = A + eps * eye (n) @end example -is an efficient method of augmenting the diagonal of a matrix. Subtraction works -analogically. + +is an efficient method of augmenting the diagonal of a matrix. Subtraction +works analogically. When involved in expressions with other element-by-element operators, @code{.*}, @code{./}, @code{.\} or @code{.^}, an implicit conversion to full matrix will @@ -307,10 +329,13 @@ help an user to understand the connection between a permutation matrix and a permuting vector. Namely, the following holds, where @code{I = eye (n)} is an identity matrix: + @example I(p,:) * M = (I*M) (p,:) = M(p,:) @end example + Similarly, + @example M * I(:,p) = (M*I) (:,p) = M(:,p) @end example @@ -329,14 +354,14 @@ Multiplication and division by permutation matrices works efficiently also when combined with sparse matrices, i.e., @code{P*S}, where @var{P} is a permutation matrix and @var{S} is a sparse matrix permutes the rows of the sparse matrix and -returns a sparse matrix. The expressions @code{S*P}, @code{P\S}, @code{S/P} work -analogically. +returns a sparse matrix. The expressions @code{S*P}, @code{P\S}, @code{S/P} +work analogically. -Two permutation matrices can be multiplied or divided (if their sizes match), performing -a composition of permutations. Also a permutation matrix can be indexed by a permutation -vector (or two vectors), giving again a permutation matrix. -Any other operations do not generally yield a permutation matrix and will thus -trigger the implicit conversion. +Two permutation matrices can be multiplied or divided (if their sizes match), +performing a composition of permutations. Also a permutation matrix can be +indexed by a permutation vector (or two vectors), giving again a permutation +matrix. Any other operations do not generally yield a permutation matrix and +will thus trigger the implicit conversion. @node Function Support @section Functions That Are Aware of These Matrices @@ -386,6 +411,7 @@ The following can be used to solve a linear system @code{A*x = b} using the pivoted LU factorization: + @example @group [L, U, P] = lu (A); ## now L*U = P*A @@ -395,6 +421,7 @@ @noindent This is how you normalize columns of a matrix @var{X} to unit norm: + @example @group s = norm (X, "columns"); @@ -406,6 +433,7 @@ The following expression is a way to efficiently calculate the sign of a permutation, given by a permutation vector @var{p}. It will also work in earlier versions of Octave, but slowly. + @example det (eye (length (p))(p, :)) @end example @@ -413,6 +441,7 @@ @noindent Finally, here's how you solve a linear system @code{A*x = b} with Tikhonov regularization (ridge regression) using SVD (a skeleton only): + @example @group m = rows (A); n = columns (A); @@ -467,7 +496,9 @@ like: @itemize @item scalar * diagonal matrix is a diagonal matrix + @item sparse matrix / scalar preserves the sparsity pattern + @item permutation matrix * matrix is equivalent to permuting rows @end itemize all of these natural mathematical truths would be invalidated by treating @@ -479,6 +510,7 @@ in Octave. Examples of effects of assumed zeros vs. numerical zeros: + @example Inf * eye (3) @result{}
--- a/doc/interpreter/diffeq.txi +++ b/doc/interpreter/diffeq.txi @@ -50,6 +50,7 @@ dt @end group @end example + @end ifnottex @noindent @@ -122,6 +123,7 @@ @example 0 = f (x-dot, x, t), x(t=0) = x_0, x-dot(t=0) = x-dot_0 @end example + @end ifnottex @noindent @@ -133,14 +135,14 @@ @math{x-dot} @end ifnottex is the derivative of @math{x}. The equation is solved using Petzold's -DAE solver @sc{Daspk}. +DAE solver @sc{daspk}. @DOCSTRING(daspk) @DOCSTRING(daspk_options) -Octave also includes @sc{Dassl}, an earlier version of @var{Daspk}, -and @var{dasrt}, which can be used to solve DAEs with constraints +Octave also includes @sc{dassl}, an earlier version of @sc{daspk}, +and @sc{dasrt}, which can be used to solve DAEs with constraints (stopping conditions). @DOCSTRING(dassl) @@ -153,4 +155,4 @@ See K. E. Brenan, et al., @cite{Numerical Solution of Initial-Value Problems in Differential-Algebraic Equations}, North-Holland (1989) for -more information about the implementation of @sc{Dassl}. +more information about the implementation of @sc{dassl}.
--- a/doc/interpreter/dynamic.txi +++ b/doc/interpreter/dynamic.txi @@ -39,16 +39,19 @@ @itemize @bullet @item Can I get the same functionality using the Octave scripting language only? + @item Is it thoroughly optimized Octave code? Vectorization of Octave code, doesn't just make it concise, it generally significantly improves its performance. Above all, if loops must be used, make sure that the allocation of space for variables takes place outside the loops using an assignment to a matrix of the right size, or zeros. + @item Does it make as much use as possible of existing built-in library routines? These are highly optimized and many do not carry the overhead of being interpreted. + @item Does writing a dynamically linked function represent useful investment of your time, relative to staying in Octave? @@ -96,7 +99,7 @@ @DOCSTRING(mkoctfile) -Consider the short example +Consider the short example: @example @group @@ -115,9 +118,12 @@ @enumerate 1 @item The function name as it will be seen in Octave, + @item The list of arguments to the function of type @code{octave_value_list}, + @item The number of output arguments, which can and often is omitted if not used, and + @item The string that will be seen as the help text of the function. @end enumerate @@ -128,9 +134,9 @@ name. Firstly, it must be a valid Octave function name and so must be a sequence of letters, digits and underscores, not starting with a digit. Secondly, as Octave uses the function name to define the filename -it attempts to find the function in, the function name in the @w{@code{DEFUN_DLD}} -macro must match the filename of the oct-file. Therefore, the above -function should be in a file @file{helloworld.cc}, and it should be +it attempts to find the function in, the function name in the +@w{@code{DEFUN_DLD}} macro must match the filename of the oct-file. Therefore, +the above function should be in a file @file{helloworld.cc}, and it should be compiled to an oct-file using the command @example @@ -167,8 +173,10 @@ @table @code @item Matrix A double precision matrix class defined in dMatrix.h, + @item ComplexMatrix A complex matrix class defined in CMatrix.h, and + @item BoolMatrix A boolean matrix class defined in boolMatrix.h. @end table @@ -180,16 +188,20 @@ @table @code @item NDArray A double precision array class defined in @file{dNDArray.h} + @item ComplexNDarray A complex array class defined in @file{CNDArray.h} + @item boolNDArray A boolean array class defined in @file{boolNDArray.h} + @item int8NDArray @itemx int16NDArray @itemx int32NDArray @itemx int64NDArray 8, 16, 32 and 64-bit signed array classes defined in @file{int8NDArray.h}, @file{int16NDArray.h}, etc. + @item uint8NDArray @itemx uint16NDArray @itemx uint32NDArray @@ -212,6 +224,7 @@ @end example This can be used on all matrix and array types + @item Define the dimensions of the matrix or array with a dim_vector. For example @@ -225,8 +238,9 @@ @end example This can be used on all matrix and array types + @item -Define the number of rows and columns in the matrix. For example +Define the number of rows and columns in the matrix. For example: @example Matrix a (2, 2) @@ -238,7 +252,7 @@ These types all share a number of basic methods and operators, a selection of which include -@deftypefn Method T& {operator ()} (octave_idx_type) +@deftypefn Method T& {operator ()} (octave_idx_type) @deftypefnx Method T& elem (octave_idx_type) The @code{()} operator or @code{elem} method allow the values of the matrix or array to be read or set. These can take a single argument, @@ -345,7 +359,7 @@ @subsection Character Strings in Oct-Files In Octave a character string is just a special @code{Array} class. -Consider the example +Consider the example: @example @EXAMPLEFILE(stringdemo.cc) @@ -387,7 +401,7 @@ Note however, that both types of strings are represented by the @code{charNDArray} type, and so when assigning to an -@code{octave_value}, the type of string should be specified. For example +@code{octave_value}, the type of string should be specified. For example: @example @group @@ -483,8 +497,10 @@ @table @code @item SparseMatrix A double precision sparse matrix class + @item SparseComplexMatrix A complex sparse matrix class + @item SparseBoolMatrix A boolean sparse matrix class @end table @@ -792,7 +808,7 @@ available from the Octave are equally available with oct-files. The basic means of extracting a sparse matrix from an @code{octave_value} and returning them as an @code{octave_value}, can be seen in the -following example +following example. @example @group @@ -857,8 +873,11 @@ @enumerate 1 @item Function Handle + @item Anonymous Function Handle + @item Inline Function + @item String @end enumerate @@ -1026,14 +1045,14 @@ purposes of parameter checking. These include the methods of the octave_value class like @code{is_real_matrix}, etc., but equally include more specialized functions. Some of the more common ones are -demonstrated in the following example +demonstrated in the following example. @example @EXAMPLEFILE(paramdemo.cc) @end example @noindent -and an example of its use is +An example of its use is: @example @group @@ -1053,7 +1072,7 @@ C++ exception handler, where memory allocated by the C++ new/delete methods are automatically released when the exception is treated. When writing an oct-file, to allow Octave to treat the user typing @kbd{Control-C}, -the @w{@code{OCTAVE_QUIT}} macro is supplied. For example +the @w{@code{OCTAVE_QUIT}} macro is supplied. For example: @example @group @@ -1065,19 +1084,19 @@ @end group @end example -The presence of the @w{@code{OCTAVE_QUIT}} macro in the inner loop allows Octave to -treat the user request with the @kbd{Control-C}. Without this macro, the user -must either wait for the function to return before the interrupt is +The presence of the @w{@code{OCTAVE_QUIT}} macro in the inner loop allows +Octave to treat the user request with the @kbd{Control-C}. Without this macro, +the user must either wait for the function to return before the interrupt is processed, or press @kbd{Control-C} three times to force Octave to exit. -The @w{@code{OCTAVE_QUIT}} macro does impose a very small speed penalty, and so for -loops that are known to be small it might not make sense to include +The @w{@code{OCTAVE_QUIT}} macro does impose a very small speed penalty, and so +for loops that are known to be small it might not make sense to include @w{@code{OCTAVE_QUIT}}. When creating an oct-file that uses an external libraries, the function might spend a significant portion of its time in the external -library. It is not generally possible to use the @w{@code{OCTAVE_QUIT}} macro in -this case. The alternative in this case is +library. It is not generally possible to use the @w{@code{OCTAVE_QUIT}} macro +in this case. The alternative in this case is @example @group @@ -1103,7 +1122,7 @@ @EXAMPLEFILE(unwinddemo.cc) @end example -As can be seen in the example +As can be seen in the example: @example @group @@ -1130,7 +1149,7 @@ The major issue is that the help string will typically be longer than a single line of text, and so the formatting of long help strings need to be taken into account. There are several manners in which to treat this -issue, but the most common is illustrated in the following example +issue, but the most common is illustrated in the following example, @example @group @@ -1228,7 +1247,7 @@ Octave file "Matrix.h" with operating systems and compilers that don't distinguish between filenames in upper and lower case -Consider the short example +Consider the short example: @example @group @@ -1338,7 +1357,7 @@ function @code{mxGetPi} that get the imaginary part. Both of these functions are for use only with double precision matrices. There also exists the generic function @code{mxGetData} and @code{mxGetImagData} -that perform the same operation on all matrix types. For example +that perform the same operation on all matrix types. For example: @example @group
--- a/doc/interpreter/emacs.txi +++ b/doc/interpreter/emacs.txi @@ -41,7 +41,7 @@ Octave Support''). This chapter describes how to set up and use this package. -Please contact <Kurt.Hornik@@wu-wien.ac.at> if you have any questions +Please contact @email{Kurt.Hornik@@wu-wien.ac.at} if you have any questions or suggestions on using EOS. @menu @@ -145,13 +145,13 @@ Move backward to the beginning of a function (@code{octave-beginning-of-defun}). With prefix argument @var{N}, do it that many times if @var{N} is -positive; otherwise, move forward to the @var{N}-th following beginning +positive; otherwise, move forward to the @var{N}-th following beginning of a function. @item M-C-e Move forward to the end of a function (@code{octave-end-of-defun}). With prefix argument @var{N}, do it that many times if @var{N} is -positive; otherwise, move back to the @var{N}-th preceding end of a +positive; otherwise, move back to the @var{N}-th preceding end of a function. @item M-C-h @@ -194,7 +194,7 @@ @item C-c C-a Move to the `real' beginning of the current line (@code{octave-beginning-of-line}). If point is in an empty or comment -line, simply go to its beginning; otherwise, move backwards to the +line, simply go to its beginning; otherwise, move backwards to the beginning of the first code line which is not inside a continuation statement, i.e., which does not follow a code line ending in @samp{...} or @samp{\}, or is inside an open parenthesis list. @@ -221,7 +221,7 @@ @item C-c M-C-d Move forward down one begin-end block level of Octave code (@code{octave-down-block}). With numeric prefix argument, do it that -many times; a negative argument means move backward, but still go down +many times; a negative argument means move backward, but still go down one level. @item C-c M-C-u @@ -268,7 +268,7 @@ is because the standard Emacs convention is that @key{RET} (aka @kbd{C-m}) just adds a newline, whereas @key{LFD} (aka @kbd{C-j}) adds a newline and indents it. This is particularly inconvenient for users with -keyboards which do not have a special @key{LFD} key at all; in such +keyboards which do not have a special @key{LFD} key at all; in such cases, it is typically more convenient to use @key{RET} as the @key{LFD} key (rather than typing @kbd{C-j}). @@ -290,7 +290,7 @@ (this works for all modes by adding to the startup hooks, without having to know the particular binding of @key{RET} in that mode!). Similar considerations apply for using @key{M-RET} as @key{M-LFD}. As Barry -A. Warsaw <bwarsaw@@cnri.reston.va.us> says in the documentation for his +A. Warsaw @email{bwarsaw@@cnri.reston.va.us} says in the documentation for his @code{cc-mode}, ``This is a very common question. @code{:-)} If you want this to be the default behavior, don't lobby me, lobby RMS!'' @@ -333,15 +333,19 @@ @itemize @bullet @item strings in @code{font-lock-string-face} + @item comments in @code{font-lock-comment-face} + @item the Octave reserved words (such as all block keywords) and the text functions (such as @samp{cd} or @samp{who}) which are also reserved using @code{font-lock-keyword-face} + @item the built-in operators (@samp{&&}, @samp{==}, @dots{}) using @code{font-lock-reference-face} + @item and the function names in function declarations in @code{font-lock-function-name-face}. @@ -405,21 +409,27 @@ With positive prefix argument @var{N}, send that many lines. If @code{octave-send-line-auto-forward} is non-@code{nil}, go to the next unsent code line. + @item C-c i b Send the current block to the inferior Octave process (@code{octave-send-block}). + @item C-c i f Send the current function to the inferior Octave process (@code{octave-send-defun}). + @item C-c i r Send the region to the inferior Octave process (@code{octave-send-region}). + @item C-c i s Make sure that `inferior-octave-buffer' is displayed (@code{octave-show-process-buffer}). + @item C-c i h Delete all windows that display the inferior Octave buffer (@code{octave-hide-process-buffer}). + @item C-c i k Kill the inferior Octave process and its buffer (@code{octave-kill-process}). @@ -447,7 +457,7 @@ as a list of strings. For example, to suppress the startup message and use `traditional' mode, set this to @code{'("-q" "--traditional")}. You can also specify a startup file of Octave commands to be loaded on -startup; note that these commands will not produce any visible output +startup; note that these commands will not produce any visible output in the process buffer. Which file to use is controlled by the variable @code{inferior-octave-startup-file}. If this is @code{nil}, the file @file{~/.emacs-octave} is used if it exists.
--- a/doc/interpreter/errors.txi +++ b/doc/interpreter/errors.txi @@ -85,6 +85,7 @@ message. Consider the following function. + @example @group ## -*- texinfo -*-
--- a/doc/interpreter/eval.txi +++ b/doc/interpreter/eval.txi @@ -111,7 +111,7 @@ as C. Consider how you might write @code{save} and @code{load} as -m-files. For example, +m-files. For example: @example @group
--- a/doc/interpreter/expr.txi +++ b/doc/interpreter/expr.txi @@ -60,6 +60,7 @@ expression, the elements of the matrix are taken in column-first order; the dimensions of the output match those of the index expression. For example, + @example @group a (2) # a scalar @@ -70,7 +71,8 @@ As a special case, when a colon is used as a single index, the output is a column vector containing all the elements of the vector or matrix. -For example +For example: + @example a (:) # a column vector @end example @@ -97,11 +99,11 @@ In general, an array with @samp{n} dimensions can be indexed using @samp{m} indices. If @code{n == m}, each index corresponds to its respective dimension. -The set of index tuples determining the result is formed by the Cartesian product -of the index vectors (or ranges or scalars). -If @code{n < m}, then the array is padded by trailing singleton dimensions. -If @code{n > m}, the last @code{n-m+1} dimensions are folded into a single -dimension with extent equal to product of extents of the original dimensions. +The set of index tuples determining the result is formed by the Cartesian +product of the index vectors (or ranges or scalars). If @code{n < m}, then the +array is padded by trailing singleton dimensions. If @code{n > m}, the last +@code{n-m+1} dimensions are folded into a single dimension with extent equal to +product of extents of the original dimensions. @c FIXED -- sections on variable prefer_zero_one_indexing were removed @@ -142,8 +144,8 @@ It should be, noted that @code{ones (1, n)} (a row vector of ones) results in a range (with zero increment), and is therefore more efficient when used in index -expression than other forms of @dfn{ones}. In particular, when @samp{r} is a row -vector, the expressions +expression than other forms of @dfn{ones}. In particular, when @samp{r} is a +row vector, the expressions @example r(ones (1, n), :) @@ -499,7 +501,7 @@ The implementation of this operator needs to be improved. @item @var{x} .^ @var{y} -@item @var{x} .** @var{y} +@itemx @var{x} .** @var{y} @opindex .** @opindex .^ Element by element power operator. If both operands are matrices, the @@ -575,7 +577,7 @@ All of Octave's comparison operators return a value of 1 if the comparison is true, or 0 if it is false. For matrix values, they all -work on an element-by-element basis. For example, +work on an element-by-element basis. For example: @example @group @@ -620,14 +622,17 @@ For complex numbers, the following ordering is defined: @var{z1} < @var{z2} iff + @example @group abs(@var{z1}) < abs(@var{z2}) || (abs(@var{z1}) == abs(@var{z2}) && arg(@var{z1}) < arg(@var{z2})) @end group @end example -This is consistent with the ordering used by @dfn{max}, @dfn{min} and @dfn{sort}, -but is not consistent with @sc{matlab}, which only compares the real parts. + +This is consistent with the ordering used by @dfn{max}, @dfn{min} and +@dfn{sort}, but is not consistent with @sc{matlab}, which only compares the real +parts. String comparisons may also be performed with the @code{strcmp} function, not with the comparison operators listed above. @@ -1009,8 +1014,8 @@ This is cleaner and more memory efficient than using a dummy variable. The @code{nargout} value for the right-hand side expression is not affected. -If the assignment is used as an expression, the return value is a comma-separated list -with the ignored values dropped. +If the assignment is used as an expression, the return value is a +comma-separated list with the ignored values dropped. @opindex += A very common programming pattern is to increment an existing variable
--- a/doc/interpreter/func.txi +++ b/doc/interpreter/func.txi @@ -350,7 +350,7 @@ Sometimes the number of input arguments is not known when the function is defined. As an example think of a function that returns the smallest -of all its input arguments. For example, +of all its input arguments. For example: @example @group @@ -440,9 +440,9 @@ @node Ignoring Arguments @section Ignoring Arguments -In the formal argument list, it is possible to use the dummy placeholder @code{~} -instead of a name. This indicates that the corresponding argument value should be ignored -and not stored to any variable. +In the formal argument list, it is possible to use the dummy placeholder +@code{~} instead of a name. This indicates that the corresponding argument +value should be ignored and not stored to any variable. @example @group @@ -568,6 +568,7 @@ As an example, the following function implements a variant of the classic ``Hello, World'' program. + @example @group function hello (who = "World") @@ -578,6 +579,7 @@ @noindent When called without an input argument the function prints the following + @example @group hello (); @@ -587,6 +589,7 @@ @noindent and when it's called with an input argument it prints the following + @example @group hello ("Beautiful World of Free Software"); @@ -597,6 +600,7 @@ Sometimes it is useful to explicitly tell Octave to use the default value of an input argument. This can be done writing a @samp{:} as the value of the input argument when calling the function. + @example @group hello (:); @@ -759,7 +763,7 @@ the functions needing access to this helper function are found. As a simple example, consider a function @code{func1}, that calls a helper -function @code{func2} to do much of the work. For example +function @code{func2} to do much of the work. For example: @example @group @@ -781,7 +785,7 @@ The @code{dispatch} function can be used to alias one function name to another. It can be used to alias all calls to a particular function name to another function, or the alias can be limited to only a particular -variable type. Consider the example +variable type. Consider the example, @example @group @@ -798,8 +802,8 @@ @end example @noindent -which aliases the user-defined function @code{spsin} to @code{sin}, but only for real sparse -matrices. Note that the builtin @code{sin} already correctly treats +which aliases the user-defined function @code{spsin} to @code{sin}, but only for +real sparse matrices. Note that the builtin @code{sin} already correctly treats sparse matrices and so this example is only illustrative. @DOCSTRING(dispatch) @@ -1076,19 +1080,19 @@ @end example @noindent -For example +For example, @example f = @@sin; @end example @noindent -Creates a function handle called @code{f} that refers to the +creates a function handle called @code{f} that refers to the function @code{sin}. Function handles are used to call other functions indirectly, or to pass a function as an argument to another function like @code{quad} or -@code{fsolve}. For example +@code{fsolve}. For example: @example @group @@ -1101,7 +1105,7 @@ You may use @code{feval} to call a function using function handle, or simply write the name of the function handle followed by an argument list. If there are no arguments, you must use an empty argument list -@samp{()}. For example +@samp{()}. For example: @example @group
--- a/doc/interpreter/image.txi +++ b/doc/interpreter/image.txi @@ -173,9 +173,9 @@ An additional colormap is @code{gmap40}. This code map contains only colors with integer values of the red, green and blue components. This -is a workaround for a limitation of gnuplot 4.0, that does not allow the color of -line or patch objects to be set, and so @code{gmap40} is useful for -gnuplot 4.0 users, and in particular in conjunction with the @var{bar}, +is a workaround for a limitation of gnuplot 4.0, that does not allow the color +of line or patch objects to be set, and so @code{gmap40} is useful for gnuplot +4.0 users, and in particular in conjunction with the @var{bar}, @var{barh} or @var{contour} functions. @DOCSTRING(gmap40)
--- a/doc/interpreter/install.txi +++ b/doc/interpreter/install.txi @@ -93,9 +93,9 @@ @item --enable-dl Use @code{dlopen} and friends to make Octave capable of dynamically linking externally compiled functions (this is the default if -@code{--enable-shared} is specified). This option only works on systems +@option{--enable-shared} is specified). This option only works on systems that actually have these functions. If you plan on using this feature, you -should probably also use @code{--enable-shared} to reduce the size of +should probably also use @option{--enable-shared} to reduce the size of your @file{.oct} files. @item --without-blas @@ -106,21 +106,21 @@ an optimized @sc{blas} will generally result in several-times faster matrix operations.) Only use this option if your system has @sc{blas}/@sc{lapack} libraries that cause problems for some reason. You can also use -@code{--with-blas=lib} to specify a particular @sc{blas} library +@option{--with-blas=lib} to specify a particular @sc{blas} library that configure doesn't check for automatically. @item --without-ccolamd -Don't use CCOLAMD, disable some sparse matrix functionality. +Don't use @sc{ccolamd}, disable some sparse matrix functionality. @item --without-colamd -Don't use COLAMD, disable some sparse matrix functionality. +Don't use @sc{colamd}, disable some sparse matrix functionality. @item --without-curl Don't use the cURL, disable the ftp objects, @code{urlread} and @code{urlwrite} functions. @item --without-cxsparse -Don't use CXSPARSE, disable some sparse matrix functionality. +Don't use @sc{cxsparse}, disable some sparse matrix functionality. @item --without-umfpack Don't use @sc{umfpack}, disable some sparse matrix functionality. @@ -129,10 +129,10 @@ Use the included @sc{fftpack} library instead of the @sc{fftw} library. @item --without-glpk -Don't use the GLPK library for linear programming. +Don't use the @sc{glpk} library for linear programming. @item --without-hdf5 -Don't use the HDF5 library for reading and writing HDF5 files. +Don't use the @sc{hdf5} library for reading and writing @sc{hdf5} files. @item --without-zlib Don't use the zlib library, disable data file compression and support @@ -146,20 +146,20 @@ an optimized @sc{blas} will generally result in several-times faster matrix operations.) Only use this option if your system has @sc{blas}/@sc{lapack} libraries that cause problems for some reason. You can also use -@code{--with-blas=lib} to specify a particular @sc{blas} library +@option{--with-blas=lib} to specify a particular @sc{blas} library that configure doesn't check for automatically. @item --without-framework-carbon Don't use framework Carbon headers, libraries and specific source code for compilation even if the configure test succeeds (the default value -is @code{--with-framework-carbon}). This is a platform specific configure +is @option{--with-framework-carbon}). This is a platform specific configure option for Mac systems. @item --without-framework-opengl Don't use framework OpenGL headers, libraries and specific source code for compilation even if the configure test succeeds. If this option is given then OpenGL headers and libraries in standard system locations are -tested (the default value is @code{--with-framework-opengl}). This is a +tested (the default value is @option{--with-framework-opengl}). This is a platform specific configure option for Mac systems. @item --help @@ -434,7 +434,7 @@ @noindent when compiling @file{Array.cc} and @file{Matrix.cc}, try recompiling -these files without @code{-g}. +these files without @option{-g}. @item Some people have reported that calls to shell_cmd and the pager do not @@ -456,7 +456,7 @@ @noindent which are part of @file{libposix.a}. Unfortunately, linking Octave with -@code{-posix} results in the following undefined symbols. +@option{-posix} results in the following undefined symbols. @example @group @@ -500,10 +500,10 @@ directory to the include search path by specifying (for example) @code{CPPFLAGS=-I/some/nonstandard/directory} as an argument to @code{configure}. Other variables that can be specified this way are -@code{CFLAGS}, @code{CXXFLAGS}, @code{FFLAGS}, and @code{LDFLAGS}. +@env{CFLAGS}, @env{CXXFLAGS}, @env{FFLAGS}, and @env{LDFLAGS}. Passing them as options to the configure script also records them in the -@file{config.status} file. By default, @code{CPPFLAGS} and -@code{LDFLAGS} are empty, @code{CFLAGS} and @code{CXXFLAGS} are set to -@code{"-g -O"} and @code{FFLAGS} is set to @code{"-O"}. +@file{config.status} file. By default, @env{CPPFLAGS} and +@env{LDFLAGS} are empty, @env{CFLAGS} and @env{CXXFLAGS} are set to +@code{"-g -O"} and @env{FFLAGS} is set to @code{"-O"}. @end itemize
--- a/doc/interpreter/interp.txi +++ b/doc/interpreter/interp.txi @@ -115,10 +115,12 @@ @noindent @ifinfo -which demonstrates the poor behavior of Fourier interpolation for non-periodic functions. +which demonstrates the poor behavior of Fourier interpolation for non-periodic +functions. @end ifinfo @ifnotinfo -which demonstrates the poor behavior of Fourier interpolation for non-periodic functions, as can be seen in @ref{fig:interpft}. +which demonstrates the poor behavior of Fourier interpolation for non-periodic +functions, as can be seen in @ref{fig:interpft}. @float Figure,fig:interpft @center @image{interpft,4in} @@ -146,13 +148,13 @@ @DOCSTRING(interpn) A significant difference between @code{interpn} and the other two -multidimensional interpolation functions is the fashion in which the +multi-dimensional interpolation functions is the fashion in which the dimensions are treated. For @code{interp2} and @code{interp3}, the 'y' axis is considered to be the columns of the matrix, whereas the 'x' axis corresponds to the rows of the array. As Octave indexes arrays in column major order, the first dimension of any array is the columns, and so @code{interpn} effectively reverses the 'x' and 'y' dimensions. -Consider the example +Consider the example, @example @group
--- a/doc/interpreter/intro.txi +++ b/doc/interpreter/intro.txi @@ -197,22 +197,21 @@ A simple example comes from chemistry and the need to obtain balanced chemical equations. Consider the burning of hydrogen and oxygen to produce water. - @tex $$ {\rm H_{2}} + {\rm O_{2}} \rightarrow {\rm H_{2}O} $$ @end tex @ifnottex + @example H2 + O2 --> H2O @end example + @end ifnottex - @noindent The equation above is not accurate. The Law of Conservation of Mass requires that the number of molecules of each type balance on the left- and right-hand sides of the equation. Writing the variable overall reaction with individual equations for hydrogen and oxygen one finds: - @tex \vbox{ $$ x_{1}{\rm H_{2}} + x_{2}{\rm O_{2}} \rightarrow {\rm H_{2}O} $$ @@ -221,6 +220,7 @@ } @end tex @ifnottex + @example @group x1*H2 + x2*O2 --> H2O @@ -228,8 +228,8 @@ O: 0*x1 + 2*x2 --> 1 @end group @end example + @end ifnottex - @noindent The solution in Octave is found in just three steps. @@ -266,8 +266,8 @@ @example x(t = t0) = x0 @end example + @end ifnottex - @noindent For Octave to integrate equations of this form, you must first provide a definition of the function @@ -444,7 +444,7 @@ @cindex documentation notation In the examples in this manual, results from expressions that you -evaluate are indicated with @samp{@result{}}. For example, +evaluate are indicated with @samp{@result{}}. For example: @example @group @@ -483,7 +483,7 @@ Sometimes to help describe one expression, another expression is shown that produces identical results. The exact equivalence of -expressions is indicated with @samp{@equiv{}}. For example, +expressions is indicated with @samp{@equiv{}}. For example: @example @group
--- a/doc/interpreter/io.txi +++ b/doc/interpreter/io.txi @@ -92,7 +92,7 @@ used to force output to be sent to the pager (or any other stream) immediately. -You can select the program to run as the pager using the @code{PAGER} +You can select the program to run as the pager using the @env{PAGER} function, and you can turn paging off by using the function @code{more}. @@ -449,7 +449,7 @@ When given a matrix value, Octave's formatted output functions cycle through the format template until all the values in the matrix have been -printed. For example, +printed. For example: @example @group @@ -465,7 +465,7 @@ functions do not return to the beginning of the format template when moving on from one value to the next. This can lead to confusing output if the number of elements in the matrices are not exact multiples of the -number of conversions in the format template. For example, +number of conversions in the format template. For example: @example @group
--- a/doc/interpreter/linalg.txi +++ b/doc/interpreter/linalg.txi @@ -55,11 +55,11 @@ @c or lower triangular matrix with row permutations, perform a forward or @c backward substitution, and goto 5. -@item If the matrix is square, hermitian with a real positive diagonal, +@item If the matrix is square, Hermitian with a real positive diagonal, attempt Cholesky factorization using the @sc{lapack} xPOTRF function. @item If the Cholesky factorization failed or the matrix is not -hermitian with a real positive diagonal, and the matrix is square, factorize +Hermitian with a real positive diagonal, and the matrix is square, factorize using the @sc{lapack} xGETRF function. @item If the matrix is not square, or any of the previous solvers flags
--- a/doc/interpreter/matrix.txi +++ b/doc/interpreter/matrix.txi @@ -238,7 +238,7 @@ single element of a random sequence. The original @code{rand} and @code{randn} functions use Fortran code from -@sc{Ranlib}, a library of Fortran routines for random number generation, +@sc{ranlib}, a library of Fortran routines for random number generation, compiled by Barry W. Brown and James Lovato of the Department of Biomathematics at The University of Texas, M.D. Anderson Cancer Center, Houston, TX 77030.
--- a/doc/interpreter/nonlin.txi +++ b/doc/interpreter/nonlin.txi @@ -32,6 +32,7 @@ @example F (x) = 0 @end example + @end ifnottex @noindent @@ -57,6 +58,7 @@ 3x^2 - 2xy^2 + 3 cos(x) = -4 @end group @end example + @end ifnottex @noindent @@ -103,7 +105,7 @@ A value of @code{info = 1} indicates that the solution has converged. The function @code{perror} may be used to print English messages -corresponding to the numeric error codes. For example, +corresponding to the numeric error codes. For example: @example @group
--- a/doc/interpreter/numbers.txi +++ b/doc/interpreter/numbers.txi @@ -133,6 +133,7 @@ @end group @end example + @end ifnottex Elements of a matrix may be arbitrary expressions, provided that the @@ -340,6 +341,7 @@ [](mx0) * [](0xn) = 0(mxn) @end group @end example + @end ifnottex By default, dimensions of the empty matrix are printed along with the @@ -416,7 +418,8 @@ range elements. However, ranges with zero increment (i.e., all elements equal) are useful, especially in indexing, and Octave allows them to be constructed using the built-in function @dfn{ones}. Note that because a range must be a row -vector, @samp{ones (1, 10)} produces a range, while @samp{ones (10, 1)} does not. +vector, @samp{ones (1, 10)} produces a range, while @samp{ones (10, 1)} does +not. When Octave parses a range expression, it examines the elements of the expression to determine whether they are all constants. If they are, it @@ -432,7 +435,7 @@ @DOCSTRING(single) -for example +for example: @example @group @@ -618,7 +621,7 @@ Bits that are shifted out of either end of the value are lost. Octave also uses arithmetic shifts, where the sign bit of the value is kept -during a right shift. For example +during a right shift. For example: @example @group @@ -681,7 +684,7 @@ @node Promotion and Demotion of Data Types @section Promotion and Demotion of Data Types -Many operators and functions can work with mixed data types. For example +Many operators and functions can work with mixed data types. For example, @example @group @@ -745,7 +748,7 @@ where the returned value is single precision. In the case of mixed type indexed assignments, the type is not -changed. For example +changed. For example, @example @group
--- a/doc/interpreter/optim.txi +++ b/doc/interpreter/optim.txi @@ -51,16 +51,18 @@ $$ @end tex @ifnottex + @example min C'*x @end example + @end ifnottex subject to the linear constraints @tex $Ax = b$ where $x \geq 0$. @end tex @ifnottex -@math{A*x = b} where @math{x >= 0}. +@math{A*x = b} where @math{x @geq{} 0}. @end ifnottex @noindent @@ -78,9 +80,11 @@ $$ @end tex @ifnottex + @example min 0.5 x'*H*x + x'*q @end example + @end ifnottex subject to @tex @@ -89,6 +93,7 @@ $$ @end tex @ifnottex + @example @group A*x = b @@ -96,6 +101,7 @@ A_lb <= A_in*x <= A_ub @end group @end example + @end ifnottex @DOCSTRING(qp)
--- a/doc/interpreter/package.txi +++ b/doc/interpreter/package.txi @@ -95,7 +95,7 @@ depends on another, it will check if that package is installed during installation. If it is not, an error will be reported and the package will not be installed. This behavior can be disabled -by passing the @code{-nodeps} flag to the @code{pkg install} +by passing the @option{-nodeps} flag to the @code{pkg install} command @example @@ -272,7 +272,7 @@ @item package/bin An optional directory containing files that will be added to the -Octave @w{@code{EXEC_PATH}} when the package is loaded. This might contain +Octave @w{@env{EXEC_PATH}} when the package is loaded. This might contain external scripts, etc., called by functions within the package. @end table @@ -442,7 +442,7 @@ @end itemize @noindent -The format can be summarized with the following example +The format can be summarized with the following example. @example @group @@ -488,7 +488,7 @@ Sometimes functions are only partially compatible, in which case you can list the non-compatible cases separately. To refer to another function in the package, use @code{<f>fn</f>}. -For example, +For example: @example eig (a, b) = use <f>qz</f> @@ -504,7 +504,7 @@ @noindent defines the macro id. You can use @code{$id} anywhere in the -description and it will be expanded. For example, +description and it will be expanded. For example: @example @group
--- a/doc/interpreter/plot.txi +++ b/doc/interpreter/plot.txi @@ -34,8 +34,9 @@ Earlier versions of Octave provided plotting through the use of gnuplot. This capability is still available. But, a newer plotting -capability is provided by access to OpenGL. Which plotting system -is used is controlled by the @code{backend} function. (See @ref{Graphics Backends}.) +capability is provided by access to OpenGL@. Which plotting system +is used is controlled by the @code{backend} function. (See @ref{Graphics +Backends}.) The function call @code{backend("fltk")} selects the fltk/OpenGL system, and @code{backend("gnuplot")} selects the gnuplot system. @@ -301,7 +302,7 @@ plot of contours for the surface. The @code{plot3} function displays arbitrary three-dimensional data, -without requiring it to form a surface. For example +without requiring it to form a surface. For example, @example @group @@ -317,7 +318,7 @@ @float Figure,fig:plot3 @center @image{plot3,4in} -@caption{Three dimensional spiral.} +@caption{Three-dimensional spiral.} @end float Finally, the @code{view} function changes the viewpoint for @@ -390,7 +391,7 @@ @subsection Plot Annotations You can add titles, axis labels, legends, and arbitrary text to an -existing plot. For example, +existing plot. For example: @example @group @@ -458,7 +459,7 @@ @subsection Multiple Plot Windows You can open multiple plot windows using the @code{figure} function. -For example +For example, @example @group @@ -575,7 +576,7 @@ @end multitable These are be used in conjunction with the @{ and @} characters to limit -the change in the font to part of the string. For example +the change in the font to part of the string. For example, @example xlabel ('@{\bf H@} = a @{\bf V@}') @@ -862,11 +863,11 @@ Each of these objects has a function by the same name. and, each of these functions returns a graphics handle pointing to an object of corresponding type. In addition there are several functions -which operate on properties of the graphics objects and which return handles: the functions @code{ plot} -and @code{plot3} -return a handle pointing to an object of type line, the function @code{subplot} -returns a handle pointing to an object of type axes, the function @code{fill} returns a -handle pointing to an object of type patch, the functions @code{area}, @code{bar}, +which operate on properties of the graphics objects and which return handles: +the functions @code{ plot} and @code{plot3} return a handle pointing to an +object of type line, the function @code{subplot} returns a handle pointing to an +object of type axes, the function @code{fill} returns a handle pointing to an +object of type patch, the functions @code{area}, @code{bar}, @code{barh}, @code{contour}, @code{contourf}, @code{contour3}, @code{surf}, @code{mesh}, @code{surfc}, @code{meshc}, @code{errorbar}, @code{quiver}, @code{quiver3}, @code{scatter}, @code{scatter3}, @@ -887,24 +888,24 @@ @code{line}, @code{text}, @code{patch}, @code{surface}, and @code{image} objects. -Graphics handles may be distinguished from function handles (@ref{Function Handles}) -by means of the function @code{ishandle()}. @code{ishandle} returns true if its -argument is a handle of a graphics object. In addition, the figure object -may be tested using @code{isfigure()}. @code{isfigure} returns true only if its -argument is a handle of a figure. -ishghandle() is synonymous with ishandle(). The @code{whos} function can be used -to show the object type of each currently defined graphics handle. (Note: this is -not true today, but it is, I hope, considered an error in whos. It may be better -to have whos just show graphics_handle as the class, and provide a new function -which, given a graphics handle, returns its object type. This could generalize -the ishandle() functions and, in fact, replace them.) +Graphics handles may be distinguished from function handles (@ref{Function +Handles}) by means of the function @code{ishandle()}. @code{ishandle} returns +true if its argument is a handle of a graphics object. In addition, the figure +object may be tested using @code{isfigure()}. @code{isfigure} returns true only +if its argument is a handle of a figure. ishghandle() is synonymous with +ishandle(). The @code{whos} function can be used to show the object type of +each currently defined graphics handle. (Note: this is not true today, but it +is, I hope, considered an error in whos. It may be better to have whos just +show graphics_handle as the class, and provide a new function which, given a +graphics handle, returns its object type. This could generalize the ishandle() +functions and, in fact, replace them.) The @code{get} and @code{set} commands are -used to obtain and set the values of properties of graphics objects. In addition, -the @code{get} command may be used to obtain property names. - -For example, the property "type" of the graphics object pointed to by the graphics -handle h may be displayed by: +used to obtain and set the values of properties of graphics objects. In +addition, the @code{get} command may be used to obtain property names. + +For example, the property "type" of the graphics object pointed to by the +graphics handle h may be displayed by: @code{get(h, "type")} @@ -1170,39 +1171,67 @@ @table @code @item __modified__ --- Values: "on," "off" + @item __myhandle__ + @item beingdeleted --- Values: "on," "off" + @item busyaction + @item buttondownfcn + @item callbackobject + @item children + @item clipping --- Values: "on," "off" + @item createfcn + @item currentfigure + @item deletefcn + @item handlevisibility --- Values: "on," "off" + @item hittest --- Values: "on," "off" + @item interruptible --- Values: "on," "off" + @item parent + @item screendepth + @item screenpixelsperinch + @item screensize + @item selected + @item selectionhighlight + @item screendepth + @item screenpixelsperinch + @item showhiddenhandles --- Values: "on," "off" + @item tag + @item type + @item uicontextmenu + @item units + @item userdata + @item visible @end table @@ -1214,50 +1243,80 @@ @table @code @item __backend__ --- The backend currently in use. + @item __enhanced__ + @item __modified__ + @item __myhandle__ + @item __plot_stream__ + @item alphamap + @item beingdeleted --- Values: "on," "off" + @item busyaction + @item buttondownfcn + @item children Handle to children. + @item clipping --- Values: "on," "off" + @item closerequestfcn --- Handle of function to call on close. + @item color + @item colormap An N-by-3 matrix containing the color map for the current axes. + @item paperorientation + @item createfcn + @item currentaxes Handle to graphics object of current axes. + @item currentcharacter + @item currentobject + @item currentpoint Holds the coordinates of the point over which the mouse pointer was when the mouse button was pressed. If a mouse callback function is defined, @code{"currentpoint"} holds the coordinates of the point over which the mouse pointer is when the function gets called. + @item deletefcn + @item dockcontrols --- Values: "on," "off" + @item doublebuffer --- Values: "on," "off" + @item filename + @item handlevisibility --- Values: "on," "off" + @item hittest + @item integerhandle + @item interruptible --- Values: "on," "off" + @item inverthardcopy + @item keypressfcn see @code{"keypressfcn"} + @item keyreleasefcn With @code{"keypressfcn"}, The keyboard callback functions. These callback functions get called when a key is pressed/released @@ -1267,68 +1326,111 @@ @table @code @item Character The ASCII value of the key + @item Key lowercase value of the key + @item Modifier A cell array containing strings representing the modifiers pressed with the key. Possible values are @code{"shift"}, @code{"alt"}, and @code{"control"}. @end table + @item menubar + @item mincolormap + @item name + @item nextplot May be one of @table @code @item "new" + @item "add" + @item "replace" + @item "replacechildren" @end table + @item numbertitle + @item paperorientation Indicates the orientation for printing. Either @code{"landscape"} or @code{"portrait"}. + @item paperposition + @item paperpositionmode + @item papersize + @item papertype + @item paperunits + @item pointer + @item pointershapecdata + @item pointershapehotspot + @item position + @item renderer + @item renderermode + @item resize + @item resizefcn + @item selected + @item selectionhighlight --- Values: "on," "off" + @item selectiontype + @item tag + @item toolbar + @item type + @item units + @item userdata + @item visible Either @code{"on"} or @code{"off"} to toggle display of the figure. + @item windowbuttondownfcn See @code{"windowbuttonupfcn"} + @item windowbuttonmotionfcn See @code{"windowbuttonupfcn"} + @item windowbuttonupfcn With @code{"windowbuttondownfcn"} and @code{"windowbuttonmotionfcn"}, The mouse callback functions. These callback functions get called when the mouse button is pressed, dragged, and released respectively. When these callback functions are called, the @code{"currentpoint"} property holds the current coordinates of the cursor. + @item windowbuttonwheelfcn + @item windowstyle + @item wvisual + @item wvisualmode + @item xdisplay + @item xvisual + @item xvisualmode @end table @@ -1339,42 +1441,68 @@ The @code{axes} properties are: @table @code @item __modified__ + @item __myhandle__ + @item activepositionproperty + @item alim + @item alimmode + @item ambientlightcolor + @item beingdeleted + @item box Box surrounding axes. --- Values: "on," "off" + @item busyaction + @item buttondownfcn + @item cameraposition + @item camerapositionmode + @item cameratarget + @item cameratargetmode + @item cameraupvector + @item cameraupvectormode + @item cameraviewangle + @item cameraviewanglemode + @item children + @item clim Two-element vector defining the limits for the c axis of an image. See @code{pcolor} property. Setting this property also forces the corresponding mode property to be set to @code{"manual"}. + @item climmode Either @code{"manual"} or @code{"auto"}. + @item clipping + @item color + @item colororder + @item createfcn + @item currentpoint Holds the coordinates of the point over which the mouse pointer was when the mouse button was pressed. If a mouse callback function is defined, @code{"currentpoint"} holds the coordinates of the point over which the mouse pointer is when the function gets called. + @item dataaspectratio A two-element vector specifying the relative height and width of the data displayed in the axes. Setting @code{dataaspectratio} to @samp{1, @@ -1382,48 +1510,74 @@ same as the length of 2 units on the x-axis. Setting @code{dataaspectratio} also forces the @code{dataaspectratiomode} property to be set to @code{"manual"}. + @item dataaspectratiomode Either @code{"manual"} or @code{"auto"}. + @item deletefcn + @item drawmode + @item fontangle + @item fontname + @item fontsize + @item fontunits + @item fontweight + @item gridlinestyle + @item handlevisibility + @item hittest + @item interpreter + @item interruptible + @item key Toggle display of the legend. --- Values: "on," "off" Note that this property is not compatible with @sc{matlab} and may be removed in a future version of Octave. + @item keybox Toggle display of a box around the legend. --- Values: "on," "off" Note that this property is not compatible with @sc{matlab} and may be removed in a future version of Octave. + @item keypos An integer from 1 to 4 specifying the position of the legend. 1 indicates upper right corner, 2 indicates upper left, 3 indicates lower left, and 4 indicates lower right. Note that this property is not compatible with @sc{matlab} and may be removed in a future version of Octave. + @item keyreverse + @item layer + @item linestyleorder + @item linewidth + @item minorgridlinestyle + @item nextplot May be one of @table @code @item "new" + @item "add" + @item "replace" + @item "replacechildren" @end table + @item outerposition A vector specifying the position of the plot, including titles, axes and legend. The four elements of the vector are the coordinates of the @@ -1432,9 +1586,13 @@ 0.3, 0.4, 0.5]} sets the lower left corner of the axes at @math{(0.2, 0.3)} and the width and height to be 0.4 and 0.5 respectively. See also the @code{position} property. + @item parent + @item plotboxaspectratio + @item plotboxaspectratiomode + @item position A vector specifying the position of the plot, excluding titles, axes and legend. The four elements of the vector are the coordinates of the @@ -1443,118 +1601,179 @@ 0.3, 0.4, 0.5]} sets the lower left corner of the axes at @math{(0.2, 0.3)} and the width and height to be 0.4 and 0.5 respectively. See also the @code{outerposition} property. + @item projection + @item selected + @item selectionhighlight + @item tag + @item tickdir + @item tickdirmode + @item ticklength + @item tightinset + @item title Index of text object for the axes title. + @item type + @item uicontextmenu + @item units + @item userdata + @item view A three element vector specifying the view point for three-dimensional plots. + @item visible Either @code{"on"} or @code{"off"} to toggle display of the axes. + @item x_normrendertransform + @item x_projectiontransform + @item x_rendertransform + @item x_viewporttransform + @item x_viewtransform + @item xaxislocation Either @code{"top"} or @code{"bottom"}. + @item xcolor + @item xdir Either @code{"forward"} or @code{"reverse"}. + @item xgrid Either @code{"on"} or @code{"off"} to toggle display of grid lines. + @item xlabel Indices to text objects for the axes labels. + @item xlim Two-element vector defining the limits for the x-axis. Setting this property also forces the corresponding mode property to be set to @code{"manual"}. + @item xlimmode Either @code{"manual"} or @code{"auto"}. + @item xminorgrid Either @code{"on"} or @code{"off"} to toggle display of minor grid lines. + @item xminortick + @item xscale Either @code{"linear"} or @code{"log"}. + @item xtick Set position of tick marks. Setting this property also forces the corresponding mode property to be set to @code{"manual"}. + @item xticklabel Setting this property also forces the corresponding mode property to be set to @code{"manual"}. + @item xticklabelmode Either @code{"manual"} or @code{"auto"}. + @item xtickmode Either @code{"manual"} or @code{"auto"}. + @item yaxislocation Either @code{"left"} or @code{"right"} + @item ycolor + @item ydir Either @code{"forward"} or @code{"reverse"}. + @item ygrid Either @code{"on"} or @code{"off"} to toggle display of grid lines. + @item ylabel Indices to text objects for the axes labels. + @item ylim Two-element vectors defining the limits for the x, y, and z axes and the Setting one of these properties also forces the corresponding mode property to be set to @code{"manual"}. + @item ylimmode Either @code{"manual"} or @code{"auto"}. + @item yminorgrid Either @code{"on"} or @code{"off"} to toggle display of minor grid lines. + @item yminortick + @item yscale Either @code{"linear"} or @code{"log"}. + @item ytick Set position of tick marks. Setting this property also forces the corresponding mode property to be set to @code{"manual"}. + @item yticklabel Setting this property also forces the corresponding mode property to be set to @code{"manual"}. + @item yticklabelmode Either @code{"manual"} or @code{"auto"}. + @item ytickmode Either @code{"manual"} or @code{"auto"}. + @item zcolor + @item zdir Either @code{"forward"} or @code{"reverse"}. + @item zgrid Either @code{"on"} or @code{"off"} to toggle display of grid lines. + @item zlabel Indices to text objects for the axes labels. + @item zlim Two-element vector defining the limits for z-axis. Setting this property also forces the corresponding mode property to be set to @code{"manual"}. + @item zlimmode Either @code{"manual"} or @code{"auto"}. + @item zminorgrid Either @code{"on"} or @code{"off"} to toggle display of minor grid lines. + @item zminortick + @item zscale Either @code{"linear"} or @code{"log"}. + @item ztick Set position of tick marks. Setting this property also forces the corresponding mode property to be set to @code{"manual"}. + @item zticklabel Setting this property also forces the corresponding mode property to be set to @code{"manual"}. + @item zticklabelmode Either @code{"manual"} or @code{"auto"}. + @item ztickmode Either @code{"manual"} or @code{"auto"}. @@ -1567,65 +1786,111 @@ The @code{line} properties are: @table @code @item __modified__ + @item __myhandle__ + @item beingdeleted + @item busyaction + @item buttondownfcn + @item children + @item clipping + @item color The RGB color of the line, or a color name. @xref{Colors}. + @item createfcn + @item deletefcn + @item displayname + @item erasemode + @item handlevisibility + @item hittest + @item interpreter + @item interruptible + @item keylabel The text of the legend entry corresponding to this line. Note that this property is not compatible with @sc{matlab} and may be removed in a future version of Octave. + @item ldata The lower errorbar in the y direction to be plotted. + @item linestyle @itemx linewidth @xref{Line Styles}. + @item linewidth + @item marker + @item markeredgecolor + @item markerfacecolor + @item markersize @xref{Marker Styles}. + @item parent + @item selected + @item selectionhighlight + @item tag + @item type + @item udata The upper errorbar in the y direction to be plotted. + @item uicontextmenu + @item userdata + @item visible + @item xdata The data to be plotted. + @item xdatasource + @item xldata The lower errorbar to be plotted. + @item xlim + @item xliminclude + @item xudata The upper errorbar to be plotted. + @item ydata The data to be plotted. + @item ydatasource + @item ylim + @item yliminclude + @item zdata The data to be plotted. + @item zdatasource + @item zlim + @item zliminclude @end table @@ -1636,65 +1901,111 @@ The @code{text} properties are: @table @code @item __modified__ + @item __myhandle__ + @item backgroundcolor + @item beingdeleted + @item busyaction + @item buttondownfcn + @item children + @item clipping + @item color The color of the text. @xref{Colors}. + @item createfcn + @item deletefcn + @item displayname + @item edgecolor + @item editing + @item erasemode + @item fontangle Flag whether the font is italic or normal. Valid values are 'normal', 'italic' and 'oblique'. + @item fontname The font used for the text. + @item fontsize The size of the font, in points to use. + @item fontunits + @item fontweight Flag whether the font is bold, etc. Valid values are 'normal', 'bold', 'demi' or 'light'. + @item handlevisibility + @item hittest + @item horizontalalignment May be @code{"left"}, @code{"center"}, or @code{"right"}. + @item interpreter Determines how the text is rendered. Valid values are 'none', 'tex' or 'latex'. + @item interruptible + @item linestyle + @item linewidth + @item margin + @item parent + @item position The coordinates of the text object. + @item rotation The angle of rotation for the displayed text, measured in degrees. + @item selected + @item selectionhighlight + @item string The character string contained by the text object. + @item tag + @item type + @item uicontextmenu + @item units May be @code{"normalized"} or @code{"graph"}. + @item userdata + @item verticalalignment + @item visible + @item xlim + @item xliminclude + @item ylim + @item yliminclude + @item zlim + @item zliminclude @end table @@ -1706,43 +2017,72 @@ The @code{image} properties are: @table @code @item __modified__ + @item __myhandle__ + @item beingdeleted + @item busyaction + @item buttondownfcn + @item cdata The data for the image. Each pixel of the image corresponds to an element of @code{cdata}. The value of an element of @code{cdata} specifies the row-index into the colormap of the axes object containing the image. The color value found in the color map for the given index determines the color of the pixel. + @item cdatamapping + @item children + @item clim + @item climinclude + @item clipping + @item createfcn + @item deletefcn + @item handlevisibility + @item hittest + @item interruptible + @item parent + @item selected + @item selectionhighlight + @item tag + @item type + @item uicontextmenu + @item userdata + @item visible + @item xdata Two-element vector specifying the range of the x-coordinates for the image. + @item xlim + @item xliminclude + @item ydata Two-element vector specifying the range of the y-coordinates for the image. + @item ylim + @item yliminclude @end table @@ -1753,80 +2093,142 @@ The @code{patch} properties are: @table @code @item __modified__ + @item __myhandle__ + @item alim + @item aliminclude + @item alphadatamapping + @item ambientstrength + @item backfacelighting + @item beingdeleted + @item busyaction + @item buttondownfcn + @item cdata Data defining the patch object. + @item cdatamapping + @item children + @item clim + @item climinclude + @item clipping + @item createfcn + @item deletefcn + @item diffusestrength + @item edgealpha + @item edgecolor The color of the line defining the patch. @xref{Colors}. + @item edgelighting + @item erasemode + @item facealpha A number in the range [0, 1] indicating the transparency of the patch. + @item facecolor The fill color of the patch. @xref{Colors}. + @item facelighting + @item faces + @item facevertexalphadata + @item facevertexcdata + @item handlevisibility + @item hittest + @item interpreter + @item interruptible + @item keylabel + @item linestyle @xref{Line Styles}. + @item linewidth @xref{Line Styles}. + @item marker @xref{Marker Styles}. + @item markeredgecolor @xref{Marker Styles}. + @item markerfacecolor @xref{Marker Styles}. + @item markersize @xref{Marker Styles}. + @item normalmode + @item parent + @item selected + @item selectionhighlight + @item specularcolorreflectance + @item specularexponent + @item specularstrength + @item tag + @item type + @item uicontextmenu + @item userdata + @item vertexnormals + @item vertices + @item visible + @item xdata Data defining the patch object. + @item xlim + @item xliminclude + @item ydata Data defining the patch object. + @item ylim + @item yliminclude + @item zdata Data defining the patch object. + @item zlim + @item zliminclude @end table @@ -1838,78 +2240,142 @@ The @code{surface} properties are: @table @code @item __modified__ + @item __myhandle__ + @item alim + @item aliminclude + @item alphadata + @item alphadatamapping + @item ambientstrength + @item backfacelighting + @item beingdeleted + @item busyaction + @item buttondownfcn + @item cdata + @item cdatamapping + @item cdatasource + @item children + @item clim + @item climinclude + @item clipping + @item createfcn + @item deletefcn + @item diffusestrength + @item edgealpha + @item edgecolor + @item edgelighting + @item erasemode + @item facealpha + @item facecolor + @item facelighting + @item handlevisibility + @item hittest + @item interpreter + @item interruptible + @item keylabel The text of the legend entry corresponding to this surface. Note that this property is not compatible with @sc{matlab} and may be removed in a future version of Octave. + @item linestyle + @item linewidth + @item marker + @item markeredgecolor + @item markerfacecolor + @item markersize + @item meshstyle + @item normalmode + @item parent + @item selected + @item selectionhighlight + @item specularcolorreflectance + @item specularexponent + @item specularstrength + @item tag + @item type + @item uicontextmenu + @item userdata + @item vertexnormals + @item visible + @item xdata The data determining the surface. The @code{xdata} and @code{ydata} elements are vectors and @code{zdata} must be a matrix. + @item xdatasource + @item xlim + @item xliminclude + @item ydata The data determining the surface. The @code{xdata} and @code{ydata} elements are vectors and @code{zdata} must be a matrix. + @item ydatasource + @item ylim + @item yliminclude + @item zdata The data determining the surface. The @code{xdata} and @code{ydata} elements are vectors and @code{zdata} must be a matrix. + @item zdatasource + @item zlim + @item zliminclude @end table @@ -2044,10 +2510,13 @@ @table @code @item "-" Solid lines. + @item "--" Dashed lines. + @item ":" Points. + @item "-." A dash-dot line. @end table @@ -2100,7 +2569,7 @@ where @code{src} gives a handle to the source of the callback, and @code{code} gives some event specific data. This can then be associated with an object either at the objects creation or later with the -@code{set} function. For example +@code{set} function. For example, @example plot (x, "DeleteFcn", @@(s, e) disp("Window Deleted")) @@ -2111,7 +2580,7 @@ Deleted" will be displayed. Additional user arguments can be passed to callback functions, and will -be passed after the 2 default arguments. For example +be passed after the 2 default arguments. For example: @example @group @@ -2241,7 +2710,9 @@ @itemize @bullet @item group together multiple graphics objects, + @item create linked properties between different graphics objects, and + @item to hide the nominal user data, from the actual data of the objects. @end itemize @@ -2329,7 +2800,8 @@ @item edgecolor @itemx facecolor -The line and fill color of the patch objects making up the areas. @xref{Colors}. +The line and fill color of the patch objects making up the areas. +@xref{Colors}. @item xdata @itemx ydata @@ -2454,7 +2926,9 @@ The distance between labels on a single contour in points. @item linewidth + @item linestyle + @item linecolor The properties of the contour lines. The properties @code{linewidth} and @code{linestyle} are similar to the corresponding properties for lines. The @@ -2485,11 +2959,13 @@ @table @code @item color -The RGB color or color name of the line objects of the error bars. @xref{Colors}. +The RGB color or color name of the line objects of the error bars. +@xref{Colors}. @item linewidth @itemx linestyle -The line width and style of the line objects of the error bars. @xref{Line Styles}. +The line width and style of the line objects of the error bars. @xref{Line +Styles}. @item marker @itemx markeredgecolor @@ -2740,8 +3216,10 @@ @table @code @item edgecolor + @item facecolor -The RGB color or color name of the edges or faces of the surface. @xref{Colors}. +The RGB color or color name of the edges or faces of the surface. +@xref{Colors}. @item linewidth @itemx linestyle @@ -2756,7 +3234,7 @@ @item xdata @itemx ydata @itemx zdata -@item cdata +@itemx cdata The original x, y, z and c data. @item xdatasource
--- a/doc/interpreter/poly.txi +++ b/doc/interpreter/poly.txi @@ -34,6 +34,7 @@ @example p(x) = @var{c}(1) x^@var{N} + @dots{} + @var{c}(@var{N}) x + @var{c}(@var{N}+1). @end example + @end ifnottex @menu
--- a/doc/interpreter/quad.txi +++ b/doc/interpreter/quad.txi @@ -190,9 +190,11 @@ $$ @end tex @ifnottex + @example f(x, y) = sin(pi*x*y)*sqrt(x*y) @end example + @end ifnottex for @math{x} and @math{y} between 0 and 1. @@ -221,7 +223,7 @@ The above process can be simplified with the @code{dblquad} and @code{triplequad} functions for integrals over two and three -variables. For example +variables. For example: @example @group
--- a/doc/interpreter/sparse.txi +++ b/doc/interpreter/sparse.txi @@ -177,14 +177,17 @@ @item Returned from a function There are many functions that directly return sparse matrices. These include @dfn{speye}, @dfn{sprand}, @dfn{diag}, etc. + @item Constructed from matrices or vectors The function @dfn{sparse} allows a sparse matrix to be constructed from three vectors representing the row, column and data. Alternatively, the function @dfn{spconvert} uses a three column matrix format to allow easy importation of data from elsewhere. + @item Created and then filled The function @dfn{sparse} or @dfn{spalloc} can be used to create an empty matrix that is then filled by the user + @item From a user binary program The user can directly create the sparse matrix within an oct-file. @end table @@ -206,7 +209,7 @@ Other functions of interest that directly create sparse matrices, are @dfn{diag} or its generalization @dfn{spdiags}, that can take the definition of the diagonals of the matrix and create the sparse matrix -that corresponds to this. For example +that corresponds to this. For example, @example s = diag (sparse(randn(1,n)), -1); @@ -236,7 +239,7 @@ The recommended way for the user to create a sparse matrix, is to create two vectors containing the row and column index of the data and a third -vector of the same size containing the data to be stored. For example +vector of the same size containing the data to be stored. For example, @example @group @@ -261,7 +264,7 @@ the third and four columns, the real and imaginary parts of the sparse matrix. The matrix can contain zero elements and the elements can be sorted in any order. Adding zero elements is a convenient way to define -the size of the sparse matrix. For example +the size of the sparse matrix. For example: @example @group @@ -346,7 +349,7 @@ matrix type when the div (/) or ldiv (\) operator is first used with the matrix and then caches the type. However the @dfn{matrix_type} function can be used to determine the type of the sparse matrix prior -to use of the div or ldiv operators. For example +to use of the div or ldiv operators. For example, @example @group @@ -357,9 +360,9 @@ @end group @end example -show that Octave correctly determines the matrix type for lower +shows that Octave correctly determines the matrix type for lower triangular matrices. @dfn{matrix_type} can also be used to force -the type of a matrix to be a particular type. For example +the type of a matrix to be a particular type. For example: @example @group @@ -395,7 +398,7 @@ command can be used to graphically display the interconnections between nodes. -As a trivial example of the use of @dfn{gplot}, consider the example +As a trivial example of the use of @dfn{gplot} consider the example, @example @group @@ -520,7 +523,7 @@ as a full matrix. For this reason operators and functions that have a high probability of returning a full matrix will always return one. For example adding a scalar constant to a sparse matrix will almost always -make it a full matrix, and so the example +make it a full matrix, and so the example, @example @group @@ -610,7 +613,7 @@ A particular problem of sparse matrices comes about due to the fact that as the zeros are not stored, the sign-bit of these zeros is equally not -stored. In certain cases the sign-bit of zero is important. For example +stored. In certain cases the sign-bit of zero is important. For example: @example @group @@ -713,8 +716,8 @@ In the case of an asymmetric matrix, the appropriate sparsity preserving permutation is @dfn{colamd} and the factorization using -this reordering can be visualized using the command @code{q = -colamd(A); [l, u, p] = lu(A(:,q)); spy(l+u)}. +this reordering can be visualized using the command +@code{q = colamd(A); [l, u, p] = lu(A(:,q)); spy(l+u)}. Finally, Octave implicitly reorders the matrix when using the div (/) and ldiv (\) operators, and so no the user does not need to explicitly @@ -762,18 +765,18 @@ continue, else goto 3b. @enumerate -@item If the matrix is hermitian, with a positive real diagonal, attempt +@item If the matrix is Hermitian, with a positive real diagonal, attempt Cholesky factorization using @sc{lapack} xPTSV. -@item If the above failed or the matrix is not hermitian with a positive +@item If the above failed or the matrix is not Hermitian with a positive real diagonal use Gaussian elimination with pivoting using @sc{lapack} xGTSV, and goto 8. @end enumerate -@item If the matrix is hermitian with a positive real diagonal, attempt +@item If the matrix is Hermitian with a positive real diagonal, attempt Cholesky factorization using @sc{lapack} xPBTRF. -@item if the above failed or the matrix is not hermitian with a positive +@item if the above failed or the matrix is not Hermitian with a positive real diagonal use Gaussian elimination with pivoting using @sc{lapack} xGBTRF, and goto 8. @end enumerate @@ -785,16 +788,16 @@ or lower triangular matrix with row permutations, perform a sparse forward or backward substitution, and goto 8 -@item If the matrix is square, hermitian with a real positive diagonal, attempt -sparse Cholesky factorization using CHOLMOD. +@item If the matrix is square, Hermitian with a real positive diagonal, attempt +sparse Cholesky factorization using @sc{cholmod}. @item If the sparse Cholesky factorization failed or the matrix is not -hermitian with a real positive diagonal, and the matrix is square, factorize +Hermitian with a real positive diagonal, and the matrix is square, factorize using @sc{umfpack}. @item If the matrix is not square, or any of the previous solvers flags a singular or near singular matrix, find a minimum norm solution using -CXSPARSE@footnote{The CHOLMOD, UMFPACK and CXSPARSE packages were +@sc{cxsparse}@footnote{The @sc{cholmod}, @sc{umfpack} and @sc{cxsparse} packages were written by Tim Davis and are available at http://www.cise.ufl.edu/research/sparse/}. @end enumerate
--- a/doc/interpreter/stmt.txi +++ b/doc/interpreter/stmt.txi @@ -383,6 +383,7 @@ @dots{} @end group @end example + @end itemize @node The @code{while} Statement @@ -576,7 +577,7 @@ the matrix or cell matrix. So the first loop iterates twice, producing two column vectors @code{[1;2]}, followed by @code{[3;4]}, and likewise for the loop over the cell array. This can be extended to loops over -multidimensional arrays. For example +multi-dimensional arrays. For example: @example @group @@ -588,7 +589,7 @@ @end example @noindent -In the above case, the multidimensional matrix @var{c} is reshaped to a +In the above case, the multi-dimensional matrix @var{c} is reshaped to a two-dimensional matrix as @code{reshape (c, rows(c), prod(size(c)(2:end)))} and then the same behavior as a loop over a two dimensional matrix is produced. @@ -624,7 +625,7 @@ In this form of the @code{for} statement, the value of @var{expression} must be a structure. If it is, @var{key} and @var{val} are set to the name of the element and the corresponding value in turn, until there are -no more elements. For example, +no more elements. For example: @example @group
--- a/doc/interpreter/strings.txi +++ b/doc/interpreter/strings.txi @@ -501,7 +501,7 @@ patterned after the functions in the standard C library. They all operate on string arrays and return matrices of zeros and ones. Elements that are nonzero indicate that the condition was true for the -corresponding character in the string array. For example, +corresponding character in the string array. For example: @example @group
--- a/doc/interpreter/testfun.txi +++ b/doc/interpreter/testfun.txi @@ -42,7 +42,7 @@ Since @code{eval()} will stop at the first error it encounters, you must divide your tests up into blocks, with anything in a separate block evaluated separately. Blocks are introduced by the keyword -@code{test} immediately following the @code{%!}. For example, +@code{test} immediately following the @code{%!}. For example: @example @group @@ -246,18 +246,25 @@ @table @code @item %!test check that entire block is correct + @item %!error check for correct error message + @item %!warning check for correct warning message + @item %!demo demo only executes in interactive mode + @item %!# comment: ignore everything within the block + @item %!shared x,y,z declares variables for use in multiple tests + @item %!function defines a function value for a shared variable + @item %!assert (x, y, tol) shorthand for %!test assert (x, y, tol) @end table
--- a/doc/interpreter/tips.txi +++ b/doc/interpreter/tips.txi @@ -86,6 +86,7 @@ @itemize @bullet @item Vectorize loops. For instance, rather than + @example @group for i = 1:n-1 @@ -100,14 +101,15 @@ a = b(2:n) - b(1:n-1); @end example -This is especially important for loops with "cheap" bodies. Often it suffices to vectorize -just the innermost loop to get acceptable performance. A general rule of thumb is that the -"order" of the vectorized body should be greater or equal to the "order" of the enclosing loop. +This is especially important for loops with "cheap" bodies. Often it suffices +to vectorize just the innermost loop to get acceptable performance. A general +rule of thumb is that the "order" of the vectorized body should be greater or +equal to the "order" of the enclosing loop. @item -Use built-in and library functions if possible. Built-in and compiled functions are very fast. -Even with a m-file library function, chances are good that it is already optimized, or will be -optimized more in a future release. +Use built-in and library functions if possible. Built-in and compiled functions +are very fast. Even with a m-file library function, chances are good that it is +already optimized, or will be optimized more in a future release. For instance, even better than @@ -123,7 +125,7 @@ @item -Avoid computing costly intermediate results multiple times. Octave currently +Avoid computing costly intermediate results multiple times. Octave currently does not eliminate common subexpressions. Also, certain internal computation results are cached for variables. For instance, if a matrix variable is used multiple times as an index, @@ -168,7 +170,7 @@ To provide a remedy working in most real cases, Octave checks for orphaned lazy slices at certain situations, when a value is stored into a "permanent" location, such as a named variable or cell or -struct element, and possibly economizes them. For example +struct element, and possibly economizes them. For example: @example @group @@ -180,9 +182,9 @@ @end example @item -Avoid deep recursion. Function calls to m-file functions carry a relatively significant overhead, -so rewriting a recursion as a loop often helps. Also, note that the maximum level of recursion is -limited. +Avoid deep recursion. Function calls to m-file functions carry a relatively +significant overhead, so rewriting a recursion as a loop often helps. Also, +note that the maximum level of recursion is limited. @item Avoid resizing matrices unnecessarily. When building a single result @@ -212,11 +214,11 @@ @end group @end example -Sometimes the number of items can't be computed in advance, and stack-like operations -are needed. When elements are being repeatedly inserted at/removed from the end of an -array, Octave detects it as stack usage and attempts to use a smarter memory management -strategy pre-allocating the array in bigger chunks. Likewise works for cell and -struct arrays. +Sometimes the number of items can't be computed in advance, and stack-like +operations are needed. When elements are being repeatedly inserted at/removed +from the end of an array, Octave detects it as stack usage and attempts to use a +smarter memory management strategy pre-allocating the array in bigger chunks. +Likewise works for cell and struct arrays. @example @group @@ -248,9 +250,9 @@ @end example @item -Octave includes a number of other functions that can replace common types of loops, -including @code{bsxfun}, @code{arrayfun}, @code{structfun}, @code{accumarray}. -These functions can take an arbitrary function as a handle. +Octave includes a number of other functions that can replace common types of +loops, including @code{bsxfun}, @code{arrayfun}, @code{structfun}, +@code{accumarray}. These functions can take an arbitrary function as a handle. Be sure to get familiar with them if you want to become an Octave expert. @item @@ -535,21 +537,26 @@ @item -*- @nospell{texinfo} -*- This string signals Octave that the following text is in Texinfo format, and should be the first part of any help string in Texinfo format. + @item @@deftypefn@{class@} @dots{} @@end deftypefn The entire help string should be enclosed within the block defined by deftypefn. + @item @@cindex index term This generates an index entry, and can be useful when the function is included as part of a larger piece of documentation. It is ignored within Octave's help viewer. Only one index term may appear per line but multiple @@cindex lines are valid if the function should be filed under different terms. + @item @@var@{variable@} All variables should be marked with this macro. The markup of variables is then changed appropriately for display. + @item @@code@{sample of code@} All samples of code should be marked with this macro for the same reasons as the @@var macro. + @item @@seealso@{function2@} This is a comma separated list of function names that allows cross referencing from one function documentation string to another.
--- a/doc/interpreter/var.txi +++ b/doc/interpreter/var.txi @@ -32,6 +32,7 @@ @cindex job hunting @cindex getting a good job @cindex flying high and fast + @example @group x @@ -225,7 +226,7 @@ @end example The behavior of persistent variables is equivalent to the behavior of -static variables in C. The command @code{static} in Octave is also +static variables in C@. The command @code{static} in Octave is also recognized and is equivalent to @code{persistent}. Like global variables, a persistent variable may only be initialized once.