doc changes; typo in _jobs; integer builtin understands `-i base'

11 files changed, 636 insertions, 395 deletions

diff --git a/Doc/Zsh/arith.yo b/Doc/Zsh/arith.yo
index 1560c81d3..e47c0284a 100644
--- a/Doc/Zsh/arith.yo
+++ b/Doc/Zsh/arith.yo
@@ -5,18 +5,49 @@ sect(Arithmetic Evaluation)
 )\
 cindex(arithmetic evaluation)
 cindex(evaluation, arithmetic)
-An ability to perform integer arithmetic is provided with the builtin tt(let).
 findex(let, use of)
-Evaluations are performed using em(long) arithmetic.
+The shell can perform integer and floating point arithmetic, either using
+the builtin tt(let), or via a substitution of the form tt($((...))).  For
+integers, the shell is usually compiled to use 8-byte precision where this
+is available, otherwise precision is 4 bytes.  This can be tested, for
+example, by giving the command `tt(print - $(( 12345678901 )))'; if the
+number appears unchanged, the precision is at least 8 bytes.  Floating
+point arithmetic is always double precision.
+
+The tt(let) builtin command takes arithmetic expressions as arguments; each
+is evaluated separately.  Since many of the arithmetic operators, as well
+as spaces, require quoting, an alternative form is provided: for any
+command which begins with a `tt(LPAR()LPAR())', all the characters until a
+matching `tt(RPAR()RPAR())' are treated as a quoted expression and
+arithmetic expansion performed as for an argument of tt(let).  More
+precisely, `tt(LPAR()LPAR())var(...)tt(RPAR()RPAR())' is equivalent to
+`tt(let ")var(...)tt(")'.  For example, the following statement
+
+example((( val = 2 + 1 )))
+
+is equivalent to
+
+example(let "val = 2 + 1")
+
+both assigning the value 3 to the shell variable tt(foo) and returning a
+zero status.
+
+cindex(bases, in arithmetic)
+Integers can be in bases other than 10.
 A leading `tt(0x)' or `tt(0X)' denotes hexadecimal.
