changeset 28713:28d2511f2af2 stable

maint: grammarcheck documentation ahead of 6.1 release. * basics.txi, external.txi, file-io.cc, audiodevinfo.cc, ode15i.m, ode15s.m, ode23.m, ode23s.m, ode45.m, pkg.m, get_inverse_dependencies.m, legend.m, gui_mainfcn.m, hgtransform.m, __debug_octave__.m: Grammarcheck documentation ahead of 6.1 release.
author Rik <rik@octave.org>
date Thu, 10 Sep 2020 14:28:33 -0700
parents 29b627624aaa
children d8dcb36bb904
files doc/interpreter/basics.txi doc/interpreter/external.txi libinterp/corefcn/file-io.cc libinterp/dldfcn/audiodevinfo.cc scripts/ode/ode15i.m scripts/ode/ode15s.m scripts/ode/ode23.m scripts/ode/ode23s.m scripts/ode/ode45.m scripts/pkg/pkg.m scripts/pkg/private/get_inverse_dependencies.m scripts/plot/appearance/legend.m scripts/plot/util/gui_mainfcn.m scripts/plot/util/hgtransform.m scripts/testfun/__debug_octave__.m
diffstat 15 files changed, 78 insertions(+), 65 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/basics.txi	Thu Sep 10 17:20:31 2020 -0400
+++ b/doc/interpreter/basics.txi	Thu Sep 10 14:28:33 2020 -0700
@@ -392,11 +392,12 @@
 invoke Octave with the @option{--verbose} option but without the
 @option{--silent} option.
 
-The startup files are always processes in the system's locale charset
-(independent of the .m file encoding that is set e.g. in the GUI properties).
-That is until a user manually sets the .m file encoding (e.g. in one of the
-startup files) and triggers re-parsing the .m files.  This can be done with the
-undocumented core function @code{__mfile_encoding__}:
+The startup files are always processed in the system's locale charset
+(independent of the m-file encoding that is set, for example, in the GUI
+properties).  In other words, the system's locale charset is in effect until a
+user manually sets the m-file encoding (e.g., in one of the startup files) and
+triggers re-parsing of any relevant m-files.  Octave can be forced to use a
+new encoding with the undocumented function @code{__mfile_encoding__}:
 
 @example
 @group
@@ -405,8 +406,8 @@
 @end group
 @end example
 
-This changes the encoding that is used to interpret all subsequently run startup
-and .m files (not including the currently executing file).
+This changes the encoding that is used to interpret all subsequently run
+startup and m-files (not including the currently executing file).
 
 @node Quitting Octave
 @section Quitting Octave
--- a/doc/interpreter/external.txi	Thu Sep 10 17:20:31 2020 -0400
+++ b/doc/interpreter/external.txi	Thu Sep 10 14:28:33 2020 -0700
@@ -1758,9 +1758,9 @@
 for all built-in functions are collected in the header file
 @code{builtin-defun-decls.h}.  This feature should be used with care as the
 list of built-in functions can change.  No guarantees can be made that a
-function that is currently a built-in won't be implemented as a .m file or as a
-dynamically linked function in the future.  An example of how to call built-in
-functions from C++ can be seen in the code
+function that is currently a built-in won't be implemented as a @file{.m} file
+or as a dynamically linked function in the future.  An example of how to call
+built-in functions from C++ can be seen in the code
 
 @example
 @EXAMPLEFILE(standalonebuiltin.cc)
--- a/libinterp/corefcn/file-io.cc	Thu Sep 10 17:20:31 2020 -0400
+++ b/libinterp/corefcn/file-io.cc	Thu Sep 10 14:28:33 2020 -0700
@@ -500,8 +500,8 @@
 character string that specifies whether the file is to be opened for
 reading, writing, or both.  The @var{encoding} is a character string with a
 valid encoding identifier.  This encoding is used when strings are read from
-or written to the file.  By default, the same encoding is used like for reading
-.m files.
+or written to the file.  By default, the same encoding specified for reading
+@file{.m} files is used for interpreting user files.
 
 The second form of the @code{fopen} function returns a vector of file ids
 corresponding to all the currently open files, excluding the
