changeset 29455:27cb1672b249

maint: merge stable to default.
author Markus Mützel <markus.muetzel@gmx.de>
date Sat, 20 Mar 2021 15:43:04 +0100
parents a0eb1ae33192 (current diff) e4cfe348b212 (diff)
children ebc3f80673f0
files doc/interpreter/func.txi doc/interpreter/octave.texi doc/interpreter/plot.txi
diffstat 3 files changed, 41 insertions(+), 19 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/func.txi	Sat Mar 20 11:40:07 2021 +0100
+++ b/doc/interpreter/func.txi	Sat Mar 20 15:43:04 2021 +0100
@@ -41,7 +41,7 @@
 * Function Files::
 * Script Files::
 * Function Handles and Anonymous Functions::
-* Commands::
+* Command Syntax and Function Syntax::
 * Organization of Functions::
 @end menu
 
@@ -1889,12 +1889,14 @@
 @xref{Operator Overloading}, for a list of operators which also have a
 functional form.
 
-@node Commands
-@section Commands
+@node Command Syntax and Function Syntax
+@section Command Syntax and Function Syntax
+@cindex commands functions
 
-Commands are a special class of functions that only accept string
-input arguments.  A command can be called as an ordinary function, but
-it can also be called without the parentheses.  For example,
+Additionally to the function syntax described above (i.e., calling a function
+like @code{fun (arg1, arg2, @dots{})}), a function can be called using command
+syntax (for example, calling a function like @code{fun arg1 arg2 @dots{}}).  In
+that case, all arguments are passed to the function as strings.  For example,
 
 @example
 my_command hello world
@@ -1911,18 +1913,31 @@
 The general form of a command call is
 
 @example
-@var{cmdname} @var{arg1} @var{arg2} @dots{}
+cmdname arg1 arg2 @dots{}
 @end example
 
 @noindent
 which translates directly to
 
 @example
-@var{cmdname} ("@var{arg1}", "@var{arg2}", @dots{})
+cmdname ("arg1", "arg2", @dots{})
+@end example
+
+If an argument including spaces should be passed to a function in command
+syntax, (double-)quotes can be used.  For example,
+@example
+my_command "first argument" "second argument"
 @end example
 
-Any regular function can be used as a command if it accepts string input
-arguments.  For example:
+@noindent
+is equivalent to
+
+@example
+my_command ("first argument", "second argument")
+@end example
+
+Any function can be used as a command if it accepts string input arguments.
+For example:
 
 @example
 @group
@@ -1931,11 +1946,9 @@
 @end group
 @end example
 
-One difficulty of commands occurs when one of the string input arguments
-is stored in a variable.  Because Octave can't tell the difference between
-a variable name and an ordinary string, it is not possible to pass a
-variable as input to a command.  In such a situation a command must be
-called as a function.  For example:
+Since the arguments are passed as strings to the corresponding function, it is
+not possible to pass input arguments that are stored in variables.  In that
+case, a command must be called using the function syntax.  For example:
 
 @example
 @group
@@ -1947,6 +1960,12 @@
 @end group
 @end example
 
+Additionally, the return values of functions cannot be assigned to variables
+using the command syntax.  Only the first return argument is assigned to the
+built-in variable @code{ans}.  If the output argument of a command should be
+assigned to a variable, or multiple output arguments of a function should be
+returned, the function syntax must be used.
+
 
 @node Organization of Functions
 @section Organization of Functions Distributed with Octave
--- a/doc/interpreter/octave.texi	Sat Mar 20 11:40:07 2021 +0100
+++ b/doc/interpreter/octave.texi	Sat Mar 20 15:43:04 2021 +0100
@@ -420,7 +420,7 @@
 * Function Files::
 * Script Files::
 * Function Handles and Anonymous Functions::
-* Commands::
+* Command Syntax and Function Syntax::
 * Organization of Functions::
 
 Validating Arguments
@@ -624,6 +624,7 @@
 
 * Customizing Toolkit Behavior::
 * Hardware vs. Software Rendering::
+* Precision issues::
 
 Matrix Manipulation
 
--- a/doc/interpreter/plot.txi	Sat Mar 20 11:40:07 2021 +0100
+++ b/doc/interpreter/plot.txi	Sat Mar 20 15:43:04 2021 +0100
@@ -2753,9 +2753,9 @@
 granularity will result in a distorted graph.
 
 As a workaround, it is possible to use the @qcode{"gnuplot"} graphics toolkit
-or subtract 2000 years---i.e. datenum(2000,0,0) or 730485---from the time
-values.  Due to the fact that the calendar structure repeats every 2000 years,
-the relation between year, month, day of month and day of week will stay
+or subtract 2000 years---i.e. @code{datenum (2000, 0, 0)} or 730485---from the
+time values.  Due to the fact that the calendar structure repeats every 2000
+years, the relation between year, month, day of month and day of week will stay
 unchanged and the ticks and ticklabels produced by the @code{datetick} function
 will still be correct.  Only years will lack the millennium digit.  Thus,
 "2020" will be printed as "20".  For example:
@@ -2791,3 +2791,5 @@
 @caption{Single precision issues with OpenGL graphics toolkits}
 @end float
 @end ifnotinfo
+
+Similarly, other data can be translated or re-scaled to work around this issue.