Merge of 21071: always use "status" in return and exit status docs + 21546: oddities of subscripts when searching arrays.

1 files changed, 435 insertions, 112 deletions

diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index f819aaecd..d48723756 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -8,25 +8,35 @@ characters and underscores, or the single characters
 `tt(*)', `tt(@)', `tt(#)', `tt(?)', `tt(-)', `tt($)', or `tt(!)'.
 The value may be a em(scalar) (a string),
 an integer, an array (indexed numerically), or an em(associative)
-array (an unordered set of name-value pairs, indexed by name).
-To assign a scalar or integer value to a parameter,
-use the tt(typeset) builtin.
+array (an unordered set of name-value pairs, indexed by name).  To declare
+the type of a parameter, or to assign a scalar or integer value to a
+parameter, use the tt(typeset) builtin.
 findex(typeset, use of)
-To assign an array value, use `tt(set -A) var(name) var(value) ...'.
-findex(set, use of)
-The value of a parameter may also be assigned by writing:
+
+The value of a scalar or integer parameter may also be assigned by
+writing:
+cindex(assignment)
 
 indent(var(name)tt(=)var(value))
 
 If the integer attribute, tt(-i), is set for var(name), the var(value)
-is subject to arithmetic evaluation.  See noderef(Array Parameters)
-for additional forms of assignment.
+is subject to arithmetic evaluation.  Furthermore, by replacing `tt(=)'
+with `tt(+=)', a parameter can be added or appended to.  See
+noderef(Array Parameters) for additional forms of assignment.
+
+To refer to the value of a parameter, write `tt($)var(name)' or
+`tt(${)var(name)tt(})'.  See
+ifzman(em(Parameter Expansion) in zmanref(zshexpn))\
+ifnzman(noderef(Parameter Expansion))
+for complete details.
 
 In the parameter lists that follow, the mark `<S>' indicates that the
 parameter is special.
-Special parameters cannot have their type changed, and they stay special even
-if unset.  `<Z>' indicates that the parameter does not exist when the shell
-initializes in tt(sh) or tt(ksh) emulation mode.
+Special parameters cannot have their type changed or their
+readonly attribute turned off, and if a special parameter is unset, then
+later recreated, the special properties will be retained.  `<Z>' indicates
+that the parameter does not exist when the shell initializes in tt(sh) or
+tt(ksh) emulation mode.
 startmenu()
 menu(Array Parameters)
 menu(Positional Parameters)
@@ -36,40 +46,78 @@ menu(Parameters Used By The Shell)
 endmenu()
 texinode(Array Parameters)(Positional Parameters)()(Parameters)
 sect(Array Parameters)
-The value of an array parameter may be assigned by writing:
+To assign an array value, write one of:
+findex(set, use of)
+cindex(array assignment)
 
+indent(tt(set -A) var(name) var(value) ...)
 indent(var(name)tt(=LPAR())var(value) ...tt(RPAR()))
 
 If no parameter var(name) exists, an ordinary array parameter is created.
-Associative arrays must be declared first, by `tt(typeset -A) var(name)'.
-When var(name) refers to an associative array, the parenthesized list is
-interpreted as alternating keys and values:
+If the parameter var(name) exists and is a scalar, it is replaced by a new
+array.  Ordinary array parameters may also be explicitly declared with:
+findex(typeset, use of)
+
+indent(tt(typeset -a) var(name))
+
+Associative arrays em(must) be declared before assignment, by using:
 
+indent(tt(typeset -A) var(name))
+
+When var(name) refers to an associative array, the list in an assignment
+is interpreted as alternating keys and values:
+
+indent(set -A var(name) var(key) var(value) ...)
 indent(var(name)tt(=LPAR())var(key) var(value) ...tt(RPAR()))
 
-Every var(key) must have a var(value) in this case.  To create an empty
-array or associative array, use:
+Every var(key) must have a var(value) in this case.  Note that this
+assigns to the entire array, deleting any elements that do not appear
+in the list.
+
+To create an empty array (including associative arrays), use one of:
 
+indent(tt(set -A) var(name))
 indent(var(name)tt(=LPAR()RPAR()))
 
-Individual elements of an array may be selected using a
-subscript.  A subscript of the form `tt([)var(exp)tt(])'
-selects the single element var(exp), where var(exp) is
-an arithmetic expression which will be subject to arithmetic
-expansion as if it were surrounded by `tt($LPAR()LPAR())...tt(RPAR()RPAR())'.
-The elements are numbered beginning with 1 unless the
-tt(KSH_ARRAYS) option is set when they are numbered from zero.
+subsect(Array Subscripts)
 cindex(subscripts)
