Merge 21071 and 22360/22365: support version 2 of Yodl.

1 files changed, 38 insertions, 3 deletions

diff --git a/Doc/Zsh/mod_mathfunc.yo b/Doc/Zsh/mod_mathfunc.yo
index 91de7fe71..dda4f36fd 100644
--- a/Doc/Zsh/mod_mathfunc.yo
+++ b/Doc/Zsh/mod_mathfunc.yo
@@ -8,7 +8,7 @@ mathematical functions for use when
 evaluating mathematical formulae.  The syntax agrees with normal C and
 FORTRAN conventions, for example,
 
-example((( f = sin(0.3) )))
+example((( f = sin+LPAR()0.3+RPAR() )))
 
 assigns the sine of 0.3 to the parameter f.
 
@@ -33,8 +33,8 @@ returns an integer.
 The function tt(signgam) takes no arguments, and returns an integer, which
 is the C variable of the same name, as described in manref(gamma)(3).  Note
 that it is therefore only useful immediately after a call to tt(gamma) or
-tt(lgamma).  Note also that `tt(signgam())' and `tt(signgam)' are distinct
-expresssions.
+tt(lgamma).  Note also that `tt(signgam+LPAR()RPAR)' and `tt(signgam)' are
+distinct expressions.
 
 The following functions take two floating point arguments: tt(copysign),
 tt(fmod), tt(hypot), tt(nextafter).
@@ -52,3 +52,38 @@ a floating point or integer value (by truncation) respectively.
 
 Note that the C tt(pow) function is available in ordinary math evaluation
 as the `tt(**)' operator and is not provided here.
+
+The function tt(rand48) is available if your system's mathematical library
+has the function tt(erand48(3)).  It returns a pseudo-random floating point
+number between 0 and 1.  It takes a single string optional argument.
+
+If the argument is not present, the random number seed is initialised by
+three calls to the tt(rand+LPAR()3+RPAR()) function --- this produces the
+same random
+numbers as the next three values of tt($RANDOM).
+
+If the argument is present, it gives the name of a scalar parameter where
+the current random number seed will be stored.  On the first call, the
+value must contain at least twelve hexadecimal digits (the remainder of the
+string is ignored), or the seed will be initialised in the same manner as
+for a call to tt(rand48) with no argument.  Subsequent calls to
+tt(rand48)LPAR()var(param)RPAR() will then maintain the seed in the
+parameter var(param) as a string of twelve hexadecimal digits, with no base
+signifier.  The random number sequences for different parameters are
+completely independent, and are also independent from that used by calls to
+tt(rand48) with no argument.
+
+For example, consider
+
+example(print $(( rand48(seed) ))
+print $(( rand48() ))
+print $(( rand48(seed) )))
+
+Assuming tt($seed) does not exist, it will be initialised by the first
+call.  In the second call, the default seed is initialised; note, however,
+that because of the properties of tt(rand+LPAR()RPAR()) there is a
+correlation between
+the seeds used for the two initialisations, so for more secure uses, you
+should generate your own 12-byte seed.  The third call returns to the same
+sequence of random numbers used in the first call, unaffected by the
+intervening tt(rand48()).