Updated from list as far as 10376

19 files changed, 6239 insertions, 1312 deletions

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 8959543c5..cb7372cc5 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -17,17 +17,26 @@ item(tt(ARG1))(
 Same as tt(ARG2).
 )\
 )\
+def(module)(2)(\
+item(tt(ARG1))(
+See ifzman(the section `The ARG2 Module' in zmanref(zshmodules))\
+ifnzman(noderef(The ARG2 Module)).
+)\
+)\
 startitem()
 prefix(-)
 findex(.)
 item(tt(.) var(file) [ var(arg) ... ])(
 Read commands from var(file) and execute them in the current shell
 environment.
-If var(file) does not contain a slash, or if tt(PATH_DIRS)
-is set, the shell looks in the components of tt($path) to find the
-directory containing var(file).
-Files in the current directory are not read unless `tt(.)' appears
-somewhere in tt($path).
+
+If var(file) does not contain a slash, or if tt(PATH_DIRS) is set,
+the shell looks in the components of tt($path) to find the directory
+containing var(file).  Files in the current directory are not read
+unless `tt(.)' appears somewhere in tt($path).  If a file named
+`var(file)tt(.zwc)' is found, is newer than var(file), and is the
+compiled form (created with the tt(zcompile) builtin) of var(file),
+then commands are read from that file instead of var(file).
 
 If any arguments var(arg) are given,
 they become the positional parameters; the old positional
@@ -39,15 +48,16 @@ cindex(expanding parameters)
 cindex(parameters, expanding)
 cindex(doing nothing)
 item(tt(:) [ var(arg) ... ])(
-This command only expands parameters.  A zero exit code is returned.
+This command does nothing, although normal argument expansions is performed
+which may have effects on shell parameters.  A zero exit code is returned.
 )
 findex(alias)
 cindex(aliases, defining)
 cindex(aliases, listing)
-item(tt(alias) [ tt(-gmrL) ] [ var(name)[tt(=)var(value)] ... ])(
+item(tt(alias) [ {tt(PLUS()|tt(-))}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.
 
@@ -58,7 +68,9 @@ are taken as patterns (they should be quoted to preserve them from being
 interpreted as glob patterns), and the aliases matching these patterns
 are printed.  When printing aliases and the tt(-g) or tt(-r) flags
 are present, then restrict the printing to global or regular
-aliases, respectively.
+aliases, respectively.  Using `tt(PLUS())' instead of `tt(-)', or ending
+the option list with a single `tt(PLUS())', prevents the values of the
+aliases from being printed.
 
 If the tt(-L) flag is present, then print each
 alias in a manner suitable for putting in a startup script.  The exit
@@ -68,7 +80,38 @@ which no alias has been defined.
 findex(autoload)
 cindex(functions, autoloading)
 cindex(autoloading functions)
-alias(autoload)(functions -u)
+item(tt(autoload) [ {tt(PLUS())|tt(-)}tt(UXmt) ] [ tt(-wkz) ] [ var(name) ... ])(
+Equivalent to tt(functions -u), with the exception of tt(-X)/tt(+X),
+tt(-w), tt(-k) and tt(-z).
+
+The flag tt(-X) may be used only inside a shell function, and may not be
+followed by a var(name).  It causes the calling function to be marked for
+autoloading and then immediately loaded and executed, with the current
+array of positional parameters as arguments.  This replaces the previous
+definition of the function.  If no function definition is found, an error
+is printed and the function remains undefined and marked for autoloading.
+
+The flag tt(+X) attempts to load each var(name) as an autoloaded function,
+but does em(not) execute it.  The exit status is zero (success) if the
+function was not previously defined em(and) a definition for it was found.
+This does em(not) replace any existing definition of the function.  The
+exit status is nonzero (failure) if the function was already defined or
+when no definition was found.  In the latter case the function remains
+undefined and marked for autoloading.
+
+The flag tt(+X) may be combined with either tt(-k) or tt(-z) to make
+the function be loaded using ksh-style or zsh-style autoloading,
+respectively. If neither is given, the current setting of the
+tt(KSH_AUTOLOAD) options determines how the function is loaded. With
+ksh-style autoloading, the contents of the file will not be executed
+immediatly. Instead, the function created will contain the contents of 
+the file plus a call to the function itself appended to it, thus given 
+normal ksh autoloading behaviour on the first call to the function.
+
+With the tt(-w) flag, the var(name)s are taken as names of files compiled
+with the tt(zcompile) builtin, and all functions defined in them are
+marked for autoloading.
+)
 findex(bg)
 cindex(jobs, backgrounding)
 xitem(tt(bg) [ var(job) ... ])
@@ -76,6 +119,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)
 findex(break)
 cindex(exiting loops)
 cindex(loops, exiting)
@@ -89,6 +133,7 @@ item(tt(builtin) var(name) [ var(args) ... ])(
 Executes the builtin var(name), with the given var(args).
 )
 alias(bye)(exit)
+module(cap)(zsh/cap)
 findex(cd)
 cindex(directories, changing)
 xitem(tt(cd) [ tt(-sLP) ] [ var(arg) ])
@@ -98,12 +143,13 @@ Change the current directory.  In the first form, change the
 current directory to var(arg), or to the value of tt($HOME) if
 var(arg) is not specified.  If var(arg) is `tt(-)', change to the
 value of tt($OLDPWD), the previous directory.
-If a directory named var(arg) is not found in the current directory
-and var(arg) does not begin with a slash,
-search each component of the shell parameter tt(cdpath).
-If the option tt(CDABLE_VARS) is set, and a parameter named var(arg)
-exists whose value begins with a slash, treat its value as
-the directory.
+Otherwise, if a directory named var(arg) is not found in the current
+directory and var(arg) does not begin with a slash, search each
+component of the shell parameter tt(cdpath).  If no directory is found
+and the option tt(CDABLE_VARS) is set, and a parameter named var(arg)
+exists whose value begins with a slash, treat its value as the
+directory.  In that case, the parameter is added to the named
+directory hash table.
 
 The second form of tt(cd) substitutes the string var(new)
 for the string var(old) in the name of the current directory,
@@ -124,7 +170,16 @@ to their true values.  If the tt(-L) option is given symbolic links are
 followed regardless of the state of the tt(CHASE_LINKS) option.
 )
 alias(chdir)(cd)
+module(clone)(zsh/clone)
 prefix(command)
+module(comparguments)(zsh/computil)
+module(compcall)(zsh/compctl)
+module(compctl)(zsh/compctl)
+module(compdescribe)(zsh/computil)
+module(compquote)(zsh/computil)
+module(comptags)(zsh/computil)
+module(comptry)(zsh/computil)
+module(compvalues)(zsh/computil)
 findex(continue)
 cindex(loops, continuing)
 cindex(continuing loops)
@@ -158,8 +213,8 @@ causes tt(disable) to act on aliases.  The tt(-f) option causes
 tt(disable) to act on shell functions.  The tt(-r) options causes
 tt(disable) to act on reserved words.  Without arguments all disabled
 hash table elements from the corresponding hash table are printed.
-With the tt(-m) flag the arguments are taken as patterns (should be
-quoted to preserve them from being taken as glob patterns), and all hash
+With the tt(-m) flag the arguments are taken as patterns (which should be
+quoted to prevent them from undergoing filename expansion), and all hash
 table elements from the corresponding hash table matching these patterns
 are disabled.  Disabled objects can be enabled with the tt(enable)
 command.
@@ -214,13 +269,29 @@ cindex(compatibility, csh)
 cindex(sh, compatibility)
 cindex(ksh, compatibility)
 cindex(csh, compatibility)
-item(tt(emulate) [ tt(-R) ] {tt(zsh)|tt(sh)|tt(ksh)|tt(csh)})(
+item(tt(emulate) [ tt(-LR) ] {tt(zsh)|tt(sh)|tt(ksh)|tt(csh)})(
 Set up zsh options to emulate the specified shell as much as possible.
 bf(csh) will never be fully emulated.
 If the argument is not one of the shells listed above, tt(zsh)
-will be used as a default.  If the tt(-R) option is given, all options
+will be used as a default; more precisely, the tests performed on the
+argument are the same as those used to determine the emulation at startup
+based on the shell name, see
+ifzman(\
+the section `Compatibility' in zmanref(zshmisc)
+)\
+ifnzman(\
+noderef(Compatibility)
+)\
+.  If the tt(-R) option is given, all options
 are reset to their default value corresponding to the specified emulation
-mode.
+mode, except for certain options describing the interactive
+environment; otherwise, only those options likely to cause portability
+problems in scripts and functions are altered.  If the tt(-L) option
+is given, the options tt(LOCAL_OPTIONS) and tt(LOCAL_TRAPS) will be set as
+well, causing the effects of the tt(emulate) command and any tt(setopt) and
+tt(trap) commands to be local to the immediately surrounding shell
+function, if any; normally these options are turned off in all emulation
+modes except tt(ksh).
 )
 findex(enable)
 cindex(enabling commands)
@@ -256,8 +327,7 @@ findex(export)
 item(tt(export) [ var(name)[tt(=)var(value)] ... ])(
 The specified var(name)s are marked for automatic export
 to the environment of subsequently executed commands.
-Equivalent to tt(typeset -x), except that no parameter will be created
-to hide an existing one in an outer scope.
+Equivalent to tt(typeset -gx).
 If a parameter specified does not
 already exist, it is created in the global scope.
 )
@@ -308,13 +378,16 @@ With the tt(-D) flag, tt(fc) prints elapsed times.
 
 cindex(history, file)
 cindex(file, history)
-tt(fc -R) reads the history from the given file,
-tt(fc -W) writes the history out to the given file,
-and tt(fc -A) appends the history out to the given file.
-If the tt(-I) option is added, only those
-events that are new since last incremental append (write) to
-the history file are appended (written).
-In any case the file will have no more than tt($SAVEHIST)
+`tt(fc -R)' reads the history from the given file,
+`tt(fc -W)' writes the history out to the given file,
+and `tt(fc -A)' appends the history out to the given file.
+If no filename is specified, the tt($HISTFILE) is assumed.
+If the tt(-I) option is added to tt(-R), only those events that are
+not already contained within the internal history list are added.
+If the tt(-I) option is added to tt(-A) or tt(-W), only those
+events that are new since last incremental append/write to
+the history file are appended/written.
+In any case, the created file will have no more than tt($SAVEHIST)
 entries.
 )
 findex(fg)
@@ -325,10 +398,16 @@ item(var(job) ...)(
 Bring each specified var(job) in turn to the foreground.
 If no var(job) is specified, resume the current job.
 )
+findex(float)
+item(tt(float) [ {tt(PLUS())|tt(-)}tt(EFghlrtux) ] [ var(name)[tt(=)var(value)] ... ])(
+Equivalent to tt(typeset -E), except that options irrelevant to floating
+point numbers are not permitted.
+)
 findex(functions)
-item(tt(functions) [ {tt(PLUS())|tt(-)}tt(tum) ] [ var(name) ... ])(
+item(tt(functions) [ {tt(PLUS())|tt(-)}tt(UXmtu) ] [ var(name) ... ])(
 Equivalent to tt(typeset -f).
 )
+module(getcap)(zsh/cap)
 findex(getln)
 cindex(line, reading)
 cindex(reading a line)
@@ -357,11 +436,20 @@ is stored in tt(OPTARG).
 vindex(OPTIND, use of)
 vindex(OPTARG, use of)
 
+The first option to be examined may be changed by explicitly assigning
+to tt(OPTIND).  tt(OPTIND) has an initial value of tt(1), and is
+normally reset to tt(1) upon exit from a shell function.  tt(OPTARG)
+is not reset and retains its value from the most recent call to
+tt(getopts).  If either of tt(OPTIND) or tt(OPTARG) is explicitly
+unset, it remains unset, and the index or option argument is not
+stored.  The option itself is still stored in var(name) in this case.
+
 A leading `tt(:)' in var(optstring) causes tt(getopts) to store the
-letter of the invalid option in tt(OPTARG), and to set var(name)
-to `tt(?)' for an unknown option and to `tt(:)' when a required option
-is missing.  Otherwise, tt(getopts) prints an error
-message.  The exit status is nonzero when there are no more options.
+letter of any invalid option in tt(OPTARG), and to set var(name) to
+`tt(?)' for an unknown option and to `tt(:)' when a required option is
+missing.  Otherwise, tt(getopts) sets var(name) to `tt(?)' and prints
+an error message when an option is invalid.  The exit status is
+nonzero when there are no more options.
 )
 findex(hash)
 item(tt(hash) [ tt(-dfmrv) ] [ var(name)[tt(=)var(value)] ] ...)(
@@ -386,7 +474,7 @@ and for the named directory hash table this adds all users' home directories.
 These two options cannot be used with any arguments.
 
 The tt(-m) option causes the arguments to be taken as patterns
-(they should be quoted) and the elements of the hash table
+(which should be quoted) and the elements of the hash table
 matching those patterns are printed.  This is the only way to display
 a limited selection of hash table elements.
 
@@ -409,7 +497,7 @@ added by explicit specification.  If has no effect if used with tt(-f).
 )
 alias(history)(fc -l)
 findex(integer)
-item(tt(integer) [ {tt(PLUS())|tt(-)}tt(lrtux) ] [ var(name)[tt(=)var(value)] ... ])(
+item(tt(integer) [ {tt(PLUS())|tt(-)}tt(ghlrtux) ] [ var(name)[tt(=)var(value)] ... ])(
 Equivalent to tt(typeset -i), except that options irrelevant to
 integers are not permitted.
 )
@@ -475,18 +563,23 @@ If no var(resource) is given, print all limits.
 var(resource) can be one of:
 
 startsitem()
-sitem(tt(memorylocked))(Maximum amount of memory locked in RAM.)
-sitem(tt(resident))(Maximum resident set size.)
-sitem(tt(vmemorysize))(Maximum amount of virtual memory.)
-sitem(tt(descriptors))(Maximum value for a file descriptor.)
+sitem(tt(addressspace))(Maximum amount of address space used.)
+sitem(tt(aiomemorylocked))(Maximum amount of memory locked in RAM for AIO operations.)
+sitem(tt(aiooperations))(Maximum number of AIO operations.)
+sitem(tt(cachedthreads))(Maximum number of cached threads.)
 sitem(tt(coredumpsize))(Maximum size of a core dump.)
-sitem(tt(stacksize))(Maximum stack size for each process.)
+sitem(tt(cputime))(Maximum CPU seconds per process.)
 sitem(tt(datasize))(Maximum data size (including stack) for each process.)
+sitem(tt(descriptors))(Maximum value for a file descriptor.)
 sitem(tt(filesize))(Largest single file allowed.)
-sitem(tt(cputime))(Maximum CPU seconds per process.)
 sitem(tt(maxproc))(Maximum number of processes.)
-sitem(tt(addressspace))(Maximum amount of address space used.)
-sitem(tt(cachedthreads))(Maximum number of cached threads.)
+sitem(tt(maxpthreads))(Maximum number of threads per process.)
+sitem(tt(memorylocked))(Maximum amount of memory locked in RAM.)
+sitem(tt(memoryuse))(Maximum resident set size.)
+sitem(tt(resident))(Maximum resident set size.)
+sitem(tt(sockbufsize))(Maximum size of all socket buffers.)
+sitem(tt(stacksize))(Maximum stack size for each process.)
+sitem(tt(vmemorysize))(Maximum amount of virtual memory.)
 endsitem()
 
 Which of these resource limits are available depends on the system.
@@ -502,8 +595,8 @@ sitem([var(mm)tt(:)]var(ss))(minutes and seconds)
 endsitem()
 )
 findex(local)
-item(tt(local) [ {tt(PLUS())|tt(-)}tt(LRZilrtu) [var(n)]] [ var(name)[tt(=)var(value)] ] ...)(
-Same as tt(typeset), except that the options tt(-x) and
+item(tt(local) [ {tt(PLUS())|tt(-)}tt(AEFLRUZahilrtu) [var(n)]] [ var(name)[tt(=)var(value)] ] ...)(
+Same as tt(typeset), except that the options tt(-g), tt(-x) and
 tt(-f) are not permitted.
 )
 findex(log)
@@ -521,8 +614,8 @@ Same as tt(exit), except that it only works in a login shell.
 prefix(noglob)
 findex(popd)
 item(tt(popd) [ {tt(PLUS())|tt(-)}var(n) ])(
-Removes a entry from the directory stack, and perform a tt(cd) to
-the new top directory. With no argument, the current top entry is
+Remove an entry from the directory stack, and perform a tt(cd) to
+the new top directory.  With no argument, the current top entry is
 removed.  An argument of the form `tt(PLUS())var(n)' identifies a stack
 entry by counting from the left of the list shown by the tt(dirs) command,
 starting with zero.  An argument of the form tt(-n) counts from the right.
@@ -531,7 +624,7 @@ If the tt(PUSHD_MINUS) option is set, the meanings of `tt(PLUS())' and
 `tt(-)' in this context are swapped.
 )
 findex(print)
-item(tt(print) [ tt(-nrslzpNDPoOicm) ] [ tt(-u)var(n) ] [ tt(-R) [ tt(-en) ]] [ var(arg) ... ])(
+item(tt(print) [ tt(-bnrslzpNDPoOicm) ] [ tt(-u)var(n) ] [ tt(-R) [ tt(-en) ]] [ var(arg) ... ])(
 With no flags or with flag `tt(-)', the arguments are printed on
 the standard output as described by tt(echo), with the following differences:
 the escape sequence `tt(\M-)var(x)' metafies the character
@@ -551,6 +644,13 @@ unless the tt(-e) flag is given.  The tt(-n) flag suppresses the trailing
 newline.  Only the tt(-e) and tt(-n) flags are recognized after
 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))\
+.
+)
 item(tt(-m))(
 Take the first argument as a pattern (should be quoted), and remove
 it from the argument list together with subsequent arguments that
@@ -575,8 +675,8 @@ item(tt(-O))(
 Print the arguments sorted in descending order.
 )
 item(tt(-i))(
-If given together with tt(-o) or tt(-O), makes them work case
-independently.
+If given together with tt(-o) or tt(-O), sorting is performed
+case-independently.
 )
 item(tt(-c))(
 Print the arguments in columns.
@@ -615,21 +715,9 @@ If var(arg) is not specified, change to the second directory
 on the stack (that is, exchange the top two entries), or
 change to tt($HOME) if the tt(PUSHD_TO_HOME)
 option is set or if there is only one entry on the stack.
-
-If var(arg) is `tt(-)', change to tt($OLDPWD), the previous directory.
-If a directory named var(arg) is not found in the current directory
-and var(arg) does not contain a slash,
-search each component of the shell parameter tt(cdpath).
-If the option tt(CDABLE_VARS) is set, and a parameter named var(arg)
-exists whose value begins with a slash, treat its value as
-the directory.
-
-If the option tt(PUSHD_SILENT) is not set, the directory
-stack will be printed after a tt(pushd) is performed.
-
-The second form of tt(pushd) substitutes the string var(new)
-for the string var(old) in the name of the current directory,
-and tries to change to this new directory.
+Otherwise, var(arg) is interpreted as it would be by tt(cd).
+The meaning of var(old) and var(new) in the second form is also
+the same as for tt(cd).
 
 The third form of tt(pushd) changes directory by rotating the
 directory list.  An argument of the form `tt(PLUS())var(n)' identifies a stack
@@ -637,6 +725,9 @@ entry by counting from the left of the list shown by the tt(dirs)
 command, starting with zero.  An argument of the form `tt(-)var(n)' counts
 from the right.  If the tt(PUSHD_MINUS) option is set, the meanings
 of `tt(PLUS())' and `tt(-)' in this context are swapped.
+
+If the option tt(PUSHD_SILENT) is not set, the directory
+stack will be printed after a tt(pushd) is performed.
 )
 findex(pushln)
 item(tt(pushln) [ var(arg) ... ])(
@@ -672,12 +763,16 @@ Read only one character from the terminal and set var(name) to
 With this flag set the return value is zero only if the character was
 `tt(y)' or `tt(Y)'.  Note that this always reads from the terminal, even
 if used with the tt(-p) or tt(-u) or tt(-z) flags or with redirected input.
+This option may also be used within zle widgets.
 )
 item(tt(-k) [ var(num) ])(
 Read only one (or var(num)) characters.  All are assigned to the first
 var(name), without word splitting.  This flag is ignored when tt(-q) is
 present.  Input is read from the terminal unless one of tt(-u) or tt(-p)
-is present.
+is present.  This option may also be used within zle widgets.
+
+Note that var(num) must be in the argument word that follows tt(-k), not
+in the same word.  See tt(-u).
 )
 item(tt(-z))(
 Read one entry from the editor buffer stack and assign it to the first
@@ -714,7 +809,8 @@ and that when the cursor is at the end of the line, its character
 index is the length of the line plus one.
 )
 item(tt(-u)var(n))(
-Input is read from file descriptor var(n).
+Input is read from file descriptor var(n), where var(n) is a single
+digit and must em(not) be separated from tt(-u) by any whitespace.
 )
 item(tt(-p))(
 Input is read from the coprocess.
@@ -727,7 +823,8 @@ is interactive.
 
 The value (exit status) of tt(read) is 1 when an end-of-file is
 encountered, or when tt(-c) or tt(-l) is present and the command is
-not called from a tt(compctl) function.  Otherwise the value is 0.
+not called from a tt(compctl) function, or as described for tt(-q).
+Otherwise the value is 0.
 
 The behavior of some combinations of the tt(-k), tt(-p), tt(-q), tt(-u)
 and tt(-z) flags is undefined.  Presently tt(-q) cancels all the others,
@@ -757,6 +854,7 @@ trap is passed as the first argument, so the statement `tt(return
 $((128PLUS()$1)))' will return the same status as if the signal had not
 been trapped.
 )
+module(sched)(zsh/sched)
 findex(set)
 cindex(parameters, listing)
 cindex(parameters, positional)
@@ -781,6 +879,7 @@ given, then the names and values of all parameters are printed on the
 standard output.  If the only argument is `tt(PLUS())',
 the names of all parameters are printed.
 )
+module(setcap)(zsh/cap)
 findex(setopt)
 cindex(options, setting)
 item(tt(setopt) [ {tt(PLUS())|tt(-)}var(options) | \
@@ -789,8 +888,8 @@ Set the options for the shell.  All options specified either
 with flags or by name are set.  If no arguments are supplied,
 the names of all options currently set are printed.
 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 set.
+(which should be quoted to protect them from filename expansion), and all
+options with names matching these patterns are set.
 )
 findex(shift)
 cindex(parameters, positional)
@@ -806,6 +905,7 @@ item(tt(source) var(file) [ var(arg) ... ])(
 Same as tt(.), except that the current directory is always searched and
 is always searched first, before directories in tt($path).
 )
+module(stat)(zsh/stat)
 findex(suspend)
 cindex(shell, suspending)
 cindex(suspending the shell)
@@ -831,11 +931,12 @@ findex(trap)
 cindex(signals, trapping)
 cindex(trapping signals)
 item(tt(trap) [ var(arg) [ var(sig) ... ] ])(
-var(arg) is a command to be read and executed when the shell
+var(arg) is a series of commands (usually quoted to protect it from
+immediate evaluation by the shell) to be read and executed when the shell
 receives var(sig).  Each var(sig) can be given as a number
 or as the name of a signal.
 If var(arg) is `tt(-)', then all traps var(sig) are reset to their
-default values.  If var(arg) is the null string, then this signal
+default values.  If var(arg) is the empty string, then this signal
 is ignored by the shell and by the commands it invokes.
 
 If var(sig) is tt(ZERR) then var(arg) will be executed
@@ -851,6 +952,20 @@ then the command var(arg) is executed when the shell terminates.
 
 The tt(trap) command with no arguments prints a list of commands
 associated with each signal.
+
+Note that traps defined with the tt(trap) builtin are slightly different
+from those defined as `tt(TRAP)var(NAL) () { ... }', as the latter have
+their own function environment (line numbers, local variables, etc.) while
+the former use the environment of the command in which they were called.
+For example,
+
+example(trap 'print $LINENO' DEBUG)
+
+will print the line number of a command executed after it has run, while
+
+example(TRAPDEBUG() { print $LINENO; })
+
+will always print the number zero.
 )
 findex(true)
 cindex(doing nothing, successfully)
@@ -876,21 +991,83 @@ Equivalent to tt(whence -v).
 findex(typeset)
 cindex(parameters, setting)
 cindex(parameters, declaring)
-item(tt(typeset) [ {tt(PLUS())|tt(-)}tt(LRUZfilrtuxm) [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:
+xitem(tt(typeset) [ {tt(PLUS())|tt(-)}tt(AEFLRUZafghilrtuxm) [var(n)]] [ \
+var(name)[tt(=)var(value)] ... ])
+item(tt(typeset) -T [ {tt(PLUS()|tt(-))}tt(LRUZrux) ] \
+  var(SCALAR)[tt(=)var(value)] var(array))(
+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 exist.  The same rules apply to special shell parameters, which
+retain their special attributes when made local.
+
+For each 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, only scalars and integers.
+
+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, or if any attribute flags
+listed below are given.  Using `tt(PLUS())' instead of minus to introduce
+an attribute turns it off.
+
+If the tt(-T) option is given, exactly two (or zero) var(name)
+arguments must be present.  They represent a scalar and an array (in
+that order) that will be tied together in the manner of tt($PATH) and
+tt($path).  In other words, an array present in the latter variable
+appears as a scalar with the elements of the array joined by colons in
+the former.  Only the scalar may have an initial value.  Both the
+scalar and the array may otherwise be manipulated as normal.  If one
+is unset, the other will automatically be unset too.  There is no way
+of untying the variables without unsetting them, or converting the
+type of one them with another tt(typeset) command; tt(+T) does not work,
+assigning an array to var(SCALAR) is an error, and assigning a scalar
+to var(array) sets it to be a single-element array.  Note that
+both tt(typeset -xT ...) and tt(export -T ...) work, but only the
+scalar will be marked for export.
+
+The flag tt(-g) (global) flag is treated specially: it means that any
+resulting parameter will not be restricted to local scope.  Note that this
+does not necessarily mean that the parameter will be global, as the flag
+will apply to any existing parameter (even if unset) from an enclosing
+function.  This flag does not affect the parameter after creation, hence it
+has no effect when listing existing parameters, nor does the flag tt(+g)
+have any effect.
+
+If no var(name) is present, the names and values of all parameters are
+printed.  In this case the attribute flags restrict the display to only
+those parameters that have the specified attributes, and using `tt(PLUS())'
+rather than `tt(-)' to introduce the flag suppresses printing of the values
+of parameters when there is no parameter name.  Also, if the option list
+ends with `tt(PLUS())', values will not be printed.  If only the tt(-m)
+flag is given the arguments are taken as patterns (which should be quoted)
+and all parameters (or functions with the tt(-f) flag) with matching names
+are printed.  If no attribute flags and no tt(-m) flag is present, the
+parameter names will be preceded by a list of any attributes (tt(array),
+tt(association), tt(exported), tt(integer), tt(readonly)).
+
+The following attribute flags may be specified:
 
 startitem()
+item(tt(-A))(
+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.
 )
@@ -899,13 +1076,14 @@ Right justify and fill with leading blanks.  If var(n) is nonzero
 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.
+This flag has a different meaning when used with tt(-f); see below.
 )
 item(tt(-Z))(
 Right justify and fill with leading zeros if the first non-blank
@@ -914,51 +1092,83 @@ 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.
 )
+item(tt(-a))(
+The names refer to array parameters.  An array parameter may be
+created this way, but it may not be assigned to in the tt(typeset)
+statement.  When displaying, both normal and associative arrays are
+shown.
+)
 item(tt(-f))(
 The names refer to functions rather than parameters.  No assignments
-can be made, and the only other valid flags are tt(-t)
-and tt(-u).  The flag tt(-t) turns on execution tracing for this
-function.  The flag tt(-u) causes this function to be marked
-for autoloading.  The tt(fpath) parameter will be searched to find the
-function definition when the function is first referenced; see
-noderef(Functions).
+can be made, and the only other valid flags are tt(-t), tt(-u) and
+tt(-U).  The flag tt(-t) turns on execution tracing for this
+function.  The tt(-u) and tt(-U) flags cause the function to be
+marked for autoloading; tt(-U) also causes alias expansion to be
+suppressed when the function is loaded.  The tt(fpath) parameter
+will be searched to find the function definition when the function
+is first referenced; see noderef(Functions).
+)
+item(tt(-h))(
+Hide: only useful for special parameters (those marked `<S>' in the table in
+ifzman(zmanref(zshparams))\
+ifnzman(noderef(Parameters))\
+), and for local parameters with the same name as a special parameter,
+though harmless for others.  A special parameter with this attribute will
+not retain its special effect when made local.  Thus after `tt(typeset -h
+PATH)', a function containing `tt(typeset PATH)' will create an ordinary
+local parameter without the usual behaviour of tt(PATH).  Alternatively,
+the local parameter may itself be given this attribute; hence inside a
+function `tt(typeset -h PATH)' creates an ordinary local parameter and the
+special tt(PATH) parameter is not altered in any way.  It is also possible
+to create a local parameter using `tt(typeset +h )var(special)', where the
+local copy of var(special) will retain its special properties regardless of
+having the tt(-h) attribute.  Global special parameters loaded from shell
+modules (currently those in tt(mapfile) and tt(parameter)) are
+automatically given the tt(-h) attribute to avoid name clashes.
 )
 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(-E))(
+Use an internal double-precision floating point representation.  On output
+the variable will be converted to scientific notation.  If var(n) is
+nonzero it defines the number of significant figures to display; the
+default is ten.
+)
+item(tt(-F))(
+Use an internal double-precision floating point representation.  On output
+the variable will be converted to fixed-point decimal notation.  If var(n)
+is nonzero it defines the number of digits to display after the decimal
+point; the default is ten.
 )
 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.
 )
 item(tt(-t))(
 Tags the named parameters.  Tags have no special meaning to the shell.
+This flag has a different meaning when used with tt(-f); see above.
 )
 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.
+This flag has a different meaning when used with tt(-f); see above.
 )
 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)
 cindex(limits, resource)
-item(tt(ulimit) [ tt(-SHacdflmnpstv) [ tt(limit) ] ... ])(
+item(tt(ulimit) [ tt(-SHacdflmnpstv) [ var(limit) ] ... ])(
 Set or display resource limits of the shell and the processes started by
 the shell.  The value of var(limit) can be a number in the unit specified
 below or the value `tt(unlimited)'.  If the tt(-H) flag is given use
@@ -1025,10 +1235,16 @@ Each named parameter is unset.
 Local parameters remain local even if unset; they appear unset within scope,
 but the previous value will still reappear when the scope ends.
 
-If the tt(-m) flag is specified the
-arguments are taken as patterns (should be quoted) and all parameters
-with matching names are unset.  tt(unset -f) is equivalent to
-tt(unfunction).
+Individual elements of associative array parameters may be unset by using
+subscript syntax on var(name), which should be quoted (or the entire command
+prefixed with tt(noglob)) to protect the subscript from filename generation.
+
+If the tt(-m) flag is specified the arguments are taken as patterns (should
+be quoted) and all parameters with matching names are unset.  Note that this
+cannot be used when unsetting associative array elements, as the subscript
+will be treated as part of the pattern.
+
+tt(unset -f) is equivalent to tt(unfunction).
 )
 findex(unsetopt)
 cindex(options, unsetting)
@@ -1041,6 +1257,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)
 findex(wait)
 cindex(waiting for jobs)
 cindex(jobs, waiting for)
@@ -1105,33 +1322,153 @@ findex(which)
 item(tt(which) [ tt(-wpams) ] var(name) ...)(
 Equivalent to tt(whence -c).
 )
+findex(zcompile)
+cindex(.zwc files, creation)
+cindex(compilation)
+xitem(tt(zcompile) [ tt(-U) ] [ tt(-z) | tt(-k) ] [ tt(-R) | tt(-M) ] var(file) [ var(name) ... ])
+xitem(tt(zcompile) tt(-ca) [ tt(-m) ] [ tt(-R) | tt(-M) ] var(file) [ var(name) ... ])
+item(tt(zcompile -t) var(file) [ var(name) ... ])(
+This builtin command can be used to compile functions or scripts and
+store the compiled form in a file, and to examine files containing
+the compiled form.  This allows faster autoloading of functions and
+execution of scripts by avoiding parsing of the text when the files
+are read.
+
+The first form (without the tt(-c), tt(-a) or tt(-t) options) creates a
+compiled file.  If only the var(file) argument is provided, the
+output file has the name `var(file)tt(.zwc)' and will be placed in
+the same directory as the var(file).  This will make the compiled
+file be loaded instead of the normal function file when the function
+is autoloaded (see
+ifzman(\
+the section `Autoloading Functions' in zmanref(zshfunc)
+)\
+ifnzman(\
+noderef(Functions)
+)\
+for a description of how autoloaded functions are searched).  The
+extension tt(.zwc) stands for `zsh word codes'.
+
+If there is at least one var(name) argument, all those named files
+are compiled into one output var(file).  If var(file) does not end
+in tt(.zwc), this extension is automatically appended.  Files
+containing multiple compiled functions are called `digest' files,
+and are intended to be used as elements of the tt(FPATH)/tt(fpath)
+special array.
+
+The second form, with the tt(-c) or tt(-a) options, writes the compiled
+definitions for all the named functions into var(file).  For tt(-c), the
+names must be functions currently defined in the shell, not those marked
+for autoloading.  Undefined functions that are marked for autoloading
+may be written by using the tt(-a) option, in which case the tt(fpath)
+is searched and the contents of the definition files for those
+functions, if found, are compiled into var(file).  If both tt(-c) and
+tt(-a) are given, names of both defined functions and functions marked
+for autoloading may be given.  In either case, the functions in files
+written with the tt(-c) or tt(-a) option will be autoloaded as if the
+tt(KSH_AUTOLOAD) option were unset.
+
+The reason for handling loaded and not-yet-loaded functions with
+different options is that some definition files for autoloading define
+multiple functions, including the function with the same name as the
+file, and, at the end, call that function.  In such cases the output of
+`tt(zcompile -c)' does not include the additional functions defined in
+the file, and any other initialization code in the file is lost.  Using
+`tt(zcompile -a)' captures all this extra information.
+
+If the tt(-m) option is combined with tt(-c) or tt(-a),
+the var(name)s are used as patterns and all functions whose names
+match one of these patterns will be written. If no var(name) is given,
+the definitions of all functions currently defined or marked as
+autoloaded will be written.
+
+The third form, with the tt(-t) option, examines an existing
+compiled file.  Without further arguments, the names of the original
+files compiled into it are listed.  The first line of output tells
+the version of the shell which compiled the file and how the file
+will be used (mapping or reading the file).  With arguments, nothing
+is output and the return value is set to zero if em(all) var(name)s
+name files contained in the wordcode file, and non-zero if at least
+one var(name) is not contained in it.
+
+Other options:
+
+startitem()
+item(tt(-U))(
+Aliases are not expanded when compiling the var(name)d files.
+)
+item(tt(-R))(
+When the compiled file is read, its contents are copied into the
+shell's memory, rather than memory-mapped (see tt(-M)).  This
+happens automatically on systems that do not support memory mapping.
+
+When compiling scripts instead of autoloadable functions, it is
+often desirable to use this option. Otherwise the whole file will
+remain mapped if the script has defined one or more functions, even
+if the rest of the file will not be used again.
+)
+item(tt(-M))(
+The compiled file is mapped into the shell's memory when read. This
+is done in such a way that multiple instances of the shell running
+on the same host will share this mapped file.  If neither tt(-R) nor
+tt(-M) is given, the tt(zcompile) builtin decides what to do based
+on the size of the compiled file.
+)
+xitem(tt(-k))
+item(tt(-z))(
+These options are used when the compiled file contains functions and
+those functions are to be autoloaded. If tt(-z) is given, the
+function will be autoloaded as if the tt(KSH_AUTOLOAD) option is
+em(not) set, even if it is set at the time the compiled file is
+read. The tt(-k) makes the function be loaded as if tt(KSH_AUTOLOAD)
+em(is) set.  If neither of these options is given, the function will
+be loaded as determined by the setting of the tt(KSH_AUTOLOAD) option
+at the time the compiled file is read.
+
+These options may also be repeated among the listed var(name)s to
+specify the loading style of all following functions, up to the next
+tt(-k) or tt(-z).
+)
+enditem()
+
+The created file always contains two versions of the compiled
+format, one for big-endian machines and one for small-endian
+machines. The upshot of this is that the compiled file is machine
+independent and if it is read or mapped, only one half of the file
+is actually used (and mapped).
+)
+module(zformat)(zsh/zutil)
+module(zftp)(zsh/zftp)
+module(zle)(zsh/zle)
 findex(zmodload)
 cindex(modules, loading)
 cindex(loading modules)
-xitem(tt(zmodload) [ tt(-iL) ] [ var(name) ... ])
-xitem(tt(zmodload) tt(-u) [ tt(-i) ] var(name) ...)
-xitem(tt(zmodload) tt(-d) [ tt(-L) ] [ var(name) [ var(dep) ... ] ])
-xitem(tt(zmodload) tt(-du) var(name) [ var(dep) ... ])
-xitem(tt(zmodload) tt(-a) [ tt(-iL) ] [ var(name) [ var(builtin) ... ] ])
-item(tt(zmodload) tt(-au) [ tt(-i) ] var(builtin) ...)(
-tt(zmodload) performs operations relating to zsh's loadable modules.
+xitem(tt(zmodload) [ tt(-dL) ] [ ... ])
+xitem(tt(zmodload -e) [ ... ])
+xitem(tt(zmodload) [ tt(-a) [ tt(-bcpf) [ tt(-I) ] ] ] [ tt(-iL) ] ...)
+item(tt(zmodload) tt(-u) [ tt(-abcdpf) [ tt(-I) ] ] [ tt(-iL) ] ...)(
+Performs operations relating to zsh's loadable modules.
 This feature is not available on all operating systems,
 or on all installations on a particular operating system.
 
-In the simplest case,
-tt(zmodload) loads a binary module.  The module must be in a file with a
-name consisting of the specified var(name) followed by a standard suffix,
-usually `tt(.so)'.  If this can't be found, the var(name) is tried without
-the suffix.
-If the module to be loaded is already loaded and the tt(-i)
-option is given, the duplicate module is ignored.  Otherwise
-tt(zmodload) prints an error message.
+Without arguments the names of all currently loaded binary modules are
+printed.  The tt(-L) option causes this list to be in the form of a
+series of tt(zmodload) commands.  Forms with arguments are:
+
+startitem()
+xitem(tt(zmodload) [ tt(-i) ] var(name) ... )
+item(tt(zmodload) tt(-u) [ tt(-i) ] var(name) ...)(
+In the simplest case, tt(zmodload) loads a binary module.  The module must
+be in a file with a name consisting of the specified var(name) followed by
+a standard suffix, usually `tt(.so)'.
+If the module to be loaded is
+already loaded and the tt(-i) option is given, the duplicate module is
+ignored.  Otherwise tt(zmodload) prints an error message.
 
 The var(name)d module is searched for in the same way a command is, using
-tt($module_path) instead of tt($path).  If var(name) contains a `tt(/)',
-it will be used as-is, and a path search will be performed otherwise.
-This behaviour can be modified by the tt(PATH_DIRS) option.
-cindex(PATH_DIRS, use of)
+tt($module_path) instead of tt($path).  However, the path search is
+performed even when the module name contains a `tt(/)', which it usually does.
+There is no way to prevent the path search.
 
 With tt(-u), tt(zmodload) unloads modules.  The same var(name)
 must be given that was given when the module was loaded, but it is not
@@ -1142,43 +1479,92 @@ unloaded (or was never loaded).
 Each module has a boot and a cleanup function.  The module
 will not be loaded if its boot function fails.  Similarly a module
 can only be unloaded if its cleanup function runs successfully.
+)
+xitem(tt(zmodload) tt(-d) [ tt(-L) ] [ var(name) ])
+xitem(tt(zmodload) tt(-d) var(name) var(dep) ...)
+item(tt(zmodload) tt(-ud) var(name) [ var(dep) ... ])(
+The tt(-d) option can be used to specify module dependencies.  The modules
+named in the second and subsequent arguments will be loaded before the
+module named in the first argument.
+
+With tt(-d) and one argument, all dependencies for that module are listed.
+With tt(-d) and no arguments, all module dependencies are listed.  This
+listing is by default in a Makefile-like format.  The tt(-L) option
+changes this format to a list of tt(zmodload -d) commands.
+
+If tt(-d) and tt(-u) are both used, dependencies are removed.  If only one
+argument is given, all dependencies for that module are removed.
+)
+xitem(tt(zmodload) tt(-ab) [ tt(-L) ])
+xitem(tt(zmodload) tt(-ab) [ tt(-i) ] var(name) [ var(builtin) ... ])
+item(tt(zmodload) tt(-ub) [ tt(-i) ] var(builtin) ...)(
+The tt(-ab) option defines autoloaded builtins.  It defines the specified
+var(builtin)s.  When any of those builtins is called, the module specified
+in the first argument is loaded.  If only the var(name) is given, one
+builtin is defined, with the same name as the module.  tt(-i) suppresses
+the error if the builtin is already defined or autoloaded, regardless of
+which module it came from.
 
-Without arguments all currently loaded binary modules are printed.
-The tt(-L) option causes this list to be in the form of a series of
-tt(zmodload) commands.
-
-The tt(-d) option can be used to specify module dependencies.
-This operation is idempotent regardless of the tt(-i) option.
-The modules named in the second and subsequent arguments will be
-loaded before the module named in the first argument.
-
-With tt(-d) and one
-argument, all dependencies for that module are listed.  With tt(-d) and no
-arguments, all module dependencies are listed.
-This listing is by default in a Makefile-like format.
-The tt(-L) option changes this format to a list of
-tt(zmodload -d) commands.
-
-If tt(-d) and tt(-u) are both used, dependencies are removed.
-This operation is idempotent regardless of the tt(-i) option.
-If only one argument is given, all dependencies for that module are removed.
-
-The tt(-a) option defines autoloaded builtins.  It defines the
-specified var(builtin)s.  When any of those builtins is called, the module
-specified in the first argument is loaded.  If only one argument is given,
-one builtin is defined, with the same name as the module.
-tt(-i) suppresses the error if the builtin is already defined or
-autoloaded, regardless of which module it came from.
-
-With tt(-a) and no arguments, all
-autoloaded builtins are listed, with the module name (if different)
-shown in parentheses after the builtin name.  The tt(-L) option changes
-this format to a list of tt(zmodload -a) commands.
-
-If tt(-a) is used
-together with the tt(-u) option it removes builtins defined with
-tt(zmodload -a).  This is only possible if the builtin is not yet
-loaded.  tt(-i) suppresses the error if the builtin is already
+With tt(-ab) and no arguments, all autoloaded builtins are listed, with the
+module name (if different) shown in parentheses after the builtin name.
+The tt(-L) option changes this format to a list of tt(zmodload -a)
+commands.
+
+If tt(-b) is used together with the tt(-u) option, it removes builtins
+previously defined with tt(-ab).  This is only possible if the builtin is
+not yet loaded.  tt(-i) suppresses the error if the builtin is already
 removed (or never existed).
 )
+xitem(tt(zmodload) tt(-ac) [ tt(-IL) ])
+xitem(tt(zmodload) tt(-ac) [ tt(-iI) ] var(name) [ var(cond) ... ])
+item(tt(zmodload) tt(-uc) [ tt(-iI) ] var(cond) ...)(
+The tt(-ac) option is used to define autoloaded condition codes. The
+var(cond) strings give the names of the conditions defined by the
+module. The optional tt(-I) option is used to define infix condition
+names. Without this option prefix condition names are defined.
+
+If given no condition names, all defined names are listed (as a series of
+tt(zmodload) commands if the tt(-L) option is given).
+
+The tt(-uc) option removes definitions for autoloaded conditions.
+)
+xitem(tt(zmodload) tt(-ap) [ tt(-L) ])
+xitem(tt(zmodload) tt(-ap) [ tt(-i) ] var(name) [ var(parameter) ... ])
+item(tt(zmodload) tt(-up) [ tt(-i) ] var(parameter) ...)(
+The tt(-p) option is like the tt(-b) and tt(-c) options, but makes
+tt(zmodload) work on autoloaded parameters instead.
+)
+xitem(tt(zmodload) tt(-af) [ tt(-L) ])
+xitem(tt(zmodload) tt(-af) [ tt(-i) ] var(name) [ var(function) ... ])
+item(tt(zmodload) tt(-uf) [ tt(-i) ] var(function) ...)(
+The tt(-f) option is like the tt(-b), tt(-p), and tt(-c) options, but
+makes tt(zmodload) work on autoloaded math functions instead. 
+)
+xitem(tt(zmodload) tt(-a) [ tt(-L) ])
+xitem(tt(zmodload) tt(-a) [ tt(-i) ] var(name) [ var(builtin) ... ])
+item(tt(zmodload) tt(-ua) [ tt(-i) ] var(builtin) ...)(
+Equivalent to tt(-ab) and tt(-ub).
+)
+item(tt(zmodload -e) [ var(string) ... ])(
+The tt(-e) option without arguments lists all loaded modules.
+With arguments only the return status is set to zero
+if all var(string)s given as arguments are names of loaded modules
+and to one if at least on var(string) is not the name of a
+loaded module. This can be used to test for the availability 
+of things implemented by modules.
+)
+enditem()
+
+Note that tt(zsh) makes no distinction between modules that were linked 
+into the shell and modules that are loaded dynamically. In both cases
+this builtin command has to be used to make available the builtins and
+other things defined by modules (unless the module is autoloaded on
+these definitions). This is true even for systems that don't support
+dynamic loading of modules.
+)
+module(zparseopts)(zsh/zutil)
+module(zprof)(zsh/zprof)
+module(zpty)(zsh/zpty)
+module(zregexparse)(zsh/zutil)
+module(zstyle)(zsh/zutil)
 enditem()
diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo
index a78a18fa9..f25ddda98 100644
--- a/Doc/Zsh/compctl.yo
+++ b/Doc/Zsh/compctl.yo
@@ -1,7 +1,25 @@
-texinode(Programmable Completion)(Zsh Modules)(Zsh Line Editor)(Top)
-chapter(Programmable Completion)
+texinode(Completion Using compctl)(Completion Widgets)(Zsh Line Editor)(Top)
+chapter(Completion Using compctl)
 cindex(completion, programmable)
 cindex(completion, controlling)
+ifzman(\
+sect(Synopsis)
+This version of zsh has two ways of performing completion of words on the
+command line.  New users of the shell may prefer to use the newer
+and more powerful system based on shell functions; this is described in
+zmanref(zshcompsys), and the basic shell mechanisms which support it are
+described in zmanref(zshcompwid).  This manual entry describes the older
+tt(compctl) command.
+)\
+ifnzman(\
+sect(Types of completion)
+This version of zsh has two ways of performing completion of words on the
+command line.  New users of the shell may prefer to use the newer
+and more powerful system based on shell functions; this is described
+in noderef(Completion System), and the basic shell mechanisms which support
+it are described in noderef(Completion Widgets).  This chapter describes
+the older tt(compctl) command.
+)\
 findex(compctl)
 sect(Description)
 startlist()
@@ -10,7 +28,8 @@ list(tt(compctl) [ tt(-CDT) ] var(options) \
   [ tt(-x) var(pattern) var(options) tt(-) ... tt(--) ] \
   [ tt(PLUS()) var(options) [ tt(-x) ... tt(--) ] ... [tt(PLUS())] ] \
   [ var(command) ... ])
-list(tt(compctl) tt(-L) [ tt(-CDT) ] [ var(command) ... ])
+list(tt(compctl) tt(-M) var(match-specs) ...)
+list(tt(compctl) tt(-L) [ tt(-CDTM) ] [ var(command) ... ])
 list(tt(compctl) tt(PLUS()) var(command) ...)
 endlist()
 
@@ -30,7 +49,8 @@ menu(Alternative Completion)
 menu(Extended Completion)
 menu(Example)
 endmenu()
-texinode(Command Flags)(Option Flags)()(Programmable Completion)
+
+texinode(Command Flags)(Option Flags)()(Completion Using compctl)
 sect(Command Flags)
 Completion of the arguments of a command may be different for each
 command or may use the default.  The behavior when completing the
@@ -44,9 +64,23 @@ item(var(command) ...)(
 controls completion for the named commands, which must be listed last
 on the command line.  If completion is attempted for a command with a
 pathname containing slashes and no completion definition is found, the
-search is retried with the last pathname component.  Note that aliases
+search is retried with the last pathname component. If the command starts
+with a tt(=), completion is tried with the pathname of the command.
+
+Any of the var(command) strings may be patterns of the form normally
+used for filename generation.  These should be be quoted to protect them
+from immediate expansion; for example the command string tt('foo*')
+arranges for completion of the words of any command beginning with
+tt(foo).  When completion is attempted, all pattern completions are
+tried in the reverse order of their definition until one matches.  By
+default, completion then proceeds as normal, i.e. the shell will try to
+generate more matches for the specific command on the command line; this
+can be overridden by including tt(-tn) in the flags for the pattern
+completion.
+
+Note that aliases
 are expanded before the command name is determined unless the
-tt(COMPLETE_ALIASES) option is set.  Commands should not be combined
+tt(COMPLETE_ALIASES) option is set.  Commands may not be combined
 with the tt(-C), tt(-D) or tt(-T) flags.
 )
 item(tt(-C))(
@@ -62,8 +96,8 @@ been issued, filenames are completed.
 )
 item(tt(-T))(
 supplies completion flags to be used before any other processing is
-done, even those given to specific commands with other compctl
-definitions.  This is only useful when combined with extended
+done, even before processing for tt(compctl)s defined for specific
+commands.  This is especially useful when combined with extended
 completion (the tt(-x) flag, see noderef(Extended Completion) below).
 Using this flag you can define default behavior
 which will apply to all commands without exception, or you can alter
@@ -71,41 +105,59 @@ the standard behavior for all commands.  For example, if your access
 to the user database is too slow and/or it contains too many users (so
 that completion after `tt(~)' is too slow to be usable), you can use
 
-nofill(tt(compctl -Tx  'C[0,*/*]' -f - 's[~]' -k friends -S/))
+example(compctl -T -x 's[~] C[0,[^/]#]' -k friends -S/ -tn)
 
 to complete the strings in the array tt(friends) after a `tt(~)'.
-The first argument is necessary so that this form of ~-completion is
+The tt(C[...]) argument is necessary so that this form of ~-completion is
 not tried after the directory name is finished.
 )
 item(tt(-L))(
 lists the existing completion behavior in a manner suitable for
 putting into a start-up script; the existing behavior is not changed.
-Any combination of the above forms may be specified, otherwise all
-defined completions are listed.  Any other flags supplied
-are ignored.
+Any combination of the above forms, or the tt(-M) flag (which must
+follow the tt(-L) flag), may be specified, otherwise all defined
+completions are listed.  Any other flags supplied are ignored.
 )
 item(em(no argument))(
 If no argument is given, tt(compctl) lists all defined completions
 in an abbreviated form;  with a list of var(options), all completions
 with those flags set (not counting extended completion) are listed.
 )
-endlist()
+enditem()
 
 If the tt(PLUS()) flag is alone and followed immediately by the var(command)
 list, the completion behavior for all the commands in the list is reset to
 the default.  In other words, completion will subsequently use the
 options specified by the tt(-D) flag.
-texinode(Option Flags)(Alternative Completion)(Command Flags)(Programmable Completion)
+
+The form with tt(-M) as the first and only option defines global
+matching specifications (see
+ifzman(zshcompwid)\
+ifnzman(noderef(Matching Control))\
+). The match specifications given will be used for every completion
+attempt (only when using tt(compctl), not with the new completion
+system) and are tried in the order in which they are defined until one 
+generates at least one match. E.g.:
+
+example(compctl -M '' 'm:{a-zA-Z}={A-Za-z}')
+
+This will first try completion without any global match specifications 
+(the empty string) and, if that generates no matches, will try case
+insensitive completion.
+
+texinode(Option Flags)(Alternative Completion)(Command Flags)(Completion Using compctl)
 sect(Option Flags)
 startlist()
-list([ tt(-fcFBdeaRGovNAIOPZEnbjrzu/) ])
+list([ tt(-fcFBdeaRGovNAIOPZEnbjrzu/12) ])
 list([ tt(-k) var(array) ] [ tt(-g) var(globstring) ] \
   [ tt(-s) var(subststring) ])
-list([ tt(-K) var(function) ] [ tt(-H) var(num pattern) ])
+list([ tt(-K) var(function) ])
 list([ tt(-Q) ] [ tt(-P) var(prefix) ] [ tt(-S) var(suffix) ])
-list([ tt(-W) var(file-prefix) ])
+list([ tt(-W) var(file-prefix) ] [ tt(-H) var(num pattern) ])
 list([ tt(-q) ] [ tt(-X) var(explanation) ] [ tt(-Y) var(explanation) ])
-list([ tt(-y) var(func-or-var) ] [ tt(-l) var(cmd) ] [ tt(-U) ])
+list([ tt(-y) var(func-or-var) ] [ tt(-l) var(cmd) ] [ tt(-h) var(cmd) ] [ tt(-U) ])
+list([ tt(-t) var(continue) ] [ tt(-J) var(name) ] [ tt(-V) var(name) ])
+list([ tt(-M) var(match-spec) ])
 endlist()
 
 The remaining var(options) specify the type of command arguments
@@ -117,6 +169,7 @@ menu(Simple Flags)
 menu(Flags with Arguments)
 menu(Control Flags)
 endmenu()
+
 texinode(Simple Flags)(Flags with Arguments)()(Option Flags)
 subsect(Simple Flags)
 These produce completion lists made up by the shell itself:
@@ -215,6 +268,7 @@ item(tt(-u))(
 User names.
 )
 enditem()
+
 texinode(Flags with Arguments)(Control Flags)(Simple Flags)(Option Flags)
 subsect(Flags with Arguments)
 These have user supplied arguments to determine how the list of
@@ -229,8 +283,8 @@ of space- or comma-separated values in parentheses, in which any
 delimiter may be escaped with a backslash; in this case the argument
 should be quoted.  For example,
 
-nofill(tt(compctl -k "(cputime filesize datasize stacksize
-    coredumpsize resident descriptors)" limit))
+example(compctl -k "(cputime filesize datasize stacksize
+	       coredumpsize resident descriptors)" limit)
 )
 item(tt(-g) var(globstring))(
 The var(globstring) is expanded using filename globbing; it should be
@@ -251,20 +305,21 @@ completions.  The tt(fignore) special parameter is not applied to the
 resulting files.  Note that tt(-g) is faster for filenames.
 )
 item(tt(-K) var(function))(
-Call the given function to get the completions.  The function is
+Call the given function to get the completions.  Unless the name
+starts with an underscore, the function is
 passed two arguments: the prefix and the suffix of the word on which
 completion is to be attempted, in other words those characters before
 the cursor position, and those from the cursor position onwards.  The
 whole command line can be accessed with the tt(-c) and tt(-l) flags
-of the tt(read) builtin.  The
+of the tt(read) builtin. The
 function should set the variable tt(reply) to an array containing
 the completions (one completion per element); note that tt(reply)
 should not be made local to the function.  From such a function the
 command line can be accessed with the tt(-c) and tt(-l) flags to
 the tt(read) builtin.  For example,
 
-nofill(tt(function whoson { reply=(`users`); }
-compctl -K whoson talk))
+example(function whoson { reply=(`users`); }
+compctl -K whoson talk)
 
 completes only logged-on users after `tt(talk)'.  Note that `tt(whoson)' must
 return an array, so `tt(reply=`users`)' would be incorrect.
@@ -276,12 +331,13 @@ zero or negative the whole history is searched and if var(pattern) is
 the empty string all words are taken (as with `tt(*)').  A typical
 use is
 
-nofill(tt(compctl -D -f PLUS() -H 0 ''))
+example(compctl -D -f PLUS() -H 0 '')
 
 which forces completion to look back in the history list for a word if
 no filename matches.
 )
 enditem()
+
 texinode(Control Flags)()(Flags with Arguments)(Option Flags)
 subsect(Control Flags)
 These do not directly specify types of name to be completed, but
@@ -303,7 +359,7 @@ The var(prefix) is inserted just before the completed string; any
 initial part already typed will be completed and the whole var(prefix)
 ignored for completion purposes.  For example,
 
-nofill(tt(compctl -j -P "%" kill))
+example(compctl -j -P "%" kill)
 
 inserts a `%' after the kill command and then completes job names.
 )
@@ -318,20 +374,25 @@ With directory var(file-prefix):  for command, file, directory and
 globbing completion (options tt(-c), tt(-f), tt(-/), tt(-g)), the file
 prefix is implicitly added in front of the completion.  For example,
 
-nofill(tt(compctl -/ -W ~/Mail maildirs))
+example(compctl -/ -W ~/Mail maildirs)
 
 completes any subdirectories to any depth beneath the directory
 tt(~/Mail), although that prefix does not appear on the command line.
+The var(file-prefix) may also be of the form accepted by the tt(-k)
+flag, i.e. the name of an array or a literal list in parenthesis. In
+this case all the directories in the list will be searched for
+possible completions.
 )
 item(tt(-q))(
 If used with a suffix as specified by the tt(-S) option, this
 causes the suffix to be removed if the next character typed is a blank
-or does not insert anything (the same rule as used for the
-tt(AUTO_REMOVE_SLASH) option).  The option is most useful for list
+or does not insert anything or if the suffix consists of only one character
+and the next character typed is the same character; this the same rule used
+for the tt(AUTO_REMOVE_SLASH) option.  The option is most useful for list
 separators (comma, colon, etc.).
 )
 item(tt(-l) var(cmd))(
-This option cannot be combined with any other.  It restricts the range
+This option restricts the range
 of command line words that are considered to be arguments.  If
 combined with one of the extended completion patterns `tt(p[)...tt(])',
 `tt(r[)...tt(])', or `tt(R[)...tt(])'  (see noderef(Extended Completion)
@@ -342,12 +403,21 @@ option. If the var(cmd) string is empty the first word in the range
 is instead taken as the command name, and command name completion
 performed on the first word in the range.  For example,
 
-nofill(tt(compctl -x 'r[-exec,;]' -l '' -- find))
+example(compctl -x 'r[-exec,;]' -l '' -- find)
 
 completes arguments between `tt(-exec)' and the following `tt(;)' (or the end
 of the command line if there is no such string) as if they were
 a separate command line.
 )
+item(tt(-h) var(cmd))(
+Normally zsh completes quoted strings as a whole. With this option,
+completion can be done separately on different parts of such
+strings. It works like the tt(-l) option but makes the completion code 
+work on the parts of the current word that are separated by
+spaces. These parts are completed as if they were arguments to the
+given var(cmd). If var(cmd) is the empty string, the first part is
+completed as a command name, as with tt(-l).
+)
 item(tt(-U))(
 Use the whole list of possible completions, whether or not they
 actually match the word on the command line.  The word typed so far
@@ -355,7 +425,10 @@ will be deleted.  This is most useful with a function (given by the
 tt(-K) option) which can examine the word components passed to it
 (or via the tt(read) builtin's tt(-c) and tt(-l) flags) and
 use its own criteria to decide what matches.  If there is no
-completion, the original word is retained.
+completion, the original word is retained.  Since the produced 
+possible completions seldom have interesting common prefixes
+and suffixes, menucompletion is started immediately if tt(AUTO_MENU) is
+set and this flag is used.
 )
 item(tt(-y) var(func-or-var))(
 The list provided by var(func-or-var) is displayed instead of the list
@@ -379,9 +452,22 @@ printed literally and if they appear output in columns is suppressed.
 )
 item(tt(-X) var(explanation))(
 Print var(explanation) when trying completion on the current set of
-options. A `tt(%n)' in this string is replaced by the number of matches.
+options. A `tt(%n)' in this string is replaced by the number of
+matches that were added for this explanation string.
 The explanation only appears if completion was tried and there was
-no unique match, or when listing completions.
+no unique match, or when listing completions. Explanation strings 
+will be listed together with the matches of the group specified
+together with the tt(-X) option (using the tt(-J) or tt(-V)
+option). If the same explanation string is given to multiple tt(-X)
+options, the string appears only once (for each group) and the number
+of matches shown for the `tt(%n)' is the total number of all matches
+for each of these uses. In any case, the explanation string will only
+be shown if there was at least one match added for the explanation
+string.
+
+The sequences tt(%B), tt(%b), tt(%S), tt(%s), tt(%U), and tt(%u) specify
+output attributes (bold, standout, and underline) and tt(%{...%}) can
+be used to include literal escape sequences as in prompts.
 )
 item(tt(-Y) var(explanation))(
 Identical to tt(-X), except that the var(explanation) first undergoes
@@ -389,8 +475,72 @@ expansion following the usual rules for strings in double quotes.
 The expansion will be carried out after any functions are called for
 the tt(-K) or tt(-y) options, allowing them to set variables.
 )
+item(tt(-t) var(continue))(
+The var(continue)-string contains a character that specifies which set
+of completion flags should be used next.  It is useful:
+
+(i) With tt(-T), or when trying a list of pattern completions, when
+tt(compctl) would usually continue with ordinary processing after
+finding matches; this can be suppressed with `tt(-tn)'.
+
+(ii) With a list of alternatives separated by tt(+), when tt(compctl)
+would normally stop when one of the alternatives generates matches.  It
+can be forced to consider the next set of completions by adding `tt(-t+)'
+to the flags of the alternative before the `tt(+)'.
+
+(iii) In an extended completion list (see below), when tt(compctl) would
+normally continue until a set of conditions succeeded, then use only
+the immediately following flags.  With `tt(-t-)', tt(compctl) will
+continue trying extended completions after the next `tt(-)'; with
+`tt(-tx)' it will attempt completion with the default flags, in other
+words those before the `tt(-x)'.
+)
+item(tt(-J) var(name))(
+This gives the name of the group the matches should be placed in. Groups
+are listed and sorted separately; likewise, menucompletion will offer
+the matches in the groups in the order in which the groups were
+defined. If no group name is explicitly given, the matches are stored in
+a group named var(default). The first time a group name is encountered,
+a group with that name is created. After that all matches with the same
+group name are stored in that group.
+
+This can be useful with non-exclusive alternative completions.  For
+example, in
+
+example(compctl -f -J files -t+ + -v -J variables foo)
+
+both files and variables are possible completions, as the tt(-t+) forces
+both sets of alternatives before and after the tt(+) to be considered at
+once.  Because of the tt(-J) options, however, all files are listed
+before all variables.
+)
+item(tt(-V) var(name))(
+Like tt(-J), but matches within the group will not be sorted in listings
+nor in menucompletion. These unsorted groups are in a different name
+space from the sorted ones, so groups defined as tt(-J files) and tt(-V
+files) are distinct.
+)
+item(tt(-1))(
+If given together with the tt(-V) option, makes
+only consecutive duplicates in the group be removed. Note that groups
+with and without this flag are in different name spaces.
+)
+item(tt(-2))(
+If given together with the tt(-J) or tt(-V) option, makes all
+duplicates be kept. Again, groups with and without this flag are in
+different name spaces.
+)
+item(tt(-M) var(match-spec))(
+This defines additional matching control specifications that should be used
+only when testing words for the list of flags this flag appears in. The format
+of the var(match-spec) string is described in 
+ifzman(zshcompwid)\
+ifnzman(noderef(Matching Control))\
+.
+)
 enditem()
-texinode(Alternative Completion)(Extended Completion)(Option Flags)(Programmable Completion)
+
+texinode(Alternative Completion)(Extended Completion)(Option Flags)(Completion Using compctl)
 sect(Alternative Completion)
 startlist()
 list(tt(compctl) [ tt(-CDT) ] var(options) tt(PLUS()) var(options) [ tt(PLUS()) ... ] \
@@ -402,16 +552,19 @@ tried with the options before the first `tt(PLUS())'. If this produces no
 matches completion is tried with the flags after the `tt(PLUS())' and so on. If
 there are no flags after the last `tt(PLUS())' and a match has not been found
 up to that point, default completion is tried.
-texinode(Extended Completion)(Example)(Alternative Completion)(Programmable Completion)
+If the list of flags contains a tt(-t) with a tt(PLUS()) character, the next
+list of flags is used even if the current list produced matches.
+
+texinode(Extended Completion)(Example)(Alternative Completion)(Completion Using compctl)
 sect(Extended Completion)
 startlist()
-list(tt(compctl) [ tt(-CDT) ] var(options) \
-tt(-x) var(pattern) var(options) tt(-) ... tt(--) \
-[ var(command) ... ])
-list(tt(compctl) [ tt(-CDT) ] var(options) \
-[ tt(-x) var(pattern) var(options) tt(-) ... tt(--) ] \
-[ tt(PLUS()) var(options) [ tt(-x) ... tt(--) ] ... [tt(PLUS())] ] \
-[ var(command) ... ])
+list(nofill(tt(compctl) [ tt(-CDT) ] var(options) \
+tt(-x) var(pattern) var(options) tt(-) ... tt(--)
+  [ var(command) ... ]))
+list(nofill(tt(compctl) [ tt(-CDT) ] var(options) \
+[ tt(-x) var(pattern) var(options) tt(-) ... tt(--) ]
+  [ tt(PLUS()) var(options) [ tt(-x) ... tt(--) ] ... [tt(PLUS())] ] \
+[ var(command) ... ]))
 endlist()
 
 The form with `tt(-x)' specifies extended completion for the
@@ -478,7 +631,7 @@ considered part of the completion, but the rest will.  var(index) may
 be negative to count from the end: in most cases, var(index) will be
 1 or -1.  For example,
 
-nofill(tt(compctl -s '`users`' -x 'n[1,@]' -k hosts -- talk))
+example(compctl -s '`users`' -x 'n[1,@]' -k hosts -- talk)
 
 will usually complete usernames, but if you insert an tt(@) after the
 name, names from the array var(hosts) (assumed to contain hostnames,
@@ -497,17 +650,27 @@ var(max) inclusive.
 )
 item(tt(r[)var(str1)tt(,)var(str2)tt(])...)(
 Matches if the cursor is after a word with prefix var(str1).  If there
-is also a word with prefix var(str2) on the command line it matches
-only if the cursor is before this word.
+is also a word with prefix var(str2) on the command line after the one 
+matched by var(str1) it matches
+only if the cursor is before this word. If the comma and var(str2) are
+omitted, it matches if the cursor is after a word with prefix var(str1).
 )
 item(tt(R[)var(str1)tt(,)var(str2)tt(])...)(
 Like tt(r) but using pattern matching instead.
 )
+item(tt(q[)var(str)tt(])...)(
+Matches the word currently being completed is in single quotes and the 
+var(str) begins with the letter `s', or if completion is done in
+double quotes and var(str) starts with the letter `d', or if
+completion is done in backticks and var(str) starts with a `b'.
+)
 enditem()
-texinode(Example)()(Extended Completion)(Programmable Completion)
+
+texinode(Example)()(Extended Completion)(Completion Using compctl)
 sect(Example)
-nofill(tt(compctl -u -x 's[tt(PLUS())] c[-1,-f],s[-f+PLUS()]' -g '~/Mail/*(:t)' \ 
-    - 's[-f],c[-1,-f]' -f -- mail))
+
+example(compctl -u -x 's[tt(PLUS())] c[-1,-f],s[-f+PLUS()]' \ 
+  -g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail)
 
 This is to be interpreted as follows:
 
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 632cb3195..35204a217 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -1,87 +1,130 @@
-texinode(Completion System)()(Zsh Modules)(Top)
+texinode(Completion System)(Zsh Modules)(Completion Widgets)(Top)
 chapter(Completion System)
-cindex(completion, system)
+cindex(completion system)
 cindex(completion, programmable)
 cindex(completion, controlling)
 sect(Description)
 
 This describes the shell code for the new completion system.  It consists
-of two scripts and a few other files that define shell functions.
-The shell functions which implement completion behaviour and which may
-be bound to keystrokes, are referred to as `widgets'.  All are contained
-in the following subdirectories of the tt(Completion) directory of the main
-distribution directory.
-
-startitem()
-item(tt(Core))(
-The core scripts and functions.  You will certainly need these, though will
-probably not need to alter them.  The contents of this directory is
-described in more detail below.
-)
-item(tt(Base))(
-Other functions you will almost certainly want if you are going to use
-any of the standard completion functions.  You may want to edit some of
-these files.
-)
-item(tt(Builtins))(
-Functions for completing arguments of shell builtin commands.
-)
-item(tt(User))(
-Functions for completing arguments of external commands and suites of
-commands.  They may need modifying for your system.
-)
-item(tt(Commands))(
-Functions which implement special types of completion to be bound to
-keystrokes rather than called by context.
-)
-enditem()
-
-You should decide which files you will be using and copy them to a
-directory (or multiple directories) of your own which should appear in your
-tt($fpath) variable so that the functions can be autoloaded.
+of various shell functions; those beginning `tt(comp)' are to be called
+directly by the user, while those beginning `tt(_)' are called by the
+completion code.  The shell functions of the second set which implement
+completion behaviour and which may be bound to keystrokes, are referred to
+as `widgets'.
 
 startmenu()
-menu(Initialisation)
+menu(Initialization)
+menu(Completion System Configuration)
 menu(Control Functions)
+menu(Bindable Commands)
 menu(Completion Functions)
+menu(Completion Directories)
 endmenu()
 
-texinode(Initialisation)(Control Functions)()(Completion System)
-sect(Initialisation)
-
-To initialise the system, the script tt(compinit) should be sourced with
-`tt(source )var(<path>)tt(/compinit)' or
-`tt(. )var(<path>)tt(/compinit)'. This will define a few utility functions,
-arrange for all the necessary shell functions to be autoloaded, and will
-then re-bind all keys that do completion to use the new system.
-
-subsect(Arguments)
+texinode(Initialization)(Completion System Configuration)()(Completion System)
+sect(Initialization)
+findex(compinstall)
+cindex(completion system, installing)
+
+The function tt(compinstall) can be run by a user to set up the completion
+system for use, which also provides options for more advanced usage.
+However, if the system was installed completely, it should be enough to
+call the shell function tt(compinit) from your initialization file; see the
+next section.
+
+Usually, tt(compinstall) will insert code into tt(.zshrc), although if
+that is not writable it will save it in another file and tell you that
+file's location.  Note that it is up to you to make sure that the lines
+added to tt(.zshrc) are actually run; you may, for example, need to move
+them to an earlier place in the file if tt(.zshrc) usually returns early.
+So long as you keep them all together (including the comment lines at the
+start and finish), you can rerun tt(compinstall) and it will correctly
+locate and modify these lines.  Note, however, that any code you add to
+this section by hand is likely to be lost if you rerun tt(compinstall).
+The new code will take effect next time you start the shell, or run
+tt(.zshrc) by hand.
+
+To run it, you will need to make sure it is in a directory mentioned in your
+tt($fpath) parameter, and that it is autoloaded (`tt(autoload -U
+compinstall)' is recommended).  It will ask you various questions about how
+you would like completion set up.  It is in two parts; the basic part
+locates the completion files and decides where to put your personal
+dumpfile, used to speed up initialization after the first time.  After
+that, you will be asked if you wish to go on to the advanced set-up; if you
+answer tt(n), you can rerun tt(compinstall) later without having to
+re-enter any of the basic settings.
+
+You can abort the installation any time you are being prompted for
+information, and your tt(.zshrc) will not be altered at all.
+
+After initialization all the builtin completion widgets such as
+tt(expand-or-complete) will be redefined to use the new completion system.
+Should you need to, you can still bind keys to the old functions by putting
+a `tt(.)' in front, e.g. `tt(.expand-or-complete)'.
+
+subsect(Use of compinit)
+findex(compinit)
+cindex(completion system, initializing)
+
+This section describes the use of tt(compinit) to initialize completion for
+the current session when run directly by the user; if you have run
+tt(compinstall) it will be called automatically from your tt(.zshrc).
+
+To initialize the system, the function tt(compinit) should be in a
+directory mentioned in the tt($fpath) variable, and should be autoloaded
+(`tt(autoload -U compinit)' is recommended).  When run, it will define a
+few utility functions, arrange for all the necessary shell functions to be
+autoloaded, and will then re-bind all keys that do completion to use the
+new system. Note that this means that the tt(zsh/complist) module has
+to be loaded before the completion system is initialized (i.e. the
+tt(compinit) function is called) to make sure that the tt(menu-select)
+widget defined by it will be redefined, too.
 
 To speed up the running of tt(compinit), it can be made to produce a dumped
-configuration which will be read in on future invocations.  The easiest way
-to do this is by adding the option tt(-d) whenever tt(compinit) is sourced.
-In this case the dumped file will have the same name as the sourced file,
-but with tt(.dump) appended to the end; alternatively, an explicit file
-name can be given following the tt(-d).  On the next call to tt(compinit
--d), the dumped file will be read instead.
+configuration which will be read in on future invocations; this is the
+default, although it can be turned off by calling tt(compinit) with the
+option tt(-D).  The dumped file is tt(.zcompdump) in the same
+directory as the startup files (i.e. tt($ZDOTDIR) or tt($HOME));
+alternatively, an explicit file name can be given by `tt(compinit -d)
+var(dumpfile)'.  On the next call to tt(compinit), the dumped file will be
+read instead of a full initialization.
 
 If the number of completion files changes, tt(compinit) will recognise this
 and produce a new dump file.  However, if the name of a function or the
-arguments in the first line of a tt(#compdef) funcion (as described below)
+arguments in the first line of a tt(#compdef) function (as described below)
 change, it is easiest to delete the dump file by hand so that the next time
 tt(compinit) will re-create it.
 
-The dumping is actually done by another script, tt(compdump), but you will
-only need to source this yourself if you change the configuration
+The dumping is actually done by another function, tt(compdump), but you
+will only need to run this yourself if you change the configuration
 (e.g. using tt(compdef)) and then want to dump the new one.  The name of
-the old dumped file will be remembered for this.
+the old dumped file will be remembered for this purpose.
+
+If the parameter tt(_compdir) is set, tt(compinit) uses it as a directory
+where completion functions can be found; this is only necessary if they are
+not already in the function search path.
 
 subsect(Autoloaded files)
+cindex(completion system, autoloaded functions)
 
 The convention for autoloaded functions used in completion is that they
 start with an underscore; as already mentioned, the tt(fpath/FPATH)
-parameter must contain the directory in which they are stored.  When
-tt(compinit) is sourced, it searches all such files accessible via
+parameter must contain the directory in which they are stored.  If tt(zsh)
+was properly installed on your system, then tt(fpath/FPATH) automatically
+contains the required directories.
+
+For incomplete installations, if tt(compinit) does not find enough files
+beginning with an underscore (fewer than twenty) in the search path, it
+will try to find more by adding the directory tt(_compdir) to the search
+path; if you have run tt(compinstall), this will be set automatically.
+Furthermore, if the directory in question ends in the path segment
+tt(Core), or has a subdirectory named tt(Core), tt(compinit) will add all
+subdirectories of the directory where tt(Core) is to the path: this allows
+the functions to be in the same format as in the tt(zsh) source
+distribution.
+
+cindex(compdef, use of by compinit)
+When tt(compinit) is run, it searches all such files accessible via
 tt(fpath/FPATH) and reads the first line of each of them.  This line should
 contain one of the tags described below. Files whose first line does not
 start with one of these tags are not considered to be part of the
@@ -103,13 +146,23 @@ called when completing for a command whose name matches the given
 var(pattern) (a standard globbing pattern).  Note that only one
 var(pattern) may be given.
 )
+item(tt(#compdef -P) var(pattern))(
+Like the previous one, but the function will be called only if no
+completion function for the command on the line could be found.
+)
 item(tt(#compdef -k) var(style key-sequences...))(
-This can be used bind special completion functions to the
+This can be used to bind special completion functions to the
 var(key-sequences).  It creates a widget behaving like the builtin widget
 var(style), which must be one of those that perform completion, namely
 tt(complete-word), tt(delete-char-or-list), tt(expand-or-complete),
 tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete),
-tt(menu-expand-or-complete), or tt(reverse-menu-complete).
+tt(menu-expand-or-complete), or tt(reverse-menu-complete). If the
+tt(complist) module is loaded (see
+ifzman(zmanref(zshmodules))\
+ifnzman(noderef(The zsh/complist Module))\
+), the tt(menu-select) widget can be used, too.  Note that the
+bindings will not be used if the key is already bound (that
+is, is bound to something other than tt(undefined-key)).
 
 The widget is then bound to all the var(key-sequences) given, if any: when
 one of the var(key-sequences) is typed, the function in the file will
@@ -117,29 +170,54 @@ be invoked to generate the matches. The widget created has the same
 name as the file and can also be bound to other keys using tt(bindkey) 
 as usual.
 )
-item(tt(#autoload))(
+item(tt(#compdef -K) var(widget-name) var(style) var(key-sequences) ...)(
+This is similar to tt(-k), with the same var(style) and var(key-sequences)
+arguments arguments, preceeded by a string giving the name of a widget.
+In this case only one var(key-sequences) argument may be given, but the
+entire set of three arguments may be repeated with a different set of
+arguments.  In particular, the var(widget-name) must be distinct in each
+set.  It should begin with `tt(_)', else one will be added, and should not
+clash with the name of any existing widget: names based on the name of the
+function are most useful.  For example,
+
+example(#compdef -K _foo_complete complete-word "^X^C" \ 
+  _foo_list list-choices "^X^D")
+
+(all on one line) defines a widget tt(_foo_complete) for completion, bound
+to `tt(^X^C)', and a widget tt(_foo_list) for listing, bound to `tt(^X^D)'.
+)
+item(tt(#autoload) [ var(options) ])(
 This is used for files defining utility function that are not to be
 called directly as completion functions but should be loaded automatically
 when invoked.  Typically they are to be called from within one of the
 completion functions.
+
+The var(options) will be given to the tt(autoload) builtin command
+when making the function autoloaded. Note that the tt(-U) flag is
+always used. Most often, this will be tt(+X) to force the function
+being loaded immediately.
 )
 enditem()
 
 Note that the tt(#) is part of the tag name and no white space is allowed
-after it.  The tt(#compdef) tags use the tt(compdef) function defined
+after it.  The tt(#compdef) tags use the tt(compdef) function described
 below; the main difference is that the name of the function is supplied
 implicitly.
 
 subsect(Functions)
 
-The tt(compinit) file defines the following functions, which may
+The tt(compinit) file defines the following function, which may
 also be called directly by the user.
 
+findex(compdef)
+cindex(completion system, adding definitions)
 startitem()
 xitem(tt(compdef) [ tt(-an) ] var(function names...))
 xitem(tt(compdef -d) var(names...))
 xitem(tt(compdef -p) [ tt(-a) ] var(function pattern))
-item(tt(compdef -k) [ tt(-a) ] var(function style key-sequences...))(
+xitem(tt(compdef -P) [ tt(-a) ] var(function pattern))
+xitem(tt(compdef -k) [ tt(-an) ] var(function style key-sequences...))
+item(tt(compdef -K) [ tt(-an) ] var(function name style key-sequences ...))(
 The first form tells the completion system to call the given
 var(function) when completing for the contexts or commands
 whose var(names) are given:  this is like the tt(#compdef) tag.  If the
@@ -147,78 +225,1588 @@ tt(-n) option is given, any existing completion behaviour for particular
 contexts or commands will not be altered.  These definitions can be deleted
 by giving the tt(-d) option as in the second form.
 
-The third form is similar to the first, but var(function) will be called
-for all commands whose name matches the var(pattern); this is like the
-tt(#compdef -p) function tag.
+The form with tt(-p) is similar to the first, but var(function) will be
+called for all commands whose name matches the var(pattern); this is like
+the tt(#compdef -p) function tag.
+
+The form with tt(-P) is like the third, but the var(function) will be
+called only if no function for the command itself was found or if one
+was found and it set the tt(_compskip) parameter to a value em(not)
+containing the substring tt(patterns).
 
-The fourth form defines a widget with the same name as the var(function)
+The form with tt(-k) defines a widget with the same name as the var(function)
 which will be called for each of the var(key-sequences); this is like the
 tt(#compdef -k) tag.  The function should generate the completions needed
 and will otherwise behave like the builtin widget whose name is given as
 the var(style) argument. The widgets usable for this are:
 tt(complete-word), tt(delete-char-or-list), tt(expand-or-complete),
 tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete),
-tt(menu-expand-or-complete), and tt(reverse-menu-complete).
+tt(menu-expand-or-complete), and tt(reverse-menu-complete), as well as
+tt(menu-select) if the tt(zsh/complist) module is loaded.  The option tt(-n)
+prevents the key being bound if it is already to bound to something other
+than tt(undefined-key).
+
+The form with tt(-K) is similar and defines multiple widgets based on the
+same var(function), each of which requires the set of three arguments
+var(name), var(style) and var(key-sequences), where the latter two are as
+for tt(-k) and the first must be a unique widget name beginning with an
+underscore.
 
 In each of the forms supporting it the tt(-a) option makes the
 var(function) autoloadable (exactly equivalent to
-tt(autoload )var(function)).
+tt(autoload -U )var(function)).
 )
-xitem(tt(compconf) var(definitions...))
-xitem(tt(compconf))
-item(tt(compconf) [ tt(-l) ] var(keys...))(
-Several aspects of the completion system can be configured by the
-user. The configuration values are stored under the keys described
-below in the associative array `tt(compconfig)'.  After sourcing
-tt(compinit), configuration values can either be set directly as in
-`tt(compconfig[completer]=_complete)' or by calling this utility function.
+enditem()
+
+texinode(Completion System Configuration)(Control Functions)(Initialization)(Completion System)
+sect(Completion System Configuration)
+cindex(completion system, configuration)
 
-Each var(definition) may be either a simple `var(key)', which sets this
-key in the tt(compconfig) array to an empty string, or of the form
-`var(key=value)' which stores the `var(value)' under key `var(key)'.
+This section gives a short overview of how the completion system works,
+and then more detail on how users can configure how and when matches are
+generated.
 
-Since the completion system also uses the array for internal purposes,
-you should not set all values at once by doing `tt(compconfig=(...))'.
+subsect(Overview)
+
+When completion is attempted somewhere on a command line the
+completion system first tries to find out the context where completion 
+was tried.  The context depends on such things as the name of the
+command when completing an argument, and possibily also
+the name of an option when completing an argument to that option.
+
+For the context a name consisting of multiple fields is built. This
+name is then used to look up styles that can be used to configure the
+completion system. Since it is not possible to build the whole context 
+name in advance, completion function may modify some of the fields and 
+hence the context name used for lookup may vary during the same call
+to the completion system.
+
+The context name always consists of the following fields, separated
+by colons:
+
+startitemize()
+itemiz(\
+The literal string tt(completion), saying that this style is used by
+the completion system.
+)
+itemiz(\
+The var(function); in many cases this field will be blank, but when
+the completion system is called from other functions, like
+tt(predict-on) or one of the functions in the tt(Command) directory of 
+the distribution, this field contains the (probably abbreviated) name
+of that function.
+)
+itemiz(\
+The var(completer) currently active, i.e. the name of the completer
+function without the leading underscore. Such a completer is in
+overall control of how completion is to be performed; `tt(complete)'
+is the basic one for ordinary completion, but completers may perform
+various related tasks such as correction, or modify the behaviour of a
+later completer (see
+ifzman(the section `Control Functions' below)\
+ifnzman(noderef(Control Functions)) 
+for more information).  
+)
+itemiz(\
+The var(context) or var(command). This is either one of the special
+context names such as tt(-condition-) as explained for the
+tt(_complete) completer below, or the name of the command we are
+completing arguments for. Completion functions for commands that have
+sub-commands usually modify this field to contain the name of the
+command followed by a minus sign and the sub-command (e.g. the
+completion function for the tt(cvs) command sets this field to strings
+such as tt(cvs-add) when completing for the tt(add) sub-command).
+)
+itemiz(\
+The var(argument), describing which argument we are
+completing. Normally this is either a string of the form
+tt(argument-)var(n), where var(n) is the number of the argument or it
+is a string of the form tt(-)var(opt)tt(-)var(n) when completing the
+var(n)'th argument of the option var(opt).
+)
+itemiz(\
+The var(tag). Tags are used for two purposes:  to describe the types
+of matches a completion function can generate for a certain context
+and to simplify the definition of styles that are tested.
+)
+enditemize()
+
+As an example, the context name
+
+example(tt(:completion::complete:dvips:-o-1:files))
+
+says that normal completion was attempted on an argument of the tt(dvips)
+command (more precisely: completion was attempted on the first argument
+after the tt(-o) option) and the completion function will generate
+filenames for this context.
+
+In many of the possible contexts the completion system can generate
+matches, often multiple types of matches.  These types are represented as
+simple names called `tags'.  The completion system will decide internally
+what sort of tags are allowed; a list of the standard possibilities is given
+below.  To determine in which order the tags are to be used by the
+completion function, the `tt(tag-order)' style for the appropriate
+context may be set, as described in the list of standard styles below.
+Only those types of matches whose tags were selected by this style
+will be produced, and in the order given.
+
+The tt(_complete_help) bindable command described in 
+ifzman(the section `Bindable Commands' below)\
+ifnzman(noderef(Bindable Commands))
+can be invoked to find out the context and tag names and styles used at a particular
+point in completion.  It shows a list of context names and the 
+tag names used in those contexts and then a list of context names and
+the styles used in those contexts if completion were tried at the
+current cursor position.  Hence one can easily find out all the
+information needed to change the behaviour of the tt(tag-order) style
+for a particular context.
+
+Completion behaviour can be modified by various other
+styles defined with the tt(zstyle) builtin command (\
+ifzman(see zmanref(zshmodules))\
+ifnzman(noderef(The zsh/zutil Module))).
+When looking up styles the completion system uses full context names,
+including the tag.
+
+Styles determine such things as how the matches are generated; some of them
+correspond to shell options (for example, the use of menu completion), but
+styles provide more specific control.  They can have any number of strings as
+their value.  Looking up the value of a style therefore consists of two
+things:  the context, which may be matched as a pattern, and the name of
+the style itself, which must be given exactly.
+
+For example, many completion functions can generate matches in a
+simple and a verbose form and use the tt(verbose) style to decide
+which form should be used. To make all such functions always use the
+verbose form one can simply call
+
+example(zstyle ':completion:*' verbose yes)
+
+in one of the startup files like tt(.zshrc). This definition simply
+means that the tt(verbose) style has tt(yes) as its value in every
+context inside the completion system.  If the pattern were `tt(*)', it
+would mean that the verbose style had this value anywhere the style
+mechanism is used.
+
+As a more specific example, the completion function for the tt(kill)
+builtin command uses the tt(verbose) style to decide if jobs and processes
+are listed only as job numbers and process identifiers or if they are
+listed with the full job texts and the command lines of the processes (the
+latter is achieved by calling the tt(ps) command). To make this builtin
+list the matches only as numbers one could call:
+
+example(zstyle ':completion:*:*:kill:*' verbose no)
+
+Furthermore, if one wanted to see the command lines for processes but not the
+job texts one could use the fact that the context name contains the tag name
+when styles are looked up.  As the function for the tt(kill)
+builtin command uses the tags tt(jobs) and tt(processes), we can use:
+
+example(zstyle ':completion:*:*:kill:*:jobs' verbose no)
+
+Note that the order in which styles are em(defined) does not matter; the
+style mechanism uses the most specific possible match for a particular
+style to determine the set of values.  More precisely, strings are
+preferred over patterns (for example, `tt(:completion:complete:foo)' is
+more specific than `tt(:completion:complete:*')), and longer patterns are
+preferred over shorter patterns.
+
+As for tags, completion functions can use any number of styles, so
+there can't be a complete list. However, the following two sections
+list those tags and styles that are used in many places of the
+completion system.
+
+subsect(Standard Tags)
+cindex(completion system, tags)
+
+Here are the tags currently used by the completion system. Note that
+some of these tags are not actually used while generating matches,
+but are only used by some completion functions when looking up
+styles.
 
-In the second form (without arguments), this function lists all keys
-and their values. If given the tt(-l) option as its first argument, as 
-in the last form, the other arguments are taken as names of keys and
-the values of these keys are printed one per line.
+startitem()
+kindex(accounts, completion tag)
+item(tt(accounts))(
+used to look up the tt(users-hosts) style
+)
+kindex(all-files, completion tag)
+item(tt(all-files))(
+for the names of all files
+)
+kindex(all-expansions, completion tag)
+item(tt(all-expansions))(
+used by the tt(_expand) completer when adding the string containing
+all expansions
+)
+kindex(arguments, completion tag)
+item(tt(arguments))(
+when an argument of a command may be completed
+)
+kindex(arrays, completion tag)
+item(tt(arrays))(
+for names of array parameters
+)
+kindex(association-keys, completion tag)
+item(tt(association-keys))(
+for keys of associative arrays (e.g. when completing inside a
+subscript of such a parameter)
+)
+kindex(bookmarks, completion tag)
+item(tt(bookmarks))(
+when completing bookmarks (e.g. for URLs and the tt(zftp) function suite)
+)
+kindex(builtins, completion tag)
+item(tt(builtins))(
+for names of builtin commands
+)
+kindex(characters, completion tag)
+item(tt(characters))(
+used for commands like tt(stty) when completing characters; also used
+when completing character classes after a opening bracket
+)
+kindex(colors, completion tag)
+item(tt(colors))(
+for color names
+)
+kindex(commands, completion tag)
+item(tt(commands))(
+for names of external commands and names of sub-commands (used by some 
+commands like tt(cvs))
+)
+kindex(corrections, completion tag)
+item(tt(corrections))(
+used by the tt(_approximate) and tt(_correct) completers for the possible
+corrections
+)
+kindex(cursors, completion tag)
+item(tt(cursors))(
+for cursor names used by X programs
+)
+kindex(default, completion tag)
+item(tt(default))(
+used to look up default values for various styles that may also be set 
+for tags that are used when generating matches
+)
+kindex(descriptions, completion tag)
+item(tt(descriptions))(
+used when looking up the value of the tt(format) style for
+descriptions
+)
+kindex(devices, completion tag)
+item(tt(devices))(
+for names of device special files
+)
+kindex(directories, completion tag)
+item(tt(directories))(
+for names of directories
+)
+kindex(directory-stack, completion tag)
+item(tt(directory-stack))(
+for entries in the directory stack
+)
+kindex(displays, completion tag)
+item(tt(displays))(
+for X display names
+)
+kindex(domains, completion tag)
+item(tt(domains))(
+for network domains
+)
+kindex(expansions, completion tag)
+item(tt(expansions))(
+used by the tt(_expand) completer for possible expansions
+)
+kindex(extensions, completion tag)
+item(tt(extensions))(
+for X server extensions
+)
+kindex(files, completion tag)
+item(tt(files))(
+used by completion functions that can complete some kind of filenames
+and different types of matches
+)
+kindex(fonts, completion tag)
+item(tt(fonts))(
+used for X font names
+)
+kindex(functions, completion tag)
+item(tt(functions))(
+names of functions (shell functions or other kinds of functions for
+some commands)
+)
+kindex(globbed-files, completion tag)
+item(tt(globbed-files))(
+for names of files matching the glob pattern used by completion
+functions that expect a certain type of file
+)
+kindex(groups, completion tag)
+item(tt(groups))(
+used when completing names of user groups
+)
+kindex(history-words, completion tag)
+item(tt(history-words))(
+for words from the history
+)
+kindex(hosts, completion tag)
+item(tt(hosts))(
+for hostnames
+)
+kindex(indexes, completion tag)
+item(tt(indexes))(
+used for array indexes
+)
+kindex(jobs, completion tag)
+item(tt(jobs))(
+used for jobs
+)
+kindex(keymaps, completion tag)
+item(tt(keymaps))(
+for names of zsh keymaps
+)
+kindex(keysyms, completion tag)
+item(tt(keysyms))(
+for names of X keysyms
+)
+kindex(local-directories, completion tag)
+item(tt(local-directories))(
+for names of directories in the current working directory when
+completing for the tt(cd) builtin command
+)
+kindex(libraries, completion tag)
+item(tt(libraries))(
+for names of system libraries
+)
+kindex(limits, completion tag)
+item(tt(limits))(
+for system limits
+)
+kindex(manuals, completion tag)
+item(tt(manuals))(
+for names of manual pages
+)
+kindex(maps, completion tag)
+item(tt(maps))(
+for map names (e.g. YP maps)
+)
+kindex(messages, completion tag)
+item(tt(messages))(
+used to look up the tt(format) style for messages
+)
+kindex(modifiers, completion tag)
+item(tt(modifiers))(
+for names of X modifiers
+)
+kindex(modules, completion tag)
+item(tt(modules))(
+for modules (e.g. tt(zsh) modules)
+)
+kindex(my-accounts, completion tag)
+item(tt(my-accounts))(
+used to look up the tt(users-hosts) style
+)
+kindex(named-directories, completion tag)
+item(tt(named-directories))(
+for named directories (you wouldn't have guessed that, would you?)
+)
+kindex(names, completion tag)
+item(tt(names))(
+for all kinds of names
+)
+kindex(nicknames, completion tag)
+item(tt(nicknames))(
+for nicknames of YP maps
+)
+kindex(options, completion tag)
+item(tt(options))(
+for command options
+)
+kindex(original, completion tag)
+item(tt(original))(
+used by the tt(_approximate), tt(_correct) and tt(_expand) completers when
+adding the original string
+)
+kindex(other-accounts, completion tag)
+item(tt(other-accounts))(
+used to look up the tt(users-hosts) style
+)
+kindex(packages, completion tag)
+item(tt(packages))(
+for packages (e.g. tt(rpm) or installed tt(Debian) packages)
+)
+kindex(parameters, completion tag)
+item(tt(parameters))(
+for names of parameters
+)
+kindex(path-directories, completion tag)
+item(tt(path-directories))(
+for names of directories in directories from the tt(cdpath) array when
+completing for the tt(cd) builtin command
+)
+kindex(paths, completion tag)
+item(tt(paths))(
+used to look up the values of the tt(expand), tt(cursor) and
+tt(special-dirs) styles
+)
+kindex(pids, completion tag)
+item(tt(pids))(
+for process identifiers
+)
+kindex(pids-list, completion tag)
+item(tt(pids-list))(
+used to look up the tt(command) style when generating the list to
+display for process identifiers
+)
+kindex(pods, completion tag)
+item(tt(pods))(
+for perl pods
+)
+kindex(ports, completion tag)
+item(tt(ports))(
+for communication ports
+)
+kindex(prefixes, completion tag)
+item(tt(prefixes))(
+for prefixes (like those of an URL)
+)
+kindex(printers, completion tag)
+item(tt(printers))(
+for printer names
+)
+kindex(processes, completion tag)
+item(tt(processes))(
+for process identifiers
+)
+kindex(sequences, completion tag)
+item(tt(sequences))(
+for sequences (e.g. tt(mh) sequences)
+)
+kindex(sessions, completion tag)
+item(tt(sessions))(
+for sessions in the tt(zftp) function suite
+)
+kindex(signals, completion tag)
+item(tt(signals))(
+for signal names
+)
+kindex(strings, completion tag)
+item(tt(strings))(
+for strings (e.g. the replacement strings for the tt(cd) builtin
+command)
+)
+kindex(tags, completion tag)
+item(tt(tags))(
+for tags (e.g. tt(rpm) tags)
+)
+kindex(targets, completion tag)
+item(tt(targets))(
+for makefile targets
+)
+kindex(types, completion tag)
+item(tt(types))(
+for types of whatever (e.g. adress types for the tt(xhost) command)
+)
+kindex(urls, completion tag)
+item(tt(urls))(
+used to look up the tt(path) and tt(local) styles when completing URLs
+)
+kindex(users, completion tag)
+item(tt(users))(
+for usernames
+)
+kindex(values, completion tag)
+item(tt(values))(
+when completing a value out of a set of values (or a list of such
+values)
+)
+kindex(warnings, completion tag)
+item(tt(warnings))(
+used to look up the tt(format) style for warnings
+)
+kindex(widgets, completion tag)
+item(tt(widgets))(
+for zsh widget names
+)
+kindex(windows, completion tag)
+item(tt(windows))(
+for IDs of X windows
+)
+kindex(zsh-options, completion tag)
+item(tt(zsh-options))(
+for shell options
 )
 enditem()
 
-texinode(Control Functions)(Completion Functions)(Initialisation)(Completion System)
-sect(Control Functions)
+subsect(Standard Styles)
+cindex(completion system, styles)
+
+Here are the names of the styles used by the completion system. Note
+that the values of several of these styles represent boolean
+values. In all these cases any of the strings `tt(true)', `tt(on)',
+`tt(yes)', and `tt(1)' can be used for the truth value `true' and
+the strings `tt(false)', `tt(off)', `tt(no)', and `tt(0)' are
+interpreted as `false'.  The behavior for any other value is undefined 
+unless the description for the particular style mentions other
+possible values.
+
+startitem()
+kindex(accept-exact, completion style)
+item(tt(accept-exact))(
+This is tested for the default tag and the tags used when generating
+matches. If it is set to `true' for at least one match which is the
+same as the string on the line, this match will immediately be
+accepted.
+)
+kindex(add-space, completion style)
+item(tt(add-space))(
+This style is used by the tt(_prefix) completer to decide if a space
+should be inserted before the suffix.
+)
+kindex(auto-description, completion style)
+item(tt(auto-description))(
+If set, this style's value will be used as the description for options which
+are not described by the completion functions, but that have exactly
+one argument. The sequence `tt(%d)' in the value will be replaced by
+the description for this argument. Depending on personal preferences,
+it may be useful to set this style to something like `tt(specify: %d)'. 
+Note that this may not work for some commands.
+)
+kindex(break, completion style)
+item(tt(break))(
+This style is used by the tt(incremental-complete-word) widget (found
+in the tt(Functions/Zle) directory of the distribution). Its value
+should be a pattern and all keys matching this pattern will cause the
+widget to stop incremental completion without the key having any
+further effect.
+)
+kindex(command, completion style)
+item(tt(command))(
+This style can be used to override the defaults in several completion
+functions for how commands are called to generate information about
+possible matches. The strings in the value are joined with spaces
+between them to build the command line to execute. If the value starts 
+with a hyphen the string built will be prepended to the default
+supplied by the completion function. This allows one to easily stick a 
+tt(builtin) or tt(command) in front of the default in case one has,
+for example, a shell function with the same name as the command
+called, but for completion purposes one needs to ensure that the real
+command is called.
+
+For example, the function generating process IDs as matches uses this
+style with the tt(pids) tag to generate the IDs to complete and iwhen
+the tt(verbose) style is `true', it uses this style with the
+tt(pids-list) tag to generate the strings to display. When using
+different values for these two tags one should ensure that the process
+IDs appear in the same order in both lists.
+)
+kindex(completer, completion style)
+item(tt(completer))(
+The strings given as the value of this style give the names of the
+completer functions to use. The available completer functions are
+described in
+ifzman(the section `Control Functions' below)\
+ifnzman(noderef(Control Functions))\
+.
+
+Each string may be the name of a completer function or a string of the 
+form `var(function)tt(:)var(name)'. In the first case the
+var(completer) field of the context will contain the name of the
+completer without the leading underscore and with all other
+underscores replaced with hyphens. In the second case the
+var(function) is the name of the completer to call, but the context
+will contain the var(name) in the var(completer) field of the
+context. If the var(name) starts with a hyphen, the string for the
+context will be build from the name of the completer function as in
+the first case with the var(name) will be appended to it. For example: 
+
+example(zstyle ':completion:*' completer _complete _complete:-foo)
+
+Here, completion will call the tt(_complete) completer twice, once
+using `tt(complete)' and once using `tt(complete-foo)' in the
+var(completer) field of the context. Normally, using the same
+completer more than once makes only sense when used with the
+`var(functions)tt(:)var(name)' form, because otherwise the context
+name will be the same in all calls to the completer (possible
+exception to this rule are the tt(_ignored) and tt(_prefix)
+completers).
+
+Note that the widget functions from the distribution that call the
+completion code (namely, the tt(incremental-complete-word) and the
+tt(predict-on) widgets) set up their top-level context name before
+calling completion. This allows one to define different sets of
+completer functions for normal completion and for these widgets. For
+example, to use completion, approximation and correction for normal
+completion, completion and correction for incremental completion and
+only completion for prediction one could use:
+
+example(zstyle ':completion:*' completer _complete _correct _approximate
+zstyle ':completion:incremental:*' completer _complete _correct
+zstyle ':completion:predict:*' completer _complete)
+
+The default value for this style is tt(_complete), i.e. normally only
+completion will be done.
+)
+kindex(completions, completion style)
+item(tt(completions))(
+This style is used by the tt(_expand) completer function.
+
+If this is set to an non-empty string it should be an expression
+usable inside a `tt($((...)))' arithmetical expression. The completer
+function evaluates this expression and if the result is `tt(1)', no
+expansions will be generated, but instead the completions will be
+generated as normal and all of them will be inserted into the command
+line.
+)
+kindex(condition, completion style)
+item(tt(condition))(
+This style is used by the tt(_list) completer function.
+
+If it is not set or set to the empty string, the insertion of
+matches will be delayed unconditionally. If it is set, the value
+should be an expression usable inside a `tt($((...)))'
+arithmetical expression. In this case, delaying will be done if the
+expression evaluates to `tt(1)'. For example, with
+
+example(zstyle ':completion:*:list:::' condition 'NUMERIC != 1')
+
+delaying will be done only if given an explicit numeric argument
+other than `tt(1)'.
+)
+kindex(cursor, completion style)
+item(tt(cursor))(
+This is used together with the tt(paths) tag by the function
+generating filenames as matches to find out if the cursor should be left
+after the first ambiguous pathname component even when menucompletion
+is used.
+
+The tt(predict-on) widget uses this style to decide where to place the 
+cursor after completion has been tried. If it is set to tt(complete),
+the cursor is left at the place where completion left it, but only if
+it is after a character equal to the one just inserted by the user. If 
+it is after another character, the value is treated as if it where the 
+string tt(key). If the value is set to tt(key), the cursor is left
+after the var(n)th occurrence of the character just inserted, where
+var(n) is the number of times that character appeared in the word
+before completion was attempted. In short, this has the effect of
+leaving the cursor after the character just typed even if the
+completion code found out that no other characters need to be inserted 
+at that position. Finally, any other value for this style
+unconditionally leaves the cursor at the position where the completion
+code left it.
+)
+kindex(disable-stat, completion style)
+item(tt(disable-stat))(
+This is used with the an empty tag by the function completing for the
+tt(cvs) command to decide if the tt(zsh/stat) module should be used to
+generate only names of modified files in the appropriate places.
+)
+kindex(domains, completion style)
+item(tt(domains))(
+If set, gives the names of network domains that should be
+completed. If this is not set by the user domain names mentioned in
+tt(/etc/resolv.conf) will be used.
+)
+kindex(expand, completion style)
+item(tt(expand))(
+This style is used when completing strings consisting of multiple
+parts, such as path names. If its
+value contains the string tt(prefix), the partially typed word from
+the line will be expanded as far as possible even if trailing parts
+can not be completed. If it contains the string tt(suffix)
+and normal (non-menu-) completion is used, matching names for
+components after the first ambiguous one will be added, too. This
+means that the resulting string is the longest unambiguous string
+possible, but if menucompletion is started on the list of matches
+generated this way (e.g. due to the option tt(AUTO_MENU) being set),
+this will also cycle through the names of the files in pathname
+components after the first ambiguous one.
+)
+kindex(file-patterns, completion style)
+item(tt(file-patterns))(
+In most places where filenames are completed, the function tt(_files)
+is used which can be configured with this style. If the style is
+unset, tt(_files) offers, one after another, up to three tags:
+tt(globbed-files),
+tt(directories) and tt(all-files), depending on the types of files
+expected by the caller of tt(_files).
+
+If the tt(file-patterns) style is set, the default tags are not
+used. Instead, the value of the style says which tags and which
+patterns are to be offered. The strings in the value are of the form
+`var(patterns)tt(:)var(tag)'. The var(patterns) gives one or more glob 
+patterns separated by spaces that are to be used to generate
+filenames. If it contains the sequence `tt(%p)', that is replaced by
+the pattern(s) given by the calling function.
+Colons in the pattern have to be preceded by a backslash to
+make them distinguishable from the colon before the var(tag). The
+var(tag)s of all strings in the value will be offered by tt(_files)
+(again, one after another) and used when looking up other styles. The
+var(tag) may also be
+followed by an optional second colon and a description. If that is
+given, this description will be used for the `tt(%d)' in the value of
+the tt(format) style (if that is set) instead of the default
+description supplied by the completion function. If the description
+given here contains itself a `tt(%d)', that is replaced with the
+description supplied by the completion function.
+
+For example, to make the tt(rm) command first complete only names of
+object files and the names of all files if no object file matches
+the string on the line, one would do:
+
+example(zstyle ':completion:*:*:rm:*' file-patterns \ 
+    '*.o:object-files' '%p:all-files')
+
+Another interesting example is to change the default behaviour that
+makes completion first offer files matching the patterns given by the
+calling function, then the directories and then all files. Many people 
+prefer to get both the files matching the given patterns and the
+directories in the first try and all files as the second try. To
+achieve this, one could do:
+
+example(zstyle ':completion:*' file-patterns \
+    '%p *(-/):globbed-files' '*:all-files')
+
+Note also that during the execution of completion functions, the
+tt(EXTENDED_GLOB) option is in effect, so the characters `tt(#)',
+`tt(~)' and `tt(^)' have special meanings in the patterns.
+)
+kindex(format, completion style)
+item(tt(format))(
+If this is set for the tt(descriptions) tag, its value is used as a
+string to display above matches in completion lists. The sequence
+`tt(%d)' in this string will be replaced with a short description of
+what these matches are. This string may also contain the sequences to
+specify output attributes, such as `tt(%b)' and `tt(%s)'.
+
+For the same purpose, this style is also tested with the tags used
+when matches are generated before it is tested for the
+tt(descriptions) tag. This gives the possibility to define different
+format strings for different types of matches.
+
+Note also that some completer functions define additional
+`tt(%)'-sequences. These are described for the completer functions that 
+make use of them.
+
+For the tt(messages) tag, this defines a string used by some
+completion functions to display messages. Here, the `tt(%d)' is
+replaced with the message given by the completion function.
+
+Finally, for the tt(warnings) tag, it is printed when no matches could 
+be generated at all. In this case the `tt(%d)' is replaced with the
+descriptions for the matches that were expected. If the value does not 
+contain a `tt(%d)', then those descriptions are added in the same way
+as matches are added, i.e. they appear below the value for the
+tt(format) style laid out in columns. The descriptions are added as if 
+for the tag tt(warnings) so that you can use the tt(list-colors) style 
+for that tag to highlight them.
+
+Here and in all other cases where the completion system uses `tt(%)'
+sequences, the `tt(%)' may be followed by field width specifications as 
+described for the tt(zformat) builtin command from the tt(zutil)
+module, see
+ifzman(zmanref(zshmodules))\
+ifnzman(noderef(The zsh/zutil Module))\
+.
+)
+kindex(glob, completion style)
+item(tt(glob))(
+Like tt(completions), this is used by the tt(_expand) completer.
+
+The value is used like the one for tt(completions) and if it evaluates to 
+`tt(1)', globbing will be attempted on the words resulting from
+substitution (see the tt(substitute) style) or the original string
+from the line.
+)
+kindex(group-name, completion style)
+item(tt(group-name))(
+The completion system can put different types of matches in different
+groups which are then displayed separately in the list of possible
+completions. This style can be use to give the names for these groups
+for particular tags. For example, in command position the completion
+system generates names of builtin and external commands, names of
+aliases and shell functions and reserved words as possible
+completions. To have the external commands and shell functions listed
+separately, one can set:
+
+example(zstyle ':completion:*:*:-command-:*:commands' group-name commands
+zstyle ':completion:*:*:-command-:*:functions' group-name functions)
+
+This also means that if the same name is used for different types of
+matches, then those matches will be displayed together in the same
+group.
+
+If the name given is the empty string, then the name of the tag for
+the matches will be used as the name of the group. So, to have all
+different types of matches displayed separately, one can just set:
+
+example(zstyle ':completion:*' group-name '')
+
+All matches for which no group name is defined will be put in a group
+named tt(-default-).
+)
+kindex(group-order, completion style)
+item(tt(group-order))(
+This style is to be used together with the tt(group-name) style. Once
+different types of matches are put into different groups, this style
+can be used to define in which order these groups should appear in the 
+list. The strings in the value are taken as group names and the named
+groups will be shown in the order in which their names appear in the
+value. All groups whose names are not given in the value of this style 
+will appear in the order defined by the function generating the
+matches.
+
+For example, to have names of builtin commands, shell functions and
+external commands appear in this order when completing in command
+position one would set:
+
+example(zstyle ':completion:*:*:-command-:*' group-order \ 
+       builtins functions commands)
+)
+kindex(groups, completion style)
+item(tt(groups))(
+A style holding the names of the groups that should be completed. If
+this is not set by the user, the group names from the YP database or
+the file `tt(/etc/group)' will be used.
+)
+kindex(hidden, completion style)
+item(tt(hidden))(
+If this is set to one of the `true' values, the matches for the tags
+for which this is set will not appear in the list; only the
+description for the matches as set with the tt(format) style will be
+shown. If this is set to tt(all), not even the description will be
+displayed.
+
+Note that the matches will still be completed, they are just not shown 
+in the list. To avoid having matches considered as possible
+completions at all the tt(tag-order) style can be modified as described
+below.
+)
+kindex(hosts, completion style)
+item(tt(hosts))(
+A style holding the names of hosts that should be completed. If this
+is not set by the user the hostnames in `tt(/etc/hosts)' will be used.
+)
+kindex(hosts-ports, completion style)
+item(tt(hosts-ports))(
+This style is used by commands that need or accept hostnames and
+ports. The strings in the value should be of the form
+`var(host)tt(:)var(port)'. These hostnames and ports are completed
+depending on the information already on the line, so that if, for
+example, the hostname is already typed, only those ports will be
+completed for which pairs with the hostname from the line exist.
+)
+kindex(ignore-parents, completion style)
+item(tt(ignore-parents))(
+When completing files it is possible to make names of directories
+already mentioned on the line or the current working directory be
+ignored. The style is tested for the tt(files) tag and if its value
+contains the string tt(parent), then the name of any directory whose
+path is already contained in the word on the line is ignored. For
+example, when completing after tt(foo/../), the directory tt(foo) will
+not be considered a valid completion.
+
+If the style contains the string tt(pwd), then the name of the current 
+working directory will not be completed, so that, for example,
+completion after tt(../) will not use the name of the current
+directory.
+
+If the style contains the string tt(..) both tests will only be
+performed if the word on the line contains the substring tt(../) and
+if the value contains the string tt(directory), then the tests will
+only be performed if only names of directories are completed.
+
+Note that names of directories ignored because of one of the tests
+will be ignored in the same way as the matches ignored because of the
+tt(ignored-patterns) style. I.e. by using the tt(_ignored) completer
+it is possible to complete these directories nonetheless.
+)
+kindex(ignored-patterns, completion style)
+item(tt(ignored-patterns))(
+This style is used with the tags used when adding matches and defines a
+couple of patterns. All matches that are matched by any of these
+patterns will be ignored as long as there are other matches not
+matched by any of the patterns.  It is a more configurable version
+of the shell parameter tt($fignore).
+
+Note that during the execution of completion functions, the
+tt(EXTENDED_GLOB) option is in effect, so the characters `tt(#)',
+`tt(~)' and `tt(^)' have special meanings in the patterns.
+)
+kindex(insert-unambiguous, completion style)
+item(tt(insert-unambiguous))(
+This is used by the tt(_match) and tt(_approximate) completer
+functions. If it is set to `true', the completer will start menu
+completion only if no unambiguous string could be generated that is at
+least as long as the original string from the line. Note that the
+tt(_approximate) completer uses it after setting the completer field
+in the context name to one of tt(correct-)var(num) or
+tt(approximate-)var(num), where var(num) is the number of errors that
+were accepted.
+)
+kindex(last-prompt, completion style)
+item(tt(last-prompt))(
+This is used to determine if the completion code should try to put the
+cursor back onto the previous command line after showing a completion
+listing (as for the tt(ALWAYS_LAST_PROMPT) option). Like several other 
+styles it is tested for the tt(default) tag and all tags used when
+generating matches. The cursor will be moved back to the previous line 
+if this style is `true' for all types of matches added. Note also that 
+this is independent of the numeric argument -- unlike the
+tt(ALWAYS_LAST_PROMPT) option.
+)
+kindex(list, completion style)
+item(tt(list))(
+This is used by the tt(_history_complete_word) bindable command
+(context `tt(:completion:history-words)') and by the
+tt(incremental-complete-word) widget (context `tt(:completion:incremental)).
+
+The tt(_history_complete_word) bindable command uses this style to
+decide if the available matches should be shown.
+
+When using the tt(incremental-complete-word) widget, this style says
+if the matches should be listed on every key press (if they fit on the 
+screen).
+
+The tt(predict-on) widget uses this style to decide if the completion
+should be shown even if there is only one possible completion. This is 
+done if the value of this style is the string tt(always).
+)
+kindex(list-colors, completion style)
+item(tt(list-colors))(
+If the tt(zsh/complist) module is used, this style can be used to set
+color specifications as with the tt(ZLS_COLORS) and tt(ZLS_COLOURS)
+parameters (see
+ifzman(the section `The zsh/complist Module' in zmanref(zshmodules))\
+ifnzman(noderef(The zsh/complist Module))\
+).
+
+If this style is set for the tt(default) tag, the strings in the value 
+are taken as specifications that are to be used everywhere. If it is
+set for other tags, the specifications are used only for matches of
+the type described by the tag. For this to work, the tt(group-name)
+style has to be set to an empty string. If the tt(group-name) tag
+specifies other names for the groups the matches in these groups can
+be colored by using these names together with the `tt((group)...)'
+syntax described for the tt(ZLS_COLORS) and tt(ZLS_COLOURS) parameters 
+and adding the specifications to the value for this style with the
+tt(default) tag.
+
+To be able to share the same specifications one has set up for the GNU
+version of the tt(ls) command one can use:
+
+example(zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS})
+
+And to get the default colors (which are the same as for the GNU
+tt(ls) command) one should set the style to an empty value.
+)
+kindex(list-packed, completion style)
+item(tt(list-packed))(
+Like the tt(list-colors) style, this is tested with the tt(default)
+tag and all tags used when generating matches. If it is set to `true'
+for a tag, the matches added for it will be listed as if the
+tt(LIST_PACKED) option were set for them. If it is set to `false',
+they are listed normally.
+)
+kindex(list-rows-first, completion style)
+item(tt(list-rows-first))(
+This style is tested like the tt(list-packed) style and determines if
+matches are to be listed in a rows-first fashion, as for the
+tt(LIST_ROWS_FIRST) option.
+)
+kindex(local, completion style)
+item(tt(local))(
+This style is used by completion functions which generate URLs as
+possible matches to add suitable matches when a URL points to a
+local web server. Its value should consist of three strings: a
+hostname, the path to the default web pages for the server and the
+directory name used by a user placing web pages within their home
+area.
+)
+kindex(match-original, completion style)
+item(tt(match-original))(
+This is used by the tt(_match) completer.  If it is set to
+tt(only), tt(_match) will try to generate matches without inserting a
+`tt(*)' at the cursor position.  If set to any other non-empty value,
+it will first try to generate matches without inserting the `tt(*)'
+and if that yields no matches, it will try again with the `tt(*)'
+inserted.
+)
+kindex(matcher, completion style)
+item(tt(matcher))(
+This style is tested for tags used when generating matches. Its value
+is used as an additional match specification to use when adding the
+matches as described in
+ifzman(the section `Matching Control' in zmanref(zshcompwid))\
+ifnzman(noderef(Matching Control))\
+.
+)
+kindex(matcher-list, completion style)
+item(tt(matcher-list))(
+This style is used by the main completion function to retrieve match
+specifications that are to be used everywhere. Its value should be a
+list of such specifications. The completion system will try them one
+after another for each completer selected. For example, to first try
+simple completion and, if that generates no matches, case-insensitive
+completion one would do:
+
+example(zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}')
+
+But the style allows even finer control: the style is looked up for
+every completer tried with the name of the completer (without the
+leading underscore) in the context name. For example, if one uses the
+completers tt(_complete) and tt(_prefix) and wants to try
+case-insensitive completion only when using the tt(_complete)
+completer, one would do:
+
+example(zstyle ':completion:*' completer _complete _prefix
+zstyle ':completion:*:complete:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}')
+
+Note that the tt(completer) style allows to give user-defined names to 
+use in the context instead of the name of the completer.
+This is useful if, for example, one wants to try
+normal completion without a match specification and with
+case-insensitive matching first, correction if that doesn't generate
+any matches and partial-word completion if that doesn't yield any
+matches either. In such a case one can give the tt(_complete)
+completer more than once in the tt(completer) style and define different
+match specifications for them, as in:
+
+example(zstyle ':completion:*' completer _complete _correct _complete:foo
+zstyle ':completion:*:complete:*' matcher-list \ 
+    '' 'm:{a-zA-Z}={A-Za-z}'
+zstyle ':completion:*:foo:*' matcher-list \ 
+    'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*')
+
+Note that in any case an unset style makes the completion code use no
+global match specification. Also, some completers (like tt(_correct)
+and tt(_approximate)) do not use the match specifications. But even if 
+such completers are used one can use the simple form to set this style 
+(as in the first example above) because such completers will make sure 
+that they are executed only once even if multiple match specifications 
+have been given.
+)
+kindex(max-errors, completion style)
+item(tt(max-errors))(
+This is used by the tt(_approximate) and tt(_correct) completer functions
+to determine the maximum number of errors to accept. The completer will try
+to generate completions by first allowing one error, then two errors, and
+so on, until either a match was found or the maximum number of errors
+given by this style has been reached.
+
+If the value for this style contains the string tt(numeric), the 
+completer function will take any numeric argument as the
+maximum number of errors allowed. For example, with
+
+example(zstyle ':completion:*:approximate:::' max-errors 2 numeric)
+
+two errors will be allowed if no numeric argument is given. However,
+with a numeric argument of six (as in `tt(ESC-6 TAB)'), up to six
+errors are accepted.  Hence with a value of `tt(0 numeric)', no correcting
+completion will be attempted unless a numeric argument is given.
+
+If the value contains the string tt(not-numeric), the completer
+will em(not) try to generate corrected
+completions when given a numeric argument, so in this case the number given
+should be greater than zero.  For example, `tt(2 not-numeric)' specifies that
+correcting completion with two errors will usually be performed, but if a
+numeric argument is given, correcting completion will not be
+performed.
+
+The default value for this style is `tt(2 numeric)'.
+)
+kindex(menu, completion style)
+item(tt(menu))(
+This style is tested for the tt(default) tag and the tags used when
+adding matches. The value should be one of the `true' values (tt(yes), 
+tt(true), tt(1), or tt(on)) if menu completion should be started when
+matches for the given tag (or always in case of the tt(default) tag)
+are generated. If none of these values is defined for any of the tags
+used, but for at least one of these tags the value is the string
+tt(auto), this says that the same behavior as for the tt(AUTO_MENU)
+option should be used. Finally, if menucompletion is started by some 
+other means (e.g. by setting the tt(MENU_COMPLETE) option) and the
+value for one of the tags used is `false' (i.e. tt(no), tt(false),
+tt(0), or tt(off)), then menucompletion will em(not) be started for
+this completion. Note that the values defined for normal tags
+override the value set for the tt(default) tag.
+
+Either instead of or in addition to one of the values above, the value
+for this style may also contain the string tt(select), optionally
+followed by an equal sign and a number. In this case menuselection
+(as defined by the tt(zsh/computil) module) will be started. Without the
+optional number, it will be started unconditionally and with a number
+it will be started only if at least that many matches are generated
+(if the values for more than one tag define such a number, the
+smallest one is taken). Starting menuselection can explicitly be
+turned off by defining a value containing the string
+tt(no-select).
+)
+kindex(numbers, completion style)
+item(tt(numbers))(
+This is used with the tt(jobs) tag. If it is `true', the completions
+will use the job numbers instead of the shortest unambiguous strings
+of the jobs' command lines. If the value is a number, job numbers will 
+only be used if for at least one of the jobs that many (or more) words 
+from the command line string have to be used to make the strings
+unambiguous. E.g. if it is set to `tt(1)', strings will only be used
+if all jobs differ in the first word on their command lines.
+)
+kindex(old-list, completion style)
+item(tt(old-list))(
+This is used by the tt(_oldlist) completer.  If this is set to tt(always),
+then standard widgets which perform listing will retain the current list of
+matches, however they were generated.  If it is set to tt(never), this will
+not be done (the behaviour without the tt(_oldlist) completer).  If it is
+unset, or any other value, then the existing list of completions will
+be displayed if it is not already; otherwise, the standard completion
+list will be generated:  this is the default behaviour of
+tt(_oldlist).  However, if there is an old list and this style contains
+the name of the completer function that generated the list, then the
+old list will be used even if it was generated by a widget which does
+not do listing.
+
+For example, suppose you type tt(^Xc) to use the tt(_correct_word)
+widget, which generates a list of corrections for the word under the
+cursor.  Usually, typing tt(^D) would generate a standard list of
+completions for the word on the command line, and show that.  With
+tt(_oldlist), it will instead show the list of corrections already
+generated.
+
+As another example consider the tt(_match) completer: with the
+tt(insert-unambiguous) style set to `true' it inserts only an
+unambiguous prefix string if there is any. But since this may remove
+parts of the original pattern, attempting completion again may result
+in more matches than on the first attempt. But by using the
+tt(_oldlist) completer and setting this style to tt(_match), the list of 
+matches generated on the first attempt will be used again.
+)
+kindex(old-menu, completion style)
+item(tt(old-menu))(
+This is used by the tt(_oldlist) completer. Here it controls how menu
+completion behaves when a completion has already been inserted and the
+user types a standard completion key type such as tt(TAB). The default
+behaviour of tt(_oldlist) is that menu completion always continues
+with the existing list of completions.  If this style is set to
+`false', however, a new completion is started if the old list was
+generated by a different completion command (the behaviour without the 
+tt(_oldlist) completer).
+
+For example, suppose you type tt(^Xc) to generate a list of corrections,
+and menu completion is started in one of the usual ways.  Usually, typing
+tt(TAB) at this point would start trying to complete the line as it now
+appears.  With tt(_oldlist), it will instead continue to cycle through the
+list of completions.
+)
+kindex(original, completion style)
+item(tt(original))(
+This is used by the tt(_approximate) and tt(_correct)
+completers to decide if the original string should be added as
+one possible completion. Normally, this is done only if there are
+at least two possible corrections, but if this style is set to `true', it
+will always be added. Note that these completers use this style after
+setting the completer field in the context name to
+tt(correct-)var(num) or tt(approximate-)var(num), where var(num) is
+the number of errors that were accepted.
+)
+kindex(packageset, completion style)
+item(tt(packageset))(
+A style containing an override for the default package set
+for that context.  For example,
+
+example(zstyle ':completion:*:complete:dpkg:--status-1:' packageset avail)
+
+will cause available packages, rather than only installed packages,
+to be completed for `dpkg --status'.
+)
+kindex(path, completion style)
+item(tt(path))(
+This is used together with the the tt(urls) tag by completion
+functions that generate URLs as possible matches. It should be set to
+the path of a directory containing sub-directories named like
+`tt(http)', `tt(ftp)', `tt(bookmark)', and so on. These
+sub-directories should contain files and other sub-directories whose
+pathnames are possible completions after the initial `tt(http://)',
+`tt(ftp://)', etc. See the description in the file tt(_urls) in the
+tt(User) sub-directory of the completion system for more information.
+
+Also, the function that completes color names uses this style with the 
+tt(colors) tag. Here, the value should be the pathname of a file
+containing color names in the format of an X11 tt(rgb.txt) file. That
+file (if it can be found) will be used as the default if the style is
+not set.
+)
+kindex(ports, completion style)
+item(tt(ports))(
+A style holding the service names of ports to complete. If this is
+not set by the user, the service names from `tt(/etc/services)' will
+be used.
+)
+kindex(prefix-hidden, completion style)
+item(tt(prefix-hidden))(
+This is used when matches with a common prefix are added (e.g. option
+names). If it is `true', this prefix will not be shown in the list of
+matches.
+
+The default value for this style is `false'.
+)
+kindex(prefix-needed, completion style)
+item(tt(prefix-needed))(
+This, too, is used for matches with a common prefix. If it is set to
+`true' this common prefix has to be typed by the user to generate the
+matches. E.g. for options this means that the `tt(-)', `tt(+)', or
+`tt(-)tt(-)' has to be on the line to make option names be completed at
+all.
+
+The default style for this style is `true'.
+)
+kindex(prompt, completion style)
+item(tt(prompt))(
+The tt(incremental-complete-word) widget shows the value of this
+style in the status line during incremental completion. The sequence
+`tt(%u)' is replaced by the unambiguous part of all matches if there
+is any and it is different from the word on the line. A `tt(%s)' is
+replaced with `tt(-no match-)', `tt(-no prefix-)', or an empty string
+if there is no completion matching the word on the line, if the
+matches have no common prefix different from the word on the line or
+if there is such a common prefix, respectively. The sequence `tt(%c)'
+is replaced by the name of the completer function that generated the
+matches (without the leading underscore). Finally, `tt(%n)' is
+replaced by the number of matches generated
+and if the tt(list) style is set, `tt(%l)' is
+replaced by `tt(...)' if the list of matches is too long to fit on the
+screen and with an empty string otherwise. If the tt(list) style is
+`false', `tt(%l)' will always be removed.
+)
+kindex(remove-all-dups, completion style)
+item(tt(remove-all-dups))(
+The tt(_history_complete_word) bindable command uses this to decide if 
+all duplicate matches should be removed, rather than just consecutive
+duplicates.
+)
+kindex(single-ignored, completion style)
+item(tt(single-ignored))(
+This is used by the tt(_ignored) completer. It allows to specify what
+should be done if it can generate only one match, which is often a
+special case. If its value is tt(show), the single match will only be shown, 
+not inserted. If the value is tt(menu), then the single match and the
+original string are both added as matches and menucompletion is
+started so that one can easily select either of them.
+)
+kindex(sort, completion style)
+item(tt(sort))(
+If set to `true', completion functions that generate words from the
+history as possible matches sort these words alphabetically instead of
+keeping them in the order in which they appear in the history (from
+youngest to oldest).
+
+The completion function that generates filenames as possible matches
+uses this style with the tt(files) tag to determine in which order the 
+names should be listed and completed when using menucompletion. The
+value may be one of tt(size) to sort them by the size of the file,
+tt(links) to sort them by the number of links to the file,
+tt(modification) (or tt(time) or tt(date)) to sort them by the last
+modification time, tt(access) to sort them by the last access time, or 
+tt(inode) (or tt(change)) to sort them by the last inode change
+time. Any other value (or not setting this style at all) makes them be 
+sorted alphabetically by name. If the value contains the string
+tt(reverse), sorting is done in decreasing order.
+
+This is also used by the tt(_expand) completer. Here, if it is set to
+`true', the expansions generated will always be sorted. If it is set
+to tt(menu), then the expansions are only sorted when they are offered 
+as single strings (not in the string containing all possible
+expansions).
+)
+kindex(special-dirs, completion style)
+item(tt(special-dirs))(
+Normally, the completion code will not produce the directory names
+tt(.) and tt(..) as possible completions. If this style is set to
+`true', it will add both `tt(.)' and `tt(..)' as possible completions,
+if it is set to tt(..), only `tt(..)' will be added.
+)
+kindex(squeeze-slashes, completion style)
+item(tt(squeeze-slashes))(
+If set to `true', sequences of slashes (like in `tt(foo//bar)') will be
+treated as if they were only one slash when completing pathnames.
+)
+kindex(stop, completion style)
+item(tt(stop))(
+If set to `true', the tt(_history_complete_word) bindable
+command will always insert matches as if menucompletion were started
+and it will stop when the last match is inserted. If this style is set
+to tt(verbose) a message will be displayed when the last match is reached.
+
+This style is also used by the tt(incremental-complete-word)
+widget. Here its value is used like the one for the tt(break)
+style. But all keys matching the pattern given as its value will stop
+incremental completion and will then execute their usual function.
+)
+kindex(subst-globs-only, completion style)
+item(tt(subst-globs-only))(
+This is used by the tt(_expand) completer. As for the tt(glob) style,
+the value should be a value usable in a `tt($((...)))' arithmetical
+expression. If it evaluates to `tt(1)', the expansion will only be
+used if they resulted from globbing. If only the expansions described
+for the tt(substitute) style described below resulted in expanded
+strings and globbing did not change the set of expanded strings, the
+tt(_expand) completer will do nothing.
+)
+kindex(substitute, completion style)
+item(tt(substitute))(
+If this is unset or set to the empty string, the tt(_expand) completer
+will first try to expand all substitutions in the string (such as
+`tt($LPAR()...RPAR())' and `tt(${...})'). If this is set to an
+non-empty string it should be an expression usable inside a `tt($((...)))'
+arithmetical expression. In this case, expansion of substitutions will
+be done if the expression evaluates to `tt(1)'. For example, with
+
+example(zstyle ':completion:*:expand:::' substitute '${NUMERIC:-1} != 1')
+
+substitution will be performed only if given an explicit numeric
+argument other than `tt(1)', as by typing `tt(ESC 2 TAB)'.
+)
+kindex(tag-order, completion style)
+kindex(tag-order, completion style)
+item(tt(tag-order))(
+This provides a mechanism for sorting how the tags available in a
+particular context will be used.
+
+The values for the style are sets of space-separated lists of tags.
+The tags in each value will be tried at the same time; if no match is
+found, the next value is used.
+
+For example:
+
+example(zstyle ':completion:*:complete:gunzip:*' tag-order \ 
+    arguments options)
+
+specifies that, many completion functions offer both completions for
+arguments and options immediately instead of offering first arguments
+and then option as usual.
+
+A string starting with an exclamation mark (`tt(!)')
+specifies names of tags that are not to be used -- the effect will be
+the same as if all other possible tags for the context had been
+listed.  If any string in the value consists of only a hyphen
+(`tt(-)'), then only the tags selected by the other strings will be
+generated.  Normally all tags not explicitly selected will be tried at
+the end if the selected tags did not generate any matches.  This means 
+that a value of only one hyphen turns off completion in a particular
+context.
+
+In strings not starting with an exclamation mark, it is also possible
+to specify tag labels instead of only tags. These are of the form
+`var(tag)tt(:)var(label)', where var(tag) is one of the tags offered
+by the completion function for the current context and var(label) is a 
+name. For this, the completion function will generate matches in the
+same way as for the var(tag) but it will use the var(label) in place
+of the tag in the context names used to look up styles. If the
+var(label) starts with a hyphen, the var(tag) is prepended to the
+var(label) to form the name used for lookup. This can be
+used to make the completion system try a certain tag more than once,
+supplying different style settings for each attempt. For example,
+
+example(zstyle ':completion:*:*:-command-:*' tag-order 'functions:-non-comp'
+zstyle ':completion:*:functions-non-comp' ignored-patterns '_*')
+
+Makes completion in command position first try only names of shell
+functions that don't match the pattern `tt(_*)'. If that generates no
+matches, the default of trying all the other things that can be
+completed in command position is used, including the names of all
+shell functions.
+
+The var(label) may optionally be followed by a second colon and a
+description. This description will then be used for the `tt(%d)' in
+the value of the tt(format) style instead of the default description
+supplied by the completion function. Spaces in the description have to 
+be quoted by preceding them with a backslash and a `tt(%d)' appearing
+in the description is replaced with the description given by the
+completion function.
+
+In each of the cases above, the tag may also be a pattern. In this
+case all of the offered tags matching this pattern will be used except 
+for those that are given explicitly in the same string. There are
+probably two main uses of this. One is the case where one wants to try
+one of the tags more than once, setting other styles differently for
+each try, but still wants to use all the other tags without having to
+bother to repeat them all. For example, to make completion of function
+names in command position first ignore all the completion functions
+starting with an underscore one could do:
+
+example(zstyle ':completion:*:*:-command-:*' tag-order \
+    'functions:-non-comp *' functions
+zstyle ':completion:*:functions-non-comp' ignored-patterns '_*')
+
+Here, the completion system will first try all tags offered, but will
+use the tag label tt(functions-non-comp) when looking up styles for
+the function names completed. For this, the tt(ignored-patterns) style 
+is set to make functions starting with an underscore be not considered 
+as possible matches. If none of the generated matches match the string 
+on the line, the completion system will use the second value of the
+tt(tag-order) style and complete functions names again, but this time
+using so name tt(functions) to look up styles, so that the
+tt(ignored-patterns) style will not be used and all function names
+will be considered.
+
+Of course, this can also be used to split the matches for one tag into 
+different groups. For example:
+
+example(zstyle ':completion:*:options' tag-order \
+    'options:-long:long options
+     options:-short:short options
+     options:-single-letter:single letter options'
+
+zstyle ':completion:*:options-long' ignored-patterns '[-+](|-|[^-]*)'
+zstyle ':completion:*:options-short' ignored-patterns '--*' '[-+]?'
+zstyle ':completion:*:options-single-letter' ignored-patterns '???*')
+
+With the tt(group-names) style set, this makes options beginning with
+`tt(-)tt(-)', options beginning with a single `tt(-)' or `tt(+)' but
+containing multiple characters and single-letter options be displayed
+in separate groups with different descriptions.
+
+The second interesting use of patterns is the case where one wants to
+try multiple match specifications one after another. The
+tt(matcher-list) style offers something similar, but it is tested very
+early in the completion system and hence can't be set for single
+commands or even more specific contexts. So, to make completion for
+the arguments of the command tt(foo) and only for this command first
+try normal completion with out any match specification and, if that
+generates no matches, try again with case-insensitive matching, one
+could do:
+
+example(zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
+zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}')
+
+This will make the completion system first try all the tags offered
+when completing after tt(foo) and use the tags to do the lookup. If
+that generates no matches, the second value of tt(tag-order) is
+used. This will make all tags be tried again, but this time using the
+names of the tags with the tt(-case) appended to them for lookup of
+styles. I.e. in this second attempt, the value for the tt(matcher)
+style from the second call to tt(zstyle) in the example will be used
+to make completion case-insensitive.
+
+Strings in the value may also be of the form `var(func)tt(())'. In
+this case the function var(func) will be called which can then define
+in which order tags are to be used based on additional context
+information. See the tt(_sort_tags) function below for a description
+of how such functions can be implemented. The return value of the
+function is used to decide if the following values for the style
+should be used. If it is zero, they are used and if it is non-zero,
+they are not used. For example:
+
+example(non-empty() { [[ -n $PREFIX ]] }
+zstyle ':completion:*:*:-command-:*' tag-order 'non-empty()')
+
+Makes completion in command position happen only if the string on the
+line is not empty (this is tested using the tt(PREFIX)
+parameter which is special in completion widgets, see
+ifzman(zshcompwid)\
+ifnzman(the section noderef(Completion System))\
+)\
+for a description of these special parameters).
+
+If no style has been defined for a context, the strings tt(arguments
+values) and tt(options) plus all tags offered by the completion
+function will be used to provide a sensible default behavior.
+)
+kindex(use-compctl, completion style)
+item(tt(use-compctl))(
+If this style is set to a string not equal to tt(false), tt(0),
+tt(no), and tt(off), the completion system will use any completion
+specifications defined with the tt(compctl) builtin command. If the
+style is unset, this will only be done if the tt(zsh/compctl) module
+is loaded. The string may also contain the substring tt(first) to make
+the definition for tt(compctl -T) be used and the substring
+tt(default) to make the one for tt(compctl -D) be used.
+
+Note that this is only intended to smooth the transition from
+tt(compctl) to the new completion system and may disappear in the
+future.
+
+Note also that the definitions from tt(compctl) will only be used if
+there is no special completion function for the command completion is
+done upon.
+)
+kindex(users, completion style)
+item(tt(users))(
+This may be set to a list of names that should be completed whenever 
+a username is needed. If it is not set or the string on the line
+doesn't match any of the strings in this list, all usernames will be
+completed.
+)
+kindex(users-hosts, completion style)
+item(tt(users-hosts))(
+The values of this style should be of the form
+`var(user)tt(@)var(host)' or `var(user)tt(:)var(host)'. It is used for
+commands that need pairs of
+user- and hostnames. For such commands, only the pairs from this style 
+are used and if, for example, the username is already typed, then only 
+the hostnames for which there is a pair with that username is defined.
+
+If set for the tt(my-accounts) tag, this is used for commands such as
+tt(rlogin) and tt(ssh). I.e. the style should contain the names of the 
+user's own accounts. With the tt(other-accounts) tag this is used for
+commands such as tt(talk) and tt(finger) and should contain other
+people's accounts. Finally, this may also be used by some commands with
+the tt(accounts) tag.
+)
+kindex(users-hosts-ports, completion style)
+item(tt(users-hosts-ports))(
+Like tt(users-hosts) but used for commands like tt(telnet) and
+containing strings of the form `var(user)tt(@)var(host)tt(:)var(port)'.
+)
+kindex(verbose, completion style)
+item(tt(verbose))(
+This is used in several contexts to decide if only a simple or a
+verbose list of matches should be generated. For example some commands 
+show descriptions for option names if this style is `true'.
+
+The default value for this style is `true'.
+)
+kindex(word, completion style)
+item(tt(word))(
+To find out if listing should be performed on its own, the tt(_list)
+completer normally compares the contents of the line with the contents
+the line had at the time of the last invocation. If this style is set to
+`true', comparison is done using only the current word. In this case,
+attempting completion on a word equal to the one when completion was called
+the last time will not delay the generation of matches.
+)
+enditem()
 
-The initialisation script tt(compinit) re-binds all the keys which perform
-completion to newly created widgets that all call the supplied widget
-function tt(_main_complete). This function acts as a wrapper calling
-the so-called `completer' functions that generate matches. If
-tt(_main_complete) is
-called with arguments, these are taken as the names of completer
-functions to be called in the order given.  If no arguments are given, the
-set of functions to try is taken from the colon-separated list in the
-configuration key tt(completer). For example, to use normal
-completion and correction if that doesn't generate any matches:
-
-indent(
-nofill(tt(compconf completer=_complete:_correct))
-)
-
-after sourcing tt(compinit). The default value for this configuration key
-set up in tt(compinit) is `tt(_complete)', i.e. normally only ordinary
-completion is tried. The tt(_main_complete) function uses the return value
-of the completer functions to decide if other completers should be
+texinode(Control Functions)(Bindable Commands)(Completion System Configuration)(Completion System)
+sect(Control Functions)
+cindex(completion system, choosing completers)
+
+The initialization script tt(compinit) redefines all the widgets
+which perform completion to call the supplied widget function
+tt(_main_complete). This function acts as a wrapper calling the
+so-called `completer' functions that generate matches. If
+tt(_main_complete) is called with arguments, these are taken as the
+names of completer functions to be called in the order given.  If no
+arguments are given, the set of functions to try is taken from the
+tt(completer) style. For example, to use normal completion and
+correction if that doesn't generate any matches:
+
+example(zstyle ':completion:*' completer _complete _correct)
+
+after calling tt(compinit). The default value for this style 
+is `tt(_complete)', i.e. normally only ordinary
+completion is tried. The tt(_main_complete) function uses the return
+value of the completer functions to decide if other completers should be
 called. If the return value is zero, no other completers are tried and the
 tt(_main_complete) function returns.
 
 The following completer functions are contained in the distribution (users
 may write their own):
 
+cindex(completion system, completers)
 startitem()
+findex(_complete)
 item(tt(_complete))(
 This completer generates all possible completions in a context-sensitive
-manner, i.e. using the tt(compdef) function
+manner, i.e. using the settings defined with the tt(compdef) function
 explained above and the current settings of all special parameters.
 
 To complete arguments of commands, tt(_complete) uses the utility function
@@ -228,53 +1816,68 @@ tt(-)var(context)tt(-), as mentioned above for the tt(#compdef) tag, are
 handled specially.  These are:
 
 startitem()
+kindex(-equal-, completion context)
 item(tt(-equal-))(
 for completion after an equal sign, other than one occurring in a
 shell-variable assignment.
 )
+kindex(-tilde-, completion context)
 item(tt(-tilde-))(
 for completion after a tilde (`tt(~)') character, but before a slash.
 )
+kindex(-redirect-, completion context)
 item(tt(-redirect-))(
 for completion after a redirection operator.
 )
+kindex(-math-, completion context)
 item(tt(-math-))(
 for completion inside mathematical contexts, such as
 `tt(LPAR()LPAR())...tt(RPAR()RPAR())'.
 )
+kindex(-subscript-, completion context)
 item(tt(-subscript-))(
 for completion inside subscripts.
 )
+kindex(-value-, completion context)
 item(tt(-value-))(
 for completion on the right hand side of an assignment.
 )
+kindex(-array-value-, completion context)
 item(tt(-array-value-))(
 for completion on the right hand side of an array-assignment
 (`tt(foo=LPAR()...RPAR())').
 )
+kindex(-condition-, completion context)
 item(tt(-condition-))(
 for completion inside conditions (`tt([[...]])').
 )
+kindex(-parameter-, completion context)
 item(tt(-parameter-))(
 for completing the name of a parameter expansion (`tt($...)').
 )
+kindex(-brace-parameter-, completion context)
 item(tt(-brace-parameter-))(
 for completing the name of a parameter expansion within braces
 (`tt(${...})').
 )
+kindex(-first-, completion context)
 item(tt(-first-))(
-for adding completions before any other other completion functions are
-tried (similar to the `tt(-T)' flag of tt(compctl)); if this
-function sets the tt(_compskip) parameter to any value, the completion
-system will not call any other function to generate matches.
+for adding completions before any other completion functions are
+tried; if this
+function sets the tt(_compskip) parameter to tt(all), no other
+completion functions will be called, if it is set to a string
+containing the substring tt(patterns), no pattern completion functions
+will be called, and if it is set to a string containing tt(default)
+the function for the `tt(-default-)' context will not be called, but
+functions defined for commands will.
 )
+kindex(-default-, completion context)
 item(tt(-default-))(
-for generating completions when no special completion function is used 
-(similar to the `tt(-D)' option of tt(compctl)).
+for generating completions when no special completion function is used.
 )
+kindex(-command-, completion context)
 item(tt(-command-))(
-for completing in a command position (as with the `tt(-C)' option of
-tt(compctl)).
+for completing in a command position.
 )
 enditem()
 
@@ -282,7 +1885,13 @@ Default implementations are supplied for each of these
 contexts, in most cases named after the context itself
 (e.g. completion for the `tt(-tilde-)' context is done by the function 
 named `tt(_tilde)').
+
+Before trying to find a function for a specific context, tt(_complete) 
+checks if the parameter `tt(compcontext)' is set to a non-empty
+value. If it is, the value is taken as the name of the context to use
+and the function defined for that context will be called.
 )
+findex(_approximate)
 item(tt(_approximate))(
 This completer function uses the tt(_complete) completer to generate
 a list of strings for the context the cursor is currently in, allowing 
@@ -299,105 +1908,45 @@ counted. The resulting list of corrected and completed strings is then
 presented to the user. The intended use of this completer function is to
 try after the normal tt(_complete) completer by setting:
 
-indent(
-nofill(tt(compconf completer=_complete:_approximate))
-)
+example(zstyle ':completion:*' completer _complete _approximate)
 
 This will give correcting completion if and only if
 normal completion doesn't yield any possible completions. When
 corrected completions are found, the completer will normally start
 menucompletion allowing you to cycle through these strings.
 
-The exact behavior of this completer can be changed by using the
-following configuration keys:
-
-startitem()
-item(tt(approximate_accept))(
-This should be set to the number of errors the correction code should
-accept. The completer will try to generate completions by first allowing
-one error, then two errors, and so on, until either a match
-was found or the maximum number of errors given by this key has
-been reached.
-
-If the value for this key contains a lower- or upper-case `tt(n)', the 
-completer function will take any numeric argument as the
-maximum number of errors allowed. For example, with
-
-indent(
-nofill(tt(compconf approximate_accept=2n))
-)
-
-two errors will be allowed if no numeric argument is given. However,
-with a numeric argument of six (as in `tt(ESC-6 TAB)'), up to six
-errors are accepted.  Hence with a value of `tt(0n)', no correcting
-completion will be attempted unless a numeric argument is given.
-
-If the value contains `tt(n)' or `tt(N)' and a exclamation mark
-(`tt(!)'), tt(_approximate) will var(not) try to generate corrected
-completions when given a numeric argument, so in this case the number given
-should be greater than zero.  For example, `tt(2n!)' specifies that
-correcting completion with two errors will usually be performed, but if a
-numeric argument is given, correcting completion will not be performed.
-)
-item(tt(approximate_original))(
-This key is used to specify whether the original string on which correcting 
-completion was attempted is to be included in the list of possible
-corrections. If it is set to any non-empty string, the original string 
-will be offered when cycling through the completions. Normally it will 
-appear as the first string, so that the command line does not change
-immediately; consecutive completion attempts will cycle through the
-corrected strings.  If the value for this key contains the substring
-`tt(last)', the original string will be the last one in the list, so
-that it appears just before wrapping around to the first corrected
-string again.  Also, if the value contains the substring `tt(always)',
-the original string will always be included; normally it is
-included only if more than one possible correction was generated.
-)
-item(tt(approximate_prompt))(
-This can be set to a string to be displayed on top of the
-corrected strings generated when cycling through them. This string
-may contain the control sequences `tt(%n)', `tt(%B)', etc. known from
-the `tt(-X)' option of tt(compctl). Also, the sequence `tt(%e)' will
-be replaced by the number of errors accepted to generate the corrected 
-strings.
-)
-item(tt(approximate_insert))(
-If this is set to a string starting with `tt(unambig)', the code will try
-to insert a usable unambiguous string in the command line instead of
-always cycling through the corrected strings. If such a unambiguous
-string could be found, the original string is not used, independent of
-the setting of tt(approximate_original). If no sensible string could be
-found, one can cycle through the corrected strings as usual.
-)
-enditem()
-
-If any of these keys is not set, but the the same key with the prefix
-`tt(correct)' instead of `tt(approximate)' is set, that value will be
-used. The forms beginning with `tt(correct)' are also used by the
-tt(_correct) completer function.
-
-The keys with the `tt(approximate)' prefix have no default values, but 
-tt(compinit) defines default values for tt(correct_accept) (which 
-is set to `tt(2n)'), and tt(correct_prompt).
+This completer uses the tags tt(corrections) and tt(original) when
+generating the possible coprrections and the original string. The
+tt(format) style for the former may contain the additional sequences
+`tt(%e)' and `tt(%o)' which will be replaced by the number of errors
+accepted to generate the corrections and the original string,
+respectively.
+
+Like all completers tt(_approximate) uses its name without the
+undersccore in the var(completer) field of the context name. Once it
+has started trying to generate matches, it will append a minus sign
+and the number of errors accepted in this attempt to its name. So on the
+first try the field contains `tt(approximate-1)', on the
+second try `tt(approximate-2)', and so on.
 )
+findex(_correct)
 item(tt(_correct))(
 Generate corrections (but not completions) for the current word; this is
-similar to spell-checking.  This calls tt(_approximate), but only the
-configuration parameters beginning tt(correct_) are used.
+similar to spell-checking.  This calls tt(_approximate) but uses a
+different var(completer) field in the context name.
 
 For example, with:
 
-indent(tt(
-nofill(compconf completer=_complete:_correct:_approximate)
-nofill(compconf correct_accept='2n!' approximate_accept=3n))
-)
+example(zstyle ':completion:::::' completer _complete _correct _approximate
+zstyle ':completion:*:correct:::' accept 2 not-numeric
+zstyle ':completion:*:approximate:::' accept 3 numeric)
 
 correction will accept up to two errors. If a numeric argument is
-given, correction will not be performed, but correcting completion will be,
-and will accept as many errors as given by the numeric argument.
-Without a numeric argument, first correction and then correcting
-completion will be tried, with the first one accepting two errors 
-and the second one accepting three errors.
+given, correction will not be performed, but correcting completion
+will be, and will accept as many errors as given by the numeric
+argument. Without a numeric argument, first correction and then
+correcting completion will be tried, with the first one accepting two
+errors  and the second one accepting three errors.
 
 This completer function is intended to be used without the
 tt(_approximate) completer or, as in the example, just before
@@ -405,21 +1954,31 @@ it. Using it after the tt(_approximate) completer is useless since
 tt(_approximate) will at least generate the corrected strings
 generated by the tt(_correct) completer -- and probably more.
 )
+findex(_match)
 item(tt(_match))(
 This completer is intended to be used after the tt(_complete)
 completer. It allows one to give patterns on the command line and
-to complete all strings metching these patterns from the set of possible
-completions for the context the cursor is in, without having to set
-the tt(GLOB_COMPLETE) option.
+to complete all strings matching these patterns from the set of
+possible completions for the context the cursor is in, without having
+to set the tt(GLOB_COMPLETE) option.
 
 Normally this will be done by taking the pattern from the line,
 inserting a `tt(*)' at the cursor position and comparing the resulting
 pattern with the possible completions generated. However, if the
-configuration key tt(match_original) has a value of `tt(only)', no
-`tt(*)' will be inserted. If tt(match_original) has any other non-empty
-string as its value, this completer will first try to generate matches
-without, then with a `tt(*)' inserted at the cursor position.
+tt(match-original) style has a value of tt(only), no `tt(*)' will be
+inserted. If tt(match-original) has any other non-empty string as its
+value, this completer will first try to generate matches without, then
+with a `tt(*)' inserted at the cursor position.
+
+The generated matches will be offered in a menucompletion unless the
+tt(insert-unambiguous) style is set to `true'. In
+this case menucompletion will only be started if no unambiguous string
+could be generated that is at least as long as the original string.
+
+Note that the matcher specifications defined globally or used by the
+completion functions will not be used.
 )
+findex(_expand)
 item(tt(_expand))(
 This completer function does not really do completion, but instead
 checks if the word on the command line is eligible for expansion and,
@@ -430,93 +1989,98 @@ will expand the string on the line before the completion widget is
 called. Also, this completer should be called before the tt(_complete) 
 completer function.
 
-Control over how the expanded string will be treated is possible with the 
-following configuration keys:
-
-startitem()
-item(tt(expand_substitute))(
-If this is unset or set to the empty string, the code will first try
-to expand all substitutions in the string (such as
-`tt($LPAR()...RPAR())' and `tt(${...})'). If this is set to an
-non-empty string it should be an expression usable inside a `tt($((...)))'
-arithmetical expression. In this case, expansion of substitutions will
-be done if the expression evaluates to `tt(1)'. For example, with
-
-indent(
-nofill(tt(compconf expand_substitute='NUMERIC != 1'))
-)
-
-substitution will be performed only if given an explicit numeric
-argument other than `tt(1)', as by typing `tt(ESC 2 TAB)'.
-)
-item(tt(expand_glob))(
-If this is unset or set to an empty string, globbing will be attempted
-on the word resulting from substitution or the original string. The
-values accepted for this key are the same as for tt(expand_substitute).
-)
-item(tt(expand_menu))(
-If this is unset or set to the empty string, the words resulting from
-expansion (if any) will simply be inserted in the command line,
-replacing the original string. However, if this key is set to a
-non-empty string, the user can cycle through the expansion as in
-menucompletion. Unless the value contains the substring `tt(only)',
-the user will still be offered all expansions at once as one of the
-strings to insert in the command line; normally, this possibility is
-offered first, but if the value contains the
-substring `tt(last)', it is offered last. Finally, if the value contains
-the substring `tt(sort)', the expansions will be sorted alphabetically,
-normally they are kept in the order the expansion produced them in.
-)
-item(tt(expand_original))(
-If this is set to an non-empty string, the original string from the
-line will be included in the list of strings the user can cycle
-through as in a menucompletion. If the value contains the substring
-`tt(last)', the original string will appear as the last string, with
-other values it is inserted as the first one (so that the command line
-does not change immediately).
-)
-item(tt(expand_prompt))(
-This may be set to a string that should be displayed before the
-possible expansions. This is passed to the `tt(-X)' option of
-tt(compadd) and thus may contain the control sequences `tt(%n)',
-`tt(%B)', etc. Also, the sequence `tt(%o)' in this string will be
-replaced by the original string.
-)
-enditem()
-
-None of these configuration keys has a default value.
+The tags used when generating expansions are tt(all-expansions) for
+the string containing all possible expansions, tt(expansions) when
+adding the possible expansions as single matches and tt(original) when 
+adding the original string from the line. In which order these strings 
+are generated and which of these strings are generated at all can be
+controlled by using the tt(group-order) style and by modifying the
+tt(tag-order) style, as usual.
+
+The format string for tt(all-expansions) and for tt(expansions) may
+contain the sequence `tt(%o)' which will be replaced by the original
+string from the line.
+
+Which kind of expansion is tried is controlled by the tt(substitute)
+and tt(glob) styles. Note that neither of these has a default value so 
+that they have to be set to make tt(_expand) generate any expansions
+at all.
+
+In a different mode selected by the tt(completions) style, all
+em(completions) generated for the string on the line are inserted.
 )
+findex(_list)
 item(tt(_list))(
 This completer allows one to delay the insertion of matches until
 completion is attempted a second time without the word on the line
 being changed. On the first attempt, only the list of matches will be
-shown. Configuration keys understood are:
-
-startitem()
-item(tt(list_condition))(
-If this key is unset or set to the empty string, the insertion of
-matches will be delayed unconditionally. If this value is set, it
-should be set to an expression usable inside a `tt($((...)))'
-arithmetical expression. In this case, delaying will be done if the
-expression evaluates to `tt(1)'. For example, with
-
-indent(
-nofill(tt(compconf list_condition='NUMERIC != 1'))
+shown. Styles used are tt(condition) and tt(word), see
+ifzman(the section `Completion System Configuration' above)\
+ifnzman(noderef(Completion System Configuration)).
 )
-
-delaying will be done only if given an explicit numeric argument
-other than `tt(1)'.
+findex(_oldlist)
+item(tt(_oldlist))(
+This completer controls how the standard completion widgets behave
+when there is an existing list of completions which may have been
+generated by a special completion (i.e. a separately-bound completion
+command).  It should appear in the list of completers before any of
+the widgets which generate matches.  It uses two styles: tt(old-list) and
+tt(old-menu), see
+ifzman(the section `Completion System Configuration' above)\
+ifnzman(noderef(Completion System Configuration)).
 )
-item(tt(list_word))(
-To find out if listing should be performed on its own, the code normally
-compares the contents of the line with the contents the line had at the
-time of the last invocation. If this key is set to an non-empty string,
-comparison is done using only the current word. So if it is set,
-attempting completion on a word equal to the one when completion was called
-the last time will not delay the generation of matches.
+findex(_prefix)
+item(tt(_prefix))(
+This completer can be used to try completion with the suffix after the 
+cursor ignored. I.e. the suffix will not be considered to be part of
+the word to complete and hence does not need to be matched. It uses
+the tt(completer) style to decide which other completers to call to
+try to generate matches. If this style is unset, the completers
+currently used by the whole completion are used -- except, of course,
+the tt(_prefix) completer itself. Also, if this completer appears more
+than once in the list of completers only those completers not
+already tried by the last invocation of tt(_prefix) will be
+called.
+
+For example, consider this global tt(completer) style:
+
+example(zstyle ':completion:*' completer \
+    _complete _prefix _correct _prefix:foo)
+
+This makes the tt(_prefix) completer try normal completion with the
+suffix ignored. If that doesn't generate any matches and neither does
+the call to the tt(_correct) completer after it, then tt(_prefix) will 
+be called a second time and will now only try correction with the
+suffix ignored. If you want to use tt(_prefix) as the last resort and
+want it to try only normal completion, you need to call:
+
+example(zstyle ':completion:*' completer _complete ... _prefix
+zstyle ':completion::prefix:*' completer _complete)
+
+The tt(add-space) style is used, too. If it is set to `true' then
+tt(_prefix) will insert a space between the matches generated (if any) 
+and the suffix.
+
+Note that using this completer will only work if the
+tt(COMPLETE_IN_WORD) option is set. Because otherwise the cursor will
+be set after the word before the completion code is called and hence
+there will be no suffix.
 )
-enditem()
+findex(_ignored)
+item(tt(_ignored))(
+Using the tt(ignored-patterns) style it is possible to make some
+matches be ignored. This completer allows to complete these matches as 
+if no tt(ignored-patterns) style were set. Which completers are called 
+for this is determined in the same way as for the tt(_prefix)
+completer.
+
+Finally, tt(_ignored) uses the tt(single-ignored) style if only one
+match could be generated. It can be set to tt(show) to make that match 
+be only displayed, not inserted into the line or it can be set to
+tt(menu) to make the single match and the original string from the
+line be offered in a menucompletion.
 )
+findex(_menu)
 item(tt(_menu))(
 This completer is a simple example function implemented to show how
 menucompletion can be done in shell code. It should be used as the
@@ -528,8 +2092,128 @@ tt(accept-and-menu-complete).
 )
 enditem()
 
-texinode(Completion Functions)()(Control Functions)(Completion System)
+texinode(Bindable Commands)(Completion Functions)(Control Functions)(Completion System)
+sect(Bindable Commands)
+cindex(completion system, bindable commands)
+
+In addition to the context-dependent completions provided, which are
+expected to work in an intuitively obvious way, there are a few widgets
+implementing special behaviour which can be bound separately to keys.  The
+following is a list of these and their default bindings.
+
+startitem()
+findex(_bash_completions)
+item(tt(_bash_completions))(
+This function is used by two widgets, tt(_bash_complete-word) and
+tt(_bash_list-choices).  It exists to provide compatibility with
+completion bindings in bash.  The last character of the binding determines
+what is completed: `tt(!)', command names; `tt($)', environment variables;
+`tt(@)', host names; `tt(/)', file names; `tt(~)' user names.  In bash, the
+binding preceeded by `tt(\e)' gives completion, and preceeded by `tt(^X)'
+lists options.  As some of these bindings clash with standard zsh
+bindings, only `tt(\e~)' and `tt(^X~)' are bound by default.  To add the
+rest, the following should be added to tt(.zshrc) after tt(compinit) has
+been run:
+
+example(for key in '!' '$' '@' '/' '~'; do
+  bindkey "\e$key" _bash_complete-word
+  bindkey "^X$key" _bash_list-choices
+done)
+
+This includes the bindings for `tt(~)' in case they were already bound to
+something else; the completion code does not override user bindings.
+)
+findex(_correct_filename (^XC))
+item(tt(_correct_filename (^XC)))(
+Correct the filename path at the cursor position.  Allows up to six errors
+in the name.  Can also be called with an argument to correct
+a filename path, independently of zle; the correction is printed on
+standard output.
+)
+findex(_correct_word) (^Xc)
+item(tt(_correct_word) (^Xc))(
+Performs correction of the current argument using the usual contextual
+completions as possible choices. This stores the string
+`tt(correct-word)' in the var(function) field of the context name and
+then calls the tt(_correct) completer.
+)
+findex(_expand_word (^Xe))
+item(tt(_expand_word (^Xe)))(
+Performs expansion on the current word:  equivalent to the standard
+tt(expand-word) command, but using the tt(_expand) completer. Before
+calling it, the var(function) field is set to `tt(expand-word)'.
+)
+findex(_history_complete_word) (\e/)
+item(tt(_history_complete_word) (\e/))(
+Complete words from the shell's command history. This uses the
+tt(list), tt(remove-all-dups), tt(sort), and tt(stop) styles.
+)
+findex(_most_recent_file (^Xm))
+item(tt(_most_recent_file (^Xm)))(
+Complete the name of the most recently modified file matching the pattern
+on the command line (which may be blank).  If given a numeric argument
+var(N), complete the var(N)th most recently modified file.  Note the
+completion, if any, is always unique.
+)
+findex(_next_tags)
+item(tt(_next_tags))(
+This allows to complete types of matches that are not immediately
+offered because of the setting of the tt(tag-order) style. After a
+normal completion was tried, invoking this command makes the matches
+for the next tag (or set of tags) be used. Repeatedly invoking this
+command makes the following tags be used. To be able to complete the
+matches selected by tt(_next_tags), the tt(completer) style should
+contain tt(_next_tags) as its first string. With that, the normal key
+binding (normally tt(TAB)) can be used to complete the matches shown
+after the call to tt(_next_tags).
+
+Normally, this command is not bound to a key. To invoke it with, say
+`tt(^Xn)', one would use:
+
+example(zle -C _next_tags complete-word _next_tags
+bindkey '^Xn' _next_tags)
+)
+findex(_read_comp (^X^R))
+item(tt(_read_comp (^X^R)))(
+Prompt the user for a string, and use that to perform completion on the
+current word.  There are two possibilities for the string.  First, it can
+be a set of words beginning `tt(_)', for example `tt(_files -/)', in which
+case the function with any arguments will be called to generate the
+completions.  Unambiguous parts of the function name will be completed
+automatically (normal completion is not available at this point) until a
+space is typed.
+
+Any other string will be passed as a set of arguments to
+tt(compadd) and should hence be an expression specifying what should
+be completed.
+
+A very restricted set of editing commands is available when reading the
+string:  `tt(DEL)' and `tt(^H)' delete the last character; `tt(^U)' deletes
+the line, and `tt(^C)' and `tt(^G)' abort the function, while `tt(RET)'
+accepts the completion.  Note the string is used verbatim as a command
+line, so arguments must be quoted in accordance with standard shell rules.
+
+Once a string has been read, the next call to tt(_read_comp) will use the
+existing string instead of reading a new one.  To force a new string to be
+read, call tt(_read_comp) with a numeric argument.
+)
+findex(_complete_help (^Xh))
+item(tt(_complete_help (^Xh)))(
+This widget displays information about the context names, 
+the tags, the styles, and the completion functions used 
+when completing at the current cursor position.
+
+Note that, depending on the control flow in the completion functions
+called, the information about the styles may be
+incomplete. I.e. depending on the settings for some styles other
+styles may be used, and, depending on the user's settings, only the
+first sort of styles may be detected by tt(_complete_help).
+)
+enditem()
+
+texinode(Completion Functions)(Completion Directories)(Bindable Commands)(Completion System)
 sect(Utility Functions)
+cindex(completion system, utility functions)
 
 Descriptions follow for utility functions that may be
 useful when writing completion functions.  Most of these reside in the
@@ -539,8 +2223,26 @@ generating matches all follow the convention of returning zero if they
 generated completions and non-zero if no matching completions could be 
 added.
 
+When writing completion functions or other ZLE widgets that call
+completion, it might be interesting to know about two more features
+offered by the tt(_main_complete) function. The arrays
+tt(compprefuncs) and tt(comppostfuncs) may be set to contain names of
+functions that are to be called immediately before or after completion 
+has been tried. The functions will only be called once, unless they
+put themselves into the array again.
+
 startitem()
-item(tt(_compalso))(
+findex(_funcall)
+item(tt(_funcall) var(return) var(name) [ var(args) ... ])(
+If a function var(name) exists, it is called with the arguments
+var(args). Unless it is the empty string or a single hyphen,
+var(return) is taken as the name of a parameter and the return status
+from the called function is stored in it.
+The return value of tt(_funcall) itself is zero if the function
+var(name) exists and was called and non-zero otherwise.
+)
+findex(_compalso)
+item(tt(_compalso) var(names) ...)(
 This function looks up the definitions for the context and command
 names given as arguments and calls the handler functions for them if
 there is a definition (given with the tt(compdef) function). For
@@ -548,6 +2250,20 @@ example, the function completing inside subscripts might use
 `tt(_compalso -math-)' to include the completions generated for
 mathematical environments.
 )
+findex(_call)
+item(tt(_call) var(tag) var(string) ...)(
+This function is used in places where a command is called and the user 
+should have the possibility to override the default for calling this
+command. It looks up the tt(command) style with the supplied
+var(tag). If the style is set, its value is used as the command to
+execute.
+
+In any case, the var(strings) from the call to tt(_call) or from the
+style are concatenated with spaces between them and the resulting
+string is evaluated. The return value is the return value of the
+command called.
+)
+findex(_normal)
 item(tt(_normal))(
 This function is used for normal command completion.  If
 completion is attempted on the first word, command names are
@@ -561,14 +2277,271 @@ the tt(words) array, decrements the tt(CURRENT) parameter, then calls this
 function.
 
 When calling a function defined for a pattern, this function also
-checks if the parameter tt(_compskip) is set. If it was set by the
-function called, no further completion functions are called. With this 
+checks if the parameter tt(_compskip) is set and uses the value in the 
+same way it is used after calling the completion function for the
+tt(-first-) context. With this 
 one can write a pattern completion function that keeps other functions 
 from being tried simply by setting this parameter to any value.
 )
-item(tt(_multi_parts))(
-This functions gets two arguments: a separator character and an
-array.  As usual, the array may be either the
+findex(_description)
+item(tt(_description) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])(
+This function tests some styles for the var(tag) and and stores
+options usable for tt(compadd) in the array with the given var(name)
+which guarantee that the matches are generated as requested by the
+user. The styles tested are: tt(format) (which is first tested for the
+given tag and then for the tt(descriptions) tag if that isn't
+defined), tt(hidden) and tt(group-name) (the last two are tested only
+for the tag given as the first argument). This function also calls the
+tt(_setup) function which tests some more styles.
+
+The format string from the style (if any) will be modified so that the 
+sequence `tt(%d)' is replaced by the var(descr) given as the third
+argument. If tt(_description) is called with more than three
+arguments, these var(specs) should be of the form
+`var(char)tt(:)var(str)' and every appearance of `tt(%)var(char)' in
+the format string will be replaced by var(string).
+
+The options placed in the array will also make sure that the matches
+are placed in a separate group, depending on the value of the
+tt(group-name) style. Normally a sorted group will be used for this
+(with the `tt(-J)' option), but if a option starting with `tt(-V)',
+`tt(-J)', `tt(-1)', or `tt(-2)' is given, that option will be included
+in the array, so that it is possible to make the group unsorted by
+giving the option `tt(-V)', `tt(-1V)', or `tt(-2V)'. 
+
+In most cases, this function will be used like this:
+
+example(local expl
+_description expl files file
+compadd "$expl[@]" - "$files[@]")
+)
+findex(_message)
+item(tt(_message) [ -r ] var(descr))(
+The var(descr) is used like the third
+argument to the tt(_description) function. However, the resulting
+string will always be shown whether or not matches were
+generated. This is useful to display help texts in places where no
+completions can be generated automatically.
+
+This function also uses the tt(format) style for the tt(messages) tag in
+preference to the tt(format) style for the tt(descriptions) tag. The
+latter is used only if the former is unset.
+
+If the tt(-r) option is given, no style is used and the var(descr) is
+used literally as the string to display. This is only used in cases
+where that string is taken from some pre-processed argument list
+containing an expanded description.
+)
+findex(_setup)
+item(tt(_setup) var(tag))(
+This function expects a tag as its argument and sets up the special
+parameters used by the completion system appropriately for the tag,
+using styles such as tt(list-colors) and tt(last-prompt).
+
+Note that this function is called automatically from tt(_description)
+so that one normally doesn't have to call it explicitly.
+)
+findex(_tags)
+item(tt(_tags) [ tt(-C) var(name) [ var(tags) ... ] ])(
+If called with arguments, these are taken as the names of the tags for 
+the types of matches the calling completion function can generate in
+the current context. These tags are stored internally and sorted by
+using the tt(tag-order) style. Following calls to this function
+without arguments from the same function will then select the first,
+second, etc. set of tags requested by the user. To test if a certain
+tag should be tried, the tt(_requested) function has to be called (see 
+below).
+
+The return value is zero if at least one of the tags is requested and
+non-zero otherwise. 
+
+This function also accepts the tt(-C) option followed by a
+var(name). This name is temporarily (i.e. not visible outside
+tt(_tags)) stored in the argument field of the context name in the
+tt(curcontext) parameter. This allows to make tt(_tags) use a more
+specific context name without having to change and reset the
+tt(curcontext) parameter (which would otherwise have the same effect).
+)
+findex(_next_label)
+item(tt(_next_label) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(options) ... ])(
+This function should be called repeatedly to generate the tag
+labels. On each call it will check if another tag label is to be used 
+and, if there is at least one, zero is returned. If no more tag
+labels are to be used, a non-zero status is returned.
+
+The tt(-12JV) options and the first three arguments are given to the
+tt(_desciption) function using the tag label instead of the first
+argument is appropriate. The var(options) given after the var(descr)
+should be other options to be used for tt(compadd) or whatever
+function is to be called to add the matches. tt(_next_label) will store these 
+var(options) in the parameter whose var(name) is given as the second
+argument. This is done in such a way that the description given by the 
+user to the tt(tag-order) style is prefered over the one given to
+tt(_next_label).
+
+Note that this function must not be called without a previous call to
+tt(_tags), tt(_wanted) or tt(_requested) because it uses the tag label
+for the current tag found by these functions.
+
+A normal use of this function for the tag labels for the tag tt(foo)
+looks like this:
+
+example(local expl ret=1
+...
+_wanted foo || return 1
+...
+while _next_label foo expl '...'; do
+  compadd "$expl[@]" ... && ret=0
+done
+...
+return ret
+)
+)
+findex(_all_labels)
+item(tt(_all_labels) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(command) var(args) ... ])(
+This is a convenient interface to the tt(_next_label) function, implementing
+the loop shown in the example above. The var(command) is the one that
+should be called to generate the matches. The options stored in the
+parameter var(name) will automatically be inserted into the var(args)
+given to the var(command). Normally, they are put directly after the
+var(command), but if one of the var(args) is a single hyphen, they are 
+inserted directly before that. If the hyphen is the last argument,
+that will be removed from the argument list before the var(command) is 
+called. This allows to use tt(_all_labels) in almost all cases where the
+matches can be generated by a single call to the tt(compadd) builtin
+command or by a call to one of the utility functions.
+
+For example:
+
+example(local expl
+...
+_wanted foo || return 1
+...
+_all_labels foo expl '...' compadd ... - $matches)
+
+Will complete the strings from the tt(matches) parameter, using
+tt(compadd) with additional options which will take precedence over
+those generated by tt(_all_labels).
+)
+findex(_requested)
+item(tt(_requested) [ tt(-12VJ) ] var(tag) [ var(name) var(descr) [ var(command) var(args) ... ] ])(
+A function that uses tt(_tags) to register tags and then calls it to
+loop over the requested sets of tags should call this function to
+check if a certain tag is currently requested. This normally has to be 
+done in a loop such as:
+
+example(_tags foo bar baz
+while _tags; do
+  if _requested foo; then
+    ...
+  fi
+  ... # test other tags
+  ... # exit loop if matches were generated
+done)
+
+So, the first argument for tt(_requested) is used as the name of a tag 
+and if that tag is currently requested, the return value is zero (and
+non-zero otherwise).
+
+If the var(name) and the var(descr) are given, tt(_requested) calls the
+tt(_description) function with these arguments, including the options.
+
+If the var(command) is given, the tt(_all_labels) function will be called
+immediatly with the same arguments.
+
+This is often useful to do both the testing of the tag,
+getting the description for the matches and adding the matches at
+once. E.g.:
+
+example(local expl ret=1
+_tags foo bar baz
+while _tags; do
+  _requested foo expl 'description' \ 
+      compadd foobar foobaz && ret=0
+  ...
+  (( ret )) || break
+done)
+)
+findex(_wanted)
+item(tt(_wanted) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])(
+In many contexts only one type of matches can be generated but even
+then it should be tested if the tag representing those matches is
+requested by the user. This function makes that easier.
+
+Like tt(_requested) it gets arguments as for tt(_description).
+With the var(tag) it calls tt(_tags) and if that returns zero 
+(i.e. the var(tag) is requested by the user) it calls tt(_description). So, 
+if you want to offer only one tag and immediatly want to use the
+description built, you can just do:
+
+example(_wanted tag expl 'description' \ 
+    compadd matches...)
+)
+findex(_alternative)
+item(tt(_alternative) [ tt(-C) var(name) ] var(specs) ...)(
+This function is useful if you offer multiple tags and building the
+matches for them is easy enough. It basically implements a loop like
+the one described for the tt(_tags) function above above.
+
+The tags to use and what to do if the tags are requested are described 
+using the var(specs) which are of the form:
+`var(tag)tt(:)var(descr)tt(:)var(action)'. The var(tag)s are offered
+using tt(_tags) and if the tag is requested, the var(action) is
+executed with the given var(descr) (description). The var(action)s
+supported are those used by the tt(_arguments) function (described
+below), without the `tt(->)var(state)' form.
+
+For example, the var(action) may be a simple function call. With that
+one could do:
+
+example(_alternative \ 
+    'users:user:_users' \ 
+    'hosts:host:_hosts')
+
+to offer usernames and hostnames as possible matches (which are
+generated by the tt(_users) and tt(_hosts) functions respectively).
+
+Note that, like tt(_arguments) this will also use tt(_all_labels) to execute 
+the actions, so one doesn't need to call that explicitly unless
+another tag is to be used, for example in a function called from
+tt(_alternative).
+
+Like tt(_tags) this function supports the tt(-C) option to give a
+different name for the argument context field.
+)
+findex(_describe)
+item(tt(_describe) var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)(
+This function can be used to add options or values with descriptions
+as matches. The var(descr) is taken as a string to display above
+the matches if the tt(format) style for the tt(descriptions) tag is set.
+
+After this one or two names of arrays followed by options to give
+to tt(compadd) must be given. The first array contains the possible
+completions with their descriptions (with the description separated
+by a colon from the completion string). If the second array is given,
+it should have the same number of elements as the first one and these
+elements are added as possible completions instead of the strings from 
+the first array. In any case, however, the completion list will show
+the strings from the first array.
+
+Any number of array/option sequences may be given separated by
+`tt(-)tt(-)'. This allows one to display matches together that need
+to be added with different options for tt(compadd).
+
+Before the first argument, the option `tt(-o)' may be given. It says
+that the matches added are option names. This will make tt(_describe)
+use the tt(prefix-hidden), tt(prefix-needed) and tt(verbose) styles
+to find out if the strings should be added at all and if the
+descriptions should be shown. Without the `tt(-o)' option, only the
+tt(verbose) style is used.
+
+tt(_describe) uses the tt(_all_labels) function to generate the matches, so
+that one doesn't need to put it into a loop over the tag labels.
+)
+findex(_multi_parts)
+item(tt(_multi_parts) var(sep) var(array))(
+This function gets two arguments: a separator character and an
+array.  As usual, the var(array) may be either the
 name of an array parameter or a literal array in the form
 `tt(LPAR()foo bar)tt(RPAR())' (i.e. a list of words separated by white 
 space in parentheses). With these arguments, this function will
@@ -579,10 +2552,19 @@ tar file in an array and then calls this function to complete these
 names in the way normal filenames are completed by the
 tt(_path_files) function.
 
+If given the tt(-i) option a single match left will be accepted
+immediatly even if that means that additional parts for which no
+separators were on the line are to be inserted. When completing from a 
+fixed set of possible completions which are really words, this is
+often the expected behaviour. But if tt(_multi_parts) should behave
+like completing pathnames, the tt(-i) option should not be used.
+
 Like other utility functions, this function accepts the `tt(-V)',
-`tt(-J)', and `tt(-X)' options with an argument and passes them to the
-tt(compadd) builtin.
+`tt(-J)', `tt(-1)', `tt(-2)', `tt(-n)', `tt(-f)', `tt(-X)', `tt(-M)', `tt(-P)',
+`tt(-S)', `tt(-r)', `tt(-R)', and `tt(-q)' options and passes them to
+the tt(compadd) builtin.
 )
+findex(_sep_parts)
 item(tt(_sep_parts))(
 This function gets as arguments alternating arrays and separators.
 The arrays specify completions for parts of strings to be separated by the
@@ -592,47 +2574,59 @@ a quoted list of words in parentheses. For example, with the array
 complete the string  `tt(f)' to `tt(foo)' and the string `tt(b@n)' to
 `tt(bar@news)'.
 
-This function passes the `tt(-V)', `tt(-J)', and `tt(-X)' options and
-their arguments to the tt(compadd) builtin used to add the matches.
+This function passes the `tt(-V)', `tt(-J)', `tt(-1)', `tt(-2)',
+`tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)', `tt(-r)', `tt(-R)',
+and `tt(-q)' options and their arguments to the tt(compadd) builtin
+used to add the matches.
 )
+findex(_path_files)
+findex(_files)
 item(tt(_path_files) and tt(_files))(
 The function tt(_path_files) is used throughout the shell code
-to complete filenames. The advantage over the builtin
-completion functions is that it allows completion of partial paths. For
+to complete filenames. It allows completion of partial paths. For
 example, the string `tt(/u/i/s/sig)' may be completed to
-`tt(/usr/include/sys/signal.h)'.  The options `tt(-/)', `tt(-f)', `tt(-g)',
-and `tt(-W)' are available as for the tt(compctl)
-and tt(compgen) builtins; tt(-f) is the default. Additionally, the `tt(-F)'
+`tt(/usr/include/sys/signal.h)'.  The option `tt(-/)' specifies that
+only directories should be completed. The option `tt(-g) var(pattern)' 
+says that only files matching the var(pattern) should be completed,
+and the `tt(-f)' option, which is the default, completes all
+filenames. The option `tt(-W) var(paths)' may be used to specify path
+prefixes that are to be prepended to the string from the line to
+generate the filenames but that should not be inserted in the line or
+shown in a completion listing. The var(paths) may be the name of an
+array parameter, a literal list of paths enclosed in parentheses or
+an absolute pathname.
+Additionally, the `tt(-F)'
 option from the tt(compadd) builtin is supported, giving direct control
-over which filenames should be ignored as done by the tt(fignore)
-parameter in normal completion.
+over which filenames should be ignored. If no such option is given,
+the tt(ignored-suffixes) style is used.
 
-The function tt(_files) calls tt(_path_files) with all the arguments
-it was passed and, if that generated no matches, call tt(_path_files) again
-without any tt(-g) or tt(-/) option, thus generating all filenames.
+The function tt(_files) uses the tt(file-patterns) style and calls
+tt(_path_files) with all the arguments it was passed except for tt(-g) 
+and tt(-/). These two options are used depending on the setting of the 
+tt(file-patterns) style.
 
-These functions also accept the `tt(-J)', `tt(-V)', `tt(-X)', `tt(-P)',
-`tt(-S)', `tt(-q)', `tt(-r)', and `tt(-R)' options from the
-tt(compadd) builtin.
+These functions also accept the `tt(-J)', `tt(-V)', `tt(-1)',
+`tt(-2)', `tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)', `tt(-q)',
+`tt(-r)', and `tt(-R)' options from the tt(compadd) builtin.
 
-Finally, the tt(_path_files) function supports one configuration key:
-tt(path_expand). If this is set to any non-empty string, the partially
-typed path from the line will be expanded as far as possible even if
-trailing pathname components can not be completed.
+Finally, the tt(_path_files) function  uses the styles tt(expand),
+tt(cursor) and tt(special-dirs) with the tt(paths) tag.
 )
+findex(_parameters)
 item(tt(_parameters))(
-This should be used to complete parameter names if you need some of the
-extra options of tt(compadd). It first tries to complete only non-local
-parameters. All arguments are passed unchanged to the tt(compadd) builtin.
+This should be used to complete parameter names. All arguments are
+passed unchanged to the tt(compadd) builtin.
 )
+findex(_options)
 item(tt(_options))(
-This can be used to complete option names. The difference to the
-`tt(-o)' option of tt(compgen) is that this function uses a matching
+This can be used to complete option names. It uses a matching
 specification that ignores a leading `tt(no)', ignores underscores and 
 allows the user to type upper-case letters, making them match their
 lower-case counterparts. All arguments passed to this function are
-propagated unchanged to the tt(compgen) builtin.
+propagated unchanged to the tt(compadd) builtin.
 )
+findex(_set_options)
+findex(_unset_options)
 item(tt(_set_options) and tt(_unset_options))(
 These functions complete only set or unset options, with the same
 matching specification used in the tt(_options) function.
@@ -642,37 +2636,248 @@ function for these functions to work properly. The lines in question
 are used to store the option settings in effect before the completion
 widget locally sets the options it needs.
 )
-item(tt(_long_options))(
+findex(_arguments)
+item(tt(_arguments) var(specs) ...)(
 This function resides in the tt(Base) subdirectory of the example
 completion system because it is not used by the core system.
 
-This function is used to complete long options for commands that
-support the `tt(--help)' option as, for example, most of the GNU
-commands do. For this it invokes the command from the line with the
-`tt(--help)' option and then parses the output to find possible option
-names. Note that this means that you should be careful to make sure
-that this function is not called for a command that does not support
-this option.
+This function can be used to complete words on the line by simply
+describing the arguments the command on the line gets. The description 
+is given as arguments to this function, with each var(spec) describing
+one option or normal argument of the command. The descriptions
+understood are:
 
-For options that get an argument after a `tt(=)', the function also
-automatically tries to find out what should be completed as the argument.
-The possible completions for option-arguments can be described with
-the arguments to this function. This is done by giving pairs of
-patterns and actions as consecutive arguments. The actions specify
-what should be done to complete arguments of those options whose
-description match the pattern. The action may be a list of words in
-brackets or in parentheses, separated by spaces. A list in square brackets
-denotes possible values for an optional argument, a list in parentheses
-gives words to complete for mandatory arguments. If the action does
-not start with a square bracket or parenthesis, it should be the name of a
-command (probably with arguments) that should be invoked to complete 
-after the equal sign. Example:
-
-indent(
-nofill(tt(_long_options '*\*'     '(yes no)' \))
-nofill(tt(              '*=FILE*' '_files' \))
-nofill(tt(              '*=DIR*'  '_files -/'))
+startitem()
+item(var(n)tt(:)var(message)tt(:)var(action))(
+This describes the var(n)'th normal argument. The var(message) will be 
+printed above the matches generated and the var(action) says what can
+be completed in this position (see below). If there are two colons
+before the var(message), this describes an optional argument.
+)
+item(tt(:)var(message)tt(:)var(action))(
+Like the previous one, but describing the em(next) argument. I.e. if
+you want to describe all arguments a command can get, you can leave
+out the numbers in the description and just use this form to describe
+them one after another in the order they have to appear on the line.
+)
+item(tt(*:)var(message)tt(:)var(action))(
+This describes how arguments are to be completed for which no
+description with one of the first two forms was given. This also means 
+that any number of arguments can be completed.
+
+If there are two colons before the var(message) (as in
+`tt(*::)var(message)tt(:)var(action)') the tt(words) special array and 
+the tt(CURRENT) special parameter will be restricted to only the
+normal arguments when the var(action) is executed or evaluated. With
+three colons before the var(message) they will be restricted to only
+the normal arguments covered by this description.
 )
+item(var(opt-spec)[var(description) ...])(
+This describes an option and (if at least one var(description) is
+given) the arguments that have to come after the option. If no
+var(description) is given, this will only be used to offer the option
+name as a possible completion in the right places. Each
+var(description) has to be of the form
+`tt(:)var(message)tt(:)var(action)' or
+`tt(::)var(message)tt(:)var(action)', where the second form describes
+an optional argument and the first one describes a mandatory argument.
+The last description may also be of the form
+`tt(:*:)var(message)tt(:)var(action)' or
+`tt(:*)var(pattern)tt(:)var(message)tt(:)var(action)'. These describe
+multiple arguments. In the first form all following words on the line
+are to be completed as described by the var(action), in the second
+form all words up to a word matching the given var(pattern) are to be
+completed using the var(action). The `tt(*)' or the var(pattern) may
+also be separated from the var(message) by two or three colons. With
+two colons the tt(words) special array and the tt(CURRENT) special
+parameter are modified to refer only to the words after the option
+(with two colons) or to the words covered by this description (with
+three colons) during the execution or evaluation of the
+var(action). Note that only one such `tt(:*)'-specification is useful
+and no other argument specification may be given after it.
+
+In the simplest form the var(opt-spec) is just the option name
+beginning with a minus or a plus sign, such as `tt(-foo)'. If the
+command accepts the option both with a leading minus and a plus sign,
+one can use either tt(-+foo) or tt(+-foo) to define both options at
+once. In this
+case, the first argument for the option (if any) has to come as a
+separate word directly after the option and the option may appear only 
+once on the line (and if it is already on the line, the option name
+will not be offered as a possible completion again). If the first
+argument for the option has to come directly after the option name
+em(in the same word), a minus sign should be added to the end of the
+var(opt-spec), as in `tt(-foo-)'. If the first argument may be given
+in one string with the option name, but may also be given as a
+separate argument after the option, a plus sign should be used
+instead. If the argument may be given as the next string or in same
+string as the option name but separated from it by an equal sign, a
+`tt(=)' should be used instead of the minus or plus sign.
+
+Note that this and the shortcut syntax with a leading tt(-+) or tt(+-) 
+means that for options like tt(-+) the second character has to be
+quoted with a backslash.
+
+If the option may be given more than once, a star
+(`tt(*)') has to be added in front of the var(opt-spec).
+
+Finally, the var(opt-spec) may contain a explanation string. This is
+given in brackets at the end, as in `tt(-q[query operation])'. The
+tt(verbose) style is used to decide if these
+explanation strings should be printed when options are listed. If no
+explanation string is given but the tt(auto-describe) style is
+set and only one argument is described for this var(opt-spec), the
+option will be described by the value of the style with any appearance
+of the sequence `tt(%d)' in it replaced by the description for the
+first argument.
+)
+enditem()
+
+Every var(spec) may also contain a list of option names and argument
+numbers with which the option or argument described is mutually
+exclusive. Such a list is given in parentheses at the beginning, as in
+`tt((-two -three 1)-one:...)' or `tt((-foo):...)'. In the first
+example, the options `tt(-two)' and `tt(-three)' and the first
+argument will not be offered as possible completions if the option
+`tt(-one)' is on the line. Also, the list may contain a single star as
+one of its elements to specify that the description for the rest
+arguments should not be used and it may contain a colon to specify
+that the descriptions for all normal (non-option-) arguments should
+not be used.
+
+In each of the cases above, the var(action) says how the possible
+completions should be generated. In cases where only one of a fixed
+set of strings can be completed, these strings can directly be given as 
+a list in parentheses, as in `tt(:foo:(foo bar baz))'. Such a list in
+doubled parentheses, as in `tt(:foo:((a\:bar b\:baz)))' should contain 
+strings consisting of the string to complete followed by a colon
+(which needs to be preceded by a backslash) and a description. The
+matches will be listed together with their descriptions if the
+tt(description) style for the tt(values) tag is set.
+
+An var(action) of the form `tt(->)var(string)' is used by functions
+that implement a state machine. In this case, the `var(string)' (with
+all leading and trailing spaces and tabs removed) will be stored in
+the global parameter tt(state) and the function returns with a return
+value of 300 (to make it distinguishable from other return values)
+after setting the global `tt(context)', `tt(line)' and `tt(opt_args)'
+parameters as described below and without resetting any changes made
+to the special parameters such as tt(PREFIX) and tt(words). Note that
+this means that a function calling tt(_arguments) with at least one
+action containing such a `tt(->)var(string)' has to declare
+appropriate local parameters as in:
+
+example(local context state line
+typeset -A opt_args)
+
+This will ensure that tt(_arguments) does not create unused global
+parameters.
+
+A string in
+braces will be evaluated to generate the matches and if the
+var(action) does not begin with an opening parentheses or brace, it
+will be split into separate words and executed. If the var(action)
+starts with a space, this list of words will be invoked unchanged,
+otherwise it will be invoked with some extra strings placed after the
+first word which can be given as arguments to the tt(compadd) builtin
+command and which make sure that the var(message) given
+in the description will be shown above the matches. These arguments
+are taken from the array parameter tt(expl) which will be set up
+before executing the var(action) and hence may be used in it (normally 
+in an expansion like `tt($expl[@])').
+
+Except for the `tt(->)var(string)' form, the var(action) will be
+executed by calling the tt(_all_labels) function to process all tag labels,
+so one doesn't need to call that explicitly unless another tag is to
+be used, for example in a function called in the var(action).
+
+In places where no sensible matches can be generated, the action
+should consist of only a space. This will make the var(message) be
+displayed but no possible completions listed. Note that even in this
+case the colon at the end of the var(message) is needed. The only case 
+where it can be left is when neither a var(message), nor a var(action) 
+is given.
+
+To include a colon in the option name, the var(message) or the
+var(action), it has to be preceded by a backslash.
+
+During the evaluation or execution of the action the array `tt(line)'
+will be set to the command name and normal arguments from the command
+line, i.e. to the words from the command line excluding all options
+and their arguments. These are stored in the associative array
+`tt(opt_args)', using the option names as keys and their arguments as
+the values. For options that have more than one argument these are
+given as one string, separated by colons. All colons in the original
+arguments are preceded with backslashes. The parameter `tt(context)'
+will be set to the automatically created context name. This is either
+a string of the form `var(-opt)tt(-)var(n)' for the var(n)'th argument 
+of the option var(-opt), or a string of the form `tt(argument-)var(n)' 
+for the var(n)'th argument (for rest arguments the var(n) is the
+string `tt(rest)'). For example, when completing the argument of the tt(-o)
+option, the name is `tt(-o-1)' and for the second normal (non-option-)
+argument it is `tt(argument-2)'.
+
+Also, during the evaluation of the var(action), the context name in
+the tt(curcontext) parameter will be changed by appending the same
+string that is stored in the tt(context) parameter.
+
+Normally the option names are taken as multi-character names and a
+word from the line is considered to contain only one option (or
+none). By giving the tt(-s) option to this function (before the first
+description), options are considered to be one-character options and the
+strings from the line may contain more than one such option
+letter. However, strings beginning with two hyphens (like
+`tt(-)tt(-prefix)') are still considered to contain only one option
+name. This allows the use of the `tt(-s)' option to describe
+single-letter options together with such long option names.
+
+Another option supported is `tt(-O) var(name)'. The var(name) will be
+taken as the name of an array and its elements will be given to
+functions called to generate matches when executing the
+var(actions). For example, this allows one to give options for the
+tt(compadd) builtin that should be used for all var(action)s.
+
+Also, the tt(-M) option followed by a string may be given before the
+first description. The string will be used as the match specification
+when completing option names and values instead of the default
+`tt(r:|[_-]=* r:|=*)'. 
+
+Finally, the option tt(-C) can be given to make tt(_arguments) modify
+the tt(curcontext) parameter when a action of the form
+`tt(->)var(state)' is used. This parameter is used to keep track of
+the current context and in this case it (and not the parameter
+tt(context) as explained above) has to be made local to make sure that 
+calling functions don't use the modified value. Also, the local
+version of tt(curcontext) has to be initialised with the old value as
+in:
+
+example(local curcontext="$curcontext")
+
+The function can also be made to automatically complete long options
+for commands that support the `tt(-)tt(-help)' option as, for example,
+most of the GNU commands do. For this, the string `tt(-)tt(-)' must be
+given as one argument and if it is, the command from the line is
+invoked with the `tt(-)tt(-help)' option and its output is parsed to find
+possible option names. Note that this means that you should be careful
+to make sure that this feature is not used for a command that does not
+support this option.
+
+For such automatically found options that get an argument after a
+`tt(=)', the function also tries
+to automatically find out what should be completed as the argument.
+The possible completions for option-arguments can be described with
+the arguments after the `tt(-)tt(-)' (which are not used as described
+above). Each argument contains one description of the form
+`var(pattern)tt(:)var(message)tt(:)var(action)'. The var(message) and
+the var(action) have the same format as for the normal option
+descriptions described above. The var(action) will be executed to
+complete arguments of options whose description in the output of the
+command from the line with the `tt(-)tt(-help)' option matches the
+var(pattern). For example:
+
+example(_arguments -- '*\*:toggle:(yes no)' \ 
+              '*=FILE*:file:_files' \ 
+              '*=DIR*:directory:_files -/')
 
 Here, `tt(yes)' and `tt(no)' will be completed as the argument of
 options whose description ends in a star, file names for options that
@@ -683,9 +2888,374 @@ for option descriptions containing `tt(=FILE)' and paths for option
 descriptions that contain `tt(=DIR)' or `tt(=PATH)'. These builtin
 patterns can be overridden by patterns given as arguments, however.
 
-This function also accepts the `tt(-X)', `tt(-J)', and `tt(-V)'
-options which are passed unchanged to `tt(compadd)'. Finally, it
-accepts the option `tt(-t)'; if this is given, completion is only done
-on words starting with two hyphens.
+Note also that tt(_arguments) tries to find out automatically if the
+argument for an option is optional. If it fails to automatically
+detect this, the colon before the var(message) can be doubled to tell
+it about this as described for the normal option descriptions above.
+
+The option `tt(-i) var(patterns)' (which must be given after the
+`tt(-)tt(-)') can be used to give patterns for options which should not be
+completed. The patterns can be given as the name of an array parameter
+or as a literal list in parentheses. E.g. `tt(-i
+"LPAR()-)tt(-(en|dis)able-FEATURE*RPAR()")' will make the options
+`tt(-)tt(-enable-FEATURE)' and `tt(-)tt(-disable-FEATURE)' be ignored. The
+option `tt(-s) var(pairs)' (again, after the `tt(-)tt(-)') can be used to
+describe option aliases. Each var(pair) consists of a pattern and a
+replacement. E.g. some tt(configure)-scripts describe options only as
+`tt(-)tt(-enable-foo)', but also accept `tt(-)tt(-disable-foo)'. To allow
+completion of the second form, one would use `tt(-s "LPAR()#-)tt(-enable-
+-)tt(-disable-RPAR()")'.
+
+Example:
+
+example(_arguments '-l+:left border:' \ 
+           '-format:paper size:(letter A4)' \ 
+           '*-copy:output file:_files::resolution:(300 600)' \ 
+           ':postscript file:_files -g *.(ps|eps)' \ 
+           '*:page number:')
+
+This describes three options: `tt(-l)', `tt(-format)', and
+`tt(-copy)'. The first one gets one argument described as `var(left
+border)' for which no completion will be offered because of the empty
+action. The argument may come directly after the `tt(-l)' or it may be 
+given as the next word on the line. The `tt(-format)' option gets one
+argument (in the next word) described as `var(paper size)' for which
+only the strings `tt(letter)' and `tt(A4)' will be completed. The
+`tt(-copy)' option differs from the first two in that it may appear
+more than once on the command line and in that it accepts two
+arguments. The first one is mandatory and will be completed as a
+filename. The second one is optional (because of the second colon
+before the description `var(resolution)') and will be completed from
+the strings `tt(300)' and `tt(600)'.
+
+The last two descriptions say what should be completed as
+arguments. The first one describes the first argument as a
+`var(postscript file)' and makes files ending in `tt(ps)' or `tt(eps)' 
+be completed. The last description says that all other arguments are
+`var(page numbers)' but does not give possible completions.
+)
+findex(_values)
+item(tt(_values) var(specs) ...)(
+This is used to complete values (strings) and their arguments or
+lists of such values.
+
+If the first argument is the option `tt(-O) var(name)', this will be
+used in the same way as by the tt(_arguments) function. I.e. the
+elements of the var(name) array will be given to calls to tt(compadd)
+and when executing an action.
+
+Otherwise, if the first argument (or the first argument after the
+`tt(-O) var(name)' option if that is used) is the option `tt(-s)', the
+next argument is used as the character that separates multiple values.
+
+The first argument (after the options and separator character if they
+are given) is used as a string to print as a description before
+listing the values.
+
+All other arguments describe the possible values and their
+arguments in the same format used for the description of options by
+the tt(_arguments) function (see above). The only difference is that
+there is no required minus or plus sign at the beginning and that
+values can have only one argument.
+
+Example:
+
+example(_values -s , 'description' \ 
+        '*foo[bar]' \ 
+        '(two)*one[number]:first count:' \ 
+        'two[another number]::second count:(1 2 3)')
+
+This describes three possible values: `tt(foo)', `tt(one)', and
+`tt(two)'. The first one is described as `tt(bar)', gets no argument 
+and may appear more than once. The second one is described as
+`tt(number)', may appear more than once, and gets one mandatory
+argument described as `tt(first count)' for which no action is
+specified so that it will not be completed automatically. The
+`tt((two))' at the beginning says that if the value `tt(one)' is on
+the line, the value `tt(two)' will not be  considered to be a possible
+completion anymore. Finally, the last value (`tt(two)') is described
+as `tt(another number)' and gets an optional argument decribed as
+`tt(second count)' which will be completed from the strings `tt(1)',
+`tt(2)', and `tt(3)'. The tt(_values) function will complete lists of
+these values separated by commas.
+
+Like tt(_arguments) this function temporarily adds another context
+name component to the current context name while executing the
+var(action). Here this name is just the name of the value for which
+the argument is completed.
+
+To decide if the descriptions for the values (not those for the
+arguments) should be printed, the tt(verbose) is used.
+
+One last difference to tt(_arguments) is that this function uses the
+associative array
+tt(val_args) to report values and their arguments (but otherwise this
+is the same as the tt(opt_args) association used by
+tt(_arguments)). This also means that the function calling tt(_values) 
+should declare the tt(state), tt(line), tt(context) and tt(val_args)
+parameters as in:
+
+example(local context state line
+typeset -A val_args)
+
+when using an action of the form `tt(->)var(string)'. With this
+function the tt(context) parameter will be set to the name of the
+value whose argument is to be completed.
+
+Like tt(_arguments), tt(_values) also supports the tt(-C) option in
+which case you have to make the parameter tt(curcontext) local instead 
+of tt(context) (as described above).
+)
+findex(_regex_arguments)
+item(tt(_regex_arguments) var(name) var(specs) ...)(
+This function is a compiler to generate a completion function.  The
+first argument specifies the name of a generated function while the
+remaining arguments specify a completion as a set of regular
+expressions with actions.  The generated function has the structure of a
+finite-state machine whose state corresponds to the state (i.e. the
+context) of the completion. This state machine uses a command line,
+which comes from concatentating the tt(words) array up to the current
+cursor position using null characters as a separator with no extra
+quotation.  This is analysed and at the end the appropriate action is
+executed.
+
+Specification arguments take one of following forms, in which
+metacharacters such as `tt(LPAR())', `tt(RPAR())', `tt(#)' and `tt(|)'
+should be quoted.
+
+startitem()
+item(tt(/)var(pattern)tt(/) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(action)])(
+This is a primitive element, corresponding to one
+state of the compiled state machine.  The state is entered if the pattern
+`tt((#b)LPAR()(#B))var(pattern)tt(RPAR()(#B))var(lookahead)tt(*)' matches
+the command line string.  If it is matched, `var(guard)' is evaluated and
+its return status is examined; if this is successful, the state is entered,
+else the test fails and other candidates are tried.  The var(pattern)
+string `tt([])' is guaranteed never to match.
+
+If the test succeeds and the state is entered, the left part of the
+command line string matched as `var(pattern)' is removed and the 
+next state is tried, proceeding from inside to outside and from left to
+right.
+
+If no test succeeds and the remaining command line string contains no null
+character, the completion target is restricted to the remainder of the
+command line string and `var(action)'s for the target are evaluated.
+In this case, nothing is actually removed from the command line string
+so that any previous or neighbouring state may also have `var(actions)'s.
+)
+item(tt(/)var(pattern)tt(/+) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(action)])(
+This is similar to `tt(/)var(pattern)tt(/) ...' but the left part of
+command line string is also considered as part of the completion target.
+)
+item(tt(/)var(pattern)tt(/-) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(action)])(
+This is similar to `tt(/)var(pattern)tt(/) ...' but `var(action)'s of the
+current and previous states are ignored even if the following state's
+`var(pattern)' matches the empty string.
+)
+item(tt(LPAR()) var(spec) tt(RPAR()))(
+This groups `var(spec)'.
+)
+item(var(spec) tt(#))(
+This allows any number of repetitions of `var(spec)'.
+)
+item(var(spec) var(spec))(
+This represents the concatenation of two `var(spec)'s.
+)
+item(var(spec) tt(|) var(spec))(
+Either of two `var(spec)'s can be matched.
+)
+enditem()
+)
+findex(_combination)
+item(tt(_combination) [ tt(-s) var(pattern) ] var(tag) var(style) var(specs) ... var(field) var(opts) ...)(
+This function is used to complete combinations of values such as pairs 
+of hostnames and usernames. The possible values will be taken from the 
+var(style) whose name is given as the second argument. The first argument
+is the var(tag) to use to do the lookup.
+
+The style name should consist of multiple parts separated by
+hyphens which are then used as fieldnames. Known values for such
+fields can be given after the second argument in arguments of the form 
+`var(field)tt(=)var(pattern)'. The first argument without a equal sign 
+is taken as the name of the field for which completions should be
+generated.
+
+The matches generated will be taken from the value of the style. These 
+values should contain the possible values for the combinations where
+the values for the different fields are separated by colons or
+characters matching the pattern given after the tt(-s) option to
+tt(_combination) (normally this is used to define character classes
+like the `tt(-s "[:@]")' used for the tt(users-hosts) style).
+
+Only the values for the requested fields for which the patterns given
+in the `var(field)tt(=)var(pattern)' match the respective fields in
+the strings from the style value are generated as possible matches.
+
+If no style with the given name is defined for the given tag but a
+function named with the name of the requested field preceded by an
+underscore is defined, that function will be called to generate the
+matches. This is also done if none of the strings in the value of the
+style match all the patterns given as arguments.
+
+If the same name is used for more than one field, in both the
+`var(field)tt(=)var(pattern)' and the argument that gives the field
+name to complete for, the number of the field (starting with one) may
+be given after the fieldname, separated from it by a colon.
+
+All arguments after the requested fieldname are given to the
+tt(compadd) used (when generating matches from the style value) and to 
+the functions for the fields if they are called.
+)
+findex(_sort_tags)
+item(tt(_sort_tags) var(tag) ...)(
+As described above for the tt(tag-order) style, this is only provided
+to show how functions that sort tags can be implemented.
+
+Inside such functions the name of the current context can
+be accessed using the tt(curcontext) parameter. For example, the
+function generating file names (called tt(_files)) in the completion
+system is often called to generate only filenames matching a given
+glob pattern, in which case it uses the tags tt(globbed-files),
+tt(directories), and tt(all-files).  This means that the function
+offers to generate filenames matching the pattern, names of
+directories or all filenames as possible matches. Example:
+
+example(_sort_tags() {
+  case $curcontext in
+  (*::dvips:*)
+    comptry globbed-files directories
+    comptry all-files
+    ;;
+  (*)
+    comptry globbed-files
+    comptry directories
+    comptry all-files
+    ;;
+  esac
+})
+
+Every call to the tt(comptry) function (actually a builtin
+command defined by the tt(zsh/computil) module) gives a
+set of tags to use; as soon as one of the completion system produces
+some matches for one set,
+subsequent sets have no effect.  Hence in the example
+this means that for the tt(dvips) command on the first attempt the
+names of DVI files and directories will be generated (first call to
+tt(comptry)). If none of those names match the string from the command
+line the completion function will generate all filenames as
+possible matches (second call to tt(comptry)).
+
+For all other context names the second case-pattern matches, so that
+normally the completion functions will only try the filenames matching 
+the glob pattern (if any glob pattern is used). If that doesn't yield
+any matches, names of directories are generated, and if that doesn't
+yield any matching names either, all filenames will be generated.
+
+In every context the function may call tt(comptry) as
+often as it wants. Also, every string may be given as argument, even
+if no tag with such a name was offered by the completion
+function. This allows one to give a preferred ordering for some common 
+tag sets without having to worry about sensible patterns for context
+names. For example, many completion functions can generate both
+arguments and option names for commands. These functions normally use
+the tags tt(arguments) and tt(options). Depending on your preference
+you may write in your sorting function:
+
+example(_sort_tags() {
+  comptry arguments options
+  case $curcontext in
+  ...
+  esac
+})
+
+or
+
+example(_sort_tags() {
+  comptry arguments
+  comptry options
+  case $curcontext in
+  ...
+  esac
+})
+
+The former always adds both the matches for the argument and the
+option names as possible matches. The latter forces matches for the
+arguments to be preferred. In this case option names are only generated
+as matches if the string on the line matches no possible completion
+for the argument, which normally means that you have to type the
+hyphen the option names start with yourself to see the list of option
+names that can be completed.
+
+Since the completion functions are free to choose the tag names they
+use, there can't be a complete list. So to make sure that all types of 
+matches are eventually tried as completions, one should  use a call to 
+tt(comptry) with all arguments at the end of the sorting function. For
+those contexts where one really wants to make sure that certain tags are
+never used one can then use a call to tt(return) to circumvent that
+last tt(comptry). For example:
+
+example(_sort_tags() {
+  ...
+  case $curcontext in
+  (*::kill:*)
+    comptry processes
+    return
+    ;;
+  esac
+  comptry "$@"
+})
+
+The completion function for the tt(kill) builtin command offers the
+tags tt(jobs) and tt(processes) which represent job references
+(e.g. `tt(%1)') and process identifiers respectively. The function
+above makes sure that for this builtin command only process
+identifiers are generated as possible matches by using only the
+tt(processes) tag in a call to tt(comptry). The immediate call to
+tt(return) then makes sure that the default tt(comptry) at the end is
+not executed.
+
+With the tt(-s) option, each tag given to tt(comptry) will be put in a 
+separate set. With the tt(-m) option, the arguments are treated in the 
+same way as the the values for the tt(tag-order) style (except for the 
+`tt(!...)', `tt(-)' and `tt(foo())' forms).
+)
+
+enditem()
+
+texinode(Completion Directories)()(Completion Functions)(Completion System)
+sect(Completion Directories)
+cindex(completion system, directory structure)
+
+In the source distribution, the files are contained in various
+subdirectories of the tt(Completion) directory.  They may have been
+installed in the same structure, or into one single function directory.
+The following is a description of the files found in the original directory
+structure.  If you wish to alter an installed file, you will need to copy
+it to some directory which appears earlier in your tt(fpath) than the
+standard directory where it appears.
+
+startitem()
+item(tt(Core))(
+The core scripts and functions.  You will certainly need these, though will
+probably not need to alter them.  Many of these are documented above.
+)
+item(tt(Base))(
+Other functions you will almost certainly want if you are going to use
+any of the standard completion functions.  You may want to edit some of
+these files.
+)
+item(tt(Builtins))(
+Functions for completing arguments of shell builtin commands and
+utility functions for this (which are also used by functions from the
+tt(User) directory).
+)
+item(tt(User))(
+Functions for completing arguments of external commands and suites of
+commands.  They may need modifying for your system.
+)
+item(tt(Commands))(
+Functions which implement special types of completion to be bound to
+keystrokes rather than called by context.
 )
 enditem()
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 2cb12e2c2..775ead546 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -1,304 +1,595 @@
-texinode(Completion Widgets)(Zsh Modules)(Programmable Completion)(Top)
+texinode(Completion Widgets)(Completion System)(Completion Using compctl)(Top)
 chapter(Completion Widgets)
 cindex(completion, widgets)
 cindex(completion, programmable)
 cindex(completion, controlling)
 sect(Description)
-Completion widgets are defined using the tt(-C) option to the tt(zle)
-builtin command provided by the tt(zle) module (see
+Completion widgets are defined by the tt(-C) option to the tt(zle)
+builtin command provided by the tt(zsh/zle) module (see
 ifzman(zmanref(zshzle))\
-ifnzman(noderef(The zle Module))\
-). For example, the invocation:
+ifnzman(noderef(The zsh/zle Module))\
+). For example,
 
-indent(nofill(
-tt(zle -C complete expand-or-complete completer)))
+example(zle -C complete expand-or-complete completer)
 
-defines a widget named tt(complete). If this widget is bound to a key
-using the tt(bindkey) builtin command defined in the tt(zle) module
+defines a widget named tt(complete). When this widget is bound to a key
+using the tt(bindkey) builtin command defined in the tt(zsh/zle) module
 (see 
 ifzman(zmanref(zshzle))\
 ifnzman(noderef(Zsh Line Editor))\
-) typing that key will make the completion code call the shell
-function tt(completer). This function is responsible for generating
-the possible matches using the builtins described below. Once the
-function returns, the completion code takes over control again and
-treats the matches the way the builtin widget tt(expand-or-complete)
-would do it. For this second argument, the name of any of the builtin
-widgets that handle completions can be given, i.e. it may be any of
+), typing that key will call the shell function tt(completer). This
+function is responsible for generating the possible matches using the
+builtins described below. Once the function returns, the completion code
+takes over control again and treats the matches as the builtin widget
+tt(expand-or-complete) would do.  For this second argument, the name of any
+of the builtin widgets that handle completions can be given:
 tt(complete-word), tt(expand-or-complete),
 tt(expand-or-complete-prefix), tt(menu-complete),
 tt(menu-expand-or-complete), tt(reverse-menu-complete),
-tt(list-choices), or tt(delete-char-or-list).
+tt(list-choices), or tt(delete-char-or-list).  Note that this will still
+work even if the widget in question has been rebound.
 
 startmenu()
 menu(Special Parameters)
 menu(Builtin Commands)
 menu(Condition Codes)
+menu(Matching Control)
 menu(Examples)
 endmenu()
 
 texinode(Special Parameters)(Builtin Commands)()(Completion Widgets)
 sect(Special Parameters)
 
-Inside completion widgets some parameters have special meaning. They
-will be used inside the widget function and other shell functions
-called from it. Outside of these function they are not special to the
-shell in any way.
-
-The parameters are used to give information about the internal state
-from the completion code to the completion widget and can be set to
-give information to the completion code from the completion
-widget. Some of the builtin commands and the condition codes use or
-change the current values of these parameters. While the completion
-widget is active, these parameters are reseton each function exit to
-the values they had when the function was entered.
+Inside completion widgets, and any functions called from those, some
+parameters have special meaning; outside these function they are not
+special to the shell in any way.  These parameters are used to pass
+information between the completion code and the completion widget. Some of
+the builtin commands and the condition codes use or change the current
+values of these parameters.  Any existing values will be hidden during
+execution of completion widgets; except for tt(compstate), the parameters
+are reset on each function exit (including nested function calls from
+within the completion widget) to the values they had when the function was
+entered.
 
 startitem()
-item(tt(argv))(
-The positional parameters are set to the arguments on the command line
-when the widget function is invoked from the completion code.
+vindex(words)
+item(tt(words))(
+This array contains the words present on the command line currently being
+edited.
 )
+vindex(CURRENT)
 item(tt(CURRENT))(
 This is the number of the current word, i.e. the word the cursor is
-currently on in the tt(argv) array.
+currently on in the tt(words) array.  Note that this value is only
+correct if the tt(ksharrays) options is not set.
+)
+vindex(PREFIX)
+item(tt(PREFIX))(
+Initially this will be set to the part of the current word from the
+beginning of the word up to the position of the cursor; it may be altered
+to give a common prefix for all matches.
 )
-item(tt(CONTEXT))(
+vindex(IPREFIX)
+item(tt(IPREFIX))(
+Initially this will be set to the empty string.  It functions like
+tt(PREFIX), and gives a string which precedes the one in tt(PREFIX) and is
+not considered part of the list of matches.  Typically, a string is
+transferred from the beginning of tt(PREFIX) to the end of tt(IPREFIX), for
+example:
+
+example(IPREFIX=${PREFIX%%\=*}=
+PREFIX=${PREFIX#*=})
+
+causes the part of the prefix up to and including the first equal sign not
+to be treated as part of a matched string.  This can be done automatically
+by the tt(compset) builtin, see below.
+)
+vindex(QIPREFIX)
+item(tt(QIPREFIX))(
+This parameter is read-only and contains the quoted string up to the
+word being completed. E.g. when completing `tt("foo)', this parameter
+contains the double quote. If the tt(-q) option of tt(compset) is used 
+(see below), and the original string was `tt("foo bar)' with the
+cursor on the `tt(bar)', this parameter contains `tt("foo )'.
+)
+vindex(SUFFIX)
+item(tt(SUFFIX))(
+Initially this will be set to the part of the current word from the
+cursor position to the end; it may be altered to give a common suffix for
+all matches.  It is most useful when the option tt(COMPLETE_IN_WORD) is
+set, as otherwise the whole word on the command line is treated as a
+prefix.
+)
+vindex(ISUFFIX)
+item(tt(ISUFFIX))(
+As tt(IPREFIX), but for a suffix that should not be considered part
+of the matches; note that the tt(ISUFFIX) string follows the tt(SUFFIX)
+string.
+)
+vindex(QISUFFIX)
+item(tt(QISUFFIX))(
+Like tt(QIPREFIX), but containing the suffix.
+)
+vindex(compstate)
+cindex(completion widgets, examining and setting state in)
+item(tt(compstate))(
+This is an associative array with various keys and values that the
+completion code uses to exchange information with the completion widget.
+The keys are:
+
+startitem()
+vindex(context, compstate)
+item(tt(context))(
 This will be set by the completion code to the overall context
-completion is attempted in. Possible values are:
+in which completion is attempted. Possible values are:
 
 startitem()
 item(tt(command))(
-when completing in a command position, e.g. in the first word on the
-command line
-)
-item(tt(argument))(
-when completing an argument for a command
+when completing for a normal command (either in a command position or for
+an argument of the command).
 )
 item(tt(redirect))(
-when completing after a redirection operator; in this case the
-positional parameters contain not only the arguments but also the
-command name itself as the first element
+when completing after a redirection operator.
 )
 item(tt(condition))(
-when completing inside a `tt([[)...tt(]])' conditional expressing; in
-this case the positional parameters are set to the words inside the
-conditional expressions
+when completing inside a `tt([[)...tt(]])' conditional expression; in
+this case the tt(words) array contains the words inside the
+conditional expression.
 )
 item(tt(math))(
 when completing in a mathematical environment such as a
-`tt(LPAR()LPAR())...tt(RPAR()RPAR())' construct
+`tt(LPAR()LPAR())...tt(RPAR()RPAR())' construct.
 )
 item(tt(value))(
-when completing the value of a parameter assignment; in case of an
-array value the positional parameters are set to the words in
-parentheses
+when completing the value of a parameter assignment.
+)
+item(tt(array_value))(
+when completing inside the value of an array parameter assignment; in
+this case the tt(words) array contains the words inside the parentheses.
 )
 item(tt(subscript))(
-when completing inside a parameter expansion subscript
+when completing inside a parameter subscript.
 )
-enditem()
+item(tt(parameter))(
+when completing the name of a parameter in a parameter expansion beginning
+with tt($) but not tt(${).
 )
-item(tt(COMMAND))(
-In most cases this is set to name of the command for which completion
-is tried. When completing after a redirection operator it contains the 
-string forming that operator. Also, when completing in the value of a
-parameter assignment or in a parameter subscript it is set to the name
-of the parameter.
+item(tt(brace_parameter))(
+when completing the name of a parameter in a parameter expansion beginning
+with tt(${).
 )
-item(tt(PREFIX))(
-This should be set to that part of the current word that should be
-taken as the string every possible match has to begin with. Initially
-this will be set to the part of the current word from the beginning of
-the word up to the position of the cursor. When 
+enditem()
 )
-item(tt(IPREFIX))(
-When a part of the current word should not be considered part of the
-matches, this part should be taken from the tt(PREFIX) parameter and
-appended to this parameter. This will initially be set to the empty
-string when called from the completion code.
+vindex(vared, compstate)
+item(tt(vared))(
+If completion is called while editing a line using the tt(vared)
+builtin, the value of this key is set to the name of the parameter
+given as argument to tt(vared). If tt(vared) is not currently used,
+this key is unset.
 )
-item(tt(SUFFIX))(
-This should be set to that part of the current word that should be
-taken as the string every possible match has to end with. The
-completion code sets this to the part of the current word from the
-cursor position to the end.
+vindex(parameter, compstate)
+item(tt(parameter))(
+The name of the parameter when completing in a subscript or in the
+value of a parameter assignment.
 )
-item(tt(NMATCHES))(
-This is always set to the number of matches generated and accepted by
-the completion code so far.
+vindex(redirect, compstate)
+item(tt(redirect))(
+The redirection operator when completing in a redirection position,
+i.e. one of tt(<), tt(>), etc.
+)
+vindex(quoting, compstate)
+item(tt(quoting))(
+When completing inside single quotes, this is set to the string
+tt(single); inside double quotes, the string
+tt(double); inside backticks, the string tt(backtick).
+Otherwise it is unset.
+)
+vindex(quote, compstate)
+item(tt(quote))(
+When completing inside quotes, this contains the quotation character
+(i.e. either a single quote, a double quote, or a backtick).  Otherwise it
+is unset.
+)
+vindex(all_quotes, compstate)
+item(tt(all_quotes))(
+The tt(-q) option of the tt(compset) builtin command (see below)
+allows breaking a quoted string into separate words and completing one 
+of these words. This key allows to test which types of quoted strings
+are currently broken into parts this way. Its value contains one
+character for each quoting level. The characters are a single quote or 
+a double quote for strings quoted with these characters and a
+backslash for strings not starting with a quote character. The first
+character in the value always corresponds to the innermost quoting
+level.
+)
+vindex(nmatches, compstate)
+item(tt(nmatches))(
+The number of matches generated and accepted by the completion code so
+far.
+)
+vindex(ignored, compstate)
+item(tt(ignored))(
+The number of words that were ignored because they matched one of the
+patterns given with the tt(-F) option to the tt(compadd) builtin
+command.
 )
-item(tt(MATCHER))(
-When completion is used with a global match specification (i.e. a
-tt(compctl) with only a tt(-M) option), this parameter is set to the
-number of the specification string which is currently used.
+vindex(restore, compstate)
+item(tt(restore))(
+This is set to tt(auto) before a function is entered, which forces the
+special parameters mentioned above (tt(words), tt(CURRENT), tt(PREFIX),
+tt(IPREFIX), tt(SUFFIX), and tt(ISUFFIX)) to be restored to their
+previous values when the function exits.   If a function unsets it or
+sets it to any other string, they will not be restored.
+)
+vindex(list, compstate)
+item(tt(list))(
+This controls whether or how the list of matches will be displayed.  If it
+is unset or empty they will never be listed; if its value begins with
+tt(list), they will always be listed; if it begins with tt(autolist)
+or tt(ambiguous), they will be listed when the tt(AUTO_LIST) or
+tt(LIST_AMBIGUOUS) options respectively would normally cause them to
+be.
+
+If the substring tt(force) appears in the value, this makes the
+list be shown even if there is only one match. Normally, the list
+would be shown only if there are at least two matches.
+
+The value contains the substring tt(packed) if the tt(LIST_PACKED)
+option is set. If this substring is given for all matches added of a
+group, this group will show the tt(LIST_PACKED) behavior. The same is
+done for the tt(LIST_ROWS_FIRST) option with the substring tt(rows).
+
+Finally, if the value contains the string tt(explanations), only the
+explanation strings, if any, will be listed. It will be set
+appropriately on entry to a completion widget and may be changed
+there.
+)
+vindex(list_max, compstate)
+item(tt(list_max))(
+Initially this is set to the value of the tt(LISTMAX) parameter.
+It may be set to any other numeric value; when the widget exits this value
+will be used in the same way as the value of tt(LISTMAX).
+)
+vindex(list_lines, compstate)
+item(tt(list_lines))(
+This gives the number of lines that are needed to display the full
+list of completions. Note that to calculate the total number of lines
+to display you need to add the number of lines needed for the command
+line to this value, this is available as the value of the tt(BLINES)
+special parameter.
+)
+vindex(last_prompt, compstate)
+item(tt(last_prompt))(
+If this is set to an non-empty string for every match added, the
+completion code will move the cursor back to the previous prompt after
+the list of completions has been displayed.  Initially this is set or
+unset according to the tt(ALWAYS_LAST_PROMPT) option.
+)
+vindex(insert, compstate)
+item(tt(insert))(
+This controls the manner in which a match is inserted into the command
+line.  On entry to the widget function, if it is unset the command line is
+not to be changed; if set to tt(unambiguous), any prefix common to all
+matches is to be inserted; if set to tt(automenu-unambiguous), the
+common prefix is to be inserted and the next invocation of the
+completion code may start menu-completion (due to the tt(AUTO_MENU)
+option being set); if set to tt(menu) or tt(automenu) menu-completion
+will be started for the matches currently generated due to (in the
+latter case this will happen because the tt(AUTO_MENU) is set).
+
+On exit it may be set to any of the values above (where setting it to
+the empty string is the same as unsetting it), or to a number, in which
+case the match whose number is given will be inserted into the command line.
+It may also be set to a string of the form `var(group):var(match)' which
+specifies a match from a group of matches to be inserted, counting from 1
+upwards (e.g. `tt(2:4)' specifies the fourth match of the second group).
+Negative numbers count backward from the last match or group (with `tt(-1)'
+selecting the last match or group) and out-of-range values are wrapped
+around, so that a value of zero selects the last match or group and a value
+one more than the maximum selects the first. Unless the value of this
+key ends in a space, the match is inserted as in a menu-completion,
+i.e. without automatically appending a space.
+
+It may also be set to tt(all), which makes all matches generated be
+inserted into the line.
+)
+vindex(to_end, compstate)
+item(tt(to_end))(
+Specifies the occasions on which the cursor is moved to the end of a string
+when a match is inserted.  On entry to a widget function, it may be
+tt(single) if this will happen when a single unambiguous match was inserted
+or tt(match) if it will happen any time a match is inserted (for example,
+by menucompletion; this is likely to be the effect of the tt(ALWAYS_TO_END)
+option).
+
+On exit, it may be set to tt(single) as above.  It may also be set to
+tt(always), or to the empty string or unset; in those cases the cursor will
+be moved to the end of the string always or never respectively.  Any
+other string is treated as tt(match).
+)
+vindex(old_list, compstate)
+item(tt(old_list))(
+This is set to tt(yes) if there is still a valid list of completions
+from a previous completion at the time the widget is invoked.  This will
+usually be the case if and only if the previous editing operation was a
+completion widget or one of the builtin completion functions.  If there is a
+valid list and it is also currently shown on the screen, the value of this
+key is tt(shown).
+
+After the widget has exited the value of this key is only used if it
+was set to tt(keep).  In this case the completion code will continue
+to use this old list.  If the widget generated new matches, they will
+not be used.
+)
+vindex(old_insert, compstate)
+item(tt(old_insert))(
+On entry to the widget this will be set to the number of the match of
+an old list of completions that is currently inserted into the command
+line. If no match has been inserted, this is unset.
+
+As with tt(old_list), the value of this key will only be used if it is the
+string tt(keep). If it was set to this value by the widget and there was an
+old match inserted into the command line, this match will be kept and if
+the value of the tt(insert) key specifies that another match should be
+inserted, this will be inserted after the old one.
+)
+vindex(exact, compstate)
+item(tt(exact))(
+Controls the behaviour when the tt(REC_EXACT) option is set.  It will be
+set to tt(accept) if an exact match would be accepted, and will be unset
+otherwise.
+)
+vindex(exact_string, compstate)
+item(tt(exact_string))(
+The string of an exact match if one was found, otherwise unset.
+)
+vindex(pattern_match, compstate)
+item(tt(pattern_match))(
+Locally controls the behaviour given by the tt(GLOB_COMPLETE) option.
+Initially it is set to `tt(*)' if and only if the option is set.
+The completion widget may set it to either of these two values, or to any
+other non-empty string.  If it is non-empty, unquoted metacharacters on the
+command line will be treated as patterns; if it is `tt(*)', then
+additionally a wildcard `tt(*)' is assumed at the cursor position; if
+it is empty or unset, metacharacters will be treated literally.
+
+Note that the matcher specifications given globally or to one of the
+builtin commands adding matches are not used if this is set to a
+non-empty string.
+)
+vindex(pattern_insert, compstate)
+item(tt(pattern_insert))(
+Normally this is set to tt(menu), which specifies that menu-completion will
+be used whenever the matches were generated using pattern matching. If it
+is set to any other non-empty string by the user and menu-completion is
+not selected by other option settings, the code will insert an
+unambiguous string for the generated matches as with normal completion.
+)
+vindex(unambiguous, compstate)
+item(tt(unambiguous))(
+This key is read-only and will always be set to the unambiguous string
+the completion code has generated for all matches added so far.
+)
+vindex(unambiguous_cursor, compstate)
+item(tt(unambiguous_cursor))(
+This gives the position the cursor would be placed at if the
+unambiguous string in the tt(unambiguous) key were inserted, relative to
+the value of that key. The cursor would be placed before the character
+whose index is given by this key.
+)
+enditem()
 )
 enditem()
 
 texinode(Builtin Commands)(Condition Codes)(Special Parameters)(Completion Widgets)
 sect(Builtin Commands)
 startitem()
-findex(complist)
-item(tt(complist) var(flags ...))(
-
-Generate matches according to the given var(flags) which can be any of 
-the option flags supported by the tt(compctl) builtin command (see
-ifzman(zmanref(zshcompctl))\
-ifnzman(noderef(Programmable Completion))\
-) except for the tt(-t) and tt(-l) flags. Also, when using the tt(-K)
-flag, the function given as argument to it can not access the command
-line with the tt(read) builtin command.
-
-The matches will be generated in the same way as if the completion code
-generated them directly from a tt(compctl)-definition with the same
-flags. The completion code will consider only those matches as
-possible completions that match the prefix and suffix from the special 
-parameters desribed above. These strings will be compared with the
-generated matches using the normal matching rules and any matching
-specifications given with the tt(-M) flag to tt(complist) and the
-global matching specifications given to the tt(compctl) builtin
-command.
-)
-xitem(tt(compadd) [ tt(-qQfnUam) ] [ tt(-F) var(array) ])
+findex(compadd)
+cindex(completion widgets, adding specified matches)
+xitem(tt(compadd) [ tt(-qQfenUal12) ] [ tt(-F) var(array) ])
 xitem([ tt(-P) var(prefix) ] [ tt(-S) var(suffix) ])
 xitem([ tt(-p) var(hidden-prefix) ] [ tt(-s) var(hidden-suffix) ])
-xitem([ tt(-i) var(ignored-prefix) ] [ tt(-W) var(file-prefix) ])
-xitem([ tt(-J) var(name) ] [ tt(-V) var(name) ])
+xitem([ tt(-i) var(ignored-prefix) ] [ tt(-I) var(ignored-suffix) ])
+xitem([ tt(-W) var(file-prefix) ] [ tt(-d) var(array) ])
+xitem([ tt(-J) var(name) ] [ tt(-V) var(name) ] [ tt(-X) var(explanation) ])
 xitem([ tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ])
-item([ tt(-M) var(match-spec) ] [ tt(--) ] [ var(words) ... ])(
+xitem([ tt(-M) var(match-spec) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ])
+item([ tt(-D) var(array) ] [ tt(--) ] [ var(words) ... ])(
 
-This builtin command can be used to add matches and directly control
+This builtin command can be used to add matches directly and control
 all the information the completion code stores with each possible
-match.
+match. The return value is zero if at least one match was added and
+non-zero if no matches were added.
+
+The completion code breaks the string to complete into seven fields in
+the order: 
+
+indent(var(<ipre><apre><hpre><word><hsuf><asuf><isuf>))
+
+The first field
+is an ignored prefix taken from the command line, the contents of the
+tt(IPREFIX) parameter plus the string given with the tt(-i)
+option. With the tt(-U) option, only the string from the tt(-i)
+option is used. The field var(<apre>) is an optional prefix string
+given with the tt(-P) option.  The var(<hpre>) field is a string
+that is considered part of the match but that should not be shown when 
+listing completions, given with the tt(-p) option; for example,
+functions that do filename generation might specify
+a common path prefix this way. var(<word>) is the part of the match that
+should appear in the list of completions, one of the tt(words) given at the
+end. The suffixes var(<hsuf>), var(<asuf>) and var(<isuf>) correspond to
+the prefixes var(<hpre>), var(<apre>) and var(<ipre>) and are given by the
+options tt(-s), tt(-S) and tt(-I), respectively.
 
 The supported flags are:
 
 startitem()
 item(tt(-P) var(prefix))(
-The same as for tt(compctl) and tt(complist), it gives a string that
-should be inserted before the given words when they are completed. The
-string given is not considered to be part of the match.
+This gives a string to be inserted before the given var(words).  The
+string given is not considered as part of the match and any shell
+metacharacters in it will not be quoted when the string is inserted.
 )
 item(tt(-S) var(suffix))(
-Like tt(-P) but gives a string that has to be inserted after the match.
+Like tt(-P) but gives a string to be inserted after the match.
 )
 item(tt(-p) var(hidden-prefix))(
-This gives a string that should be 
-...
+This gives a string that should be inserted into the command line before the
+match but that should not appear in the list of matches. Unless the
+tt(-U) option is given, this string must be matched as part of the string
+on the command line.
 )
 item(tt(-s) var(hidden-suffix))(
-...
+Like `tt(-p)', but gives a string to insert after the match.
 )
 item(tt(-i) var(ignored-prefix))(
-...
+This gives a string to insert into the command line just before any
+string given with the `tt(-P)' option.  Without `tt(-P)' the string is
+inserted before the string given with `tt(-p)' or directly before the
+match.
+)
+item(tt(-I) var(ignored-suffix))(
+Like tt(-i), but gives an ignored suffix.
+)
+item(tt(-d) var(array))(
+This adds per-match display strings. The var(array) should contain one 
+element per var(word) given. The completion code will then display the 
+first element instead of the first var(word), and so on. The
+var(array) may be given as the name of a array parameter or directly
+as a space-separated list of words in parentheses.
+
+If there are fewer display strings than var(words), the leftover
+var(words) will be displayed unchanged and if there are more display
+strings than var(words), the leftover display strings will be silently
+ignored.
+)
+item(tt(-l))(
+This option only has an effect if used together with the tt(-d)
+option. If it is given, the display strings are listed one per line,
+not arrayed in columns.
 )
 item(tt(-J) var(name))(
-As for tt(compctl) and tt(complist) this gives the name of the group
-of matches the words should be stored in.
+Gives the name of the group of matches the words should be stored in.
 )
 item(tt(-V) var(name))(
-Like tt(-J) but naming a unsorted group.
+Like tt(-J) but naming a unsorted group. These are in a different name 
+space than groups created with the tt(-J) flag.
+)
+item(tt(-1))(
+If given together with the tt(-V) option, makes
+only consecutive duplicates in the group be removed. If combined with
+the tt(-J) option, this has no visible effect. Note that groups
+with and without this flag are in different name spaces.
+)
+item(tt(-2))(
+If given together with the tt(-J) or tt(-V) option, makes all
+duplicates be kept. Again, groups with and without this flag are in
+different name spaces.
+)
+item(tt(-X) var(explanation))(
+The var(explanation) string will be printed with the list of matches.
 )
 item(tt(-q))(
-This flag has the same meaning as for tt(compctl) and tt(complist),
-too. It makes the suffix given with tt(-S) be automatically removed if 
-the next character typed is a blank or does not insert anything or if
+The suffix given with tt(-S) will be automatically removed if 
+the next character typed is a blank or does not insert anything, or if
 the suffix consists of only one character and the next character typed 
 is the same character.
 )
 item(tt(-r) var(remove-chars))(
-This makes the suffix given with tt(-S) be automatically removed if
+This is a more versatile form of the tt(-q) option.
+The suffix given with tt(-S) or the slash automatically added after
+completing directories will be automatically removed if
 the next character typed inserts one of the characters given in the
-var(remove-chars). This string is parsed as a characters class with
-the usual backslash-sequences understood, e.g. using `tt(-r "a-z\t")'
-removes the suffix if the next character typed inserts one of the
-lower case letters or a TAB, and `tt(-r "^0-9")' removes the suffix if 
-the next character typed inserts anything but a digit. One extra
+var(remove-chars).  This string is parsed as a characters class and
+understands the backslash sequences used by the tt(print) command.  For
+example, `tt(-r "a-z\t")' removes the suffix if the next character typed
+inserts a lowercase character or a TAB, and `tt(-r "^0-9")' removes the
+suffix if the next character typed inserts anything but a digit. One extra
 backslash sequence is understood in this string: `tt(\-)' stands for
 all characters that insert nothing. Thus `tt(-S "=" -q)' is the same
 as `tt(-S "=" -r "= \t\n\-")'.
 )
 item(tt(-R) var(remove-func))(
-For the cases where one wants to remove suffix and the tt(-r) option
-does not give enough control, this option can be used. It stores the
-name of the shell function var(remove-func) in the matches. If one of
-the matches is finally accepted and the tt(-S)-suffix inserted, this
-function will be called after the next character typed. It gets the
-length of the suffix as its argument and can use the special
-parameters available in zle widgets (see
+This is another form of the tt(-r) option. When a suffix 
+has been inserted and the completion accepted, the function
+var(remove-func) will be called after the next character typed.  It is
+passed the length of the suffix as an argument and can use the special
+parameters available in ordinary (non-completion) zle widgets (see
 ifzman(zmanref(zshzle))\
 ifnzman(noderef(Zsh Line Editor))\
 ) to analyse and modify the command line.
 )
 item(tt(-f))(
-If this flag is given, the matches build are marked as being the names 
-of files. They need not be actual filenames, though. But if they are
-and the option tt(LIST_TYPES) is set, the characters describing the
-types of the files in the completion lists will be shown. This also
-makes a slash automatically be added when the name of a directory is
-completed.
+If this flag is given, all of the matches built from var(words) are
+marked as being the names of files.  They are not required to be actual
+filenames, but if they are, and the option tt(LIST_TYPES) is set, the
+characters describing the types of the files in the completion lists will
+be shown. This also forces a slash to be added when the name of a
+directory is completed.
+)
+item(tt(-e))(
+This flag can be used to tell the completion code that the matches
+added are parameter names for a parameter expansion. This will make
+the tt(AUTO_PARAM_SLASH) and tt(AUTO_PARAM_KEYS) options be used for
+the matches.
 )
 item(tt(-W) var(file-prefix))(
-This option has the same meaning as for the tt(compctl) and
-tt(complist) builtin commands. Here, however, only one string may be
-given, not an array. This string is used as a pathname that will be
-prepended to the given words and the prefix given with the tt(-p)
-option to perform the file-tests when showing completion
-listings. Hence it is only useful if combined with the tt(-f) flag,
-since the tests will only be performed if that flag is given.
-)
-item(tt(-a))(
-When used by tt(compctl) or tt(complist) the completion code normally
-builds two sets of matches: the normal one where words with one of the 
-suffixes in the array parameter tt(fignore) are not considered
-possible matches, and the alternate set where the words excluded
-from the first set are stored. Normally only the matches in the first
-set are used. But if this set is empty, the words from the alternate
-set are used.
-
-The tt(compadd) builtin does not use tt(fignore) parameter and
-normally stores all words in the first set. With the tt(-a)-flag
-given, however, they are all stored in the alternate set unless this
-flag is overridden by the tt(-F) option.
+This string is a pathname that will be
+prepended to each of the matches formed by the given var(words) together 
+with any prefix specified by the tt(-p) option to form a complete filename
+for testing.  Hence it is only useful if combined with the tt(-f) flag, as
+the tests will not otherwise be performed.
 )
 item(tt(-F) var(array))(
-This can be used to give an array containing suffixes like the
-tt(fignore) parameter. Words with one of these suffixes are stored in
-the alternate set of matches and words without one of these suffixes
-are stored in the normal set.
+Specifies an array containing patterns. Words matching one of these
+patterns are ignored, i.e. not considered to be possible matches.
 
 The var(array) may be the name of an array parameter or a list of
-literal suffixes enclosed in parentheses as in `tt(-F "(.o .h)")'. If
-the name of an array is given, the elements of the array are taken as
-the suffixes.
+literal patterns enclosed in parentheses and quoted, as in `tt(-F "(*?.o
+*?.h)")'. If the name of an array is given, the elements of the array are
+taken as the patterns.
 )
 item(tt(-Q))(
-As for tt(compctl) and tt(complist) this flag instructs the completion 
+This flag instructs the completion 
 code not to quote any metacharacters in the words when inserting them
-in the command line.
-)
-item(tt(-m))(
-Normally the matches added by tt(compadd) will not be compared with
-what is already on the line. If this flag is given, this comparison is 
-performed as usual and the match specifications given with the tt(-M)
-option to tt(compadd) and the global match specifications defined with 
-tt(compctl) will be used. This means that probably not all the word
-given will be stored as matches since some of them may not match the
-string on the line.
+into the command line.
 )
 item(tt(-M) var(match-spec))(
-This option allows one to give local match specifications with the
-same meaning and format as for the tt(compctl) and tt(complist)
-builtin commands. Note that they will only be used if the tt(-m) is
-given, too.
+This gives local match specifications as described below in
+noderef(Matching Control). This option may be given more than once. In 
+this case all var(match-spec)s given are concatenated with spaces
+between them to form the specification string to use.
+Note that they will only be used if the tt(-U) option is not given.
 )
 item(tt(-n))(
-Words added with tt(compadd) with this flag will be used as possible
-matches as usual but they not appear in the completion listing.
+Specifies that the words added are to be used as possible
+matches, but are not to appear in the completion listing.
 )
 item(tt(-U))(
-If this flag is given to one of the calls to tt(compadd) and the
-option tt(AUTO_MENU) is set, the completion code will immediatly
-switch to menucompletion.
+If this flag is given, all words given will be accepted and no matching
+will be done by the completion code. Normally this is used in
+functions that do the matching themselves.
+)
+item(tt(-O) var(array))(
+If this option is given, the var(words) are em(not) added to the set of
+possible completions.  Instead, matching is done as usual and all of the
+var(words) given as arguments that match the string on the command line
+will be stored in the array parameter whose name is given as var(array).
+)
+item(tt(-A) var(array))(
+As the tt(-O) option, except that instead of those of the var(words) which
+match being stored in var(array), the strings generated internally by the
+completion code are stored. For example,
+with a matching specification of `tt(-M "L:|no=")', the string `tt(nof)'
+on the command line and the string `tt(foo)' as one of the var(words), this
+option stores the string `tt(nofoo)' in the array, whereas the tt(-O)
+option stores the `tt(foo)' originally given.
+)
+item(tt(-D) var(array))(
+As with tt(-O), the var(words) are not added to the set of possible
+completions. Instead, the completion code tests every var(word) if 
+it matches what is on the line. If the var(n)'th var(word) does not
+match, the var(n)'th element of the var(array) is removed. Elements
+for which the corresponding var(word) is matched are retained.
 )
 item(tt(-), tt(--))(
 This flag ends the list of flags and options. All arguments after it
@@ -306,123 +597,344 @@ will be taken as the words to use as matches even if they begin with
 hyphens.
 )
 enditem()
+
+Except for the tt(-M) flag, if any of these flags is given more than
+once, the first one (and its argument) will be used.
+)
+findex(compset)
+cindex(completion widgets, modifying special parameters)
+xitem(tt(compset -p) var(number))
+xitem(tt(compset -P) [ var(number) ] var(pattern))
+xitem(tt(compset -s) var(number))
+xitem(tt(compset -S) [ var(number) ] var(pattern))
+xitem(tt(compset -n) var(begin) [ var(end) ])
+xitem(tt(compset -N) var(beg-pat) [ var(end-pat) ])
+item(tt(compset -q))(
+This command simplifies modification of the special parameters,
+while its return value allows tests on them to be carried out.
+
+The options are:
+
+startitem()
+item(tt(-p) var(number))(
+If the contents of the tt(PREFIX) parameter is longer than var(number)
+characters, the first var(number) characters are removed from it and
+appended to the contents of the tt(IPREFIX) parameter.
+)
+item(tt(-P) [ var(number) ] var(pattern))(
+If the value of the tt(PREFIX) parameter begins with anything that
+matches the var(pattern), the matched portion is removed from
+tt(PREFIX) and appended to tt(IPREFIX).
+
+Without the optional var(number), the longest match is taken, but
+if var(number) is given, anything up to the var(number)'th match is
+moved.  If the var(number) is negative, the var(number)'th longest
+match is moved. For example, if tt(PREFIX) contains the string
+`tt(a=b=c)', then tt(compset -P '*\=') will move the string `tt(a=b=)' 
+into the tt(IPREFIX) parameter, but tt(compset -P 1 '*\=') will move only
+the string `tt(a=)'.
+)
+item(tt(-s) var(number))(
+As tt(-p), but transfer the last var(number) characters from the
+value of tt(SUFFIX) to the front of the value of tt(ISUFFIX).
+)
+item(tt(-S) [ var(number) ] var(pattern))(
+As tt(-P), but match the last portion of tt(SUFFIX) and transfer the
+matched portion to the front of the value of tt(ISUFFIX).
+)
+item(tt(-n) var(begin) [ var(end) ])(
+If the current word position as specified by the parameter tt(CURRENT) 
+is greater than or equal to var(begin), anything up to the
+var(begin)'th word is removed from the tt(words) array and the value
+of the parameter tt(CURRENT) is decremented by var(begin).
+
+If the optional var(end) is given, the modification is done only if
+the current word position is also less than or equal to var(end). In
+this case, the words from position var(end) onwards are also removed from
+the tt(words) array.
+
+Both var(begin) and var(end) may be negative to count backwards
+from the last element of the tt(words) array.
+)
+item(tt(-N) var(beg-pat) [ var(end-pat) ])(
+If one of the elements of the tt(words) array before the one at the
+index given by the value of the parameter tt(CURRENT) matches the
+pattern var(beg-pat), all elements up to and including the matching one are
+removed from the tt(words) array and the value of tt(CURRENT) is changed to
+point to the same word in the changed array.
+
+If the optional pattern var(end-pat) is also given, and there is an
+element in the tt(words) array matching this pattern, the parameters
+are modified only if the index of this word is higher than the one
+given by the tt(CURRENT) parameter (so that the matching word has 
+to be after the cursor). In this case, the words starting with the one
+matching tt(end-pat) are also removed from the tt(words)
+array. If tt(words) contains no word matching var(end-pat), the
+testing and modification is performed as if it were not given.
+)
+item(tt(-q))(
+The word
+currently being completed is split in separate words at the spaces. The 
+resulting words are stored in the tt(words) array, and tt(CURRENT),
+tt(PREFIX), tt(SUFFIX), tt(QIPREFIX), and tt(QISUFFIX) are modified to
+reflect the word part that is completed.
+)
+enditem()
+
+In all the above cases the return value is zero if the test succeeded
+and the parameters were modified and non-zero otherwise. This allows
+one to use this builtin in tests such as:
+
+example(if compset -P '*\='; then ...)
+
+This forces anything up to and including the last equal sign to be
+ignored by the completion code.
 )
 item(tt(compcall) [ tt(-TD) ])(
+This allows the use of completions defined with the tt(compctl) builtin
+from within completion widgets.  The list of matches will be generated as
+if one of the non-widget completion function (tt(complete-word), etc.)
+had been called, except that only tt(compctl)s given for specific commands
+are used. To force the code to try completions defined with the tt(-T)
+option of tt(compctl) and/or the default completion (whether defined by
+tt(compctl -D) or the builtin default) in the appropriate places, the
+tt(-T) and/or tt(-D) flags can be passed to tt(compcall).
+
+The return value can be used to test if a matching tt(compctl)
+definition was found. It is non-zero if a tt(compctl) was found and
+zero otherwise.
 
-This allows one to use completion definitions given with the
-tt(compctl) builtin from within completion widgets. It makes
-completion code complete the current word according to the
-tt(compctl)s defined. Normally only tt(compctl)s given for specific
-commands are used. To make the code use the completion flags given to
-the tt(-T) option of tt(compctl), one can give the tt(-T) flag to
-tt(compctl). Likewise, the tt(-D) flag to tt(compcall) makes the
-default completion flags given to tt(compctl) with the tt(-D) option
-be used.
+Note that this builtin is defined by the tt(zsh/compctl) module.
 )
 enditem()
 
-texinode(Condition Codes)(Examples)(Builtin Commands)(Completion Widgets)
+texinode(Condition Codes)(Matching Control)(Builtin Commands)(Completion Widgets)
 sect(Condition Codes)
+cindex(completion widgets, condition codes)
 
-Inside completion widgets not only the builtin commands described
-above can be used, but also some additional condition codes. These
-work on the special parameters and can be used to easily build
-completion functions that generate different matches depending on the
-strings on the line.
-
-The following condition codes are made available inside completion
-widgets:
+The following additional condition codes for use within the tt([[ ... ]])
+construct are available in completion widgets.  These work on the special
+parameters.  All of these tests can also be performed by the tt(compset)
+builtin, but in the case of the condition codes the contents of the special
+parameters are not modified.
 
 startitem()
-item(tt(-prefix) var(string))(
-true if the content of tt(PREFIX) starts with var(string)
-)
-item(tt(-iprefix) var(string))(
-like tt(-prefix), but the var(string) is removed from tt(PREFIX) and
-added to tt(IPREFIX)
-)
-item(tt(-position) var(beg) [ var(end) ])(
-true if tt(CURRENT) is equal to var(beg) or, if var(end) is given,
-equal to or greater than var(beg) and equal to or less than var(end);
-both of var(beg) and var(end) may be arithmetic expressions, if they
-are less than zero the number of words in tt(argv) are added to them
-before comparing them to tt(CURRENT); thus, tt(-1) is the last word,
-tt(-2) is the word before that and so on
-)
-item(tt(-word) var(index) var(string))(
-true if the word number var(index) in tt(argv) is equal to
-var(string); again, var(index) may be negative, counting backwards
+item(tt(-prefix) [ var(number) ] var(pattern))(
+true if the test for the tt(-P) option of tt(compset) would succeed.
 )
-item(tt(-mword) var(index) var(pattern))(
-like tt(-word) but using pattern matching
+item(tt(-suffix) [ var(number) ] var(pattern))(
+true if the test for the tt(-S) option of tt(compset) would succeed.
 )
-item(tt(-current) var(offset) var(string))(
-like tt(-word) but var(offset) is relative to the value of
-tt(CURRENT)
+item(tt(-after) var(beg-pat))(
+true if the test of the tt(-N) option with only the var(beg-pat) given 
+would succeed.
 )
-item(tt(-mcurrent) var(offset) var(pattern))(
-like tt(-current) but using pattern matching
+item(tt(-between) var(beg-pat end-pat))(
+true if the test for the tt(-N) option with both patterns would succeed.
 )
-item(tt(-string) [ var(number) ] var(string))(
-true if the current word contains var(string); anything up to the last 
-occurrence of this string will be ingnored by removing it from
-tt(PREFIX) and adding it to tt(IPREFIX); if var(number) is given,
-anything up to the var(number)'th occurrence of the var(string) will
-be ignored; again, var(nmuber) may be any arithmetic expression and
-negative values count backward
-)
-item(tt(-class) [ var(number) ] var(class))(
-like tt(-string) but the var(class) is used as a character class so
-that anything up to and including the last or the var(number)'th
-occurrence of any character from the string var(class) is ignored
-)
-item(tt(-words) var(min) [ var(max) ])(
-true if the number of words is equal to var(min); if var(max) is
-given, it is true if the number of words is equal to or greater than
-var(min) and equal to or less than var(max)
-)
-item(tt(-after) var(string))(
-true if the cursor is after a word that is equal to var(string)
-)
-item(tt(-mafter) var(pattern))(
-like tt(-after) but using pattern matching
-)
-item(tt(-between) var(string1) var(string2))(
-true if the cursor is after a word that is equal to var(string1), if
-there is also a word that is equal to va(string2), this is true only
-if the cursor is before it
-)
-item(tt(-mbetween) var(pattern1) var(pattern2))(
-like tt(-between) but using pattern matching
-)
-item(tt(-nmatches) var(number))(
-true if the the value of tt(NMATCHES) is equal to var(number)
-)
-item(tt(-matcher) var(number))(
-true if the value of tt(MATCHER) is equal to var(number)
+enditem()
+
+texinode(Matching Control)(Examples)(Condition Codes)(Completion Widgets)
+sect(Matching Control)
+
+It is possible by use of the 
+tt(-M) option of the tt(compadd) builtin command to specify how the
+characters in the string to be completed (referred to here as the
+command line) map onto the characters in the list of matches produced by
+the completion code (referred to here as the trial completions). Note
+that this is not used if the command line contains a glob pattern and
+the tt(GLOB_COMPLETE) option is set.
+
+The var(spec) consists of one or more matching descriptions separated by
+whitespace. Each description consists of a letter followed by a colon,
+then the patterns describing which character sequences on the line match
+which character sequences in the trial completion.  Any sequence of characters not
+handled in this fashion must match exactly, as usual.
+
+The forms of var(spec) understood are as follows. In each case, the
+form with an uppercase initial character retains the string already
+typed on the command line as the final result of completion, while with
+a lowercase initial character the string on the command line is changed
+into the corresponding part of the trial completion.
+
+startitem()
+xitem(tt(m:)var(lpat)tt(=)var(tpat))
+item(tt(M:)var(lpat)tt(=)var(tpat))(
+Here, var(lpat) is a pattern that matches on the command line,
+corresponding to var(tpat) which matches in the trial completion.
+)
+xitem(tt(l:)var(anchor)tt(|)var(lpat)tt(=)var(tpat))
+item(tt(L:)var(anchor)tt(|)var(lpat)tt(=)var(tpat))(
+These letters are for patterns that are anchored by another pattern on
+the left side. Matching for var(lpat) and var(tpat) is as for tt(m) and
+tt(M), but the pattern var(lpat) matched on the command line must be
+preceeded by the pattern var(anchor).  The var(anchor) can be blank to
+anchor the match to the start of the command line string; otherwise the
+anchor can occur anywhere, but must match in both the command line and
+trial completion strings.
+)
+xitem(tt(r:)var(lpat)tt(|)var(anchor)tt(=)var(tpat))
+item(tt(R:)var(lpat)tt(|)var(anchor)tt(=)var(tpat))(
+As tt(l) and tt(L) with the difference that the command line and trial
+completion patterns are anchored on the right side.  Here an empty
+var(anchor) forces the match to the end of the command line string.
 )
 enditem()
 
-texinode(Examples)()(Condition Codes)(Completion Widgets)
+Each var(lpat), var(tpat) or var(anchor) is either an empty string or
+consists of a sequence of literal characters (which may be quoted with a
+backslash), question marks, character classes, and correspondence
+classes; ordinary shell patterns are not used.  Literal characters match
+only themselves, question marks match any character, and character
+classes are formed as for globbing and match any character in the given
+set.
+
+Correspondence classes are defined like character classes, but with two
+differences: they are delimited by a pair of braces, and negated classes
+are not allowed, so the characters tt(!) and tt(^) have no special
+meaning directly after the opening brace.  They indicate that a range of
+characters on the line match a range of characters in the trial
+completion, but (unlike ordinary character classes) paired according to
+the corresponding position in the sequence. For example, to make any
+lowercase letter on the line match the corresponding uppercase letter in
+the trial completion, you can use `tt(m:{a-z}={A-Z})'.  More than one
+pair of classes can occur, in which case the first class before the
+tt(=) corresponds to the first after it, and so on.  If one side has
+more such classes than the other side, the superfluous classes behave
+like normal character classes. In anchor patterns correspondence classes
+also behave like normal character classes.
+
+The pattern var(tpat) may also be one or two stars, `tt(*)' or
+`tt(**)'. This means that the pattern on the command line can match
+any number of characters in the trial completion. In this case the
+pattern must be anchored (on either side); in the case of a single
+star, the var(anchor) then determines how much of the trial completion
+is to be included --- only the characters up to the next appearance of
+the anchor will be matched. With two stars, substrings matched by the
+anchor can be matched, too.
+
+Examples:
+
+The keys of the tt(options) association defined by the tt(parameter)
+module are the option names in all-lowercase form, without
+underscores, and without the optional tt(no) at the beginning even
+though the builtins tt(setopt) and tt(unsetopt) understand option names
+with uppercase letters, underscores, and the optional tt(no).  The
+following alters the matching rules so that the prefix tt(no) and any
+underscore are ignored when trying to match the trial completions
+generated and uppercase letters on the line match the corresponding
+lowercase letters in the words:
+
+example(compadd -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' - \ 
+  ${(k)options} )
+
+The first part says that the pattern `tt([nN][oO])' at the beginning
+(the empty anchor before the pipe symbol) of the string on the
+line matches the empty string in the list of words generated by
+completion, so it will be ignored if present. The second part does the
+same for an underscore anywhere in the command line string, and the
+third part uses correspondence classes so that any
+uppercase letter on the line matches the corresponding lowercase
+letter in the word. The use of the uppercase forms of the
+specification characters (tt(L) and tt(M)) guarantees that what has
+already been typed on the command line (in particular the prefix
+tt(no)) will not be deleted.
+
+The second example makes completion case insensitive.  This is just
+the same as in the option example, except here we wish to retain the
+characters in the list of completions:
+
+example(compadd -M 'm:{a-z}={A-Z}' ... )
+
+This makes lowercase letters match their uppercase counterparts.
+To make uppercase letters match the lowercase forms as well:
+
+example(compadd -M 'm:{a-zA-Z}={A-Za-z}' ... )
+
+A nice example for the use of tt(*) patterns is partial word
+completion. Sometimes you would like to make strings like tt(c.s.u)
+complete to strings like tt(comp.source.unix), i.e. the word on the
+command line consists of multiple parts, separated by a dot in this
+example, where each part should be completed separately --- note,
+however, that the case where each part of the word, i.e. tt(comp),
+tt(source) and tt(unix) in this example, is to be completed separately
+is a different problem to be solved by extended completion.  The
+example can be handled by:
+
+example(compadd -M 'r:|.=* r:|=*' \ 
+  - comp.sources.unix comp.sources.misc ...)
+
+The first specification says that tt(lpat) is the empty string, while
+tt(anchor) is a dot; tt(tpat) is tt(*), so this can match anything
+except for the `tt(.)' from the anchor in
+the trial completion word.  So in tt(c.s.u), the matcher sees tt(c),
+followed by the empty string, followed by the anchor `tt(.)', and
+likewise for the second dot, and replaces the empty strings before the
+anchors, giving tt(c)[tt(omp)]tt(.s)[tt(ources)]tt(.u)[tt(nix)], where
+the last part of the completion is just as normal.
+
+With the pattern shown above, the string `tt(c.u)' could not be
+completed to `tt(comp.sources.unix)' because the single star means
+that no dot (matched by the anchor) can be skipped. By using two stars 
+as in `tt(r:|.=**)', however, `tt(c.u)' could be completed to
+`tt(comp.sources.unix)'. This also shows that in some cases,
+especially if the anchor is a real pattern, like a character class,
+the form with two stars may result in more matches than one would like.
+
+The second specification is needed to make this work when the cursor is
+in the middle of the string on the command line and the option
+tt(COMPLETE_IN_WORD) is set. In this case the completion code would
+normally try to match trial completions that end with the string as
+typed so far, i.e. it will only insert new characters at the cursor
+position rather then at the end.  However in our example we would like
+the code to recognise matches which contain extra characters after the
+string on the line (the tt(nix) in the example).  Hence we say that the
+empty string at the end of the string on the line matches any characters
+at the end of the trial completion.
+
+More generally, the specification
+
+example(compadd -M 'r:|[.,_-]=* r:|=*' ... )
+
+allows one to complete words with abbreviations before any of the
+characters in the square brackets.  For example, to
+complete tt(veryverylongfile.c) rather than tt(veryverylongheader.h)
+with the above in effect, you can just type tt(very.c) before attempting
+completion.
+
+When using the completion system (see
+ifzman(zmanref(zshcompsys))\
+ifnzman(noderef(Completion System))\
+), users can define match specifications that are to be used for
+specific contexts by using the tt(matcher) style and match
+specifications that are to be used everywhere can be defined by the
+use of the tt(_matcher) completer.
+
+texinode(Examples)()(Matching Control)(Completion Widgets)
 sect(Examples)
+cindex(completion widgets, examples)
 
 The first step is to define the widget:
 
-indent(nofill(
-tt(zle -C complete complete-word complete-history)))
+example(zle -C complete complete-word complete-files)
 
 Then the widget can be bound to a key using the tt(bindkey) builtin
 command:
 
-indent(nofill(
-tt(bindkey '^X\t' complete)))
+example(bindkey '^X\t' complete)
 
-After that the shell function tt(complete-history) will be invoked
-after typing control-X and TAB. The function should then generte the
+After that the shell function tt(complete-files) will be invoked
+after typing control-X and TAB. The function should then generate the
 matches, e.g.:
 
-indent(nofill(
-tt(complete-history LPAR()RPAR() { complist -H 0 '' })))
+example(complete-files LPAR()RPAR() { compadd - * })
 
-In this the function will complete words from the history matching the 
+This function will complete files in the current directory matching the 
 current word.
+
+For a description of the widget-based completion system provided with the
+source code distribution, see
+ifzman(zmanref(zshcompsys))\
+ifnzman(noderef(Completion System))\
+.
+
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 99844b42a..7198df703 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -5,15 +5,15 @@ sect(Description)
 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 @@ em(filename expansion) followed by em(filename generation).
 
 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 @@ 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)
-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
@@ -161,11 +161,17 @@ Print the new command but do not execute it.  Only works with history
 expansion.
 )
 item(tt(q))(
-Quote the substituted words, escaping further substitutions.  Only
-works with history expansion.
+Quote the substituted words, escaping further substitutions.  Works
+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.
@@ -175,17 +181,18 @@ 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 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.
 )
 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 any of `tt(LPAR())', `tt([)', or `tt({)'
-is used as the opening delimiter
-the second one has to be 'tt(RPAR())', `tt(])', or `tt(})' respectively.
+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
@@ -200,13 +207,13 @@ 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,
 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
+immediately by a tt(g).  In parameter expansion the tt(&) must appear
+inside braces, and in filename generation it must be quoted with a
 backslash.
 )
 enditem()
@@ -225,7 +232,7 @@ 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 last history reference on that command line, unless it is the
+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,
@@ -244,8 +251,12 @@ 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 character sequence `tt(^)var(foo)tt(^)var(bar)'
+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
@@ -275,7 +286,8 @@ 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,
 
-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))
+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))
 
 cuts fields 1 and 3 from the files var(file1) and var(file2) respectively,
 pastes the results together, and sends it to the processes
@@ -284,7 +296,7 @@ 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.
 Also note that the previous example can be more compactly and
-efficiently written as:
+efficiently written (provided the tt(MULTIOS) option is set) as:
 
 nofill(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR() > >LPAR())var(process1)tt(RPAR() > >LPAR())var(process2)tt(RPAR()))
 
@@ -309,27 +321,37 @@ zmanref(zshparam)
 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).  In addition to the following
-operations, the file modifiers described in
+see noderef(Filename Generation).  Note that these patterns, along with
+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).  In addition, more complicated forms of substitution
+usually require the braces to be present; exceptions, which only apply if
+the option tt(KSH_ARRAYS) is not set, are a single subscript or any colon
+modifiers appearing after the name, or any of the characters `tt(^)',
+`tt(=)', `tt(~)', `tt(#)' or `tt(+)' appearing before the name, all of
+which work with or without braces.
 
-If var(name) is an array parameter, then the values 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)
-option is set.
+If var(name) is an array parameter, and the tt(KSH_ARRAYS) option is not
+set, then the value of each
+element of var(name) is substituted, one element per word.  Otherwise, the
+expansion results in one word only; with tt(KSH_ARRAYS), this is the first
+element of an array.  No field splitting is done on the result unless the
+tt(SH_WORD_SPLIT) option is set.
 )
 item(tt(${PLUS())var(name)tt(}))(
 If var(name) is the name of a set parameter `tt(1)' is substituted,
@@ -340,14 +362,17 @@ If var(name) is set and is non-null then substitute its
 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
+If var(name) is set and is non-null then substitute
 its value; otherwise, print var(word) and exit from the shell.
+Interactive shells instead return to the prompt.
 If var(word) is omitted, then a standard message is printed.
 )
 item(tt(${)var(name)tt(:PLUS())var(word)tt(}))(
@@ -358,13 +383,14 @@ enditem()
 
 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
@@ -373,9 +399,7 @@ the matched portion deleted; otherwise, just
 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(}))(
@@ -385,24 +409,52 @@ the matched portion deleted; otherwise, just
 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(}))(
+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.
+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.
+
+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; however,
+the flags tt(M), tt(R), tt(B), tt(E) and tt(N) are not useful.
+
+For example,
+
+example(foo="twinkle twinkle little star" sub="t*e" rep="spy"
+print ${foo//${~sub}/$rep}
+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
+match for tt(t*e) is substituted and the result is `tt(spy star)',
+while in the second case, the shortest matches are taken and the
+result is `tt(spy spy lispy star)'.
+)
 item(tt(${#)var(spec)tt(}))(
 If var(spec) is one of the above substitutions, substitute
 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)
@@ -411,7 +463,7 @@ cindex(rc, array expansion style)
 Turn on the tt(RC_EXPAND_PARAM) option for the
 evaluation of var(spec); if the `tt(^)' is doubled, turn it off.
 When this option is set, array expansions of the form
-`var(foo)tt(${)var(xx)tt(})var(bar)',
+var(foo)tt(${)var(xx)tt(})var(bar),
 where the parameter var(xx)
 is set to tt(LPAR())var(a b c)tt(RPAR()), are substituted with
 `var(fooabar foobbar foocbar)' instead of the default
@@ -420,7 +472,7 @@ is set to tt(LPAR())var(a b c)tt(RPAR()), are substituted with
 Internally, each such expansion is converted into the
 equivalent list for brace expansion.  E.g., tt(${^var}) becomes
 tt({$var[1],$var[2],)...tt(}), and is processed as described in
-noderef(Brace Expansion) above.
+noderef(Brace Expansion) below.
 If word splitting is also in effect the
 tt($var[)var(N)tt(]) may themselves be split into different list
 elements.
@@ -429,36 +481,51 @@ item(tt(${=)var(spec)tt(}))(
 pindex(SH_WORD_SPLIT, use of)
 cindex(field splitting, sh style)
 cindex(sh, field splitting style)
-Turn on the tt(SH_WORD_SPLIT) option for the
-evaluation of var(spec); if the `tt(=)' is doubled, turn it off.
+Perform word splitting using the rules for tt(SH_WORD_SPLIT) during the
+evaluation of var(spec), but regardless of whether the parameter appears in
+double quotes; 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.
+This forces parameter expansions to be 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
-generation.
+set, the string resulting from the expansion will be interpreted as a
+pattern anywhere that is possible, such as in filename expansion and
+filename generation and pattern-matching contexts like the right
+hand side of the `tt(=)' and `tt(!=)' operators in conditions.
 )
 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)
+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 example below.
+combination with the flags described next; see the examples below.
+
+Note that double quotes may appear around nested substitutions, 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
+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
+before.
+
 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
@@ -468,20 +535,33 @@ in place of the colon as delimiters.  The following flags are supported:
 
 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)=)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
 em(arithmetic expansion) on the result. Such expansions can be
 nested but too deep recursion may have unpredictable effects.
 )
+item(tt(P))(
+This forces the value of the parameter var(name) to be interpreted as a
+further parameter name, whose value will be used where appropriate. If used
+with a nested parameter or command substitution, the result of that will be
+taken as a parameter name in the same way.  For example, if you have
+`tt(foo=bar)' and `tt(bar=baz)', the strings tt(${(P)foo}),
+tt(${(P)${foo}}), and tt(${(P)$(echo bar)}) will be expanded to `tt(baz)'.
+)
 item(tt(o))(
 Sort the resulting words in ascending order.
 )
@@ -498,7 +578,33 @@ item(tt(U))(
 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(V))(
+Make any special characters in the resulting words visible.
+)
+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($).
+)
+item(tt(Q))(
+Remove one level of quotes from the resulting words.
+)
+item(tt(%))(
+Expand all tt(%) escapes in the resulting words in the same way as in
+prompts (see noderef(Prompt Expansion)). If this flag is given twice,
+full prompt expansion is done on the resulting words, depending on the 
+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
+pattern matching forms such as `tt(${)var(name)tt(#)var(pattern)tt(})' 
+are reported. Without the flag they are silently ignored.
 )
 item(tt(c))(
 With tt(${#)var(name)tt(}), count the total number of characters in an array,
@@ -512,20 +618,34 @@ item(tt(W))(
 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
 required and placed in a field var(expr) characters wide.  The space
 to the left will be filled with var(string1) (concatenated as often
 as needed) or spaces if var(string1) is not given.  If both
-var(string1) and var(string2) are given, this string will be placed
-exactly once directly to the left of the resulting word.
+var(string1) and var(string2) are given, this string is inserted
+once directly to the left of each word, before padding.
 )
 item(tt(r:)var(expr)tt(::)var(string1)tt(::)var(string2)tt(:))(
-As tt(l), but pad the words on the right.
+As tt(l), but pad the words on the right and insert var(string2)
+on the right.
 )
 item(tt(j:)var(string)tt(:))(
 Join the words of arrays together using var(string) as a separator.
@@ -546,13 +666,78 @@ item(tt(f))(
 Split the result of the expansion to lines. This is a shorthand
 for `tt(ps:\n:)'.
 )
+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:
+
+startitem()
+item(tt(local))(
+for local parameters
+)
+item(tt(left))(
+for left justified parameters
+)
+item(tt(right_blanks))(
+for right justified parameters with leading blanks
+)
+item(tt(right_zeros))(
+for right justified parameters with leading zeros
+)
+item(tt(lower))(
+for parameters whose value is converted to all lower case when it is
+expanded
+)
+item(tt(upper))(
+for parameters whose value is converted to all upper case when it is
+expanded
+)
+item(tt(readonly))(
+for readonly parameters
+)
+item(tt(tag))(
+for tagged parameters
+)
+item(tt(export))(
+for exported parameters
+)
+item(tt(unique))(
+for arrays which keep only the first occurrence of duplicated values
+)
+item(tt(hide))(
+for parameters with the `hide' flag
+)
+item(tt(special))(
+for special parameters defined by the shell
+)
+enditem()
+)
+enditem()
+
+The following flags are meaningful with the tt(${)...tt(#)...tt(}) or
+tt(${)...tt(%)...tt(}) forms.  The tt(S) and tt(I) flags may also be
+used with the 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.
+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
+tt(${)...tt(//)...tt(}), specifies that the shortest instead of the
+longest match should be replaced.
 )
 item(tt(I:)var(expr)tt(:))(
 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.
 )
 item(tt(M))(
 Include the matched portion in the result.
@@ -570,22 +755,153 @@ item(tt(N))(
 Include the length of the match in the result.
 )
 enditem()
-subsect(Example)
+
+subsect(Rules)
+
+Here is a summary of the rules for substitution; this assumes that braces
+are present around the substitution, i.e. tt(${...}).  Some particular
+examples are given below.  Note that the Zsh Development Group accepts
+em(no responsibility) for any brain damage which may occur during the
+reading of the following rules.
+
+startitem()
+item(tt(1.) em(Nested Substitution))(
+If multiple nested tt(${...}) forms are present, substitution is
+performed from the inside outwards.  At each level, the substitution takes
+account of whether the current value is a scalar or an array, whether the
+whole substitution is in double quotes, and what flags are supplied to the
+current level of substitution, just as if the nested substitution were the
+outermost.  The flags are not propagated up to enclosing
+substitutions; the nested substitution will return either a scalar or an
+array as determined by the flags, possibly adjusted for quoting.  All the
+following steps take place where applicable at all levels of substitution.
+Note that, unless the `tt((P))' flag is present, the flags and any subscripts
+apply directly to the value of the nested substitution; for example, the
+expansion tt(${${foo}}) behaves exactly the same as tt(${foo}).
+)
+item(tt(2.) em(Parameter Subscripting))(
+If the value is a raw parameter reference with a subscript, such as
+tt(${)var(var)tt([3]}), the effect of subscripting is applied directly to
+the parameter.  Subscripts are evaluated left to right; subsequent
+subscripts apply to the scalar or array value yielded by the previous
+subscript.  Thus if tt(var) is an array, tt(${var[1][2]}) is the second
+character of the first word, but tt(${var[2,4][2]}) is the entire third
+word (the second word of the range of words two through four of the
+original array).  Any number of subscripts may appear.
+)
+item(tt(3.) em(Parameter Name Replacement))(
+The effect of any tt((P)) flag, which treats the value so far as a
+parameter name and replaces it with the corresponding value, is applied.
+)
+item(tt(4.) em(Double-Quoted Joining))(
+If the value after this process is an array, and the substitution
+appears in double quotes, and no tt((@)) flag is present at the current
+level, the words of the value are joined with the first character of the
+parameter tt($IFS), by default a space, between each word (single word
+arrays are not modified).  If the tt((j)) flag is present, that is used for
+joining instead of tt($IFS).
+)
+item(tt(5.) em(Nested Subscripting))(
+Any remaining subscripts (i.e. of a nested substitution) are evaluated at
+this point, based on whether the value is an array or a scalar.  As with
+tt(2.), multiple subscripts can appear.  Note that tt(${foo[2,4][2]}) is
+thus equivalent to tt(${${foo[2,4]}[2]}) and also to
+tt("${${(@)foo[2,4]}[2]}") (the nested substitution returns an array in
+both cases), but not to tt("${${foo[2,4]}[2]}") (the nested substitution
+returns a scalar because of the quotes).
+)
+item(tt(6.) em(Modifiers))(
+Any modifiers, as specified by a trailing `tt(#)', `tt(%)', `tt(/)'
+(possibly doubled) or by a set of modifiers of the form tt(:...) (see
+noderef(Modifiers) in noderef(History Expansion)), are applied to the words
+of the value at this level.
+)
+item(tt(7.) em(Forced Joining))(
+If the `tt((j))' flag is present, or no `tt((j))' flag is present but
+the string is to be split as given by rules tt(8.) or tt(9.), and joining
+did not take place at step tt(4.), any words in the value are joined
+together using the given string or the first character of tt($IFS) if none.
+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(=)'
+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).
+)
+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.
+)
+item(tt(10.) em(Re-Evaluation))(
+Any `tt((e))' flag is applied to the value, forcing it to be re-examined
+for new parameter substitutions, but also for command and arithmetic
+substitutions.
+)
+item(tt(11.) em(Padding))(
+Any padding of the value by the `tt(LPAR()l.)var(fill)tt(.RPAR())' or
+`tt(LPAR()r.)var(fill)tt(.RPAR())' flags is applied.
+)
+enditem()
+
+subsect(Examples)
 The flag tt(f) is useful to split a double-quoted substitution line by
-line.  For example, `tt("${(f)$LPAR()<)var(file)tt(RPAR()}")'
-will substitue the contents of var(file) divided so that one line is
-supplied per argument to var(cmd).  Compare this with the effect of
-`tt($)tt(LPAR()<)var(file)tt(RPAR())' alone, which divides the file
-up by words, or the same inside double quotes, where the entire
-contents of the file are passed as a single argument.
+line.  For example, tt(${(f)"$LPAR()<)var(file)tt(RPAR()"})
+substitutes the contents of var(file) divided so that each line is
+an element of the resulting array.  Compare this with the effect of
+tt($)tt(LPAR()<)var(file)tt(RPAR()) alone, which divides the file
+up by words, or the same inside double quotes, which makes the entire
+content of the file a single string.
+
+The following illustrates the rules for nested parameter expansions.
+Suppose that tt($foo) contains the array tt(LPAR()bar baz)tt(RPAR()):
+
+startitem()
+item(tt("${(@)${foo}[1]}"))(
+This produces the result tt(b).  First, the inner substitution
+tt("${foo}"), which has no array (tt(@)) flag, produces a single word
+result tt("bar baz").  The outer substitution tt("${(@)...[1]}") detects
+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
+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]}").
+)
+enditem()
+
+As an example of the rules for word splitting and joining, suppose tt($foo)
+contains the array `tt(LPAR()ax1 bx1)tt(RPAR())'.  Then
+
+startitem()
+item(tt(${(s/x/)foo}))(
+produces the words `tt(a)', `tt(1 b)' and `tt(1)'.
+)
+item(tt(${(j/x/s/x/)foo}))(
+produces `tt(a)', `tt(1)', `tt(b)' and `tt(1)'.
+)
+item(tt(${(s/x/)foo%%1*}))(
+produces `tt(a)' and `tt( b)' (note the extra space).  As substitution
+occurs before either joining or splitting, the operation  first generates
+the modified array tt(LPAR()ax bx)tt(RPAR()), which is joined to give
+tt("ax bx"), and then split to give `tt(a)', `tt( b)' and `'.  The final
+empty string will then be elided, as it is not in double quotes.
+)
+enditem()
+
 texinode(Command Substitution)(Arithmetic Expansion)(Parameter Expansion)(Expansion)
 sect(Command Substitution)
 cindex(command substitution)
 cindex(substitution, command)
-A command enclosed in parentheses
-preceded by a dollar sign, like `tt($LPAR())...tt(RPAR())', or quoted with grave
-accents, like `tt(`)...tt(`)', is replaced with its standard output, with any
-trailing newlines deleted.
+A command enclosed in parentheses preceded by a dollar sign, like
+`tt($LPAR())...tt(RPAR())', or quoted with grave 
+accents, like `tt(`)...tt(`)', is replaced with its standard output, with
+any trailing newlines deleted.
 If the substitution is not enclosed in double quotes, the
 output is broken into words using the tt(IFS) parameter.
 vindex(IFS, use of)
@@ -630,6 +946,14 @@ In that case, it is expanded to a sorted list of the individual
 characters between the braces, in the manner of a search set.
 `tt(-)' is treated specially as in a search set, but `tt(^)' or `tt(!)' as
 the first character is treated normally.
+
+Note that brace expansion is not part of filename generation (globbing); an
+expression such as tt(*/{foo,bar}) is split into two separate words
+tt(*/foo) and tt(*/bar) before filename generation takes place.  In
+particular, note that this is liable to produce a `no match' error if
+em(either) of the two expressions does not match; this is to be contrasted
+with tt(*/(foo|bar)), which is treated as a single pattern but otherwise
+has similar effects.
 texinode(Filename Expansion)(Filename Generation)(Brace Expansion)(Expansion)
 sect(Filename Expansion)
 cindex(filename expansion)
@@ -677,7 +1001,8 @@ directory as its prefix.  If so, then the prefix portion
 is replaced with a `tt(~)' followed by the name of the directory.
 The shortest way of referring to the directory is used,
 with ties broken in favour of using a named directory,
-except when the directory is tt(/) itself.
+except when the directory is tt(/) itself.  The parameters tt($PWD) and
+tt($OLDPWD) are never abbreviated in this fashion.
 
 If a word begins with an unquoted `tt(=)'
 and the tt(EQUALS) option is set,
@@ -745,7 +1070,7 @@ 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.
 There are also several named classes of characters, in the form
-`tt([:)var(name)(tt:])' with the following meanings:  `tt([:alnum:])'
+`tt([:)var(name)tt(:])' with the following meanings:  `tt([:alnum:])'
 alphanumeric, `tt([:alpha:])' alphabetic,
 `tt([:blank:])' space or tab,
 `tt([:cntrl:])' control character, `tt([:digit:])' decimal
@@ -770,13 +1095,23 @@ not in the given set.
 item(tt(<)[var(x)]tt(-)[var(y)]tt(>))(
 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.
+hence `tt(<->)' matches any number.  To match individual digits, the
+tt([)...tt(]) form is more efficient.
 )
 item(tt(LPAR())...tt(RPAR()))(
 Matches the enclosed pattern.  This is used for grouping.
 If the tt(KSH_GLOB) option is set, then a
 `tt(@)', `tt(*)', `tt(+)', `tt(?)' or `tt(!)' immediately preceding
-the `tt(LPAR())' is treated specially, as detailed below.
+the `tt(LPAR())' is treated specially, as detailed below. The option
+tt(SH_GLOB) prevents bare parentheses from being used in this way, though
+the tt(KSH_GLOB) option is still available.
+
+Note that grouping cannot extend over multiple directories: it is an error
+to have a `tt(/)' within a group (this only applies for patterns used in
+filename generation).  There is one exception:  a group of the form
+tt(LPAR())var(pat)tt(/RPAR()#) appearing as a complete path segment can
+match a sequence of directories.  For example, tt(foo/(a*/)#bar) matches
+tt(foo/bar), tt(foo/any/bar), tt(foo/any/anyother/bar), and so on.
 )
 item(var(x)tt(|)var(y))(
 Matches either var(x) or var(y).
@@ -797,7 +1132,7 @@ Match anything that matches the pattern var(x) but does not match var(y).
 This has lower precedence than any operator except `tt(|)', so
 `tt(*/*~foo/bar)' will search for all files in all directories in `tt(.)'
 and then exclude `tt(foo/bar)' if there was such a match.
-It groups left-to-right, so multiple patterns can be excluded by
+Multiple patterns can be excluded by
 `var(foo)tt(~)var(bar)tt(~)var(baz)'.
 In the exclusion pattern (var(y)), `tt(/)' and `tt(.)' are not treated
 specially the way they usually are in globbing.
@@ -806,13 +1141,19 @@ item(var(x)tt(#))(
 (Requires tt(EXTENDED_GLOB) to be set.)
 Matches zero or more occurrences of the pattern var(x).
 This operator has high precedence; `tt(12#)' is equivalent to `tt(1(2#))',
-rather than `tt((12)#)'.
+rather than `tt((12)#)'.  It is an error for an unquoted `tt(#)' to follow
+something which cannot be repeated; this includes an empty string, a
+pattern already followed by `tt(##)', or parentheses when part of a
+tt(KSH_GLOB) pattern (for example, `tt(!LPAR())var(foo)tt(RPAR()#)' is
+invalid and must be replaced by
+`tt(*LPAR()!LPAR())var(foo)tt(RPAR()RPAR())').
 )
 item(var(x)tt(##))(
 (Requires tt(EXTENDED_GLOB) to be set.)
 Matches one or more occurrences of the pattern var(x).
 This operator has high precedence; `tt(12##)' is equivalent to `tt(1(2##))',
-rather than `tt((12)##)'.
+rather than `tt((12)##)'.  No more than two active `tt(#)' characters may
+appear together.
 )
 enditem()
 subsect(ksh-like Glob Operators)
@@ -840,21 +1181,221 @@ Match anything but the expression in parentheses.
 (Like `tt(LPAR()^LPAR())...tt(RPAR()RPAR())'.)
 )
 enditem()
+subsect(Precedence)
+cindex(precedence of glob operators)
+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(])',
+`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
+than filename generation (for example, in tt(case) statements and tests
+within `tt([[)...tt(]])'), a `tt(/)' is not special; and `tt(/)' is also
+not special after a `tt(~)' appearing outside parentheses in a filename
+pattern.
+subsect(Globbing Flags)
+There are various flags which affect any text to their right up to the
+end of the enclosing group or to the end of the pattern; they require
+the tt(EXTENDED_GLOB) option. All take the form
+tt(LPAR()#)var(X)tt(RPAR()) where var(X) may have one of the following
+forms:
+
+startitem()
+item(i)(
+Case insensitive:  upper or lower case characters in the pattern match
+upper or lower case characters.
+)
+item(l)(
+Lower case characters in the pattern match upper or lower case
+characters; upper case characters in the pattern still only match
+upper case characters.
+)
+item(I)(
+Case sensitive:  locally negates the effect of tt(i) or tt(l) from
+that point on.
+)
+item(b)(
+Activate backreferences for parenthesised groups in the pattern;
+this does not work in filename generation.  When a pattern with a set of
+active parentheses is matched, the strings matched by the groups are
+stored in the array tt($match), the indices of the beginning of the matched
+parentheses in the array tt($mbegin), and the indices of the end in the array
+tt($mend), with the first element of each array corresponding to the first
+parenthesised group, and so on.  These arrays are not otherwise special to
+the shell.  The indices use the same convention as does parameter
+substitution, so that elements of tt($mend) and tt($mbegin) may be used in
+subscripts; the tt(KSH_ARRAYS) option is respected.  Sets of globbing flags
+are not considered parenthesised groups; only the first nine active
+parentheses can be referenced.
+
+For example,
+
+example(foo="a string with a message"
+if [[ $foo = (a|an)' '(#b)(*)' '* ]]; then
+  print ${foo[$mbegin[1],$mend[1]]}
+fi)
+
+prints `tt(string with a)'.  Note that the first parenthesis is before the
+tt((#b)) and does not create a backreference.
+
+Backreferences work with all forms of pattern matching other than filename
+generation, but note that when performing matches on an entire array, such
+as tt(${)var(array)tt(#)var(pattern)tt(}), or a global substitution, such
+as tt(${)var(param)tt(//)var(pat)tt(/)var(repl)tt(}), only the data for the
+last match remains available.  In the case of global replacements this may
+still be useful.  See the example for the tt(m) flag below.
+
+The numbering of backreferences strictly follows the order of the opening
+parentheses from left to right in the pattern string, although sets of
+parentheses may be nested.  There are special rules for parentheses followed
+by `tt(#)' or `tt(##)'.  Only the last match of the parenthesis is
+remembered: for example, in `tt([[ abab = (#b)([ab])# ]])', only the final
+`tt(b)' is stored in tt(match[1]).  Thus extra parentheses may be necessary
+to match the complete segment: for example, use `tt(X((ab|cd)#)Y)' to match
+a whole string of either `tt(ab)' or `tt(cd)' between `tt(X)' and `tt(Y)',
+using the value of tt($match[1]) rather than tt($match[2]).
+
+If the match fails none of the parameters is altered, so in some cases it
+may be necessary to initialise them beforehand.  If some of the
+backreferences fail to match --- which happens if they are in an alternate
+branch which fails to match, or if they are followed by tt(#) and matched
+zero times --- then the matched string is set to the empty string, and the
+start and end indices are set to -1.
+
+Pattern matching with backreferences is slightly slower than without.
+)
+item(B)(
+Deactivate backreferences, negating the effect of the tt(b) flag from that
+point on.
+)
+item(m)(
+Set references to the match data for the entire string matched; this is
+similar to backreferencing and does not work in filename generation.  The
+flag must be in effect at the end of the pattern, i.e. not local to a
+group. The parameters tt($MATCH),  tt($MBEGIN) and tt($MEND) will be set to
+the string matched and to the indices of the beginning and end of the
+string, respectively.  This is most useful in parameter substitutions, as
+otherwise the string matched is obvious.
+
+For example,
+
+example(arr=(veldt jynx grimps waqf zho buck)
+print ${arr//(#m)[aeiou]/${(U)MATCH}})
+
+forces all the matches (i.e. all vowels) into uppercase, printing
+`tt(vEldt jynx grImps wAqf zhO bUck)'.
+
+Unlike backreferences, there is no speed penalty for using match
+references, other than the extra substitutions required for the
+replacement strings in cases such as the example shown.
+)
+item(M)(
+Deactivate the tt(m) flag, hence no references to match data will be
+created.
+)
+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.
+)
+enditem()
+
+For example, the test string tt(fooxx) can be matched by the pattern
+tt(LPAR()#i)tt(RPAR()FOOXX), but not by tt(LPAR()#l)tt(RPAR()FOOXX),
+tt(LPAR()#i)tt(RPAR()FOO)tt(LPAR()#I)tt(RPAR()XX) or
+tt(LPAR()LPAR()#i)tt(RPAR()FOOX)tt(RPAR()X).  The string
+tt(LPAR()#ia2)tt(RPAR()readme) specifies case-insensitive matching of
+tt(readme) with up to two errors.
+
+When using the ksh syntax for grouping both tt(KSH_GLOB) and
+tt(EXTENDED_GLOB) must be set and the left parenthesis should be
+preceded by tt(@).  Note also that the flags do not affect letters
+inside tt([...]) groups, in other words tt(LPAR()#i)tt(RPAR()[a-z])
+still matches only lowercase letters.  Finally, note that when
+examining whole paths case-insensitively every directory must be
+searched for all files which match, so that a pattern of the form
+tt(LPAR()#i)tt(RPAR()/foo/bar/...) is potentially slow.
+
+subsect(Approximate Matching)
+When matching approximately, the shell keeps a count of the errors found,
+which cannot exceed the number specified in the
+tt(LPAR()#a)var(num)tt(RPAR()) flags.  Four types of error are recognised:
+
+startitem()
+item(1.)(
+Different characters, as in tt(fooxbar) and tt(fooybar).
+)
+item(2.)(
+Transposition of characters, as in tt(banana) and tt(abnana).
+)
+item(3.)(
+A character missing in the target string, as with the pattern tt(road) and
+target string tt(rod).
+)
+item(4.)(
+An extra character appearing in the target string, as with tt(stove)
+and tt(strove).
+)
+enditem()
+
+Thus, the pattern tt(LPAR()#a3)tt(RPAR()abcd) matches tt(dcba), with the
+errors occurring by using the first rule twice and the second once,
+grouping the string as tt([d][cb][a]) and tt([a][bc][d]).
+
+Non-literal parts of the pattern must match exactly, including characters
+in character ranges: hence tt(LPAR()#a1)tt(RPAR()???)  matches strings of
+length four, by applying rule 4 to an empty part of the pattern, but not
+strings of length two, since all the tt(?) must match.  Other characters
+which must match exactly are initial dots in filenames (unless the
+tt(GLOB_DOTS) option is set), and all slashes in filenames, so that
+tt(a/bc) is two errors from tt(ab/c) (the slash cannot be transposed with
+another character).  Similarly, errors are counted separately for
+non-contiguous strings in the pattern, so that tt(LPAR()ab|cd)tt(RPAR()ef)
+is two errors from tt(aebf).
+
+When using exclusion via the tt(~) operator, approximate matching is
+treated entirely separately for the excluded part and must be activated
+separately.  Thus, tt(LPAR()#a1)tt(RPAR()README~READ_ME) matches
+tt(READ.ME) but not tt(READ_ME), as the trailing tt(READ_ME) is matched
+without approximation.  However,
+tt(LPAR()#a1)tt(RPAR()README~LPAR()#a1)tt(RPAR()READ_ME)
+does not match any pattern of the form tt(READ)var(?)tt(ME) as all
+such forms are now excluded.
+
+Apart from exclusions, there is only one overall error count; however, the
+maximum errors allowed may be altered locally, and this can be delimited by
+grouping.  For example,
+tt(LPAR()#a1)tt(RPAR()cat)tt(LPAR()LPAR()#a0)tt(RPAR()dog)tt(RPAR()fox)
+allows one error in total, which may not occur in the tt(dog) section, and
+the pattern
+tt(LPAR()#a1)tt(RPAR()cat)tt(LPAR()#a0)tt(RPAR()dog)tt(LPAR()#a1)tt(RPAR()fox)
+is equivalent.  Note that the point at which an error is first found is the
+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.
+
 subsect(Recursive Globbing)
 A pathname component of the form `tt(LPAR())var(foo)tt(/RPAR()#)'
 matches a path consisting of zero or more directories
 matching the pattern var(foo).
-As a shorthand, `tt(**/)' is equivalent to `tt((*/)#)'.
+
+As a shorthand, `tt(**/)' is equivalent to `tt((*/)#)'; note that this
+therefore matches files in the current directory as well as
+subdirectories.
 Thus:
 
-nofill(tt(ls (*/)#bar))
+example(ls (*/)#bar)
 
 or
 
-nofill(tt(ls **/bar))
+example(ls **/bar)
 
-does a recursive directory search for files named `tt(bar)', not following
-symbolic links.  To follow links, use `tt(***/)'.
+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.
 subsect(Glob Qualifiers)
 cindex(globbing, qualifiers)
 cindex(qualifiers, globbing)
@@ -937,6 +1478,67 @@ setgid files (02000)
 item(tt(t))(
 files with the sticky bit (01000)
 )
+item(tt(f)var(spec))(
+files with access rights matching var(spec). This var(spec) may be a
+octal number optionally preceded by a `tt(=)', a `tt(PLUS())', or a
+`tt(-)'. If none of these characters is given, the behavior is the
+same as for `tt(=)'. The octal number describes the mode bits to be
+expected, if combined with a `tt(=)', the value given must match the
+file-modes exactly, with a `tt(PLUS())', at least the bits in the
+given number must be set in the file-modes, and with a `tt(-)', the
+bits in the number must not be set. Giving a `tt(?)' instead of a
+octal digit anywhere in the number ensures that the corresponding bits 
+in the file-modes are not checked, this is only useful in combination
+with `tt(=)'.
+
+If the qualifier `tt(f)' is followed by any other character anything
+up to the next matching character (`tt([)', `tt({)', and `tt(<)' match 
+`tt(])', `tt(})', and `tt(>)' respectively, any other character
+matches itself) is taken as a list of comma-separated
+var(sub-spec)s. Each var(sub-spec) may be either a octal number as
+described above or a list of any of the characters `tt(u)', `tt(g)',
+`tt(o)', and `tt(a)', followed by a `tt(=)', a `tt(PLUS())', or a
+`tt(-)', followed by a list of any of the characters `tt(r)', `tt(w)', 
+`tt(x)', `tt(s)', and `tt(t)', or a octal digit. The first list of
+characters specify which access rights are to be checked. If a `tt(u)'
+is given, those for the owner of the file are used, if a `tt(g)' is
+given, those of the group are checked, a `tt(o)' means to test those
+of other users, and the `tt(a)' says to test all three groups. The
+`tt(=)', `tt(PLUS())', and `tt(-)' again says how the modes are to be
+checked and have the same meaning as described for the first form
+above. The second list of characters finally says which access rights
+are to be expected: `tt(r)' for read access, `tt(w)' for write access, 
+`tt(x)' for the right to execute the file (or to search a directory),
+`tt(s)' for the setuid and setgid bits, and `tt(t)' for the sticky
+bit.
+
+Thus, `tt(*(f70?))' gives the files for which the owner has read,
+write, and execute permission, and for which other group members have
+no rights, independent of the permissions for other users. The pattern
+`tt(*(f-100))' gives all files for which the owner does not have
+execute permission, and `tt(*(f:gu+w,o-rx:))' gives the files for which 
+the owner and the other members of the group have at least write
+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.
+)
 item(tt(d)var(dev))(
 files on the device var(dev)
 )
@@ -954,8 +1556,8 @@ item(tt(u)var(id))(
 files owned by user ID var(id) if it is a number, if not, than the
 character after the `tt(u)' will be used as a separator and the string
 between it and the next matching separator
-(`tt(LPAR())', `tt([)', `tt({)', and `tt(<)'
-match `tt(RPAR())', `tt(])', `tt(})', and `tt(>)' respectively,
+(`tt([)', `tt({)', and `tt(<)'
+match `tt(])', `tt(})', and `tt(>)' respectively,
 any other character matches
 itself) will be taken as a user name, and the user ID of this user will
 be taken (e.g. `tt(u:foo:)' or `tt(u[foo])' for user `tt(foo)')
@@ -963,21 +1565,21 @@ be taken (e.g. `tt(u:foo:)' or `tt(u[foo])' for user `tt(foo)')
 item(tt(g)var(id))(
 like tt(u)var(id) but with group IDs or names
 )
-item(tt(a)[tt(Mwhm)][tt(-)|tt(PLUS())]var(n))(
-files accessed exactly var(n) days ago.  Files accessed within the
-last var(n) days are selected using a negative value for var(n)
-(tt(-)var(n)).  Files accessed more than var(n) days ago are selected by a
-positive var(n) value (tt(PLUS())var(n)).  Optional unit specifiers `tt(M)',
-`tt(w)', `tt(h)' or `tt(m)' (e.g. `tt(ah5)') cause the check to be
-performed with months (of 30 days), weeks, hours, or minutes instead of
-days, respectively.  For instance, `tt(echo *(ah-5))' would echo files
-accessed within the last five hours.
-)
-item(tt(m)[tt(Mwhm)][tt(-)|tt(PLUS())]var(n))(
+item(tt(a)[tt(Mwhms)][tt(-)|tt(PLUS())]var(n))(
+files accessed exactly var(n) days ago.  Files accessed within the last
+var(n) days are selected using a negative value for var(n) (tt(-)var(n)).
+Files accessed more than var(n) days ago are selected by a positive var(n)
+value (tt(PLUS())var(n)).  Optional unit specifiers `tt(M)', `tt(w)',
+`tt(h)', `tt(m)' or `tt(s)' (e.g. `tt(ah5)') cause the check to be
+performed with months (of 30 days), weeks, hours, minutes or seconds
+instead of days, respectively.  For instance, `tt(echo *(ah-5))' would
+echo files accessed within the last five hours.
+)
+item(tt(m)[tt(Mwhms)][tt(-)|tt(PLUS())]var(n))(
 like the file access qualifier, except that it uses the file modification
 time.
 )
-item(tt(c)[tt(Mwhm)][tt(-)|tt(PLUS())]var(n))(
+item(tt(c)[tt(Mwhms)][tt(-)|tt(PLUS())]var(n))(
 like the file access qualifier, except that it uses the file inode change
 time.
 )
@@ -1000,7 +1602,7 @@ sets the tt(MARK_DIRS) option for the current pattern
 pindex(MARK_DIRS, setting in pattern)
 )
 item(tt(T))(
-appends a trailing qualifier mark to the file names, analogous to the
+appends a trailing qualifier mark to the filenames, analogous to the
 tt(LIST_TYPES) option, for the current pattern (overrides tt(M))
 )
 item(tt(N))(
@@ -1011,6 +1613,34 @@ item(tt(D))(
 sets the tt(GLOB_DOTS) option for the current pattern
 pindex(GLOB_DOTS, setting in pattern)
 )
+item(tt(n))(
+sets the tt(NUMERIC_GLOB_SORT) option for the current pattern
+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)
+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.
+)
+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))'
+)
+item(tt([)var(beg)[tt(,)var(end)]tt(]))(
+specifies which of the matched filenames should be included in the
+returned list. The syntax is the same as for array
+subscripts. var(beg) and the optional var(end) may be mathematical
+expressions. As in parameter subscripting they may be negative to make 
+them count from the last match backward. E.g.: `tt(*(-OL[1,3]))'
+gives a list of the names of the three largest files.
+)
 enditem()
 
 More than one of these lists can be combined, separated by commas. The
@@ -1026,26 +1656,26 @@ name of any existing file can be followed by a modifier of the form
 `tt((:..))' even if no actual filename generation is performed.
 Thus:
 
-nofill(tt(ls *(-/)))
+example(ls *(-/))
 
 lists all directories and symbolic links that point to directories,
 and
 
-nofill(tt(ls *(%W)))
+example(ls *(%W))
 
 lists all world-writable device files in the current directory, and
 
-nofill(tt(ls *(W,X)))
+example(ls *(W,X))
 
 lists all files in the current directory that are
 world-writable or world-executable, and
 
-nofill(tt(echo /tmp/foo*(u0^@:t)))
+example(echo /tmp/foo*(u0^@:t))
 
 outputs the basename of all root-owned files beginning with the string
 `tt(foo)' in tt(/tmp), ignoring symlinks, and
 
-nofill(tt(ls *.*~(lex|parse).[ch](^D^l1)))
+example(ls *.*~(lex|parse).[ch](^D^l1))
 
 lists all files having a link count of one whose names contain a dot
 (but not those starting with a dot, since tt(GLOB_DOTS) is explicitly
diff --git a/Doc/Zsh/filelist.yo b/Doc/Zsh/filelist.yo
index 298eff074..f6e3d9dda 100644
--- a/Doc/Zsh/filelist.yo
+++ b/Doc/Zsh/filelist.yo
@@ -11,5 +11,5 @@ list(tt(/etc/zshenv))
 list(tt(/etc/zprofile))
 list(tt(/etc/zshrc))
 list(tt(/etc/zlogin))
-list(tt(/etc/zlogout)   (installation-specific - tt(/etc) is the default))
+list(tt(/etc/zlogout)    (installation-specific - tt(/etc) is the default))
 endlist()
diff --git a/Doc/Zsh/files.yo b/Doc/Zsh/files.yo
index 0d775a14f..aeb4ae885 100644
--- a/Doc/Zsh/files.yo
+++ b/Doc/Zsh/files.yo
@@ -6,12 +6,17 @@ cindex(startup files)
 cindex(files, shutdown)
 cindex(shutdown files)
 pindex(NO_RCS, use of)
-Commands are first read from tt(/etc/zshenv).
-If the tt(RCS) option is unset
-within tt(/etc/zshenv), all other
-initialization files are skipped.
-Otherwise, commands are read
-from tt($ZDOTDIR/.zshenv).
+pindex(NO_GLOBAL_RCS, use of)
+Commands are first read from tt(/etc/zshenv); this cannot be overridden.
+Subsequent behaviour is modified by the tt(RCS) and
+tt(GLOBAL_RCS) options; the former affects all startup files, while the
+second only affects those in the tt(/etc) directory.  If one of the options
+is unset at any point, any subsequent startup file(s) of the corresponding
+type will not be read.  It is also possible for a file in tt($ZDOTDIR) to
+re-enable tt(GLOBAL_RCS). Both tt(RCS) and tt(GLOBAL_RCS) are set by
+default.
+
+Commands are then read from tt($ZDOTDIR/.zshenv).
 pindex(LOGIN, use of)
 If the shell is a login shell, commands
 are read from tt(/etc/zprofile) and then tt($ZDOTDIR/.zprofile).
@@ -20,7 +25,35 @@ commands are read from tt(/etc/zshrc) and then tt($ZDOTDIR/.zshrc).
 Finally, if the shell is a login shell, tt(/etc/zlogin) and
 tt($ZDOTDIR/.zlogin) are read.
 
+When a login shell exits, the files tt($ZDOTDIR/.zlogout) and then
+tt(/etc/zlogout) are read.  This happens with either an explicit exit
+via the tt(exit) or tt(logout) commands, or an implicit exit by reading
+end-of-file from the terminal.  However, if the shell terminates due
+to tt(exec)'ing another process, the logout files are not read.
+These are also affected by the tt(RCS) and tt(GLOBAL_RCS) options.
+Note also that the tt(RCS) option affects the saving of history files,
+i.e. if tt(RCS) is unset when the shell exits, no history file will be
+saved.
+
 If tt(ZDOTDIR) is unset, tt(HOME) is used instead.
 Those files listed above as being in tt(/etc) may be in another
 directory, depending on the installation.
+
+As tt(/etc/zshenv) is run for all instances of zsh, it is important that
+it be kept as small as possible.  In particular, it is a good idea to
+put code that does not need to be run for every single shell behind
+a test of the form `tt(if [[ -o rcs ]]; then ...)' so that it will not
+be executed when zsh is invoked with the `tt(-f)' option.
 ifnzman(includefile(Zsh/filelist.yo))

+
+Any of these files may be pre-compiled with the tt(zcompile) builtin
+command (\
+ifzman(\
+see zmanref(zshbuiltins)\
+)\
+ifnzman(\
+noderef(Shell Builtin Commands)\
+)\
+).  If a compiled file exists (named for the original file plus the
+tt(.zwc) extension) and it is newer than the original file, the compiled
+file will be used instead.
diff --git a/Doc/Zsh/index.yo b/Doc/Zsh/index.yo
index 7afa14d07..99cf8558b 100644
--- a/Doc/Zsh/index.yo
+++ b/Doc/Zsh/index.yo
@@ -16,9 +16,9 @@ printindex(Options Index)(pg)
 texinode(Functions Index)(Editor Functions Index)(Options Index)(Top)
 printindex(Functions Index)(fn)
 
-texinode(Editor Functions Index)(Keystroke Index)(Functions Index)(Top)
+texinode(Editor Functions Index)(Style and Tag Index)(Functions Index)(Top)
 printindex(Editor Functions Index)(tp)
 
-texinode(Keystroke Index)()(Editor Functions Index)(Top)
-printindex(Keystroke Index)(ky)
+texinode(Style and Tag Index)()(Editor Functions Index)(Top)
+printindex(Style and Tag Index)(ky)
 )\
diff --git a/Doc/Zsh/manual.yo b/Doc/Zsh/manual.yo
index c4691b89d..a19161038 100644
--- a/Doc/Zsh/manual.yo
+++ b/Doc/Zsh/manual.yo
@@ -28,10 +28,10 @@ menu(Parameters)
 menu(Options)
 menu(Shell Builtin Commands)
 menu(Zsh Line Editor)
-menu(Programmable Completion Using compctl)
+menu(Completion Using compctl)
 menu(Completion Widgets)
-menu(Zsh Modules)
 menu(Completion System)
+menu(Zsh Modules)
 menu(Zftp Function System)
 
  --- Indices ---
@@ -41,7 +41,7 @@ menu(Variables Index)
 menu(Options Index)
 menu(Functions Index)
 menu(Editor Functions Index)
-menu(Keystroke Index)
+menu(Style and Tag Index)
 
  --- The Detailed Node Listing ---
 
@@ -98,7 +98,7 @@ menu(Arguments)
 menu(Completion)
 menu(Miscellaneous)
 
-Programmable Completion Using compctl
+Completion Using compctl
 
 menu(Command Flags)
 menu(Option Flags)
@@ -113,23 +113,18 @@ menu(Builtin Commands)
 menu(Condition Codes)
 menu(Examples)
 
+Completion System
+
+menu(Initialization)
+menu(Completion System Configuration)
+menu(Control Functions)
+menu(Bindable Commands)
+menu(Completion Functions)
+menu(Completion Directories)
+
 Zsh Modules
 
-menu(The cap Module)
-menu(The clone Module)
-menu(The comp1 Module)
-menu(The compctl Module)
-menu(The complist Module)
-menu(The deltochar Module)
-menu(The example Module)
-menu(The files Module)
-menu(The mapfile Module)
-menu(The mathfunc Module)
-menu(The parameter Module)
-menu(The sched Module)
-menu(The stat Module)
-menu(The zftp Module)
-menu(The zle Module)
+includefile(Zsh/manmodmenu.yo)

 endmenu()
 texinode(The Z Shell Manual)(Introduction)(Top)(Top)
 chapter(The Z Shell Manual)
diff --git a/Doc/Zsh/mod_compctl.yo b/Doc/Zsh/mod_compctl.yo
index b7adf8fa6..c4a254bb0 100644
--- a/Doc/Zsh/mod_compctl.yo
+++ b/Doc/Zsh/mod_compctl.yo
@@ -1,7 +1,13 @@
-texinode(The compctl Module)(The deltochar Module)(The comp1 Module)(Zsh Modules)
-sect(The compctl Module)
-The tt(compctl) module makes available one builtin command, tt(compctl),
-which is the standard way to control completions for ZLE.  See
+COMMENT(!MOD!zsh/compctl
+The tt(compctl) builtin for controlling completion.
+!MOD!)
+The tt(zsh/compctl) module makes available two builtin commands. tt(compctl),
+is the old, deprecated way to control completions for ZLE.  See
 ifzman(zmanref(zshcompctl))\
-ifnzman(noderef(Programmable Completion))\
+ifnzman(noderef(Completion Using compctl))\
+.
+The other builtin command, tt(compcall) can be used in user-defined
+completion widgets, see
+ifzman(zmanref(zshcompwid))\
+ifnzman(noderef(Completion Widgets))\
 .
diff --git a/Doc/Zsh/mod_zle.yo b/Doc/Zsh/mod_zle.yo
index 9aa03f7f8..a677ad0b1 100644
--- a/Doc/Zsh/mod_zle.yo
+++ b/Doc/Zsh/mod_zle.yo
@@ -1,6 +1,7 @@
-texinode(The zle Module)()(The stat Module)(Zsh Modules)
-sect(The zle Module)
-The tt(zle) module contains the Zsh Line Editor.  See
+COMMENT(!MOD!zsh/zle
+The Zsh Line Editor, including the tt(bindkey) and tt(vared) builtins.
+!MOD!)
+The tt(zsh/zle) module contains the Zsh Line Editor.  See
 ifzman(zmanref(zshzle))\
 ifnzman(noderef(Zsh Line Editor))\
 .  It also contains three related builtin commands:
@@ -41,15 +42,14 @@ and does not otherwise count as an argument.
 )
 enditem()
 
-Some operations do not permit a keymap to be selected.
 If a keymap selection is required and none of the options above are used, the
-`tt(main)' keymap is used.  These operations do not permit a keymap to be
-selected:
+`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 used, list in the form of tt(bindkey)
+option is also used, list in the form of tt(bindkey)
 commands to create the keymaps.
 )
 item(tt(-d))(
@@ -67,12 +67,24 @@ 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 initialised to be a duplicate of it, otherwise the new keymap will
+is initialized to be a duplicate of it, otherwise the new keymap will
 be empty.
 )
 enditem()
 
-The following operations require a keymap to be selected:
+To use a newly created keymamp, 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))(
@@ -82,29 +94,34 @@ 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.
 )
 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 an exception,
-if the tt(-e) or tt(-v) options are used alone, the keymap is em(not)
-displayed - the implicit linking of keymaps is the only thing that happens.
+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 tt(-L) option is used, the list is in the form of tt(bindkey)
+commands to create the key bindings.
 )
 enditem()
 
-In the binding operations, if the tt(-R) option is used, the var(in-string)s
-are interpreted as ranges, instead of plain strings.  A valid range
-consists of two characters, with an optional `tt(-)'
-between them.  All characters between the two specified, inclusive,
-are bound as specified.
+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:
@@ -126,21 +143,34 @@ 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.
+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(-ch) ] [ tt(-p) var(prompt) ] [ tt(-r) var(rprompt) ] var(name))(
+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.
-If the tt(-c) flag is given, the parameter is created if it doesn't
-already exist.
+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.
+
+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.
+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 immediatly with a non-zero return value.
 )
 findex(zle)
 cindex(widgets, rebinding)
@@ -153,11 +183,16 @@ cindex(widgets, calling)
 cindex(calling widgets)
 cindex(widgets, defining)
 cindex(defining widgets)
-xitem(tt(zle) tt(-l) [ tt(-L) ])
+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) ])
-item(tt(zle) var(widget))(
+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) 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:
 
@@ -166,7 +201,15 @@ item(tt(-l) [ tt(-L) ])(
 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.
-Built-in widgets are not listed.
+
+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.
@@ -182,12 +225,86 @@ 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.
+the same name as the widget.  For further information, see the section
+em(Widgets) in
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor))\
+.
+)
+citem(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(var(widget))(
+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
+immediatly after using it because the strings displayed will be erased 
+immediatly after return from the widget.
+)
+item(tt(-M) var(string))(
+As with the tt(-R) option, the var(string) will be displayed below the 
+command line. But unlike the tt(-R) option the string 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.
+
+Note that since ZLE uses a stack, using tt(zle) with this option more
+than once will make the last string pushed be used first. The
+characters in each var(string) will be used in the order in which they
+appear in the string, though.
+)
+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 returns 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()
diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
index 477f955eb..891ebef11 100644
--- a/Doc/Zsh/mod_zutil.yo
+++ b/Doc/Zsh/mod_zutil.yo
@@ -1,9 +1,12 @@
-texinode(The zutil Module)(The complete Module)(The clone Module)(Zsh Modules)
-sect(The zutil Module)
+COMMENT(!MOD!zsh/zutil
+Some utility builtins, e.g. the one for supporting configuration via 
+styles.
+!MOD!)
 cindex(builtins, utility)
-The tt(zutil) module only adds some builtins:
+The tt(zsh/zutil) module only adds some builtins:
 
 startitem()
+findex(zstyle)
 xitem(tt(zstyle) [ tt(-L) ])
 xitem(tt(zstyle) [ tt(-) | tt(-)tt(-) ] var(pattern) var(style) var(strings) ...)
 xitem(tt(zstyle -d) [ var(pattern) [ var(styles) ... ] ])
@@ -13,6 +16,7 @@ xitem(tt(zstyle -b) var(context) var(style) var(name))
 xitem(tt(zstyle -a) var(context) var(style) var(name))
 xitem(tt(zstyle -h) var(context) var(style) var(name))
 xitem(tt(zstyle -t) var(context) var(style) [ var(strings) ...])
+xitem(tt(zstyle -T) var(context) var(style) [ var(strings) ...])
 item(tt(zstyle -m) var(context) var(style) var(pattern))(
 This builtin command is used to define and lookup styles. Styles are
 pairs of names and values, where the values consist of any number of
@@ -61,17 +65,22 @@ makes it be returned as an associative array (with the first, third,
 etc. string being used as the keys and the other strings being used as 
 the values).
 
-The tt(-t) option can be used to test the value of a style, i.e. it
+The tt(-t) options can be used to test the value of a style, i.e. it
 only sets the return value. Without any var(strings) arguments it is
 zero if the style is defined for at least one matching pattern, has
 only one string in its value and that is equal to one of tt(true),
 tt(yes), tt(on) or tt(1). If any var(strings) are given the return
 zero if and only if at least one of the var(strings) is equal to at
-least one of the strings in the value.
+least one of the strings in the value. If the style is not defined,
+the return value is tt(2).
+
+The tt(-T) option is like tt(-t) but returns zero if the style is not
+set for any matching pattern.
 
 The tt(-m) option can be used to match a value. It returns zero if the 
 var(pattern) matches at least one of the strings in the value.
 )
+findex(zformat)
 xitem(tt(zformat -f) var(param) var(format) var(specs) ...)
 item(tt(zformat -a) var(array) var(sep) var(specs) ...)(
 This builtin provides to different forms of formatting. The first form 
@@ -106,4 +115,52 @@ trailing colon removed. In both cases the lengths of the strings
 are not used to determine how the other strings have to be aligned.
 The resulting strings are stored in the var(array).
 )
+findex(zregexparse)
+item(tt(zregexparse))(
+This implements the internals of the `tt(_regex_arguments)'.
+)
+findex(zparseopts)
+item(tt(zparseopts) [ tt(-D) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] var(specs))(
+This builtin simplifies the parsing of options in the positional
+parameters. Each var(spec) describes one option and should be of the
+form `var(name)[tt(+)][tt(:)[tt(:)][tt(-)]][tt(=)var(array)]'. The var(name)
+is the name of the option (without the leading `tt(-)'). If only that
+is given, the option takes no argument and if it is found in the
+positional parameters it will be placed in the var(array) given with
+the tt(-a) option. If the optional `tt(=)var(array)' is given, it will 
+be put into that array instead. If one or two colons are given, the
+option takes an argument. With one colon, this argument is mandatory
+and with two colons it is optional. The argument will be inserted into 
+the var(array), too. For mandatory arguments it is added as a separate 
+string and for optional arguments it is put into one string together
+with the option name unless the `tt(-)' option is given. In this case
+the argument will be put into the same word even for mandatory
+arguments (note that this makes empty strings as arguments
+indistinguishable). Finally, if the `tt(+)' is given and the option
+appears more than once in the positional parameters, it will be
+inserted more than once in the var(array), too. Without the `tt(+)'
+the option will be inserted only once in the var(array) with arguments 
+of later options overwriting earlier once. If any of the special
+character needs to appear in the option name it must be preceded by a
+backslash.
+
+If the tt(-A) option is given, the options and their values will also
+be put into an associative array with the option names as keys and the 
+arguments (if any) as the values. Note that it is an error to give
+var(specs) without a `tt(=)var(array)' and not use either the tt(-a)
+or tt(-A) option.
+
+If the tt(-D) option is given, all options found are removed from the
+positional parameters leaving only the strings from the first one that 
+was not described by any of the var(specs) to the last (note that this 
+is the usual rule used by tt(zparseopts) to find out when to stop
+processing options).
+
+For example, calling `tt(zparseopts a=foo b:=bar c+:=bar)' with the
+strings `tt(-a)', `tt(-bx)', `tt(-c)', `tt(y)', `tt(-cz)', `tt(baz)'
+and `tt(-cend)' as positional arguments will set the array tt(foo) to
+contain the element `tt(-a)' and the array tt(bar) to the strings
+`tt(-b)', `tt(x)', `tt(-c)', `tt(y)', `tt(-c)', and `tt(z)'. The
+`tt(baz)' and all strings after it will not be used.
+)
 enditem()
diff --git a/Doc/Zsh/modules.yo b/Doc/Zsh/modules.yo
index b44b00e6b..e74a94aed 100644
--- a/Doc/Zsh/modules.yo
+++ b/Doc/Zsh/modules.yo
@@ -1,4 +1,4 @@
-texinode(Zsh Modules)()(Programmable Completion)(Top)
+texinode(Zsh Modules)(Zftp Function System)(Completion System)(Top)
 chapter(Zsh Modules)
 cindex(modules)
 sect(Description)
@@ -6,59 +6,7 @@ Some optional parts of zsh are in modules, separate from the core
 of the shell.  Each of these modules may be linked in to the
 shell at build time,
 or can be dynamically linked while the shell is running
-if the installation supports this feature.  The modules available are:
+if the installation supports this feature.  The modules that
+are bundled with the zsh distribution are:
 
-startitem()
-item(tt(cap))(
-Builtins for manipulating POSIX.1e (POSIX.6) capability (privilege) sets.
-)
-item(tt(clone))(
-A builtin that can clone a running shell onto another terminal.
-)
-item(tt(comp1))(
-Base of the completion system.  Used by the tt(compctl) and tt(zle) modules.
-)
-item(tt(compctl))(
-The tt(compctl) builtin for controlling completion.
-)
-item(tt(deltochar))(
-A ZLE function duplicating EMACS' tt(zap-to-char).
-)
-item(tt(example))(
-An example of how to write a module.
-)
-item(tt(files))(
-Some basic file manipulation commands as builtins.
-)
-item(tt(sched))(
-A builtin that provides a timed execution facility within the shell.
-)
-item(tt(stat))(
-A builtin command interface to the tt(stat) system call.
-)
-item(tt(zle))(
-The Zsh Line Editor, including the tt(bindkey) and tt(vared) builtins.
-)
-enditem()
-startmenu()
-menu(The cap Module)
-menu(The clone Module)
-menu(The comp1 Module)
-menu(The compctl Module)
-menu(The deltochar Module)
-menu(The example Module)
-menu(The files Module)
-menu(The sched Module)
-menu(The stat Module)
-menu(The zle Module)
-endmenu()
-includefile(Zsh/mod_cap.yo)

-includefile(Zsh/mod_clone.yo)

-includefile(Zsh/mod_comp1.yo)

-includefile(Zsh/mod_compctl.yo)

-includefile(Zsh/mod_deltochar.yo)

-includefile(Zsh/mod_example.yo)

-includefile(Zsh/mod_files.yo)

-includefile(Zsh/mod_sched.yo)

-includefile(Zsh/mod_stat.yo)

-includefile(Zsh/mod_zle.yo)

+includefile(Zsh/modlist.yo)

diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index 4c25a18ef..c6571f38f 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -7,7 +7,8 @@ A name may be any sequence of alphanumeric
 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)
@@ -15,45 +16,41 @@ To assign an array value, use `tt(set -A) var(name) var(value) ...'.
 findex(set, use of)
 The value of a parameter may also be assigned by writing:
 
-nofill(var(name)tt(=)var(value))
+indent(var(name)tt(=)var(value))
 
-If the integer attribute, tt(-i), is set for var(name),
-the var(value) is subject to arithmetic evaluation.
+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.
+initializes in tt(sh) or tt(ksh) emulation mode.
 startmenu()
-menu(Local Parameters)
 menu(Array Parameters)
 menu(Positional Parameters)
+menu(Local Parameters)
 menu(Parameters Set By The Shell)
 menu(Parameters Used By The Shell)
 endmenu()
-texinode(Local Parameters)(Array Parameters)()(Parameters)
-sect(Local Parameters)
-Shell function executions delimit scopes for shell parameters.
-(Parameters are dynamically scoped.)  The tt(typeset) builtin, and its
-alternative forms tt(declare), tt(integer), tt(local) and tt(readonly)
-(but not tt(export)), can be used to declare a parameter as being local
-to the innermost scope.
-
-When a parameter is read or assigned to, the
-innermost existing parameter of that name is used.  (That is, the
-local parameter hides any less-local parameter.)  However, assigning
-to a non-existent parameter, or declaring a new parameter with tt(export),
-causes it to be created in the em(outer)most scope.
-
-Local parameters disappear when their scope ends.
-tt(unset) can be used to delete a parameter while it is still in scope; this
-will reveal the next outer parameter of the same name.  However, em(special)
-parameters are still special when unset.
-texinode(Array Parameters)(Positional Parameters)(Local Parameters)(Parameters)
+texinode(Array Parameters)(Positional Parameters)()(Parameters)
 sect(Array Parameters)
 The value of an array parameter may be assigned by writing:
 
-nofill(var(name)tt(=LPAR())var(value) ...tt(RPAR()))
+indent(var(name)tt(=LPAR())var(value) ...tt(RPAR()))
+
+If no parameter var(name) exists, an ordinary array parameter is created.
+Associative arrays must be declared first, by `tt(typeset -A) var(name)'.
+When var(name) refers to an associative array, the parenthesized list is
+interpreted as alternating keys and values:
+
+indent(var(name)tt(=LPAR())var(key) var(value) ...tt(RPAR()))
+
+Every var(key) must have a var(value) in this case.  To create an empty
+array or associative array, use:
+
+indent(var(name)tt(=LPAR()RPAR()))
 
 Individual elements of an array may be selected using a
 subscript.  A subscript of the form `tt([)var(exp)tt(])'
@@ -62,8 +59,12 @@ an arithmetic expression which will be subject to arithmetic
 expansion as if it were surrounded by `tt($LPAR()LPAR())...tt(RPAR()RPAR())'.
 The elements are numbered beginning with 1 unless the
 tt(KSH_ARRAYS) option is set when they are numbered from zero.
+cindex(subscripts)
 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.
@@ -72,8 +73,8 @@ except when they appear within double quotes.
 
 A subscript of the form `tt([)var(exp1)tt(,)var(exp2)tt(])'
 selects all elements in the range var(exp1) to var(exp2),
-inclusive.
-If one of the subscripts evaluates to a negative number,
+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
 from the end of the array tt(foo), and
@@ -90,22 +91,29 @@ option is set, the braced form is the only one that will
 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.  Arrays do not nest, so assigning a parenthesized list
+of values to an element or range changes the number of elements in the
+array, shifting the other elements to accommodate the new values.  (This
+is not supported for associative arrays.)
+
+To delete an element of an ordinary array, assign `tt(LPAR()RPAR())' to
+that element.
+To delete an element of an associative array, use the tt(unset) command.
 
 If the opening bracket or the comma is directly followed by an opening
 parentheses the string up to the matching closing one is considered to
 be a list of flags. The flags currently understood are:
 
 startitem()
-item(tt(e))(
-this option has no effect and retained for backward compatibility only.
-)
 item(tt(w))(
-if the parameter subscripted is a scalar than this flag makes
-subscription work on a per-word basis instead of characters.
+If the parameter subscripted is a scalar than this flag makes
+subscripting work on words instead of characters.  The default word
+separator is whitespace.
 )
 item(tt(s:)var(string)tt(:))(
-this gives the var(string) that separates words (for use with the
+This gives the var(string) that separates words (for use with the
 tt(w) flag).
 )
 item(tt(p))(
@@ -113,44 +121,117 @@ Recognize the same escape sequences as the tt(print) builtin in
 the string argument of a subsequent `tt(s)' flag.
 )
 item(tt(f))(
-if the parameter subscripted is a scalar than this flag makes
-subscription work on a per-line basis instead of characters.
-This is a shorthand for `tt(pws:\n:)'.
+If the parameter subscripted is a scalar than this flag makes
+subscripting work on lines instead of characters, i.e. with elements
+separated by newlines.  This is a shorthand for `tt(pws:\n:)'.
 )
 item(tt(r))(
-if this flag is given the var(exp) is taken as a pattern and the
-result is the first matching array element, substring or word (if the
-parameter is an array, if it is a scalar, or if it is a scalar and the
-`tt(w)' flag is given, respectively); note that this is like giving a
-number: `tt($foo[(r))var(??)tt(,3])' and `tt($foo[(r))var(??)tt(,(r)f*])' work.
+Reverse subscripting:  if this flag is given, the var(exp) is taken as a
+pattern and the  result is the first matching array element, substring or
+word (if the parameter is an array, if it is a scalar, or if it is a scalar
+and the `tt(w)' flag is given, respectively).  The subscript used is the
+number of the matching element, so that pairs of subscripts such as
+`tt($foo[(r))var(??)tt(,3])' and `tt($foo[(r))var(??)tt(,(r)f*])'
+are possible.  If the parameter is an associative array, only the value part
+of each pair is compared to the pattern.
 )
 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(k))(
+If used in a subscript on a parameter that is not an associative
+array, this behaves like `tt(r)', but if used on an association, it
+makes the keys be interpreted as patterns and returns the first value
+whose key matches the var(exp).
+)
+item(tt(K))(
+On an associtation this is like `tt(k)' but returns all values whose
+keys match the var(exp). On other types of parameters this has the
+same effect as `tt(R)'.
 )
 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.
+)
+item(tt(b:)var(expr)tt(:))(
+if combined with `tt(r)', `tt(R)', `tt(i)' or `tt(I)', makes them begin
+at the var(n)th or var(n)th last element, word, or character (if var(expr)
+evaluates to var(n)).  This flag is ignored when the array is associative.
+)
+item(tt(e))(
+This option has no effect and retained for backward compatibility only.
 )
 enditem()
-texinode(Positional Parameters)(Parameters Set By The Shell)(Array Parameters)(Parameters)
+texinode(Positional Parameters)(Local Parameters)(Array Parameters)(Parameters)
 sect(Positional Parameters)
-Positional parameters are set by the shell on invocation,
-by the tt(set) builtin, or by direct assignment.
+The positional parameters provide access to the command-line arguments
+of a shell function, shell script, or the shell itself; see
+noderef(Invocation), and also noderef(Functions).
 The parameter var(n), where var(n) is a number,
 is the var(n)th positional parameter.
 The parameters tt(*), tt(@) and tt(argv) are
 arrays containing all the positional parameters;
 thus `tt($argv[)var(n)tt(])', etc., is equivalent to simply `tt($)var(n)'.
 
-texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Positional Parameters)(Parameters)
+Positional parameters may be changed after the shell or function starts by
+using the tt(set) builtin, by assigning to the tt(argv) array, or by direct
+assignment of the form `var(n)tt(=)var(value)' where var(n) is the number of
+the positional parameter to be changed.  This also creates (with empty
+values) any of the positions from 1 to var(n) that do not already have
+values.  Note that, because the positional parameters form an array, an
+array assignment of the form `var(n)tt(=LPAR())var(value) ...tt(RPAR())' is
+allowed, and has the effect of shifting all the values at positions greater
+than var(n) by as many positions as necessary to accommodate the new values.
+
+texinode(Local Parameters)(Parameters Set By The Shell)(Positional Parameters)(Parameters)
+sect(Local Parameters)
+Shell function executions delimit scopes for shell parameters.
+(Parameters are dynamically scoped.)  The tt(typeset) builtin, and its
+alternative forms tt(declare), tt(integer), tt(local) and tt(readonly)
+(but not tt(export)), can be used to declare a parameter as being local
+to the innermost scope.
+
+When a parameter is read or assigned to, the
+innermost existing parameter of that name is used.  (That is, the
+local parameter hides any less-local parameter.)  However, assigning
+to a non-existent parameter, or declaring a new parameter with tt(export),
+causes it to be created in the em(outer)most scope.
+
+Local parameters disappear when their scope ends.
+tt(unset) can be used to delete a parameter while it is still in scope;
+any outer parameter of the same name remains hidden.
+
+Special parameters may also be made local; they retain their special
+attributes unless either the existing or the newly-created parameter
+has the tt(-h) (hide) attribute.  This may have unexpected effects.
+Firstly, there is no default value, so if there is no assigment at the
+point the variable is made local, it will be set to an empty value (or zero
+in the case of integers).  Secondly, special parameters which are made
+local will not be exported (as with other parameters), so that the global
+value of the parameter remains present in the environment if it is already
+there.  This should be particularly noted in the case of tt(PATH): the
+shell will use the local version of tt(PATH) for finding programmes, but
+programmes using the shell's environment will inherit the global version.
+The following:
+
+example(typeset PATH=/new/directory:$PATH)
+
+is valid for temporarily allowing the shell to find the programs in
+tt(/new/directory) inside a function.
+
+texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Local Parameters)(Parameters)
 sect(Parameters Set By The Shell)
 The following parameters are automatically set by the shell:
 
@@ -182,11 +263,15 @@ An array containing the positional parameters.
 )
 vindex(argv)
 item(tt(argv) <S> <Z>)(
-Same as tt(*).
+Same as tt(*).  Assigning to tt(argv) changes the local positional
+parameters, but tt(argv) is em(not) itself a local parameter.
+Deleting tt(argv) with tt(unset) in any function deletes it everywhere,
+although only the innermost positional parameter array is deleted (so
+tt(*) and tt(@) in other scopes are not affected).
 )
 vindex(@)
 item(tt(@) <S>)(
-Same as tt(argv[@]).
+Same as tt(argv[@]), even when tt(argv) is not set.
 )
 vindex(?)
 item(tt(?) <S>)(
@@ -202,12 +287,22 @@ vindex(status)
 item(tt(status) <S> <Z>)(
 Same as tt(?).
 )
+vindex(pipestatus)
+item(tt(pipestatus) <S> <Z>)(
+An array containing the exit values returned by all commands in the
+last pipeline.
+)
 vindex(_)
 item(tt(_) <S>)(
 The last argument of the previous command.
 Also, this parameter is set in the environment of every command
 executed to the full pathname of the command.
 )
+vindex(CPUTYPE)
+item(tt(CPUTYPE))(
+The machine type (microprocessor class or machine model),
+as determined at run time.
+)
 vindex(EGID)
 item(tt(EGID) <S>)(
 The effective group ID of the shell process.  If you have sufficient
@@ -245,8 +340,11 @@ The current hostname.
 )
 vindex(LINENO)
 item(tt(LINENO) <S>)(
-The line number of the current line within the current script
-being executed.
+The line number of the current line within the current script, sourced
+file, or shell function being executed, whichever was started most
+recently.  Note that in the case of shell functions the line
+number refers to the function as it appeared in the original definition,
+not necesarily as displayed by the tt(functions) builtin.
 )
 vindex(LOGNAME)
 item(tt(LOGNAME))(
@@ -262,7 +360,7 @@ as determined at compile time.
 )
 vindex(OLDPWD)
 item(tt(OLDPWD))(
-The previous working directory.  This is set when the shell initialises
+The previous working directory.  This is set when the shell initializes
 and whenever the directory changes.
 )
 vindex(OPTARG)
@@ -285,7 +383,7 @@ The process ID of the parent of the shell.
 )
 vindex(PWD)
 item(tt(PWD))(
-The present working directory.  This is set when the shell initialises
+The present working directory.  This is set when the shell initializes
 and whenever the directory changes.
 )
 vindex(RANDOM)
@@ -356,7 +454,7 @@ The following parameters are used by the shell:
 startitem()
 vindex(ARGV0)
 item(tt(ARGV0))(
-If exported, its value is used as tt(argv[0]) of external commands.
+If exported, its value is used as the tt(argv[0]) of external commands.
 Usually used in constructs like `tt(ARGV0=emacs nethack)'.
 )
 vindex(BAUD)
@@ -417,7 +515,7 @@ vindex(histchars)
 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(#)').
 )
@@ -432,7 +530,10 @@ If unset, the history is not saved.
 )
 vindex(HISTSIZE)
 item(tt(HISTSIZE) <S>)(
-The maximum size of the history list.
+The maximum number of events stored in the internal history list.
+If you use the tt(HIST_EXPIRE_DUPS_FIRST) option, setting this value
+larger than the tt(SAVEHIST) size will give you the difference as a
+cushion for saving duplicated history events.
 )
 vindex(HOME)
 item(tt(HOME) <S>)(
@@ -442,7 +543,7 @@ vindex(IFS)
 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
@@ -481,6 +582,13 @@ item(tt(LC_MESSAGES) <S>)(
 This variable determines the language in which messages should be
 written.  Note that zsh does not use message catalogs.
 )
+vindex(LC_NUMERIC)
+item(tt(LC_NUMERIC) <S>)(
+This variable affects the decimal point character and thousands
+separator character for the formatted input/output functions
+and string conversion functions.  Note that zsh ignores this
+setting when parsing floating point mathematical expressions.
+)
 vindex(LC_TIME)
 item(tt(LC_TIME) <S>)(
 This variable determines the locale category for date and time
@@ -493,7 +601,9 @@ Used for printing select lists and for the line editor.
 )
 vindex(LISTMAX)
 item(tt(LISTMAX))(
-In the line editor, the number of filenames to list without asking first.
+In the line editor, the number of matches to list without asking
+first. If the value is negative, the list will be shown if it spans at 
+most as many lines as given by the absolute value.
 If set to zero, the shell asks only if the top of the listing would scroll
 off the screen.
 )
@@ -518,7 +628,7 @@ An array (colon-separated list) of filenames to check for
 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
@@ -538,7 +648,7 @@ item(tt(module_path) <S> <Z> (tt(MODULE_PATH) <S>))(
 An array (colon-separated list)
 of directories that tt(zmodload)
 searches for dynamically loadable modules.
-This is initialised to a standard pathname,
+This is initialized to a standard pathname,
 usually `tt(/usr/local/lib/zsh/$ZSH_VERSION)'.
 (The `tt(/usr/local/lib)' part varies from installation to installation.)
 For security reasons, any value set in the environment when the shell
@@ -593,7 +703,9 @@ The default is `tt(?# )'.
 )
 vindex(PS4)
 item(tt(PS4) <S>)(
-The execution trace prompt.  Default is `tt(PLUS() )'.
+The execution trace prompt.  Default is `tt(PLUS()%N:%i> )', which displays
+the name of the current shell structure and the line number within it.
+In sh or ksh emulation, the default is `tt(PLUS() )'.
 )
 vindex(PROMPT)
 xitem(tt(PROMPT) <S> <Z>)
@@ -656,12 +768,12 @@ set up the terminal before executing the command. The modes apply only to the
 command, and are reset when it finishes or is suspended. If the command is
 suspended and continued later with the tt(fg) or tt(wait) builtins it will
 see the modes specified by tt(STTY), as if it were not suspended.  This
-(intentionally) does not apply if the command is continued via `tt(kill -CONT)'.
-tt(STTY) is ignored if the command is run in the background, or if it is in the
-environment of the shell but not explicitly assigned to in the input line. This
-avoids running stty at every external command by accidentally exporting it.
-Also note that tt(STTY) should not be used for window size specifications; these
-will not be local to the command.
+(intentionally) does not apply if the command is continued via `tt(kill
+-CONT)'.  tt(STTY) is ignored if the command is run in the background, or
+if it is in the environment of the shell but not explicitly assigned to in
+the input line. This avoids running stty at every external command by
+accidentally exporting it. Also note that tt(STTY) should not be used for
+window size specifications; these will not be local to the command.
 )
 vindex(TERM)
 item(tt(TERM) <S>)(
@@ -804,6 +916,19 @@ item(tt(WORDCHARS) <S>)(
 A list of non-alphanumeric characters considered part of a word
 by the line editor.
 )
+vindex(ZBEEP)
+item(tt(ZBEEP))(
+If set, this gives a string of characters, which can use all the same codes
+as the tt(bindkey) command as described in
+ifzman(the zsh/zle module entry in zmanref(zshmodules))\
+ifnzman(noderef(The zsh/zle Module))\
+, that will be output to the terminal
+instead of beeping.  This may have a visible instead of an audible effect;
+for example, the string `tt(\e[?5h\e[?5l)' on a vt100 or xterm will have
+the effect of flashing reverse video on and off (if you usually use reverse
+video, you should use the string `tt(\e[?5l\e[?5h)' instead).  This takes
+precedence over the tt(NOBEEP) option.
+)
 vindex(ZDOTDIR)
 item(tt(ZDOTDIR))(
 The directory to search for shell startup files (.zshrc, etc),
diff --git a/Doc/Zsh/redirect.yo b/Doc/Zsh/redirect.yo
index 8955e67ac..70085a5d2 100644
--- a/Doc/Zsh/redirect.yo
+++ b/Doc/Zsh/redirect.yo
@@ -16,7 +16,7 @@ input/output specifications.
 
 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 @@ exist, even if tt(CLOBBER) is unset.
 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.
@@ -77,10 +77,10 @@ item(tt(<<<) var(word))(
 Perform shell expansion on var(word) and pass the result
 to standard input.  This is known as a em(here-string).
 )
-xitem(tt(<&) var(digit))
-item(tt(>&) var(digit))(
+xitem(tt(<&) var(number))
+item(tt(>&) var(number))(
 The standard input/output is duplicated from file descriptor
-var(digit) (see manref(dup)(2)).
+var(number) (see manref(dup2)(2)).
 )
 xitem(tt(<& -))
 item(tt(>& -))(
@@ -90,11 +90,33 @@ xitem(tt(<& p))
 item(tt(>& p))(
 The input/output from/to the coprocess is moved to the standard input/output.
 )
-item(tt(>&) var(word))(
-Same as `tt(>) var(word) tt(2>&1)'.
+xitem(tt(>&) var(word))
+item(tt(&>) var(word))(
+(Except where `tt(>&) var(word)' matches one of the above syntaxes;
+`tt(&>)' can always be used to avoid this ambiguity.)
+Redirects both standard output and standard error (file descriptor 2)
+in the manner of `tt(>) var(word)'.
+Note that this does em(not) have the same effect as `tt(>) var(word) tt(2>&1)'
+in the presence of multios (see the section below).
 )
-item(tt(>>&) var(word))(
-Same as `tt(>>) var(word) tt(2>&1)'.
+xitem(tt(>&|) var(word))
+xitem(tt(>&!) var(word))
+xitem(tt(&>|) var(word))
+item(tt(&>!) var(word))(
+Redirects both standard output and standard error (file descriptor 2)
+in the manner of `tt(>|) var(word)'.
+)
+xitem(tt(>>&) var(word))
+item(tt(&>>) var(word))(
+Redirects both standard output and standard error (file descriptor 2)
+in the manner of `tt(>>) var(word)'.
+)
+xitem(tt(>>&|) var(word))
+xitem(tt(>>&!) var(word))
+xitem(tt(&>>|) var(word))
+item(tt(&>>!) var(word))(
+Redirects both standard output and standard error (file descriptor 2)
+in the manner of `tt(>>|) var(word)'.
 )
 enditem()
 
@@ -107,7 +129,7 @@ The shell evaluates each redirection in terms of the
 association at the time of evaluation.
 For example:
 
-nofill(... tt(1>)var(fname) tt(2>&1))
+indent(... tt(1>)var(fname) tt(2>&1))
 
 first associates file descriptor 1 with file var(fname).
 It then associates file descriptor 2 with the file associated with file
@@ -123,12 +145,12 @@ the shell opens the file descriptor as a pipe to a process that copies
 its input to all the specified outputs, similar to bf(tee),
 provided the tt(MULTIOS) option is set.  Thus:
 
-nofill(tt(date >foo >bar))
+example(date >foo >bar)
 
 writes the date to two files, named `tt(foo)' and `tt(bar)'.
 Note that a pipe is an implicit redirection; thus
 
-nofill(tt(date >foo | cat))
+example(date >foo | cat)
 
 writes the date to the file `tt(foo)', and also pipes it to cat.
 
@@ -136,14 +158,14 @@ If the tt(MULTIOS)
 option is set, the word after a redirection operator is also subjected
 to filename generation (globbing).  Thus
 
-nofill(tt(: > *))
+example(: > *)
 
 will truncate all files in the current directory,
 assuming there's at least one.  (Without the tt(MULTIOS)
 option, it would create an empty file called `tt(*)'.)
 Similarly, you can do
 
-nofill(tt(echo exit 0 >> *.sh))
+example(echo exit 0 >> *.sh)
 
 If the user tries to open a file descriptor for reading more than once,
 the shell opens the file descriptor as a pipe to a process that copies
@@ -151,17 +173,17 @@ all the specified inputs to its output in the order
 specified, similar to bf(cat),
 provided the tt(MULTIOS) option is set.  Thus
 
-nofill(tt(sort <foo <fubar))
+example(sort <foo <fubar)
 
 or even
 
-nofill(tt(sort <f{oo,ubar}))
+example(sort <f{oo,ubar})
 
 is equivalent to `tt(cat foo fubar | sort)'.
 
 Note that a pipe is an implicit redirection; thus
 
-nofill(tt(cat bar | sort <foo))
+example(cat bar | sort <foo)
 
 is equivalent to `tt(cat bar foo | sort)' (note the order of the inputs).
 
@@ -169,15 +191,35 @@ If the tt(MULTIOS) option is em(un)set,
 each redirection replaces the previous redirection for that file descriptor.
 However, all files redirected to are actually opened, so
 
-nofill(tt(echo foo > bar > baz))
+example(echo foo > bar > baz)
 
 when tt(MULTIOS) is unset will truncate bar, and write `tt(foo)' into baz.
 
-If a simple command consists of one or more redirection operators
-and zero or more parameter assignments, but no command name,
-the command named in the shell variable tt(READNULLCMD) is assumed.
-(If tt(READNULLCMD) is empty or not set, `tt(cat)' is used.)  Thus
+sect(Redirections with no command)
+vindex(NULLCMD, use of)
+vindex(READNULLCMD, use of)
+pindex(CSH_NULLCMD, use of)
+pindex(SH_NULLCMD, use of)
+When a simple command consists of one or more redirection operators
+and zero or more parameter assignments, but no command name, zsh can
+behave in several ways.
+
+If the parameter tt(NULLCMD) is not set or the option tt(CSH_NULLCMD) is
+set, an error is caused.  This is the bf(csh) behavior and tt(CSH_NULLCMD)
+is set by default when emulating bf(csh).
+
+If the option tt(SH_NULLCMD) is set, the builtin `tt(:)' is inserted as a
+command with the given redirections.  This is the default when emulating
+bf(sh) or bf(ksh).
+
+Otherwise, if the parameter tt(NULLCMD) is set, its value will be used as a
+command with the given redirections.  If both tt(NULLCMD) and
+tt(READNULLCMD) are set, then the value of the latter will be used instead
+of that of the former when the redirection is an input.  The default for
+tt(NULLCMD) is `tt(cat)' and for tt(READNULLCMD) is `tt(more)'. Thus
+
+example(< file)
 
-nofill(tt(< file))
+shows the contents of tt(file) on standard output, with paging if that is a
+terminal.  tt(NULLCMD) and tt(READNULLCMD) may refer to shell functions.
 
-prints the contents of tt(file).
diff --git a/Doc/Zsh/zftpsys.yo b/Doc/Zsh/zftpsys.yo
index f20a0a6c3..e5b980cef 100644
--- a/Doc/Zsh/zftpsys.yo
+++ b/Doc/Zsh/zftpsys.yo
@@ -1,30 +1,31 @@
-texinode(Zftp Function System)()(Completion System)(Top)
+texinode(Zftp Function System)()(Zsh Modules)(Top)
 chapter(Zftp Function System)
-cindex(zftp, function system)
+cindex(zftp function system)
+cindex(FTP, functions for using shell as client)
 sect(Description)
 
 This describes the set of shell functions supplied with the source
 distribution as an interface to the tt(zftp) builtin command, allowing you
 to perform FTP operations from the shell command line or within functions
 or scripts.  The interface is similar to a traditional FTP client (e.g. the
-manref(ftp)(1) command itself), but as it is entirely done within the shell
-all the familar completion, editing and globbing features, and so on, are
-present, and macros are particularly simple to write as they are just
-ordinary shell functions.
+tt(ftp) command itself, see manref(ftp)(1)), but as it is entirely done
+within the shell all the familiar completion, editing and globbing features,
+and so on, are present, and macros are particularly simple to write as they
+are just ordinary shell functions.
 
 The prerequisite is that the tt(zftp) command, as described in
 ifzman(\
 zmanref(zshmodules)
 )\
 ifnzman(\
-noderef(The zftp Module)
+noderef(The zsh/zftp Module)
 ), must be available in the
 version of tt(zsh) installed at your site.  If the shell is configured to
-load new commands at run time, it probably is: typing tt(zmodload zftp)
+load new commands at run time, it probably is: typing `tt(zmodload zsh/zftp)'
 will make sure (if that runs silently, it has worked).  If this is not the
 case, it is possible tt(zftp) was linked into the shell anyway: to test
-this, type tt(which zftp) and if tt(zftp) is available you will get the
-message tt(zftp: shell built-in command).
+this, type `tt(which zftp)' and if tt(zftp) is available you will get the
+message `tt(zftp: shell built-in command)'.
 
 Commands given directly with tt(zftp) builtin may be interspersed between
 the functions in this suite; in a few cases, using tt(zftp) directly may
@@ -43,63 +44,85 @@ sect(Installation)
 
 You should make sure all the functions from the tt(Functions/Zftp)
 directory of the source distribution are available; they all begin with the
-two letters tt(zf).  They may already have been installed on your system;
+two letters `tt(zf)'.  They may already have been installed on your system;
 otherwise, you will need to find them and copy them.  The directory should
-appear as one of the elements of the tt($fpath) array, and the functions
-should be autoloaded.  Finally, to initialise the use of the system you
-need to call the tt(zfinit) function.  The following code in your
-tt(.zshrc) will arrange for this; assume the functions are stored in the
-directory tt(~/myfns):
-
-tt(indent(
-nofill(fpath=(~/myfns $fpath))
-nofill(autoload ~/myfns/zf*(:t))
-nofill(zfinit)
-))
+appear as one of the elements of the tt($fpath) array (this should already
+be the case if they were installed), and at least the function tt(zfinit)
+should be autoloaded; it will autoload the rest.  Finally, to initialize
+the use of the system you need to call the tt(zfinit) function.  The
+following code in your tt(.zshrc) will arrange for this; assume the
+functions are stored in the directory tt(~/myfns):
+
+example(fpath=(~/myfns $fpath)
+autoload -U zfinit
+zfinit)
 
 Note that tt(zfinit) assumes you are using the tt(zmodload) method to
 load the tt(zftp) command.  If it is already built into the shell, change
-tt(zfinit) to tt(zfinit -n).
+tt(zfinit) to tt(zfinit -n).  It is helpful (though not essential) if the
+call to tt(zfinit) appears after any code to initialize the new completion
+system, else unnecessary tt(compctl) commands will be given.
 
 texinode(Zftp Functions)(Miscellaneous Features)(Installation)(Zftp Function System)
 sect(Functions)
 
 The sequence of operations in performing a file transfer is essentially the
-same as that in a standard FTP client.
+same as that in a standard FTP client.  Note that, due to a quirk of the
+shell's tt(getopts) builtin, for those functions that handle options you
+must use `tt(-)tt(-)' rather than `tt(-)' to ensure the remaining arguments
+are treated literally (a single `tt(-)' is treated as an argument).
 
 subsect(Opening a connection)
 startitem()
+findex(zfparams)
 item(tt(zfparams [ var(host) [ var(user) [ var(password) ... ] ] ]))(
 Set or show the parameters for a future tt(zfopen) with no arguments.  If
 no arguments are given, the current parameters are displayed (the password
 will be shown as a line of asterisks).  If a host is given, and either the
 var(user) or var(password) is not, they will be prompted for; also, any
-parameter given as `tt(?)' will be prompted for.
-
-As tt(zfopen) calls tt(zfparams) to store the parameters, this usually need
-not be called directly.
+parameter given as `tt(?)' will be prompted for, and if the `tt(?)' is
+followed by a string, that will be used as the prompt.  As tt(zfopen) calls
+tt(zfparams) to store the parameters, this usually need not be called
+directly.
+
+A single argument `tt(-)' will delete the stored parameters.  This will
+also cause the memory of the last directory (and so on) on the other host
+to be deleted.
 )
+findex(zfopen)
 item(tt(zfopen [ -1 ] [ var(host) [ var(user) [ var(password) [ var(account) ] ] ] ]))(
 If var(host) is present, open a connection to that host under username
 var(user) with password var(password) (and, on the rare occasions when it
-is necessary account var(account)).  If a necessary parameter is missing or
+is necessary, account var(account)).  If a necessary parameter is missing or
 given as `tt(?)' it will be prompted for.  If var(host) is not present, use
 a previously stored set of parameters.
 
-If the command was successful, and the terminal is an tt(xterm), a summary
-will appear in the title bar, giving the local tt(host:directory) and the
-remote tt(host:directory); this is handled by the function tt(zftp_chpwd),
-described below.
+If the command was successful, and the terminal is compatible with
+tt(xterm) or is tt(sun-cmd), a summary will appear in the title bar,
+giving the local tt(host:directory) and the remote tt(host:directory);
+this is handled by the function tt(zftp_chpwd), described below.
 
 Normally, the var(host), var(user) and var(password) are internally
 recorded for later re-opening, either by a tt(zfopen) with no arguments, or
-automatically (see below).  With the option tt(-1), no information is
-stored.
+automatically (see below).  With the option `tt(-1)', no information is
+stored.  Also, if an open command with arguments failed, the parameters
+will not be retained (and any previous parameters will also be deleted).
+A tt(zfopen) on its own, or a tt(zfopen -1), never alters the stored
+parameters.
+
+Both tt(zfopen) and tt(zfanon) (but not tt(zfparams)) understand URLs of
+the form tt(ftp://)var(host)/var(path...) as meaning to connect to the
+var(host), then change directory to var(path) (which must be a directory,
+not a file).  The `tt(ftp://)' can be omitted; the trailing `tt(/)' is enough
+to trigger recognition of the var(path).  Note prefixes other than
+`tt(ftp:)' are not recognized, and that all characters after the first
+slash beyond var(host) are significant in var(path).
 )
+findex(zfanon)
 item(tt(zfanon [ -1 ] var(host)))(
 Open a connection var(host) for anonymous FTP.  The username used is
-tt(anonymous).  The password (which will be reported the first time) is
-generated from var(user)tt(@)tt(host); this is then stored in the shell
+`tt(anonymous)'.  The password (which will be reported the first time) is
+generated as var(user)tt(@)var(host); this is then stored in the shell
 parameter tt($EMAIL_ADDR) which can alternatively be set manually to a
 suitable string.
 )
@@ -107,6 +130,7 @@ enditem()
 
 subsect(Directory management)
 startitem()
+findex(zfcd)
 xitem(tt(zfcd [ var(dir) ]))
 xitem(tt(zfcd -))
 item(tt(zfcd var(old) var(new)))(
@@ -114,9 +138,9 @@ Change the current directory on the remote server:  this is implemented to
 have many of the features of the shell builtin tt(cd).
 
 In the first form with var(dir) present, change to the directory var(dir).
-The command tt(zfcd ..) is treated specially, so is guaranteed to work on
-non-UNIX servers (note this is handled internall by tt(zftp)).  If var(dir)
-is omitted, has the effect of tt(zfcd ~).
+The command `tt(zfcd ..)' is treated specially, so is guaranteed to work on
+non-UNIX servers (note this is handled internally by tt(zftp)).  If var(dir)
+is omitted, has the effect of `tt(zfcd ~)'.
 
 The second form changes to the directory previously current.
 
@@ -125,56 +149,63 @@ first occurrence of the string var(old) with the string var(new) in the
 current directory.
 
 Note that in this command, and indeed anywhere a remote filename is
-expected, the string which on the local host corresponds to tt(~) is
-converted back to a tt(~) before being passed to the remote machine.
+expected, the string which on the local host corresponds to `tt(~)' is
+converted back to a `tt(~)' before being passed to the remote machine.
 This is convenient because of the way expansion is performed on the command
 line before tt(zfcd) receives a string.  For example, suppose the command
-is tt(zfcd ~/foo).  The shell will expand this to a full path as in tt(zfcd
-/home/user2/pws/foo).  At this stage, tt(zfcd) recognises the initial path
-as tt(~), and the directory sent to the remote host is tt(~/foo), so that
-the tt(~) will be expanded by the server to the correct remote host
-directory.  Other named directories of the form tt(~name) are not treated
-in this fashion.
+is `tt(zfcd ~/foo)'.  The shell will expand this to a full path such as
+`tt(zfcd /home/user2/pws/foo)'.  At this stage, tt(zfcd) recognises the
+initial path as corresponding to `tt(~)' and will send the directory to
+the remote host as tt(~/foo), so that the `tt(~)' will be expanded by the
+server to the correct remote host directory.  Other named directories of
+the form `tt(~name)' are not treated in this fashion.
 )
+findex(zfhere)
 item(tt(zfhere))(
 Change directory on the remote server to the one corresponding to the
-current local directory, with special handling of tt(~) as in tt(zfcd).
+current local directory, with special handling of `tt(~)' as in tt(zfcd).
 For example, if the current local directory is tt(~/foo/bar), then
-tt(zfhere) performs the effect of tt(zfcd ~/foo/bar).
+tt(zfhere) performs the effect of `tt(zfcd ~/foo/bar)'.
 )
+findex(zfdir)
 item(tt(zfdir [ -rfd ] [ - ] [ var(dir-options) ] [ var(dir) ]))(
 Produce a long directory listing.  The arguments var(dir-options) and
 var(dir) are passed directly to the server and their effect is
 implementation dependent, but specifying a particular remote directory
-var(dir) is usually possible.  The output is passed through pager.
+var(dir) is usually possible.  The output is passed through a pager
+given by the environment variable tt($PAGER) or defaulting to `tt(more)'.
 
 The directory is usually cached for re-use.  In fact, two caches are
 maintained.  One is for use when there is no var(dir-options) or var(dir),
 i.e. a full listing of the current remote directory; it is flushed
 when the current remote directory changes.  The other is
 kept for repeated use of tt(zfdir) with the same arguments; for example,
-repeated use of tt(zfdir /pub/gnu) will only require the directory to be
+repeated use of `tt(zfdir /pub/gnu)' will only require the directory to be
 retrieved on the first call.  Alternatively, this cache can be re-viewed with
 the tt(-r) option.  As relative directories will confuse
-tt(zfdir), the tt(-f) option can be used to force the cache to be flushed.
-Also, the option tt(-d) will delete both caches without showing a directory
-listing.
+tt(zfdir), the tt(-f) option can be used to force the cache to be flushed
+before the directory is listed.  The option tt(-d) will delete both
+caches without showing a directory listing; it will also delete the cache
+of file names in the current remote directory, if any.
 )
+findex(zfls)
 item(tt(zfls) [ var(ls-options) ] [ var(dir) ])(
 List files on the remote server.  With no arguments, this will produce a
 simple list of file names for the current remote directory.  Any arguments
-are passed directory to the server.  No pager and no caching is used.
+are passed directly to the server.  No pager and no caching is used.
 )
 enditem()
 
 subsect(Status commands)
 startitem()
+findex(zftype)
 item(tt(zftype) [ var(type) ])(
 With no arguments, show the type of data to be transferred, usually ASCII
-or binary.  With an argument, change the type: the types tt(A) or
-tt(ASCII) for ASCII data and tt(B) or tt(BINARY), tt(I) or tt(IMAGE) for
-binary data are understood case-insensitively.
+or binary.  With an argument, change the type: the types `tt(A)' or
+`tt(ASCII)' for ASCII data and `tt(B)' or `tt(BINARY)', `tt(I)' or
+`tt(IMAGE)' for binary data are understood case-insensitively.
 )
+findex(zfstat)
 item(tt(zfstat) [ -v ])(
 Show the status of the current or last connection, as well as the status of
 some of tt(zftp)'s status variables.  With the tt(-v) option, a more
@@ -192,12 +223,16 @@ this requires version 5 of tt(perl), see the description of the function
 tt(zfrtime) below for more information.
 
 startitem()
-item(tt(zfget [ -Gt ] var(file1) ...))(
+findex(zfget)
+item(tt(zfget [ -Gtc ] var(file1) ...))(
 Retrieve all the listed files var(file1) ... one at a time from the remote
 server.  If a file contains a `tt(/)', the full name is passed to the
 remote server, but the file is stored locally under the name given by the
-part after the final `tt(/)'.
+part after the final `tt(/)'.  The option tt(-c) (cat) forces all files to
+be sent as a single stream to standard output; in this case the tt(-t)
+option has no effect.
 )
+findex(zfuget)
 item(tt(zfuget [ -Gvst ] var(file1) ...))(
 As tt(zfget), but only retrieve files where the version on the remote
 server is newer (has a later modification time), or where the local file
@@ -208,6 +243,7 @@ and will always retrieve the file in either of those two cases.  With the
 option tt(-v), the command prints more information about the files while it
 is working out whether or not to transfer them.
 )
+findex(zfcget)
 item(tt(zfcget [ -Gt ] var(file1) ...))(
 As tt(zfget), but if any of the local files exists, and is shorter than
 the corresponding remote file, the command assumes that it is the result of
@@ -217,6 +253,7 @@ file.  This is useful on a poor connection which keeps failing.
 Note that this requires a commonly implemented, but non-standard, version
 of the FTP protocol, so is not guaranteed to work on all servers.
 )
+findex(zfgcp)
 xitem(tt(zfgcp [ -Gt ] var(remote-file) var(local-file)))
 item(tt(zfgcp [ -Gt ] var(rfile1) ... var(ldir)))(
 This retrieves files from the remote server with arguments behaving
@@ -233,16 +270,24 @@ enditem()
 
 subsect(Sending files)
 startitem()
-item(tt(zfput var(file1) ...))(
+findex(zfput)
+item(tt(zfput [ -r ] var(file1) ...))(
 Send all the var(file1) ... given separately to the remote server.  If a
 filename contains a `tt(/)', the full filename is used locally to find the
 file, but only the basename is used for the remote file name.
+
+With the option tt(-r), if any of the var(files) are directories they are
+sent recursively with all their subdirectories, including files beginning
+with `tt(.)'.  This requires that the remote machine understand UNIX file
+semantics. as `tt(/)' is used as a directory separator.
 )
+findex(zfuput)
 item(tt(zfuput [ -vs ] var(file1) ...))(
 As tt(zfput), but only send files which are newer than their local
 equivalents, or if the remote file does not exist.  The logic is the same
 as for tt(zfuget), but reversed between local and remote files.
 )
+findex(zfcput)
 item(tt(zfcput var(file1) ...))(
 As tt(zfput), but if any remote file already exists and is shorter than the
 local equivalent, assume it is the result of an incomplete transfer and
@@ -250,6 +295,7 @@ send the rest of the file to append to the existing part.  As the FTP
 append command is part of the standard set, this is in principle more
 likely to work than tt(zfcget).
 )
+findex(zfpcp)
 xitem(tt(zfpcp var(local-file) var(remote-file)))
 item(tt(zfpcp var(lfile1) ... var(rdir)))(
 This sends files to the remote server with arguments behaving similarly to
@@ -266,32 +312,117 @@ A problem arises if you attempt to use tt(zfpcp) var(lfile1) var(rdir),
 i.e. the second form of copying but with two arguments, as the command has
 no simple way of knowing if var(rdir) corresponds to a directory or a
 filename.  It attempts to resolve this in various ways.  First, if the
-var(rdir) argument is tt(.) or tt(..) or ends in a slash, it is assumed to
-be a directory.  Secondly, if the operation of copying to a remote file in
-the first form failed, and the remote server sends back the expected
+var(rdir) argument is `tt(.)' or `tt(..)' or ends in a slash, it is assumed
+to be a directory.  Secondly, if the operation of copying to a remote file
+in the first form failed, and the remote server sends back the expected
 failure code 553 and a reply including the string `tt(Is a directory)',
 then tt(zfpcp) will retry using the second form.
 )
 enditem()
 
-subsect(Closing the connectino)
+subsect(Closing the connection)
 startitem()
+findex(zfclose)
 item(tt(zfclose))(
 Close the connection.
 )
 enditem()
 
+subsect(Session management)
+startitem()
+findex(zfsession)
+item(tt(zfsession) [ tt(-lvod) ] [ var(sessname) ])(
+Allows you to manage multiple FTP sessions at once.  By default,
+connections take place in a session called `tt(default)'; by giving the
+command `tt(zfsession) var(sessname)' you can change to a new or existing
+session with a name of your choice.  The new session remembers its own
+connection, as well as associated shell parameters, and also the host/user
+parameters set by tt(zfparams).  Hence you can have different sessions set
+up to connect to different hosts, each remembering the appropriate host,
+user and password.
+
+With no arguments, tt(zfsession) prints the name of the current session;
+with the option tt(-l) it lists all sessions which currently exist, and
+with the option tt(-v) it gives a verbose list showing the host and
+directory for each session, where the current session is marked with an
+asterisk.  With tt(-o), it will switch to the most recent previous session.
+
+With tt(-d), the given session (or else the current one) is removed;
+everything to do with it is completely forgotten.  If it was the only
+session, a new session called `tt(default)' is created and made current.
+It is safest not to delete sessions while background commands using
+tt(zftp) are active.
+)
+findex(zftransfer)
+item(tt(zftransfer) var(sess1)tt(:)var(file1) var(sess2)tt(:)var(file2))(
+Transfer files between two sessions; no local copy is made.  The file
+is read from the session var(sess1) as var(file1) and written to session
+var(sess1) as file var(file2); var(file1) and var(file2) may be relative to
+the current directories of the sesssion.  Either var(sess1) or var(sess2)
+may be omitted (though the colon should be retained if there is a
+possibility of a colon appearing in the file name) and defaults to the
+current session; var(file2) may be omitted or may end with a slash, in
+which case the basename of var(file1) will be added.  The sessions
+var(sess1) and var(sess2) must be distinct.
+
+The operation is performed using pipes, so it is required that the
+connections still be valid in a subshell, which is not the case under some
+operating systems.
+)
+enditem()
+
+subsect(Bookmarks)
+The two functions tt(zfmark) and tt(zfgoto) allow you to `bookmark' the
+present location (host, user and directory) of the current FTP connection
+for later use.  The file to be used for storing and retrieving bookmarks is
+given by the parameter tt($ZFTP_BMFILE); if not set when one of the two
+functions is called, it will be set to the file tt(.zfbfmarks) in the
+directory where your zsh startup files live (usually tt(~)).
+
+startitem()
+findex(zfmark)
+item(tt(zfmark [ )var(bookmark)tt( ]))(
+If given an argument, mark the current host, user and directory under the
+name var(bookmark) for later use by tt(zfgoto).  If there is no connection
+open, use the values for the last connection immediately before it was
+closed; it is an error if there is none.  Any existing bookmark
+under the same name will be silently replaced.
+
+If not given an argument, list the existing bookmarks and the points to
+which they refer in the form var(user)tt(@)var(host)tt(:)var(directory);
+this is the format in which they are stored, and the file may be edited
+directly.
+)
+findex(zfgoto)
+item(tt(zfgoto [ -n ] )var(bookmark))(
+Return to the location given by var(bookmark), as previously set by
+tt(zfmark).  If the location has user `tt(ftp)' or `tt(anonymous)', open
+the connection with tt(zfanon), so that no password is required.  If the
+user and host parameters match those stored for the current session, if
+any, those will be used, and again no password is required.  Otherwise a
+password will be prompted for.
+
+With the option tt(-n), the bookmark is taken to be a nickname stored by
+the tt(ncftp) program in its bookmark file, which is assumed to be
+tt(~/.ncftp/bookmarks).  The function works identically in other ways.
+Note that there is no mechanism for adding or modifying tt(ncftp) bookmarks
+from the zftp functions.
+)
+enditem()
+
 subsect(Other functions)
 Mostly, these functions will not be called directly (apart from
 tt(zfinit)), but are described here for completeness.  You may wish to
 alter tt(zftp_chpwd) and tt(zftp_progress), in particular.
 
 startitem()
+findex(zfinit)
 item(tt(zfinit [ -n ]))(
-As decribed above, this is used to initialise the zftp function system.
+As described above, this is used to initialize the zftp function system.
 The tt(-n) option should be used if the zftp command is already built into
 the shell.
 )
+findex(zfautocheck)
 item(tt(zfautocheck [ -dn ]))(
 This function is called to implement automatic reopening behaviour, as
 described in more detail below.  The options must appear in the first
@@ -302,6 +433,7 @@ transfer.  The host and directory for the last session are stored in the
 variable tt($zflastsession), but the internal host/user/password parameters
 must also be correctly set.
 )
+findex(zfcd_match)
 item(tt(zfcd_match var(prefix) var(suffix)))(
 This performs matching for completion of remote directory names.  If the
 remote server is UNIX, it will attempt to persuade the server to list the
@@ -310,6 +442,7 @@ guaranteed.  On other hosts it simply calls tt(zfget_match) and hence
 completes all files, not just directories.  On some systems, directories
 may not even look like filenames.
 )
+findex(zfget_match)
 item(tt(zfget_match var(prefix) var(suffix)))(
 This performs matching for completion of remote filenames.  It caches files
 for the current directory (only) in the shell parameter tt($zftp_fcache).
@@ -317,12 +450,14 @@ It is in the form to be called by the tt(-K) option of tt(compctl), but
 also works when called from a widget-style completion function with
 var(prefix) and var(suffix) set appropriately.
 )
+findex(zfrglob)
 item(tt(zfrglob var(varname)))(
 Perform remote globbing, as describes in more detail below.  var(varname)
 is the name of a variable containing the pattern to be expanded; if there
-were any matches, the same variable will be set to the exanded set of
+were any matches, the same variable will be set to the expanded set of
 filenames on return.
 )
+findex(zfrtime)
 item(tt(zfrtime var(lfile) var(rfile) [ var(time) ]))(
 Set the local file var(lfile) to have the same modification time as the
 remote file var(rfile), or the explicit time var(time) in FTP format
@@ -332,41 +467,129 @@ Currently this requires tt(perl) version 5 to perform the conversion from
 GMT to local time.  This is unfortunately difficult to do using shell code
 alone.
 )
+findex(zftp_chpwd, supplied version)
 item(tt(zftp_chpwd))(
 This function is called every time a connection is opened, or closed, or
 the remote directory changes.  This version alters the title bar of an
-tt(xterm) or tt(sun-cmd) terminal emulator to reflect the local and remote
-hostnames and current directories.  It works best when combined with the
-function tt(chpwd).  In particular, a function of the form
-
-tt(indent(
-nofill(chpwd() {)
-nofill(  if [[ -n $ZFTP_USER ]]; then)
-nofill(    zftp_chpwd)
-nofill(  else)
-nofill(    # usual chpwd e.g put host:directory in title bar)
-nofill(  fi)
-nofill(})
-))
+tt(xterm) compatible or tt(sun-cmd) terminal emulator to reflect the 
+local and remote hostnames and current directories.  It works best when
+combined with the function tt(chpwd).  In particular, a function of 
+the form
+
+example(chpwd() {
+  if [[ -n $ZFTP_USER ]]; then
+    zftp_chpwd
+  else
+    # usual chpwd e.g put host:directory in title bar
+  fi
+})
 
 fits in well.
 )
+findex(zftp_progress, supplied version)
 item(tt(zftp_progress))(
-This function shows the status of the transfer as the percentage of the
-total so far transferred.  It will not write anything unless the output is
-going to a terminal; however, if you transfer files in the background, you
-should tt(unfunction) this first.  (Background file transfers don't work on
-all OSes.)  Note also that if you alter it, any output em(must) be to
-standard error, as standard output may be a file being received.
+This function shows the status of the transfer.  It will not write anything
+unless the output is going to a terminal; however, if you transfer files in
+the background, you should turn off progress reports by hand using
+`tt(zstyle ':zftp:*' progress none)'.  Note also that if you alter it, any
+output em(must) be to standard error, as standard output may be a file
+being received.  The form of the progess meter, or whether it is used at
+all, can be configured without altering the function, as described in the
+next section.
+)
+findex(zffcache)
+item(tt(zffcache))(
+This is used to implement caching of files in the current directory for
+each session separately.  It is used by tt(zfget_match) and tt(zfrglob).
 )
 enditem()
 
 texinode(Miscellaneous Features)()(Zftp Functions)(Zftp Function System)
 sect(Miscellaneous Features)
 
+subsect(Configuration)
+cindex(zftp function system, configuration)
+cindex(zftp function system, styles)
+cindex(styles in zftp functions)
+
+Various styles are available using the standard shell style mechanism,
+described in
+ifzman(zmanref(zshmodules))\
+ifnzman(noderef(The zsh/zutil Module)). Briefly, the
+command `tt(zstyle ':zftp:*') var(style) var(value) ...'.
+defines the var(style) to have value var(value) (more than one may be
+given, although that is not useful in the cases described here).  These
+values will then be used throughout the zftp function system.  For more
+precise control, the first argument, which gives a context in which the
+style applies, can be modified to include a particular function, as for
+example `tt(:zftp:zfget:)': the style will then have the given value only
+in the tt(zfget) function.  Values for the same style in different contexts
+may be set; the most specific function will be used, where
+strings are held to be more specific than patterns, and longer patterns and
+shorter patterns.  Note that only the top level function name, as called by
+the user, is used; calling of lower level functions is transparent to the
+user.  Hence modifications to the title bar in tt(zftp_chpwd) use the
+contexts tt(:zftp:zfopen:), tt(:zftp:zfcd:), etc., depending where it was
+called from.  The following styles are understood:
+
+startitem()
+kindex(progress, zftp style)
+item(tt(progress))(
+Controls the way that tt(zftp_progress) reports on the progress of a
+transfer.  If empty, unset, or `tt(none)', no progress report is made; if
+`tt(bar)' a growing bar of inverse video is shown; if `tt(percent)' (or any
+other string, though this may change in future), the percentage of the file
+transferred is shown.  The bar meter requires that the width of the
+terminal be available via the tt($COLUMNS) parameter (normally this is set
+automatically).  If the size of the file being transferred is not
+available, tt(bar) and tt(percent) meters will simply show the number of
+bytes transferred so far.
+
+When tt(zfinit) is run, if this style is not defined for the context
+tt(:zftp:*), it will be set to `bar'.
+)
+kindex(update, zftp style)
+item(tt(update))(
+Specifies the minimum time interval between updates of the progress meter
+in seconds.  No update is made unless new data has been received, so the
+actual time interval is limited only by tt($ZFTP_TIMEOUT).
+
+As described for tt(progress), tt(zfinit) will force this to default to 1.
+)
+kindex(remote-glob, zftp style)
+item(tt(remote-glob))(
+If set to `1', `yes' or `true', filename generation (globbing) is
+performed on the remote machine instead of by zsh itself; see below.
+)
+kindex(titlebar, zftp style)
+item(tt(titlebar))(
+If set to `1', `yes' or `true', tt(zftp_chpwd) will put the remote host and
+remote directory into the titlebar of terminal emulators such as xterm or
+sun-cmd that allow this.
+
+As described for tt(progress), tt(zfinit) will force this to default to 1.
+)
+kindex(chpwd, zftp style)
+item(tt(chpwd))(
+If set to `1' `yes' or `true', tt(zftp_chpwd) will call the function
+tt(chpwd) when a connection is closed.  This is useful if the remote host
+details were put into the terminal title bar by tt(zftp_chpwd) and your
+usual tt(chpwd) also modifies the title bar.
+
+When tt(zfinit) is run, it will determine whether tt(chpwd) exists and if
+so it will set the default value for the style to 1 if none exists
+already.
+)
+enditem()
+
+Note that there is also an associative array tt(zfconfig) which contains
+values used by the function system.  This should not be modified or
+overwritten.
+
 subsect(Remote globbing)
+cindex(zftp function system, remote globbing)
 
-The commands for retrieving files usually perform filename expansion
+The commands for retrieving files usually perform filename generation
 (globbing) on their arguments; this can be turned off by passing the option
 tt(-G) to each of the commands.  Normally this operates by retrieving a
 complete list of files for the directory in question, then matching these
@@ -378,16 +601,17 @@ remote server does not support the UNIX directory semantics, directory
 handling is problematic and it is recommended that globbing only be used
 within the current directory.  The list of files in the current directory,
 if retrieved, will be cached, so that subsequent globs in the same
-directory without an interventing tt(zfcd) are fast.
+directory without an intervening tt(zfcd) are much faster.
 
-If the variable tt($zfrglob) is set to a non-zero length, globbing is
-instead performed on the remote host:  the server is asked for a list of
-matching files.  This is highly dependent on how the server is implemented,
-though typically UNIX servers will provide support for basic glob
-patterns.  This may in some cases be faster, as it avoids retrieving the
-entire list of directory contents.
+If the tt(remote-glob) style (see above) is set, globbing is instead
+performed on the remote host: the server is asked for a list of matching
+files.  This is highly dependent on how the server is implemented, though
+typically UNIX servers will provide support for basic glob patterns.  This
+may in some cases be faster, as it avoids retrieving the entire list of
+directory contents.
 
 subsect(Automatic and temporary reopening)
+cindex(zftp function system, automatic reopening)
 
 As described for the tt(zfopen) command, a subsequent tt(zfopen) with no
 parameters will reopen the connection to the last host (this includes
@@ -415,21 +639,24 @@ never close the connection automatically.
 Information about the previous connection is given by the tt(zfstat)
 function.  So, for example, if that reports:
 
-tt(indent(
-nofill(Not connected.)
-nofill(Last session:   ftp.bar.com:/pub/textfiles)
-))
+example(Session:        default
+Not connected.
+Last session:   ftp.bar.com:/pub/textfiles)
 
 then the command tt(zfget file.txt) will attempt to reopen a connection to
 tt(ftp.bar.com), retrieve the file tt(/pub/textfiles/file.txt), and
 immediately close the connection again.  On the other hand, tt(zfcd ..)
 will open the connection in the directory tt(/pub) and leave it open.
 
+Note that all the above is local to each session; if you return to a
+previous session, the connection for that session is the one which will be
+reopened.
+
 subsect(Completion)
 
-Completion of remote files and directories is supported.  The older,
-tt(compctl)-style completion is defined when tt(zfinit) is called; support
-for the new widget-based completion system is provided in the function
-tt(Completion/Builtins/_zftp), which should be installed with the other
-functions of the completion system and hence should automatically be
-available.
+Completion of local and remote files, directories, sessions and bookmarks
+is supported.  The older, tt(compctl)-style completion is defined when
+tt(zfinit) is called; support for the new widget-based completion system is
+provided in the function tt(Completion/Builtins/_zftp), which should be
+installed with the other functions of the completion system and hence
+should automatically be available.
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index fccf538bd..9b5744c2c 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -1,12 +1,13 @@
-texinode(Zsh Line Editor)(Programmable Completion)(Shell Builtin Commands)(Top)
+texinode(Zsh Line Editor)(Completion Using compctl)(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 (it is by default)
+If the tt(ZLE) option is set (which it is by default in interactive shells)
 and the shell input is attached to the terminal, the user
-is allowed to edit command lines.
+is able to edit command lines.
 
 There are two display modes.  The first, multiline mode, is the
 default.  It only works if the tt(TERM) parameter is set to a valid
@@ -67,7 +68,8 @@ that is bound to some command and is also a prefix of a longer bound string.
 In this case ZLE will wait a certain time to see if more characters
 are typed, and if not (or they don't match any longer string) it will
 execute the binding.  This timeout is defined by the tt(KEYTIMEOUT) parameter;
-its default is 0.4 sec.  No timeout is done if the prefix string is not bound.
+its default is 0.4 sec.  There is no timeout if the prefix string is not
+itself bound to a command.
 
 As well as ZLE commands, key sequences can be bound to other strings, by using
 `tt(bindkey -s)'.
@@ -83,7 +85,7 @@ simply to perform some small action.  The ZLE commands that key sequences
 in keymaps are bound to are in fact widgets.  Widgets can be user-defined
 or built in.
 
-There are 162 standard widgets built in to ZLE (see sectref(Standard Widgets)).
+The standard widgets built in to ZLE are listed in Standard Widgets below.
 Other built-in widgets can be defined by other modules (see
 ifzman(zmanref(zshmodules))\
 ifnzman(noderef(Zsh Modules))\
@@ -102,7 +104,8 @@ 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.
-Finally, they can examine and edit the ZLE buffer being edited by
+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
 reading and setting the special parameters described below.
 
 cindex(parameters, editor)
@@ -113,6 +116,9 @@ outside ZLE, that value is temporarily inaccessible, but will return
 when the widget function exits.  These special parameters in fact have
 local scope, like parameters created in a function using tt(local).
 
+Inside completion widgets and traps called while ZLE is active, these
+parameters are available read-only.
+
 startitem()
 vindex(BUFFER)
 item(tt(BUFFER) (scalar))(
@@ -127,6 +133,10 @@ 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(LBUFFER)
 item(tt(LBUFFER) (scalar))(
 The part of the buffer that lies to the left of the cursor position.
@@ -139,6 +149,42 @@ 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(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(PREBUFFER)
+item(tt(PREBUFFER) (scalar))(
+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(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)
@@ -317,6 +363,10 @@ item(tt(down-line-or-search))(
 Move down a line in the buffer, or if already at the bottom line,
 search forward in the history for a line beginning with the first
 word in the buffer.
+
+If called from a function by the tt(zle) command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
 )
 tindex(down-history)
 item(tt(down-history) (unbound) (^N) (unbound))(
@@ -385,6 +435,17 @@ search, leaving the last found line in the buffer. Any single character that
 is not bound to one of the above functions, or tt(self-insert) or
 tt(self-insert-unmeta), will have the same effect but the function will be
 executed.
+
+When called from a widget function by the tt(zle) command, the incremental
+search commands can take a string argument.  This will be treated as a
+string of keys, as for arguments to the tt(bindkey) command, and used as
+initial input for the command.  Any characters in the string which are
+unused by the incremental search will be silently ignored.  For example,
+
+example(zle history-incremental-search-backward forceps)
+
+will search backwards for tt(forceps), leaving the minibuffer containing
+the string `tt(forceps)'.
 )
 tindex(history-incremental-search-forward)
 item(tt(history-incremental-search-forward) (^S ^Xs) (unbound) (unbound))(
@@ -398,6 +459,10 @@ tindex(history-search-backward)
 item(tt(history-search-backward) (ESC-P ESC-p) (unbound) (unbound))(
 Search backward in the history for a line beginning with the first
 word in the buffer.
+
+If called from a function by the tt(zle) command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
 )
 tindex(vi-history-search-backward)
 item(tt(vi-history-search-backward) (unbound) (/) (unbound))(
@@ -425,18 +490,27 @@ tt(magic-space) is treated as a space.
 Any other character that is not bound to self-insert or
 self-insert-unmeta will beep and be ignored. If the function is called from vi
 command mode, the bindings of the current insert mode will be used.
+
+If called from a function by the tt(zle) command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
 )
 tindex(history-search-forward)
 item(tt(history-search-forward) (ESC-N ESC-n) (unbound) (unbound))(
 Search forward in the history for a line beginning with the first
 word in the buffer.
+
+If called from a function by the tt(zle) command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
 )
 tindex(vi-history-search-forward)
 item(tt(vi-history-search-forward) (unbound) (?) (unbound))(
 Search forward in the history for a specified string.
 The string may begin with `tt(^)' to anchor the search to the
 beginning of the line. The functions available in the mini-buffer are the same
-as for tt(vi-history-search-backward).
+as for tt(vi-history-search-backward).  Argument handling is also the same
+as for that command.
 )
 tindex(infer-next-history)
 item(tt(infer-next-history) (^X^N) (unbound) (unbound))(
@@ -449,7 +523,10 @@ Insert the last word from the previous history event at the
 cursor position.  If a positive numeric argument is given,
 insert that word from the end of the previous history event.
 If the argument is zero or negative insert that word from the
-left (zero inserts the previous command word).
+left (zero inserts the previous command word).  Repeating this command
+replaces the word just inserted with the last word from the
+history event prior to the one just used; numeric arguments can be used in
+the same way to pick a word from that event.
 )
 tindex(vi-repeat-search)
 item(tt(vi-repeat-search) (unbound) (n) (unbound))(
@@ -475,6 +552,10 @@ item(tt(up-line-or-search))(
 Move up a line in the buffer, or if already at the top line,
 search backward in the history for a line beginning with the
 first word in the buffer.
+
+If called from a function by the tt(zle) command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
 )
 tindex(up-history)
 item(tt(up-history) (unbound) (^P) (unbound))(
@@ -771,7 +852,11 @@ startitem()
 tindex(digit-argument)
 item(tt(digit-argument) (ESC-0..ESC-9) (1-9) (unbound))(
 Start a new numeric argument, or add to the current one.
-See also tt(vi-digit-or-beginning-of-line).
+See also tt(vi-digit-or-beginning-of-line).  This only works if bound to a
+key sequence ending in a decimal digit.
+
+Inside a widget function, a call to this function treats the last key of
+the key sequence which called the widget as the digit.
 )
 tindex(neg-argument)
 item(tt(neg-argument) (ESC--) (unbound) (unbound))(
@@ -786,6 +871,10 @@ repeated using this command.  For example, if this command occurs
 twice, followed immediately by tt(forward-char), move forward sixteen
 spaces; if instead it is followed by tt(-2), then tt(forward-char),
 move backward two spaces.
+
+Inside a widget function, if passed an argument, i.e. `tt(zle
+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)
@@ -857,6 +946,11 @@ Perform menu completion, like tt(menu-complete), except that if
 a menu completion is already in progress, move to the em(previous)
 completion rather than the next.
 )
+tindex(end-of-list)
+item(tt(end-of-list))(
+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)
 subsect(Miscellaneous)
@@ -882,6 +976,10 @@ item(tt(accept-line-and-down-history) (^O) (unbound) (unbound))(
 Execute the current line, and push the next history
 event on the the buffer stack.
 )
+tindex(beep)
+item(tt(beep))(
+Beep, unless the tt(BEEP) option is unset.
+)
 tindex(vi-cmd-mode)
 item(tt(vi-cmd-mode) (^X^V) (unbound) (^[))(
 Enter command mode; that is, select the `tt(vicmd)' keymap.
diff --git a/Doc/zsh.yo b/Doc/zsh.yo
index c38313b4e..3d39a41c0 100644
--- a/Doc/zsh.yo
+++ b/Doc/zsh.yo
@@ -61,10 +61,10 @@ ifnzman(includefile(Zsh/params.yo))

 ifnzman(includefile(Zsh/options.yo))

 ifnzman(includefile(Zsh/builtins.yo))

 ifnzman(includefile(Zsh/zle.yo))

-ifnzman(includefile(Zsh/compwid.yo))

 ifnzman(includefile(Zsh/compctl.yo))

-ifnzman(includefile(Zsh/modules.yo))

+ifnzman(includefile(Zsh/compwid.yo))

 ifnzman(includefile(Zsh/compsys.yo))

+ifnzman(includefile(Zsh/modules.yo))

 ifnzman(includefile(Zsh/zftpsys.yo))

 ifzshall(\
 def(source)(1)(NOTRANS(.so )man1/ARG1NOTRANS(.)1)\
@@ -75,10 +75,10 @@ source(zshparam)
 source(zshoptions)
 source(zshbuiltins)
 source(zshzle)
-source(zshcompwid)
 source(zshcompctl)
-source(zshmodules)
+source(zshcompwid)
 source(zshcompsys)
+source(zshmodules)
 source(zshzftpsys)
 manpage(ZSHALL)(1)(date())(zsh version())
 )\
diff --git a/Doc/ztexi.yo b/Doc/ztexi.yo
index b8e115ec0..02fee37a6 100644
--- a/Doc/ztexi.yo
+++ b/Doc/ztexi.yo
@@ -11,7 +11,6 @@ def(CMT)(0)(NOTRANS(@c))
 
 ATEXIT(\
   NL()\
-  NOTRANS(@setchapternewpage odd)NL()\
   NOTRANS(@contents)NL()\
   NOTRANS(@bye)NL()\
 )
@@ -33,7 +32,7 @@ COMMENT(--- emphasised text ---)
 
 def(em)(1)(NOTRANS(@emph{)ARG1NOTRANS(}))
 def(bf)(1)(NOTRANS(@cite{)ARG1NOTRANS(}))
-def(tt)(1)(NOTRANS(@code{)ARG1NOTRANS(}))
+def(tt)(1)(NOTRANS(@t{)ARG1NOTRANS(}))
 def(var)(1)(NOTRANS(@var{)ARG1NOTRANS(}))
 
 COMMENT(--- man page headers ---)
@@ -47,16 +46,26 @@ def(texinfo)(2)(\
   STDPAR()\
   NOTRANS(\input texinfo.tex)NL()\
   NOTRANS(@c %**start of header)NL()\
+  NOTRANS(@iftex)NL()\
+  NOTRANS(@afourpaper)NL()\
+  NOTRANS(@setchapternewpage off)NL()\
+  NOTRANS(@end iftex)NL()\
   NOTRANS(@setfilename )ARG1NL()\
   NOTRANS(@settitle )ARG2NL()\
   NOTRANS(@c %**end of header)NL()\
   NL()\
   NOTRANS(@ifinfo)NL()\
-  NOTRANS(@set dsq @'@')NL()\
+  NOTRANS(@set dsq '@:')NL()\
   NOTRANS(@end ifinfo)NL()\
   NOTRANS(@iftex)NL()\
   NOTRANS(@set dsq '{}')NL()\
   NOTRANS(@end iftex)NL()\
+  NOTRANS(@ifinfo)NL()\
+  NOTRANS(@dircategory Utilities)NL()\
+  NOTRANS(@direntry)NL()\
+  NOTRANS(     * ZSH: (zsh).                     The Z Shell Manual.)NL()\
+  NOTRANS(@end direntry)NL()\
+  NOTRANS(@end ifinfo)NL()\
 )
 
 def(texiifinfo)(1)(\
@@ -171,6 +180,7 @@ def(startlist)(0)(\
   startitem()\
 )
 def(endlist)(0)(\
+  NOTRANS(@item)NL()\
   enditem()\
 )
 def(list)(1)(\
@@ -201,8 +211,16 @@ def(nofill)(1)(\
   USECHARTABLE(standard)\
 )
 
+def(example)(1)(\
+  NOTRANS(@example)NL()\
+  ARG1\
+  NL()NOTRANS(@end example)\
+)
+
 def(indent)(1)(\
+  NOTRANS(@quotation)NL()\
   ARG1\
+  NL()NOTRANS(@end quotation)\
 )
 
 COMMENT(--- hyperlink menus ---)