--- a/libinterp/dldfcn/audiodevinfo.cc	Thu Sep 10 17:20:31 2020 -0400
+++ b/libinterp/dldfcn/audiodevinfo.cc	Thu Sep 10 14:28:33 2020 -0700
@@ -89,7 +89,7 @@
 
 The @var{devinfo} structure has two fields @qcode{"input"} and
 @qcode{"output"}.  The value of each field is a structure array with fields
-@qcode{"Name"}, @qcode{@nospell{"DriverVersion"}} and @qcode{"ID"} describing
+@qcode{"Name"}, @nospell{@qcode{"DriverVersion"}} and @qcode{"ID"} describing
 an audio device.
 
 If the optional argument @var{io} is 1, return information about input devices
@@ -103,7 +103,7 @@
 If the optional argument @var{name} is provided, return the ID of the named
 device.
 
-If the optional argument @qcode{@nospell{"DriverVersion"}} is given, return the
+If the optional argument @nospell{@qcode{"DriverVersion"}} is given, return the
 name of the driver for the specified device.
 
 Given a sampling rate, bits per sample, and number of channels for an input or
--- a/scripts/ode/ode15i.m	Thu Sep 10 17:20:31 2020 -0400
+++ b/scripts/ode/ode15i.m	Thu Sep 10 14:28:33 2020 -0700
@@ -71,9 +71,9 @@
 ## @w{@code{fieldnames (@var{solution})}} to see the other fields and
 ## additional information returned.
 ##
-## If no output arguments are requested, and no @code{OutputFcn} is specified
-## in @var{ode_opt}, then the @code{OutputFcn} is set to @code{odeplot} and the
-## results of the solver are plotted immediately.
+## If no output arguments are requested, and no @qcode{"OutputFcn"} is
+## specified in @var{ode_opt}, then the @qcode{"OutputFcn"} is set to
+## @code{odeplot} and the results of the solver are plotted immediately.
 ##
 ## If using the @qcode{"Events"} option then three additional outputs may be
 ## returned.  @var{te} holds the time when an Event function returned a zero.
--- a/scripts/ode/ode15s.m	Thu Sep 10 17:20:31 2020 -0400
+++ b/scripts/ode/ode15s.m	Thu Sep 10 14:28:33 2020 -0700
@@ -65,9 +65,9 @@
 ## @w{@code{fieldnames (@var{solution})}} to see the other fields and
 ## additional information returned.
 ##
-## If no output arguments are requested, and no @code{OutputFcn} is specified
-## in @var{ode_opt}, then the @code{OutputFcn} is set to @code{odeplot} and the
-## results of the solver are plotted immediately.
+## If no output arguments are requested, and no @qcode{"OutputFcn"} is
+## specified in @var{ode_opt}, then the @qcode{"OutputFcn"} is set to
+## @code{odeplot} and the results of the solver are plotted immediately.
 ##
 ## If using the @qcode{"Events"} option then three additional outputs may be
 ## returned.  @var{te} holds the time when an Event function returned a zero.
--- a/scripts/ode/ode23.m	Thu Sep 10 17:20:31 2020 -0400
+++ b/scripts/ode/ode23.m	Thu Sep 10 14:28:33 2020 -0700
@@ -68,9 +68,9 @@
 ## @w{@code{fieldnames (@var{solution})}} to see the other fields and
 ## additional information returned.
 ##
-## If no output arguments are requested, and no @code{OutputFcn} is specified
-## in @var{ode_opt}, then the @code{OutputFcn} is set to @code{odeplot} and the
-## results of the solver are plotted immediately.
+## If no output arguments are requested, and no @qcode{"OutputFcn"} is
+## specified in @var{ode_opt}, then the @qcode{"OutputFcn"} is set to
+## @code{odeplot} and the results of the solver are plotted immediately.
 ##
 ## If using the @qcode{"Events"} option then three additional outputs may be
 ## returned.  @var{te} holds the time when an Event function returned a zero.
--- a/scripts/ode/ode23s.m	Thu Sep 10 17:20:31 2020 -0400
+++ b/scripts/ode/ode23s.m	Thu Sep 10 14:28:33 2020 -0700
@@ -36,8 +36,8 @@
 ## @var{fun} is a function handle, inline function, or string containing the
 ## name of the function that defines the ODE: @code{M y' = f(t,y)}.  The
 ## function must accept two inputs where the first is time @var{t} and the
