changeset 28958:6fd6ad758b10

doc: Use @xref, @pxref rather than "see @code{}" in TexInfo. Using macros produces a hyperlinked cross-reference, rather than just text, which is easier to navigate. * integral.m, griddata.m, errordlg.m, warndlg.m, lookfor.m, cond.m, getfield.m, odeset.m, fminsearch.m, fminunc.m, fsolve.m, erase.m, example.m, datenum.m, datestr.m, datevec.m, now.m: doc: Use @xref, @pxref rather than "see @code{}" in TexInfo.
author Rik <rik@octave.org>
date Mon, 19 Oct 2020 09:13:53 -0700
parents efc998c08d27
children 5394d688d456
files scripts/general/integral.m scripts/geometry/griddata.m scripts/gui/errordlg.m scripts/gui/warndlg.m scripts/help/lookfor.m scripts/linear-algebra/cond.m scripts/miscellaneous/getfield.m scripts/ode/odeset.m scripts/optimization/fminsearch.m scripts/optimization/fminunc.m scripts/optimization/fsolve.m scripts/strings/erase.m scripts/testfun/example.m scripts/time/datenum.m scripts/time/datestr.m scripts/time/datevec.m scripts/time/now.m
diffstat 17 files changed, 40 insertions(+), 35 deletions(-) [+]
line wrap: on
line diff
--- a/scripts/general/integral.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/general/integral.m	Mon Oct 19 09:13:53 2020 -0700
@@ -55,14 +55,14 @@
 ## Specifies points to be used in defining subintervals of the quadrature
 ## algorithm, or if @var{a}, @var{b}, or @var{waypoints} are complex then
 ## the quadrature is calculated as a contour integral along a piecewise
-## continuous path.  For more detail see @code{quadgk}.
+## continuous path.  For more detail, @pxref{XREFquadgk,,@code{quadgk}}.
 ##
 ## @item ArrayValued
 ## @code{integral} expects @var{f} to return a scalar value unless
 ## @var{arrayvalued} is specified as true.  This option will cause
 ## @code{integral} to perform the integration over the entire array and return
 ## @var{q} with the same dimensions as returned by @var{f}.  For more detail
-## see @code{quadv}.
+## @pxref{XREFquadv,,@code{quadv}}.
 ##
 ## @item AbsTol
 ## Define the absolute error tolerance for the quadrature.  The default
--- a/scripts/geometry/griddata.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/geometry/griddata.m	Mon Oct 19 09:13:53 2020 -0700
@@ -64,8 +64,8 @@
 ##
 ## For 3-D interpolation, the optional argument @var{options} is passed
 ## directly to Qhull when computing the Delaunay triangulation used for
-## interpolation.  See @code{delaunayn} for information on the defaults and
-## how to pass different values.
+## interpolation.  For more information on the defaults and how to pass
+## different values, @pxref{XREFdelaunayn,,@code{delaunayn}}.
 ##
 ## Programming Notes: If the input is complex the real and imaginary parts
 ## are interpolated separately.  Interpolation is normally based on a
--- a/scripts/gui/errordlg.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/gui/errordlg.m	Mon Oct 19 09:13:53 2020 -0700
@@ -39,7 +39,7 @@
 ## ("\n"), or it may be a cellstr array with one element for each line.
 ##
 ## The third optional argument @var{opt} controls the behavior of the dialog.
-## See @code{msgbox} for details.
+## For details, @pxref{XREFmsgbox,,@code{msgbox}}.
 ##
 ## The return value @var{h} is a handle to the figure object used for
 ## building the dialog.
--- a/scripts/gui/warndlg.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/gui/warndlg.m	Mon Oct 19 09:13:53 2020 -0700
@@ -40,7 +40,7 @@
 ## ("\n"), or it may be a cellstr array with one element for each line.
 ##
 ## The third optional argument @var{opt} controls the behavior of the dialog.
-## See @code{msgbox} for details.
+## For details, @pxref{XREFmsgbox,,@code{msgbox}}.
 ##
 ## The return value @var{h} is a handle to the figure object used for
 ## building the dialog.
--- a/scripts/help/lookfor.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/help/lookfor.m	Mon Oct 19 09:13:53 2020 -0700
@@ -49,7 +49,8 @@
 ## related functions that are not a part of Octave.
 ##
 ## The speed of lookup is greatly enhanced by having a cached documentation
-## file.  See @code{doc_cache_create} for more information.
+## file.  For more information,
+## @pxref{XREFdoc_cache_create,,@code{doc_cache_create}}.
 ## @seealso{help, doc, which, path, doc_cache_create}
 ## @end deftypefn
 
