Changes from 4.1 which need to be backported

3 files changed, 747 insertions, 209 deletions

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index c7866120d..88dd45594 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -23,6 +23,12 @@ See ifzman(the section `The ARG2 Module' in zmanref(zshmodules))\
 ifnzman(noderef(The ARG2 Module)).
 )\
 )\
+def(zlecmd)(1)(\
+item(tt(ARG1))(
+See ifzman(the section `Zle Builtins' in zmanref(zshzle))\
+ifnzman(noderef(Zle Builtins)).
+)\
+)\
 startitem()
 prefix(-)
 findex(.)
@@ -119,7 +125,7 @@ item(var(job) ... tt(&))(
 Put each specified var(job) in the background,
 or the current job if none is specified.
 )
-module(bindkey)(zsh/zle)
+zlecmd(bindkey)
 findex(break)
 cindex(exiting loops)
 cindex(loops, exiting)
@@ -649,8 +655,8 @@ tt(-R); all other arguments and options are printed.
 item(tt(-b))(
 Recognize all the escape sequences defined for the tt(bindkey) command,
 see 
-ifzman(zmanref(zshmodules))\
-ifnzman(noderef(The zsh/zle Module))\
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zle Builtins))\
 .
 )
 item(tt(-m))(
@@ -1303,7 +1309,7 @@ If the tt(-m) flag is given the arguments are taken as patterns
 (which should be quoted to preserve them from being interpreted as glob
 patterns), and all options with names matching these patterns are unset.
 )
-module(vared)(zsh/zle)
+zlecmd(vared)
 findex(wait)
 cindex(waiting for jobs)
 cindex(jobs, waiting for)
@@ -1487,7 +1493,7 @@ ifzman(enditem())
 )
 module(zformat)(zsh/zutil)
 module(zftp)(zsh/zftp)
-module(zle)(zsh/zle)
+zlecmd(zle)
 findex(zmodload)
 cindex(modules, loading)
 cindex(loading modules)
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index ee554e6c1..a4631f37b 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -1,4 +1,4 @@
-texinode(Expansion)(Parameters)(Restricted Shell)(Top)
+texinode(Expansion)(Parameters)(Prompt Expansion)(Top)
 chapter(Expansion)
 cindex(expansion)
 sect(Description)
@@ -49,36 +49,91 @@ cindex(expansion, history)
 History expansion allows you to use words from previous command
 lines in the command line you are typing.  This simplifies spelling
 corrections and the repetition of complicated commands or arguments.
-Command lines are saved in the history list, the size of which
-is controlled by the tt(HISTSIZE)
 vindex(HISTSIZE, use of)
-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
-expansions do not nest.  The `tt(!)' can be escaped with `tt(\)'
-or can be enclosed between a pair of single quotes (tt('')) to suppress
-its special meaning. Double quotes will em(not) work for this.
-
-Input lines containing history expansions are echoed on the
-terminal after being expanded, but before any other
-expansions take place or the command gets executed.
+Immediately before execution, each command is saved in the history list,
+the size of which is controlled by the tt(HISTSIZE) parameter.  The one
+most recent command is always retained in any case.  Each saved command in
+the history list is called a history em(event) and is assigned a number,
+beginning with 1 (one) when the shell starts up.  The history number that
+you may see in your prompt (see noderef(Prompt Expansion)) is the number
+that is to be assigned to the em(next) command.
+
 startmenu()
+menu(Overview)
 menu(Event Designators)
 menu(Word Designators)
 menu(Modifiers)
 endmenu()
