PATCH: 3.1.5-pws-3: Parameter documentation cleanup + associative arrays

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxx>]

This patch includes the following:

 * Canonicalize usage of terms "history expansion", "alias expansion",
   "process substitution", "parameter expansion", "command substitution",
   "arithmetic expansion", "brace expansion", "filename expansion", and
   "filename generation" throughout.

 * Always use "expansion" to refer to the complete process described in
   expn.yo; never call it "substitution."  Similarly, parameters are
   "expanded" not "substituted" nor "printed" (but the expansion is then
   "substituted" in some cases; there aren't enough words to go around).

 * In some (but probably still not all) cases, say various manipulations
   are performed on the "expansion" of a parameter, not on its "value."
   (The value as stored stays unchanged in nearly all cases!  I'd also
   have liked to have replaced all uses of "variable" with "parameter,"
   but ...)

 * Move some crucial information from the end of the description of
   `typeset' to the beginning, and expand upon it a little.

 * Rearrange the list of expansion forms slightly, to lift out some oft-
   repeated verbiage.
 
 * Document associative arrays (the real reason I started on all this).

I'm going to bed early the rest of this week.

Index: Doc/Zsh/arith.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/arith.yo,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 arith.yo
--- arith.yo	1998/06/01 17:08:42	1.1.1.1
+++ arith.yo	1998/12/16 05:38:31
@@ -53,7 +53,7 @@
 of the parameter var(foo).
 
 Named parameters and subscripted arrays can be referenced by name within an
-arithmetic expression without using the parameter substitution syntax.
+arithmetic expression without using the parameter expansion syntax.
 
 An internal integer representation of a named parameter
 can be specified with the tt(integer) builtin.
Index: Doc/Zsh/builtins.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/builtins.yo,v
retrieving revision 1.10
diff -u -r1.10 builtins.yo
--- builtins.yo	1998/12/14 22:03:18	1.10
+++ builtins.yo	1998/12/16 09:29:11
@@ -47,7 +47,7 @@
 item(tt(alias) [ tt(-gmrL) ] [ var(name)[tt(=)var(value)] ... ])(
 For each var(name) with a corresponding var(value), define an alias
 with that value.  A trailing space in var(value) causes the next word
-to be checked for alias substitution.  If the tt(-g) flag is present,
+to be checked for alias expansion.  If the tt(-g) flag is present,
 define a global alias; global aliases are expanded even if they do not
 occur in command position.
 
@@ -879,23 +879,50 @@
 cindex(parameters, setting)
 cindex(parameters, declaring)
 item(tt(typeset) [ {tt(PLUS())|tt(-)}tt(ALRUZafilrtuxm) [var(n)]] [ var(name)[tt(=)var(value)] ... ])(
-Set attributes and values for shell parameters.
-When invoked inside a function a new parameter is created which will be
-unset when the function completes.  The new parameter will not be
-exported unless tt(ALL_EXPORT) is set, in which case the parameter will be
-exported provided no parameter of that name already exists.
-The following attributes are valid:
+Set or display attributes and values for shell parameters.
+
+A parameter is created for each var(name) that does not already refer
+to one.  When inside a function, a new parameter is created for every
+var(name) (even those that already exist), and is unset again when the
+function completes.  See
+ifzman(`Local Parameters' in zmanref(zshparam))\
+ifnzman(noderef(Local Parameters))\
+.  Local parameters are not exported unless tt(ALL_EXPORT) is set, in
+which case the parameter is exported em(only) when var(name) does not
+already appear in the environment.
+
+For each nofill(var(name)tt(=)var(value)) assignment, the parameter
+var(name) set to var(value).  Note that arrays currently cannot be
+assigned in tt(typeset) expressions; scalars and integers only.
+
+For each remaining var(name) that refers to a parameter that is set,
+the name and value of the parameter are printed in the form of an
+assignment.  Nothing is printed for newly-created parameters.
+
+If no var(name) is present, the names and values of all parameters are
+printed.  In this case the attribute flags restrict the the display to
+only those parameters that have the specified attributes.  Using
+`tt(PLUS())' rather than `tt(-)' to introduce the flag causes the
+attribute to be turned off, and suppresses printing of the names and
+values.  If only the tt(-m) flag is given the arguments are taken as
+patterns (should be quoted) and all parameters (or functions with the
+tt(-f) flag) with matching names are printed.
+
+The following attribute flags may be specified:
 
 startitem()
 item(tt(-A))(
-Declare var(name) to be an em(A)ssociation parameter (also known as a hash).
+The names refer to associative array parameters; see
+ifzman(`Array Parameters' in zmanref(zshparam))\
+ifnzman(noderef(Array Parameters))\
+.
 )
 item(tt(-L))(
 Left justify and remove leading blanks from var(value).
 If var(n) is nonzero, it defines the width of the field;
 otherwise it is determined by the width of the value of the first
 assignment.
-When the parameter is printed, it is filled on the right with
+When the parameter is expanded, it is filled on the right with
 blanks or truncated if necessary to fit the field.
 Leading zeros are removed if the tt(-Z) flag is also set.
 )
@@ -904,13 +931,13 @@
 if defines the width of the field;
 otherwise it is determined by the width of the value of the first
 assignment.
-When the parameter is printed, the field is left filled with
+When the parameter is expanded, the field is left filled with
 blanks or truncated from the end.
 )
 item(tt(-U))(
-For arrays keep only the first element of each duplications. It can also be
-set for colon separated special parameters like tt(PATH) or tt(FIGNORE),
-etc.
+For arrays (but not for associative arrays), keep only the first
+occurrence of each duplicated value.  This may also be set for
+colon-separated special parameters like tt(PATH) or tt(FIGNORE), etc.
 )
 item(tt(-Z))(
 Right justify and fill with leading zeros if the first non-blank
@@ -920,8 +947,9 @@
 first assignment.
 )
 item(tt(-a))(
-On its own, this option produces a list of all array parameters.
-If any non-options are provided, the tt(typeset) command is silently ignored.
+The names refer to array parameters.  For historical reasons, scalar
+parameters are created even when this flag is specified, but the
+output is restricted to arrays (including associative arrays).
 )
 item(tt(-f))(
 The names refer to functions rather than parameters.  No assignments
@@ -933,12 +961,13 @@
 noderef(Functions).
 )
 item(tt(-i))(
-Use an internal integer representation.  If var(n) is nonzero
-it defines the output arithmetic base, otherwise it is determined by the first
-assignment.
+Use an internal integer representation.  If var(n) is nonzero it
+defines the output arithmetic base, otherwise it is determined by the
+first assignment.
 )
 item(tt(-l))(
-Convert to lower case.
+Convert the result to lower case whenever the parameter is expanded.
+The value is em(not) converted when assigned.
 )
 item(tt(-r))(
 The given var(name)s are marked readonly.
@@ -947,22 +976,14 @@
 Tags the named parameters.  Tags have no special meaning to the shell.
 )
 item(tt(-u))(
-Convert to upper case.
+Convert the result to upper case whenever the parameter is expanded.
+The value is em(not) converted when assigned.
 )
 item(tt(-x))(
 Mark for automatic export to the environment of subsequently
 executed commands.
 )
 enditem()
-
-Using `tt(PLUS())' rather than `tt(-)' causes these flags to be turned off.
-If no arguments are given but flags are specified,
-a list of named parameters which have these flags set is printed.
-Using `tt(PLUS())' instead of `tt(-)' keeps their values from being printed.
-If no arguments or options are given, the names and attributes
-of all parameters are printed. If only the tt(-m) flag is given the
-arguments are taken as patterns (should be quoted) and all parameters
-or functions (with the tt(-f) flag) with matching names are printed.
 )
 findex(ulimit)
 cindex(resource limits)
Index: Doc/Zsh/compat.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/compat.yo,v
retrieving revision 1.2
diff -u -r1.2 compat.yo
--- compat.yo	1998/06/20 04:47:20	1.2
+++ compat.yo	1998/12/16 05:38:31
@@ -32,9 +32,9 @@
 source tt(/etc/profile) followed by tt($HOME/.profile).  If the
 tt(ENV) environment variable is set on invocation, 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 the tt(PRIVILEGED) option
-also affects the execution of startup files.
+parameter expansion, command substitution, and arithmetic expansion
+before being interpreted as a pathname.  Note that the tt(PRIVILEGED)
+option also affects the execution of startup files.
 
 The following options are set if the shell is invoked as tt(sh) or
 tt(ksh):
Index: Doc/Zsh/expn.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/expn.yo,v
retrieving revision 1.12
diff -u -r1.12 expn.yo
--- expn.yo	1998/12/12 07:25:47	1.12
+++ expn.yo	1998/12/16 09:21:23
@@ -5,15 +5,15 @@
 The types of expansions performed are
 
 startlist()
-list(em(history expansion))
-list(em(alias expansion))
-list(em(process substitution))
-list(em(parameter expansion))
-list(em(command substitution))
-list(em(arithmetic expansion))
-list(em(brace expansion))
-list(em(filename expansion))
-list(em(filename generation))
+list(em(History Expansion))
+list(em(Alias Expansion))
+list(em(Process Substitution))
+list(em(Parameter Expansion))
+list(em(Command Substitution))
+list(em(Arithmetic Expansion))
+list(em(Brace Expansion))
+list(em(Filename Expansion))
+list(em(Filename Generation))
 endlist()
 
 Expansion is done in the above specified order in five steps.  The
@@ -29,8 +29,8 @@
 
 If the tt(SH_FILE_EXPANSION) option is set, the order of expansion is modified
 for compatibility with bf(sh) and bf(ksh).  em(Filename expansion)
-is performed immediately after em(alias substitution),
-preceding the set of five substitutions mentioned above.
+is performed immediately after em(alias expansion),
+preceding the set of five expansions mentioned above.
 startmenu()
 menu(History Expansion)
 menu(Process Substitution)
@@ -52,7 +52,7 @@
 Command lines are saved in the history list, the size of which
 is controlled by the tt(HISTSIZE)
 vindex(HISTSIZE, use of)
-variable.  The most recent command is retained in any case.
+parameter.  The most recent command is retained in any case.
 A history expansion begins with the first character of the
 tt(histchars) parameter which is `tt(!)'
 by default and may occur anywhere on the command line; history
@@ -175,8 +175,8 @@
 )
 item(tt(f))(
 (This and the following
-tt(F), tt(w) and tt(W) modifier only work with parameter and
-filename expansion.)
+tt(F), tt(w) and tt(W) modifier only work with parameter expansion and
+filename generation.)
 Repeats the immediately (without a colon) following modifier until the
 resulting word doesn't change any more.
 )
@@ -200,13 +200,13 @@
 Substitute var(r) for var(l) as described below.
 Unless preceded immediately by a tt(g), with no colon between,
 the substitution is done only for the
-first string that matches var(l).  For arrays and filename
-expansion, this applies to each word of the expanded text.
+first string that matches var(l).  For arrays and for filename
+generation, this applies to each word of the expanded text.
 )
 item(tt(&))(
 Repeat the previous tt(s) substitution.  Like tt(s), may be preceded
 immediately by a tt(g).  In variable expansion the tt(&) must appear
-inside braces, and in filename expansion it must be quoted with a
+inside braces, and in filename generation it must be quoted with a
 backslash.
 )
 enditem()
@@ -309,25 +309,27 @@
 ifnzman(\
 noderef(Parameters)
 )\
-for a description of parameters.
+for a description of parameters, including arrays, associative arrays,
+and subscript notation to access individual array elements.
+
 In the expansions discussed below that require a pattern, the form of
 the pattern is the same as that used for filename generation;
 see noderef(Filename Generation).  Note that this pattern, along with
-the replacement text of a substitution, is itself subject to
-parameter, command and arithmetic substitution.  In addition to the
-following operations, the file modifiers described in
+the replacement text of any substitutions, are themselves subject to
+parameter expansion, command substitution, and arithmetic expansion.
+In addition to the following operations, the file modifiers described in
 noderef(Modifiers) in noderef(History Expansion) can be
 applied:  for example, tt(${i:s/foo/bar/}) performs string
-substitution on the value of parameter tt($i).
+substitution on the expansion of parameter tt($i).
 
 startitem()
 item(tt(${)var(name)tt(}))(
 The value, if any, of the parameter var(name) is substituted.
-The braces are required if var(name) is followed by
+The braces are required if the expansion is to be followed by
 a letter, digit, or underscore that is not to be interpreted
-as part of its name.
+as part of var(name).
 
-If var(name) is an array parameter, then the values of each
+If var(name) is an array parameter, then the value of each
 element of var(name) is substituted, one element per word.
 Otherwise, the expansion results in one word only; no field
 splitting is done on the result unless the tt(SH_WORD_SPLIT)
@@ -342,10 +344,12 @@
 value; otherwise substitute var(word). If var(name) is
 missing, substitute var(word).
 )
-item(tt(${)var(name)tt(:=)var(word)tt(}))(
-If var(name) is unset or is null then
-set it to var(word); the value of the parameter is then
-substituted.
+xitem(tt(${)var(name)tt(:=)var(word)tt(}))
+item(tt(${)var(name)tt(::=)var(word)tt(}))(
+In the first form, if var(name) is unset or is null then
+set it to var(word); in the second form, unconditionally
+set var(name) to var(word).  In both forms, the value of
+the parameter is then substituted.
 )
 item(tt(${)var(name)tt(:?)var(word)tt(}))(
 If var(name) is set and is non-null, then substitute
@@ -360,13 +364,14 @@
 
 If the colon is omitted from one of the above expressions
 containing a colon, then the shell only checks whether
-var(name) is set or not, not whether it is null.
+var(name) is set, not whether its value is null.
+
+In the following expressions, when var(name) is an array and
+the substitution is not quoted, or if the tt((@)) flag or the
+`var(name)tt([@])' syntax is used, matching and replacement is
+performed on each array element separately.
 
 startitem()
-item(tt(${)var(name)tt(::=)var(word)tt(}))(
-Set var(name) to var(word); the value of the parameter is then
-substituted.
-)
 xitem(tt(${)var(name)tt(#)var(pattern)tt(}))
 item(tt(${)var(name)tt(##)var(pattern)tt(}))(
 If the var(pattern) matches the beginning of the value of
@@ -375,9 +380,7 @@
 substitute the value of var(name).  In the first
 form, the smallest matching pattern is preferred;
 in the second form, the largest matching pattern is
-preferred. If var(name) is an array and the substitution
-is not quoted or the tt((@)) flag or the `var(name)tt([@])' syntax
-is used, matching is performed on each array elements separately.
+preferred.
 )
 xitem(tt(${)var(name)tt(%)var(pattern)tt(}))
 item(tt(${)var(name)tt(%%)var(pattern)tt(}))(
@@ -387,43 +390,38 @@
 substitute the value of var(name).  In the first
 form, the smallest matching pattern is preferred;
 in the second form, the largest matching pattern is
-preferred. If var(name) is an array and the substitution
-is not quoted or the tt((@)) flag or the `var(name)tt([@])' syntax
-is used, matching is performed on each array elements separately.
+preferred.
 )
 item(tt(${)var(name)tt(:#)var(pattern)tt(}))(
 If the var(pattern) matches the value of var(name), then substitute
 the empty string; otherwise, just substitute the value of var(name).
-If var(name) is an array and the substitution
-is not quoted or the tt((@)) flag or the `var(name)tt([@])' syntax
-is used, matching is performed on each array elements separately, and
-the matched array elements are removed (use the tt((M)) flag to
+If var(name) is an array
+the matching array elements are removed (use the tt((M)) flag to
 remove the non-matched elements).
 )
 xitem(tt(${)var(name)tt(/)var(pattern)tt(/)var(repl)tt(}))
 item(tt(${)var(name)tt(//)var(pattern)tt(/)var(repl)tt(}))(
-Substitute the longest possible match of var(pattern) in the value of
-variable var(name) with the string var(repl).  The first form
-substitutes just the first occurrence, the second all occurrences.
+Replace by string var(repl), the longest possible match of
+var(pattern) in the expansion of parameter var(name).  The first form
+replaces just the first occurrence, the second form all occurrences.
 The var(pattern) may begin with a var(#), in which case the
 var(pattern) must match at the start of the string, or var(%), in
 which case it must match at the end of the string.  The var(repl) may
 be an empty string, in which case the final tt(/) may also be omitted.
 To quote the final tt(/) in other cases it should be preceded by two
 backslashes (i.e., a quoted backslash); this is not necessary if the
-tt(/) occurs inside a substituted parameter.  Substitution of an array
-is as described for tt(#) and tt(%) above.
+tt(/) occurs inside a substituted parameter.
 
 The first tt(/) may be preceded by a tt(:), in which case the match
 will only succeed if it matches the entire word.  Note also the
-effect of the tt(I) and tt(S) parameter expansion flags below:  the
-flags tt(M), tt(R), tt(B), tt(E) and tt(N) are not useful, however.
+effect of the tt(I) and tt(S) parameter expansion flags below; however,
+the flags tt(M), tt(R), tt(B), tt(E) and tt(N) are not useful.
 
 For example,
 
-nofill(tt(foo="twinkle twinkle little star" sub="t*e" rep="spy"))
-nofill(tt(print ${foo//${~sub}/$rep}))
-nofill(tt(print ${(S)foo//${~sub}/$rep}))
+nofill(tt(foo="twinkle twinkle little star" sub="t*e" rep="spy")
+tt(print ${foo//${~sub}/$rep})
+tt(print ${(S)foo//${~sub}/$rep}))
 
 Here, the tt(~) ensures that the text of tt($sub) is treated as a
 pattern rather than a plain string.  In the first case, the longest
@@ -436,6 +434,8 @@
 the length in characters of the result instead of
 the result itself.  If var(spec) is an array expression,
 substitute the number of elements of the result.
+Note that tt(^), tt(=), and tt(~), below, must appear
+to the left of tt(#) when these forms are combined.
 )
 item(tt(${^)var(spec)tt(}))(
 pindex(RC_EXPAND_PARAM, use of)
@@ -465,24 +465,27 @@
 Turn on the tt(SH_WORD_SPLIT) option for the
 evaluation of var(spec); if the `tt(=)' is doubled, turn it off.
 vindex(IFS, use of)
-When this option is set, parameter values are split into
-separate words using tt(IFS) as a delimiter
-before substitution.
+When this option is set, parameter expansions are split into
+separate words before substitution, using tt(IFS) as a delimiter.
 This is done by default in most other shells.
+
+Note that splitting is applied to var(word) in the assignment forms
+of var(spec) em(before) the assignment to var(name) is performed.
+This affects the result of array assignments with the tt(A) flag.
 )
 item(tt(${~)var(spec)tt(}))(
 pindex(GLOB_SUBST)
 Turn on the tt(GLOB_SUBST) option for the evaluation of
 var(spec); if the `tt(~)' is doubled, turn it off.  When this option is
 set, any pattern characters resulting
-from the substitution become eligible for file expansion and filename
+from parameter expansion are eligible for filename expansion and filename
 generation.
 )
 enditem()
 
 If a tt(${)...tt(}) type parameter expression or a
 tt($LPAR())...tt(RPAR()) type command substitution is used in place of
-var(name) above, it is substituted first and the result is used as if
+var(name) above, it is expanded first and the result is used as if
 it were the value of var(name).  Thus it is
 possible to perform nested operations:  tt(${${foo#head}%tail})
 substitues the value of tt($foo) with both tt(head) and tt(tail)
@@ -491,7 +494,7 @@
 subsect(Parameter Expansion Flags)
 cindex(parameter expansion flags)
 cindex(flags, parameter expansion)
-cindex(expansion, parameter, flags)
+cindex(substitution, parameter, flags)
 If the opening brace is directly followed by an opening parenthesis,
 the string up to the matching closing parenthesis will be taken as a
 list of flags.  Where arguments are valid, any character, or the
@@ -501,9 +504,14 @@
 
 startitem()
 item(tt(A))(
-Create an array parameter with
+Create an array parameter with tt(${)...tt(=)...tt(}),
 tt(${)...tt(:=)...tt(}) or tt(${)...tt(::=)...tt(}).
-Assignment is made before sorting or padding.
+If this flag is repeated (as in tt(AA)), create an associative
+array parameter.  Assignment is made before sorting or padding.
+The var(name) part may be a subscripted range for ordinary
+arrays; the var(word) part em(must) be converted to an array, for
+example by using tt(${(AA)=)...tt(}) to activate word splitting,
+when creating an associative array.
 )
 item(tt(@))(
 In double quotes, array elements are put into separate words.
@@ -531,7 +539,9 @@
 Convert all letters in the result to upper case.
 )
 item(tt(C))(
-Capitalize the resulting words.
+Capitalize the resulting words.  `Words' in this case refers to sequences
+of alphanumeric characters separated by non-alphanumerics, em(not) to words
+that result from field splitting.
 )
 item(tt(c))(
 With tt(${#)var(name)tt(}), count the total number of characters in an array,
@@ -545,9 +555,22 @@
 Similar to tt(w) with the difference that empty words between
 repeated delimiters are also counted.
 )
+item(tt(k))(
+If var(name) refers to an associative array, substitute the em(keys)
+(element names) rather than the values of the elements.  Used with
+subscripts (including ordinary arrays), force indices or keys to be
+substituted even if the subscript form refers to values.  However,
+this flag may not be combined with subscript ranges.
+)
+item(tt(v))(
+Used with tt(k), substitute (as two consecutive words) both the key
+and the value of each associative array element.  Used with subscripts,
+force values to be substituted even if the subscript form refers to
+indices or keys.
+)
 item(tt(p))(
 Recognize the same escape sequences as the tt(print) builtin
-in string arguments to subsequent flags.
+in string arguments to any of the flags described below.
 )
 item(tt(l:)var(expr)tt(::)var(string1)tt(::)var(string2)tt(:))(
 Pad the resulting words on the left.  Each word will be truncated if
@@ -579,9 +602,13 @@
 Split the result of the expansion to lines. This is a shorthand
 for `tt(ps:\n:)'.
 )
+enditem()
+
+The following flags are meaningful with the tt(${)...tt(#)...tt(}),
+tt(${)...tt(%)...tt(}), or tt(${)...tt(/)...tt(}) forms.
+
+startitem()
 item(tt(S))(
-(This and all remaining flags are used with the tt(${)...tt(#)...tt(}) or
-tt(${)...tt(%)...tt(}) forms.)
 Search substrings as well as beginnings or ends; with tt(#) start
 from the beginning and with tt(%) start from the end of the string.
 With substitution via tt(${)...tt(/)...tt(}) or
Index: Doc/Zsh/grammar.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/grammar.yo,v
retrieving revision 1.4
diff -u -r1.4 grammar.yo
--- grammar.yo	1998/10/30 17:52:39	1.4
+++ grammar.yo	1998/12/16 05:38:29
@@ -307,9 +307,9 @@
 An alias is defined using the tt(alias) builtin; global aliases
 may be defined using the tt(-g) option to that builtin.
 
-Alias substitution is done on the shell input before any
-other substitution except history substitution.  Therefore,
-if an alias is defined for the word tt(foo), alias substitution
+Alias expansion is done on the shell input before any
+other expansion except history expansion.  Therefore,
+if an alias is defined for the word tt(foo), alias expansion
 may be avoided by quoting part of the word, e.g. tt(\foo).
 But there is nothing to prevent an alias being defined
 for tt(\foo) as well.
Index: Doc/Zsh/options.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/options.yo,v
retrieving revision 1.4
diff -u -r1.4 options.yo
--- options.yo	1998/10/30 17:52:41	1.4
+++ options.yo	1998/12/16 05:51:59
@@ -139,7 +139,7 @@
 cindex(history, enable substitution)
 cindex(enable history substitution)
 item(tt(BANG_HIST) (tt(PLUS()K)))(
-Perform textual history substitution, bf(csh)-style,
+Perform textual history expansion, bf(csh)-style,
 treating the character `tt(!)' specially.
 )
 pindex(BARE_GLOB_QUAL)
@@ -263,9 +263,9 @@
 Overrides tt(NULL_GLOB).
 )
 pindex(EQUALS)
-cindex(filename substitution, =)
+cindex(filename expansion, =)
 item(tt(EQUALS))(
-Perform tt(=) filename substitution.
+Perform tt(=) filename expansion.
 (See noderef(Filename Expansion).)
 )
 pindex(ERR_EXIT)
@@ -344,7 +344,7 @@
 )
 pindex(GLOB_SUBST)
 item(tt(GLOB_SUBST))(
-Treat any characters resulting from parameter substitution as being
+Treat any characters resulting from parameter expansion as being
 eligible for file expansion and filename generation, and any
 characters resulting from command substitution as being eligible for
 filename generation.
@@ -412,9 +412,9 @@
 pindex(HIST_VERIFY)
 cindex(history, verifying substitution)
 item(tt(HIST_VERIFY))(
-Whenever the user enters a line with history substitution,
+Whenever the user enters a line with history expansion,
 don't execute the line directly; instead, perform
-history substitution and reload the line into the editing buffer.
+history expansion and reload the line into the editing buffer.
 )
 pindex(HUP)
 cindex(jobs, HUP)
Index: Doc/Zsh/params.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/params.yo,v
retrieving revision 1.4
diff -u -r1.4 params.yo
--- params.yo	1998/10/30 17:52:41	1.4
+++ params.yo	1998/12/16 07:55:47
@@ -7,7 +7,8 @@
 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, or an array.
+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.
 findex(typeset, use of)
@@ -17,10 +18,12 @@
 
 nofill(var(name)tt(=)var(value))
 
-If the integer attribute, tt(-i), is set for var(name),
-the var(value) is subject to arithmetic evaluation.
+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.
 
-In the parameter lists, the mark `<S>' indicates that the parameter is special.
+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
 initialises in tt(sh) or tt(ksh) emulation mode.
@@ -55,6 +58,15 @@
 
 nofill(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:
+
+nofill(var(name)tt(=LPAR())var(key) var(value) ...tt(RPAR()))
+
+Every var(key) must have a var(value) in this case.
+
 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
@@ -64,6 +76,9 @@
 tt(KSH_ARRAYS) option is set when 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).
+
 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.
@@ -73,6 +88,7 @@
 A subscript of the form `tt([)var(exp1)tt(,)var(exp2)tt(])'
 selects all elements in the range var(exp1) to var(exp2),
 inclusive.
+(Associative arrays are unordered, and so do not support ranges.)
 If one of the subscripts evaluates to a negative number,
 say tt(-)var(n), then the var(n)th element from the end
 of the array is used.  Thus `tt($foo[-3])' is the third element
@@ -90,7 +106,9 @@
 work, the subscript otherwise not being treated specially.
 
 If a subscript is used on the left side of an assignment the selected
-range is replaced by the expression on the right side.
+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.
 
 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
@@ -123,21 +141,27 @@
 parameter is an array, if it is a scalar, or if it is a scalar and the
 `tt(w)' flag is given, respectively); note that this is like giving a
 number: `tt($foo[(r))var(??)tt(,3])' and `tt($foo[(r))var(??)tt(,(r)f*])' work.
+If the parameter is an associative array, only the value part of each pair
+is compared to the pattern.
 )
 item(tt(R))(
-like `tt(r)', but gives the last match.
+like `tt(r)', but gives the last match.  For associative arrays, gives
+all possible matches.
 )
 item(tt(i))(
 like `tt(r)', but gives the index of the match instead; this may not
-be combined with a second argument.
+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.
 )
 item(tt(I))(
-like `tt(i), but gives the index of the last match.
+like `tt(i), but gives the index of the last match, or all possible
+matching keys in an associative array.
 )
 item(tt(n:)var(expr)tt(:))(
 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)).
+var(n)).  This flag is ignored when the array is associative.
 )
 enditem()
 texinode(Positional Parameters)(Parameters Set By The Shell)(Array Parameters)(Parameters)
@@ -417,7 +441,7 @@
 item(tt(histchars) <S>)(
 Three characters used by the shell's history and lexical analysis
 mechanism.  The first character signals the start of a history
-substitution (default `tt(!)').  The second character signals the
+expansion (default `tt(!)').  The second character signals the
 start of a quick history substitution (default `tt(^)').  The third
 character is the comment character (default `tt(#)').
 )
@@ -442,7 +466,7 @@
 item(tt(IFS) <S>)(
 Internal field separators (by default space, tab, newline and NUL), that
 are used to separate words which result from
-command or parameter substitution and words read by
+command or parameter expansion and words read by
 the tt(read) builtin.  Any characters from the set space, tab and
 newline that appear in the IFS are called em(IFS white space).
 One or more IFS white space characters or one non-IFS white space
@@ -518,7 +542,7 @@
 new mail.  Each filename can be followed by a `tt(?)' and a
 message that will be printed.  The message will undergo
 parameter expansion, command substitution and arithmetic
-substitution with the variable tt($_) defined as the name
+expansion with the variable tt($_) defined as the name
 of the file that has changed.  The default message is
 `tt(You have new mail)'.  If an element is a directory
 instead of a file the shell will recursively check every
Index: Doc/Zsh/redirect.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/redirect.yo,v
retrieving revision 1.3
diff -u -r1.3 redirect.yo
--- redirect.yo	1998/06/14 23:13:25	1.3
+++ redirect.yo	1998/12/16 05:38:28
@@ -16,7 +16,7 @@
 
 The following may appear anywhere in a simple command
 or may precede or follow a complex command.
-Substitution occurs before var(word) or var(digit)
+Expansion occurs before var(word) or var(digit)
 is used except as noted below.
 If the result of substitution on var(word)
 produces more than one filename,
@@ -57,7 +57,7 @@
 item(tt(<<)[tt(-)] var(word))(
 The shell input is read up to a line that is the same as
 var(word), or to an end-of-file.
-No parameter substitution, command substitution or
+No parameter expansion, command substitution or
 filename generation is performed on var(word).
 The resulting document, called a
 em(here-document), becomes the standard input.


-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com