-## second is a column vector of unknowns @var{y}. @var{M} is a constant mass
-## matrix, non-singular and possibly sparse. Set the field @var{Mass} in
+## second is a column vector of unknowns @var{y}.  @var{M} is a constant mass
+## matrix, non-singular and possibly sparse.  Set the field @qcode{"Mass"} in
 ## @var{odeopts} using @var{odeset} to specify a mass matrix.
 ##
 ## @var{trange} specifies the time interval over which the ODE will be
@@ -58,8 +58,9 @@
 ##
 ## The optional fourth argument @var{ode_opt} specifies non-default options to
 ## the ODE solver.  It is a structure generated by @code{odeset}.
-## @code{ode23s} will ignore the following options: "BDF", "InitialSlope",
-## "MassSingular", "MStateDependence", "MvPattern", "MaxOrder", "NonNegative".
+## @code{ode23s} will ignore the following options: @qcode{"BDF"},
+## @qcode{"InitialSlope"}, @qcode{"MassSingular"}, @qcode{"MStateDependence"},
+## @qcode{"MvPattern"}, @qcode{"MaxOrder"}, @qcode{"Non-negative"}.
 ##
 ## The function typically returns two outputs.  Variable @var{t} is a
 ## column vector and contains the times where the solution was found.  The
--- a/scripts/ode/ode45.m	Thu Sep 10 17:20:31 2020 -0400
+++ b/scripts/ode/ode45.m	Thu Sep 10 14:28:33 2020 -0700
@@ -68,9 +68,9 @@
 ## @w{@code{fieldnames (@var{solution})}} to see the other fields and
 ## additional information returned.
 ##
-## If no output arguments are requested, and no @code{OutputFcn} is specified
-## in @var{ode_opt}, then the @code{OutputFcn} is set to @code{odeplot} and the
-## results of the solver are plotted immediately.
+## If no output arguments are requested, and no @qcode{"OutputFcn"} is
+## specified in @var{ode_opt}, then the @qcode{"OutputFcn"} is set to
+## @code{odeplot} and the results of the solver are plotted immediately.
 ##
 ## If using the @qcode{"Events"} option then three additional outputs may be
 ## returned.  @var{te} holds the time when an Event function returned a zero.
--- a/scripts/pkg/pkg.m	Thu Sep 10 17:20:31 2020 -0400
+++ b/scripts/pkg/pkg.m	Thu Sep 10 14:28:33 2020 -0700
@@ -29,18 +29,19 @@
 ## @deftypefnx {} {[@var{out1}, @dots{}] =} pkg (@var{command}, @dots{} )
 ## Manage or query packages (groups of add-on functions) for Octave.
 ##
-## Packages can be installed globally (i.e. for all users of the system) or
-## locally (i.e. for the current user only).
+## Packages can be installed globally (i.e., for all users of the system) or
+## locally (i.e., for the current user only).
 ##
-## Global packages are by default installed in the "global packages store".
-## That is usually located in a subdirectory of the folder where Octave itself
-## is installed in.  Therefore, Octave needs write access to this folder to
-## install global packages.  That usually means that Octave has to run with root
-## access (or "Run as administrator") to be able to install packages globally.
+## Global packages are installed by default in a system-wide location.  This is
+## usually a subdirectory of the folder where Octave itself is installed.
+## Therefore, Octave needs write access to this folder to install global
+## packages.  That usually means that Octave has to run with root access (or
+## "Run as administrator" on Windows) to be able to install packages globally.
 ##
-## In contrast, local packages are by default installed in the user's profile
-## and are only available to that specific user.  Usually, they can be installed
-## without root access (or administrative privileges).
+## In contrast, local packages are installed by default in the user's
+## home directory (profile on Windows) and are only available to that specific
+## user.  Usually, they can be installed without root access (or administrative
+## privileges).
 ##
 ## For global and local packages, there are separate databases holding the
 ## information about the installed packages.  If some package is installed
