From a41dcfb8e145f849699207ca68ca18066b8cc561 Mon Sep 17 00:00:00 2001 From: Rik Date: Thu, 23 Nov 2023 18:28:08 -0800 Subject: [PATCH 1/3] doc: grammarcheck m-files before 9.1 release. * scripts/help/bytecode.m, scripts/linear-algebra/tensorprod.m, scripts/optimization/optimget.m, scripts/optimization/optimset.m, scripts/plot/appearance/xlim.m, scripts/plot/appearance/ylim.m, scripts/plot/appearance/zlim.m, scripts/plot/draw/quiver.m, scripts/plot/draw/quiver3.m, scripts/plot/util/print.m, scripts/set/ismembertol.m, scripts/statistics/cov.m, scripts/statistics/mad.m, scripts/time/datenum.m: grammarcheck m-files before 9.1 release. --- scripts/help/bytecode.m | 4 ++-- scripts/linear-algebra/tensorprod.m | 2 +- scripts/optimization/optimget.m | 6 +++--- scripts/optimization/optimset.m | 6 +++--- scripts/plot/appearance/xlim.m | 2 +- scripts/plot/appearance/ylim.m | 2 +- scripts/plot/appearance/zlim.m | 2 +- scripts/plot/draw/quiver.m | 2 +- scripts/plot/draw/quiver3.m | 2 +- scripts/plot/util/print.m | 2 +- scripts/set/ismembertol.m | 30 +++++++++++++++-------------- scripts/statistics/cov.m | 2 +- scripts/statistics/mad.m | 4 ++-- scripts/time/datenum.m | 6 +++--- 14 files changed, 37 insertions(+), 35 deletions(-) diff --git a/scripts/help/bytecode.m b/scripts/help/bytecode.m index 2f54c9a61d..f249d91ee5 100644 --- a/scripts/help/bytecode.m +++ b/scripts/help/bytecode.m @@ -28,8 +28,8 @@ ## Summary of commands related to Octave's bytecode interpreter. ## ## As of Octave 9, the bytecode interpreter is considered @emph{experimental}. -## The user is encouraged to test it with that in mind. All bytecode functions, -## being experimental, may be renamed in future. +## The user is encouraged to test it with that in mind. All bytecode +## functions, being experimental, may be renamed in future. ## ## To switch on the bytecode interpreter, type: @code{__vm_enable__ (1)} ## diff --git a/scripts/linear-algebra/tensorprod.m b/scripts/linear-algebra/tensorprod.m index c63beff40a..cf4c151c54 100644 --- a/scripts/linear-algebra/tensorprod.m +++ b/scripts/linear-algebra/tensorprod.m @@ -51,7 +51,7 @@ ## @var{C}. The specified @var{value} should be the total number of dimensions ## of @var{A}. ## -## Matlab Compatibility: Octave does not currently support the +## @sc{matlab} Compatibility: Octave does not currently support the ## @qcode{"@var{property_name}=@var{value}"} syntax for the ## @qcode{"NumDimensionsA"} parameter. ## diff --git a/scripts/optimization/optimget.m b/scripts/optimization/optimget.m index fe38a6e3a4..1f93d9f5cb 100644 --- a/scripts/optimization/optimget.m +++ b/scripts/optimization/optimget.m @@ -36,12 +36,12 @@ ## @code{optimget} will attempt to match @var{par} to a standard parameter ## and will return that parameter's value if a match is found. Matching is ## case insensitive and is based on character matching at the start of the -## parameter name. @code{optimget} produces an error if it finds multiple -## ambiguous matches. If no standard parameter matches are found a warning is +## parameter name. @code{optimget} produces an error if it finds multiple +## ambiguous matches. If no standard parameter matches are found a warning is ## issued. See @code{optimset} for information about the standard options ## list. ## -## Note: Only parameter names from the standard list are considered when +## Note: Only parameter names from the standard list are considered when ## matching short parameter names, and @var{par} will always be expanded to ## match a standard parameter even if an exact non-standard match exists. The ## value of a non-standard parameter that is ambigious with one or more diff --git a/scripts/optimization/optimset.m b/scripts/optimization/optimset.m index 041498e373..7e49d3ffbc 100644 --- a/scripts/optimization/optimset.m +++ b/scripts/optimization/optimset.m @@ -125,18 +125,18 @@ ## @item Updating ## @end table ## -## This list can be extended by the user or other loaded Octave packages. An +## This list can be extended by the user or other loaded Octave packages. An ## updated valid parameters list can be queried using the no-argument form of ## @code{optimset}. ## -## Note 1: Only parameter names from the standard list are considered when +## Note 1: Only parameter names from the standard list are considered when ## matching short parameter names, and @var{par} will always be expanded ## to match a standard parameter even if an exact non-standard match exists. ## The value of a non-standard parameter that is ambigious with one or more ## standard parameters cannot be set by @code{optimset} and can only be set ## using @code{setfield} or dot notation for structs. ## -## Note 2: The optimization options structure is primarily intended for +## Note 2: The optimization options structure is primarily intended for ## manipulation of known parameters by @code{optimset} and @code{optimget}. ## Unpredictable behavior on future calls to @code{optimset} or ## @code{optimget} can result from creating non-standard or ambiguous diff --git a/scripts/plot/appearance/xlim.m b/scripts/plot/appearance/xlim.m index a713d5cd20..937272f237 100644 --- a/scripts/plot/appearance/xlim.m +++ b/scripts/plot/appearance/xlim.m @@ -48,7 +48,7 @@ ## The special values -Inf and Inf can be used to indicate that either ## the lower axis limit or upper axis limit should be automatically calculated. ## -## The current limit calculation "mode" may be one of +## The current limit calculation @qcode{"mode"} may be one of ## ## @table @asis ## @item @qcode{"auto"} (default) diff --git a/scripts/plot/appearance/ylim.m b/scripts/plot/appearance/ylim.m index 5567f5c713..0b7bb9a7a9 100644 --- a/scripts/plot/appearance/ylim.m +++ b/scripts/plot/appearance/ylim.m @@ -48,7 +48,7 @@ ## The special values -Inf and Inf can be used to indicate that either ## the lower axis limit or upper axis limit should be automatically calculated. ## -## The current limit calculation "mode" may be one of +## The current limit calculation @qcode{"mode"} may be one of ## ## @table @asis ## @item @qcode{"auto"} (default) diff --git a/scripts/plot/appearance/zlim.m b/scripts/plot/appearance/zlim.m index 86b5ba5c7b..7298c9a99c 100644 --- a/scripts/plot/appearance/zlim.m +++ b/scripts/plot/appearance/zlim.m @@ -48,7 +48,7 @@ ## The special values -Inf and Inf can be used to indicate that either ## the lower axis limit or upper axis limit should be automatically calculated. ## -## The current limit calculation "mode" may be one of +## The current limit calculation @qcode{"mode"} may be one of ## ## @table @asis ## @item @qcode{"auto"} (default) diff --git a/scripts/plot/draw/quiver.m b/scripts/plot/draw/quiver.m index 4e8e97757f..7b9575c134 100644 --- a/scripts/plot/draw/quiver.m +++ b/scripts/plot/draw/quiver.m @@ -46,7 +46,7 @@ ## The optional input @var{s} is a scalar defining a scaling factor to use for ## the arrows of the field relative to the mesh spacing. A value of 1.0 will ## result in the longest vector exactly filling one grid square. A value of 0 -## or "off" disables all scaling. The default value is 0.9. +## or @qcode{"off"} disables all scaling. The default value is 0.9. ## ## The style to use for the plot can be defined with a line style, @var{style}, ## of the same format as the @code{plot} command. If a marker is specified diff --git a/scripts/plot/draw/quiver3.m b/scripts/plot/draw/quiver3.m index f9f0a78aee..4033244788 100644 --- a/scripts/plot/draw/quiver3.m +++ b/scripts/plot/draw/quiver3.m @@ -46,7 +46,7 @@ ## The optional input @var{s} is a scalar defining a scaling factor to use for ## the arrows of the field relative to the mesh spacing. A value of 1.0 will ## result in the longest vector exactly filling one grid cube. A value of 0 -## or "off" disables all scaling. The default value is 0.9. +## or @qcode{"off"} disables all scaling. The default value is 0.9. ## ## The style to use for the plot can be defined with a line style @var{style} ## of the same format as the @code{plot} command. If a marker is specified diff --git a/scripts/plot/util/print.m b/scripts/plot/util/print.m index 9846401ca9..d76d0eefe9 100644 --- a/scripts/plot/util/print.m +++ b/scripts/plot/util/print.m @@ -157,7 +157,7 @@ ## Caution: If Octave was built against Qt version earlier than 5.13, ## @option{-svgconvert} may lead to inaccurate rendering of image objects. ## -## @item -polymerge +## @item -polymerge ## @itemx -nopolymerge ## @itemx -polymerge-all ## When using the SVG based backend @option{-svgconvert}, faces are rendered diff --git a/scripts/set/ismembertol.m b/scripts/set/ismembertol.m index 3d6015cadf..6a269d67d7 100644 --- a/scripts/set/ismembertol.m +++ b/scripts/set/ismembertol.m @@ -28,15 +28,15 @@ ## @deftypefnx {} {@var{tf} =} ismembertol (@var{a}, @var{s}, @var{tol}) ## @deftypefnx {} {@var{tf} =} ismembertol (@var{a}, @var{s}, @var{name}, @var{value}) ## @deftypefnx {} {[@var{tf}, @var{s_idx}] =} ismembertol (@dots{}) -## Check if values are member of a set within a tolerance. +## Check if values are members of a set within a tolerance. ## ## This functions returns a logical matrix @var{tf} with the same shape as ## @var{a} which is true (1) where the element in @var{a} is close to @var{s} ## within a tolerance @var{tol} and false (0) if it is not. If @var{tol} is -## not provided, a default tolerance of @qcode{1e-6} is used. +## not specified, a default tolerance of @code{1e-6} is used. ## -## If a second output argument is requested, then the index into @var{s} of -## each matching element is also returned. +## If a second output argument is requested then the index into @var{s} of each +## matching element is also returned. ## ## The inputs @var{a} and @var{s} must be numeric values. ## @@ -50,35 +50,37 @@ ## @end group ## @end example ## -## Optional property-value pairs @var{name} and @var{value} might be given. -## For each of these pairs, the @var{name} might be one of the following -## strings: +## Optional property/value pairs may be given to change the function's +## behavior. The property may be one of following strings: ## ## @table @asis ## @item @qcode{"ByRows"} -## If set to @qcode{false} (default), all elements in @var{a} and @var{s} are -## treated separately. If set to @qcode{true}, @var{tf} contains @qcode{true} +## If set to @code{false} (default), all elements in @var{a} and @var{s} are +## treated separately. If set to @code{true}, @var{tf} will be @code{true} ## for each row in @var{a} that matches a row in @var{s} within the given ## tolerance. Two rows, @var{u} and @var{v}, are within tolerance if they -## fullfill the condition @qcode{all (abs (u-v) <= tol*max (abs ([a;s])))}. +## fulfill the condition @code{all (abs (u-v) <= tol*max (abs ([a;s])))}. ## ## @item @qcode{"OutputAllIndices"} -## If set to @qcode{false} (default), @var{s_idx} contains indices for one -## of the matches. If set to @qcode{true}, @var{s_idx} is a cell array +## If set to @code{false} (default), @var{s_idx} contains indices for one +## of the matches. If set to @code{true}, @var{s_idx} is a cell array ## containing the indices for all elements in @var{s} that are within tolerance ## of the corresponding value in @var{a}. ## ## @item @qcode{"DataScale"} -## The corresponding value @var{DS} is used to change the scale factor in the -## tolerance test to @qcode{abs(u-v) <= tol*DS}. By default, the maximum +## The provided value @var{DS} is used to change the scale factor in the +## tolerance test to @code{abs (u-v) <= tol*@var{DS}}. By default, the maximum ## absolute value in @var{a} and @var{s} is used as the scale factor. ## @end table ## ## Example: +## ## @example +## @group ## s = [1:6].' * pi; ## a = 10.^log10 (x); ## [tf, s_idx] = ismembertol (a, s); +## @end group ## @end example ## ## @seealso{ismember, lookup, unique, union, intersect, setdiff, setxor} diff --git a/scripts/statistics/cov.m b/scripts/statistics/cov.m index d1a4f873fe..6939099f20 100644 --- a/scripts/statistics/cov.m +++ b/scripts/statistics/cov.m @@ -98,7 +98,7 @@ ## @math{N}, being used to calculated each element of the covariance matrix. ## @end table ## -## Compatibility Note: Previous versions of @code{cov} treated rows +## Compatibility Note: Previous versions of @code{cov} treated rows ## @var{x} and @var{y} as multivariate random variables. This version ## attempts to maintain full compatibility with @sc{matlab} by treating ## @var{x} and @var{y} as two univariate distributions regardless of shape, diff --git a/scripts/statistics/mad.m b/scripts/statistics/mad.m index 6c595e6ef8..67dfd37577 100644 --- a/scripts/statistics/mad.m +++ b/scripts/statistics/mad.m @@ -44,12 +44,12 @@ ## @var{mad} = median (abs (@var{x} - median (@var{x}))) ## @end example ## -## If @var{x} is a vector, compute @code{mad} for each element in @var{x}. If +## If @var{x} is a vector, compute @code{mad} for each element in @var{x}. If ## @var{x} is an array the calculation is performed over the first ## non-singleton dimension. ## ## @code{mad} excludes NaN values from calculation similar to using the -## @qcode{omitnan} option in @code{var}, @code{mean}, and @code{median}. +## @code{omitnan} option in @code{var}, @code{mean}, and @code{median}. ## ## The optional argument @var{opt} determines whether mean or median absolute ## deviation is calculated. The default is 0 which corresponds to mean diff --git a/scripts/time/datenum.m b/scripts/time/datenum.m index 60e1f10109..b989f04aef 100644 --- a/scripts/time/datenum.m +++ b/scripts/time/datenum.m @@ -54,9 +54,9 @@ ## 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. ## -## When passing separate @var{year}, @var{month}, @var{day}, etc. arguments, -## each may be a scalar or nonscalar array. Nonscalar inputs must all be of -## the same size. Scalar inputs will be expanded to be the size of the +## When passing separate @var{year}, @var{month}, @var{day}, etc.@: arguments, +## each may be a scalar or nonscalar array. Nonscalar inputs must all be of +## the same size. Scalar inputs will be expanded to be the size of the ## nonscalar inputs. ## ## @var{p} is the year at the start of the century to which two-digit years From d46ac79ca14c5976c19a525776760fdebeee1c9f Mon Sep 17 00:00:00 2001 From: Rik Date: Thu, 23 Nov 2023 19:42:27 -0800 Subject: [PATCH 2/3] doc: grammarcheck C++ files before 9.1 release. * libinterp/corefcn/graphics.cc, libinterp/corefcn/input.cc, libinterp/corefcn/pr-output.cc, libinterp/corefcn/qz.cc, libinterp/corefcn/sysdep.cc: grammarcheck C++ files before 9.1 release. --- libinterp/corefcn/compile.cc | 88 +++++++++++++++++----------------- libinterp/corefcn/graphics.cc | 1 + libinterp/corefcn/input.cc | 2 +- libinterp/corefcn/pr-output.cc | 2 + libinterp/corefcn/qz.cc | 14 +++--- libinterp/corefcn/sysdep.cc | 14 +++--- 6 files changed, 62 insertions(+), 59 deletions(-) diff --git a/libinterp/corefcn/compile.cc b/libinterp/corefcn/compile.cc index e0e2d7952c..9c5c7c87a5 100644 --- a/libinterp/corefcn/compile.cc +++ b/libinterp/corefcn/compile.cc @@ -47,13 +47,13 @@ extern "C" void dummy_mark_2 (void); DEFUN (__dummy_mark_1__, , , doc: /* -*- texinfo -*- -@deftypefn {} {} __dummy_mark_1__ () +@deftypefn {} {} __dummy_mark_1__ () -Dummy function that calls the c-function void dummy_mark_1 (void) +Dummy function that calls the C-function @code{void dummy_mark_1 (void)} that does nothing. -Usefull for e.g. marking start and end for Callgrind analyzis -or as an entry point for gdb. +This is useful for marking start and end for Callgrind analysis or as an entry +point for @code{gdb}. @end deftypefn */) { @@ -64,13 +64,13 @@ or as an entry point for gdb. DEFUN (__dummy_mark_2__, , , doc: /* -*- texinfo -*- -@deftypefn {} {} __dummy_mark_2__ () +@deftypefn {} {} __dummy_mark_2__ () -Dummy function that calls the c-function void dummy_mark_2 (void) +Dummy function that calls the C-function @code{void dummy_mark_2 (void)} that does nothing. -Usefull for e.g. marking start and end for Callgrind analyzis -or as an entry point for gdb. +This is useful for marking start and end for Callgrind analysis or as an entry +point for @code{gdb}. @end deftypefn */) { @@ -81,7 +81,7 @@ or as an entry point for gdb. DEFUN (__vm_clear_cache__, , , doc: /* -*- texinfo -*- -@deftypefn {} {@var{val} =} __vm_clear_cache__ () +@deftypefn {} {@var{val} =} __vm_clear_cache__ () Internal function. @@ -94,16 +94,18 @@ Internal function. DEFUN (__vm_print_trace__, , , doc: /* -*- texinfo -*- -@deftypefn {} {@var{prints_trace} =} __vm_print_trace__ ()) +@deftypefn {} {@var{print_trace} =} __vm_print_trace__ ()) Internal function. -Print a debug trace from the VM. Toggles on or off each call. +Print a debug trace from the VM@. -There has to be a breakpoint set in some file for the trace -to actually print anything. +Toggles on or off each call. -Returns true if a trace will be printed from now on, false otherwise. +There has to be a breakpoint set in some file for the trace to actually print +anything. + +The return value is true if a trace will be printed and false otherwise. @end deftypefn */) { @@ -114,11 +116,11 @@ Returns true if a trace will be printed from now on, false otherwise. DEFUN (__ref_count__, args, , doc: /* -*- texinfo -*- -@deftypefn {} {@var{count} =} __ref_count__ (@var{obj})) +@deftypefn {} {@var{count} =} __ref_count__ (@var{obj})) Internal function. -Returns reference count for an object. +Return the reference count for an object. @end deftypefn */) { @@ -134,13 +136,12 @@ Returns reference count for an object. DEFMETHOD (__vm_is_executing__, interp, , , doc: /* -*- texinfo -*- -@deftypefn {} {@var{is_executing} =} __vm_is_executing__ ()) +@deftypefn {} {@var{is_executing} =} __vm_is_executing__ ()) Internal function. -Returns true if the VM is executing the function calling __vm_is_executing__ (). - -False otherwise. +Return true if the VM is executing the function calling +@code{__vm_is_executing__ ()}, and false otherwise. @end deftypefn */) { @@ -172,27 +173,28 @@ Profile code running in the VM. @table @code @item __vm_profile__ on -Start the profiler, clearing all previously collected data if there is any. +Start the profiler. Any previously collected data is cleared. @item __vm_profile__ off -Stop profiling. The collected data can later be retrieved and examined -with @code{T = profile ("info")}. +Stop profiling. The collected data can be retrieved and examined with +@code{T = profile ("info")}. @item __vm_profile__ clear Clear all collected profiler data. @item __vm_profile__ resume -Restart profiling without clearing the old data. All newly collected +Restart profiling without clearing existing data. All newly collected statistics are added to the existing ones. @item __vm_profile__ -Toggles between profiling and printing the result of the profiler. +Toggle between profiling and printing the result of the profiler. Clears the profiler on each print. @item __vm_profile__ info -Prints the profiler data. +Print the profiler data. -Not that output to a variable is not implemented yet. +Programming Note: The calling form that returns profiler data in a variable +is not implemented yet. @end table @@ -273,7 +275,7 @@ Not that output to a variable is not implemented yet. DEFMETHOD (__vm_print_bytecode__, interp, args, , doc: /* -*- texinfo -*- @deftypefn {} {@var{success} =} __vm_print_bytecode__ (@var{fn_name})) -@deftypefnx {} {@var{success} =} __vm_print_bytecode__ (@var{fn_handle})) +@deftypefnx {} {@var{success} =} __vm_print_bytecode__ (@var{fn_handle})) Internal function. @@ -348,7 +350,7 @@ Prints the bytecode of a function name or function handle, if any. DEFMETHOD (__vm_is_compiled__, interp, args, , doc: /* -*- texinfo -*- @deftypefn {} {@var{is_compiled} =} __vm_is_compiled__ (@var{fn_name}) -@deftypefnx {} {@var{is_compiled} =} __vm_is_compiled__ (@var{fn_handle}) +@deftypefnx {} {@var{is_compiled} =} __vm_is_compiled__ (@var{fn_handle}) Internal function. @@ -412,8 +414,8 @@ False otherwise. DEFMETHOD (__vm_compile__, interp, args, , doc: /* -*- texinfo -*- @deftypefn {} {@var{success} =} __vm_compile__ (@var{fn_name}) -@deftypefnx {} {@var{success} =} __vm_compile__ (@var{fn_name}, "clear") -@deftypefnx {} {@var{success} =} __vm_compile__ (@var{fn_name}, "print") +@deftypefnx {} {@var{success} =} __vm_compile__ (@var{fn_name}, "clear") +@deftypefnx {} {@var{success} =} __vm_compile__ (@var{fn_name}, "print") Internal function. @@ -567,27 +569,25 @@ DEFUN (__vm_enable__, args, nargout, @deftypefn {} {@var{val} =} __vm_enable__ () @deftypefnx {} {@var{old_val} =} __vm_enable__ (@var{new_val}) @deftypefnx {} {@var{old_val} =} __vm_enable__ (@var{new_val}, "local") -Query or set whether Octave automatically compiles functions to bytecode -and executes them in a virtual machine (VM). +Query or set the internal variable that determines whether Octave automatically +compiles functions to bytecode and executes them in a virtual machine (VM). -Note that the virtual machine feature is experimental. +@strong{Warning:} The virtual machine feature is experimental. -The default value is currently false, while the VM is still experimental. -Users need to explicitly call @code{__vm_enable__ (1)} to enable it. +The default value is false while the VM is still experimental. +Users must explicitly call @code{__vm_enable__ (1)} to use it. -When false, Octave uses a traditional tree walker -to evaluate statements parsed from m-code. When true, Octave translates parsed -statements to an intermediate representation that is then evaluated by a -virtual machine. +When false, Octave uses a traditional tree walker to evaluate statements parsed +from m-code. When true, Octave translates parsed statements to an intermediate +representation that is then evaluated by a virtual machine. When called from inside a function with the @qcode{"local"} option, the setting is changed locally for the function and any subroutines it calls. The original setting is restored when exiting the function. -Once compiled to bytecode, the function will always be evaluated by the -VM no matter the state of @qcode{"__vm_enable__"}, until the bytecode is -cleared, by e.g. @qcode{"clear all"} or an modification to the -function's m-file. +Once compiled to bytecode, the function will always be evaluated by the VM +regardless of the state of @code{__vm_enable__}, until the bytecode is cleared +by, e.g., @qcode{"clear all"}, or a modification to the function's m-file. @seealso{__vm_compile__} diff --git a/libinterp/corefcn/graphics.cc b/libinterp/corefcn/graphics.cc index 92793b2ca8..0f9e1f9603 100644 --- a/libinterp/corefcn/graphics.cc +++ b/libinterp/corefcn/graphics.cc @@ -12134,6 +12134,7 @@ props.color = 'green'; set (h, props); @end group @end example + @end itemize The three syntaxes for setting properties may appear in any combination. diff --git a/libinterp/corefcn/input.cc b/libinterp/corefcn/input.cc index 77f5cf3c93..45abd1a084 100644 --- a/libinterp/corefcn/input.cc +++ b/libinterp/corefcn/input.cc @@ -1577,7 +1577,7 @@ DEFMETHOD (mfile_encoding, interp, args, nargout, @deftypefnx {} {@var{old_encoding} =} mfile_encoding (@var{new_encoding}) Query or set the encoding that is used for reading m-files. -The input and output are strings naming an encoding, e.g., "utf-8". +The input and output are strings naming an encoding, e.g., @qcode{"utf-8"}. This encoding is used by Octave's parser when reading m-files unless a different encoding was set for a specific directory containing m-files using diff --git a/libinterp/corefcn/pr-output.cc b/libinterp/corefcn/pr-output.cc index fa82f2f5c7..3e8483a0ee 100644 --- a/libinterp/corefcn/pr-output.cc +++ b/libinterp/corefcn/pr-output.cc @@ -3936,6 +3936,7 @@ most significant bit first. For example, @code{pi} is printed like this: @end group @end example +@noindent where spaces have been added for clarity to show the sign bit, the 11-bit exponent, and the 52-bit mantissa, in that order. Together they represent @code{pi} as an IEEE 754 double precision floating point number in the normal @@ -3956,6 +3957,7 @@ For example, the value of @code{pi} in this format on x86-64 is: @end group @end example +@noindent shown here with spaces added for clarity. Compare with the previous bit string from @code{format bit} to see the grouping into bytes and their ordering. diff --git a/libinterp/corefcn/qz.cc b/libinterp/corefcn/qz.cc index 5933a61575..05fa06cbc9 100644 --- a/libinterp/corefcn/qz.cc +++ b/libinterp/corefcn/qz.cc @@ -61,7 +61,7 @@ OCTAVE_BEGIN_NAMESPACE(octave) DEFUN (qz, args, nargout, doc: /* -*- texinfo -*- -@deftypefn {} {[@var{AA}, @var{BB}, @var{Q}, @var{Z}, @var{V}, @var{W}] =} qz (@var{A}, @var{B}) +@deftypefn {} {[@var{AA}, @var{BB}, @var{Q}, @var{Z}, @var{V}, @var{W}] =} qz (@var{A}, @var{B}) @deftypefnx {} {[@var{AA}, @var{BB}, @var{Q}, @var{Z}, @var{V}, @var{W}] =} qz (@var{A}, @var{B}, @var{opt}) Compute the QZ@tie{}decomposition of a generalized eigenvalue problem. @@ -81,8 +81,8 @@ There are two calling forms of the function: @enumerate @item @code{[@var{AA}, @var{BB}, @var{Q}, @var{Z}, @var{V}, @var{W}, @var{lambda}] = qz (@var{A}, @var{B})} -Compute the complex QZ@tie{}decomposition, generalized eigenvectors, and generalized -eigenvalues. +Compute the complex QZ@tie{}decomposition, generalized eigenvectors, and +generalized eigenvalues. @tex $$ AA = Q^T AZ, BB = Q^T BZ $$ $$ { \rm diag }(BB)AV = BV{ \rm diag }(AA) $$ @@ -102,20 +102,20 @@ diag (diag (@var{BB})) * @var{W}' * @var{A} = diag (diag (@var{AA})) * @var{W}' @end ifnottex with @var{AA} and @var{BB} upper triangular, and @var{Q} and @var{Z} -unitary. The matrices @var{V} and @var{W} respectively contain the right +unitary. The matrices @var{V} and @var{W} respectively contain the right and left generalized eigenvectors. @item @code{[@var{AA}, @var{BB}, @var{Z} @{, @var{lambda}@}] = qz (@var{A}, @var{B}, @var{opt})} The @var{opt} argument must be equal to either @qcode{"real"} or -@qcode{"complex"}. If it is equal to @qcode{"complex"}, then this +@qcode{"complex"}. If it is equal to @qcode{"complex"}, then this calling form is equivalent to the first one with only two input arguments. If @var{opt} is equal to @qcode{"real"}, then the real QZ decomposition -is computed. In particular, @var{AA} is only guaranteed to be +is computed. In particular, @var{AA} is only guaranteed to be quasi-upper triangular with 1-by-1 and 2-by-2 blocks on the diagonal, -and @var{Q} and @var{Z} are orthogonal. The identities mentioned above +and @var{Q} and @var{Z} are orthogonal. The identities mentioned above for right and left generalized eigenvectors are only verified if @var{AA} is upper triangular (i.e., when all the generalized eigenvalues are real, in which case the real and complex QZ coincide). diff --git a/libinterp/corefcn/sysdep.cc b/libinterp/corefcn/sysdep.cc index 3a824faaef..5e22fb0a16 100644 --- a/libinterp/corefcn/sysdep.cc +++ b/libinterp/corefcn/sysdep.cc @@ -772,11 +772,9 @@ returns a string containing the value of your path. DEFUN (isenv, args, , doc: /* -*- texinfo -*- -@deftypefn {} {@var{val} =} isenv (@var{var}) -Check if the environment variable @var{var} exists. - -This function returns true if an environment variable with the name @var{var} -exists. Otherwise, it returns false. +@deftypefn {} {@var{tf} =} isenv (@var{var}) +Return true if the variable @var{var} is an environment variable, and false +otherwise. For example, @@ -785,7 +783,8 @@ tf = isenv ("PATH") @end example @noindent -returns true if an environment variable with the name @qcode{"PATH"} exists. +will typically return true on UNIX systems because @qcode{"PATH"} is an +environment variable for UNIX. @seealso{getenv, setenv, unsetenv} @end deftypefn */) { @@ -850,7 +849,8 @@ DEFALIAS (putenv, setenv); DEFUN (unsetenv, args, , doc: /* -*- texinfo -*- -@deftypefn {} {@var{status} =} unsetenv (@var{var}) +@deftypefn {} {} unsetenv ("@var{var}") +@deftypefnx {} {@var{status} =} unsetenv ("@var{var}") Delete the environment variable @var{var}. Return 0 if the variable was deleted, or did not exist, and -1 if an error From 5aadaf17a851f6a24f131071ea4b1e0a93fc52e9 Mon Sep 17 00:00:00 2001 From: Rik Date: Thu, 23 Nov 2023 20:30:44 -0800 Subject: [PATCH 3/3] doc: grammarcheck Octave manual before 9.1 release. * doc/interpreter/func.txi, doc/interpreter/numbers.txi, doc/interpreter/octave.texi, doc/interpreter/plot.txi, doc/interpreter/sparse.txi, doc/interpreter/vectorize.txi, scripts/miscellaneous/jupyter_notebook.m, scripts/plot/draw/stemleaf.m: grammarcheck Octave manual before 9.1 release. --- doc/interpreter/container.txi | 20 +++++++++----------- doc/interpreter/expr.txi | 13 +++++++------ doc/interpreter/func.txi | 17 ++++++++++++++--- doc/interpreter/numbers.txi | 16 ++++++++++++++-- doc/interpreter/octave.texi | 2 +- doc/interpreter/plot.txi | 10 +++++----- doc/interpreter/sparse.txi | 6 +++--- doc/interpreter/vectorize.txi | 4 ++-- scripts/miscellaneous/jupyter_notebook.m | 16 ++++++++-------- scripts/plot/draw/stemleaf.m | 2 +- 10 files changed, 64 insertions(+), 42 deletions(-) diff --git a/doc/interpreter/container.txi b/doc/interpreter/container.txi index 86227c60af..03c9b0d955 100644 --- a/doc/interpreter/container.txi +++ b/doc/interpreter/container.txi @@ -949,9 +949,8 @@ using the @code{cell2mat} and @code{cell2struct} functions. @cindex cs-lists Comma-separated lists @footnote{Comma-separated lists are also sometimes -informally referred to as @dfn{cs-lists}.} are the basic argument type -to all Octave functions - both for input and return arguments. In the -example +referred to as @dfn{cs-lists}.} are the basic argument type to all Octave +functions---both for input and return arguments. In the example @example max (@var{a}, @var{b}) @@ -971,14 +970,13 @@ x = [1 0 1 0 0 1 1; 0 0 0 0 0 0 7]; @noindent Here, @samp{@var{x}, 2, "last"} is a comma-separated list constituting -the input arguments of @code{find}. @code{find} returns a comma -separated list of output arguments which is assigned element by -element to the comma-separated list @samp{@var{i}, @var{j}}. - -Another example of where comma-separated lists are used is in the -creation of a new array with @code{[]} (@pxref{Matrices}) or the -creation of a cell array with @code{@{@}} (@pxref{Basic Usage of Cell -Arrays}). In the expressions +the input arguments of @code{find}. @code{find} returns a comma-separated list +of output arguments which is assigned element by element to the comma-separated +list @samp{@var{i}, @var{j}}. + +Another example of where comma-separated lists are used is in the creation of a +new array with @code{[]} (@pxref{Matrices}) or the creation of a cell array +with @code{@{@}} (@pxref{Basic Usage of Cell Arrays}). In the expressions @example @group diff --git a/doc/interpreter/expr.txi b/doc/interpreter/expr.txi index 85bdac983e..b1cdf28ee3 100644 --- a/doc/interpreter/expr.txi +++ b/doc/interpreter/expr.txi @@ -145,6 +145,7 @@ A([1; 2]) # result is a column vector: ans = [1; 2] @end example The shape rules for @var{A}(@var{P}) are: + @itemize @bullet @item When at least one of @var{A} or @var{P} has two or more dimensions, then @var{A}(@var{P}) takes the shape of @var{P}. This happens when at least one @@ -1103,28 +1104,28 @@ the equivalent of the operation @code{all (@var{boolean1}(:))}. If @var{boolean1} is not a logical value, it is considered true if its value is nonzero, and false if its value is zero. If @var{boolean1} is an array, it is considered true only if it is non-empty and all elements are -non-zero. If @var{boolean1} evaluates to false, the result of the overall +nonzero. If @var{boolean1} evaluates to false, the result of the overall expression is false. If it is true, the expression @var{boolean2} is -evaluated in the same way as @var{boolean1}. If it is true, the result of +evaluated in the same way as @var{boolean1}. If it is true, the result of the overall expression is true. Otherwise the result of the overall expression is false. @strong{Warning:} the one exception to the equivalence with evaluating @code{all (@var{boolean1}(:))} is when @code{boolean1} an the empty array. -For @sc{MATLAB} compatibility, the truth value of an empty array is always +For @sc{matlab} compatibility, the truth value of an empty array is always @code{false} so @code{[] && true} evaluates to @code{false} even though @code{all ([])} is @code{true}. @item @var{boolean1} || @var{boolean2} @opindex || The expression @var{boolean1} is evaluated and converted to a scalar using -the equivalent of the operation @code{all (@var{boolean1}(:))}. If +the equivalent of the operation @code{all (@var{boolean1}(:))}. If @var{boolean1} is not a logical value, it is considered true if its value is nonzero, and false if its value is zero. If @var{boolean1} is an array, it is considered true only if it is non-empty and all elements are -non-zero. If @var{boolean1} evaluates to true, the result of the overall +nonzero. If @var{boolean1} evaluates to true, the result of the overall expression is true. If it is false, the expression @var{boolean2} is -evaluated in the same way as @var{boolean1}. If it is true, the result of +evaluated in the same way as @var{boolean1}. If it is true, the result of the overall expression is true. Otherwise the result of the overall expression is false. diff --git a/doc/interpreter/func.txi b/doc/interpreter/func.txi index c13e8c19ea..8d42a64c4a 100644 --- a/doc/interpreter/func.txi +++ b/doc/interpreter/func.txi @@ -1987,9 +1987,11 @@ create apparent ambiguities with mathematical and logical expressions that use function syntax. For example, all three of the statements @example +@group arg1 - arg2 arg1 -arg2 arg1-arg2 +@end group @end example @noindent @@ -1997,7 +1999,7 @@ could be intended by a user to be subtraction operations between @code{arg1} and @code{arg2}. The first two, however, could also have been meant as a command syntax call to function @code{arg1}, in the first case with options @code{-} and @code{arg2}, and in the second case with option -@code{-arg2}. +@option{-arg2}. Octave uses whitespace to interpret such expressions according to the following rules: @@ -2013,10 +2015,13 @@ arg1 arg2 arg3 ... argn @item Statements without any whitespace are always treated as function syntax: + @example +@group arg1+arg2 arg1&&arg2||arg3 arg1+=arg2*arg3 +@end group @end example @item @@ -2024,20 +2029,26 @@ If the first symbol is a constant (or special-valued named constant pi, i, I, j, J, e, NaN, or Inf) followed by a binary operator, the statement is treated as function syntax regardless of any whitespace or what follows the second symbol: + @example +@group 7 -arg2 pi+ arg2 j * arg2 -arg3 +@end group @end example @item If the first symbol is a function or variable and there is no whitespace separating the operator and the second symbol, the statement is treated as command syntax: + @example +@group arg1 -arg2 arg1 &&arg2 ||arg3 arg1 +=arg2*arg3 +@end group @end example @item @@ -2045,11 +2056,11 @@ Any other whitespace combination will result in the statement being treated as function syntax. @end itemize -Note 1: If a special-valued named constant has been redefined as a +Note 1: If a special-valued named constant has been redefined as a variable, the interpreter will still process the statement with function syntax. -Note 2: Attempting to use a variable as @code{arg1} in a command being +Note 2: Attempting to use a variable as @code{arg1} in a command being processed as command syntax will result in an error. diff --git a/doc/interpreter/numbers.txi b/doc/interpreter/numbers.txi index 8f666a38f0..a596ceaf98 100644 --- a/doc/interpreter/numbers.txi +++ b/doc/interpreter/numbers.txi @@ -435,9 +435,11 @@ the range is not always included in the set of values. This can be useful in some contexts. For example: @example +@group ## x is some predefined range or vector or matrix or array x(1:2:end) += 1; # increment all odd-numbered elements x(2:2:end) -= 1; # decrement all even-numbered elements +@end group @end example The above code works correctly whether @var{x} has an odd number of elements @@ -448,9 +450,11 @@ range. As a result, defining ranges with floating-point values can result in pitfalls like these: @example +@group a = -2 b = (0.3 - 0.2 - 0.1) x = a : b +@end group @end example Due to floating point rounding, @var{b} may or may not equal zero exactly, @@ -458,10 +462,13 @@ and if it does not, it may be above zero or below zero, hence the final range @var{x} may or may not include zero as its final value. Similarly: @example +@group x = 1.80 : 0.05 : 1.90 y = 1.85 : 0.05 : 1.90 +@end group @end example +@noindent is not as predictable as it looks. As of Octave 8.3, the results obtained are that @var{x} has three elements (1.80, 1.85, and 1.90), and @var{y} has only one element (1.85 but not 1.90). Thus, when using floating points in ranges, @@ -469,23 +476,27 @@ changing the start of the range can easily affect the end of the range even though the ending value was not touched in the above example. To avoid such pitfalls with floating-points in ranges, you should use one of -the following patterns. This change to the previous code: +the following patterns. This change to the previous code: @example +@group x = (0:2) * 0.05 + 1.80 y = (0:1) * 0.05 + 1.85 +@end group @end example +@noindent makes it much safer and much more repeatable across platforms, compilers, and compiler settings. If you know the number of elements, you can also use the @code{linspace} function (@pxref{Special Utility Matrices}), which will include the endpoints of a range. You can also make judicious use of -@code{round}, @code{floor}, @code{ceil}, @code{fix}, etc to set the +@code{round}, @code{floor}, @code{ceil}, @code{fix}, etc.@: to set the limits and the increment without getting interference from floating-point rounding. For example, the earlier example can be made safer and much more repeatable with one of the following: @example +@group a = -2 b = round ((0.3 - 0.2 - 0.1) * 1e12) / 1e12 # rounds to 12 digits c = floor (0.3 - 0.2 - 0.1) # floors as integer @@ -493,6 +504,7 @@ d = floor ((0.3 - 0.2 - 0.1) * 1e12) / 1e12 # floors at 12 digits x = a : b y = a : c z = a : d +@end group @end example When adding a scalar to a range, subtracting a scalar from it (or subtracting a diff --git a/doc/interpreter/octave.texi b/doc/interpreter/octave.texi index fac375403a..f4b3af081d 100644 --- a/doc/interpreter/octave.texi +++ b/doc/interpreter/octave.texi @@ -625,7 +625,7 @@ Object Groups Graphics Toolkits * Customizing Toolkit Behavior:: -* Hardware vs Software Rendering:: +* Hardware vs. Software Rendering:: * Precision issues:: Matrix Manipulation diff --git a/doc/interpreter/plot.txi b/doc/interpreter/plot.txi index 78ee5d10fe..4c29ae773a 100644 --- a/doc/interpreter/plot.txi +++ b/doc/interpreter/plot.txi @@ -2764,7 +2764,7 @@ Data source variables. @menu * Customizing Toolkit Behavior:: -* Hardware vs Software Rendering:: +* Hardware vs. Software Rendering:: * Precision issues:: @end menu @@ -2794,8 +2794,8 @@ plot (1:10) @end group @end example -@node Hardware vs Software Rendering -@subsubsection Hardware vs Software Rendering +@node Hardware vs. Software Rendering +@subsubsection Hardware vs. Software Rendering @cindex opengl rendering slow windows When using the Octave for Windows installer, the user has the option to select @@ -2804,7 +2804,7 @@ whether software rendering is used for the OpenGL graphics toolkits (@qcode{"qt"} and @qcode{"fltk"}). Software rendering can be used to avoid rendering and printing issues due to imperfect OpenGL driver implementations for diverse graphic cards from different vendors (notably integrated Intel -graphics). As a down-side, software rendering might be considerably slower +graphics). As a downside, software rendering might be considerably slower than hardware accelerated rendering (and it might not work correctly on 32-bit platforms or WoW64). To permanently switch between hardware accelerated rendering with your graphics card drivers and software rendering, use the @@ -2813,7 +2813,7 @@ Alternatively, rename the following file while Octave is closed: @file{@var{octave-home}\bin\opengl32.dll} @*where @var{octave-home} is the directory returned by -@ref{XREFOCTAVE_HOME, , @w{@qcode{OCTAVE_HOME}}}, i.e., the directory in which +@ref{XREFOCTAVE_HOME, , @w{@code{OCTAVE_HOME}}}, i.e., the directory in which Octave is installed (the default is @file{C:\Program Files\GNU Octave\Octave\Octave-@var{version}\mingw64}). Change the file extension to @file{.bak} for hardware rendering or to diff --git a/doc/interpreter/sparse.txi b/doc/interpreter/sparse.txi index fbca82b613..9a7a91ac20 100644 --- a/doc/interpreter/sparse.txi +++ b/doc/interpreter/sparse.txi @@ -150,9 +150,9 @@ contents of these three vectors for the above matrix will be Note that this is the representation of these elements with the first row and column assumed to start at zero, while in Octave itself the row and -column indexing starts at one. Thus the number of elements in the -@var{i}-th column is given by @code{@var{cidx} (@var{i} + 1) - -@var{cidx} (@var{i})}. +column indexing starts at one. Thus, the number of elements in the +@var{i}-th column is given by +@code{@var{cidx} (@var{i} + 1) - @var{cidx} (@var{i})}. Although Octave uses a compressed column format, it should be noted that compressed row formats are equally possible. However, in the diff --git a/doc/interpreter/vectorize.txi b/doc/interpreter/vectorize.txi index 627f681bf4..69237c6195 100644 --- a/doc/interpreter/vectorize.txi +++ b/doc/interpreter/vectorize.txi @@ -344,8 +344,8 @@ subtraction takes place. A special case of broadcasting that may be familiar is when all dimensions of the array being broadcast are 1, i.e., the array is a -scalar. Thus for example, operations like @code{x - 42} and @code{max -(x, 2)} are basic examples of broadcasting. +scalar. Thus, for example, operations like @code{x - 42} and +@code{max (x, 2)} are basic examples of broadcasting. For a higher-dimensional example, suppose @code{img} is an RGB image of size @code{[m n 3]} and we wish to multiply each color by a different diff --git a/scripts/miscellaneous/jupyter_notebook.m b/scripts/miscellaneous/jupyter_notebook.m index ce663ae963..2488ffa490 100644 --- a/scripts/miscellaneous/jupyter_notebook.m +++ b/scripts/miscellaneous/jupyter_notebook.m @@ -50,8 +50,8 @@ ## ## @itemize @bullet ## @item - ## "%plot -f " or "%plot --format ": specifies the - ## image storage format. Supported formats are: + ## "@code{%plot -f }" or "@code{%plot --format }": specifies + ## the image storage format. Supported formats are: ## ## @itemize @minus ## @item @@ -67,16 +67,16 @@ ## @end itemize ## ## @item - ## "%plot -r " or "%plot --resolution ": specifies the - ## image resolution. + ## "@code{%plot -r }" or "@code{%plot --resolution }": + ## specifies the image resolution. ## ## @item - ## "%plot -w " or "%plot --width ": specifies the - ## image width. + ## "@code{%plot -w }" or "@code{%plot --width }": specifies + ## the image width. ## ## @item - ## "%plot -h " or "%plot --height ": specifies the - ## image height. + ## "@code{%plot -h }" or "@code{%plot --height }": specifies + ## the image height. ## @end itemize ## ## Examples: diff --git a/scripts/plot/draw/stemleaf.m b/scripts/plot/draw/stemleaf.m index b624b82a44..165a0eb713 100644 --- a/scripts/plot/draw/stemleaf.m +++ b/scripts/plot/draw/stemleaf.m @@ -42,7 +42,7 @@ ## The default stem width is 10. ## ## The output of @code{stemleaf} is composed of two parts: a -## "Fenced Letter Display," followed by the stem-and-leaf plot itself. +## "Fenced Letter Display", followed by the stem-and-leaf plot itself. ## The Fenced Letter Display is described in @cite{Exploratory Data Analysis}. ## Briefly, the entries are as shown: ##