--- a/scripts/linear-algebra/cond.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/linear-algebra/cond.m	Mon Oct 19 09:13:53 2020 -0700
@@ -39,8 +39,8 @@
 ##
 ## 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, "fro"} which are generally faster.  See @code{norm}
-## for a full discussion of possible @var{p} values.
+## @code{@var{p} = 1, Inf, "fro"} which are generally faster.  For a full
+## discussion of possible @var{p} values, @pxref{XREFnorm,,@code{norm}}.
 ##
 ## The condition number of a matrix quantifies the sensitivity of the matrix
 ## inversion operation when small changes are made to matrix elements.  Ideally
--- a/scripts/miscellaneous/getfield.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/miscellaneous/getfield.m	Mon Oct 19 09:13:53 2020 -0700
@@ -32,8 +32,8 @@
 ## If @var{s} is a structure array then @var{sidx} selects an element of the
 ## structure array, @var{field} specifies the field name of the selected
 ## element, and @var{fidx} selects which element of the field (in the case of
-## an array or cell array).  See @code{setfield} for a more complete
-## description of the syntax.
+## an array or cell array).  For a more complete description of the syntax,
+## @pxref{XREFsetfield,,@code{setfield}}.
 ##
 ## @seealso{setfield, rmfield, orderfields, isfield, fieldnames, isstruct, struct}
 ## @end deftypefn
--- a/scripts/ode/odeset.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/ode/odeset.m	Mon Oct 19 09:13:53 2020 -0700
@@ -119,7 +119,7 @@
 ##
 ## @item @code{OutputFcn}: function_handle
 ## Function to monitor the state during the simulation.  For the form of
-## the function to use see @code{odeplot}.
+## the function to use @pxref{XREFodeplot,,@code{odeplot}}.
 ##
 ## @item @code{OutputSel}: scalar | vector
 ## Indices of elements of the state vector to be passed to the output
--- a/scripts/optimization/fminsearch.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/optimization/fminsearch.m	Mon Oct 19 09:13:53 2020 -0700
@@ -55,8 +55,9 @@
 ## @code{200 * number_of_variables}, i.e., @code{200 * length (@var{x0})}.
 ## The value must be a positive integer.
 ##
-## For a description of the other options, see @code{optimset}.  To initialize
-## an options structure with default values for @code{fminsearch} use
+## For a description of the other options,
+## @pxref{XREFoptimset,,@code{optimset}}.  To initialize an options structure
+## with default values for @code{fminsearch} use
 ## @code{options = optimset ("fminsearch")}.
 ##
 ## @code{fminsearch} may also be called with a single structure argument
--- a/scripts/optimization/fminunc.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/optimization/fminunc.m	Mon Oct 19 09:13:53 2020 -0700
@@ -70,7 +70,8 @@
 ## @var{x}, while @qcode{"TolFun"} is a tolerance for the objective function
 ## value @var{fval}.  The default is @code{1e-6} for both options.
 ##
-## For a description of the other options, see @code{optimset}.
+## For a description of the other options,
+## @pxref{XREFoptimset,,@code{optimset}}.
 ##
 ## On return, @var{x} is the location of the minimum and @var{fval} contains
 ## the value of the objective function at @var{x}.
--- a/scripts/optimization/fsolve.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/optimization/fsolve.m	Mon Oct 19 09:13:53 2020 -0700
@@ -78,8 +78,9 @@
 ## while @qcode{"TolFun"} is a tolerance for equations.  Default is @code{1e-6}
 ## for both @qcode{"TolX"} and @qcode{"TolFun"}.
 ##
-## For a description of the other options, see @code{optimset}.  To initialize
-## an options structure with default values for @code{fsolve} use
+## For a description of the other options,
+## @pxref{XREFoptimset,,@code{optimset}}.  To initialize an options structure
+## with default values for @code{fsolve} use
 ## @code{options = optimset ("fsolve")}.
 ##
 ## The first output @var{x} is the solution while the second output @var{fval}
--- a/scripts/strings/erase.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/strings/erase.m	Mon Oct 19 09:13:53 2020 -0700
@@ -64,7 +64,7 @@
 ## @end group
 ## @end example
 ##
-## See @code{strrep} for processing overlaps.
+## For processing overlaps, @pxref{XREFstrrep,,@code{strrep}}.
 ##
 ## @seealso{strrep, regexprep}
 ## @end deftypefn
--- a/scripts/testfun/example.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/testfun/example.m	Mon Oct 19 09:13:53 2020 -0700
@@ -39,7 +39,7 @@
 ## a string @var{s}, with @var{idx} indicating the ending position of the
 ## various examples.
 ##