@@ -63,12 +64,13 @@
 ## @enumerate
 ## @item
 ## If the package depends on other packages (and @code{pkg load} is called
-## without the @qcode{"-nodeps"} option), the package is not loaded immediately.
-## Instead, those dependencies are loaded first (recursively if needed).
+## without the @qcode{"-nodeps"} option), the package is not loaded
+## immediately.  Instead, those dependencies are loaded first (recursively if
+## needed).
 ##
 ## @item
-## When all dependencies are satified, the package's subdirectories are added to
-## the search path.
+## When all dependencies are satified, the package's subdirectories are
+## added to the search path.
 ## @end enumerate
 ##
 ## This load order leads to functions that are provided by dependencies being
@@ -79,9 +81,9 @@
 ## for the package are automatically executed if they are provided by the
 ## package.
 ##
-## Depending on the value of @var{command} and on the number of requested return
-## arguments, @code{pkg} can be used to perform several tasks.  Possible values
-## for @var{command} are:
+## Depending on the value of @var{command} and on the number of requested
+## return arguments, @code{pkg} can be used to perform several tasks.
+## Possible values for @var{command} are:
 ##
 ## @table @samp
 ##
@@ -366,7 +368,7 @@
 ##
 ## @item test
 ## Perform the built-in self tests contained in all functions provided by
-## the named packages.  For example,
+## the named packages.  For example:
 ##
 ## @example
 ## pkg test image
--- a/scripts/pkg/private/get_inverse_dependencies.m	Thu Sep 10 17:20:31 2020 -0400
+++ b/scripts/pkg/private/get_inverse_dependencies.m	Thu Sep 10 14:28:33 2020 -0700
@@ -26,7 +26,7 @@
 ## -*- texinfo -*-
 ## @deftypefn {} {@var{installed_pkgs_list} =} get_inverse_dependencies (@var{installed_pkgs_lst})
 ## Find inverse dependencies, if any, for each package, and store in
-## the struct field "invdeps".
+## the struct field @qcode{"invdeps"}.
 ##
 ## @end deftypefn
 
--- a/scripts/plot/appearance/legend.m	Thu Sep 10 17:20:31 2020 -0400
+++ b/scripts/plot/appearance/legend.m	Thu Sep 10 14:28:33 2020 -0700
@@ -93,11 +93,13 @@
 ## Following is a subset of supported legend properties:
 ## @c The following table is obtained by copying the output of
 ## @c genpropdoc ("legend", "", {"autoupdate", "box", "location", "numcolumns", "orientation", "string", "textcolor"})
+##
 ## @table @asis
 ##
 ## @item @code{autoupdate}: @qcode{"off"} | @{@qcode{"on"}@}
-## Control whether the number of legend items is updated automatically when objects are added to (or deleted from) the peer axes.
-## For example:
+## Control whether the number of legend items is updated automatically when
+## objects are added to (or deleted from) the peer axes.  For example:
+##
 ## @example
 ## @group
 ## ## Create a single plot with its legend.
@@ -114,17 +116,22 @@
 ## @end group
 ## @end example
 ##
-##
 ## @item @code{box}: @qcode{"off"} | @{@qcode{"on"}@}
 ## Control whether the legend has a surrounding box.
 ##
-##
-## @item @code{location}: @qcode{"best"} | @qcode{"bestoutside"} | @qcode{"east"} | @qcode{"eastoutside"} | @qcode{"none"} | @qcode{"north"} | @{@qcode{"northeast"}@} | @qcode{"northeastoutside"} | @qcode{"northoutside"} | @qcode{"northwest"}| @qcode{"northwestoutside"} | @qcode{"south"} | @qcode{"southeast"} | @qcode{"southeastoutside"} | @qcode{"southoutside"} | @qcode{"southwest"} | @qcode{"southwestoutside"} | @qcode{"west"} | @qcode{"westoutside"}
+## @item @code{location}: @qcode{"best"} | @qcode{"bestoutside"} |
+## @qcode{"east"} | @qcode{"eastoutside"} | @qcode{"none"} | @qcode{"north"} |
+## @{@qcode{"northeast"}@} | @qcode{"northeastoutside"} |
+## @qcode{"northoutside"} | @qcode{"northwest"}| @qcode{"northwestoutside"} |
+## @qcode{"south"} | @qcode{"southeast"} | @qcode{"southeastoutside"} |
+## @qcode{"southoutside"} | @qcode{"southwest"} | @qcode{"southwestoutside"} |
+## @qcode{"west"} | @qcode{"westoutside"}
 ## Control the location of the legend.
 ##
