# HG changeset patch
# User Nicholas R. Jankowski <jankowski.nicholas@gmail.com>
# Date 1670274915 18000
#      Mon Dec 05 16:15:15 2022 -0500
# Node ID 766cb4952ff1615a095a7c6fac0e913675815539
# Parent  e518e1f7e944da41501ab2c341a55a13ed517b77
doc: Clarify command and function syntax binary operator handling (bug #62552)

* doc/interpreter/func.txi: Append explanation to "Command Syntax and Function
Syntax" section describing handling of ambiguous statements with binary
operators.
* doc/interpreter/expr.txi: Append note to "Arithmetic Operators" section
indicating potential ambiguity and linking to "Command Syntax and Function
Syntax" section.

diff -r e518e1f7e944 -r 766cb4952ff1 doc/interpreter/expr.txi
--- a/doc/interpreter/expr.txi	Mon Dec 05 10:17:17 2022 -0500
+++ b/doc/interpreter/expr.txi	Mon Dec 05 16:15:15 2022 -0500
@@ -814,6 +814,11 @@
 preferring the longest possible match at any given point, it is more
 useful in this case.
 
+Note also that some combinations of binary operators and whitespace can
+create ambiguities with Octave's Command Syntax form of calling functions. See
+@ref{Command Syntax and Function Syntax} for more detail on avoiding such
+issues.
+
 @opindex @code{'}
 @DOCSTRING(ctranspose)
 
diff -r e518e1f7e944 -r 766cb4952ff1 doc/interpreter/func.txi
--- a/doc/interpreter/func.txi	Mon Dec 05 10:17:17 2022 -0500
+++ b/doc/interpreter/func.txi	Mon Dec 05 16:15:15 2022 -0500
@@ -1906,7 +1906,7 @@
 @section Command Syntax and Function Syntax
 @cindex commands functions
 
-Additionally to the function syntax described above (i.e., calling a function
+In addition 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,
@@ -1980,6 +1980,75 @@
 assigned to a variable, or multiple output arguments of a function should be
 returned, the function syntax must be used.
 
+It should be noted that mixing command syntax and binary operators can
+create ambiguities with mathematical and logical expressions that would use
+function syntax. For example, all three of the statements
+
+@example
+arg1 - arg2
+arg1 -arg2
+arg1-arg2
+@end example
+
+@noindent
+could be interpreted as a subtraction operation between
+@code{arg1} and @code{arg2}. The first two, however, could also be taken 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}.
+
+Octave uses whitespace to interpret such expressions according to the
+following rules:
+
+@itemize @bullet
+@item
+Statements consisting of plain symbols without any operators that are
+separated only by whitespace are always treated as command syntax:
+
+@example
+arg1 arg2 arg3 ... argn
+@end example
+
+@item
+Statements without any whitespace are always treated as function syntax:
+@example
+arg1+arg2
+arg1&&arg2||arg3
+arg1+=arg2*arg3
+@end example
+
+@item
+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
+7 -arg2
+pi+ arg2
+j * arg2 -arg3
+@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
+arg1 -arg2
+arg1 &&arg2 ||arg3
+arg1 +=arg2*arg3
+@end example
+
+@item
+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
+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
+processed as command syntax will result in an error.
+
 
 @node Organization of Functions
 @section Organization of Functions Distributed with Octave
