changeset 11966:c45c78914af0 release-3-2-x

Various documentation improvements
author Rik <rdrider0-list@yahoo.com>
date Sat, 06 Jun 2009 18:30:52 -0700
parents c48029d8d71c
children 85bbe9e61647
files doc/interpreter/package.txi doc/interpreter/var.txi scripts/linear-algebra/cond.m scripts/linear-algebra/condest.m scripts/pkg/pkg.m scripts/plot/gtext.m src/DLD-FUNCTIONS/cellfun.cc src/DLD-FUNCTIONS/eig.cc src/strfns.cc
diffstat 9 files changed, 66 insertions(+), 52 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/package.txi
+++ b/doc/interpreter/package.txi
@@ -40,7 +40,7 @@
 @node Installing and Removing Packages
 @section Installing and Removing Packages
 
-Assuming a package is available in the file @code{image-1.0.0.tar.gz}
+Assuming a package is available in the file @file{image-1.0.0.tar.gz}
 it can be installed from the Octave prompt with the command
 
 @example
@@ -139,9 +139,9 @@
 system-wide installations of a package.  If the user performing the
 installation is @code{root} the packages will be installed in a
 system-wide directory that defaults to 
-@code{OCTAVE_HOME/share/octave/packages/}.  If the user is not 
+@file{OCTAVE_HOME/share/octave/packages/}.  If the user is not 
 @code{root} the default installation directory is
-@code{~/octave/}.  Packages will be installed in a subdirectory of the
+@file{~/octave/}.  Packages will be installed in a subdirectory of the
 installation directory that will be named after the package.  It is
 possible to change the installation directory by using the
 @code{pkg prefix} command
@@ -159,9 +159,9 @@
 
 To function properly the package manager needs to keep some
 information about the installed packages.  For per-user packages this
-information is by default stored in the file @code{~/.octave_packages}
+information is by default stored in the file @file{~/.octave_packages}
 and for system-wide installations it is stored in
-@code{OCTAVE_HOME/share/octave/octave_packages}.  The path to the
+@file{OCTAVE_HOME/share/octave/octave_packages}.  The path to the
 per-user file can be changed with the @code{pkg local_list} command
 
 @example
@@ -257,12 +257,12 @@
 @item package/src
 An optional directory containing code that must be built prior to the
 packages installation.  The Octave package manager will execute
-@code{./configure} in this directory if this script exists, and will
-then call @code{make} if a file @code{Makefile} exists in this
+@file{./configure} in this directory if this script exists, and will
+then call @code{make} if a file @file{Makefile} exists in this
 directory.  @code{make install} will however not be called.  If a file
-called @code{FILES} exist all files listed there will be copied to the
+called @code{FILES} exists all files listed there will be copied to the
 @code{inst} directory, so they also will be installed.  If the
-@code{FILES} file doesn't exist, @code{src/*.m} and @code{src/*.oct}
+@code{FILES} file doesn't exist, @file{src/*.m} and @file{src/*.oct}
 will be copied to the @code{inst} directory.
 
 @item package/doc
@@ -292,7 +292,7 @@
 @noindent
 @itemize
 @item