-## See @code{demo} for a complete explanation.
+## For a complete explanation @pxref{XREFdemo,,@code{demo}}.
 ## @seealso{demo, test}
 ## @end deftypefn
 
--- a/scripts/time/datenum.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/time/datenum.m	Mon Oct 19 09:13:53 2020 -0700
@@ -42,12 +42,12 @@
 ## The fractional part, @code{rem (@var{days}, 1)} corresponds to the time
 ## on the given day.
 ##
-## The input may be a date vector (see @code{datevec}),
-## datestr (see @code{datestr}), or directly specified as input.
+## The input may be a date vector (@pxref{XREFdatevec,,datevec}),
+## date string (@pxref{XREFdatestr,,datestr}), or directly specified as input.
 ##
 ## When processing input datestrings, @var{f} is the format string used to
-## interpret date strings (see @code{datestr}).  If no format @var{f} is
-## specified, then a relatively slow search is performed through various
+## interpret date strings (@pxref{XREFdatestr,,datestr}).  If no format @var{f}
+## is specified, then a relatively slow search is performed through various
 ## formats.  It is always preferable to specify the format string @var{f} if
 ## it is known.  Formats which do not specify a particular time component
 ## will have the value set to zero.  Formats which do not specify a date
--- a/scripts/time/datestr.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/time/datestr.m	Mon Oct 19 09:13:53 2020 -0700
@@ -30,9 +30,10 @@
 ## Format the given date/time according to the format @var{f} and return
 ## the result in @var{str}.
 ##
-## @var{date} is a serial date number (see @code{datenum}), a date vector (see
-## @code{datevec}), or a string or cell array of strings.  In the latter case,
-## it is passed to @code{datevec} to guess the input date format.
+## @var{date} is a serial date number (@pxref{XREFdatenum,,@code{datenum}}), a
+## date vector (@pxref{XREFdatevec,,@code{datevec}}), or a string or cell array
+## of strings.  In the latter case, it is passed to @code{datevec} to guess the
+## input date format.
 ##
 ## @var{f} can be an integer which corresponds to one of the codes in the table
 ## below, or a date format string.
--- a/scripts/time/datevec.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/time/datevec.m	Mon Oct 19 09:13:53 2020 -0700
@@ -29,19 +29,19 @@
 ## @deftypefnx {} {@var{v} =} datevec (@var{date}, @var{p})
 ## @deftypefnx {} {@var{v} =} datevec (@var{date}, @var{f}, @var{p})
 ## @deftypefnx {} {[@var{y}, @var{m}, @var{d}, @var{h}, @var{mi}, @var{s}] =} datevec (@dots{})
-## Convert a serial date number (see @code{datenum}) or date string (see
-## @code{datestr}) into a date vector.
+## Convert a serial date number (@pxref{XREFdatenum,,@code{datenum}}) or date
+## string (@pxref{XREFdatestr,,@code{datestr}}) into a date vector.
 ##
 ## A date vector is a row vector with six members, representing the year,
 ## month, day, hour, minute, and seconds respectively.
 ##
 ## @var{f} is the format string used to interpret date strings
-## (see @code{datestr}).  If @var{date} is a string, but no format is
-## specified, then a relatively slow search is performed through various
-## formats.  It is always preferable to specify the format string @var{f} if it
-## is known.  Formats which do not specify a particular time component will
-## have the value set to zero.  Formats which do not specify a date will
-## default to January 1st of the current year.
+## (@pxref{XREFdatestr,,@code{datestr}}).  If @var{date} is a string, but no
+## format is specified, then a relatively slow search is performed through
+## various formats.  It is always preferable to specify the format string
+## @var{f} if it is known.  Formats which do not specify a particular time
+## component will have the value set to zero.  Formats which do not specify a
+## date will default to January 1st of the current year.
 ##
 ## @var{p} is the year at the start of the century to which two-digit years
 ## will be referenced.  If not specified, it defaults to the current year minus
--- a/scripts/time/now.m	Mon Oct 19 08:26:46 2020 -0700
+++ b/scripts/time/now.m	Mon Oct 19 09:13:53 2020 -0700
@@ -26,7 +26,7 @@
 ## -*- texinfo -*-
 ## @deftypefn {} {t =} now ()
 ## Return the current local date/time as a serial day number
-## (see @code{datenum}).
+## (@pxref{XREFdatenum,,@code{datenum}}).
 ##
 ## The integral part, @code{floor (now)} corresponds to the number of days
 ## between today and Jan 1, 0000.