changeset 14171:2ced2f59f523 stable

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.
author Rik <octave@nomad.inbox5.com>
date Sun, 08 Jan 2012 13:39:44 -0800
parents 2ff75e38c299
children cba1c681f1b7
files doc/interpreter/doccheck/aspell-octave.en.pws doc/interpreter/doccheck/mk_undocumented_list doc/interpreter/expr.txi doc/interpreter/install.txi scripts/plot/xlim.m src/data.cc src/file-io.cc src/help.cc src/syscalls.cc
diffstat 9 files changed, 66 insertions(+), 35 deletions(-) [+]
line wrap: on
line diff
--- 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
--- 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
--- 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
--- 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
--- 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 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- 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')
--- 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\
--- 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);
--- 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\
--- 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")