+
+Individual elements of an array may be selected using a subscript.  A
+subscript of the form `tt([)var(exp)tt(])' selects the single element
+var(exp), where var(exp) is an arithmetic expression which will be subject
+to arithmetic expansion as if it were surrounded by
+`tt($LPAR()LPAR())...tt(RPAR()RPAR())'.  The elements are numbered
+beginning with 1, unless the tt(KSH_ARRAYS) option is set in which case
+they are numbered from zero.
 pindex(KSH_ARRAYS, use of)
 
-The same subscripting syntax is used for associative arrays,
-except that no arithmetic expansion is applied to var(exp).
+Subscripts may be used inside braces used to delimit a parameter name, thus
+`tt(${foo[2]})' is equivalent to `tt($foo[2])'.  If the tt(KSH_ARRAYS)
+option is set, the braced form is the only one that works, as bracketed
+expressions otherwise are not treated as subscripts.
+
+The same subscripting syntax is used for associative arrays, except that
+no arithmetic expansion is applied to var(exp).  However, the parsing
+rules for arithmetic expressions still apply, which affects the way that
+certain special characters must be protected from interpretation.  See
+em(Subscript Parsing) below for details.
 
-A subscript of the form `tt([*])' or `tt([@])' evaluates to all
-elements of an array; there is no difference between the two
-except when they appear within double quotes.
-`tt("$foo[*]")' evaluates to `tt("$foo[1] $foo[2] )...tt(")', while
-`tt("$foo[@]")' evaluates to `tt("$foo[1]" "$foo[2]")', etc.
+A subscript of the form `tt([*])' or `tt([@])' evaluates to all elements
+of an array; there is no difference between the two except when they
+appear within double quotes.
+`tt("$foo[*]")' evaluates to `tt("$foo[1] $foo[2] )...tt(")', whereas
+`tt("$foo[@]")' evaluates to `tt("$foo[1]" "$foo[2]" )...'.  For
+associative arrays, `tt([*])' or `tt([@])' evaluate to all the values,
+in no particular order.  Note that this does not substitute
+the keys; see the documentation for the `tt(k)' flag under
+ifzman(em(Parameter Expansion Flags) in zmanref(zshexpn))\
+ifnzman(noderef(Parameter Expansion))
+for complete details.
+When an array parameter is referenced as `tt($)var(name)' (with no
+subscript) it evaluates to `tt($)var(name)tt([*])', unless the tt(KSH_ARRAYS)
+option is set in which case it evaluates to `tt(${)var(name)tt([0]})' (for
+an associative array, this means the value of the key `tt(0)', which may
+not exist even if there are values for other keys).
 
 A subscript of the form `tt([)var(exp1)tt(,)var(exp2)tt(])'
 selects all elements in the range var(exp1) to var(exp2),
@@ -85,26 +133,44 @@ case the subscripts specify a substring to be extracted.
 For example, if tt(FOO) is set to `tt(foobar)', then
 `tt(echo $FOO[2,5])' prints `tt(ooba)'.
 
-Subscripts may be used inside braces used to delimit a parameter name, thus
-`tt(${foo[2]})' is equivalent to `tt($foo[2])'.  If the tt(KSH_ARRAYS)
-option is set, the braced form is the only one that will
-work, the subscript otherwise not being treated specially.
+subsect(Array Element Assignment)
+
+A subscript may be used on the left side of an assignment like so:
+
+indent(var(name)tt([)var(exp)tt(]=)var(value))
+
+In this form of assignment the element or range specified by var(exp)
+is replaced by the expression on the right side.  An array (but not an
+associative array) may be created by assignment to a range or element.
+Arrays do not nest, so assigning a parenthesized list of values to an
+element or range changes the number of elements in the array, shifting the
+other elements to accommodate the new values.  (This is not supported for
+associative arrays.)
+
+This syntax also works as an argument to the tt(typeset) command:
 
