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

3 files changed, 138 insertions, 13 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()).
diff --git a/Doc/Zsh/mod_zftp.yo b/Doc/Zsh/mod_zftp.yo
index 55f08bedd..de53cdbb3 100644
--- a/Doc/Zsh/mod_zftp.yo
+++ b/Doc/Zsh/mod_zftp.yo
@@ -31,15 +31,25 @@ cindex(zftp, subcommands)
 
 startitem()
 cindex(FTP, starting a session)
-item(tt(open) var(host) [ var(user) [ var(password) [ var(account) ] ] ])(
+item(tt(open) var(host)[tt(:)var(port)] [ var(user) [ var(password) [ var(account) ] ] ])(
 Open a new FTP session to var(host), which may be the name of a TCP/IP
-connected host or an IP number in the standard dot notation.
+connected host or an IP number in the standard dot notation.  If the
+argument is in the form var(host)tt(:)var(port), open a connection to
+TCP port var(port) instead of the standard FTP port 21.  This may be
+the name of a TCP service or a number:  see the description of
+tt(ZFTP_PORT) below for more information.
+
+If IPv6 addresses in colon format are used, the var(host) should be
+surrounded by quoted square brackets to distinguish it from the var(port),
+for example tt('[fe80::203:baff:fe02:8b56]').  For consistency this is
+allowed with all forms of var(host).
+
 Remaining arguments are passed to the tt(login) subcommand.  Note that
 if no arguments beyond var(host) are supplied, tt(open) will em(not)
 automatically call tt(login).  If no arguments at all are supplied,
 tt(open) will use the parameters set by the tt(params) subcommand.
 
-After a successful open, the shell variables tt(ZFTP_HOST),
+After a successful open, the shell variables tt(ZFTP_HOST), tt(ZFTP_PORT),
 tt(ZFTP_IP) and tt(ZFTP_SYSTEM) are available; see `Variables'
 below.
 )
@@ -65,7 +75,7 @@ item(tt(params) tt(-))(
 Store the given parameters for a later tt(open) command with no
 arguments.  Only those given on the command line will be remembered.
 If no arguments are given, the parameters currently set are printed,
-although the password will appear as a line of stars; the return value is
+although the password will appear as a line of stars; the return status is
 one if no parameters were set, zero otherwise.
 
 Any of the parameters may be specified as a `tt(?)', which
@@ -102,8 +112,9 @@ silent, apart from messages printed by the tt($ZFTP_VERBOSE)
 mechanism, or error messages if the connection closes.  There is no
 network overhead for this test.
 
-The test is only supported on systems with either the tt(select(2)) or
-tt(poll(2)) system calls; otherwise the message `tt(not
+The test is only supported on systems with either the
+tt(select+LPAR()2+RPAR()) or
+tt(poll+LPAR()2+RPAR()) system calls; otherwise the message `tt(not
 supported on this system)' is printed instead.
 
 The tt(test) subcommand will automatically be called at the start of any
@@ -222,7 +233,7 @@ control connection are sent to standard error.
 xitem(tt(close))
 item(tt(quit))(
 Close the current data connection.  This unsets the shell parameters
-tt(ZFTP_HOST), tt(ZFTP_IP), tt(ZFTP_SYSTEM), tt(ZFTP_USER),
+tt(ZFTP_HOST), tt(ZFTP_PORT), tt(ZFTP_IP), tt(ZFTP_SYSTEM), tt(ZFTP_USER),
 tt(ZFTP_ACCOUNT), tt(ZFTP_PWD), tt(ZFTP_TYPE) and tt(ZFTP_MODE).
 )
 item(tt(session) [ var(sessname) ])(
@@ -278,6 +289,18 @@ opened as an IP number, tt(ZFTP_HOST) contains that instead; this
 saves the overhead for a name lookup, as IP numbers are most commonly
 used when a nameserver is unavailable.
 )
+vindex(ZFTP_PORT)
+item(tt(ZFTP_PORT))(
+Readonly.  The number of the remote TCP port to which the connection is
+open (even if the port was originally specified as a named service).
+Usually this is the standard FTP port, 21.
+
+In the unlikely event that your system does not have the appropriate
+conversion functions, this appears in network byte order.  If your
+system is little-endian, the port then consists of two swapped bytes and the
+standard port will be reported as 5376.  In that case, numeric ports passed
+to tt(zftp open) will also need to be in this format.
+)
 vindex(ZFTP_SYSTEM)
 item(tt(ZFTP_SYSTEM))(
 Readonly.  The system type string returned by the server in response
@@ -474,6 +497,6 @@ all connections, and deleting a session changes the ordering of that
 information.
 
 On some operating systems, the control connection is not valid after a
-fork(), so that operations in subshells, on the left hand side of a
-pipeline, or in the background are not possible, as they should be.  This
-is presumably a bug in the operating system.
+fork+LPAR()RPAR(), so that operations in subshells, on the left hand side
+of a pipeline, or in the background are not possible, as they should be.
+This is presumably a bug in the operating system.
diff --git a/Doc/Zsh/mod_zselect.yo b/Doc/Zsh/mod_zselect.yo
new file mode 100644
index 000000000..23beef1e8
--- /dev/null
+++ b/Doc/Zsh/mod_zselect.yo
@@ -0,0 +1,67 @@
+COMMENT(!MOD!zsh/zselect
+Block and return when file descriptors are ready.
+!MOD!)
+The tt(zsh/zselect) module makes available one builtin command:
+
+startitem()
+findex(zselect)
+cindex(select, system call)
+cindex(file descriptors, waiting for)
+item(tt(zselect) [ tt(-rwe) tt(-t) var(timeout) tt(-a) var(array) ] [ var(fd) ... ])(
+The tt(zselect) builtin is a front-end to the `select' system call, which
+blocks until a file descriptor is ready for reading or writing, or has an
+error condition, with an optional timeout.  If this is not available on
+your system, the command prints an error message and returns status 2
+(normal errors return status 1).  For more information, see your systems
+documentation for manref(select)(3).  Note there is no connection with the
+shell builtin of the same name.
+
+Arguments and options may be intermingled in any order.  Non-option
+arguments are file descriptors, which must be decimal integers.  By
+default, file descriptors are to be tested for reading, i.e. tt(zselect)
+will return when data is available to be read from the file descriptor, or
+more precisely, when a read operation from the file descriptor will not
+block.  After a tt(-r), tt(-w) and tt(-e), the given file descriptors are
+to be tested for reading, writing, or error conditions.  These options and
+an arbitrary list of file descriptors may be given in any order.
+
+(The presence of an `error condition' is not well defined in the
+documentation for many implementations of the select system call.
+According to recent versions of the POSIX specification, it is really an
+em(exception) condition, of which the only standard example is out-of-band
+data received on a socket.  So zsh users are unlikely to find the tt(-e)
+option useful.)
+
+The option `tt(-t) var(timeout)' specifies a timeout in hundredths of a
+second.  This may be zero, in which case the file descriptors will simply
+be polled and tt(zselect) will return immediately.  It is possible to call
+zselect with no file descriptors and a non-zero timeout for use as a
+finer-grained replacement for `sleep'; not, however, the return status is
+always 1 for a timeout.
+
+The option `tt(-a) var(array)' indicates that tt(array) should be set to
+indicate the file descriptor+LPAR()s+RPAR() which are ready.  If the option
+is not
+given, the array tt(reply) will be used for this purpose.  The array will
+contain a string similar to the arguments for tt(zselect).  For example,
+
+example(zselect -t 0 -r 0 -w 1)
+
+might return immediately with status 0 and tt($reply) containing `tt(-r 0 -w
+1)' to show that both file descriptors are ready for the requested
+operations.
+
+The option `tt(-A) var(assoc)' indicates that the associative array
+tt(assoc) should be set to indicate the file descriptor+LPAR()s+LPAR()
+which are ready.  This option overrides the option tt(-a), nor will
+tt(reply) be modified.  The keys of tt(assoc) are the file descriptors, and
+the corresponding values are any of the characters `tt(rwe)' to indicate
+the condition.
+
+The command returns status 0 if some file descriptors are ready for
+reading.  If the operation timed out, or a timeout of 0 was given and no
+file descriptors were ready, or there was an error, it returns status 1 and
+the array will not be set (nor modified in any way).  If there was an error
+in the select operation the appropriate error message is printed.
+)
+enditem()