-Lines starting with @code{#} are comments.
+Lines starting with @samp{#} are comments.
 
 @item
 Lines starting with a blank character are continuations from the 
@@ -426,7 +426,7 @@
 
 @noindent
 @itemize
-@item Lines beginning with @code{#} are comments.
+@item Lines beginning with @samp{#} are comments.
 
 @item The first non-comment line should look like this
 
--- a/doc/interpreter/var.txi
+++ b/doc/interpreter/var.txi
@@ -265,7 +265,7 @@
 
 The value of a persistent variable is kept in memory until it is
 explicitly cleared.  Assuming that the implementation of @code{count_calls}
-is saved on disc, we get the following behavior.
+is saved on disk, we get the following behavior.
 
 @example
 for i = 1:2
--- a/scripts/linear-algebra/cond.m
+++ b/scripts/linear-algebra/cond.m
@@ -24,7 +24,7 @@
 ## By default @code{@var{p}=2} is used which implies a (relatively slow)
 ## singular value decomposition.  Other possible selections are 
 ## @code{@var{p}= 1, Inf, inf, 'Inf', 'fro'} which are generally faster.
-## @seealso{norm, inv, det, svd, rank}
+## @seealso{condest, rcond, norm, svd}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/linear-algebra/condest.m
+++ b/scripts/linear-algebra/condest.m
@@ -61,7 +61,7 @@
 ## Pseudospectra." @url{http://citeseer.ist.psu.edu/223007.html}
 ## @end itemize
 ##
-## @seealso{norm, cond, onenormest}
+## @seealso{cond, norm, onenormest}
 ## @end deftypefn
 
 ## Code originally licensed under
--- a/scripts/pkg/pkg.m
+++ b/scripts/pkg/pkg.m
@@ -29,7 +29,7 @@
 ## pkg install image-1.0.0.tar.gz
 ## @end example
 ## @noindent
-## installs the package found in the file @code{image-1.0.0.tar.gz}.
+## installs the package found in the file @file{image-1.0.0.tar.gz}.
 ##
 ## The @var{option} variable can contain options that affect the manner
 ## in which a package is installed.  These options can be one or more of
@@ -130,7 +130,7 @@
 ## pkg prefix ~/my_octave_packages
 ## @end example
 ## @noindent
-## sets the installation prefix to @code{~/my_octave_packages}.
+## sets the installation prefix to @file{~/my_octave_packages}.
 ## Packages will be installed in this directory.
 ##
 ## It is possible to get the current installation prefix by requesting an
--- a/scripts/plot/gtext.m
+++ b/scripts/plot/gtext.m
@@ -17,15 +17,14 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {} gtext (@var{s})
+## @deftypefn  {Function File} {} gtext (@var{s})
+## @deftypefnx {Function File} {} gtext (@{@var{s1}; @var{s2}; @dots{}@})
 ## @deftypefnx {Function File} {} gtext (@dots{}, @var{prop}, @var{val})
-## Place text on the current figure.  The text can be defined by the
-## string @var{s}.  If @var{s} is a cell array, each element of the cell
-## array is written to a separate line.
-##
-## Additional arguments are passed to the underlying text object as
-## properties.
-## @seealso{ginput}
+## Place text on the current figure using the mouse.  The text is defined
+## by the string @var{s}.  If @var{s} is a cell array, each element of the cell
+## array is written to a separate line.  Additional arguments are passed to
+## the underlying text object as properties.
+## @seealso{ginput, text}
 ## @end deftypefn
 
 function gtext (s, varargin)
--- a/src/DLD-FUNCTIONS/cellfun.cc
+++ b/src/DLD-FUNCTIONS/cellfun.cc
@@ -900,9 +900,9 @@
 
 DEFUN_DLD (num2cell, args, ,
   "-*- texinfo -*-\n\
-@deftypefn {Loadable Function} {@var{c} =} num2cell (@var{m})\n\
+@deftypefn  {Loadable Function} {@var{c} =} num2cell (@var{m})\n\
 @deftypefnx {Loadable Function} {@var{c} =} num2cell (@var{m}, @var{dim})\n\
-Convert the matrix @var{m} into a cell array.  If @var{dim} is defined, the\n\
+Convert the matrix @var{m} to a cell array.  If @var{dim} is defined, the\n\
 value @var{c} is of dimension 1 in this dimension and the elements of\n\
 @var{m} are placed in slices in @var{c}.\n\
 @seealso{mat2cell}\n\
--- a/src/DLD-FUNCTIONS/eig.cc
+++ b/src/DLD-FUNCTIONS/eig.cc
@@ -36,7 +36,7 @@
 
 DEFUN_DLD (eig, args, nargout,
   "-*- texinfo -*-\n\
-@deftypefn {Loadable Function} {@var{lambda} =} eig (@var{a})\n\
+@deftypefn  {Loadable Function} {@var{lambda} =} eig (@var{a})\n\
 @deftypefnx {Loadable Function} {@var{lambda} =} eig (@var{a}, @var{b})\n\
 @deftypefnx {Loadable Function} {[@var{v}, @var{lambda}] =} eig (@var{a})\n\
 @deftypefnx {Loadable Function} {[@var{v}, @var{lambda}] =} eig (@var{a}, @var{b})\n\
@@ -47,6 +47,7 @@
 Schur decomposition.\n\
 \n\
 The eigenvalues returned by @code{eig} are not ordered.\n\
+@seealso{eigs}\n\
 @end deftypefn")
 {
   octave_value_list retval;
--- a/src/strfns.cc
+++ b/src/strfns.cc
@@ -43,29 +43,37 @@
 
 DEFUN (char, args, ,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} char (@var{x})\n\
+@deftypefn  {Built-in Function} {} char (@var{x})\n\
+@deftypefnx {Built-in Function} {} char (@var{x}, @dots{})\n\
+@deftypefnx {Built-in Function} {} char (@var{s1}, @var{s2}, @dots{})\n\
 @deftypefnx {Built-in Function} {} char (@var{cell_array})\n\
-@deftypefnx {Built-in Function} {} char (@var{s1}, @var{s2}, @dots{})\n\
 Create a string array from one or more numeric matrices, character\n\
-matrices or cell arrays.  For numerical input, each element is converted\n\
-to the corresponding ASCII character.  The arguments (and elements of\n\
-cell array(s)) are concatenated vertically.\n\
+matrices, or cell arrays.  Arguments are concatenated vertically.\n\
 The returned values are padded with blanks as needed to make each row\n\
-of the string array have the same length.  Empty strings are not removed.\n\
+of the string array have the same length.  Empty input strings are\n\
+significant and will concatenated in the output.\n\
+\n\
+For numerical input, each element is converted\n\
+to the corresponding ASCII character.  A range error results if an input\n\
+is outside the ASCII range (0-255).\n\
+\n\
+For cell arrays, each element is concatenated separately.  Cell arrays converted through\n\
+@code{char} can mostly be converted back with @code{cellstr}.\n\
 For example,\n\
 \n\
 @example\n\
 @group\n\
-char ([97, 98, 99], \"\", @{\"98\", \"99\", 100@}, [\"num\", \"bers\"])\n\
+char ([97, 98, 99], \"\", @{\"98\", \"99\", 100@}, \"str1\", [\"ha\", \"lf\"])\n\
      @result{} [\"abc    \"\n\
-        \"       \"\n\
-        \"98     \"\n\
-        \"99     \"\n\
-        \"d      \"\n\
-        \"numbers\"]\n\
+         \"       \"\n\
+         \"98     \"\n\
+         \"99     \"\n\
+         \"d      \"\n\
+         \"str1   \"\n\
+         \"half   \"]\n\
 @end group\n\
 @end example\n\
-\n\
+@seealso{strvcat, cellstr}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -158,29 +166,35 @@
 
 DEFUN (strvcat, args, ,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} strvcat (@var{x})\n\
+@deftypefn  {Built-in Function} {} strvcat (@var{x})\n\
+@deftypefnx {Built-in Function} {} strvcat (@var{x}, @dots{})\n\
+@deftypefnx {Built-in Function} {} strvcat (@var{s1}, @var{s2}, @dots{})\n\
 @deftypefnx {Built-in Function} {} strvcat (@var{cell_array})\n\
-@deftypefnx {Built-in Function} {} strvcat (@var{s1}, @var{s2}, @dots{})\n\
 Create a character array from one or more numeric matrices, character\n\
-matrices or cell arrays.  For numerical input, each element is converted\n\
-to the corresponding ASCII character.  The arguments (and elements of\n\
-cell array(s)) are concatenated vertically.\n\
+matrices, or cell arrays.  Arguments are concatenated vertically.\n\
 The returned values are padded with blanks as needed to make each row\n\
 of the string array have the same length.  Unlike @code{char}, empty\n\
-strings are removed.\n\
+strings are removed and will not appear in the output.\n\
+\n\
+For numerical input, each element is converted\n\
+to the corresponding ASCII character.  A range error results if an input\n\
+is outside the ASCII range (0-255).\n\
+\n\
+For cell arrays, each element is concatenated separately.  Cell arrays converted through\n\
+@code{strvcat} can mostly be converted back with @code{cellstr}.\n\
 For example,\n\
 \n\
 @example\n\
 @group\n\
-strvcat ([97, 98, 99], \"\", @{\"98\", \"99\", 100@}, [\"num\", \"bers\"])\n\
+strvcat ([97, 98, 99], \"\", @{\"98\", \"99\", 100@}, \"str1\", [\"ha\", \"lf\"])\n\
      @result{} [\"abc    \"\n\
-        \"98     \"\n\
-        \"99     \"\n\
-        \"d      \"\n\
-        \"numbers\"]\n\
+         \"98     \"\n\
+         \"99     \"\n\
+         \"d      \"\n\
+         \"str1   \"\n\
+         \"half   \"]\n\
 @end group\n\
 @end example\n\
-\n\
 @seealso{char, strcat, cstrcat}\n\
 @end deftypefn")
 {