Mercurial > hg > octave-nkf
changeset 9080:ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
author | Rik <rdrider0-list@yahoo.com> |
---|---|
date | Thu, 02 Apr 2009 14:45:33 -0700 |
parents | 4d610aba7347 |
children | c79cf77061b7 |
files | doc/interpreter/dynamic.txi doc/interpreter/testfun.txi doc/interpreter/tips.txi scripts/miscellaneous/mkoctfile.m |
diffstat | 4 files changed, 37 insertions(+), 35 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/interpreter/dynamic.txi +++ b/doc/interpreter/dynamic.txi @@ -355,7 +355,7 @@ @longexamplefile{stringdemo.cc} -An example of the of the use of this function is +An example of the use of this function is @example @group @@ -941,7 +941,7 @@ The underlying Fortran code should use the @code{XSTOPX} function to replace the Fortran @code{STOP} function. @code{XSTOPX} uses the Octave exception handler to treat failing cases in the fortran code -explicitly. Note that Octave supplies its own replacement blas +explicitly. Note that Octave supplies its own replacement @sc{blas} @code{XERBLA} function, which uses @code{XSTOPX}. If the underlying code calls @code{XSTOPX}, then the @code{F77_XFCN} @@ -1018,7 +1018,7 @@ There are several functions within Octave that might be useful for the purposes of parameter checking. These include the methods of the -octave_value class like @code{is_real_matrix}, etc, but equally include +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 @@ -1088,7 +1088,7 @@ The Octave unwind_protect mechanism (@ref{The @code{unwind_protect} Statement}) can also be used in oct-files. In conjunction with the exception handling of Octave, it is important to enforce that certain code is run -to allow variables, etc to be restored even if an exception occurs. An +to allow variables, etc. to be restored even if an exception occurs. An example of the use of this mechanism is @longexamplefile{unwinddemo.cc} @@ -1294,7 +1294,7 @@ name. Allow the user should only include @code{mex.h} in their code, Octave -declares additional functions, typedefs, etc, available to the user to +declares additional functions, typedefs, etc., available to the user to write mex-files in the headers @code{mexproto.h} and @code{mxarray.h}. @node Working with Matrices and Arrays in Mex-Files @@ -1336,14 +1336,14 @@ @end group @end example -There are also the functions @code{mxSetPr}, etc, that perform the +There are also the functions @code{mxSetPr}, etc., that perform the inverse, and set the data of an Array to use the block of memory pointed to by the argument of @code{mxSetPr}. Note the type @code{mwSize} used above, and @code{mwIndex} are defined as the native precision of the indexing in Octave on the platform on -which the mex-file is built. This allows both 32- and 64-bit platforms -to support mex-files. @code{mwSize} is used to define array dimension +which the mex-file is built. This allows both 32- and 64-bit platforms +to support mex-files. @code{mwSize} is used to define array dimension and maximum number or elements, while @code{mwIndex} is used to define indexing into arrays. @@ -1427,7 +1427,7 @@ @end group @end example -Note in the example the use of the @code{mxDuplicateArry} function. This +Note in the example the use of the @code{mxDuplicateArray} function. This is needed as the @code{mxArray} pointer returned by @code{mxGetCell} might be deallocated. The inverse function to @code{mxGetCell} is @code{mcSetCell} and is defined as @@ -1640,11 +1640,11 @@ @end example Note that the application @code{hello} will be dynamically linked -against the octave libraries and any octave support libraries. The above -allows the Octave math libraries to be used by an application. It does +against the octave libraries and any octave support libraries. The above +allows the Octave math libraries to be used by an application. It does not however allow the script files, oct-files or builtin functions of -Octave to be used by the application. To do that the Octave interpreter -needs to be initialized first. An example of how to do this can then be +Octave to be used by the application. To do that the Octave interpreter +needs to be initialized first. An example of how to do this can then be seen in the code @examplefile{embedded.cc}
--- a/doc/interpreter/testfun.txi +++ b/doc/interpreter/testfun.txi @@ -35,8 +35,8 @@ @DOCSTRING(test) @code{test} scans the named script file looking for lines which -start with @code{%!}. The prefix is stripped off and the rest of the -line is processed through the Octave interpreter. If the code +start with @code{%!}. The prefix is stripped off and the rest of the +line is processed through the Octave interpreter. If the code generates an error, then the test is said to fail. Since @code{eval()} will stop at the first error it encounters, you must @@ -91,7 +91,7 @@ @end example @code{assert} can accept a tolerance so that you can compare results -absolutely or relatively. For example, the following all succeed: +absolutely or relatively. For example, the following all succeed: @example @group @@ -130,8 +130,10 @@ failures, mark the block with @code{xtest} rather than @code{test}: @example +@group %!xtest assert (1==0) %!xtest fail ('success=1','error')) +@end group @end example Another use of @code{xtest} is for statistical tests which should @@ -182,7 +184,7 @@ %!error <passes!> error('this test passes!'); @end example -If the code doesn't generate an error, the test fails. For example, +If the code doesn't generate an error, the test fails. For example, @example %!error "this is an error because it succeeds."; @@ -200,8 +202,8 @@ It is important to automate the tests as much as possible, however some tests require user interaction. These can be isolated into demo blocks, which if you are in batch mode, are only run when -called with @code{demo} or @code{verbose}. The code is displayed before -it is executed. For example, +called with @code{demo} or @code{verbose}. The code is displayed before +it is executed. For example, @example @group @@ -261,7 +263,7 @@ @end table You can also create test scripts for builtins and your own C++ -functions. Just put a file of the function name on your path without +functions. Just put a file of the function name on your path without any extension and it will be picked up by the test procedure. You can even embed tests directly in your C++ code:
--- a/doc/interpreter/tips.txi +++ b/doc/interpreter/tips.txi @@ -289,9 +289,9 @@ @section Tips for Documentation Strings As noted above, documentation is typically in a commented header block -on an Octave function following the copyright statement. The help string +on an Octave function following the copyright statement. The help string shown above is an unformatted string and will be displayed as is by -Octave. Here are some tips for the writing of documentation strings. +Octave. Here are some tips for the writing of documentation strings. @itemize @bullet @item @@ -452,14 +452,14 @@ @end example Note that often TeX output can be used in html documents and so often -the @code{@@ifhtml} blocks are unnecessary. If no specific output +the @code{@@ifhtml} blocks are unnecessary. If no specific output processor is chosen, by default, the text goes into all output -processors. It is usual to have the above blocks in pairs to allow the +processors. It is usual to have the above blocks in pairs to allow the same information to be conveyed in all output formats, but with a different markup. Another important feature of Texinfo that is often used in Octave help -strings is the @code{@@example} environment. An example of its use is +strings is the @code{@@example} environment. An example of its use is @example @group @@ -486,7 +486,7 @@ arrow signifying the result of a command. In many cases a function has multiple ways in which it can be called, -and the @code{@@deftypefnx} macro can be used to give alternatives. For +and the @code{@@deftypefnx} macro can be used to give alternatives. For example @example @@ -500,8 +500,8 @@ @end example Many complete examples of Texinfo documentation can be taken from the -help strings for the Octave functions themselves. A relatively complete -example of which is the @code{nchoosek} function. The Texinfo +help strings for the Octave functions themselves. A relatively complete +example of which is the @code{nchoosek} function. The Texinfo documentation string of @code{nchoosek} is @example @@ -510,7 +510,7 @@ @@deftypefn @{Function File@} @{@} nchoosek (@@var@{n@}, @@var@{k@}) Compute the binomial coefficient or all combinations of -@@var@{n@}. If @@var@{n@} is a scalar then, calculate the +@@var@{n@}. If @@var@{n@} is a scalar then, calculate the binomial coefficient of @@var@{n@} and @@var@{k@}, defined as @@iftex @@ -525,7 +525,7 @@ @@example @@group / \ - | n | n (n-1) (n-2) ... (n-k+1) + | n | n (n-1) (n-2) @dots{} (n-k+1) | | = ------------------------- | k | k! \ / @@ -535,7 +535,7 @@ If @@var@{n@} is a vector, this generates all combinations of the elements of @@var@{n@}, taken @@var@{k@} at a time, -one row per combination. The resulting @@var@{c@} has size +one row per combination. The resulting @@var@{c@} has size @@code@{[nchoosek (length (@@var@{n@}),@@var@{k@}), @@var@{k@}]@}. @@seealso@{bincoeff@} @@ -558,14 +558,14 @@ coefficient of N and K, defined as / \ - | n | n (n-1) (n-2) ... (n-k+1) n! + | n | n (n-1) (n-2) @dots{} (n-k+1) n! | | = ------------------------- = --------- | k | k! k! (n-k)! \ / If N is a vector generate all combinations of the elements of N, taken K at a time, one row per - combination. The resulting C has size `[nchoosek + combination. The resulting C has size `[nchoosek (length (N), K), K]'. @@ -589,7 +589,7 @@ @end tex If @var{n} is a vector generate all combinations of the elements -of @var{n}, taken @var{k} at a time, one row per combination. The +of @var{n}, taken @var{k} at a time, one row per combination. The resulting @var{c} has size @code{[nchoosek (length (@var{n}), @var{k}), @var{k}]}.