# HG changeset patch
# User Rik <rik@octave.org>
# Date 1487724925 28800
# Node ID 893d99338cc8136a520f16e5cf59f5e17868b1ed
# Parent  54404cc329034b8390dd7918f2e0e8d03dc170fe
doc: Reword manual section on numeric constants for clarity.

* numbers.txi: Reword section on numeric constants for clarity.

* plot.txi: Add more explanation for why random number generators
are initialized before producing plots for the manual.

diff -r 54404cc32903 -r 893d99338cc8 doc/interpreter/numbers.txi
--- a/doc/interpreter/numbers.txi	Tue Feb 21 16:24:19 2017 -0800
+++ b/doc/interpreter/numbers.txi	Tue Feb 21 16:55:25 2017 -0800
@@ -25,18 +25,21 @@
 contain complex values.
 
 The simplest form of a numeric constant, a scalar, is a single number.  Note
-that by default numeric constants are represented within Octave in IEEE 754
+that by default numeric constants are represented within Octave by IEEE 754
 double precision (binary64) floating-point format (complex constants are
 stored as pairs of binary64 values).  It is, however, possible to represent
-real integers as described in @ref{Integer Data Types}.  If the numeric
-constant is a real integer, it can be defined in decimal, hexadecimal, or
-binary notation.  Hexadecimal notations start with @code{0x} or @code{0X},
-binary notations start with @code{0b} or @code{0B}, otherwise decimal notation
-is assumed.  Therefore, @code{0b} is not a hexadecimal number, it is not a
-valid number at all.  For better readability, digits may be partitioned by the
-underscore separator @code{_}, which is ignored by the Octave interpreter.
-Here are some examples of real-valued integer constants, which all represent
-the same value and are internally stored as binary64:
+real integers as described in @ref{Integer Data Types}.
+
+If the numeric constant is a real integer, it can be defined in decimal,
+hexadecimal, or binary notation.  Hexadecimal notation starts with @samp{0x} or
+@samp{0X}, binary notation starts with @samp{0b} or @samp{0B}, otherwise
+decimal notation is assumed.  As a consequence, @samp{0b} is not a hexadecimal
+number, in fact, it is not a valid number at all.
+
+For better readability, digits may be partitioned by the underscore separator
+@samp{_}, which is ignored by the Octave interpreter.  Here are some examples
+of real-valued integer constants, which all represent the same value and are
+internally stored as binary64:
 
 @example
 @group
@@ -50,7 +53,7 @@
 
 In decimal notation, the numeric constant may be denoted as decimal fraction
 or even in scientific (exponential) notation.  Note that this is not possible
-for the hexadecimal or binary notation.  Again, in the following example all
+for hexadecimal or binary notation.  Again, in the following example all
 numeric constants represent the same value:
 
 @example
@@ -61,18 +64,19 @@
 @end group
 @end example
 
-Unlike in most programming languages, complex numeric constants are denoted as
-sum of real and imaginary part.  The imaginary part is denoted by a
-real-valued numeric constant immediately followed by @samp{i}, @samp{j},
-@samp{I}, or @samp{J}, which is defined by
+Unlike most programming languages, complex numeric constants are denoted as
+the sum of real and imaginary parts.  The imaginary part is denoted by a
+real-valued numeric constant followed immediately by a complex value indicator
+(@samp{i}, @samp{j}, @samp{I}, or @samp{J} which represents
 @tex
-  $\sqrt{-1}$.
+  $\sqrt{-1}$).
 @end tex
 @ifnottex
-  @code{sqrt (-1)}.
+  @code{sqrt (-1)}).
 @end ifnottex
-Intermediate blanks are not allowed.  Some examples where all complex numeric
-constants represent the same value:
+No spaces are allowed between the numeric constant and the complex value
+indicator.  Some examples of complex numeric constants that all represent the
+same value:
 
 @example
 @group
diff -r 54404cc32903 -r 893d99338cc8 doc/interpreter/plot.txi
--- a/doc/interpreter/plot.txi	Tue Feb 21 16:24:19 2017 -0800
+++ b/doc/interpreter/plot.txi	Tue Feb 21 16:55:25 2017 -0800
@@ -136,9 +136,10 @@
 
 @noindent
 produces the histogram of 10,000 normally distributed random numbers
-shown in @ref{fig:hist}.  Note that, @code{randn ("state", 1);} sets
-the start value for @code{randn} so that the returned values are
-always the same as shown.
+shown in @ref{fig:hist}.  Note that, @code{randn ("state", 1);}, initializes
+the random number generator for @code{randn} to a known value so that the
+returned values are reproducible; This guarantees that the figure produced
+is identical to the one in this manual.
 
 @float Figure,fig:hist
 @center @image{hist,4in}