-If a subscript is used on the left side of an assignment the selected
-element or range is replaced by the expression on the right side.  An
-array (but not an associative array) may be created by assignment to a
-range or element.  Arrays do not nest, so assigning a parenthesized list
-of values to an element or range changes the number of elements in the
-array, shifting the other elements to accommodate the new values.  (This
-is not supported for associative arrays.)
+indent(tt(typeset) tt(")var(name)tt([)var(exp)tt(]"=)var(value))
+
+The var(value) may em(not) be a parenthesized list in this case; only
+single-element assignments may be made with tt(typeset).  Note that quotes
+are necessary in this case to prevent the brackets from being interpreted
+as filename generation operators.  The tt(noglob) precommand modifier
+could be used instead.
 
 To delete an element of an ordinary array, assign `tt(LPAR()RPAR())' to
-that element.
-To delete an element of an associative array, use the tt(unset) command.
+that element.  To delete an element of an associative array, use the
+tt(unset) command:
+
+indent(tt(unset) tt(")var(name)tt([)var(exp)tt(]"))
+
+subsect(Subscript Flags)
+cindex(subscript flags)
 
-If the opening bracket or the comma is directly followed by an opening
-parentheses the string up to the matching closing one is considered to
-be a list of flags. The flags currently understood are:
+If the opening bracket, or the comma in a range, in any subscript
+expression is directly followed by an opening parenthesis, the string up
+to the matching closing one is considered to be a list of flags, as in
+`var(name)tt([LPAR())var(flags)tt(RPAR())var(exp)tt(])'.  The flags
+currently understood are:
 
 startitem()
 item(tt(w))(
@@ -126,54 +192,209 @@ subscripting work on lines instead of characters, i.e. with elements
 separated by newlines.  This is a shorthand for `tt(pws:\n:)'.
 )
 item(tt(r))(
-Reverse subscripting:  if this flag is given, the var(exp) is taken as a
-pattern and the  result is the first matching array element, substring or
-word (if the parameter is an array, if it is a scalar, or if it is a scalar
-and the `tt(w)' flag is given, respectively).  The subscript used is the
-number of the matching element, so that pairs of subscripts such as
-`tt($foo[(r))var(??)tt(,3])' and `tt($foo[(r))var(??)tt(,(r)f*])'
-are possible.  If the parameter is an associative array, only the value part
-of each pair is compared to the pattern.
+Reverse subscripting: if this flag is given, the var(exp) is taken as a
+pattern and the result is the first matching array element, substring or
+word (if the parameter is an array, if it is a scalar, or if it is a
+scalar and the `tt(w)' flag is given, respectively).  The subscript used
+is the number of the matching element, so that pairs of subscripts such as
+`tt($foo[(r))var(??)tt(,3])' and `tt($foo[(r))var(??)tt(,(r)f*])' are
+possible if the parameter is not an associative array.  If the
+parameter is an associative array, only the value part of each pair is
+compared to the pattern, and the result is that value.
+
+If a search through an ordinary array failed, the search sets the
+subscript to one past the end of the array, and hence
+tt(${array[(r)pattern]}) will substitute the empty string.  Thus the
+success of a search can be tested by using the tt((i)) flag, for
+example (assuming the option tt(KSH_ARRAYS) is not in effect):
+
+example([[ ${array[(i)pattern]} -le ${#array} ]])
+
+If tt(KSH_ARRAYS) is in effect, the tt(-le) should be replaced by tt(-lt).
 )
 item(tt(R))(
 Like `tt(r)', but gives the last match.  For associative arrays, gives
-all possible matches.
-)
-item(tt(k))(
-If used in a subscript on a parameter that is not an associative
-array, this behaves like `tt(r)', but if used on an association, it
-makes the keys be interpreted as patterns and returns the first value
-whose key matches the var(exp).
-)
-item(tt(K))(
-On an associtation this is like `tt(k)' but returns all values whose
-keys match the var(exp). On other types of parameters this has the
-same effect as `tt(R)'.
+all possible matches. May be used for assigning to ordinary array
+elements, but not for assigning to associative arrays.
+
+Note that this flag can give odd results on failure.  For an ordinary array
+the item substituted is that corresponding to subscript 0.  If the option
+tt(KSH_ARRAYS) is not in effect, this is the same as the element
+corresponding to subscript 1, although the form tt(${array[(I)pattern]})
+will evaluate to 0 for a failed match.  If the option tt(KSH_ARRAYS) is in
+effect, the subscript is still 0 for a failed match; this cannot be
+distinguished from a successful match without testing tt(${array[0]})
+against the pattern.
 )
 item(tt(i))(
-like `tt(r)', but gives the index of the match instead; this may not
-be combined with a second argument.  For associative arrays, the key
-part of each pair is compared to the pattern, and the first matching
-key found is used.
+Like `tt(r)', but gives the index of the match instead; this may not be
+combined with a second argument.  On the left side of an assignment,
+behaves like `tt(r)'.  For associative arrays, the key part of each pair
+is compared to the pattern, and the first matching key found is the
+result.
+
+See `tt(r)' for discussion of subscripts of failed matches.
 )
 item(tt(I))(
-like `tt(i)', but gives the index of the last match, or all possible
+Like `tt(i)', but gives the index of the last match, or all possible
 matching keys in an associative array.
+
+See `tt(R)' for discussion of subscripts of failed matches.
+)
+item(tt(k))(
+If used in a subscript on an associative array, this flag causes the keys
+to be interpreted as patterns, and returns the value for the first key
+found where var(exp) is matched by the key.  This flag does not work on
+the left side of an assignment to an associative array element.  If used
+on another type of parameter, this behaves like `tt(r)'.
+)
+item(tt(K))(
+On an associative array this is like `tt(k)' but returns all values where
+var(exp) is matched by the keys.  On other types of parameters this has
+the same effect as `tt(R)'.
 )
 item(tt(n:)var(expr)tt(:))(
-if combined with `tt(r)', `tt(R)', `tt(i)' or `tt(I)', makes them give
+If combined with `tt(r)', `tt(R)', `tt(i)' or `tt(I)', makes them give
 the var(n)th or var(n)th last match (if var(expr) evaluates to
 var(n)).  This flag is ignored when the array is associative.
 )
 item(tt(b:)var(expr)tt(:))(
-if combined with `tt(r)', `tt(R)', `tt(i)' or `tt(I)', makes them begin
+If combined with `tt(r)', `tt(R)', `tt(i)' or `tt(I)', makes them begin
 at the var(n)th or var(n)th last element, word, or character (if var(expr)
 evaluates to var(n)).  This flag is ignored when the array is associative.
 )
 item(tt(e))(
-This option has no effect and retained for backward compatibility only.
+This flag has no effect and for ordinary arrays is retained for backward
+compatibility only.  For associative arrays, this flag can be used to
+force tt(*) or tt(@) to be interpreted as a single key rather than as a
+reference to all values.  This flag may be used on the left side of an
+assignment.
 )
 enditem()
+
+See em(Parameter Expansion Flags) (\
+ifzman(zmanref(zshexpn))\
+ifnzman(noderef(Parameter Expansion))\
+) for additional ways to manipulate the results of array subscripting.
+
+subsect(Subscript Parsing)
+
+This discussion applies mainly to associative array key strings and to
+patterns used for reverse subscripting (the `tt(r)', `tt(R)', `tt(i)',
+etc. flags), but it may also affect parameter substitutions that appear
+as part of an arithmetic expression in an ordinary subscript.
+
+It is possible to avoid the use of subscripts in assignments to associative
+array elements by using the syntax:
+
+example(
+   aa+=('key with "*strange*" characters' 'value string')
+)
+
+This adds a new key/value pair if the key is not already present, and
+replaces the value for the existing key if it is.
+
+The basic rule to remember when writing a subscript expression is that all
+text between the opening `tt([)' and the closing `tt(])' is interpreted
+em(as if) it were in double quotes (\
+ifzman(see zmanref(zshmisc))\
+ifnzman(noderef(Quoting))\
+).  However, unlike double quotes which normally cannot nest, subscript
+expressions may appear inside double-quoted strings or inside other
+subscript expressions (or both!), so the rules have two important
+differences.
+
+The first difference is that brackets (`tt([)' and `tt(])') must appear as
+balanced pairs in a subscript expression unless they are preceded by a
+backslash (`tt(\)').  Therefore, within a subscript expression (and unlike
+true double-quoting) the sequence `tt(\[)' becomes `tt([)', and similarly
+`tt(\])' becomes `tt(])'.  This applies even in cases where a backslash is
+not normally required; for example, the pattern `tt([^[])' (to match any
+character other than an open bracket) should be written `tt([^\[])' in a
+reverse-subscript pattern.  However, note that `tt(\[^\[\])' and even
+`tt(\[^[])' mean the em(same) thing, because backslashes are always
+stripped when they appear before brackets!
+
+The same rule applies to parentheses (`tt(LPAR())' and `tt(RPAR())') and
+braces (`tt({)' and `tt(})'): they must appear either in balanced pairs or
+preceded by a backslash, and backslashes that protect parentheses or
+braces are removed during parsing.  This is because parameter expansions
+may be surrounded balanced braces, and subscript flags are introduced by
+balanced parenthesis.
+
+The second difference is that a double-quote (`tt(")') may appear as part
+of a subscript expression without being preceded by a backslash, and
+therefore that the two characters `tt(\")' remain as two characters in the
+subscript (in true double-quoting, `tt(\")' becomes `tt(")').  However,
+because of the standard shell quoting rules, any double-quotes that appear
+must occur in balanced pairs unless preceded by a backslash.  This makes
+it more difficult to write a subscript expression that contains an odd
+number of double-quote characters, but the reason for this difference is
+so that when a subscript expression appears inside true double-quotes, one
+can still write `tt(\")' (rather than `tt(\\\")') for `tt(")'.
+
+To use an odd number of double quotes as a key in an assignment, use the
+tt(typeset) builtin and an enclosing pair of double quotes; to refer to
+the value of that key, again use double quotes:
+
+example(typeset -A aa
+typeset "aa[one\"two\"three\"quotes]"=QQQ
+print "$aa[one\"two\"three\"quotes]")
+
+It is important to note that the quoting rules do not change when a
+parameter expansion with a subscript is nested inside another subscript
+expression.  That is, it is not necessary to use additional backslashes
+within the inner subscript expression; they are removed only once, from
+the innermost subscript outwards.  Parameters are also expanded from the
+innermost subscript first, as each expansion is encountered left to right
+in the outer expression.
+
+A further complication arises from a way in which subscript parsing is
+em(not) different from double quote parsing.  As in true double-quoting,
+the sequences `tt(\*)', and `tt(\@)' remain as two characters when they
+appear in a subscript expression.  To use a literal `tt(*)' or `tt(@)' as
+an associative array key, the `tt(e)' flag must be used:
+
+example(typeset -A aa
+aa[(e)*]=star
+print $aa[(e)*])
+
+A last detail must be considered when reverse subscripting is performed.
+Parameters appearing in the subscript expression are first expanded and
+then the complete expression is interpreted as a pattern.  This has two
+effects: first, parameters behave as if tt(GLOB_SUBST) were on (and it
+cannot be turned off); second, backslashes are interpreted twice, once
+when parsing the array subscript and again when parsing the pattern.  In a
+reverse subscript, it's necessary to use em(four) backslashes to cause a
+single backslash to match literally in the pattern.  For complex patterns,
+it is often easiest to assign the desired pattern to a parameter and then
+refer to that parameter in the subscript, because then the backslashes,
+brackets, parentheses, etc., are seen only when the complete expression is
+converted to a pattern.  To match the value of a parameter literally in a
+reverse subscript, rather than as a pattern,
+use `tt(${LPAR()q)tt(RPAR())var(name)tt(})' (\
+ifzman(see zmanref(zshexpn))\
+ifnzman(noderef(Parameter Expansion))\
+) to quote the expanded value.
+
+Note that the `tt(k)' and `tt(K)' flags are reverse subscripting for an
+ordinary array, but are em(not) reverse subscripting for an associative
+array!  (For an associative array, the keys in the array itself are
+interpreted as patterns by those flags; the subscript is a plain string
+in that case.)
+
+One final note, not directly related to subscripting: the numeric names
+of positional parameters (\
+ifzman(described below)\
+ifnzman(noderef(Positional Parameters))\
+) are parsed specially, so for example `tt($2foo)' is equivalent to
+`tt(${2}foo)'.  Therefore, to use subscript syntax to extract a substring
+from a positional parameter, the expansion must be surrounded by braces;
+for example, `tt(${2[3,5]})' evaluates to the third through fifth
+characters of the second positional parameter, but `tt($2[3,5])' is the
+entire second parameter concatenated with the filename generation pattern
+`tt([3,5])'.
+
 texinode(Positional Parameters)(Local Parameters)(Array Parameters)(Parameters)
 sect(Positional Parameters)
 The positional parameters provide access to the command-line arguments
@@ -215,21 +436,19 @@ any outer parameter of the same name remains hidden.
 
 Special parameters may also be made local; they retain their special
 attributes unless either the existing or the newly-created parameter
-has the tt(-h) (hide) attribute.  This may have unexpected effects.
-Firstly, there is no default value, so if there is no assigment at the
+has the tt(-h) (hide) attribute.  This may have unexpected effects:
+there is no default value, so if there is no assignment at the
 point the variable is made local, it will be set to an empty value (or zero
-in the case of integers).  Secondly, special parameters which are made
-local will not be exported (as with other parameters), so that the global
-value of the parameter remains present in the environment if it is already
-there.  This should be particularly noted in the case of tt(PATH): the
-shell will use the local version of tt(PATH) for finding programmes, but
-programmes using the shell's environment will inherit the global version.
+in the case of integers).  
 The following:
 
 example(typeset PATH=/new/directory:$PATH)
 
-is valid for temporarily allowing the shell to find the programs in
-tt(/new/directory) inside a function.
+is valid for temporarily allowing the shell or programmes called from it to
+find the programs in tt(/new/directory) inside a function.
+
+Note that the restriction in older versions of zsh that local parameters
+were never exported has been removed.
 
 texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Local Parameters)(Parameters)
 sect(Parameters Set By The Shell)
@@ -242,7 +461,11 @@ The process ID of the last background command invoked.
 )
 vindex(#)
 item(tt(#) <S>)(
-The number of positional parameters in decimal.
+The number of positional parameters in decimal.  Note that some confusion
+may occur with the syntax tt($#)var(param) which substitutes the length of
+var(param).  Use tt(${#}) to resolve ambiguities.  In particular, the
+sequence `tt($#-)var(...)' in an arithmetic expression is interpreted as
+the length of the parameter tt(-), q.v.
 )
 vindex(ARGC)
 item(tt(ARGC) <S> <Z>)(
@@ -275,7 +498,7 @@ Same as tt(argv[@]), even when tt(argv) is not set.
 )
 vindex(?)
 item(tt(?) <S>)(
-The exit value returned by the last command.
+The exit status returned by the last command.
 )
 vindex(0)
 item(tt(0) <S>)(
@@ -287,12 +510,22 @@ vindex(status)
 item(tt(status) <S> <Z>)(
 Same as tt(?).
 )
+vindex(pipestatus)
+item(tt(pipestatus) <S> <Z>)(
+An array containing the exit statuses returned by all commands in the
+last pipeline.
+)
 vindex(_)
 item(tt(_) <S>)(
 The last argument of the previous command.
 Also, this parameter is set in the environment of every command
 executed to the full pathname of the command.
 )
+vindex(CPUTYPE)
+item(tt(CPUTYPE))(
+The machine type (microprocessor class or machine model),
+as determined at run time.
+)
 vindex(EGID)
 item(tt(EGID) <S>)(
 The effective group ID of the shell process.  If you have sufficient
@@ -314,7 +547,8 @@ item(tt(ERRNO) <S>)(
 The value of errno (see manref(errno)(3))
 as set by the most recently failed system call.
 This value is system dependent and is intended for debugging
-purposes.
+purposes.  It is also useful with the tt(zsh/system) module which
+allows the number to be turned into a name or message.
 )
 vindex(GID)
 item(tt(GID) <S>)(
@@ -324,6 +558,12 @@ parameter.  Also (assuming sufficient privileges), you may start a single
 command under a different
 group ID by `tt(LPAR()GID=)var(gid)tt(; command+RPAR())'
 )
+vindex(HISTCMD)
+item(tt(HISTCMD))(
+The current history line number in an interactive shell, in other
+words the line number for the command that caused tt($HISTCMD)
+to be read.
+)
 vindex(HOST)
 item(tt(HOST))(
 The current hostname.
@@ -334,7 +574,7 @@ The line number of the current line within the current script, sourced
 file, or shell function being executed, whichever was started most
 recently.  Note that in the case of shell functions the line
 number refers to the function as it appeared in the original definition,
-not necesarily as displayed by the tt(functions) builtin.
+not necessarily as displayed by the tt(functions) builtin.
 )
 vindex(LOGNAME)
 item(tt(LOGNAME))(
@@ -378,9 +618,14 @@ and whenever the directory changes.
 )
 vindex(RANDOM)
 item(tt(RANDOM) <S>)(
-A random integer from 0 to 32767, newly generated each time
+A pseudo-random integer from 0 to 32767, newly generated each time
 this parameter is referenced.  The random number generator
 can be seeded by assigning a numeric value to tt(RANDOM).
+
+The values of tt(RANDOM) form an intentionally-repeatable pseudo-random
+sequence; subshells that reference tt(RANDOM) will result
+in identical pseudo-random values unless the value of tt(RANDOM) is
+referenced or seeded in the parent shell in between subshell invocations.
 )
 vindex(SECONDS)
 item(tt(SECONDS) <S>)(
@@ -388,6 +633,12 @@ The number of seconds since shell invocation.  If this parameter
 is assigned a value, then the value returned upon reference
 will be the value that was assigned plus the number of seconds
 since the assignment.
+
+Unlike other special parameters, the type of the tt(SECONDS) parameter can
+be changed using the tt(typeset) command.  Only integer and one of the
+floating point types are allowed.  For example, `tt(typeset -F SECONDS)'
+causes the value to be reported as a floating point number.  The precision
+is six decimal places, although not all places may be useful.
 )
 vindex(SHLVL)
 item(tt(SHLVL) <S>)(
@@ -397,6 +648,14 @@ vindex(signals)
 item(tt(signals))(
 An array containing the names of the signals.
 )
+vindex(TRY_BLOCK_ERROR)
+item(tt(TRY_BLOCK_ERROR) <S>)(
+In an tt(always) block, indicates whether the preceding list of code
+caused an error.  The value is 1 to indicate an error, 0 otherwise.
+It may be reset, clearing the error condition.  See
+ifzman(em(Complex Commands) in zmanref(zshmisc))\
+ifnzman(noderef(Complex Commands))
+)
 vindex(TTY)
 item(tt(TTY))(
 The name of the tty associated with the shell, if any.
@@ -439,7 +698,17 @@ The version number of this zsh.
 enditem()
 texinode(Parameters Used By The Shell)()(Parameters Set By The Shell)(Parameters)
 sect(Parameters Used By The Shell)
-The following parameters are used by the shell:
+The following parameters are used by the shell.
+
+In cases where there are two parameters with an upper- and lowercase
+form of the same name, such as tt(path) and tt(PATH), the lowercase form
+is an array and the uppercase form is a scalar with the elements of the
+array joined together by colons.  These are similar to tied parameters
+created via `tt(typeset -T)'.  The normal use for the colon-separated
+form is for exporting to the environment, while the array form is easier
+to manipulate within the shell.  Note that unsetting either of the pair
+will unset the other; they retain their special properties when
+recreated, and recreating one of the pair will recreate the other.
 
 startitem()
 vindex(ARGV0)
@@ -479,6 +748,14 @@ stack gets larger than this, it will be truncated automatically.
 This is useful with the tt(AUTO_PUSHD) option.
 pindex(AUTO_PUSHD, use of)
 )
+vindex(ENV)
+item(tt(ENV))(
+If the tt(ENV) environment variable is set when zsh is invoked as tt(sh)
+or tt(ksh), tt($ENV) is sourced after the profile scripts.  The value of
+tt(ENV) is subjected to parameter expansion, command substitution, and
+arithmetic expansion before being interpreted as a pathname.  Note that
+tt(ENV) is em(not) used unless zsh is emulating bf(sh) or bf(ksh).
+)
 vindex(FCEDIT)
 item(tt(FCEDIT))(
 The default editor for the tt(fc) builtin.
@@ -488,9 +765,8 @@ vindex(FIGNORE)
 item(tt(fignore) <S> <Z> (tt(FIGNORE) <S>))(
 An array (colon separated list)
 containing the suffixes of files to be ignored
-during filename completion.  However, if the completion generates only files
-which would match if this variable would be ignored, than these files are
-completed anyway.
+during filename completion.  However, if completion only generates files
+with suffixes in this list, then these files are completed anyway.
 )
 vindex(fpath)
 vindex(FPATH)
@@ -671,6 +947,21 @@ item(tt(POSTEDIT) <S>)(
 This string is output whenever the line editor exits.
 It usually contains termcap strings to reset the terminal.
 )
+vindex(PROMPT)
+xitem(tt(PROMPT) <S> <Z>)
+vindex(PROMPT2)
+xitem(tt(PROMPT2) <S> <Z>)
+vindex(PROMPT3)
+xitem(tt(PROMPT3) <S> <Z>)
+vindex(PROMPT4)
+item(tt(PROMPT4) <S> <Z>)(
+Same as tt(PS1), tt(PS2), tt(PS3) and tt(PS4),
+respectively.
+)
+vindex(prompt)
+item(tt(prompt) <S> <Z>)(
+Same as tt(PS1).
+)
 vindex(PS1)
 item(tt(PS1) <S>)(
 The primary prompt string, printed before a command is read.
@@ -697,17 +988,6 @@ The execution trace prompt.  Default is `tt(PLUS()%N:%i> )', which displays
 the name of the current shell structure and the line number within it.
 In sh or ksh emulation, the default is `tt(PLUS() )'.
 )
-vindex(PROMPT)
-xitem(tt(PROMPT) <S> <Z>)
-vindex(PROMPT2)
-xitem(tt(PROMPT2) <S> <Z>)
-vindex(PROMPT3)
-xitem(tt(PROMPT3) <S> <Z>)
-vindex(PROMPT4)
-item(tt(PROMPT4) <S> <Z>)(
-Same as tt(PS1), tt(PS2), tt(PS3) and tt(PS4),
-respectively.
-)
 vindex(psvar)
 vindex(PSVAR)
 item(tt(psvar) <S> <Z> (tt(PSVAR) <S>))(
@@ -715,10 +995,6 @@ An array (colon-separated list) whose first nine values can be used in
 tt(PROMPT) strings.  Setting tt(psvar) also sets tt(PSVAR), and
 vice versa.
 )
-vindex(prompt)
-item(tt(prompt) <S> <Z>)(
-Same as tt(PS1).
-)
 vindex(READNULLCMD)
 item(tt(READNULLCMD) <S>)(
 The command name to assume if a single input redirection
@@ -730,6 +1006,19 @@ If nonnegative, commands whose combined user and system execution times
 (measured in seconds) are greater than this value have timing
 statistics printed for them.
 )
+vindex(REPLY)
+item(tt(REPLY))(
+This parameter is reserved by convention to pass string values between
+shell scripts and shell builtins in situations where a function call or
+redirection are impossible or undesirable.  The tt(read) builtin and the
+tt(select) complex command may set tt(REPLY), and filename generation both
+sets and examines its value when evaluating certain expressions.  Some
+modules also employ tt(REPLY) for similar purposes.
+)
+vindex(reply)
+item(tt(reply))(
+As tt(REPLY), but for array values rather than strings.
+)
 vindex(RPROMPT)
 xitem(tt(RPROMPT) <S>)
 vindex(RPS1)
@@ -739,6 +1028,15 @@ when the primary prompt is being displayed on the left.
 This does not work if the tt(SINGLELINEZLE) option is set.
 It is expanded in the same way as tt(PS1).
 )
+vindex(RPROMPT2)
+xitem(tt(RPROMPT2) <S>)
+vindex(RPS2)
+item(tt(RPS2) <S>)(
+This prompt is displayed on the right-hand side of the screen
+when the secondary prompt is being displayed on the left.
+This does not work if the tt(SINGLELINEZLE) option is set.
+It is expanded in the same way as tt(PS2).
+)
 vindex(SAVEHIST)
 item(tt(SAVEHIST))(
 The maximum number of history events to save in the history file.
@@ -767,20 +1065,45 @@ window size specifications; these will not be local to the command.
 )
 vindex(TERM)
 item(tt(TERM) <S>)(
-The type of terminal in use.  This is used when looking up termcap sequences.
+The type of terminal in use.  This is used when looking up termcap
+sequences.  An assignment to tt(TERM) causes zsh to re-initialize the
+terminal, even if the value does not change (e.g., `tt(TERM=$TERM)').  It
+is necessary to make such an assignment upon any change to the terminal
+definition database or terminal type in order for the new settings to
+take effect.
 )
 vindex(TIMEFMT)
 item(tt(TIMEFMT))(
 The format of process time reports with the tt(time) keyword.
 The default is `tt(%E real  %U user  %S system  %P %J)'.
-Recognizes the following escape sequences:
+Recognizes the following escape sequences, although not all
+may be available on all systems, and some that are available
+may not be useful:
 
 startsitem()
 sitem(tt(%%))(A `tt(%)'.)
 sitem(tt(%U))(CPU seconds spent in user mode.)
 sitem(tt(%S))(CPU seconds spent in kernel mode.)
 sitem(tt(%E))(Elapsed time in seconds.)
-sitem(tt(%P))(The CPU percentage, computed as (tt(%U)PLUS()tt(%S))/tt(%E).)
+sitem(tt(%P))(The CPU percentage, computed as
+(100*tt(%U)PLUS()tt(%S))/tt(%E).)
+sitem(tt(%W))(Number of times the process was swapped.)
+sitem(tt(%X))(The average amount in (shared) text space used in Kbytes.)
+sitem(tt(%D))(The average amount in (unshared) data/stack space used in
+Kbytes.)
+sitem(tt(%K))(The total space used (%X+%D) in Kbytes.)
+sitem(tt(%M))(The  maximum memory the process had in use at any time in
+Kbytes.)
+sitem(tt(%F))(The number of major page faults (page needed to be brought
+from disk).)
+sitem(tt(%R))(The number of minor page faults.)
+sitem(tt(%I))(The number of input operations.)
+sitem(tt(%O))(The number of output operations.)
+sitem(tt(%r))(The number of socket messages received.)
+sitem(tt(%s))(The number of socket messages sent.)
+sitem(tt(%k))(The number of signals received.)
+sitem(tt(%w))(Number of voluntary context switches (waits).)
+sitem(tt(%c))(Number of involuntary context switches.)
 sitem(tt(%J))(The name of this job.)
 endsitem()