-texinode(Event Designators)(Word Designators)()(History Expansion)
+texinode(Overview)(Event Designators)()(History Expansion)
+subsect(Overview)
+vindex(histchars, use of)
+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 expansions do not nest.  The `tt(!)' can be escaped
+with `tt(\)' or can be enclosed between a pair of single quotes (tt(''))
+to suppress its special meaning.  Double quotes will em(not) work for
+this.  Following this history character is an optional event designator
+(ifzman(see )noderef(Event Designators)) and then an optional word
+designator (noderef(Word Designators)); if neither of these designators is
+present, no history expansion occurs.
+
+Input lines containing history expansions are echoed after being expanded,
+but before any other expansions take place and before the command is
+executed.  It is this expanded form that is recorded as the history event
+for later references.
+
+By default, a history reference with no event designator refers to the
+same event as any preceding history reference on that command line; if it
+is the only history reference in a command, it refers to the previous
+command.
+pindex(CSH_JUNKIE_HISTORY, use of)
+However, if the option tt(CSH_JUNKIE_HISTORY) is set, then every history
+reference with no event specification em(always) refers to the previous
+command.
+
+For example, `tt(!)' is the event designator for the previous command, so
+`tt(!!:1)' always refers to the first word of the previous command, and
+`tt(!!$)' always refers to the last word of the previous command.  With
+tt(CSH_JUNKIE_HISTORY) set, then `tt(!:1)' and `tt(!$)' function in the
+same manner as `tt(!!:1)' and `tt(!!$)', respectively.  Conversely, if
+tt(CSH_JUNKIE_HISTORY) is unset, then `tt(!:1)' and `tt(!$)' refer to the
+first and last words, respectively, of the same event referenced by the
+nearest other history reference preceding them on the current command
+line, or to the previous command if there is no preceding reference.
+
+The character sequence `tt(^)var(foo)tt(^)var(bar)' (where `tt(^)' is
+actually the second character of the tt(histchars) parameter)
+repeats the last command, replacing the string var(foo) with var(bar).
+More precisely, the sequence `tt(^)var(foo)tt(^)var(bar)tt(^)' is
+synonymous with `tt(!!:s)tt(^)var(foo)tt(^)var(bar)tt(^)', hence other
+modifiers (see noderef(Modifiers)) may follow the final `tt(^)'.
+
+If the shell encounters the character sequence `tt(!")'
+in the input, the history mechanism is temporarily disabled until
+the current list (see
+ifzman(zmanref(zshmisc))\
+ifnzman(noderef(Shell Grammar))\
+) is fully parsed.  The `tt(!")' is removed from the input, and any
+subsequent `tt(!)' characters have no special significance.
+
+findex(fc, use of)
+A less convenient but more comprehensible form of command history support
+is provided by the tt(fc) builtin.
+texinode(Event Designators)(Word Designators)(Overview)(History Expansion)
 subsect(Event Designators)
 cindex(history event designators)
 cindex(event designators, history)
-An event designator is a reference to a command-line entry in
-the history list.
+An event designator is a reference to a command-line entry in the history
+list.  In the list below, remember that the initial tt(`!') in each item
+may be changed to another character by setting the tt(histchars)
+parameter.
 
 startitem()
 item(tt(!))(
 Start a history expansion, except when followed by a blank, newline,
-`tt(=)' or `tt(LPAR())'.
+`tt(=)' or `tt(LPAR())'.  If followed immediately by a word designator
+(ifzman(see )noderef(Word Designators)), this forms a history reference
+with no event designator (ifzman(see )noderef(Overview)).
 )
 item(tt(!!))(
 Refer to the previous command.
@@ -95,7 +150,9 @@ item(tt(!)var(str))(
 Refer to the most recent command starting with var(str).
 )
 item(tt(!?)var(str)[tt(?)])(
-Refer to the most recent command containing var(str).
+Refer to the most recent command containing var(str).  The trailing
+`tt(?)' is necessary if this reference is to be followed by a modifier or
+followed by any text that is not to be considered part of var(str).
 )
 item(tt(!#))(
 Refer to the current command line typed in so far.  The line is
@@ -110,10 +167,10 @@ texinode(Word Designators)(Modifiers)(Event Designators)(History Expansion)
 subsect(Word Designators)
 cindex(history word designators)
 cindex(word designators, history)
-A word designator indicates which word or words of a given command line will
-be included in a history reference.  A `tt(:)'
+A word designator indicates which word or words of a given command line are
+to be included in a history reference.  A `tt(:)' usually
 separates the event specification from the word designator.
-It can be omitted if the word designator begins with a
+It may be omitted only if the word designator begins with a
 `tt(^)', `tt($)', `tt(*)', `tt(-)' or `tt(%)'.
 Word designators include:
 
@@ -129,9 +186,9 @@ sitem(var(x)tt(*))(Abbreviates `var(x)tt(-$)'.)
 sitem(var(x)tt(-))(Like `var(x)tt(*)' but omitting word tt($).)
 endsitem()
 
-Note that a `tt(%)' word designator will only work when used as
-`tt(!%)', `tt(!:%)' or `tt(!?)var(str)tt(?:%)',
-and only when used after a tt(!?) expansion.  Anything else will result
+Note that a `tt(%)' word designator works only when used in one of
+`tt(!%)', `tt(!:%)' or `tt(!?)var(str)tt(?:%)', and only when used after a
+tt(!?) expansion (possibly in an earlier command).  Anything else results
 in an error, although the error may not be the most obvious one.
 texinode(Modifiers)()(Word Designators)(History Expansion)
 subsect(Modifiers)
@@ -145,16 +202,19 @@ noted.
 
 startitem()
 item(tt(h))(
-Remove a trailing pathname component, leaving the head.
+Remove a trailing pathname component, leaving the head.  This works
+like `tt(dirname)'.
 )
 item(tt(r))(
-Remove a trailing suffix of the form `tt(.)var(xxx)', leaving the basename.
+Remove a filename extension of the form `tt(.)var(xxx)', leaving
+the root name.
 )
 item(tt(e))(
-Remove all but the suffix.
+Remove all but the extension.
 )
 item(tt(t))(
-Remove all leading pathname components, leaving the tail.
+Remove all leading pathname components, leaving the tail.  This works
+like `tt(basename)'.
 )
 item(tt(p))(
 Print the new command but do not execute it.  Only works with history
@@ -162,15 +222,16 @@ expansion.
 )
 item(tt(q))(
 Quote the substituted words, escaping further substitutions.  Works
-with history expansion and parameter expansion, though in the second
-case it is only useful if the resulting text is to be re-evaluated
-such as by tt(eval).
+with history expansion and parameter expansion, though for parameters
+it is only useful if the resulting text is to be re-evaluated such as
+by tt(eval).
 )
 item(tt(Q))(
 Remove one level of quotes from the substituted words.
 )
 item(tt(x))(
-Like tt(q), but break into words at each blank.
+Like tt(q), but break into words at each blank.  Does not work with
+parameter expansion.
 )
 item(tt(l))(
 Convert the words to all lowercase.
@@ -178,30 +239,6 @@ Convert the words to all lowercase.
 item(tt(u))(
 Convert the words to all uppercase.
 )
-item(tt(f))(
-(This and the following
-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.
-)
-item(tt(F:)var(expr)tt(:))(
-Like tt(f), but repeats only var(n) times if the expression
-var(expr) evaluates to var(n).  Any character can be used instead of
-the `tt(:)'; if `tt(LPAR())', `tt([)', or `tt({)'
-is used as the opening delimiter,
-the closing delimiter should be 'tt(RPAR())', `tt(])', or `tt(})',
-respectively.
-)
-item(tt(w))(
-Makes the immediately following modifier work on each word in the
-string.
-)
-item(tt(W:)var(sep)tt(:))(
-Like tt(w) but words are considered to be the parts of the string
-that are separated by var(sep). Any character can be used instead of
-the `tt(:)'; opening parentheses are handled specially, see above.
-)
 item(tt(s/)var(l)tt(/)var(r)[tt(/)])(
 Substitute var(r) for var(l) as described below.
 Unless preceded immediately by a tt(g), with no colon between,
@@ -230,43 +267,33 @@ the rightmost `tt(?)' in a context scan can similarly be omitted.
 Note the same record of the last var(l) and var(r) is maintained
 across all forms of expansion.
 
-By default, a history reference with no event specification refers to the same
-line as the previous history reference on that command line, unless it is the
-first history reference in a command.  In that case, a history reference
-with no event specification always refers to the previous command.  However,
-if the option tt(CSH_JUNKIE_HISTORY) is set,
-pindex(CSH_JUNKIE_HISTORY, use of)
-then history reference with no
-event specification will em(always) refer to the previous command.
-
-For example, `tt(!!:1)'
-will always refer to the first word of the previous command, and `tt(!!$)'
-will always refer to the last word of the previous command.  And with
-tt(CSH_JUNKIE_HISTORY) set, then `tt(!:1)' and `tt(!$)'
-will function in the same manner as `tt(!!:1)' and `tt(!!$)',
-respectively.  However, if tt(CSH_JUNKIE_HISTORY) is unset, then
-`tt(!:1)' and `tt(!$)'
-will refer to the first and last words respectively, of the last command
-referenced on the current command line.  However, if they are the first history
-reference on the command line, then they refer to the previous command.
+The following tt(f), tt(F), tt(w) and tt(W) modifiers work only with
+parameter expansion and filename generation.  They are listed here to
+provide a single point of reference for all modifiers.
 
-The character sequence `tt(^)var(foo)tt(^)var(bar)' (where `tt(^)' is
-actually the second charcter of the tt(histchars) parameter)
-repeats the last command, replacing the string var(foo) with var(bar).
-More precisely, the sequence `tt(^)var(foo)tt(^)var(bar)tt(^)' is
-synonymous with `tt(!!:s)tt(^)var(foo)tt(^)var(bar)tt(^)', hence other
-modifiers may follow the final `tt(^)'.
-
-If the shell encounters the character sequence `tt(!")'
-in the input, the history mechanism is temporarily disabled until
-the current list is fully parsed.  The `tt(!")'
-is removed from the input, and any subsequent `tt(!)'
-characters have no special significance.
-
-A less convenient but more comprehensible
-form of command history support
-is provided by the tt(fc) builtin.
-findex(fc, use of)
+startitem()
+item(tt(f))(
+Repeats the immediately (without a colon) following modifier until the
+resulting word doesn't change any more.
+)
+item(tt(F:)var(expr)tt(:))(
+Like tt(f), but repeats only var(n) times if the expression
+var(expr) evaluates to var(n).  Any character can be used instead of
+the `tt(:)'; if `tt(LPAR())', `tt([)', or `tt({)'
+is used as the opening delimiter,
+the closing delimiter should be 'tt(RPAR())', `tt(])', or `tt(})',
+respectively.
+)
+item(tt(w))(
+Makes the immediately following modifier work on each word in the
+string.
+)
+item(tt(W:)var(sep)tt(:))(
+Like tt(w) but words are considered to be the parts of the string
+that are separated by var(sep). Any character can be used instead of
+the `tt(:)'; opening parentheses are handled specially, see above.
+)
+enditem()
 texinode(Process Substitution)(Parameter Expansion)(History Expansion)(Expansion)
 sect(Process Substitution)
 cindex(process substitution)
@@ -276,14 +303,14 @@ Each command argument of the form
 `tt(>LPAR())var(list)tt(RPAR())' or
 `tt(=LPAR())var(list)tt(RPAR())'
 is subject to process substitution.
-In the case of the tt(<) or tt(>) forms, the shell will run process
-var(list) asynchronously, connected to a named pipe (FIFO).
-The name of this pipe will become the argument to the command.
-If the form with tt(>)
-is selected then writing on this file will provide input for var(list).
-If tt(<) is used, then the file passed as an argument will
-be a named pipe connected to the output of the var(list) process.
-For example,
+In the case of the tt(<) or tt(>) forms, the shell runs process
+var(list) asynchronously.  If the system supports the tt(/dev/fd)
+mechanism, the command argument is the name of the device file
+corresponding to a file descriptor; otherwise, if the system supports named
+pipes (FIFOs), the command argument will be a named pipe.  If the form with
+tt(>) is selected then writing on this special file will provide input for
+var(list).  If tt(<) is used, then the file passed as an argument will
+be connected to the output of the var(list) process.  For example,
 
 nofill(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR() |
 tee >LPAR())var(process1)tt(RPAR() >LPAR())var(process2)tt(RPAR() >/dev/null))
@@ -291,9 +318,19 @@ tee >LPAR())var(process1)tt(RPAR() >LPAR())var(process2)tt(RPAR() >/dev/null))
 cuts fields 1 and 3 from the files var(file1) and var(file2) respectively,
 pastes the results together, and sends it to the processes
 var(process1) and var(process2).
-Note that the file, which is passed as an argument to the command,
-is a system pipe, so programs that expect to lseek (see manref(lseek)(2))
-on the file will not work.
+
+Both the tt(/dev/fd) and the named pipe implementation have drawbacks.  In
+the former case, some programmes may automatically close the file
+descriptor in question before examining the file on the command line,
+particularly if this is necessary for security reasons such as when the
+programme is running setuid.  In the second case,  if the
+programme does not actually open the file the subshell attempting to read
+from or write to the pipe will (in a typical implementation, different
+operating systems may have different behaviour) block for ever and have to
+be killed explicitly.  In both cases, the shell actually supplies the
+information using a pipe, so that programmes that expect to lseek
+(see manref(lseek)(2)) on the file will not work.
+
 Also note that the previous example can be more compactly and
 efficiently written (provided the tt(MULTIOS) option is set) as:
 
@@ -422,13 +459,21 @@ item(tt(${)var(name)tt(//)var(pattern)tt(/)var(repl)tt(}))(
 Replace the longest possible match of var(pattern) in the expansion of
 parameter var(name) by string var(repl).  The first form
 replaces just the first occurrence, the second form all occurrences.
+Both var(pattern) and var(repl) are subject to double-quoted substitution,
+so that expressions like tt(${name/$opat/$npat}) will work, but note the
+usual rule that pattern characters in tt($opat) are not treated specially
+unless either the option tt(GLOB_SUBST) is set, or tt($opat) is instead
+substituted as tt(${~opat}).
+
 The var(pattern) may begin with a `tt(#)', in which case the
 var(pattern) must match at the start of the string, or `tt(%)', 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.
+`tt(/)' occurs inside a substituted parameter.  Note also that the `tt(#)'
+and `tt(%)' are not active if they occur inside a substituted parameter,
+even at the start.
 
 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
@@ -511,11 +556,15 @@ possible to perform nested operations:  tt(${${foo#head}%tail})
 substitutes the value of tt($foo) with both `tt(head)' and `tt(tail)'
 deleted.  The form with tt($LPAR())...tt(RPAR()) is often useful in
 combination with the flags described next; see the examples below.
+Each var(name) or nested tt(${)...tt(}) in a parameter expansion may
+also be followed by a subscript expression as described in
+ifzman(em(Array Parameters) in zmanref(zshparam))\
+ifnzman(noderef(Array Parameters)).
 
-Note that double quotes may appear around nested substitutions, in which
+Note that double quotes may appear around nested expressions, in which
 case only the part inside is treated as quoted; for example,
 tt(${(f)"$(foo)"}) quotes the result of tt($(foo)), but the flag `tt((f))'
-(see below) is applied using the rules for unquoted substitutions.  Note
+(see below) is applied using the rules for unquoted expansions.  Note
 further that quotes are themselves nested in this context; for example, in
 tt("${(@f)"$(foo)"}"), there are two sets of quotes, one surrounding the
 whole expression, the other (redundant) surrounding the tt($(foo)) as
@@ -534,19 +583,19 @@ in place of the colon as delimiters.  The following flags are supported:
 
 startitem()
 item(tt(A))(
-Create an array parameter with tt(${)...tt(=)...tt(}),
-tt(${)...tt(:=)...tt(}) or tt(${)...tt(::=)...tt(}).
-If this flag is repeated (as in tt(AA)), create an associative
+Create an array parameter with `tt(${)...tt(=)...tt(})',
+`tt(${)...tt(:=)...tt(})' or `tt(${)...tt(::=)...tt(})'.
+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)=)var(name)tt(=)...tt(}) to activate word
+example by using `tt(${(AA)=)var(name)tt(=)...tt(})' to activate word
 splitting, when creating an associative array.
 )
 item(tt(@))(
 In double quotes, array elements are put into separate words.
-E.g., tt("${(@)foo}") is equivalent to tt("${foo[@]}") and
-tt("${(@)foo[1,2]}") is the same as tt("$foo[1]" "$foo[2]").
+E.g., `tt("${(@)foo}")' is equivalent to `tt("${foo[@]}")' and
+`tt("${(@)foo[1,2]}")' is the same as `tt("$foo[1]" "$foo[2]")'.
 )
 item(tt(e))(
 Perform em(parameter expansion), em(command substitution) and
@@ -588,7 +637,7 @@ item(tt(q))(
 Quote the resulting words with backslashes. If this flag is given
 twice, the resulting words are quoted in single quotes and if it is
 given three times, the words are quoted in double quotes. If it is
-given four times, the words are quoted in single quotes preceded a tt($).
+given four times, the words are quoted in single quotes preceded by a tt($).
 )
 item(tt(Q))(
 Remove one level of quotes from the resulting words.
@@ -601,7 +650,7 @@ setting of the tt(PROMPT_PERCENT), tt(PROMPT_SUBST) and
 tt(PROMPT_BANG) options.
 )
 item(tt(X))(
-With this flag parsing errors occuring with the tt(Q) flag or the
+With this flag parsing errors occurring with the tt(Q) and tt(e) flags or the
 pattern matching forms such as `tt(${)var(name)tt(#)var(pattern)tt(})' 
 are reported. Without the flag they are silently ignored.
 )
@@ -665,13 +714,22 @@ item(tt(f))(
 Split the result of the expansion to lines. This is a shorthand
 for `tt(ps:\n:)'.
 )
+item(tt(z))(
+Split the result of the expansion into words using shell parsing to
+find the words, i.e. taking into account any quoting in the value.
+
+Note that this is done very late, as for the `tt((s))' flag. So to
+access single words in the result, one has to use nested expansions as 
+in `tt(${${(z)foo}[2]})'. Likewise, to remove the quotes in the
+resulting words one would do: `tt(${(Q)${(z)foo}})'.
+)
 item(tt(t))(
 Use a string describing the type of the parameter where the value
 of the parameter would usually appear. This string consists of keywords
 separated by hyphens (`tt(-)'). The first keyword in the string describes
 the main type, it can be one of `tt(scalar)', `tt(array)', `tt(integer)',
-or `tt(association)'. The other keywords describe the type in more
-detail:
+`tt(float)' or `tt(association)'. The other keywords describe the type in
+more detail:
 
 startitem()
 item(tt(local))(
@@ -733,10 +791,26 @@ Search the var(expr)th match (where var(expr) evaluates to a number).
 This only applies when searching for substrings, either with the tt(S)
 flag, or with tt(${)...tt(/)...tt(}) (only the var(expr)th match is
 substituted) or tt(${)...tt(//)...tt(}) (all matches from the
-var(expr)th on are substituted).  The var(expr)th match is counted
-such that there is either one or zero matches from each starting
-position in the string, although for global substitution matches
-overlapping previous replacements are ignored.
+var(expr)th on are substituted).  The default is to take the first match.
+
+The var(expr)th match is counted such that there is either one or zero
+matches from each starting position in the string, although for global
+substitution matches overlapping previous replacements are ignored.  With
+the tt(${)...tt(%)...tt(}) and tt(${)...tt(%%)...tt(}) forms, the starting
+position for the match moves backwards from the end as the index increases,
+while with the other forms it moves forward from the start.
+
+Hence with the string
+example(which switch is the right switch for Ipswich?)
+substitutions of the form
+tt(${)LPAR()tt(SI:)var(N)tt(:)RPAR()tt(string#w*ch}) as var(N) increases
+from 1 will match and remove `tt(which)', `tt(witch)', `tt(witch)' and
+`tt(wich)'; the form using `tt(##)' will match and remove `tt(which switch
+is the right switch for Ipswich)', `tt(witch is the right switch for
+Ipswich)', `tt(witch for Ipswich)' and `tt(wich)'. The form using `tt(%)'
+will remove the same matches as for `tt(#)', but in reverse order, and the
+form using `tt(%%)' will remove the same matches as for `tt(##)' in reverse
+order.
 )
 item(tt(M))(
 Include the matched portion in the result.
@@ -824,7 +898,7 @@ Note that the `tt((F))' flag implicitly supplies a string for joining in this
 manner.
 )
 item(tt(8.) em(Forced Splitting))(
-If one of the `tt((s))' or `tt((f))' flags are present, or the `tt(=)'
+If one of the `tt((s))', `tt((f))' or `tt((z))' flags are present, or the `tt(=)'
 specifier was present (e.g. tt(${=)var(var)tt(})), the word is split on
 occurrences of the specified string, or (for tt(=) with neither of the two
 flags present) any of the characters in tt($IFS).
@@ -833,7 +907,7 @@ item(tt(9.) em(Shell Word Splitting))(
 If no `tt((s))', `tt((f))' or `tt(=)' was given, but the word is not
 quoted and the option tt(SH_WORD_SPLIT) is set, the word is split on
 occurrences of any of the characters in tt($IFS).  Note this step, too,
-take place at all levels of a nested substitution.
+takes place at all levels of a nested substitution.
 )
 item(tt(10.) em(Re-Evaluation))(
 Any `tt((e))' flag is applied to the value, forcing it to be re-examined
@@ -867,7 +941,7 @@ that this is a scalar, so that (despite the `tt((@))' flag) the subscript
 picks the first character. 
 )
 item(tt("${${(@)foo}[1]}"))(
-The produces the result `tt(bar)'.  In this case, the inner substitution
+This produces the result `tt(bar)'.  In this case, the inner substitution
 tt("${(@)foo}") produces the array `tt(LPAR()bar baz)tt(RPAR())'.  The outer
 substitution tt("${...[1]}") detects that this is an array and picks the
 first word.  This is similar to the simple case tt("${foo[1]}").
@@ -1068,6 +1142,7 @@ Matches any of the enclosed characters.  Ranges of characters
 can be specified by separating two characters by a `tt(-)'.
 A `tt(-)' or `tt(])' may be matched by including it as the
 first character in the list.
+cindex(character classes)
 There are also several named classes of characters, in the form
 `tt([:)var(name)tt(:])' with the following meanings:  `tt([:alnum:])'
 alphanumeric, `tt([:alpha:])' alphabetic,
@@ -1096,6 +1171,14 @@ Matches any number in the range var(x) to var(y), inclusive.
 Either of the numbers may be omitted to make the range open-ended;
 hence `tt(<->)' matches any number.  To match individual digits, the
 tt([)...tt(]) form is more efficient.
+
+Be careful when using other wildcards adjacent to patterns of this form;
+for example, tt(<0-9>*) will actually match any number whatsoever at the
+start of the string, since the `tt(<0-9>)' will match the first digit, and
+the `tt(*)' will match any others.  This is a trap for the unwary, but is
+in fact an inevitable consequence of the rule that the longest possible
+match always succeeds.  Expressions such as `tt(<0-9>[^[:digit:]]*)' can be
+used instead.
 )
 item(tt(LPAR())...tt(RPAR()))(
 Matches the enclosed pattern.  This is used for grouping.
@@ -1186,7 +1269,7 @@ The precedence of the operators given above is (highest) `tt(^)', `tt(/)',
 `tt(~)', `tt(|)' (lowest); the
 remaining operators are simply treated from left to right as part of a
 string, with `tt(#)' and `tt(##)' applying to the shortest possible
-preceeding unit (i.e. a character, `tt(?)', `tt([)...tt(])',
+preceding unit (i.e. a character, `tt(?)', `tt([)...tt(])',
 `tt(<)...tt(>)', or a parenthesised expression).  As mentioned
 above, a `tt(/)' used as a directory separator may not appear inside
 parentheses, while a `tt(|)' must do so; in patterns used in other contexts
@@ -1298,6 +1381,31 @@ item(tt(a)var(num))(
 Approximate matching: var(num) errors are allowed in the string matched by
 the pattern.  The rules for this are described in the next subsection.
 )
+item(tt(s), tt(e))(
+Unlike the other flags, these have only a local effect, and each must
+appear on its own:  `tt((#s))' and `tt((#e))' are the only valid forms.
+The `tt((#s))' flag succeeds only at the start of the test string, and the
+`tt((#e))' flag succeeds only at the end of the test string; they
+correspond to `tt(^)' and `tt($)' in standard regular expressions.  They
+are useful for matching path segments in patterns other than those in
+filename generation (where path segments are in any case treated
+separately).  For example, `tt(*((#s)|/)test((#e)|/)*)' matches a path
+segment `tt(test)' in any of the following strings: tt(test),
+tt(test/at/start), tt(at/end/test), tt(in/test/middle).
+
+Another use is in parameter substitution; for example
+`tt(${array/(#s)A*Z(#e)})' will remove only elements of an array which
+match the complete pattern `tt(A*Z)'.  There are other ways of performing
+many operations of this type, however the combination of the substitution
+operations `tt(/)' and `tt(//)' with the `tt((#s))' and `tt((#e))' flags
+provides a single simple and memorable method.
+
+Note that assertions of the form `tt((^(#s)))' also work, i.e. match
+anywhere except at the start of the string, although this actually means
+`anything except a zero-length portion at the start of the string'; you
+need to use `tt((""~(#s)))' to match a zero-length portion of the string
+not at the start.
+)
 enditem()
 
 For example, the test string tt(fooxx) can be matched by the pattern
@@ -1374,6 +1482,13 @@ crucial one for establishing whether to use approximation; for example,
 tt((#a1)abc(#a0)xyz) will not match tt(abcdxyz), because the error occurs
 at the `tt(x)', where approximation is turned off.
 
+Entire path segments may be matched approximately, so that
+`tt((#a1)/foo/d/is/available/at/the/bar)' allows one error in any path
+segment.  This is much less efficient than without the tt((#a1)), however,
+since every directory in the path must be scanned for a possible
+approximate match.  It is best to place the tt((#a1)) after any path
+segments which are known to be correct.
+
 subsect(Recursive Globbing)
 A pathname component of the form `tt(LPAR())var(foo)tt(/RPAR()#)'
 matches a path consisting of zero or more directories
@@ -1391,10 +1506,11 @@ or
 example(ls **/bar)
 
 does a recursive directory search for files named `tt(bar)' (potentially
-including the file `tt(bar)' in the current directory), not following
-symbolic links.  To follow links, use `tt(***/)'.  Neither of these can be
-combined with other forms of globbing within the same filename segment; in
-that case, the `tt(*)' operators revert to their usual effect.
+including the file `tt(bar)' in the current directory).  This form does not
+follow symbolic links; the alternative form `tt(***/)' does, but is
+otherwise identical.  Neither of these can be combined with other forms of
+globbing within the same path segment; in that case, the `tt(*)'
+operators revert to their usual effect.
 subsect(Glob Qualifiers)
 cindex(globbing, qualifiers)
 cindex(qualifiers, globbing)
@@ -1409,7 +1525,8 @@ containing no `tt(|)' or `tt(LPAR())' characters (or `tt(~)' if it is special)
 is taken as a set of
 glob qualifiers.  A glob subexpression that would normally be taken as glob
 qualifiers, for example `tt((^x))', can be forced to be treated as part of
-the glob pattern by doubling the parentheses, for example `tt(((^x)))'.
+the glob pattern by doubling the parentheses, in this case producing
+`tt(((^x)))'.
 
 A qualifier may be any one of the following:
 
@@ -1521,29 +1638,35 @@ permission, and for which other users don't have read or execute
 permission.
 )
 item(tt(e)var(string))(
-The var(string) will be executed and the return value determines if the
-filename should be included in the list (if it is zero) or not (if it
-is non-zero). The first character after the `tt(e)' will be used as a
-separator and anything up to the next matching separator will be taken 
-as the var(string) (`tt([)', `tt({)', and `tt(<)' match `tt(])',
-`tt(})', and `tt(>)' respectively, any other character matches
-itself). Note that expansions have to be quoted in the var(string) to
-prevent them from being expanded before globbing is done.
-
-During the execution of var(string) the parameter tt(REPLY) is set to
-the filename currently being tested. It may also be set to any string
-to make this string be inserted into the list instead of the original
-filename. Also, the parameter tt(reply) may be set to an array or a
-string and if it is, these strings will be inserted instead of the
-value of the tt(REPLY) parameter. For security reasons, tt(reply)
-will be unset by the shell before the var(string) is executed.
+The var(string) will be executed as shell code.  The filename will be
+included in the list if and only if the code returns a zero status (usually
+the status of the last command).  The first character after the `tt(e)'
+will be used as a separator and anything up to the next matching separator
+will be taken  as the var(string); `tt([)', `tt({)', and `tt(<)' match
+`tt(])', `tt(})', and `tt(>)', respectively, while any other character
+matches itself. Note that expansions must be quoted in the var(string)
+to prevent them from being expanded before globbing is done.
+
+vindex(REPLY, use of)
+vindex(reply, use of)
+During the execution of var(string) the filename currently being tested is
+available in the parameter tt(REPLY); the parameter may be altered to
+a string to be inserted into the list instead of the original
+filename.  In addition, the parameter tt(reply) may be set to an array or a
+string, which overrides the value of tt(REPLY).  If set to an array, the
+latter is inserted into the command line word by word.
+
+For example, suppose a directory contains a single file `tt(lonely)'.  Then
+the expression `tt(*(e:'reply=(${REPLY}{1,2})':))' will cause the words
+`tt(lonely1 lonely2)' to be inserted into the command line.  Note the
+quotation marks.
 )
 item(tt(d)var(dev))(
 files on the device var(dev)
 )
 item(tt(l)[tt(-)|tt(PLUS())]var(ct))(
 files having a link count less than var(ct) (tt(-)), greater than
-var(ct) (tt(PLUS())), or is equal to var(ct)
+var(ct) (tt(PLUS())), or equal to var(ct)
 )
 item(tt(U))(
 files owned by the effective user ID
@@ -1618,19 +1741,24 @@ pindex(NUMERIC_GLOB_SORT, setting in pattern)
 )
 item(tt(o)var(c))(
 specifies how the names of the files should be sorted. If var(c) is
-tt(n) they are sorted by name (the default), if it is tt(L) they
-are sorted depending on the size (length) of the files, if tt(l) 
-they are sorted by the number of links, and if tt(a), tt(m), and tt(c)
+tt(n) they are sorted by name (the default); if it is tt(L) they
+are sorted depending on the size (length) of the files; if tt(l) 
+they are sorted by the number of links; if tt(a), tt(m), or tt(c)
 they are sorted by the time of the last access, modification, or
-inode change respectively. Note that tt(a), tt(m), and tt(c) compare
-the age against the current time, hence the first name in the list is the 
-the youngest file. Also note that the modifiers tt(^) and tt(-) are 
-used, so `tt(*(^-oL))' gives a list of all files sorted by file size in 
-descending order, following any symbolic links.
+inode change respectively; if var(d), files in subdirectories appear before
+those in the current directory at each level of the search --- this is best
+combined with other criteria, for example `tt(odon)' to sort on names for
+files within the same directory.  Note that tt(a), tt(m), and tt(c) compare
+the age against the current time, hence the first name in the list is the
+youngest file. Also note that the modifiers tt(^) and tt(-) are used,
+so `tt(*(^-oL))' gives a list of all files sorted by file size in descending
+order, following any symbolic links.
 )
 item(tt(O)var(c))(
 like `tt(o)', but sorts in descending order; i.e. `tt(*(^oc))' is the
-same as `tt(*(Oc))' and `tt(*(^Oc))' is the same as `tt(*(oc))'
+same as `tt(*(Oc))' and `tt(*(^Oc))' is the same as `tt(*(oc))'; `tt(Od)'
+puts files in the current directory before those in subdirectories at each
+level of the search.
 )
 item(tt([)var(beg)[tt(,)var(end)]tt(]))(
 specifies which of the matched filenames should be included in the
@@ -1644,7 +1772,11 @@ enditem()
 
 More than one of these lists can be combined, separated by commas. The
 whole list matches if at least one of the sublists matches (they are
-`or'ed, the qualifiers in the sublists are `and'ed).
+`or'ed, the qualifiers in the sublists are `and'ed).  Some qualifiers,
+however, affect all matches generated, independent of the sublist in
+which they are given.  These are the qualifiers `tt(M)', `tt(T)',
+`tt(N)', `tt(D)', `tt(n)', `tt(o)', `tt(O)' and the subscripts given
+in brackets (`tt([...])').
 
 If a `tt(:)' appears in a qualifier list, the remainder of the expression in
 parenthesis is interpreted as a modifier (see noderef(Modifiers)
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 820774173..d39c610f4 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -2,6 +2,7 @@ texinode(Zsh Line Editor)(Completion Widgets)(Shell Builtin Commands)(Top)
 chapter(Zsh Line Editor)
 cindex(line editor)
 cindex(editor, line)
+cindex(ZLE)
 sect(Description)
 pindex(ZLE, use of)
 If the tt(ZLE) option is set (which it is by default in interactive shells)
@@ -19,6 +20,14 @@ cindex(editor ksh style)
 This mode
 is similar to bf(ksh), and uses no termcap sequences.  If tt(TERM) is
 "emacs", the tt(ZLE) option will be unset by default.
+
+startmenu()
+menu(Keymaps)
+menu(Zle Builtins)
+menu(Zle Widgets)
+endmenu()
+
+texinode(Keymaps)(Zle Builtins)()(Zsh Line Editor)
 sect(Keymaps)
 cindex(keymaps)
 cindex(key bindings)
@@ -77,6 +86,372 @@ and the command reading process starts again using these fake keystrokes.
 This input can itself invoke further replacement strings, but in order to
 detect loops the process will be stopped if there are twenty such replacements
 without a real command being read.
+
+texinode(Zle Builtins)(Zle Widgets)(Keymaps)(Zsh Line Editor)
+sect(Zle Builtins)
+cindex(zle, builtin commands)
+The ZLE module contains three related builtin commands. The tt(bindkey)
+command manipulates keymaps and key bindings; the tt(vared) command invokes
+ZLE on the value of a shell parameter; and the tt(zle) command manipulates
+editing widgets and allows command line access to ZLE commands from within
+shell functions.
+
+startitem()
+findex(bindkey)
+cindex(keys, rebinding)
+cindex(rebinding keys)
+cindex(keys, binding)
+cindex(binding keys)
+cindex(keymaps)
+xitem(tt(bindkey) [ var(options) ] tt(-l))
+xitem(tt(bindkey) [ var(options) ] tt(-d))
+xitem(tt(bindkey) [ var(options) ] tt(-D) var(keymap) ...)
+xitem(tt(bindkey) [ var(options) ] tt(-A) var(old-keymap new-keymap))
+xitem(tt(bindkey) [ var(options) ] tt(-N) var(new-keymap) [ var(old-keymap) ])
+xitem(tt(bindkey) [ var(options) ] tt(-m))
+xitem(tt(bindkey) [ var(options) ] tt(-r) var(in-string) ...)
+xitem(tt(bindkey) [ var(options) ] tt(-s) var(in-string out-string) ...)
+xitem(tt(bindkey) [ var(options) ] var(in-string command) ...)
+item(tt(bindkey) [ var(options) ] [ var(in-string) ])(
+tt(bindkey)'s options can be divided into three categories: keymap selection,
+operation selection, and others.  The keymap selection options are:
+
+startitem()
+item(tt(-e))(
+Selects keymap `tt(emacs)', and also links it to `tt(main)'.
+)
+item(tt(-v))(
+Selects keymap `tt(viins)', and also links it to `tt(main)'.
+)
+item(tt(-a))(
+Selects keymap `tt(vicmd)'.
+)
+item(tt(-M))(
+The first non-option argument is used as a keymap name,
+and does not otherwise count as an argument.
+)
+enditem()
+
+If a keymap selection is required and none of the options above are used, the
+`tt(main)' keymap is used.  Some operations do not permit a keymap to be
+selected, namely:
+
+startitem()
+item(tt(-l))(
+List all existing keymap names.  If the tt(-L)
+option is also used, list in the form of tt(bindkey)
+commands to create the keymaps.
+)
+item(tt(-d))(
+Delete all existing keymaps and reset to the default state.
+)
+item(tt(-D) var(keymap) ...)(
+Delete the named var(keymap)s.
+)
+item(tt(-A) var(old-keymap new-keymap))(
+Make the var(new-keymap) name an alias for var(old-keymap), so that
+both names refer to the same keymap.  The names have equal standing;
+if either is deleted, the other remains.  If there is already a keymap
+with the var(new-keymap) name, it is deleted.
+)
+item(tt(-N) var(new-keymap) [ var(old-keymap) ])(
+Create a new keymap, named var(new-keymap).  If a keymap already has that
+name, it is deleted.  If an var(old-keymap) name is given, the new keymap
+is initialized to be a duplicate of it, otherwise the new keymap will
+be empty.
+)
+enditem()
+
+To use a newly created keymap, it should be linked to tt(main).  Hence
+the sequence of commands to create and use a new keymap `tt(mymap)'
+initialized from the tt(emacs) keymap (which remains unchanged) is:
+
+example(bindkey -N mymap emacs
+bindkey -A mymap main)
+
+Note that while `tt(bindkey -A) var(newmap) tt(main)' will work when
+var(newmap) is tt(emacs) or tt(viins), it will not work for tt(vicmd), as
+switching from vi insert to command mode becomes impossible.
+
+The following operations act on the `tt(main)' keymap if no keymap
+selection option was given:
+
+startitem()
+item(tt(-m))(
+Add the built-in set of meta-key bindings to the selected keymap.
+Only keys that are unbound or bound to tt(self-insert) are affected.
+)
+item(tt(-r) var(in-string) ...)(
+Unbind the specified var(in-string)s in the selected keymap.
+This is exactly equivalent to binding the strings to tt(undefined-key).
+
+When tt(-R) is also used, interpret the var(in-string)s as ranges.
+
+When tt(-p) is also used, the var(in-string)s specify prefixes.  Any
+binding that has the given var(in-string) as a prefix, not including the
+binding for the var(in-string) itself, if any, will be removed.  For
+example,
+
+example(bindkey -rpM viins '^[')
+
+will remove all bindings in the vi-insert keymap beginning with an escape
+character (probably cursor keys), but leave the binding for the escape
+character itself (probably tt(vi-cmd-mode)).  This is incompatible with the
+option tt(-R).
+)
+item(tt(-s) var(in-string out-string) ...)(
+Bind each var(in-string) to each var(out-string).
+When var(in-string) is typed, var(out-string) will be
+pushed back and treated as input to the line editor.
+When tt(-R) is also used, interpret the var(in-string)s as ranges.
+)
+item(var(in-string command) ...)(
+Bind each var(in-string) to each var(command).
+When tt(-R) is used, interpret the var(in-string)s as ranges.
+)
+item([ var(in-string) ])(
+List key bindings.  If an var(in-string) is specified, the binding of
+that string in the selected keymap is displayed.  Otherwise, all key
+bindings in the selected keymap are displayed.  (As a special case,
+if the tt(-e) or tt(-v) option is used alone, the keymap is em(not)
+displayed - the implicit linking of keymaps is the only thing that
+happens.)
+
+When the option tt(-p) is used, the var(in-string) must be present.
+The listing shows all bindings which have the given key sequence as a
+prefix, not including any bindings for the key sequence itself.
+
+When the tt(-L) option is used, the list is in the form of tt(bindkey)
+commands to create the key bindings.
+)
+enditem()
+
+When the tt(-R) option is used as noted above, a valid range consists of
+two characters, with an optional `tt(-)' between them.  All characters
+between the two specified, inclusive, are bound as specified.
+
+For either var(in-string) or var(out-string), the following
+escape sequences are recognised:
+
+startsitem()
+sitem(tt(\a))(bell character)
+sitem(tt(\b))(backspace)
+sitem(tt(\e), tt(\E))(escape)
+sitem(tt(\f))(form feed)
+sitem(tt(\n))(linefeed (newline))
+sitem(tt(\r))(carriage return)
+sitem(tt(\t))(horizontal tab)
+sitem(tt(\v))(vertical tab)
+sitem(tt(\)var(NNN))(character code in octal)
+sitem(tt(\x)var(NN))(character code in hexadecimal)
+sitem(tt(\M)[tt(-)]var(X))(character with meta bit set)
+sitem(tt(\C)[tt(-)]var(X))(control character)
+sitem(tt(^)var(X))(control character)
+endsitem()
+
+In all other cases, `tt(\)' escapes the following character.  Delete is
+written as `tt(^?)'.  Note that `tt(\M^?)' and `tt(^\M?)' are not the same,
+and that (unlike emacs), the bindings `tt(\M-)var(X)' and `tt(\e)var(X)'
+are entirely distinct, although they are initialized to the same bindings
+by `tt(bindkey -m)'.
+)
+findex(vared)
+cindex(parameters, editing)
+cindex(editing parameters)
+item(tt(vared) [ tt(-Aache) ] [ tt(-p) var(prompt) ] [ tt(-r) var(rprompt) ] var(name))(
+The value of the parameter var(name) is loaded into the edit
+buffer, and the line editor is invoked.  When the editor exits,
+var(name) is set to the string value returned by the editor.
+When the tt(-c) flag is given, the parameter is created if it doesn't
+already exist.  The tt(-a) flag may be given with tt(-c) to create
+an array parameter, or the tt(-A) flag to create an associative array.
+If the type of an existing parameter does not match the type to be
+created, the parameter is unset and recreated.
+
+If an array or array slice is being edited, separator characters as defined
+in tt($IFS) will be shown quoted with a backslash, as will backslashes
+themselves.  Conversely, when the edited text is split into an array, a
+backslash quotes an immediately following separator character or backslash;
+no other special handling of backslashes, or any handling of quotes, is
+performed.
+
+Individual elements of existing array or associative array parameters
+may be edited by using subscript syntax on var(name).  New elements are
+created automatically, even without tt(-c).
+
+If the tt(-p) flag is given, the following string will be taken as
+the prompt to display at the left.  If the tt(-r) flag is given,
+the following string gives the prompt to display at the right.  If the
+tt(-h) flag is specified, the history can be accessed from ZLE. If the 
+tt(-e) flag is given, typing tt(^D) (Control-D) on an empty line
+causes tt(vared) to exit immediately with a non-zero return value.
+)
+findex(zle)
+cindex(widgets, rebinding)
+cindex(rebinding widgets)
+cindex(widgets, binding)
+cindex(binding widgets)
+cindex(widgets, invoking)
+cindex(invoking widgets)
+cindex(widgets, calling)
+cindex(calling widgets)
+cindex(widgets, defining)
+cindex(defining widgets)
+xitem(tt(zle) tt(-l) [ tt(-L) | tt(-a) ] [ var(string) ... ])
+xitem(tt(zle) tt(-D) var(widget) ...)
+xitem(tt(zle) tt(-A) var(old-widget) var(new-widget))
+xitem(tt(zle) tt(-N) var(widget) [ var(function) ])
+xitem(tt(zle) tt(-C) var(widget) var(completion-widget) var(function))
+xitem(tt(zle) tt(-R) [ tt(-c) ] [ var(display-string) ] [ var(string) ... ])
+xitem(tt(zle) tt(-M) var(string))
+xitem(tt(zle) tt(-U) var(string))
+xitem(tt(zle) tt(-I))
+xitem(tt(zle) var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)
+item(tt(zle))(
+The tt(zle) builtin performs a number of different actions concerning
+ZLE.  Which operation it performs depends on its options:
+
+startitem()
+item(tt(-l) [ tt(-L) | tt(-a) ])(
+List all existing user-defined widgets.  If the tt(-L)
+option is used, list in the form of tt(zle)
+commands to create the widgets.
+
+When combined with the tt(-a) option, all widget names are listed,
+including the builtin ones. In this case the tt(-L) option is ignored.
+
+If at least one var(string) is given, nothing will be printed but the
+return status will be zero if all var(string)s are names of existing
+widgets (or of user-defined widgets if the tt(-a) flag is not given)
+and non-zero if at least one var(string) is not a name of an defined
+widget.
+)
+item(tt(-D) var(widget) ...)(
+Delete the named var(widget)s.
+)
+item(tt(-A) var(old-widget) var(new-widget))(
+Make the var(new-widget) name an alias for var(old-widget), so that
+both names refer to the same widget.  The names have equal standing;
+if either is deleted, the other remains.  If there is already a widget
+with the var(new-widget) name, it is deleted.
+)
+item(tt(-N) var(widget) [ var(function) ])(
+Create a user-defined widget.  If there is already a widget with the
+specified name, it is overwritten.  When the new
+widget is invoked from within the editor, the specified shell var(function)
+is called.  If no function name is specified, it defaults to
+the same name as the widget.  For further information, see the section
+em(Widgets) in
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor))\
+.
+)
+cindex(completion widgets, creating)
+item(tt(-C) var(widget) var(completion-widget) var(function))(
+Create a user-defined completion widget named var(widget). The 
+completion widget will behave like the built-in completion-widget
+whose name is given as var(completion-widget). To generate the
+completions, the shell function var(function) will be called.
+For further information, see
+ifzman(zmanref(zshcompwid))\
+ifnzman(noderef(Completion Widgets))\
+.
+)
+item(tt(-R) [ tt(-c) ] [ var(display-string) ] [ var(string) ... ])(
+Redisplay the command line; this is to be called from within a user-defined
+widget to allow changes to become visible.  If a var(display-string) is
+given and not empty, this is shown in the status line (immediately
+below the line being edited).
+
+If the optional var(string)s are given they are listed below the
+prompt in the same way as completion lists are printed. If no
+var(string)s are given but the tt(-c) option is used such a list is
+cleared.
+
+Note that this option is only useful for widgets that do not exit
+immediately after using it because the strings displayed will be erased 
+immediately after return from the widget.
+
+This command can safely be called outside user defined widgets; if zle is
+active, the display will be refreshed, while if zle is not active, the
+command has no effect.  In this case there will usually be no other
+arguments.  The status is zero if zle was active, else one.
+)
+item(tt(-M) var(string))(
+As with the tt(-R) option, the var(string) will be displayed below the 
+command line; unlike the tt(-R) option, the string will not be put into
+the status line but will instead be printed normally below the
+prompt.  This means that the var(string) will still be displayed after
+the widget returns (until it is overwritten by subsequent commands).
+)
+item(tt(-U) var(string))(
+This pushes the characters in the var(string) onto the input stack of
+ZLE.  After the widget currently executed finishes ZLE will behave as
+if the characters in the var(string) were typed by the user.
+
+As ZLE uses a stack, if this option is used repeatedly
+the last string pushed onto the stack will be processed first.  However,
+the characters in each var(string) will be processed in the order in which
+they appear in the string.
+)
+item(tt(-I))(
+Unusually, this option is only useful em(outside) ordinary widget functions.
+It invalidates the current zle display in preparation for output; usually
+this will be from a trap function.  It has no effect if zle is not
+active.  When a trap exits, the shell checks to see if the display needs
+restoring, hence the following will print output in such a way as not to
+disturb the line being edited:
+
+example(TRAPUSR1() {
+    # Invalidate zle display
+  zle -I
+    # Show output
+  print Hello
+})
+
+Note that there are better ways of manipulating the display from within zle
+widgets.  In general, the trap function may need to test whether zle is
+loaded before using this method; if it is not, there is no point in loading
+it specially since the line editor will not be active.
+
+The status is zero if zle was active, else one.
+)
+item(var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)(
+Invoke the specified widget.  This can only be done when ZLE is
+active; normally this will be within a user-defined widget.
+
+With the options tt(-n) and tt(-N), the current numerical argument will be
+saved and then restored after the call to tt(widget); `tt(-n) var(num)'
+sets the numerical argument temporarily to var(num), while `tt(-N)' sets it
+to the default, i.e. as if there were none.
+
+Any further arguments will be passed to the widget.  If it is a shell
+function, these are passed down as positional parameters; for builtin
+widgets it is up to the widget in question what it does with them.
+Currently arguments are only handled by the incremental-search commands,
+the tt(history-search-forward) and tt(-backward) and the corresponding
+functions prefixed by tt(vi-), and by tt(universal-argument).  No error is
+flagged if the command does not use the arguments, or only uses some of
+them.
+
+The return status reflects the success or failure of the operation carried
+out by the widget, or if it is a user-defined widget the return status of
+the shell function.  
+
+A non-zero return status causes the shell to beep when the widget exits,
+unless the tt(BEEP) options was unset or the widget was called via the
+tt(zle) command.  Thus if a user defined widget requires an immediate beep,
+it should call the tt(beep) widget directly.
+)
+enditem()
+
+With no options and no arguments, only the return status will be
+set. It is zero if ZLE is currently active and widgets could be
+invoked using this builtin command and non-zero if ZLE is not active.
+)
+enditem()
+
+texinode(Zle Widgets)()(Zle Builtins)(Zsh Line Editor)
 sect(Widgets)
 cindex(widgets)
 All actions in the editor are performed by `widgets'.  A widget's job is
@@ -103,8 +478,10 @@ cindex(widgets, user-defined)
 User-defined widgets, being implemented as shell functions,
 can execute any normal shell command.  They can also run other widgets
 (whether built-in or user-defined) using the tt(zle) builtin command.
-They can use tt(read -k) or tt(read -q) to read characters from standard
-input.  Finally, they can examine and edit the ZLE buffer being edited by
+The standard input of the function is closed to prevent external commands
+from unintentionally blocking ZLE by reading from the terminal, but
+tt(read -k) or tt(read -q) can be used to read characters.  Finally,
+they can examine and edit the ZLE buffer being edited by
 reading and setting the special parameters described below.
 
 cindex(parameters, editor)
@@ -125,6 +502,12 @@ The entire contents of the edit buffer.  If it is written to, the
 cursor remains at the same offset, unless that would put it outside the
 buffer.
 )
+vindex(BUFFERLINES)
+item(tt(BUFFERLINES))(
+The number of screen lines needed for the edit buffer currently
+displayed on screen (i.e. without any changes to the preceding
+parameters done after the last redisplay).
+)
 vindex(CURSOR)
 item(tt(CURSOR) (integer))(
 The offset of the cursor, within the edit buffer.  This is in the range
@@ -132,9 +515,17 @@ The offset of the cursor, within the edit buffer.  This is in the range
 Attempts to move the cursor outside the buffer will result in the
 cursor being moved to the appropriate end of the buffer.
 )
-vindex(MARK)
-item(tt(MARK) (integer))(
-Like tt(CURSOR), but for the mark.
+vindex(HISTNO)
+item(tt(HISTNO) (integer))(
+The current history number.
+)
+vindex(KEYS)
+item(tt(KEYS) (scalar))(
+The keys typed to invoke this widget, as a literal string.
+)
+vindex(LASTWIDGET)
+item(tt(LASTWIDGET) (scalar))(
+The name of the last widget that was executed.
 )
 vindex(LBUFFER)
 item(tt(LBUFFER) (scalar))(
@@ -142,17 +533,24 @@ The part of the buffer that lies to the left of the cursor position.
 If it is assigned to, only that part of the buffer is replaced, and the
 cursor remains between the new tt($LBUFFER) and the old tt($RBUFFER).
 )
-vindex(RBUFFER)
-item(tt(RBUFFER) (scalar))(
-The part of the buffer that lies to the right of the cursor position.
-If it is assigned to, only that part of the buffer is replaced, and the
-cursor remains between the old tt($LBUFFER) and the new tt($RBUFFER).
+vindex(MARK)
+item(tt(MARK) (integer))(
+Like tt(CURSOR), but for the mark.
 )
-vindex(BUFFERLINES)
-item(tt(BUFFERLINES))(
-The number of screen lines needed for the edit buffer currently
-displayed on screen (i.e. without any changes to the preceding
-parameters done after the last redisplay).
+vindex(NUMERIC)
+item(tt(NUMERIC) (integer))(
+The numeric argument. If no numeric argument was given, this parameter
+is unset. When this is set inside a widget function, builtin widgets
+called with the tt(zle) builtin command will use the value
+assigned. If it is unset inside a widget function, builtin widgets
+called behave as if no numeric argument was given.
+)
+vindex(PENDING)
+item(tt(PENDING) (integer))(
+The number of bytes pending for input, i.e. the number of bytes which have
+already been typed and can immediately be read. On systems where the shell
+is not able to get this information, this parameter will always have a
+value of zero.
 )
 vindex(PREBUFFER)
 item(tt(PREBUFFER) (scalar))(
@@ -160,30 +558,16 @@ In a multi-line input at the secondary prompt, this read-only parameter
 contains the contents of the lines before the one the cursor is
 currently in.
 )
+vindex(RBUFFER)
+item(tt(RBUFFER) (scalar))(
+The part of the buffer that lies to the right of the cursor position.
+If it is assigned to, only that part of the buffer is replaced, and the
+cursor remains between the old tt($LBUFFER) and the new tt($RBUFFER).
+)
 vindex(WIDGET)
 item(tt(WIDGET) (scalar))(
 The name of the widget currently being executed.
 )
-vindex(LASTWIDGET)
-item(tt(LASTWIDGET) (scalar))(
-The name of the last widget that was executed.
-)
-vindex(KEYS)
-item(tt(KEYS) (scalar))(
-The keys typed to invoke this widget, as a literal string.
-)
-vindex(NUMERIC)
-item(tt(NUMERIC) (integer))(
-The numeric argument. If no numeric argument was given, this parameter
-is unset. When this is set inside a widget function, builtin widgets
-called with the tt(zle) builtin command will use the value
-assigned. If it is unset inside a widget function, builtin widgets
-called behave as if no numeric argument was given.
-)
-vindex(HISTNO)
-item(tt(HISTNO) (integer))(
-The current history number.
-)
 enditem()
 sect(Standard Widgets)
 cindex(widgets, standard)
@@ -191,6 +575,16 @@ The following is a list of all the standard widgets,
 and their default bindings in emacs mode,
 vi command mode and vi insert mode
 (the `tt(emacs)', `tt(vicmd)' and `tt(viins)' keymaps, respectively).
+
+Note that cursor keys are bound to movement keys in all three keymaps;
+the shell assumes that the cursor keys send the key sequences reported
+by the terminal-handling library (termcap or terminfo).  The key sequences
+shown in the list are those based on the VT100, common on many modern
+terminals, but in fact these are not necessarily bound.  In the case of the
+tt(viins) keymap, the initial escape character of the sequences serves also
+to return to the tt(vicmd) keymap: whether this happens is determined by
+the tt(KEYTIMEOUT) parameter, see ifzman(zmanref(zshparam))\
+ifnzman(noderef(Parameters)).
 startmenu()
 menu(Movement)
 menu(History Control)
@@ -199,7 +593,7 @@ menu(Arguments)
 menu(Completion)
 menu(Miscellaneous)
 endmenu()
-texinode(Movement)(History Control)()(Zsh Line Editor)
+texinode(Movement)(History Control)()(Zle Widgets)
 subsect(Movement)
 startitem()
 tindex(vi-backward-blank-word)
@@ -212,7 +606,7 @@ item(tt(backward-char) (^B ESC-[D) (unbound) (unbound))(
 Move backward one character.
 )
 tindex(vi-backward-char)
-item(tt(vi-backward-char) (unbound) (^H h ^?) (unbound))(
+item(tt(vi-backward-char) (unbound) (^H h ^?) (ESC-[D))(
 Move backward one character, without changing lines.
 )
 tindex(backward-word)
@@ -263,7 +657,7 @@ item(tt(forward-char) (^F ESC-[C) (unbound) (unbound))(
 Move forward one character.
 )
 tindex(vi-forward-char)
-item(tt(vi-forward-char) (unbound) (space l) (unbound))(
+item(tt(vi-forward-char) (unbound) (space l) (ESC-[C))(
 Move forward one character.
 )
 tindex(vi-find-next-char)
@@ -329,7 +723,7 @@ item(tt(vi-rev-repeat-find) (unbound) (,) (unbound))(
 Repeat the last tt(vi-find) command in the opposite direction.
 )
 enditem()
-texinode(History Control)(Modifying Text)(Movement)(Zsh Line Editor)
+texinode(History Control)(Modifying Text)(Movement)(Zle Widgets)
 subsect(History Control)
 startitem()
 tindex(beginning-of-buffer-or-history)
@@ -347,7 +741,7 @@ item(tt(beginning-of-history))(
 Move to the first event in the history list.
 )
 tindex(down-line-or-history)
-item(tt(down-line-or-history) (^N ESC-[B) (j) (unbound))(
+item(tt(down-line-or-history) (^N ESC-[B) (j) (ESC-[B))(
 Move down a line in the buffer, or if already at the bottom line,
 move to the next event in the history list.
 )
@@ -536,7 +930,7 @@ item(tt(vi-rev-repeat-search) (unbound) (N) (unbound))(
 Repeat the last vi history search, but in reverse.
 )
 tindex(up-line-or-history)
-item(tt(up-line-or-history) (^P ESC-[A) (k) (unbound))(
+item(tt(up-line-or-history) (^P ESC-[A) (k) (ESC-[A))(
 Move up a line in the buffer, or if already at the top line,
 move to the previous event in the history list.
 )
@@ -567,7 +961,7 @@ line up to the cursor.
 This leaves the cursor in its original position.
 )
 enditem()
-texinode(Modifying Text)(Arguments)(History Control)(Zsh Line Editor)
+texinode(Modifying Text)(Arguments)(History Control)(Zle Widgets)
 subsect(Modifying Text)
 startitem()
 tindex(vi-add-eol)
@@ -630,7 +1024,13 @@ Copy the area from the cursor to the mark to the kill buffer.
 )
 tindex(copy-prev-word)
 item(tt(copy-prev-word) (ESC-^_) (unbound) (unbound))(
-Duplicate the word behind the cursor.
+Duplicate the word to the left of the cursor.
+)
+tindex(copy-prev-shell-word)
+item(tt(copy-prev-shell-word) (ESC-^_) (unbound) (unbound))(
+Like tt(copy-prev-word), but the word is found by using shell parsing, 
+whereas tt(copy-prev-word) looks for blanks. This makes a difference
+when the word is quoted and contains spaces.
 )
 tindex(vi-delete)
 item(tt(vi-delete) (unbound) (d) (unbound))(
@@ -845,7 +1245,7 @@ into the kill buffer.
 Arguably, this is what Y should do in vi, but it isn't what it actually does.
 )
 enditem()
-texinode(Arguments)(Completion)(Modifying Text)(Zsh Line Editor)
+texinode(Arguments)(Completion)(Modifying Text)(Zle Widgets)
 subsect(Arguments)
 startitem()
 tindex(digit-argument)
@@ -876,7 +1276,7 @@ universal-argument) var(num)', the numerical argument will be set to
 var(num); this is equivalent to `tt(NUMERIC=)var(num)'.
 )
 enditem()
-texinode(Completion)(Miscellaneous)(Arguments)(Zsh Line Editor)
+texinode(Completion)(Miscellaneous)(Arguments)(Zle Widgets)
 subsect(Completion)
 startitem()
 tindex(accept-and-menu-complete)
@@ -951,7 +1351,7 @@ When a previous completion displayed a list below the prompt, this
 widget can be used to move the prompt below the list.
 )
 enditem()
-texinode(Miscellaneous)()(Completion)(Zsh Line Editor)
+texinode(Miscellaneous)()(Completion)(Zle Widgets)
 subsect(Miscellaneous)
 startitem()
 tindex(accept-and-hold)
@@ -1099,7 +1499,7 @@ tindex(run-help)
 item(tt(run-help) (ESC-H ESC-h) (unbound) (unbound))(
 Push the buffer onto the buffer stack, and execute the
 command `tt(run-help) var(cmd)', where var(cmd) is the current
-command.  tt(run-help) is normally aliased to var(man).
+command.  tt(run-help) is normally aliased to tt(man).
 )
 tindex(vi-set-buffer)
 item(tt(vi-set-buffer) (unbound) (") (unbound))(