-Otherwise, numbers are of the form `[var(base)tt(#)]var(n)',
+Integers may also be of the form `var(base)tt(#)var(n)',
 where var(base) is a decimal number between two and thirty-six
 representing the arithmetic base and var(n)
 is a number in that base (for example, `tt(16#ff)' is 255 in hexadecimal).
-If var(base) is omitted
-then base 10 is used.  For backwards compatibility the form
+The var(base)tt(#) may also be omitted, in which case
+base 10 is used.  For backwards compatibility the form
 `tt([)var(base)tt(])var(n)' is also accepted.
 
+Floating point constants are recognized by the presence of a decimal point
+or an exponent.  The decimal point may be the first character of the
+constant, but the exponent character tt(e) or tt(E) may not, as it will be
+taken for a parameter name.
+
 cindex(arithmetic operators)
 cindex(operators, arithmetic)
 An arithmetic expression uses nearly the same syntax, precedence, and
@@ -42,18 +73,37 @@ sitem(tt(= PLUS()= -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **=))(assignment)
 sitem(tt(,))(comma operator)
 endsitem()
 
-The operators `tt(&&)', `tt(||)', `tt(&&=)', and `tt(||=)' are short-circuiting,
-and only one of the latter two expressions in a ternary operator
-is evaluated.  Note the precedence of the bitwise AND, OR,
+The operators `tt(&&)', `tt(||)', `tt(&&=)', and `tt(||=)' are
+short-circuiting, and only one of the latter two expressions in a ternary
+operator is evaluated.  Note the precedence of the bitwise AND, OR,
 and XOR operators.
 
-An expression of the form `tt(#\)var(x)' where var(x) is any character
-gives the ascii value of this character and an expression of the form
-`tt(#)var(foo)' gives the ascii value of the first character of the value
-of the parameter var(foo).
+cindex(math functions)
+cindex(functions, math)
+Mathematical functions can be called with the syntax
+`var(func)tt(LPAR())var(args)tt(RPAR())', where the function decides
+if the var(args) is used as a string or a comma-separated list of
+arithmetic expressions. The shell currently defines no mathematical
+functions by default, but the module tt(zsh/mathfunc) may be loaded with
+the tt(zmodload) builtin to provide standard floating point mathematical
+functions.
+
+An expression of the form `tt(##)var(x)' where var(x) is any character
+sequence such as `tt(a)', `tt(^A)', or `tt(\M-\C-x)' gives the ascii
+value of this character and an expression of the form `tt(#)var(foo)'
+gives the ascii value of the first character of the value of the
+parameter var(foo).  Note that this is different from the expression
+`tt($#)var(foo)', a standard parameter substitution which gives the
+length of the parameter var(foo).  `tt(#\)' is accepted instead of
+`tt(##)', but its use is deprecated.
 
 Named parameters and subscripted arrays can be referenced by name within an
-arithmetic expression without using the parameter substitution syntax.
+arithmetic expression without using the parameter expansion syntax.  For
+example,
+
+example(((val2 = val1 * 2)))
+
+assigns twice the value of tt($val1) to the parameter named tt(val2).
 
 An internal integer representation of a named parameter
 can be specified with the tt(integer) builtin.
@@ -62,12 +112,41 @@ cindex(integer parameters)
 findex(integer, use of)
 Arithmetic evaluation is performed on the value of each
 assignment to a named parameter declared integer
-in this manner.
-
-Since many of the arithmetic operators require
-quoting, an alternative form of the tt(let) command is provided.
-For any command which begins with a tt(LPAR()LPAR()),
-all the characters until a matching tt(RPAR()RPAR())
-are treated as a quoted expression.
-More precisely, `tt(LPAR()LPAR()) ... tt(RPAR()RPAR())'
-is equivalent to `tt(let ")...tt(")'.
+in this manner.  Assigning a floating point number to an integer results in
+rounding down to the next integer.
+
+cindex(parameters, floating point)
+cindex(floating point parameters)
+findex(float, use of)
+Likewise, floating point numbers can be declared with the tt(float)
+builtin; there are two types, differing only in their output format, as
+described for the tt(typeset) builtin.  The output format can be bypassed
+by using arithmetic substitution instead of the parameter substitution,
+i.e. `tt(${)var(float)tt(})' uses the defined format, but
+`tt($LPAR()LPAR())var(float)tt(RPAR()RPAR())' uses a generic floating point
+format.
+
+Promotion of integer to floating point values is performed where
+necessary.  In addition, if any operator which requires an integer
+(`tt(~)', `tt(&)', `tt(|)', `tt(^)', `tt(%)', `tt(<<)', `tt(>>)' and their
+equivalents with assignment) is given a floating point argument, it will be
+silently rounded down to the next integer.
+
+Scalar variables can hold integer or floating point values at different
+times; there is no memory of the numeric type in this case.
+
+If a variable is first assigned in a numeric context without previously
+being declared, it will be implicitly typed as tt(integer) or tt(float) and
+retain that type either until the type is explicitly changed or until the
+end of the scope.  This can have unforeseen consequences.  For example, in
+the loop
+
+example(for (( f = 0; f < 1; f += 0.1 )); do;
+# use $f
+done)
+
+if tt(f) has not already been declared, the first assignment will cause it
+to be created as an integer, and consequently the operation `tt(f += 0.1)'
+will always cause the result to be truncated to zero, so that the loop will
+fail.  A simple fix would be to turn the initialization into `tt(f = 0.0)'.
+It is therefore best to declare numeric variables with explicit types.
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 3ab87ece8..6d6b9cfbc 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -497,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(ghlrtux) ] [ var(name)[tt(=)var(value)] ... ])(
+item(tt(integer) [ {tt(PLUS())|tt(-)}tt(ghilrtux) ] [ var(name)[tt(=)var(value)] ... ])(
 Equivalent to tt(typeset -i), except that options irrelevant to
 integers are not permitted.
 )
@@ -850,10 +850,10 @@ the effect is different for zero and non-zero return status.  With zero
 status (or after an implicit return at the end of the trap), the shell
 will return to whatever it was previously processing; with a non-zero
 status, the shell will behave as interrupted except that the return
-status of the trap is retained.  Note that the signal which caused the
-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.
+status of the trap is retained.  Note that the numeric value of the signal
+which caused the 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)
@@ -1330,32 +1330,32 @@ 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
+This builtin command can be used to compile functions or scripts,
+storing 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
+compiled file.  If only the var(file) argument is given, 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
+the same directory as the var(file).  The shell will load the compiled
+file 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)
+for a description of how autoloaded functions are searched.  The
+extension tt(.zwc) stands for `zsh word code'.
+
+If there is at least one var(name) argument, all the named files
+are compiled into the output var(file) given as the first argument.  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
@@ -1386,12 +1386,13 @@ 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
+files compiled into it are listed.  The first line of output shows
 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.
+will be used (i.e. by reading it directly or by mapping it into memory).
+With arguments, nothing is output and the return value is set to zero if
+definitions for em(all) var(name)s name files were found in the wordcode
+file, and non-zero if the definition for at least one var(name) was not
+found.
 
 Other options:
 
@@ -1405,9 +1406,9 @@ 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.
+often desirable to use this option; otherwise the whole file, including the
+code to define functions which have already been defined, will
+remain mapped, consequently wasting memory.
 )
 item(tt(-M))(
 The compiled file is mapped into the shell's memory when read. This
@@ -1418,24 +1419,24 @@ 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
+These options are used when the compiled file contains functions which
+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.
+read, while if the tt(-k) is given, the function will 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).
+These options may also appear as many times as necessary between 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
+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).
 )
@@ -1450,8 +1451,11 @@ 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.
+Loading of modules while the shell is running (`dynamical loading') is not
+available on all operating systems, or on all installations on a particular
+operating system, although the tt(zmodload) command itself is always
+available and can be used to manipulate modules built into versions of the
+shell executable without dynamical loading.
 
 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
@@ -1462,7 +1466,7 @@ 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)'.
+a standard suffix, usually `tt(.so)' (`tt(.sl)' on HPUX).
 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.
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 8834fd489..af17d9434 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -66,13 +66,14 @@ 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
+(`tt(autoload -U compinit)' is recommended), and then run simply as
+`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. 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.
+new system.  If you use the tt(menu-select) widget, which is part of the
+tt(zsh/complist) module, you should make sure that that module is loaded
+before the call to tt(compinit) to make sure that that widget is also
+re-bound.
 
 Should you need to use the original completion commands, you can still
 bind keys to the old functions by putting a `tt(.)' in front of the
@@ -84,14 +85,14 @@ 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.
+var(dumpfile)'.  On the next call to tt(compinit), it will read the dumped
+file instead of performing 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) 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.
+change, it is easiest to delete the dump file by hand so that
+tt(compinit) will re-create it the next time it is run.
 
 The dumping is actually done by another function, tt(compdump), but you
 will only need to run this yourself if you change the configuration
@@ -109,13 +110,12 @@ 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.  If tt(zsh)
 was properly installed on your system, then tt(fpath/FPATH) automatically
-contains the required directories.
+contains the required directories for the standard functions.
 
 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
+path.  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
@@ -124,7 +124,7 @@ 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
+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
 completion system and will not be treated specially.
 
@@ -150,23 +150,22 @@ completion function for the command on the line could be found.
 )
 item(tt(#compdef -k) var(style key-sequences...))(
 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). If the
-tt(zsh/complist) module is loaded (see
+var(key-sequences) specified.  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).  If the tt(zsh/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 same happens to the tt(menu-select) widget.
 
 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
-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.
+be invoked to generate the matches.  Note that a key will not be re-bound
+if if it already was (that is, was bound to something other than
+tt(undefined-key)).  The widget created has the same name as the file and
+can be bound to any other keys using tt(bindkey) as usual.
 )
 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)
@@ -191,27 +190,24 @@ 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
-to be loaded immediately.
+when making the function autoloaded.  Most often, this will be tt(+X) to
+force the function to be loaded immediately.  Note that the tt(-U) flag is
+always implicitly added.
 )
 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 described
-below; the main difference is that the name of the function is supplied
-implicitly.
+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 described below; the
+main difference is that the name of the function is supplied implicitly.
 
 Note also that the functions for the completion system assume that the
-tt(KSH_AUTOLOAD) option is not set, they can't be loaded when it is
-set. But when you can't or don't want to unset tt(KSH_AUTOLOAD) and
-still want to use the completion system, you can simply use one or
-more tt(zwc) file(s) created with the tt(zcompile) builtin command
-with the tt(-z) option to load the functions for the completion system 
-from (see
+tt(KSH_AUTOLOAD) option is not set and cannot be loaded when it is
+set.  To avoid having to unset tt(KSH_AUTOLOAD), you can instead use one or
+more tt(zwc) file(s) which have been created with the command tt(zcompile
+-z) to load the functions for the completion system; see
 ifzman(zmanref(zshbuiltins))\
 ifnzman(noderef(Shell Builtin Commands))\
-). This forces the functions to be autoloaded the way zsh normally
+.  This forces the functions to be autoloaded the way zsh normally
 loads functions.
 
 subsect(Functions)
@@ -284,15 +280,15 @@ 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 functions may modify some of the fields and 
-hence the context name used for lookup may vary during the same call
+The `context' of a completion is a string consisting of multiple fields. This
+is used to look up styles that can be used to configure the
+completion system.  Since it is not possible to build the whole context 
+string in advance, completion functions may modify some of the fields and 
+hence the context 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:
+The context string always consists of the following fields, separated
+by colons and with a leading colon before the first:
 
 startitemize()
 itemiz(\
@@ -303,12 +299,12 @@ 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.
+the distribution, this field contains the name of that function, often
+in an abbreviated form.
 )
 itemiz(\
-The var(completer) currently active, i.e. the name of the completer
-function without the leading underscore. Such a completer is in
+The var(completer) currently active, which is the name of the function
+without the leading underscore.  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
@@ -318,10 +314,10 @@ ifnzman(noderef(Control Functions))
 for more information).  
 )
 itemiz(\
-The var(context) or var(command). This is either one of the special
+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
+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
@@ -329,15 +325,14 @@ 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
+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(option-)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.
+The var(tag).  Tags are used to discriminate between the types
+of matches a completion function can generate in a certain context.
 )
 enditemize()
 
@@ -358,17 +353,18 @@ 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.
+will be produced, and in the order given, although the default is to try
+all relevant tags in an order determined by the particular completion in
+use.
 
 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 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.
+can be invoked to find out the context and tag names and styles used at a
+particular point in completion.  It shows the list of contexts and tags 
+that would be used in 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 (\
@@ -386,22 +382,23 @@ 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
+which form should be used.  To make all such functions use the verbose form,
+put
 
 example(zstyle ':completion:*' verbose yes)
 
-in one of the startup files like tt(.zshrc). This definition simply
+in one of the startup files like tt(.zshrc); this sort of style can also be
+configured with the tt(compinstall) function.  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.
+context inside the completion system.  If the context pattern were `tt(*)',
+the verbose style would have this value anywhere the style mechanism is
+used, not just in completion.
 
 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
+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)
@@ -420,18 +417,17 @@ 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
+As with tags, completion functions can use any style they choose, 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.
+Here are the tags currently used by the completion system.  Some of them
+are only used when looking up styles and do not refer to a particular type
+of match.
 
 startitem()
 kindex(accounts, completion tag)
@@ -440,12 +436,13 @@ used to look up the tt(users-hosts) style
 )
 kindex(all-files, completion tag)
 item(tt(all-files))(
-for the names of all files
+for the names of all files (as distinct from a particular subset, see the
+tt(globbed-files) tag).
 )
 kindex(all-expansions, completion tag)
 item(tt(all-expansions))(
-used by the tt(_expand) completer when adding the string containing
-all expansions
+used by the tt(_expand) completer when adding the single string containing
+all possible expansions
 )
 kindex(arguments, completion tag)
 item(tt(arguments))(
@@ -457,8 +454,8 @@ 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)
+for keys of associative arrays; used when completing inside a
+subscript of a parameter of this type
 )
 kindex(bookmarks, completion tag)
 item(tt(bookmarks))(
@@ -523,7 +520,8 @@ for network domains
 )
 kindex(expansions, completion tag)
 item(tt(expansions))(
-used by the tt(_expand) completer for possible expansions
+used by the tt(_expand) completer for individual possibilities resulting
+from expansion of a word
 )
 kindex(extensions, completion tag)
 item(tt(extensions))(
@@ -531,8 +529,8 @@ 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
+the generic file-matching tag used by completion functions that can
+complete the names of some kind of file
 )
 kindex(fonts, completion tag)
 item(tt(fonts))(
@@ -540,8 +538,8 @@ 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)
+names of functions, normally shell functions although certain commands may
+understand other kinds of function
 )
 kindex(globbed-files, completion tag)
 item(tt(globbed-files))(
@@ -578,8 +576,8 @@ 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
+for names of directories which are subdirectories of the current working
+directory when completing for the tt(cd) and related builtin commands
 )
 kindex(libraries, completion tag)
 item(tt(libraries))(
@@ -595,7 +593,7 @@ for names of manual pages
 )
 kindex(maps, completion tag)
 item(tt(maps))(
-for map names (e.g. YP maps)
+for map names (e.g. NIS maps)
 )
 kindex(messages, completion tag)
 item(tt(messages))(
@@ -623,7 +621,7 @@ for all kinds of names
 )
 kindex(nicknames, completion tag)
 item(tt(nicknames))(
-for nicknames of YP maps
+for nicknames of NIS maps
 )
 kindex(options, completion tag)
 item(tt(options))(
@@ -648,8 +646,8 @@ 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
+for names of directories found by searching the tt(cdpath) array when
+completing for the tt(cd) and related builtin commands
 )
 kindex(paths, completion tag)
 item(tt(paths))(
@@ -658,7 +656,7 @@ tt(special-dirs) styles
 )
 kindex(pods, completion tag)
 item(tt(pods))(
-for perl pods
+for perl pods (documentation files)
 )
 kindex(ports, completion tag)
 item(tt(ports))(
@@ -754,26 +752,27 @@ enditem()
 subsect(Standard Styles)
 cindex(completion system, styles)
 
-Here are the names of the styles used by the completion system. Note
+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)',
+values; here, 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.
+possible values; in particular, the default value may be either on or off
+if the style is not set.
 
 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
+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(_expand) completer. If it is `true' (the
+This style is used by the tt(_expand) completer.  If it is `true' (the
 default), a space will be inserted after all words resulting from the 
 expansion (except for directory names which get a slash).
 
@@ -782,19 +781,17 @@ be inserted before the suffix.
 )
 kindex(ambiguous, completion style)
 item(tt(ambiguous))(
-This is used 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.
+This applies when completing non-final components of filename paths.
+If it is set, the cursor is left after the first ambiguous component, even
+if menucompletion is in use.  It is tested with the tt(paths) tag.
 )
 kindex(assign-list, completion style)
 item(tt(assign-list))(
 When completing after an equal sign, the completion system normally
-completes only one filename.  But when completing the value for some
-parameters or after other strings separated by an equal sign from a
-value, a colon-separated list of filenames is needed. This style
-can be set to a list of patterns matching the names of parameters for
-which such a colon-separated list of filenames should be completed.
+completes only one filename.  In some cases, particularly for certain
+parameters such as tt(PATH), a list of filenames separated by colons is
+required.  This style can be set to a list of patterns matching the names
+of such parameters.
 
 The default is to complete lists when the word on the line already
 contains a colon.
@@ -803,8 +800,8 @@ 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,
+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.
 )
@@ -818,27 +815,26 @@ 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
+In many places, completion functions need to call external commands to
+generate the list of completions.  This style can be used to override the
+command which is called in some such cases.  The elements of the value are
+joined with spaces to form a command line to execute.  The value can also
+start with a hyphen, in which case the usual command will be added to the
+end; this is most useful for putting `tt(builtin)' or `tt(command)' in
+front to make sure the appropriate version of a command is called, for
+example to avoid calling a shell function with the same name as an external
+command.
+
+As an example, the function generating process IDs as matches uses this
 style with the tt(processes) tag to generate the IDs to complete and when
 the tt(verbose) style is `true', it uses this style with the
-tt(processes-list) tag to generate the strings to display. When using
+tt(processes-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
+The strings given as the value of this style provide the names of the
 completer functions to use. The available completer functions are
 described in
 ifzman(the section `Control Functions' below)\
@@ -849,29 +845,29 @@ 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
+underscores replaced by 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.  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) appended to it. For example: 
+the first case with the var(name) 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
+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
+name will be the same in all calls to the completer; possible
 exceptions to this rule are the tt(_ignored) and tt(_prefix)
-completers).
+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
+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:
@@ -901,9 +897,9 @@ 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
+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
+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} != 1')
@@ -918,15 +914,15 @@ cursor after completion has been tried.  Values are:
 
 startitem()
 item(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 
+The cursor is left where it was when completion finished, but only if
+it is after a character equal to the one just inserted by the user.  If 
 it is after another character, this value is the same as `tt(key)'.
 )
 item(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
+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.
@@ -940,23 +936,24 @@ kindex(disable-stat, completion style)
 item(tt(disable-stat))(
 This is used with 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.
+generate names of modified files in the appropriate places (this is its
+only use).  If set, completion will use the tt(ls) command.
 )
 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.
+completed.  If this is not set by the user domain names will be taken from
+the file tt(/etc/resolv.conf).
 )
 kindex(expand, completion style)
 item(tt(expand))(
 This style is used when completing strings consisting of multiple
-parts, such as path names. If its
+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)'
+cannot 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
+components after the first ambiguous one will also be added.  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),
@@ -966,35 +963,35 @@ 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
+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 contain
+used.  Instead, the value of the style says which tags and which
+patterns are to be offered.  The strings in the value contain
 specifications of the form
 `var(pattern)tt(:)var(tag)'; each string may contain any number of
-such specifications. The var(pattern) gives a glob 
+such specifications.  The var(pattern) gives a glob 
 pattern that is to be used to generate
-filenames. If it contains the sequence `tt(%p)', that is replaced by
+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). If more
+Colons in the pattern must be preceded by a backslash to
+make them distinguishable from the colon before the var(tag).  If more
 than one pattern is needed, the patterns can be given inside braces,
-separated by commas. The
+separated by commas.  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. For
+(again, one after another) and used when looking up other styles.  For
 strings containing more than one specification, the filenames for all
-specifications will be generated at the same try. If
-no `tt(:)var(tag)' is given the `tt(files)' tag will be used. The
+specifications will be generated at the same try.  If
+no `tt(:)var(tag)' is given the `tt(files)' tag will be used.  The
 var(tag) may also be
-followed by an optional second colon and a description. If that is
+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
+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.
 
@@ -1007,9 +1004,9 @@ example(zstyle ':completion:*:*:rm:*' file-patterns \
 
 Another interesting example is to change the default behaviour that
 makes completion first offer files matching the patterns given by the
-calling function, then directories and then all files. Many people 
+calling function, then 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 at the second try. To
+directories in the first try and all files at the second try.  To
 achieve this, one could do:
 
 example(zstyle ':completion:*' file-patterns \ 
@@ -1023,25 +1020,25 @@ kindex(file-sort, completion style)
 item(tt(file-sort))(
 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
+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
+time.  If the style is set to any other value, or is unset, files will be
+sorted alphabetically by name.  If the value contains the string
 `tt(reverse)', sorting is done in decreasing order.
 )
 kindex(force-list, completion style)
 item(tt(force-list))(
-If the completion code would show a list of completions at all, this
-style controls whether the list is shown even in cases when it would
-normally not do that. For example, normally the list is only shown if
-there are at least two different matches. By setting this style to
+This forces a list of completions to be shown at any point where listing is
+done, even in cases where the list would usually be suppressed.
+For example, normally the list is only shown if
+there are at least two different matches.  By setting this style to
 `tt(always)', the list will always be shown, even if there is only a
-single match which is immediately accepted. The style may also
-be set to a number. In this case the list will be shown if there are
+single match which is immediately accepted.  The style may also
+be set to a number.  In this case the list will be shown if there are
 at least that many matches, even if they would all insert the same
 string.
 
@@ -1052,33 +1049,33 @@ for certain types of matches.
 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
+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
+what these matches are.  This string may also contain the sequences to
 specify output attributes, such as `tt(%B)', `tt(%S)' and
 `tt(%{)...tt(%})'.
 
 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
+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 
+`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
+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.
+Finally, when set with the tt(warnings) tag, the format string 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.
 
 The `tt(%)' for the sequences that are replaced by strings provided by 
 the completion functions like the `tt(%d)' may be followed by field
@@ -1101,11 +1098,11 @@ 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 used to give the names for these groups
-for particular tags. For example, in command position the completion
+completions.  This style can be used 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, shell functions and parameters and reserved words as possible
-completions. To have the external commands and shell functions listed
+completions.  To have the external commands and shell functions listed
 separately, one can set:
 
 example(zstyle ':completion:*:*:-command-:*:commands' group-name commands
@@ -1129,7 +1126,7 @@ 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
+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
@@ -1153,12 +1150,12 @@ 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
+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
+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)
@@ -1169,20 +1166,20 @@ 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
+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.
+example, the hostname is already typed, only those ports specified for that
+host will be completed.  Multiple ports for the same host may appear.
 )
 kindex(ignore-line, completion style)
 item(tt(ignore-line))(
-This style is tested for the tags used when generating matches. If it
+This style is tested for the tags used when generating matches.  If it
 is set to `true', then none of the words that are already on the line
 will be considered possible completions.
 
 Note that you almost certainly don't want to set this for a general
-context such as `tt(:completion:*)'. This is because it would disallow
+context such as `tt(:completion:*)'.  This is because it would disallow
 completion of, for example, options multiple times even if the command
 in question accepts the option more than once.
 )
@@ -1226,10 +1223,11 @@ it is possible to complete these directories nonetheless.
 )
 kindex(ignored-patterns, completion style)
 item(tt(ignored-patterns))(
-This style is used with the tags for adding matches and defines a couple
-of patterns. All matches that are also matched by any of these patterns
-are ignored (not offered as completions) until the tt(_ignored) completer
-is tried (see the tt(completer) style).  This is a more configurable
+This style can be used to specify a list of patterns which are tested
+against against the trial completions in a given context; any matching
+completions will be removed from the list of possibilities.  The
+tt(_ignored) completer can appear in the list of completers to produce a
+list which includes these matches once more.  This is a more configurable
 version of the shell parameter tt($fignore).
 
 Note that during the execution of completion functions, the
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 957cb0bf9..162e1af1b 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -4,6 +4,19 @@ cindex(completion, widgets)
 cindex(completion, programmable)
 cindex(completion, controlling)
 sect(Description)
+The shell's programmable completion mechanism can be manipulated in two
+ways; here the low-level features supporting the newer, function-based
+mechanism are defined.  A complete set of shell functions based on these
+features is described in
+ifzman(zmanref(zshcompsys))\
+ifnzman(the next chapter, noderef(Completion System)),
+and users with no interest in adding to that system (or, potentially,
+writing their own --- see dictionary entry for `hubris') should skip this
+section.  The older system based on the tt(compctl) builtin command is
+described in
+ifzman(zmanref(zshcompctly))\
+ifnzman(the chapter noderef(Completion Using compctl)).
+
 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))\
@@ -18,7 +31,7 @@ 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).  Note that this will still
-work even if the widget in question has been rebound.
+work even if the widget in question has been re-bound.
 
 When this newly defined widget is bound to a key
 using the tt(bindkey) builtin command defined in the tt(zsh/zle) module
@@ -76,9 +89,9 @@ to give a common prefix for all matches.
 )
 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
+Initially this will be set to the empty string.  This parameter functions
+like tt(PREFIX); it contains 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:
 
@@ -130,7 +143,7 @@ in which completion is attempted. Possible values are:
 
 startitem()
 item(tt(command))(
-when completing for a normal command (either in a command position or for
+when completing for a normal command (either in command position or for
 an argument of the command).
 )
 item(tt(redirect))(
@@ -138,7 +151,7 @@ when completing after a redirection operator.
 )
 item(tt(condition))(
 when completing inside a `tt([[)...tt(]])' conditional expression; in
-this case the tt(words) array contains the words inside the
+this case the tt(words) array contains only the words inside the
 conditional expression.
 )
 item(tt(math))(
@@ -169,8 +182,8 @@ 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.
+given as argument to tt(vared).  This key is only set while a tt(vared)
+command is active.
 )
 vindex(parameter, compstate)
 item(tt(parameter))(
@@ -198,14 +211,15 @@ 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.
+allows a quoted string to be broken into separate words; if the cursor is
+on one of those words, that word will be completed, possibly invoking
+`tt(compset -q)' recursively.  With this key it is possible to test the
+types of quoted strings which are currently broken into parts in this
+fashion.  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))(
@@ -245,7 +259,7 @@ 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
+explanation strings, if any, will be listed.  It will be set
 appropriately on entry to a completion widget and may be changed
 there.
 )
@@ -258,7 +272,7 @@ 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
+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(BUFFERLINES)
 special parameter.
@@ -376,20 +390,20 @@ command 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 menucompletion 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 menucompletion is
-not selected by other option settings, the code will insert an
-unambiguous string for the generated matches as with normal completion.
+be used whenever a set of matches was generated using pattern matching.  If
+it is set to any other non-empty string by the user and menucompletion is
+not selected by other option settings, the code will instead insert any
+common prefix 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.
+This key is read-only and will always be set to the common (unambiguous)
+prefix 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
+common prefix 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.
 )
@@ -431,11 +445,12 @@ 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 var(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.
+a common path prefix this way.  var(<word>) is the part of the match that
+should appear in the list of completions, i.e. one of the var(words) given
+at the end of the tt(compadd) command line. 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:
 
@@ -607,9 +622,9 @@ 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
+completions.  Instead, the completion code tests whether each var(word) 
+in turn 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(--))(
@@ -695,7 +710,8 @@ 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 
+currently being completed is split on spaces into separate words,
+respecting the usual shell quoting conventions.  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.
@@ -769,10 +785,10 @@ tt(compstate) special association is set to a non-empty string.
 
 The var(spec) given as argument to the tt(-m) option 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.
+whitespace.  Each description consists of a letter followed by a colon
+and 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
@@ -798,7 +814,7 @@ 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.
 
-If no var(lpat) is given, but a var(ranchor), this matches the gap
+If no var(lpat) is given but a var(ranchor) is, this matches the gap
 between substrings matched by var(lanchor) and var(ranchor). Unlike
 var(lanchor), the var(ranchor) only needs to match the trial
 completion string.
@@ -807,7 +823,7 @@ xitem(tt(r:)var(lpat)tt(|)var(ranchor)tt(=)var(tpat))
 xitem(tt(R:)var(lpat)tt(|)var(ranchor)tt(=)var(tpat))
 xitem(tt(r:)var(lanchor)tt(||)var(ranchor)tt(=)var(tpat))
 item(tt(R:)var(lanchor)tt(||)var(ranchor)tt(=)var(tpat))(
-As tt(l) and tt(L) with the difference that the command line and trial
+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(ranchor) forces the match to the end of the command line string.
 )
@@ -833,7 +849,7 @@ 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
+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
@@ -985,10 +1001,3 @@ example(complete-files LPAR()RPAR() { compadd - * })
 
 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 bea2888bc..1aa866dff 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -1147,6 +1147,14 @@ Matches any number in the range var(x) to var(y), inclusive.
 Either of the numbers may be omitted to make the range open-ended;
 hence `tt(<->)' matches any number.  To match individual digits, the
 tt([)...tt(]) form is more efficient.
+
+Be careful when using other wildcards adjacent to patterns of this form;
+for example, tt(<0-9>*) will actually match any number whatsoever at the
+start of the string, since the `tt(<0-9>)' will match the first digit, and
+the `tt(*)' will match any others.  This is a trap for the unwary, but is
+in fact an inevitable consequence of the rule that the longest possible
+match always succeeds.  Expressions such as `tt(<0-9>[^[:digit:]]*)' can be
+used instead.
 )
 item(tt(LPAR())...tt(RPAR()))(
 Matches the enclosed pattern.  This is used for grouping.
@@ -1355,10 +1363,11 @@ appear on its own:  `tt((#s))' and `tt((#e))' are the only valid forms.
 The `tt((#s))' flag succeeds only at the start of the test string, and the
 `tt((#e))' flag succeeds only at the end of the test string; they
 correspond to `tt(^)' and `tt($)' in standard regular expressions.  They
-are useful for matching path segments in patterns.  For example,
-`tt(*((#s)|/)test((#e)|/)*)' matches a path segment `tt(test)' in any of
-the following strings: tt(test), tt(test/at/start), tt(at/end/test),
-tt(in/test/middle).
+are useful for matching path segments in patterns other than those in
+filename generation (where path segments are in any case treated
+separately).  For example, `tt(*((#s)|/)test((#e)|/)*)' matches a path
+segment `tt(test)' in any of the following strings: tt(test),
+tt(test/at/start), tt(at/end/test), tt(in/test/middle).
 
 Another use is in parameter substitution; for example
 `tt(${array/(#s)A*Z(#e)})' will remove only elements of an array which
@@ -1449,6 +1458,13 @@ crucial one for establishing whether to use approximation; for example,
 tt((#a1)abc(#a0)xyz) will not match tt(abcdxyz), because the error occurs
 at the `tt(x)', where approximation is turned off.
 
+Entire path segments may be matched approximately, so that
+`tt((#a1)/foo/d/is/available/at/the/bar)' allows one error in any path
+segment.  This is much less efficient than without the tt((#a1)), however,
+since every directory in the path must be scanned for a possible
+approximate match.  It is best to place the tt((#a1)) after any path
+segments which are known to be correct.
+
 subsect(Recursive Globbing)
 A pathname component of the form `tt(LPAR())var(foo)tt(/RPAR()#)'
 matches a path consisting of zero or more directories
@@ -1466,10 +1482,11 @@ or
 example(ls **/bar)
 
 does a recursive directory search for files named `tt(bar)' (potentially
-including the file `tt(bar)' in the current directory), not following
-symbolic links.  To follow links, use `tt(***/)'.  Neither of these can be
-combined with other forms of globbing within the same filename segment; in
-that case, the `tt(*)' operators revert to their usual effect.
+including the file `tt(bar)' in the current directory).  This form does not
+follow symbolic links; the alternative form `tt(***/)' does, but is
+otherwise identical.  Neither of these can be combined with other forms of
+globbing within the same path segment; in that case, the `tt(*)'
+operators revert to their usual effect.
 subsect(Glob Qualifiers)
 cindex(globbing, qualifiers)
 cindex(qualifiers, globbing)
@@ -1484,7 +1501,8 @@ containing no `tt(|)' or `tt(LPAR())' characters (or `tt(~)' if it is special)
 is taken as a set of
 glob qualifiers.  A glob subexpression that would normally be taken as glob
 qualifiers, for example `tt((^x))', can be forced to be treated as part of
-the glob pattern by doubling the parentheses, for example `tt(((^x)))'.
+the glob pattern by doubling the parentheses, in this case producing
+`tt(((^x)))'.
 
 A qualifier may be any one of the following:
 
@@ -1596,22 +1614,26 @@ permission, and for which other users don't have read or execute
 permission.
 )
 item(tt(e)var(string))(
-The var(string) will be executed and the return value determines if the
-filename should be included in the list (if it is zero) or not (if it
-is non-zero). The first character after the `tt(e)' will be used as a
-separator and anything up to the next matching separator will be taken 
-as the var(string) (`tt([)', `tt({)', and `tt(<)' match `tt(])',
-`tt(})', and `tt(>)' respectively, any other character matches
-itself). Note that expansions have to be quoted in the var(string) to
-prevent them from being expanded before globbing is done.
-
-During the execution of var(string) the parameter tt(REPLY) is set to
-the filename currently being tested. It may also be set to any string
-to make this string be inserted into the list instead of the original
-filename. Also, the parameter tt(reply) may be set to an array or a
-string and if it is, these strings will be inserted instead of the
-value of the tt(REPLY) parameter. For security reasons, tt(reply)
-will be unset by the shell before the var(string) is executed.
+The var(string) will be executed as shell code.  The filename will be
+included in the list if and only if the code returns a zero status (usually
+the status of the last command).  The first character after the `tt(e)'
+will be used as a separator and anything up to the next matching separator
+will be taken  as the var(string); `tt([)', `tt({)', and `tt(<)' match
+`tt(])', `tt(})', and `tt(>)', respectively, while any other character
+matches itself. Note that expansions must be quoted in the var(string)
+to prevent them from being expanded before globbing is done.
+
+During the execution of var(string) the filename currently being tested is
+available in the parameter tt(REPLY); the parameter may be altered to
+a string to be inserted into the list instead of the original
+filename.  In addition, the parameter tt(reply) may be set to an array or a
+string, which overrides the value of tt(REPLY).  If set to an array, the
+latter is inserted into the command line word by word.
+
+For example, suppose a directory contains a single file `tt(lonely)'.  Then
+the expression `tt(*(e:'reply=(${REPLY}{1,2})':))' will cause the words
+`tt(lonely1 lonely2)' to be inserted into the command line.  Note the
+quotation marks.
 )
 item(tt(d)var(dev))(
 files on the device var(dev)
@@ -1708,7 +1730,7 @@ 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))'; `tt(OD)'
+same as `tt(*(Oc))' and `tt(*(^Oc))' is the same as `tt(*(oc))'; `tt(Od)'
 puts files in the current directory before those in subdirectories at each
 level of the search.
 )
diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index c2fc71d55..af21fba82 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -5,7 +5,8 @@ sect(Functions)
 )\
 cindex(functions)
 findex(function)
-The tt(function) reserved word is used to define shell functions.
+Shell functions are defined with the tt(function) reserved word or the
+special syntax `var(funcname) tt(())'.
 Shell functions are read in and stored internally.
 Alias names are resolved when the function is read.
 Functions are executed like commands with the arguments
@@ -30,29 +31,119 @@ sect(Autoloading Functions)
 findex(autoload, use of)
 cindex(autoloading functions)
 cindex(functions, autoloading)
+
 A function can be marked as em(undefined) using the tt(autoload) builtin
 (or `tt(functions -u)' or `tt(typeset -fu)').  Such a function has no
-body.  When the function is first executed, the tt(fpath)
-variable will be searched for a file with the same name as the
-function.
+body.  When the function is first executed, the shell searches for its
+definition using the elements of the tt(fpath) variable.  Thus to define
+functions for autoloading, a typical sequence is:
+
+example(fpath=(~/myfuncs $fpath)
+autoload myfunc1 myfunc2 ...)
+
+The usual alias expansion during reading will be suppressed if the
+tt(autoload) builtin or its equivalent is given the option tt(-U). This is
+recommended for the use of functions supplied with the zsh distribution.
+Note that for functions precompiled with the tt(zcompile) builtin command
+the flag tt(-U) must be created when the tt(.zwc) file is created, as the
+corresponding information is compiled into the latter.
+
+For each var(element) in tt(fpath), the shell looks for three possible
+files, the newest of which is used to load the definition for the function:
+
+startitem()
+item(var(element)tt(.zwc))(
+A file created with the tt(zcompile) builtin command, which is expected to
+contain the definitions for all functions in the directory named
+var(element).  The file is treated in the same manner as a directory
+containing files for functions and is searched for the definition of the
+function.   If the definition is not found, the search for a definition
+proceeds with the the other two possibilities described below.
+
+If var(element) already includes a tt(.zwc) extension (i.e. the extension
+was explicitly given by the user), var(element) is searched for the
+definition of the function without comparing its age to that of other
+files; in fact, there does not need to be any directory named var(element)
+without the suffix.  Thus including an element such as
+`tt(/usr/local/funcs.zwc)' in tt(fpath) will speed up the search for
+functions, with the disadvantage that functions included must be explicitly
+recompiled by hand before the shell notices any changes.  )
+item(var(element)tt(/)var(function)tt(.zwc))( A file created with
+tt(zcompile), which is expected to contain the definition for
+var(function).  It may include other function definitions as well, but
+those are neither loaded nor executed; a file found in this way is searched
+em(only) for the definition of var(function).  )
+item(var(element)tt(/)var(function))( A file of zsh command text, taken to
+be the definition for var(function).  ) enditem()
+
+In summary, the order of searching is, first, directories in tt(fpath),
+with the earliest directory containing a function definition being used;
+within that directory, the newest of the three possibilities --- a compiled
+directory, a compiled function, or an ordinary function defition --- is
+used.
 
 pindex(KSH_AUTOLOAD, use of)
-If the tt(KSH_AUTOLOAD) option is set, or the file contains only a simple
-definition of the function, the file's contents will be
-executed.  It would normally define the function in question, but may
-also perform initialisation.
-It is executed in the context of the function
-execution, and may therefore define local parameters.
-
-Otherwise, the function is defined such that its body is the
-complete contents of the file.  This form allows the file to be
-used directly as an executable shell script.
-Initialisation code can be executed, but only as part of the first
-function execution, so the function would have to redefine itself to
-avoid reinitialising on the next execution.
-
-If this processing of the file results in the function being
-fully defined, the function itself is then executed.
+If the tt(KSH_AUTOLOAD) option is set, or the file contains only a
+simple definition of the function, the file's contents will be executed.
+This will normally define the function in question, but may also perform
+initialization, which is executed in the context of the function execution,
+and may therefore define local parameters.  It is an error if the function
+is not defined by loading the file.
+
+Otherwise, the function body with no surrounding `var(funcname)tt(()
+{)var(...)tt(}) is taken to be the complete contents of the file.  This
+form allows the file to be used directly as an executable shell script.  If
+processing of the file results in the function being re-defined, the
+function itself is not re-executed.  To force the shell to perform
+initialization and then call the function defined, the file should contain
+initialization code (which will be executed then discarded) in addition to
+a complete function definition (which will be retained for subsequent calls
+to the function), and a call to the shell function, including any
+arguments, at the end.
+
+For example, suppose the autoload file tt(func) contains
+
+example(func() { print This is func; }
+print func is initialized
+)
+
+then `tt(func; func)' with tt(KSH_AUTOLOAD) set will produce both messages
+on the first call, but only the message `tt(This is func)' on the second
+and subsequent calls.  Without tt(KSH_AUTOLOAD) set, it will produce
+the initialization message on the first call, and the other message on the
+second and subsequent calls.
+
+It is also possible to create a function that is not marked as autoloaded,
+but which loads its own definition by searching tt(fpath), by using
+`tt(autoload -X)' within a shell function.  For example, the following are
+equivalent:
+
+example(myfunc() {
+  autoload -X
+}
+myfunc args...)
+
+and
+
+example(unfunction myfunc   # if myfunc was defined
+autoload myfunc
+myfunc args...)
+
+In fact, the tt(functions) command outputs `tt(builtin autoload -X)' as
+the body of an autoloaded function.  A true autoloaded function can be
+identified by the presence of the comment `tt(# undefined)' in the body,
+because all comments are discarded from defined functions.  This is done
+so that
+
+example(eval "$(functions)")
+
+produces a reasonable result.
+
+To load the definition of an autoloaded function tt(myfunc) without
+executing tt(myfunc), use:
+
+example(autoload +X myfunc)
+
 sect(Special Functions)
 The following functions, if defined, have special meaning to
 the shell:
@@ -102,6 +193,27 @@ or when the current function exits if defined inside a function.
 )
 findex(TRAPZERR)
 item(tt(TRAPZERR))(
-Executed whenever a command has a non-zero exit status.
+Executed whenever a command has a non-zero exit status.  However, the
+function is not executed if the command occurred in a sublist followed by
+`tt(&&)' or `tt(||)'; only the final command in a sublist of this type
+causes the trap to be executed.
 )
 enditem()
+
+The functions beginning `tt(TRAP)' may alternatively be defined with the
+tt(trap) builtin:  this may be preferable for some uses, as they are then
+run in the environment of the calling process, rather than in their own
+function environment.  Apart from the difference in calling procedure and
+the fact that the function form appears in lists of functions, the forms
+
+example(TRAPNAL() { 
+ # code
+})
+
+and
+
+example(trap '
+ # code
+' NAL)
+
+are equivalent.
diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo
index 3325e2185..d5282d22e 100644
--- a/Doc/Zsh/grammar.yo
+++ b/Doc/Zsh/grammar.yo
@@ -387,5 +387,5 @@ outputs nothing apart from a newline if tt(RC_QUOTES) is not set, but one
 single quote if it is set.
 
 Inside double quotes (tt("")), parameter and
-command substitution occurs, and `tt(\)' quotes the characters
+command substitution occur, and `tt(\)' quotes the characters
 `tt(\)', `tt(`)', `tt(")', and `tt($)'.
diff --git a/Doc/Zsh/metafaq.yo b/Doc/Zsh/metafaq.yo
index a9e0bbecf..65d4f366b 100644
--- a/Doc/Zsh/metafaq.yo
+++ b/Doc/Zsh/metafaq.yo
@@ -11,18 +11,19 @@ sect(Author)
 cindex(author)
 Zsh was originally written by Paul Falstad tt(<pf@zsh.org>).
 Zsh is now maintained by the members of the zsh-workers mailing
-list tt(<zsh-workers@math.gatech.edu>).  The development is currently
-coordinated by Andrew Main (Zefram) tt(<zefram@zsh.org>).  The coordinator
+list tt(<zsh-workers@sunsite.auc.dk>).  The development is currently
+coordinated by Peter Stephenson tt(<pws@zsh.org>).  The coordinator
 can be contacted at tt(<coordinator@zsh.org>), but matters relating to
 the code should generally go to the mailing list.
 texinode(Availability)(Mailing Lists)(Author)(Introduction)
 sect(Availability)
 Zsh is available from the following anonymous FTP sites.  These mirror
-sites are kept frequently up to date.  The sites marked with em((G))
-may be mirroring tt(ftp.math.gatech.edu) instead of the primary site.
-The sites marked with em((H)) may be mirroring tt(ftp.cs.elte.hu)
-instead of the primary site.
+sites are kept frequently up to date.  The sites marked with em((H)) may be
+mirroring tt(ftp.cs.elte.hu) instead of the primary site.
 
+cindex(FTP sites for zsh)
+cindex(acquiring zsh by FTP)
+cindex(availability of zsh)
 startitem()
 item(Primary site)(
 nofill(tt(ftp://ftp.zsh.org/pub/zsh/)
@@ -31,56 +32,61 @@ tt(http://www.zsh.org/pub/zsh/))
 item(Australia)(
 nofill(tt(ftp://ftp.zsh.org/pub/zsh/)
 tt(http://www.zsh.org/pub/zsh/)
-tt(ftp://ftp.ips.oz.au/pub/packages/zsh/)  em((G))  em((H)))
+tt(ftp://ftp.ips.gov.au/pub/packages/zsh/)  em((H)))
 )
 item(Denmark)(
 nofill(tt(ftp://sunsite.auc.dk/pub/unix/shells/zsh/))
 )
 item(Finland)(
-nofill(tt(ftp://ftp.funet.fi/pub/unix/shells/zsh/)  em((H)))
+nofill(tt(ftp://ftp.funet.fi/pub/unix/shells/zsh/))
 )
 item(France)(
 nofill(tt(ftp://ftp.cenatls.cena.dgac.fr/pub/shells/zsh/))
 )
 item(Germany)(
 nofill(tt(ftp://ftp.fu-berlin.de/pub/unix/shells/zsh/)  em((H))
-tt(ftp://ftp.gmd.de/packages/zsh/)  em((H))
-tt(ftp://ftp.uni-trier.de/pub/unix/shell/zsh/)  em((H)))
+tt(ftp://ftp.gmd.de/packages/zsh/)
+tt(ftp://ftp.uni-trier.de/pub/unix/shell/zsh/))
 )
 item(Hungary)(
 nofill(tt(ftp://ftp.cs.elte.hu/pub/zsh/)
 tt(http://www.cs.elte.hu/pub/zsh/)
-tt(ftp://ftp.kfki.hu/pub/packages/zsh/)  em((H)))
+tt(ftp://ftp.kfki.hu/pub/packages/zsh/))
 )
 item(Israel)(
 nofill(tt(ftp://ftp.math.technion.ac.il/mirror/ftp.zsh.org/pub/zsh/)
 tt(http://www.math.technion.ac.il/mirror/ftp.zsh.org/pub/zsh/))
 )
+item(Italy)(
+nofill(tt(ftp://ftp.unina.it/pub/Unix/pkgs/shell/zsh/))
+)
 item(Japan)(
-nofill(tt(ftp://ftp.tohoku.ac.jp/mirror/zsh/)  em((H))
-tt(ftp://ftp.nis.co.jp/pub/shells/zsh/)  em((H)))
+nofill(tt(ftp://ftp.nisiq.net/pub/shells/zsh/)  em((H))
+tt(ftp://ftp.win.ne.jp/pub/shell/zsh/))
 )
 item(Norway)(
-nofill(tt(ftp://ftp.uit.no/pub/unix/shells/zsh/)  em((H)))
+nofill(tt(ftp://ftp.uit.no/pub/unix/shells/zsh/))
+)
+item(Poland)(
+nofill(tt(ftp://sunsite.icm.edu.pl/pub/unix/shells/zsh/))
 )
 item(Romania)(
-nofill(tt(ftp://ftp.roedu.net/pub/mirrors/ftp.zsh.org/pub/zsh/))
+nofill(tt(ftp://ftp.roedu.net/pub/mirrors/ftp.zsh.org/pub/zsh/)
+tt(ftp://ftp.kappa.ro/pub/mirrors/ftp.zsh.org/pub/zsh/))
 )
 item(Slovenia)(
-nofill(tt(ftp://ftp.siol.net/pub/unix/shells/zsh/)  em((H)))
+nofill(tt(ftp://ftp.siol.net/mirrors/zsh/))
 )
 item(Sweden)(
-nofill(tt(ftp://ftp.lysator.liu.se/pub/unix/zsh/)  em((H)))
+nofill(tt(ftp://ftp.lysator.liu.se/pub/unix/zsh/))
 )
 item(UK)(
-nofill(tt(ftp://ftp.net.lut.ac.uk/zsh/)  em((H))
-tt(ftp://sunsite.doc.ic.ac.uk/packages/unix/shells/zsh/)  em((G)))
+nofill(tt(ftp://ftp.net.lut.ac.uk/zsh/)
+tt(ftp://sunsite.org.uk/packages/zsh/))
 )
 item(USA)(
-nofill(tt(ftp://ftp.math.gatech.edu/pub/zsh/)
-tt(ftp://uiarchive.uiuc.edu/pub/packages/shells/zsh/)
-tt(ftp://ftp.sterling.com/zsh/)  em((G))  em((H))
-tt(ftp://ftp.rge.com/pub/shells/zsh/)  em((G))  em((H))
+nofill(tt(ftp://uiarchive.uiuc.edu/pub/packages/shells/zsh/)
+tt(ftp://ftp.rge.com/pub/shells/zsh/)
 tt(ftp://foad.org/pub/zsh/)
 tt(http://foad.org/zsh/))
 )
@@ -91,28 +97,30 @@ cindex(mailing lists)
 Zsh has 3 mailing lists:
 
 startitem()
-item(tt(<zsh-announce@math.gatech.edu>))(
+item(tt(<zsh-announce@sunsite.auc.dk>))(
 Announcements about releases, major changes in the shell and the
 monthly posting of the Zsh FAQ.  (moderated)
 )
-item(tt(<zsh-users@math.gatech.edu>))(
+item(tt(<zsh-users@sunsite.auc.dk>))(
 User discussions.
 )
-item(tt(<zsh-workers@math.gatech.edu>))(
+item(tt(<zsh-workers@sunsite.auc.dk>))(
 Hacking, development, bug reports and patches.
 )
 enditem()
 
-To subscribe, send mail with the SUBJECT `tt(subscribe) var(<e-mail-address>)'
+To subscribe or unsubscribe, send mail
 to the associated administrative address for the mailing list.
 
 startlist()
-list(tt(<zsh-announce-request@math.gatech.edu>))
-list(tt(<zsh-users-request@math.gatech.edu>))
-list(tt(<zsh-workers-request@math.gatech.edu>))
-endlist()
+list(tt(<zsh-announce-subscribe@sunsite.auc.dk>))
+list(tt(<zsh-users-subscribe@sunsite.auc.dk>))
+list(tt(<zsh-workers-subscribe@sunsite.auc.dk>))
 
-Unsubscribing is done similarly.
+list(tt(<zsh-announce-unsubscribe@sunsite.auc.dk>))
+list(tt(<zsh-users-unsubscribe@sunsite.auc.dk>))
+list(tt(<zsh-workers-unsubscribe@sunsite.auc.dk>))
+endlist()
 
 YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED.
 All submissions to bf(zsh-announce) are automatically forwarded to
@@ -121,7 +129,7 @@ forwarded to bf(zsh-workers).
 
 If you have problems subscribing/unsubscribing to any of the mailing
 lists, send mail to tt(<listmaster@zsh.org>).  The mailing lists are
-maintained by Richard Coleman tt(<coleman@zsh.org>).
+maintained by Karsten Thygesen tt(<karthy@kom.auc.dk>).
 
 The mailing lists are archived; the archives can be accessed via the
 administrative addresses listed above.  There is also a hypertext
@@ -135,8 +143,18 @@ newsgroup bf(comp.unix.shell) and the bf(zsh-announce) mailing list.
 The latest version can be found at any of the Zsh FTP sites, or at
 tt(http://www.zsh.org/FAQ/).  The contact address for FAQ-related matters
 is tt(<faqmaster@zsh.org>).
-texinode(The Zsh Web Page)(See Also)(The Zsh FAQ)(Introduction)
+texinode(The Zsh Web Page)(The Zsh Userguide)(The Zsh FAQ)(Introduction)
 sect(The Zsh Web Page)
 Zsh has a web page which is located at tt(http://www.zsh.org/).  This is
 maintained by Karsten Thygesen tt(<karthy@zsh.org>), of SunSITE Denmark.
 The contact address for web-related matters is tt(<webmaster@zsh.org>).
+
+texinode(The Zsh Userguide)(See Also)(The Zsh Web Page)(Introduction)
+sect(The Zsh Userguide)
+A userguide is currently in preparation.  It is intended to complement the
+manual, with explanations and hints on issues where the manual can be
+cabbalistic, hierographic, or downright mystifying (for example, the word
+`hierographic' does not exist).  It can be viewed in its current state at
+tt(http://www.zsh.org/Guide).  As of this writing, chapters dealing with
+startup files and their contents and the new completion system are
+essentially complete.
diff --git a/Doc/Zsh/redirect.yo b/Doc/Zsh/redirect.yo
index 70085a5d2..d65dc133d 100644
--- a/Doc/Zsh/redirect.yo
+++ b/Doc/Zsh/redirect.yo
@@ -143,7 +143,7 @@ pindex(MULTIOS, use of)
 If the user tries to open a file descriptor for writing more than once,
 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:
+provided the tt(MULTIOS) option is set, as it is by default.  Thus:
 
 example(date >foo >bar)
 
diff --git a/Doc/Zsh/restricted.yo b/Doc/Zsh/restricted.yo
index a61fd4955..65baacc59 100644
--- a/Doc/Zsh/restricted.yo
+++ b/Doc/Zsh/restricted.yo
@@ -29,8 +29,6 @@ itemiz(using the tt(ARGV0) parameter to override tt(argv[0]) for external
 commands)
 itemiz(turning off restricted mode with tt(set +r) or tt(unsetopt
 RESTRICTED))
-itemiz(specifying modules to be loaded with an explicitly given
-pathname containing slashes)
 enditemize()
 
 These restrictions are enforced after processing the startup files.  The
@@ -40,5 +38,5 @@ add further restrictions by disabling selected builtins.
 
 Restricted mode can also be activated any time by setting the
 tt(RESTRICTED) option.  This immediately enables all the restrictions
-described above even if the shell still have not processed all startup
+described above even if the shell still has not processed all startup
 files.
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 49c8f8e88..13f25cfb4 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -189,8 +189,9 @@ The current history number.
 )
 vindex(PENDING)
 item(tt(PENDING) (integer))(
-The number of bytes pending for input. On systems where the shell is
-not able to get this information, this parameter will always have a
+The number of bytes pending for input, i.e. the number of bytes which have
+already been typed and can immediately be read. On systems where the shell
+is not able to get this information, this parameter will always have a
 value of zero.
 )
 enditem()