# HG changeset patch # User Rik # Date 1599773313 25200 # Node ID 28d2511f2af2d4c22406afe635f640c448fd8057 # Parent 29b627624aaa2a4c59ede368a2a3371a7e602d6e 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. diff -r 29b627624aaa -r 28d2511f2af2 doc/interpreter/basics.txi --- 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 diff -r 29b627624aaa -r 28d2511f2af2 doc/interpreter/external.txi --- 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) diff -r 29b627624aaa -r 28d2511f2af2 libinterp/corefcn/file-io.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 diff -r 29b627624aaa -r 28d2511f2af2 libinterp/dldfcn/audiodevinfo.cc --- 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 diff -r 29b627624aaa -r 28d2511f2af2 scripts/ode/ode15i.m --- 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. diff -r 29b627624aaa -r 28d2511f2af2 scripts/ode/ode15s.m --- 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. diff -r 29b627624aaa -r 28d2511f2af2 scripts/ode/ode23.m --- 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. diff -r 29b627624aaa -r 28d2511f2af2 scripts/ode/ode23s.m --- 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 diff -r 29b627624aaa -r 28d2511f2af2 scripts/ode/ode45.m --- 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. diff -r 29b627624aaa -r 28d2511f2af2 scripts/pkg/pkg.m --- 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 diff -r 29b627624aaa -r 28d2511f2af2 scripts/pkg/private/get_inverse_dependencies.m --- 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 diff -r 29b627624aaa -r 28d2511f2af2 scripts/plot/appearance/legend.m --- 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. ## diff -r 29b627624aaa -r 28d2511f2af2 scripts/plot/util/gui_mainfcn.m --- 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. ## diff -r 29b627624aaa -r 28d2511f2af2 scripts/plot/util/hgtransform.m --- 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 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 diff -r 29b627624aaa -r 28d2511f2af2 scripts/testfun/__debug_octave__.m --- 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