# HG changeset patch # User Rik # Date 1326058784 28800 # Node ID 2ced2f59f5237ab8096a0ed17d06393361d34483 # Parent 2ff75e38c299747a62d6604f864dd977828c3190 doc: miscellaneous documentation improvements * aspell-octave.en.pws: Add new words to spelling dictionary. * expr.txi: Use hyphens in "element-by-element" construction. * install.txi: Miscellaneous docstring improvements. * mk_undocumented_list: Update script. * xlim.m: Add ylim and zlim to function index. * data.cc: Add inf and nan to to function index. * file-io.cc: Add octave_tmp_file_name to function index. Expand docstring for SEEK_CUR and SEEK_END. * help.cc: Miscellaneous docstring improvements. * syscalls.cc: Improve docstrings for F_XXXX series of functions. diff -r 2ff75e38c299 -r 2ced2f59f523 doc/interpreter/doccheck/aspell-octave.en.pws --- a/doc/interpreter/doccheck/aspell-octave.en.pws Sun Jan 08 16:28:31 2012 -0500 +++ b/doc/interpreter/doccheck/aspell-octave.en.pws Sun Jan 08 13:39:44 2012 -0800 @@ -38,6 +38,7 @@ autoloaded autoloading Autoloading +Automake autoregression autoregressions autoscaled @@ -82,6 +83,7 @@ brackety breakpoint Brenan +broadcastable Brockwell BSX builtin @@ -305,6 +307,7 @@ fprintf FreeBSD freespacing +FreeType freetype frnd frob @@ -339,6 +342,7 @@ globbing glpk GLS +gnulib gnuplot Gnuplot gnuplot's @@ -348,6 +352,7 @@ Goto gotos GPL +GPLK gplot grabdemo GradObj @@ -485,6 +490,7 @@ libcurl liblapack liboctave +Libtool licensors lineanchors linefeeds @@ -551,6 +557,7 @@ mex Michelsen Microsystems +MinGW minima Minimizers Minitab @@ -572,6 +579,7 @@ mpoles mpower mrdivide +MSYS mtimes Multi multi @@ -745,6 +753,7 @@ Reindent relicensing ren +renderer repelems repmat resampled @@ -781,6 +790,7 @@ SCO screenful se +sed seealso semidefinite Sep @@ -909,6 +919,7 @@ tinv Tisseur Tisseur's +tmp Toeplitz tokenExtents TolF @@ -1046,6 +1057,7 @@ ydata yerrorbar yerrorbars +ylim yy YY yyyy @@ -1056,3 +1068,4 @@ zer Ziggurat zlib +zlim diff -r 2ff75e38c299 -r 2ced2f59f523 doc/interpreter/doccheck/mk_undocumented_list --- a/doc/interpreter/doccheck/mk_undocumented_list Sun Jan 08 16:28:31 2012 -0500 +++ b/doc/interpreter/doccheck/mk_undocumented_list Sun Jan 08 13:39:44 2012 -0800 @@ -9,7 +9,7 @@ where = cellfun (\@which, funclist, \"UniformOutput\", 0)' _END_OCT_SCRIPT_ -die "Unable to invoke 'run-octave'. Exiting\n" unless (@octave_output); +unless (@octave_output) { die "Unable to invoke 'run-octave'. Exiting\n" ;} ################################################################################ # Winnow list of functions that require a DOCSTRING @@ -86,9 +86,9 @@ F_DUPFD F_GETFD F_GETFL +fact finite fmod -fntests F_SETFD F_SETFL gammaln diff -r 2ff75e38c299 -r 2ced2f59f523 doc/interpreter/expr.txi --- a/doc/interpreter/expr.txi Sun Jan 08 16:28:31 2012 -0500 +++ b/doc/interpreter/expr.txi Sun Jan 08 13:39:44 2012 -0800 @@ -523,7 +523,7 @@ @item @var{x} .+ @var{y} @opindex .+ -Element by element addition. This operator is equivalent to @code{+}. +Element-by-element addition. This operator is equivalent to @code{+}. @item @var{x} - @var{y} @opindex - @@ -532,17 +532,17 @@ shape. @item @var{x} .- @var{y} -Element by element subtraction. This operator is equivalent to @code{-}. +Element-by-element subtraction. This operator is equivalent to @code{-}. @item @var{x} * @var{y} @opindex * -Matrix multiplication. The number of columns of @var{x} must agree with +Matrix multiplication. The number of columns of @var{x} must agree with the number of rows of @var{y}, or they must be broadcastable to the same shape. @item @var{x} .* @var{y} @opindex .* -Element by element multiplication. If both operands are matrices, the +Element-by-element multiplication. If both operands are matrices, the number of rows and columns must both agree, or they must be broadcastable to the same shape. @@ -562,7 +562,7 @@ @item @var{x} ./ @var{y} @opindex ./ -Element by element right division. +Element-by-element right division. @item @var{x} \ @var{y} @opindex \ @@ -580,7 +580,7 @@ @item @var{x} .\ @var{y} @opindex .\ -Element by element left division. Each element of @var{y} is divided +Element-by-element left division. Each element of @var{y} is divided by each corresponding element of @var{x}. @item @var{x} ^ @var{y} @@ -601,12 +601,12 @@ @itemx @var{x} .** @var{y} @opindex .** @opindex .^ -Element by element power operator. If both operands are matrices, the +Element-by-element power operator. If both operands are matrices, the number of rows and columns must both agree, or they must be -broadcastable to the same shape. If several complex results are -possible, the one with smallest nonnegative argument (angle) is taken. -This may mean a complex root even if a real root is also possible. Use -@code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a +broadcastable to the same shape. If several complex results are +possible, the one with smallest non-negative argument (angle) is taken. +This rule may return a complex root even when a real root is also possible. +Use @code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a real result is preferred. @item -@var{x} @@ -632,7 +632,7 @@ Transpose. @end table -Note that because Octave's element by element operators begin with a +Note that because Octave's element-by-element operators begin with a @samp{.}, there is a possible ambiguity for statements like @example diff -r 2ff75e38c299 -r 2ced2f59f523 doc/interpreter/install.txi --- a/doc/interpreter/install.txi Sun Jan 08 16:28:31 2012 -0500 +++ b/doc/interpreter/install.txi Sun Jan 08 13:39:44 2012 -0800 @@ -121,8 +121,6 @@ The following external packages are required: @table @asis -@item PCRE -The Perl Compatible Reular Expression library (http://www.pcre.org). @item BLAS Basic Linear Algebra Subroutine library (@url{http://www.netlib.org/blas}). Accelerated BLAS libraries such as @@ -130,6 +128,8 @@ better performance. @item LAPACK Linear Algebra Package (@url{http://www.netlib.org/lapack}). +@item PCRE +The Perl Compatible Regular Expression library (http://www.pcre.org). @end table The following external package is optional but strongly recommended: @@ -152,7 +152,7 @@ @item cURL Library for transferring data with URL syntax -(@url{http://curl.haxx.se}). cURL is required to provide the +(@url{http://curl.haxx.se}). cURL is required to provide the @code{urlread} and @code{urlwrite} functions and the @code{ftp} class. @item FFTW3 @@ -172,7 +172,7 @@ @item FreeType Portable font engine (@url{http://www.freetype.org}). FreeType is used -to peform font rendering Octave's OpenGL-based graphics functions. +to perform font rendering for Octave's OpenGL-based graphics functions. @item GLPK GNU Linear Programming Kit (@url{http://www.gnu.org/software/glpk}). @@ -190,7 +190,7 @@ @item HDF5 Library for manipulating portable data files (@url{http://www.hdfgroup.org/HDF5}). HDF5 is required for Octave's -@code{save} and @code{load} commands to write and read HDF data files. +@code{load} and @code{save} commands to read and write HDF data files. @item OpenGL API for portable 2D and 3D graphics (@url{http://www.opengl.org}). An diff -r 2ff75e38c299 -r 2ced2f59f523 scripts/plot/xlim.m --- a/scripts/plot/xlim.m Sun Jan 08 16:28:31 2012 -0500 +++ b/scripts/plot/xlim.m Sun Jan 08 13:39:44 2012 -0800 @@ -17,6 +17,10 @@ ## . ## -*- texinfo -*- +## @c List other forms of function in documentation index +## @findex ylim +## @findex zlim +## ## @deftypefn {Function File} {@var{xl} =} xlim () ## @deftypefnx {Function File} {} xlim (@var{xl}) ## @deftypefnx {Function File} {@var{m} =} xlim ('mode') diff -r 2ff75e38c299 -r 2ced2f59f523 src/data.cc --- a/src/data.cc Sun Jan 08 16:28:31 2012 -0500 +++ b/src/data.cc Sun Jan 08 13:39:44 2012 -0800 @@ -3927,6 +3927,9 @@ DEFUN (Inf, args, , "-*- texinfo -*-\n\ +@c List other form of function in documentation index\n\ +@findex inf\n\ +\n\ @deftypefn {Built-in Function} {} Inf\n\ @deftypefnx {Built-in Function} {} Inf (@var{n})\n\ @deftypefnx {Built-in Function} {} Inf (@var{n}, @var{m})\n\ @@ -3984,6 +3987,9 @@ DEFUN (NaN, args, , "-*- texinfo -*-\n\ +@c List other form of function in documentation index\n\ +@findex nan\n\ +\n\ @deftypefn {Built-in Function} {} NaN\n\ @deftypefnx {Built-in Function} {} NaN (@var{n})\n\ @deftypefnx {Built-in Function} {} NaN (@var{n}, @var{m})\n\ @@ -5599,8 +5605,8 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} power (@var{x}, @var{y})\n\ Return the element-by-element operation of @var{x} raised to the\n\ -@var{y} power. If several complex results are possible,\n\ -returns the one with smallest nonnegative argument (angle). Use\n\ +@var{y} power. If several complex results are possible,\n\ +returns the one with smallest non-negative argument (angle). Use\n\ @code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\ real result is preferred.\n\ \n\ diff -r 2ff75e38c299 -r 2ced2f59f523 src/file-io.cc --- a/src/file-io.cc Sun Jan 08 16:28:31 2012 -0500 +++ b/src/file-io.cc Sun Jan 08 13:39:44 2012 -0800 @@ -1879,6 +1879,9 @@ DEFUNX ("tmpnam", Ftmpnam, args, , "-*- texinfo -*-\n\ +@c List other forms of function in documentation index\n\ +@findex octave_tmp_file_name\n\ +\n\ @deftypefn {Built-in Function} {} tmpnam ()\n\ @deftypefnx {Built-in Function} {} tmpnam (@var{dir})\n\ @deftypefnx {Built-in Function} {} tmpnam (@var{dir}, @var{prefix})\n\ @@ -2178,7 +2181,7 @@ @deftypefn {Built-in Function} {} SEEK_SET ()\n\ @deftypefnx {Built-in Function} {} SEEK_CUR ()\n\ @deftypefnx {Built-in Function} {} SEEK_END ()\n\ -Return the value required to request that @code{fseek} perform\n\ +Return the numerical value to pass to @code{fseek} to perform\n\ one of the following actions:\n\ @table @code\n\ @item SEEK_SET\n\ @@ -2190,6 +2193,7 @@ @item SEEK_END\n\ Position file relative to the end.\n\ @end table\n\ +@seealso{fseek}\n\ @end deftypefn") { return const_value ("SEEK_SET", args, -1); @@ -2198,7 +2202,9 @@ DEFUNX ("SEEK_CUR", FSEEK_CUR, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} SEEK_CUR ()\n\ -See SEEK_SET.\n\ +Return the numerical value to pass to @code{fseek} to\n\ +position the file pointer relative to the current position.\n\ +@seealso{SEEK_SET, SEEK_END}.\n\ @end deftypefn") { return const_value ("SEEK_CUR", args, 0); @@ -2207,7 +2213,9 @@ DEFUNX ("SEEK_END", FSEEK_END, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} SEEK_END ()\n\ -See SEEK_SET.\n\ +Return the numerical value to pass to @code{fseek} to\n\ +position the file pointer relative to the end of the file.\n\ +@seealso{SEEK_SET, SEEK_CUR}.\n\ @end deftypefn") { return const_value ("SEEK_END", args, 1); diff -r 2ff75e38c299 -r 2ced2f59f523 src/help.cc --- a/src/help.cc Sun Jan 08 16:28:31 2012 -0500 +++ b/src/help.cc Sun Jan 08 13:39:44 2012 -0800 @@ -239,7 +239,7 @@ pair_type ("**", "-*- texinfo -*-\n\ @deftypefn {Operator} {} **\n\ -Power operator. This may return complex results for real inputs. Use\n\ +Power operator. This may return complex results for real inputs. Use\n\ @code{realsqrt}, @code{cbrt}, @code{nthroot}, or @code{realroot} to obtain\n\ real results when possible.\n\ @seealso{power, ^, .**, .^, realpow, realsqrt, cbrt, nthroot}\n\ @@ -248,7 +248,7 @@ pair_type ("^", "-*- texinfo -*-\n\ @deftypefn {Operator} {} ^\n\ -Power operator. This may return complex results for real inputs. Use\n\ +Power operator. This may return complex results for real inputs. Use\n\ @code{realsqrt}, @code{cbrt}, @code{nthroot}, or @code{realroot} to obtain\n\ real results when possible.\n\ @seealso{power, **, .^, .**, realpow, realsqrt, cbrt, nthroot}\n\ @@ -308,8 +308,8 @@ pair_type (".**", "-*- texinfo -*-\n\ @deftypefn {Operator} {} .*\n\ -Element by element power operator. If several complex results are possible,\n\ -returns the one with smallest nonnegative argument (angle). Use\n\ +Element by element power operator. If several complex results are possible,\n\ +returns the one with smallest non-negative argument (angle). Use\n\ @code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\ real result is preferred.\n\ @seealso{**, ^, .^, power, realpow, realsqrt, cbrt, nthroot}\n\ @@ -318,8 +318,8 @@ pair_type (".^", "-*- texinfo -*-\n\ @deftypefn {Operator} {} .^\n\ -Element by element power operator. If several complex results are possible,\n\ -returns the one with smallest nonnegative argument (angle). Use\n\ +Element by element power operator. If several complex results are possible,\n\ +returns the one with smallest non-negative argument (angle). Use\n\ @code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\ real result is preferred.\n\ @seealso{.**, ^, **, power, realpow, realsqrt, cbrt, nthroot}\n\ diff -r 2ff75e38c299 -r 2ced2f59f523 src/syscalls.cc --- a/src/syscalls.cc Sun Jan 08 16:28:31 2012 -0500 +++ b/src/syscalls.cc Sun Jan 08 13:39:44 2012 -0800 @@ -1646,7 +1646,7 @@ DEFUNX ("F_DUPFD", FF_DUPFD, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} F_DUPFD ()\n\ -Return the value required to request that @code{fcntl} return a\n\ +Return the numerical value to pass to @code{fcntl} to return a\n\ duplicate file descriptor.\n\ @seealso{fcntl, F_GETFD, F_GETFL, F_SETFD, F_SETFL}\n\ @end deftypefn") @@ -1662,7 +1662,7 @@ DEFUNX ("F_GETFD", FF_GETFD, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} F_GETFD ()\n\ -Return the value required to request that @code{fcntl} to return the\n\ +Return the numerical value to pass to @code{fcntl} to return the\n\ file descriptor flags.\n\ @seealso{fcntl, F_DUPFD, F_GETFL, F_SETFD, F_SETFL}\n\ @end deftypefn") @@ -1678,7 +1678,7 @@ DEFUNX ("F_GETFL", FF_GETFL, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} F_GETFL ()\n\ -Return the value required to request that @code{fcntl} to return the\n\ +Return the numerical value to pass to @code{fcntl} to return the\n\ file status flags.\n\ @seealso{fcntl, F_DUPFD, F_GETFD, F_SETFD, F_SETFL}\n\ @end deftypefn") @@ -1694,7 +1694,7 @@ DEFUNX ("F_SETFD", FF_SETFD, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} F_SETFD ()\n\ -Return the value required to request that @code{fcntl} to set the file\n\ +Return the numerical value to pass to @code{fcntl} to set the file\n\ descriptor flags.\n\ @seealso{fcntl, F_DUPFD, F_GETFD, F_GETFL, F_SETFL}\n\ @end deftypefn") @@ -1710,7 +1710,7 @@ DEFUNX ("F_SETFL", FF_SETFL, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} F_SETFL ()\n\ -Return the value required to request that @code{fcntl} to set the file\n\ +Return the numerical value to pass to @code{fcntl} to set the file\n\ status flags.\n\ @seealso{fcntl, F_DUPFD, F_GETFD, F_GETFL, F_SETFD}\n\ @end deftypefn")