+## @item @code{numcolumns}: scalar interger, def. @code{1}
+## Control the number of columns used in the layout of the legend items.
+## For example:
 ##
-## @item @code{numcolumns}: scalar interger, def. @code{1}
-## Control the number of columns used in the layout of the legend items.  For example:
 ## @example
 ## @group
 ## figure ();
@@ -132,15 +139,17 @@
 ## legend ("numcolumns", 3);
 ## @end group
 ## @end example
-## Setting @code{numcolumns} also forces the @code{numcolumnsmode} property to be set to @qcode{"manual"}.
 ##
+## Setting @code{numcolumns} also forces the @code{numcolumnsmode} property
+## to be set to @qcode{"manual"}.
 ##
 ## @item @code{orientation}: @qcode{"horizontal"} | @{@qcode{"vertical"}@}
-## Control whether the legend items are arranged vertically (column-wise) or horizontally (row-wise).
-##
+## Control whether the legend items are arranged vertically (column-wise) or
+## horizontally (row-wise).
 ##
 ## @item @code{string}: string | cell array of strings
 ## List of labels for the legend items.  For example:
+##
 ## @example
 ## @group
 ## figure ();
@@ -154,7 +163,6 @@
 ## @end group
 ## @end example
 ##
-##
 ## @item @code{textcolor}: colorspec, def. @code{[0   0   0]}
 ## Control the color of the text strings for legend item.
 ##
--- a/scripts/plot/util/gui_mainfcn.m	Thu Sep 10 17:20:31 2020 -0400
+++ b/scripts/plot/util/gui_mainfcn.m	Thu Sep 10 14:28:33 2020 -0700
@@ -25,8 +25,8 @@
 ########################################################################
 
 ## -*- texinfo -*-
-## @deftypefn  {} {[@var{@dots{}}] =} gui_mainfcn  (@var{gui_state}, @dots{})
-## Compatibility function for figures created with Matlab's Guide.
+## @deftypefn {} {[@var{@dots{}}] =} gui_mainfcn (@var{gui_state}, @dots{})
+## Compatibility function for figures created with @sc{matlab}'s Guide.
 ##
 ## This function is undocumented and users should not use it in new code.
 ##
--- a/scripts/plot/util/hgtransform.m	Thu Sep 10 17:20:31 2020 -0400
+++ b/scripts/plot/util/hgtransform.m	Thu Sep 10 14:28:33 2020 -0700
@@ -31,11 +31,10 @@
 ## Create a graphics transform object.
 ##
 ## FIXME: Need to write documentation.
-## FIXME: Add 'makehgtform' to seealso list when it is implemented.
+## FIXME: Add <makehgtform> to seealso list when it is implemented.
 ## @seealso{hggroup}
 ## @end deftypefn
 
-
 ## FIXME: hgtransform should be a C++ graphics object, not an m-file.
 ##        For the moment (3/7/17), it is quicker to implement something in
 ##        an m-file.  But, this approach requires double the memory (original
--- a/scripts/testfun/__debug_octave__.m	Thu Sep 10 17:20:31 2020 -0400
+++ b/scripts/testfun/__debug_octave__.m	Thu Sep 10 14:28:33 2020 -0700
@@ -30,14 +30,16 @@
 ## Octave process.
 ##
 ## If @var{command_string} is not supplied, it should have a single
-## @qcode{%d} format option that will be replaced by the process ID
+## @code{%d} format option that will be replaced by the process ID
 ## for the current Octave process, as returned by @code{getpid}.  For
 ## example, on Windows systems the following two commands are
 ## equivalent:
 ##
 ## @example
+## @group
 ## __debug_octave__ ()
 ## __debug_octave__ ("start gdb -p %d")
+## @end group
 ## @end example
 ## @end deftypefn