changeset 28652:bb0ca2753bc2 stable

update docs for built-in variables (bug #58988) * basics.txi, expr.txi, io.txi, numbers.txi, oop.txi, var.txi: Refer to functions, not built-in variables. Update docs for ans. Correct output of simple expression like "pi" to display "ans =" rather than "pi =".
author John W. Eaton <jwe@octave.org>
date Wed, 26 Aug 2020 13:27:48 -0400
parents 410f162af184
children ddcc33be4fd9 844b3b9bab7a
files doc/interpreter/basics.txi doc/interpreter/expr.txi doc/interpreter/io.txi doc/interpreter/numbers.txi doc/interpreter/oop.txi doc/interpreter/var.txi
diffstat 6 files changed, 26 insertions(+), 24 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/basics.txi	Wed Aug 26 13:26:26 2020 -0400
+++ b/doc/interpreter/basics.txi	Wed Aug 26 13:27:48 2020 -0400
@@ -110,8 +110,8 @@
 Specify the path to search for programs to run.  The value of @var{path}
 specified on the command line will override any value of
 @w{@env{OCTAVE_EXEC_PATH}} found in the environment, but not any commands
-in the system or user startup files that set the built-in variable
-@w{@env{EXEC_PATH}}.
+in the system or user startup files that call the
+@w{@env{EXEC_PATH}} function.
 
 @item --gui
 @cindex @sortas{options, Octave command --gui} @ @ @code{--gui}
@@ -128,8 +128,8 @@
 Add path to the head of the search path for images.  The value of
 @var{path} specified on the command line will override any value of
 @w{@env{OCTAVE_IMAGE_PATH}} found in the environment, but not any commands
-in the system or user startup files that set the built-in variable
-@w{@env{IMAGE_PATH}}.
+in the system or user startup files that call the @w{@env{IMAGE_PATH}}
+function.
 
 @item --info-file @var{filename}
 @cindex @sortas{options, Octave command --info-file} @ @ @code{--info-file @var{filename}}
--- a/doc/interpreter/expr.txi	Wed Aug 26 13:26:26 2020 -0400
+++ b/doc/interpreter/expr.txi	Wed Aug 26 13:27:48 2020 -0400
@@ -597,13 +597,13 @@
 argument is no longer greater than zero, it does not call itself, and
 the recursion ends.
 
-The built-in variable @code{max_recursion_depth} specifies a limit to
-the recursion depth and prevents Octave from recursing infinitely.
-Similarly, the variable @code{max_stack_depth} specifies a limit to the
-depth of function calls, whether recursive or not.  These limits help
-prevent stack overflow on the computer Octave is running on, so that
-instead of exiting with a signal, the interpreter will throw an error
-and return to the command prompt.
+The function @code{max_recursion_depth} may be used to specify a limit
+to the recursion depth and prevents Octave from recursing infinitely.
+Similarly, the function @code{max_stack_depth} may be used to specify
+limit to the depth of function calls, whether recursive or not.  These
+limits help prevent stack overflow on the computer Octave is running on,
+so that instead of exiting with a signal, the interpreter will throw an
+error and return to the command prompt.
 
 @DOCSTRING(max_recursion_depth)
 
--- a/doc/interpreter/io.txi	Wed Aug 26 13:26:26 2020 -0400
+++ b/doc/interpreter/io.txi	Wed Aug 26 13:27:48 2020 -0400
@@ -52,7 +52,7 @@
 @example
 @group
 pi
-     @print{} pi = 3.1416
+     @print{} ans =  3.1416
 @end group
 @end example
 
--- a/doc/interpreter/numbers.txi	Wed Aug 26 13:26:26 2020 -0400
+++ b/doc/interpreter/numbers.txi	Wed Aug 26 13:27:48 2020 -0400
@@ -301,10 +301,10 @@
 Octave automatically switches to scientific notation when values become
 very large or very small.  This guarantees that you will see several
 significant figures for every value in a matrix.  If you would prefer to
-see all values in a matrix printed in a fixed point format, you can set
-the built-in variable @code{fixed_point_format} to a nonzero value.  But
-doing so is not recommended, because it can produce output that can
-easily be misinterpreted.
+see all values in a matrix printed in a fixed point format, you can use
+the function @code{fixed_point_format}.  But doing so is not
+recommended, because it can produce output that can easily be
+misinterpreted.
 
 @DOCSTRING(fixed_point_format)
 
--- a/doc/interpreter/oop.txi	Wed Aug 26 13:26:26 2020 -0400
+++ b/doc/interpreter/oop.txi	Wed Aug 26 13:27:48 2020 -0400
@@ -381,9 +381,10 @@
 subsasgn will not do anything, however, only indexed assignments matter.
 
 Since this optimization may change the way code works (especially if badly
-written), a built-in variable @code{optimize_subsasgn_calls} is provided to
-control it.  It is on by default.  Another way to avoid the optimization is to
-declare subsasgn methods with different output and input arguments like this:
+written), a function @code{optimize_subsasgn_calls} is provided to
+control it.  This feature is enabled by default.  Another way to avoid
+the optimization is to declare subsasgn methods with different output
+and input arguments like this:
 
 @example
 @group
--- a/doc/interpreter/var.txi	Wed Aug 26 13:26:26 2020 -0400
+++ b/doc/interpreter/var.txi	Wed Aug 26 13:27:48 2020 -0400
@@ -51,11 +51,12 @@
 @dfn{assignment operators} and @dfn{increment operators}.
 @xref{Assignment Ops,,Assignment Expressions}.
 
-There is one built-in variable with a special meaning.  The @code{ans} variable
-always contains the result of the last computation, where the output wasn't
-assigned to any variable.  The code @code{a = cos (pi)} will assign the value
--1 to the variable @code{a}, but will not change the value of @code{ans}.
-However, the code @code{cos (pi)} will set the value of @code{ans} to -1.
+There is one automatically created variable with a special meaning.  The
+@code{ans} variable always contains the result of the last computation,
+where the output wasn't assigned to any variable.  The code @code{a =
+cos (pi)} will assign the value -1 to the variable @code{a}, but will
+not change the value of @code{ans}.  However, the code @code{cos (pi)}
+will set the value of @code{ans} to -1.
 
 Variables in Octave do not have fixed types, so it is possible to first
 store a numeric value in a variable and then to later use the same name