unposted: rewritten compsys.yo down to end of _describe function

2 files changed, 1430 insertions, 1446 deletions

diff --git a/ChangeLog b/ChangeLog
index 18cfe3313..6c03616f4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2003-04-14  Peter Stephenson  <pws@csr.com>
+
+	* unposted: Doc/Zsh/compsys.yo: large-scale but unfinished
+	rewrite.
+
 2003-04-08  Felix Rosencrantz <f_rosencrantz@yahoo.com>
 
 	* 18440: Src/Zle/complete.mdd: Add the cygwin completion functions
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 7e0e8b452..58f985021 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -7,9 +7,9 @@ sect(Description)
 
 This describes the shell code for the new completion system.  It consists
 of various shell functions; those beginning `tt(comp)' are to be called
-directly by the user, while those beginning `tt(_)' are called by the
-completion code.  The shell functions of the second set which implement
-completion behaviour and which may be bound to keystrokes, are referred to
+directly, while those beginning `tt(_)' are called by the
+completion code.  The shell functions of the second set, which implement
+completion behaviour and may be bound to keystrokes, are referred to
 as `widgets'.
 
 startmenu()
@@ -61,7 +61,7 @@ findex(compinit)
 cindex(completion system, initializing)
 
 This section describes the use of tt(compinit) to initialize completion for
-the current session when run directly by the user; if you have run
+the current session when called directly; if you have run
 tt(compinstall) it will be called automatically from your tt(.zshrc).
 
 To initialize the system, the function tt(compinit) should be in a
@@ -83,12 +83,12 @@ bind keys to the old widgets by putting a `tt(.)' in front of the
 widget name, e.g. `tt(.expand-or-complete)'.
 
 To speed up the running of tt(compinit), it can be made to produce a dumped
-configuration which will be read in on future invocations; this is the
-default, although it can be turned off by calling tt(compinit) with the
+configuration that will be read in on future invocations; this is the
+default, but 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), it will read the dumped
+var(dumpfile)'.  The next invocation of tt(compinit) will read the dumped
 file instead of performing a full initialization.
 
 If the number of completion files changes, tt(compinit) will recognise this
@@ -166,55 +166,53 @@ either the name of a command whose arguments are to be completed or one of
 a number of special contexts in the form tt(-)var(context)tt(-) described
 below.
 
-Each var(name) may also be of the form `var(cmd)tt(=)var(service)'.  This
-is used by functions that offer multiple services, i.e. different
-completion behaviour for multiple commands.  Such a string
-makes the completion system call the function when completing
-arguments for the command `tt(cmd)', setting the parameter tt($service) 
-to the string `tt(service)'.  The function can then use that parameter 
-to decide what to complete.
-
-If the list of var(names) contains a tt(-p) or tt(-P) option, the
-following words are taken to be patterns.  When completing for a
-command or context whose name matches one of the patterns, the
-function will be called.  In the case of tt(-P), this will only be
-done if no other completion function for the command or context could
-be found (i.e. this can be used to define default completion for
-commands or contexts matching one of the patterns which don't have a
-completion function specifically defined for them).
-
-If the list contains the tt(-N) option, the following words are used
-as in the normal case again.  Another tt(-p) or tt(-P) option can be
-usedto toggle back to defining patterns again. 
+Each var(name) may also be of the form `var(cmd)tt(=)var(service)'.
+When completing the command var(cmd), the function typically behaves as
+if the command (or special context) var(service) was being completed
+instead.  This provides a way of altering the behaviour of functions
+that can perform many different completions.  It is implemented
+by setting the parameter tt($service) when calling the function;
+the function may choose to interpret this how it wishes, and simpler
+functions will probably ignore it.
+
+If the tt(#compdef) line contains one of the options tt(-p) or tt(-P),
+the words following are taken to be patterns.  The function will be
+called when completion is attempt for a command or context that matches
+one of the patterns.  The options tt(-p) and tt(-P) are used to specify
+patterns to be tried before or after other completions respectively.
+Hence tt(-P) may be used to specify default actions.
+
+The option tt(-N) is used after a list following tt(-p) or tt(-P); it
+specifies that remaining words no longer define patterns.  It is
+possible to toggle between the three options as many times as necessary.
 )
 item(tt(#compdef -k) var(style key-sequences...))(
-This can be used to bind special completion functions to the
-var(key-sequences) specified.  It creates a widget behaving like the
-builtin widget var(style), which must be one of those that perform
+This option creates a widget behaving like the
+builtin widget var(style) and binds it to the given var(key-sequences),
+if any.  The var(style) must be one of the builtin widgets 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 same happens to the tt(menu-select) widget.
+) the widget tt(menu-select) is also available.
 
-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
+When one of the var(key-sequences) is typed, the function in the file will
 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)
-arguments, preceded by a string giving the name of a widget.
-In this case only one var(key-sequences) argument may be given, but the
-entire set of three arguments may be repeated with a different set of
-arguments.  In particular, the var(widget-name) must be distinct in each
-set.  It should begin with `tt(_)', else one will be added, and should not
-clash with the name of any existing widget: names based on the name of the
-function are most useful.  For example,
+This is similar to tt(-k) except that only one var(key-sequences)
+argument may be given for each var(widget-name) var(style) parir.
+However, the entire set of three arguments may be repeated with a
+different set of arguments.  Note in particular that the
+var(widget-name) must be distinct in each set.  If it does not begin with
+`tt(_)' this will be added.  The var(widget-name) should not clash with
+the name of any existing widget: names based on the name of the function
+are most useful.  For example,
 
 example(#compdef -K _foo_complete complete-word "^X^C" \ 
   _foo_list list-choices "^X^D")
@@ -223,15 +221,12 @@ example(#compdef -K _foo_complete complete-word "^X^C" \
 to `tt(^X^C)', and a widget tt(_foo_list) for listing, bound to `tt(^X^D)'.
 )
 item(tt(#autoload) [ var(options) ])(
-This is used for files defining utility functions that are not to be
-called directly as completion functions but should be loaded automatically
-when invoked.  Typically they are to be called from within one of the
-completion functions.
-
-The var(options) will be given to the tt(autoload) builtin command
-when making the function autoloaded.  Most often, this will be tt(+X) to
+Functions with the tt(#autoload) tag are marked for autoloading but
+are not otherwise treated specially.  Typically they are to be called
+from within one of the completion functions.  Any var(options) supplied
+will be passed to the tt(autoload) builtin; a typical use is tt(+X) to
 force the function to be loaded immediately.  Note that the tt(-U) flag is
-always implicitly added.
+always added implicitly.
 )
 enditem()
 
@@ -240,9 +235,9 @@ 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 and cannot be loaded when it is
+tt(KSH_AUTOLOAD) option is not set.  They cannot be loaded if 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
+more tt(zwc) file(s) that 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))\
@@ -254,120 +249,121 @@ The special contexts for which completion functions can be defined are:
 startitem()
 kindex(-array-value-, completion context)
 item(tt(-array-value-))(
-for completion on the right hand side of an array-assignment
-(`tt(foo=LPAR()...RPAR())').
+The right hand side of an array-assignment
+(`tt(foo=LPAR()...RPAR())')
 )
 kindex(-brace-parameter-, completion context)
 item(tt(-brace-parameter-))(
-for completing the name of a parameter expansion within braces
-(`tt(${...})').
+The name of a parameter expansion within braces (`tt(${...})')
 )
 kindex(-assign-parameter-, completion context)
 item(tt(-assign-parameter-))(
-for completing the name of a parameter in an assignment.
+The name of a parameter in an assignment, i.e. on the left hand side of
+an `tt(=)'
 )
 kindex(-command-, completion context)
 item(tt(-command-))(
-for completing in a command position.
+A word In command position
 )
 kindex(-condition-, completion context)
 item(tt(-condition-))(
-for completion inside conditions (`tt([[...]])').
+A word inside a condition (`tt([[...]])')
 )
 kindex(-default-, completion context)
 item(tt(-default-))(
-for generating completions when no special completion function is used.
+Any word for which no other completion is defined
 )
 kindex(-equal-, completion context)
 item(tt(-equal-))(
-for completion of words beginning with an equals sign
+A word beginning with an equals sign
 )
 kindex(-first-, completion context)
 item(tt(-first-))(
-for adding completions before any other completion functions are tried;
-if this function sets the tt(_compskip) parameter to tt(all), no other
-completion functions will be called, if it is set to a string
-containing the substring tt(patterns), no pattern completion functions
-will be called, and if it is set to a string containing tt(default) the
+This is tried before any other completion function.  The function called
+may set the tt(_compskip) parameter to one of various values: 
+tt(all): no further completion is attempted; a string
+containing the substring tt(patterns): no pattern completion functions
+will be called; a string containing tt(default): the
 function for the `tt(-default-)' context will not be called, but
-functions defined for commands will.
+functions defined for commands will
 )
 kindex(-math-, completion context)
 item(tt(-math-))(
-for completion inside mathematical contexts, such as
-`tt(LPAR()LPAR())...tt(RPAR()RPAR())'.
+Inside mathematical contexts, such as
+`tt(LPAR()LPAR())...tt(RPAR()RPAR())'
 )
 kindex(-parameter-, completion context)
 item(tt(-parameter-))(
-for completing the name of a parameter expansion (`tt($...)').
+The name of a parameter expansion (`tt($...)')
 )
 kindex(-redirect-, completion context)
 item(tt(-redirect-))(
-for completion after a redirection operator.
+The word after a redirection operator.
 )
 kindex(-subscript-, completion context)
 item(tt(-subscript-))(
-for completion inside subscripts.
+The contents of a parameter subscript.
 )
 kindex(-tilde-, completion context)
 item(tt(-tilde-))(
-for completion after a tilde (`tt(~)') character, but before a slash.
+After an initial tilde (`tt(~)'), but before the first slash
+in the word.
 )
 kindex(-value-, completion context)
 item(tt(-value-))(
-for completion on the right hand side of an assignment.
+On the right hand side of an assignment.
 )
 enditem()
 
 Default implementations are supplied for each of these
-contexts, in most cases named after the context itself
-(e.g. completion for the `tt(-tilde-)' context is done by the function 
-named `tt(_tilde)').
-
-The functions for some contexts re-dispatch by calling the function
-tt(_dispatch) to offer more specific context information.  This is
-done by appending the parts of extra information to the name of the
-context, separated by commas.  Currently, only the function
-completing redirection arguments (tt(_redirect)) and the function
-completing values in parameter assignments (tt(_value)) use this
-feature.  The former uses contexts of the form
+contexts.  In most cases the context tt(-)var(context)tt(-) is
+implemented by the function tt(_)var(context), for example the context
+`tt(-tilde-)' and the function `tt(_tilde)').
+
+The contexts tt(-redirect-) and tt(-value-) allow extra context-specific
+information.  (Internally, this is handled by the functions for each
+context calling the function tt(_dispatch).)  The extra
+information is added separate by commas.
+
+For the tt(-redirect-) context, the extra information is in the form
 `tt(-redirect-,)var(op)tt(,)var(command)', where var(op) is the
 redirection operator and var(command) is the name of the command on
-the line.  If there isn't a command yet, the var(command) field will
-be empty.  The function completing values uses contexts of the form
-`tt(-value-,)var(name)tt(,)var(command)', where var(name) is the name
-of the parameter (or `var(name)tt(-)var(key)' when completing a
-value of an associative array in an assignment like
-`tt(assoc=LPAR()key <TAB>)').  The var(command) part is the name of
-the command from the line again in completions like `tt(make
-CFLAGS=<TAB>)' and is empty for normal assignments.
-
-To simplify defining functions for multiple cases, the functions
-tt(_redirect) and tt(_value) will make tt(_dispatch) try these context
-names more than once with each of the parts once set to the string
-tt(-default-).  For example, when completing after `tt(foo=<TAB>)',
-tt(_value) will try the names `tt(-value-,foo,)' (note the empty
-var(command) part), `tt(-value-,foo,-default-)' and
-`tt(-value-,-default-,-default-)'.  Also note the order in which the
-contexts are tried.
+the line.  If there is no command on the line yet, the var(command)
+field will be empty.
+
+For the tt(-value-) context, the form is
+`tt(-value-,)var(name)tt(,)var(command)', where var(name) is the name of
+the parameter.  In the case of elements of an associative array, for
+example `tt(assoc=LPAR()key <TAB>)', var(name) is eexpanded to
+`var(name)tt(-)var(key)'.  In certain special contexts, such as
+completing after `tt(make CFLAGS=)', the var(command) part gives the
+name of the command, here tt(make); otherwise it is empty.
+
+It is not necessary to define fully specific completions as the
+functions provided will try to generate completions by progressively
+replacing the elements with `tt(-default-)'.  For example, when
+completing after `tt(foo=<TAB>)', tt(_value) will try the names
+`tt(-value-,foo,)' (note the empty var(command) part),
+`tt(-value-,foo,-default-)' and`tt(-value-,-default-,-default-)', in
+that order, until it finds a function to handle the context.
 
 As an example:
 
 example(compdef '_files -g "*.log"' '-redirect-,2>,-default-')
 
-could be used to complete files matching `tt(*.log)' when completing
-after `tt(2> <TAB>)'.
+completes files matching `tt(*.log)' after `tt(2> <TAB>)' for any
+command with no more specific handler defined.
 
-And:
+Also:
 
 example(compdef _foo -value-,-default-,-default-)
 
-says that the function tt(_foo) is to be called to provide completion
-for the values of parameters for which no special function has been
-defined.
+specifies that tt(_foo) provides completions for the values of
+parameters for which no special function has been defined.  This is
+usually handled by the function tt(_value) itself.
 
-In any case the most specific context name will be used inside the
-context string used for looking up styles.  For example:
+The same lookup rules are used when looking up styles (as described
+below); for example
 
 example(zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log')
 
@@ -376,8 +372,8 @@ matching `tt(*.log)'.
 
 subsect(Functions)
 
-The tt(compinit) file defines the following function, which may
-also be called directly by the user.
+The following function is defined by tt(compinit) and may be called
+directly.
 
 findex(compdef)
 cindex(completion system, adding definitions)
@@ -386,49 +382,45 @@ xitem(tt(compdef) [ tt(-an) ] var(function names...) [ tt(-[pP]) var(patterns...
 xitem(tt(compdef -d) var(names...))
 xitem(tt(compdef -k) [ tt(-an) ] var(function style key-sequences...))
 item(tt(compdef -K) [ tt(-an) ] var(function name style key-sequences ...))(
-The first form tells the completion system to call the given
-var(function) when completing for the contexts or commands
-whose var(names) are given:  this is like the tt(#compdef) tag unless
-the first word contains an equal sign.  In this case all words have to 
-be of the form `var(cmd)tt(=)var(service)' where var(service) is the
-name of a command or of a service defined by an autoloaded function
-with the tt(#compdef) tag and an argument of the form
-`var(cmd)tt(=)var(service)'.  This kind of use makes the arguments of
-the var(cmd)s be completed as those for the var(services).
-
-The var(function) may actually be a string containing any shell code
-and that string will be executed via the tt(eval) builtin command. 
-This allows for the easy definition of completions for commands that
-need to call one of the completion functions with arguments.  For
-example to make files ending in `tt(.h)' be completed as arguments to
-the command tt(foo), one would use:
+The first form defines the var(function) to call for completion in the
+given contexts as described for the tt(#compdef) tag above.
+
+Alternatively, all the arguments may have the form
+`var(cmd)tt(=)var(service)'.  Here var(service) should already have been
+defined by `var(cmd1)tt(=)var(service)' lines in tt(#compdef) files, as
+described above.  The argument for var(cmd) will be completed in the
+same way as var(service).
+
+The var(function) argument may alternatively be a string containing any
+shell code.  The string will be executed using the tt(eval) builtin
+command to generate completions.  This provides a way of avoiding having
+to define a new completion function.  For example, to complete
+files ending in `tt(.h)' as arguments to the command tt(foo):
 
 example(compdef '_files -g "*.h"' foo)
 
-If the tt(-n) option is given, any existing completion behaviour for
-particular contexts or commands will not be altered.  These definitions
-can be deleted by giving the tt(-d) option as in the second form.
-
-In both of the first two forms and as for the tt(#compdef) tag
-described above, the var(names) may also contain tt(-p), tt(-P) and
-tt(-N) options.  The first two make the following arguments be used as
-patterns and the var(function) will be called for all commands and
-contexts matching one of the patterns.  With tt(-P) this will only
-happen if no specific function is defined for the command or context.
-The tt(-N) option toggles back to using the var(names) as described
-above.
-
-Inside functions defined for patterns, the parameter tt($_compskip)
-may be used.  If it is set to a value containing the substring
-`tt(patterns)' none of the pattern-functions will be called.  If it is
+The option tt(-n) prevents any completions already defined for the
+command or context from being overwritten.
+
+The option tt(-d) deletes any completion defined for the command or
+contexts listed.
+
+The var(names) may also contain tt(-p), tt(-P) and tt(-N) options as
+described for the tt(#compdef) tag.  The effect on the argument list is
+identical, switching between definitions of patterns tried initially,
+patterns tried finally, and normal commands and contexts.
+
+The parameter tt($_compskip) may be set by any function defined for a
+pattern context.  If it is set to a value containing the substring
+`tt(patterns)' none of the pattern-functions will be called; if it is
 set to a value containing the substring `tt(all)', no other function
 will be called.
 
 The form with tt(-k) defines a widget with the same name as the var(function)
-which will be called for each of the var(key-sequences); this is like the
+that will be called for each of the var(key-sequences); this is like the
 tt(#compdef -k) tag.  The function should generate the completions needed
 and will otherwise behave like the builtin widget whose name is given as
-the var(style) argument. The widgets usable for this are:
+the var(style) argument.  The widgets usable for this are:
 tt(complete-word), tt(delete-char-or-list), tt(expand-or-complete),
 tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete),
 tt(menu-expand-or-complete), and tt(reverse-menu-complete), as well as
@@ -442,25 +434,21 @@ var(name), var(style) and var(key-sequences), where the latter two are as
 for tt(-k) and the first must be a unique widget name beginning with an
 underscore.
 
-In each of the forms supporting it the tt(-a) option makes the
-var(function) autoloadable (exactly equivalent to
-tt(autoload -U )var(function)).
+Wherever applicable, the tt(-a) option makes the var(function)
+autoloadable, equivalent to tt(autoload -U )var(function).
 )
 enditem()
 
-The tt(compdef) function is the place to turn to when one wants to
-define what the completion system should complete for a certain
-command.  The function named can of course be one of the functions
-supplied or one written by the user.  For example, if one has a
-command tt(foo) that gets process identifiers as arguments, one could
-do:
+The function tt(compdef) can be used to associate existing completion
+functions with new commands.  For example,
 
 example(compdef _pids foo)
 
-using the tt(_pids) function from the distribution to generate the
-process identifiers.  Note also the tt(_gnu_generic) function described
-below, which can be used to complete options for commands that
-understand the `tt(-)tt(-help)' option.
+uses the function tt(_pids) to complete process IDs for the command tt(foo).
+
+Note also the tt(_gnu_generic) function described below, which can be
+used to complete options for commands that understand the
+`tt(-)tt(-help)' option.
 
 texinode(Completion System Configuration)(Control Functions)(Initialization)(Completion System)
 sect(Completion System Configuration)
@@ -472,18 +460,19 @@ generated.
 
 subsect(Overview)
 
-When completion is attempted somewhere on a command line the
-completion system first tries to find out the context where completion 
-was tried.  The context depends on such things as the name of the
-command when completing an argument, and possibly also
-the name of an option when completing an argument to that option.
+When completion is attempted somewhere on the command line the
+completion system first works out the context.  This takes account of a
+number of things including the command word (such as `tt(grep)' or
+`tt(zsh)') and options to which the current word may be an argument
+(such as the `tt(-o)' option to tt(zsh) which takes a shell option as an
+argument).
 
-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.
+This context information is condensed into a string consisting of
+multiple fields separated by colons, referred to simply as `the context'
+in the remainder of the documentation.  This is used to look up
+em(styles), context-sensitive options that can be used to configure the
+completion system.  The context used for lookup may vary during the same
+call to the completion system.
 
 The context string always consists of the following fields, separated
 by colons and with a leading colon before the first:
@@ -491,46 +480,49 @@ by colons and with a leading colon before the first:
 startitemize()
 itemiz(\
 The literal string tt(completion), saying that this style is used by
-the completion system.
+the completion system.  This distinguishes the context from those used
+by, for example, zle widgets and ZFTP functions.
 )
 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(Widget) directory of 
-the distribution, this field contains the name of that function, often
-in an abbreviated form.
+The var(function), if completion is called from a named widget rather
+than through the normal completion system.  Typically this is blank, but
+it is set by special widgets such as tt(predict-on) and the various
+functions in the tt(Widget) directory of the distribution to the name of
+that function, often in an abbreviated form.
 )
 itemiz(\
-The var(completer) currently active, which is the name of the function
+The var(completer) currently active, 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
-later completer (see
+is the simplest, but other completers exist to perform
+related tasks such as correction, or to modify the behaviour of a
+later completer.  See
 ifzman(the section `Control Functions' below)\
 ifnzman(noderef(Control Functions)) 
-for more information).  
+for more information.  
 )
 itemiz(\
-The var(context) or var(command).  This is either one of the special
-context names such as tt(-condition-) as explained for the
-tt(#compdef) tag above, or the name of the command we are
-completing arguments for.  Completion functions for commands that have
-sub-commands usually modify this field to contain the name of the
-command followed by a minus sign and the sub-command (e.g. the
-completion function for the tt(cvs) command sets this field to strings
-such as tt(cvs-add) when completing for the tt(add) sub-command).
+The var(command) or a special tt(-)var(context)tt(-), just at it appears
+following the tt(#compdef) tag or the tt(compdef) function.  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.  For example, the completion function for the tt(cvs)
+command sets this field to tt(cvs-add) when completing arguments to
+the tt(add) subcommand.
 )
 itemiz(\
-The var(argument), describing which argument we are
-completing.  Normally this is either a string of the form
-tt(argument-)var(n), where var(n) is the number of the argument or it
-is a string of the form tt(option-)var(opt)tt(-)var(n) when completing the
-var(n)'th argument of the option var(opt).
+The var(argument); this indicates which command line or option argument
+we are completing.  For command arguments this generally takes the form
+tt(argument-)var(n), where var(n) is the number of the argument,
+and for arguments to options the form tt(option-)var(opt)tt(-)var(n)
+where var(n) is the number of the argument to option var(opt).  However,
+this is only the case if the command line is parsed with standard
+UNIX-style options and arguments, so many completions do not set this.
 )
 itemiz(\
 The var(tag).  Tags are used to discriminate between the types
-of matches a completion function can generate in a certain context.
+of matches a completion function can generate in a certain context and
+are described further below.
 )
 enditemize()
 
@@ -538,45 +530,41 @@ As an example, the context name
 
 example(tt(:completion::complete:dvips:option-o-1:files))
 
-says that normal completion was attempted on an argument of the tt(dvips)
-command (more precisely: completion was attempted on the first argument
-after the tt(-o) option) and the completion function will generate
-filenames for this context.
-
-In many of the possible contexts the completion system can generate
-matches, often multiple types of matches.  These types are represented as
-simple names called `tags'.  The completion system will decide internally
-what sort of tags are allowed; a list of the standard possibilities is given
-below.  To determine in which order the tags are to be used by the
-completion function, the `tt(tag-order)' style for the appropriate
-context may be set, as described in the list of standard styles below.
-Only those types of matches whose tags were selected by this style
-will be produced, and in the order given, 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 
+says that normal completion was attempted as the first arguement to the
+option tt(-o) of the command tt(dvips):
+
+example(tt(dvips -o ...))
+
+and the completion function will generate filenames.
+
+Each type of completion the system can perform in a given context is
+described by a `tag', a short descriptive string such as tt(files) in
+the example above.  Any completion function may use any tag name it
+likes, but a list of the more common ones is given below.
+
+Usually completion will be tried by all possible tags in an order given
+by the completion function.  However, this can be altered by using the
+tt(tag-order) style.  Completion is then limited to the list of given
+tags in the given order.
+
+The tt(_complete_help) bindable command shows all the contexts and tags
+available for completion at a particular point.  This provides an easy
+way of finding information for tt(tag-order) and other styles.  It is
+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 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 (\
+ifnzman(noderef(Bindable Commands)).
+
+Styles determine such things as how the matches are generated, similarly
+to shell options but with much more control.  They can have any number
+of strings as their value.  They are defined with the tt(zstyle) builtin
+command (\
 ifzman(see zmanref(zshmodules))\
 ifnzman(noderef(The zsh/zutil Module))).
-When looking up styles the completion system uses full context names,
-including the tag.
 
-Styles determine such things as how the matches are generated; some of them
-correspond to shell options (for example, the use of menu completion), but
-styles provide more specific control.  They can have any number of strings as
-their value.  Looking up the value of a style therefore consists of two
-things:  the context, which may be matched as a pattern, and the name of
-the style itself, which must be given exactly.
+When looking up styles the completion system uses full context names,
+including the tag.  Looking up the value of a style therefore consists
+of two things:  the context, which may be matched as a pattern, and the
+name of the style itself, which must be given exactly.
 
 For example, many completion functions can generate matches in a
 simple and a verbose form and use the tt(verbose) style to decide
@@ -585,37 +573,33 @@ put
 
 example(zstyle ':completion:*' verbose yes)
 
-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 context pattern were `tt(*)',
-the verbose style would have this value anywhere the style mechanism is
-used, not just in completion.
+in a startup file (probably tt(.zshrc)).
+This gives the tt(verbose) style the value tt(yes) in every
+context inside the completion system, unless that context has a more
+specific definition.  It is best to avoid giving the context as `tt(*)'
+in case the style has some meaning outside the completion system.
 
-As a more specific example, the completion function for the tt(kill)
-builtin command uses the tt(verbose) style to decide if jobs and processes
-are listed only as job numbers and process identifiers or if they are
-listed with the full job texts and the command lines of the processes (the
-latter is achieved by calling the tt(ps) command).  To make this builtin
-list the matches only as numbers one could call:
+Many such general purpose styles can be configured simply by using the
+tt(compinstall) function.
+
+A more specific example of the use of the tt(verbose) style is by the
+completion for the tt(kill) builtin.  If the style is set, the builtin
+lists full job texts and process command lines; otherwise it shows the
+bare job numbers and PIDs.  To turn the style off for this use only:
 
 example(zstyle ':completion:*:*:kill:*' verbose no)
 
-Furthermore, if one wanted to see the command lines for processes but not the
-job texts one could use the fact that the context name contains the tag name
-when styles are looked up.  As the function for the tt(kill)
-builtin command uses the tags tt(jobs) and tt(processes), we can use:
+For even more control, the style can use one of the tags `tt(jobs)' or
+`tt(processes)'.  To turn off verbose display only for jobs:
 
 example(zstyle ':completion:*:*:kill:*:jobs' verbose no)
 
-To have more control over when certain values for styles are used one
-can use the special parameters available in completion widgets (see
+The tt(-e) option to tt(zstyle) even allows completion function code to
+appear as the argument to a style; this requires some understanding of
+the internals of completion functions (see
 ifzman(see zmanref(zshcompwid))\
 ifnzman(noderef(Completion Widgets)))\
-) and the tt(-e) option to tt(zstyle) that makes the value be
-evaluated when looked up.  For example, to make the tt(completer)
-style have a different value when completing for the tt(cvs) command,
-one could use the tt(words) special array:
+).  For example:
 
 example(zstyle -e ':completion:*' completer '
     if [[ $words[1] = cvs ]]; then
@@ -624,15 +608,12 @@ example(zstyle -e ':completion:*' completer '
       reply=(_complete _approximate)
     fi')
 
-One should be careful not to use too complicated code with this
-option, at least for the styles that are looked up quite often.  These 
-are basically those that define some global completion behaviour but
-allow that to be different for all matches or groups of matches (such
-as the tt(menu) and tt(list-rows-first) styles).  Alternatively one
-can always use a less general pattern for the context than in the
-example above and use a second call to tt(zstyle) with a generic
-pattern and without using the tt(-e) option to define the default
-behaviour.
+uses the value `tt(_complete)' for the tt(completer) style in most
+contexts, but the value `tt(_complete _approximate)' when the first word
+on the command line is `tt(cvs)'.  This is probably more conviently done
+by specifying the style for two different contexts.  This form can be
+slow and should be avoided for commonly examined styles such
+as tt(menu) and tt(list-rows-first).
 
 Note that the order in which styles are em(defined) does not matter; the
 style mechanism uses the most specific possible match for a particular
@@ -641,17 +622,15 @@ 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 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.
+Style names like those of tags are arbitrary and depend on the completion
+function.  However, the following two sections list some of the most
+common tags and styles.
 
 subsect(Standard Tags)
 cindex(completion system, tags)
 
-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.
+Some of the following are only used when looking up particular styles
+and do not refer to a type of match.
 
 startitem()
 kindex(accounts, completion tag)
@@ -670,7 +649,7 @@ tt(globbed-files) tag).
 )
 kindex(arguments, completion tag)
 item(tt(arguments))(
-when an argument of a command may be completed
+for arguments to a command
 )
 kindex(arrays, completion tag)
 item(tt(arrays))(
@@ -679,7 +658,7 @@ for names of array parameters
 kindex(association-keys, completion tag)
 item(tt(association-keys))(
 for keys of associative arrays; used when completing inside a
-subscript of a parameter of this type
+subscript to a parameter of this type
 )
 kindex(bookmarks, completion tag)
 item(tt(bookmarks))(
@@ -691,7 +670,7 @@ for names of builtin commands
 )
 kindex(characters, completion tag)
 item(tt(characters))(
-used for commands like tt(stty) when completing characters; also used
+for single characters in arguments of commands such as tt(stty).   Also used
 when completing character classes after an opening bracket
 )
 kindex(colormapids, completion tag)
@@ -704,16 +683,16 @@ for color names
 )
 kindex(commands, completion tag)
 item(tt(commands))(
-for names of external commands and names of sub-commands (used by some 
-commands like tt(cvs))
+for names of external commands.  Also used by complex commands such as
+tt(cvs) when completing names subcommands.
 )
 kindex(contexts, completion tag)
 item(tt(contexts))(
-for contexts used by the zstyle builtin command
+for contexts in arguments to the tt(zstyle) builtin command
 )
 kindex(corrections, completion tag)
 item(tt(corrections))(
-used by the tt(_approximate) and tt(_correct) completers for the possible
+used by the tt(_approximate) and tt(_correct) completers for possible
 corrections
 )
 kindex(cursors, completion tag)
@@ -722,14 +701,14 @@ for cursor names used by X programs
 )
 kindex(default, completion tag)
 item(tt(default))(
-used to look up default values for various styles that may also be set 
-for tags that are used when generating matches; note that this tag is
-used when only the var(function) field of the context name is set up
+used in some contexts to provide a way of supplying a default when more
+specific tags are also valid.  Note that this tag is
+used when only the var(function) field of the context name is set
 )
 kindex(descriptions, completion tag)
 item(tt(descriptions))(
-used when looking up the value of the tt(format) style for
-descriptions
+used when looking up the value of the tt(format) style to generate
+descriptions for types of matches
 )
 kindex(devices, completion tag)
 item(tt(devices))(
@@ -753,8 +732,9 @@ for network domains
 )
 kindex(expansions, completion tag)
 item(tt(expansions))(
-used by the tt(_expand) completer for individual possibilities resulting
-from expansion of a word
+used by the tt(_expand) completer for individual words (as opposed to
+the complete set of expansions) resulting from the expansion of a word
+on the command line
 )
 kindex(extensions, completion tag)
 item(tt(extensions))(
@@ -762,35 +742,32 @@ for X server extensions
 )
 kindex(file-descriptors, completion tag)
 item(tt(file-descriptors))(
-for the numbers of open file descriptors
+for numbers of open file descriptors
 )
 kindex(files, completion tag)
 item(tt(files))(
-the generic file-matching tag used by completion functions that can
-complete the names of some kind of file
+the generic file-matching tag used by functions completing filenames
 )
 kindex(fonts, completion tag)
 item(tt(fonts))(
-used for X font names
+for X font names
 )
 kindex(fstypes, completion tag)
 item(tt(fstypes))(
-used when completing the available file system types (e.g. for the
-tt(mount) command)
+for file system types (e.g. for the tt(mount) command)
 )
 kindex(functions, completion tag)
 item(tt(functions))(
-names of functions, normally shell functions although certain commands may
-understand other kinds of function
+names of functions --- normally shell functions, although certain
+commands may understand other kinds of function
 )
 kindex(globbed-files, completion tag)
 item(tt(globbed-files))(
-for names of files matching the glob pattern used by completion
-functions that expect a certain type of file
+for filenames when the name has been generated by pattern matching
 )
 kindex(groups, completion tag)
 item(tt(groups))(
-used when completing names of user groups
+for names of user groups
 )
 kindex(history-words, completion tag)
 item(tt(history-words))(
@@ -802,11 +779,11 @@ for hostnames
 )
 kindex(indexes, completion tag)
 item(tt(indexes))(
-used for array indexes
+for array indexes
 )
 kindex(jobs, completion tag)
 item(tt(jobs))(
-used for jobs
+for jobs (as listed by the `tt(jobs)' builtin)
 )
 kindex(interfaces, completion tag)
 item(tt(interfaces))(
@@ -830,8 +807,9 @@ for system limits
 )
 kindex(local-directories, completion tag)
 item(tt(local-directories))(
-for names of directories which are subdirectories of the current working
-directory when completing for the tt(cd) and related builtin commands
+for names of directories that are subdirectories of the current working
+directory when completing arguments of tt(cd) and related builtin
+commands (compare tt(path-directories))
 )
 kindex(manuals, completion tag)
 item(tt(manuals))(
@@ -884,7 +862,7 @@ for command options
 kindex(original, completion tag)
 item(tt(original))(
 used by the tt(_approximate), tt(_correct) and tt(_expand) completers when
-adding the original string
+offering the original string as a match
 )
 kindex(other-accounts, completion tag)
 item(tt(other-accounts))(
@@ -901,7 +879,8 @@ for names of parameters
 kindex(path-directories, completion tag)
 item(tt(path-directories))(
 for names of directories found by searching the tt(cdpath) array when
-completing for the tt(cd) and related builtin commands
+completing arguments of tt(cd) and related builtin commands (compare
+tt(local-directories))
 )
 kindex(paths, completion tag)
 item(tt(paths))(
@@ -984,8 +963,7 @@ for usernames
 )
 kindex(values, completion tag)
 item(tt(values))(
-when completing a value out of a set of values (or a list of such
-values)
+for one of a set of values in certain lists
 )
 kindex(variant, completion tag)
 item(tt(variant))(
@@ -1017,80 +995,82 @@ enditem()
 subsect(Standard Styles)
 cindex(completion system, styles)
 
-Here are the names of the styles used by the completion system.  Note
-that the values of several of these styles represent boolean
-values; 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; in particular, the default value may be either on or off
-if the style is not set.
-
-Some of these styles are tested for every tag used to add possible
-matches and for the tt(default) tag (most notably tt(menu),
-tt(list-colors) and the styles controlling the completion listing like 
-tt(list-packed) and tt(last-prompt)). When tested for the tt(default)
-tag, only the var(function) field of the context will be set up, so
-the default value will normally be set like:
+Note that the values of several of these styles represent boolean
+values.  Any of the strings `tt(true)', `tt(on)',
+`tt(yes)', and `tt(1)' can be used for the value `true' and
+any of the strings `tt(false)', `tt(off)', `tt(no)', and `tt(0)' for
+the value `false'.  The behavior for any other value is undefined 
+except where explicitly mentioned.  The default value may
+be either true or false if the style is not set.
+
+Some of these styles are tested first for every possible tag
+corresponding to a type of match, and if no style was found, for the
+tt(default) tag.  The most notable styles of this type are tt(menu), 
+tt(list-colors) and styles controlling completion listing such as 
+tt(list-packed) and tt(last-prompt)).  When tested for the tt(default)
+tag, only the var(function) field of the context will be set so that
+a style using the default tag will normally be defined along the lines of:
 
 example(zstyle ':completion:*:default' menu ...)
 
 startitem()
 kindex(accept-exact, completion style)
 item(tt(accept-exact))(
-This is tested for the default tag and the tags used when generating
-matches.  If it is set to `true' for at least one match which is the
-same as the string on the line, this match will immediately be
-accepted.
-
-When completing pathnames (where it is looked up for the tt(paths)
-tag), this style also accepts any number of patterns as the value. If
-this is used, pathnames matching one of these patterns will be
-accepted immediately even if the command line contains some more
-partially typed pathname components and these match no file under the
-directory accepted.
-
-Note that this is also used by the tt(_expand) completer to decide if
+This is tested for the default tag in addition to the tags valid for
+the current context.  If it is set to `true' and any of the trial
+matches is the same as the string on the command line, this match will
+immediately be accepted (even if it would otherwise be considered
+ambiguous).
+
+When completing pathnames (where the tag used is `tt(paths)')
+this style accepts any number of patterns as the value in addition to
+the boolean values.  Pathnames matching one of these
+patterns will be accepted immediately even if the command line contains
+some more partially typed pathname components and these match no file
+under the directory accepted.
+
+This style is also used by the tt(_expand) completer to decide if
 words beginning with a tilde or parameter expansion should be
-expanded. This means that if, for example, there are parameters
+expanded.  For example, if there are parameters
 tt(foo) and tt(foobar), the string `tt($foo)' will only be expanded if 
-tt(accept-exact) is set to `true'.
+tt(accept-exact) is set to `true'; otherwise the completion system will
+be allowed to complete tt($foo) to tt($foobar).
 )
 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).  The value
-may also be the string `tt(file)' to make the completer add a space
-only to names of existing files.  Finally, the `true' values and
-`tt(file)' may be combined with `tt(subst)' to keep the completer from 
-adding a space when the resulting words were generated by expanding a
+expansion, or a slash in the case of directory names.  If the value
+is `tt(file)', the completer will only add a space
+to names of existing files.  Either a boolean true or the value
+`tt(file)' may be combined with `tt(subst)', in which case the completer
+will not add a space to words generated from the expansion of a
 substitution of the form `tt($LPAR()...RPAR())' or `tt(${...})'.
 
-It is also used by the tt(_prefix) completer as a simple boolean value
+The tt(_prefix) completer uses this style as a simple boolean value
 to decide if a space should be inserted before the suffix.
 )
 kindex(ambiguous, completion style)
 item(tt(ambiguous))(
-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 menu completion is in use.  It is tested with the tt(paths) tag.
+This applies when completing non-final components of filename paths, in
+other words those with a trailing slash.  If it is set, the cursor is
+left after the first ambiguous component, even if menu completion is in
+use.  The style is always tested with the tt(paths) tag.
 )
 kindex(assign-list, completion style)
 item(tt(assign-list))(
-When completing after an equals sign, the completion system normally
-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.
+When completing after an equals sign that is being treated as an
+assignment, the completion system normally completes only one filename.
+In some cases the value  may be a list of filenames separated by colons,
+as with tt(PATH) and similar parameters.  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.
 )
 kindex(auto-description, completion style)
 item(tt(auto-description))(
-If set, this style's value will be used as the description for options which
+If set, this style's value will be used as the description for options that
 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,
@@ -1112,13 +1092,13 @@ with all matches will almost never be wanted.
 kindex(cache-path, completion style)
 item(tt(cache-path))(
 This style defines the path where any cache files containing dumped
-completion data are stored.  Defaults to `tt($ZDOTDIR/.zcompcache)', or
+completion data are stored.  It defaults to `tt($ZDOTDIR/.zcompcache)', or
 `tt($HOME/.zcompcache)' if tt($ZDOTDIR) is not defined.  The completion
-layer will not be used unless the tt(use-cache) style is set.
+cache will not be used unless the tt(use-cache) style is set.
 )
 kindex(cache-policy, completion style)
 item(tt(cache-policy))(
-This style defines the function which will be used to determine whether
+This style defines the function that will be used to determine whether
 a cache needs rebuilding.  See the section on the tt(_cache_invalid)
 function below.
 )
@@ -1126,17 +1106,17 @@ kindex(call-command, completion style)
 item(tt(call-command))(
 Currently this is only used by the function completing tt(make)
 targets.  If it is set to `true' and the installed version of the
-tt(make) command allows it, tt(make) is called in a way to generate
-all possible targets.  The default value of this style is `false'
-because calling tt(make) can potentially take a very long time and in
+tt(make) command allows it, tt(make) is called in such a way as to
+generate all possible targets.  The default value of this style is `false'
+since calling tt(make) can potentially take a very long time and in
 some cases may even cause actions from the makefile be executed
-despite the options given to tt(make).
+despite the options passed to tt(make).
 )
 kindex(command, completion style)
 item(tt(command))(
 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
+command that 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
@@ -1144,7 +1124,7 @@ 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
+As an example, the completion function for process IDs uses this
 style with the tt(processes) tag to generate the IDs to complete and
 the list of processes to display (if the tt(verbose) style is `true').
 The list produced by the command should look like the output of the
@@ -1154,16 +1134,16 @@ process IDs in the following lines.  If the line does not contain
 `tt(PID)', the first numbers in each of the other lines are taken as the 
 process IDs to complete.
 
-Note that the completion function generally has to call the command
-every time it is called.  Because of that care should be taken to
-specify only commands that take a short time to run (and that will
-eventually stop at all).
+Note that the completion function generally has to call the specified
+command for each attempt to generate the completion list.  Hence
+care should be taken to specify only commands that take a short
+time to run, and in particular to avoid any that may never terminate.
 )
 kindex(commands, completion style)
 item(tt(commands))(
 This is used by the function completing sub-commands for the system
 initialisation scripts (residing in tt(/etc/init.d) or somewhere not
-too far away from that).  It's values give the default commands to
+too far away from that).  Its values give the default commands to
 complete for those commands for which the completion function isn't
 able to find them out automatically.  The default for this style are
 the two strings `tt(start)' and `tt(stop)'.
@@ -1184,14 +1164,14 @@ ifzman(the section `Control Functions' below)\
 ifnzman(noderef(Control Functions))\
 .
 
-Each string may be the name of a completer function or a string of the 
-form `var(function)tt(:)var(name)'. In the first case the
+Each string may be either 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 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
+will contain the user-defined var(name) in the var(completer) field of
+the context.  If the var(name) starts with a hyphen, the string for the
 context will be build from the name of the completer function as in
 the first case with the var(name) appended to it.  For example: 
 
@@ -1200,16 +1180,15 @@ example(zstyle ':completion:*' completer _complete _complete:-foo)
 Here, completion will call the tt(_complete) completer twice, once
 using `tt(complete)' and once using `tt(complete-foo)' in the
 var(completer) field of the context.  Normally, using the same
-completer more than once makes only sense when used with the
+completer more than once only makes 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
 exceptions to this rule are the tt(_ignored) and tt(_prefix)
 completers.
 
-The default value for this style is tt(_complete _ignored),
-i.e. normally only completion will be done, first using the
-tt(ignored-patterns) style and the tt($fignore) array and then without 
-ignoring matches.
+The default value for this style is `tt(_complete _ignored)':
+only completion will be done, first using the tt(ignored-patterns) style
+and the tt($fignore) array and then without ignoring matches.
 )
 kindex(condition, completion style)
 item(tt(condition))(
@@ -1225,47 +1204,43 @@ command will try to expand disabled aliases, too.  The default is
 )
 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
+This is used with an empty tag by the tt(_cvs) function
+to decide whether the tt(zsh/stat) module should be used to
 generate names of modified files in the appropriate places (this is its
-only use).  If set, completion will use the tt(ls) command.
+only use).  If the style is 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 will be taken from
+A list of names of network domains for completion.
+If this is not set, 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 one of its values is
-the string `tt(prefix)', the partially typed word from
-the line will be expanded as far as possible even if trailing parts
-cannot be completed.  If one of its values is the string `tt(suffix)',
-matching names for
-components after the first ambiguous one will also be added.  This
-means that the resulting string is the longest unambiguous string
-possible, but if menu completion is started on the list of matches
-generated this way,
-this will also cycle through the names of the files in pathname
-components after the first ambiguous one.
+parts, such as path names.
+
+If one of its values is the string `tt(prefix)', the partially typed
+word from the line will be expanded as far as possible even if trailing
+parts cannot be completed.
+
+If one of its values is the string `tt(suffix)', matching names for
+components after the first ambiguous one will also be added.  This means
+that the resulting string is the longest unambiguous string possible.
+However, menu completion can be used to cycle through all matches.
 )
 kindex(fake, completion style)
 item(tt(fake))(
-This style may be set for every completion context and is used to
-specify additional strings to complete in that context.  It's values
-are either the strings to complete with every colon quoted by a
-preceding backslash or strings of the form
-`var(string)tt(:)var(description)'.  In the latter case the var(string)s
-will be shown together with the var(description)s in completion
-listings.
-
-Note that you only really want to use this style for a narrow
-enough context, so that the additional string won't show up in other
-contexts.  Also note the styles tt(fake-files) and tt(fake-parameters)
-which give more control over additional strings to add when completing
-files or parameters.
+This style may be set for any completion context.  It
+specifies additional strings that may always be completed in that
+context.  The form of each string is `var(value)tt(:)var(description)'; 
+the colon and description may be omitted, but any literal colons in
+var(value) must be quoted with a backslash.  Any var(description)
+provided is shown alongside the value in completion listings.
+
+It is important to use a sufficiently restricted context when specifying
+fake strings.  Note that the styles tt(fake-files) and tt(fake-parameters)
+provide additional features when completing files or parameters.
 )
 kindex(fake-files, completion style)
 item(tt(fake-files))(
@@ -1283,99 +1258,94 @@ permission.
 )
 kindex(fake-parameters, completion style)
 item(tt(fake-parameters))(
-This is used by the completion function generating parameter names as
-matches.  Its values are names of parameters which might not yet be
-set, but which should be completed nonetheless.  Each name may also be 
+This is used by the completion function for parameter names.
+Its values are names of parameters that might not yet be
+set but should be completed nonetheless.  Each name may also be 
 followed by a colon and a string specifying the type of the parameter
-(like `tt(scalar)', `tt(array)' or `tt(integer)').  If such a type is
+(like `tt(scalar)', `tt(array)' or `tt(integer)').  If the type is
 given, the name will only be completed if parameters of that type are
-requested in the particular context.  Names for which no type is
+required in the particular context.  Names for which no type is
 specified will always be completed.
 )
 kindex(file-patterns, completion style)
 item(tt(file-patterns))(
-In most places where filenames are completed, the function tt(_files)
-is used which can be configured with this style.  If the style is
-unset, tt(_files) offers, 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).  The first two
+This is used by the standard function for completing filenames,
+tt(_files).  If the style is unset up to three tags are offered,
+`tt(globbed-files)',`tt(directories)' and `tt(all-files)', depending on
+the types of files  expected by the caller of tt(_files).  The first two
 (`tt(globbed-files)' and `tt(directories)') are normally offered
 together to make it easier to complete files in sub-directories.
 
-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
-specifications of the form
+The tt(file-patterns) style provides alternatives to the default tags,
+which are not used.  Its value consists of elements of the form
 `var(pattern)tt(:)var(tag)'; each string may contain any number of
-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
-the pattern(s) given by the calling function.
-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
-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
-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
-var(tag) may also be
-followed by an optional second colon and a description.  If that is
-given, this description will be used for the `tt(%d)' in the value of
+such specifications separated by spaces.
+
+The var(pattern) is a pattern that is to be used to generate filenames.
+Any occurence of the sequence `tt(%p)' is replaced by any pattern(s)
+passed by the function calling tt(_files).  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 var(tag)s of all strings in the value will be offered by tt(_files)
+and used when looking up other styles.  Any var(tag)s in the same
+word will be offered at the same time and before later words.
+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, which will be used for the `tt(%d)' in the value of
 the tt(format) style (if that is set) instead of the default
 description supplied by the completion function.  If the description
 given here contains itself a `tt(%d)', that is replaced with the
 description supplied by the completion function.
 
 For example, to make the tt(rm) command first complete only names of
-object files and the names of all files if no object file matches
-the string on the line, one would do:
+object files and then the names of all files if there is no matching
+object file:
 
 example(zstyle ':completion:*:*:rm:*' file-patterns \ 
     '*.o:object-files' '%p:all-files')
 
-Another interesting example is to change the default behaviour in a
-way that makes completion first offer files matching the patterns
-given by the calling function, then directories and then all files. 
-Some people prefer this over getting both the files matching the given
-patterns and the directories in the first try and all files at the
-second try.  To achieve this, one could do:
+To alter the default behaviour of file completion --- offer files
+matching a pattern and directories on the first attempt, then all files
+--- to offer only matching files on the first attempt, then directories,
+and finally all files:
 
 example(zstyle ':completion:*' file-patterns \ 
     '%p:globbed-files' '*(-/):directories' '*:all-files')
 
-This works even for contexts in which all files would be completed,
-because tt(_files) will not try a pattern more than once and it stops
-when the pattern `tt(*)' was tried.
+This works even where there is no special pattern: tt(_files) matches
+all files using the pattern `tt(*)' at the first step and stops when it
+sees this pattern.  Note also it will never try a pattern more than once
+for a single completion attempt.
 
-Note also that during the execution of completion functions, the
-tt(EXTENDED_GLOB) option is in effect, so the characters `tt(#)',
-`tt(~)' and `tt(^)' have special meanings in the patterns.
+During the execution of completion functions, the tt(EXTENDED_GLOB)
+option is in effect, so the characters `tt(#)', `tt(~)' and `tt(^)' have
+special meanings in the patterns.
 )
 kindex(file-sort, completion style)
 item(tt(file-sort))(
-The completion function that generates filenames as possible matches
-uses this style without a tag to determine in which order the 
-names should be listed and completed when using menu completion.  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
+The standard filename completion function uses this style without a tag
+to determine in which order the names should be listed; menu completion
+will cycle through them in the same order.  The possible
+values are: `tt(size)' to sort by the size of the file;
+`tt(links)' to sort by the number of links to the file;
+`tt(modification)' (or `tt(time)' or `tt(date)') to sort by the last
+modification time; `tt(access)' to sort by the last access time; and
+`tt(inode)' (or `tt(change)') to sort by the last inode change
 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.
+`tt(reverse)', sorting is done in the opposite order.
 )
 kindex(filter, completion style)
 item(tt(filter))(
 This is used by the LDAP plugin for e-mail address completion to specify
-the attributes to match against when filtering entries. So for example, if
-the style is set to `tt(sn)', matching is done against surnames. Standard
-LDAP filtering is used so normal completion matching is bypassed. If this
-style is not set, the LDAP plugin is skipped. You may also need to set the
-tt(command) style before it can connect to your LDAP server though.
+the attributes to match against when filtering entries.  So for example, if
+the style is set to `tt(sn)', matching is done against surnames.  Standard
+LDAP filtering is used so normal completion matching is bypassed.  If this
+style is not set, the LDAP plugin is skipped.  You may also need to set the
+tt(command) style to specify how to connect to your LDAP server.
 )
 kindex(force-list, completion style)
 item(tt(force-list))(
@@ -1384,14 +1354,14 @@ 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
+single match that will immediately be 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.
 
-This style is tested for the default tag and all tags used when
-generating matches. This allows one to turn unconditional listing on
-for certain types of matches.
+This style is tested for the default tag as well as for each tag valid
+for the current completion.  Hence the listing can be forced only for
+certain types of match.
 )
 kindex(format, completion style)
 item(tt(format))(
@@ -1402,29 +1372,27 @@ 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 provides the possibility of defining different format
-strings for different types of matches.
+The style is tested with each tag valid for the current completion
+before it is tested for the tt(descriptions) tag.  Hence different format 
+strings can be defined for different types of match.
 
 Note also that some completer functions define additional
 `tt(%)'-sequences.  These are described for the completer functions that 
 make use of them.
 
-For the tt(messages) tag, this style defines a string used by some
-completion functions to display messages.  Here, the `tt(%d)' is
+Some completion functions display messages that may be customised by
+setting this style for the tt(messages) tag.  Here, the `tt(%d)' is
 replaced with a message given by the completion function.
 
-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
+Finally, the format string is looked up with the tt(warnings) tag, 
+for use 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 separated by spaces and the sequence `tt(%D)' is replaced with
-those descriptions separated by newlines.
+expected separated by spaces.  The sequence `tt(%D)' is replaced with
+the same descriptions separated by newlines.
 
-The `tt(%)' for the sequences that are replaced by strings provided by 
-the completion functions like the `tt(%d)' may be followed by field
-width specifications as  described for the tt(zformat) builtin command
-from the tt(zsh/zutil) module, see
+It is possible to use printf-style field width specifiers with `tt(%d)'
+and similar escape sequences.  This is handled by the tt(zformat)
+builtin command from the tt(zsh/zutil) module, see
 ifzman(zmanref(zshmodules))\
 ifnzman(noderef(The zsh/zutil Module))\
 .
@@ -1433,8 +1401,8 @@ kindex(glob, completion style)
 item(tt(glob))(
 This is used by the tt(_expand) completer.  If
 it is set to `true' (the default), globbing will be attempted on the
-words resulting from substitution (see the tt(substitute) style) or
-the original string from the line.
+words resulting from a previous substitution (see the tt(substitute)
+style) or else the original string from the line.
 )
 kindex(global, completion style)
 item(tt(global))(
@@ -1443,24 +1411,22 @@ completer and bindable command will try to expand global aliases.
 )
 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
+The completion system can group different types of matches, which appear
+in separate lists.  This style can be used to give the names of 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
-separately, one can set:
+separately:
 
 example(zstyle ':completion:*:*:-command-:*:commands' group-name commands
 zstyle ':completion:*:*:-command-:*:functions' group-name functions)
 
-This also means that if the same name is used for different types of
-matches, then those matches will be displayed together in the same
-group.
+As a consequence, any match with the same tag will be displayed in the
+same group.
 
-If the name given is the empty string, then the name of the tag for
-the matches will be used as the name of the group. So, to have all
+If the name given is the empty string the name of the tag for
+the matches will be used as the name of the group.  So, to have all
 different types of matches displayed separately, one can just set:
 
 example(zstyle ':completion:*' group-name '')
@@ -1470,35 +1436,30 @@ named tt(-default-).
 )
 kindex(group-order, completion style)
 item(tt(group-order))(
-This style is to be used together with the tt(group-name) style.  Once
-different types of matches are put into different groups, this style
-can be used to define in which order these groups should appear when listing 
-(compare tt(tag-order), which determines which completions appear at
-all).  The strings in the value are taken as group names and the named
-groups will be shown in the order in which their names appear in the
-value.  All groups whose names are not given in the value of this style 
-will appear in the order defined by the function generating the
-matches.
+This style is additional the tt(group-name) style to put the groups
+defined by that style into order for display (compare tt(tag-order),
+which determines which completions appear at all).  The groups named
+are shown in the given order; any other groups
+are shown in the order defined by the completion function.
 
 For example, to have names of builtin commands, shell functions and
-external commands appear in this order when completing in command
-position one would set:
+external commands appear in that order when completing in command
+position:
 
 example(zstyle ':completion:*:*:-command-:*' group-order \ 
        builtins functions commands)
 )
 kindex(groups, completion style)
 item(tt(groups))(
-A style holding the names of the groups that should be completed. If
-this is not set by the user, the group names from the YP database or
-the file `tt(/etc/group)' will be used.
+A list of names of UNIX groups.  If this is not set,
+group names are taken from the YP database or the file `tt(/etc/group)'.
 )
 kindex(hidden, completion style)
 item(tt(hidden))(
-If this is set to one of the `true' values, the matches for the tags
-for which this is set will not appear in the list; only the
-description for the matches as set with the tt(format) style will be
-shown.  If this is set to `tt(all)', not even the description will be
+If this is set to true, matches for the given context
+will not be listed, although
+any description for the matches set with the tt(format) style will be
+shown.  If it 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 
@@ -1508,32 +1469,29 @@ below.
 )
 kindex(hosts, completion style)
 item(tt(hosts))(
-A style holding the names of hosts that should be completed. If this
-is not set by the user the hostnames in `tt(/etc/hosts)' will be used.
+A list of names of hosts that should be completed.  If this is not set,
+hostnames are taken from the file `tt(/etc/hosts)'.
 )
 kindex(hosts-ports, completion style)
 item(tt(hosts-ports))(
 This style is used by commands that need or accept hostnames and
-ports.  The strings in the value should be of the form
-`var(host)tt(:)var(port)'.  These hostnames and ports are completed
-depending on the information already on the line, so that if, for
-example, the hostname is already typed, only those ports specified for that
-host will be completed.  Multiple ports for the same host may appear.
+network ports.  The strings in the value should be of the form
+`var(host)tt(:)var(port)'.  Valid ports are determined by the presence
+of hostnames; 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
-is set to `true', then none of the words that are already on the line
-will be considered possible completions.  If it is set to
-`tt(current)', the word the cursor is on will not be considered a
-possible completion.  The same happens if the value is
-`tt(current-shown)', but only if the list of completions is currently
-shown on the screen.  Finally, if it is set to `tt(other)' all words
-except the current one will not be considered to be a possible
-completion.
+This is tested for each tag valid for the current completion.  If
+it is set to `tt(true)', none of the words that are already on the line
+will be considered as possible completions.  If it is set to
+`tt(current)', the word the cursor is on will not be considered as a
+possible completion.  The value `tt(current-shown)' is similar but only
+applies if the list of completions is currently shown on the screen.
+Finally, if the style is set to `tt(other)', no word apart from the
+current one will be considered as a possible completion.
 
 The values `tt(current)' and `tt(current-shown)' are a bit like the
-opposite of tt(accept-exact). They mean that only strings with
+opposite of the tt(accept-exact) style:  only strings with
 missing characters will be completed.
 
 Note that you almost certainly don't want to set this to `true' or
@@ -1544,8 +1502,8 @@ in question accepts the option more than once.
 )
 kindex(ignore-parents, completion style)
 item(tt(ignore-parents))(
-The style is tested by the function completing pathnames without a tag to
-determine whether to ignore
+The style is tested without a tag by the function completing pathnames
+in order to determine whether to ignore
 the names of directories already mentioned in the current word, or the
 name of the current working directory.  The value must include one or both
 of the following strings:
@@ -1557,7 +1515,7 @@ the line is ignored.  For example, when completing after tt(foo/../), the
 directory tt(foo) will not be considered a valid completion.
 )
 item(tt(pwd))(
-The name of the current working directory will not be completed, so that,
+The name of the current working directory will not be completed; hence,
 for example, completion after tt(../) will not use the name of the current
 directory.
 )
@@ -1571,143 +1529,144 @@ Ignore the specified directories only when the word on the line contains
 the substring `tt(../)'.
 )
 item(tt(directory))(
-Ignore only when names of directories are completed, not when completing
-names of files.
+Ignore the specified directories only when names of directories are
+completed, not when completing names of files.
 )
 enditem()
 
-Note that names of directories ignored because of one of the tests
-will be ignored in the same way as the matches ignored because of the
-tt(ignored-patterns) style.  I.e., by using the tt(_ignored) completer
-it is possible to complete these directories nonetheless.
+Excluded values act in a similar fashion to values of the
+tt(ignored-patterns) style, so they can be restored to consideratoin by
+the tt(_ignored) completer.
 )
 kindex(ignored-patterns, completion style)
 item(tt(ignored-patterns))(
-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
+A list of patterns; any trial completion matching one of the patterns
+will be excluded from consideration.  The
+tt(_ignored) completer can appear in the list of completers to
+restore the ignored matches.  This is a more configurable
 version of the shell parameter tt($fignore).
 
-Note that during the execution of completion functions, the
-tt(EXTENDED_GLOB) option is in effect, so the characters `tt(#)',
-`tt(~)' and `tt(^)' have special meanings in the patterns.
+Note that the
+tt(EXTENDED_GLOB) option is set during the execution of completion
+functions, so the characters `tt(#)', `tt(~)' and `tt(^)' have special
+meanings in the patterns.
 )
 kindex(insert, completion style)
 item(tt(insert))(
 This style is used by the tt(_all_matches) completer to decide whether to
-insert the list of all matches instead of adding it as another match.
+insert the list of all matches unconditionally instead of adding the
+list as another match.
 )
 kindex(insert-ids, completion style)
 item(tt(insert-ids))(
 When completing process IDs, for example as arguments to the tt(kill) and
-tt(wait) builtins, completion allows the user to type the name of a
-command, which will be converted to the appropriate process ID.  A problem
+tt(wait) builtins the name of a
+command may be converted to the appropriate process ID.  A problem
 arises when the process name typed is not unique.  By default (or if this
 style is set explicitly to `tt(menu)') the name will be converted
 immediately to a set of possible IDs, and menu completion will be started
-to cycle through them.  If the value of the style is `tt(single)', however,
+to cycle through them.
+
+If the value of the style is `tt(single)'
 the shell will wait until the user has typed enough to make the command
-unique before converting the name to an ID; the user must type any
-additional characters required.  If the value is any other string, menu
-completion will be started when the string typed by the user is longer than
-the common prefix of the corresponding IDs.
+unique before converting the name to an ID; attempts at completion will
+be unsuccessul until that point.  If the value is any other
+string, menu completion will be started when the string typed by the
+user is longer than the common prefix to the corresponding IDs.
 )
 kindex(insert-tab, completion style)
 item(tt(insert-tab))(
-If this has one of the `true' values, the completion system will
-insert a TAB character (assuming it was used to start completion) instead
+If this is set to `true', the completion system will
+insert a TAB character (assuming that was used to start completion) instead
 of performing completion when there is no non-blank character to the left
-of the cursor.  If set to `false', completion will be done even there.
+of the cursor.  If it is set to `false', completion will be done even there.
 
 The value may also contain the substrings `tt(pending)' or
-`tt(pending=)var(val)' to make the character typed to start completion 
-be inserted instead of completion being tried when there is input
-pending which has not yet been processed by the shell. If a var(val)
-is given, completion will not be done if there are at least that many
-characters of unprocessed input. This is often useful to have set when 
-pasting characters into a terminal. Note however, that it relies on
-the tt($PENDING) special parameter from the tt(zsh/zle) module being set
-properly which is not guaranteed on all platforms.
-
-The default value of this style is `true' unless when completing
-inside the tt(vared) builtin command, where it defaults to `false'.
+`tt(pending=)var(val)'.  In this case, the typed character will be
+inserted instead of staring completion when there is unprocessed input
+pending.  If a var(val) is given, completion will not be done if there
+are at least that many characters of unprocessed input.  This is often
+useful when pasting characters into a terminal.  Note
+however, that it relies on the tt($PENDING) special parameter from the
+tt(zsh/zle) module being set properly which is not guaranteed on all
+platforms.
+
+The default value of this style is `true' except for completion within
+tt(vared) builtin command where it is `false'.
 )
 kindex(insert-unambiguous, completion style)
 item(tt(insert-unambiguous))(
-This is used by the tt(_match) and tt(_approximate) completer
-functions, where the possible completions may not have a common prefix so
-that menu completion is often the most useful may of choosing completions.
-If the style is set to `true', the completer will start menu
-completion only if no unambiguous string could be generated that is at
-least as long as the original string typed by the user.  Note that the
-tt(_approximate) completer uses it after setting the completer field
-in the context name to one of tt(correct-)var(num) or
-tt(approximate-)var(num), where var(num) is the number of errors that
-were accepted.
-
-When used for the tt(_match) completer, the style may also be set to
-the string `tt(pattern)'.  This makes the pattern on the line be left
-unchanged if it didn't match unambiguously.
+This is used by the tt(_match) and tt(_approximate) completers.
+These styles are often used with menu completion since the word typed
+may bear little resemblance to the final completion.
+However, if this the style is `true', the completer will start menu
+completion only if it could find no unambiguous initial string at
+least as long as the original string typed by the user.
+
+In the case of the tt(_approximate) completer, the completer
+field in the context will already have been set to one of
+tt(correct-)var(num) or tt(approximate-)var(num), where var(num) is the
+number of errors that were accepted.
+
+In the case of the tt(_match) completer, the style may also be set to
+the string `tt(pattern)'.  Then the pattern on the line is left
+unchanged if it does not match unambiguously.
 )
 kindex(keep-prefix, completion style)
 item(tt(keep-prefix))(
 This style is used by the tt(_expand) completer.  If it is `true', the
 completer will try to keep a prefix containing a tilde or parameter
-expansion.  I.e., the string `tt(~/f*)' would be expanded to
+expansion.  Hence, for example, the string `tt(~/f*)' would be expanded to
 `tt(~/foo)' instead of `tt(/home/user/foo)'.  If the style is set to
 `tt(changed)' (the default), the prefix will only be left unchanged if
 there were other changes between the expanded words and the original
-word from the command line.  Any other value makes the prefix be
+word from the command line.  Any other value forces the prefix to be
 expanded unconditionally.
 
-Note that with one of the `true' values, the tt(_expand) completer
-returns if there is only one expansion and that is, after restoring
-the original prefix, the same as the original word.  This means that
-other completers will be called immediately after tt(_expand).
+The behaviour of expand when this style is true is to cause tt(_expand)
+to give up when a single expansion with the restored prefix is the same
+as the original; hence any remaining completers may be called.
 )
 kindex(last-prompt, completion style)
 item(tt(last-prompt))(
-This is used to determine if the completion code should try to put the
-cursor back onto the previous command line after showing a completion
-listing (as for the tt(ALWAYS_LAST_PROMPT) option).  As with several other
-styles, it is tested for the tt(default) tag as well as all the possible
-tags when generating matches.  The cursor will be moved back to the
-previous line if this style is `true' for all types of matches added.  Note
-also that this is independent of the numeric argument, unlike the
-tt(ALWAYS_LAST_PROMPT) option.
+This is a more flexible form of the tt(ALWAYS_LAST_PROMPT) option.
+If it is true, the completion system will try to return the cursor to
+the previous command line after displaying a completion list.  It is
+tested for all tags valid for the current completion, then the
+tt(default) tag.  The cursor will be moved back to the
+previous line if this style is `true' for all types of match.  Note
+that unlike the tt(ALWAYS_LAST_PROMPT) option this is independent of the
+numeric prefix argument.
 )
 kindex(list, completion style)
 item(tt(list))(
 This style is used by the tt(_history_complete_word) bindable command.
-If it is set to `true' it has no effect, but if it is set to `false'
-the matches will not be listed, overriding the setting of the options
-that control listing behaviour, especially tt(AUTO_LIST). Use the
-context prefix `tt(:completion:history-words)'.
+If it is set to `true' it has no effect.  If it is set to `false'
+matches will not be listed.  This overrides the setting of the options
+controlling listing behaviour, in particular tt(AUTO_LIST).  The context
+always starts with `tt(:completion:history-words)'.
 )
 kindex(list-colors, completion style)
 item(tt(list-colors))(
-If the tt(zsh/complist) module is used, this style can be used to set
-color specifications as with the tt(ZLS_COLORS) and tt(ZLS_COLOURS)
-parameters, which will not be honored under this completion system (see
+If the tt(zsh/complist) module is loaded, this style can be used to set
+color specifications.  This mechanism replaces the use of the
+tt(ZLS_COLORS) and tt(ZLS_COLOURS) parameters described in
 ifzman(the section `The zsh/complist Module' in zmanref(zshmodules))\
 ifnzman(noderef(The zsh/complist Module))\
-).
+, but the syntax is the same.
 
 If this style is set for the tt(default) tag, the strings in the value 
 are taken as specifications that are to be used everywhere.  If it is
 set for other tags, the specifications are used only for matches of
 the type described by the tag.  For this to work best, the tt(group-name)
-style must be set to an empty string.  If the tt(group-name) tag
-specifies other names for the groups the matches in these groups can
-be colored by using these names together with the `tt((group)...)'
-syntax described for the tt(ZLS_COLORS) and tt(ZLS_COLOURS) parameters 
-and adding the specifications to the value for this style with the
-tt(default) tag (although in most cases it should work by setting this 
-style for the appropriate tags).
-
-It is possible to use the same specifications set up for the GNU
+style must be set to an empty string.  
+
+In addition to setting styles for specific tags, it is also possible to
+use group names specified explicitly by the tt(group-name) tag together
+withe the `tt((group))' syntax allowed by the tt(ZLS_COLORS) and
+tt(ZLS_COLOURS) parameters and simply using the tt(default) tag.
+
+It is possible to use any color specifications alrady set up for the GNU
 version of the tt(ls) command:
 
 example(zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS})
@@ -1718,21 +1677,18 @@ obtained by setting the style to an empty string (i.e. tt('')).
 kindex(list-grouped, completion style)
 item(tt(list-grouped))(
 If this style is `true' (the default), the completion system will try to
-make some completion listings more compact by grouping matches together.
-For example, options for commands that have the same description (which
-are shown because the tt(verbose) style is set to `true') will have only
-one entry in the list, showing all options that can be used to select
-the specific behaviour.  When menu selection is done on such a list, the
-matches will appear as separate entries in the list to be able to select
-each of them.
+make certain completion listings more compact by grouping matches.
+For example, options for commands that have the same description (shown
+when the tt(verbose) style is set to `true') will appear as a single
+entry.  However, menu selection can be used to cycle through all the
+matches.
 )
 kindex(list-packed, completion style)
 item(tt(list-packed))(
-Like the tt(list-colors) style, this is tested with the tt(default)
-tag and all tags used when generating matches.  If it is set to `true'
-for a tag, the matches added for it will be listed as if the
-tt(LIST_PACKED) option were set.  If it is set to `false',
-they are listed normally.
+This is tested for each tag valid in the current context as well as the
+tt(default) tag.  If it is set to `true', the corresponding matches
+appear in listings as if the tt(LIST_PACKED) option were set.  If it is
+set to `false', they are listed normally.
 )
 kindex(list-prompt, completion style)
 item(tt(list-prompt))(
@@ -1743,32 +1699,36 @@ ifnzman(noderef(The zsh/complist Module))\
 ).  The value, if not the empty string, will be displayed after every
 screenful and the shell will prompt for a key press; if the style is
 set to the empty string,
-a default prompt will be used.  The value may contain the escape sequences
+a default prompt will be used.
+
+The value may contain the escape sequences:
 `tt(%l)' or `tt(%L)', which will be replaced by the number of the last line
-displayed and the total number of lines; `tt(%m)' or `tt(%M)', which will
-be replaced by the number of the  last match shown and the total number of
-matches; and `tt(%p)' and `tt(%P)', which will be replaced by `tt(Top)'
+displayed and the total number of lines; `tt(%m)' or `tt(%M)', 
+the number of the  last match shown and the total number of
+matches; and `tt(%p)' and `tt(%P)', `tt(Top)'
 when at the beginning of the list, `tt(Bottom)' when at the end and the
-position shown in percent of the total length otherwise.  In each of these
-cases the form with the uppercase letter is replaced by a string of fixed
-width, padded to the  right with spaces.  As in other prompt strings, the
+position shown as a percentage of the total length otherwise.  In each
+case the form with the uppercase letter will be replaced by a string of fixed
+width, padded to the  right with spaces, while the lowercase form will
+be replaced by a variable width string.  As in other prompt strings, the
 escape sequences `tt(%S)', `tt(%s)', `tt(%B)', `tt(%b)', `tt(%U)',
-`tt(%u)', and `tt(%{)...tt(%})' for entering and leaving the display modes
-standout, bold and underline are also available.
+`tt(%u)' for entering and leaving the display modes
+standout, bold and underline are also available, as is the form
+`tt(%{)...tt(%})' for enclosing escape sequences which display with zero
+width.
 )
 kindex(list-rows-first, completion style)
 item(tt(list-rows-first))(
 This style is tested in the same way as the tt(list-packed) style and
-determines if matches are to be listed in a rows-first fashion, as for the
-tt(LIST_ROWS_FIRST) option.
+determines whether matches are to be listed in a rows-first fashion as
+if the tt(LIST_ROWS_FIRST) option were set.
 )
 kindex(list-suffixes, completion style)
 item(tt(list-suffixes))(
-This style is used by the function used to complete filenames.  If
-completion is attempted on a string containing multiple partially
-typed pathname components and this style is set to `true', all
-components starting with the first one for which more than one match
-could be generated will be shown.
+This style is used by the function that completes filenames.  If it is
+true, and completion is attempted on a string containing multiple partially
+typed pathname components, all ambiguous components will be shown.
+Otherwise, completion stops at the first ambiguous component.
 )
 kindex(list-separator, completion style)
 item(tt(list-separator))(
@@ -1778,16 +1738,22 @@ completing options).  It defaults to `tt(-)tt(-)' (two hyphens).
 )
 kindex(local, completion style)
 item(tt(local))(
-This style is used by completion functions which generate URLs as
-possible matches to add suitable matches when a URL points to a
-local web server, that is, one whose files are available directly on the
-local file system.  Its value should consist of three strings: a
-hostname, the path to the default web pages for the server and the
+This is for use with functions that complete URLs for which the
+corresponding files are available directly from the filing system.
+Its value should consist of three strings: a
+hostname, the path to the default web pages for the server, and the
 directory name used by a user placing web pages within their home
-area.  For example, completion after `tt(http://toast/~yousir/)' will
-attempt to match the name `tt(toast)' against the first argument to the
-style, and if successful will look in the directory under tt(~yousir) given
-by the third argument to the style for possible completions.
+area.
+
+For example:
+
+example(zstyle ':completion:*' local toast \ 
+    /var/http/public/toast public_html)
+
+Completion after `tt(http://toast/stuff/)' will look for files in the
+directory tt(/var/http/public/toast/stuff),  while completion after
+`tt(http://toast/~yousir/)' will look for files in the directory
+tt(~yousir/public_html).
 )
 kindex(mail-directory, completion style)
 item(tt(mail-directory))(
@@ -1802,54 +1768,52 @@ tt(only), tt(_match) will try to generate matches without inserting a
 it will first try to generate matches without inserting the `tt(*)'
 and if that yields no matches, it will try again with the `tt(*)'
 inserted.  If it is unset or set to the empty string, matching will
-only be done with the `tt(*)' inserted.
+only be performed with the `tt(*)' inserted.
 )
 kindex(matcher, completion style)
 item(tt(matcher))(
-This style is tested for tags used when generating matches.  Its value
-is used as an match specification additional to any given by the
-tt(matcher-list) style which should be in the form described in
+This style is tested separately for each tag valid in the current
+context.  Its value is added to any match specifications given by the 
+tt(matcher-list) style.  It should be in the form described in
 ifzman(the section `Matching Control' in zmanref(zshcompwid))\
 ifnzman(noderef(Matching Control))\
 .
 )
 kindex(matcher-list, completion style)
 item(tt(matcher-list))(
-This style is used by the main completion function to retrieve match
-specifications that are to be used everywhere.  Its value should be a
-list of such specifications.  The completion system will try them one
-after another for each completer selected. For example, to first try
-simple completion and, if that generates no matches, case-insensitive
-completion one would do:
+This style is a list of match specifications that are valid everywhere.
+Match specifications are described in
+ifzman(the section `Matching Control' in zmanref(zshcompwid))\
+ifnzman(noderef(Matching Control))\
+.
+The completion system will try them one after another for each completer
+selected.  For example, to try first simple completion and, if that
+generates no matches, case-insensitive completion:
 
 example(zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}')
 
-By default every specification replaces previous ones. If specification
-is prefixed with tt(+), it is added to the existing list. This allows
-testing more general patterns without repeating the whole list every
-time, as in:
+By default each specification replaces the previous one; however, if a
+specification is prefixed with tt(+), it is added to the existing list.
+Hence it is possible to create increasingly general specifications
+without repetition:
 
 example(zstyle ':completion:*' matcher-list '' '+m{a-Z}={A-Z}' '+m{A-Z}={a-z}')
 
-The style allows even finer control by specifying a particular completer,
-without the leading underscore, in the third field of the completion
-context.  For example, if one uses the completers tt(_complete) and
-tt(_prefix) but wants to try case-insensitive completion only when using
-the tt(_complete) completer, one would do:
+It is possible to create match specifications valid for particular
+completers by using the third field of the context.  For example, to
+use the completers tt(_complete) and tt(_prefix) but only allow
+case-insensitive completion with tt(_complete):
 
 example(zstyle ':completion:*' completer _complete _prefix
 zstyle ':completion:*:complete:*' matcher-list \ 
        '' 'm:{a-zA-Z}={A-Za-z}')
 
-Note that the tt(completer) style allows user-defined names to 
-be used in the context instead of the name of the completer.
-This is useful if, for example, one wants to try
-normal completion without a match specification and with
-case-insensitive matching first, correction if that doesn't generate
-any matches and partial-word completion if that doesn't yield any
-matches either.  In this case one can give the tt(_complete)
-completer more than once in the tt(completer) style and define different
-match specifications for each occurrence, as in:
+User-defined names, as explained for the tt(completer) style, are
+available.  This makes it possible to try the same completer more than
+once with different match specifications each time.  For example, to try
+normal completion without a match specification, then normal completion
+with case-insensitive matching, then correction, and finally
+partial-word completion:
 
 example(zstyle ':completion:*' completer _complete _correct _complete:foo
 zstyle ':completion:*:complete:*' matcher-list \ 
@@ -1857,18 +1821,18 @@ zstyle ':completion:*:complete:*' matcher-list \
 zstyle ':completion:*:foo:*' matcher-list \ 
     'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*')
 
-If the style is unset in any context no match specification is applied;
-further, some completers such as tt(_correct) and tt(_approximate) do not
-use the match specifications at all.  However, it is always safe
-to use the simple form for this style (as in the first example above),
-since any completers which do not use match specifications will only ever
-be called once, rather than once per specification.
+If the style is unset in any context no match specification is applied.
+Note also that some completers such as tt(_correct) and tt(_approximate)
+do not use the match specifications at all, though these completers will
+only ever called once even if the tt(matcher-list) contains more than
+one element.
 
-Since the specification-strings in this style have to be tried one after
-another, it is a good idea to keep their number low.  In most cases
-one to three strings (each of which may, without to large a performance 
-hit, consist of more than one single match specification) will give
-acceptable performance.
+Where multiple specifications are useful, note that the em(entire)
+completion is done for each element of tt(matcher-list), which can
+quickly reduce the shell's performance.  As a rough rule of thum,
+one to three strings will give acceptable performance.  On the other
+hand, putting multiple space-separated values into the same string does
+not have an appreciable impact on performance.
 )
 kindex(max-errors, completion style)
 item(tt(max-errors))(
@@ -1901,80 +1865,87 @@ The default value for this style is `tt(2 numeric)'.
 )
 kindex(max-matches-width, completion style)
 item(tt(max-matches-width))(
-This is used to define the maximum width to use for the matches when
-listing matches with descriptions. In such lists, matches with the
-same description will be grouped together, but that means that in
-cases where many matches have the same description, the matches take
-up most of the display width, leaving only little room for the
-descriptions. By setting this style one can specify whether one
-prefers to make more matches be grouped together or whether the shell
-should try keep more of the descriptions visible. 
-
-The value should give the maximum number of display columns to give to
-the matches, the default is half the screen width.
+This style is used to determine the trade off between the width of the
+display used for matches and the width used for their descriptions when
+the tt(verbose) style is in effect.  The value gives the number of
+display columns to reserve for the matches.  The default is half the
+width of the screen.
+
+This has the most impact when several matches have the
+same description and so will be grouped together.  Increasing the style
+will allow more matches to be grouped together; decreasing it will allow
+more of the description to be visible.
 )
 kindex(menu, completion style)
 item(tt(menu))(
-If this is set to true in a given context, using any of the tags defined
-for a given completion, menu completion will be used.  The tag
-`tt(default)' can be used to set the default value, but a specific tag will take
-precedence.  If none of the values found in this way is true but at least
-one is set to `tt(auto)' the behaviour will be as for the tt(AUTO_MENU)
-option.  Finally, if one of the values is explicitly set to false, menu
-completion will be turned off even if it would otherwise be active (for
-example, with the tt(MENU_COMPLETE) option).
-
-Using the form `tt(yes=)var(num)', where `tt(yes)' may be any of the
-true values (`tt(yes)', `tt(true)', `tt(on)' and `tt(1)') turns on
-menu completion if there at least var(num) matches.  Using this for one
-of the `false' values (as in `tt(no=10)') makes menu completion
-em(not) be used if there are var(num) or more matches.  Of course,
-this is only useful when menu completion is normally used, e.g. by
-setting the tt(MENU_COMPLETE) option.  The `true' values may also be
-used in the form `tt(yes=long)' to turn on menu completion
-if the list does not fit onto the screen.  This will start menu
-completion only if normal completion was attempted, not when only the
-list of possible completions was requested.  To start menu completion
-even then, the value `tt(yes=long-list)' can be used.
-
-In addition to (or instead of) the above possibilities, the value may
-contain the string `tt(select)', optionally followed by an equals sign and a
-number.  In this case menu selection (as defined by the tt(zsh/complist)
-module) will be started.  Without the optional number, it will be started
-unconditionally and with a number it will be started only if at least that
-many matches are generated; if the values for more than one tag provide a
-number, the smallest number is taken.  Menu selection can be turned off
-explicitly by defining a value containing the string `tt(no-select)'.
+If this is true in the context of any of the tags defined
+for the current completion menu completion will be used.  The value for
+a specific tag will take precedence over that for the `tt(default)' tag.
+
+If none of the values found in this way is true but at least
+one is set to `tt(auto)', the shell behaves as if the tt(AUTO_MENU)
+option is set.
+
+If one of the values is explicitly set to false, menu
+completion will be explicitly turned off, overriding the
+tt(MENU_COMPLETE) option and other settings.
+
+In the form `tt(yes=)var(num)', where `tt(yes)' may be any of the
+true values (`tt(yes)', `tt(true)', `tt(on)' and `tt(1)'),
+menu completion will be turned on if there at least var(num) matches.
+In the form `tt(yes=long)', menu completion will be turned on
+if the list does not fit onto the screen.  This does not activate menu
+completion if the widget normally only lists completions, but menu
+completion can be activated in that case with the value `tt(yes=long-list)'
+(Typically, the value `tt(select=long-list)' described later is more
+useful as it provides control over scrolling.)
+
+Similarly, with any of the `false' values (as in `tt(no=10)'), menu
+completion will em(not) be used if there are var(num) or more matches.  
+
+The value of this widget also controls menu selection, as implemented by
+the tt(zsh/complist) module.  The following values may appear either
+alongside or instead of the values bbavoe.
+
+If the value contains the string `tt(select)', menu selection (as
+will be started unconditionally.
+
+In the form `tt(select=)var(num)', menu selection will only be started if
+there are at least var(num) matches.  If the values for more than one
+tag provide a number, the smallest number is taken.
+
+Menu selection can be turned off explicitly by defining a value
+containing the string`tt(no-select)'.
 
 It is also possible to start menu selection only if the list of
 matches does not fit on the screen by using the value
-`tt(select=long)'.  This will only start menu selection if the widget
-invoked does completion, not simply listing as done by
-tt(delete-char-or-list); to start menu selection even here, use the value
-`tt(select=long-list)'.
-
-To turn on menu completion or menu selection when a certain number of
-matches is generated em(or) the list of matches does not fit onto the
-screen, both of `tt(yes=)' and `tt(select=)' can be given twice, once
+`tt(select=long)'.  To start menu selection even if the current widget
+only performs listing, use the value `tt(select=long-list)'.
+
+To turn on menu completion or menu selection when a there are a certain
+number of matches em(or) the list of matches does not fit onto the
+screen, both of `tt(yes=)' and `tt(select=)' may be given twice, once
 with a number and once with `tt(long)' or `tt(long-list)'.
 
-Finally, the two special modes of menu selection, namely interactive
-mode and incremental search can be pre-selected with this style. By
-including the word `tt(interactive)' in the value, interactive mode
-will be entered immediately when menu selection is started and the
-string `tt(search)' does the same for incremental search. To select
-backward incremental search, include the string `tt(search-backward)'.
+Finally, it is possible to activate two special modes of menu selection.
+The word `tt(interactive)' in the value causes interactive mode
+to be entered immediately when menu selection is started; see
+ifzman(the description of the tt(zsh/complist) module in zmanref(zshmodules))\
+ifnzman(noderef(The zsh/complist Module))\
+) for a description of interactive mode.  Including the string
+`tt(search)' does the same for incremental search mode.  To select backward
+incremental search, include the string `tt(search-backward)'.
 )
 kindex(muttrc, completion style)
 item(tt(muttrc))(
-If set, zsh will assume that the local mutt configuration can be found
-in the file specified.  It defaults to `tt(~/.muttrc)'.
+If set, gives the location of the mutt configuration file.  It defaults
+to `tt(~/.muttrc)'.
 )
 kindex(numbers, completion style)
 item(tt(numbers))(
 This is used with the tt(jobs) tag.  If it is `true', the shell will
-complete the job numbers instead of the shortest unambiguous strings
-of the jobs' command lines.  If the value is a number, job numbers will
+complete job numbers instead of the shortest unambiguous prefix
+of the job command text.  If the value is a number, job numbers will
 only be used if that many words from the job descriptions are required to
 resolve ambiguities.  For example, if the value is `tt(1)', strings will
 only be used if all jobs differ in the first word on their command lines.
@@ -2011,22 +1982,27 @@ used again.
 kindex(old-matches, completion style)
 item(tt(old-matches))(
 This is used by the tt(_all_matches) completer to decide if an old
-list of matches should be used if one exists.  It may be set to one of 
-the `true' values or to the string `tt(only)' to use such a list.  If
-it is set to `tt(only)', tt(_all_matches) will only use an old list
+list of matches should be used if one exists.  This is selected by one of
+the `true' values or to the string `tt(only)'.  If
+the value is `tt(only)', tt(_all_matches) will only use an old list
 and won't have any effect on the list of matches currently being
 generated.
+
+If this style is set it is generally unwise to call the tt(_all_matches)
+completer unconditionally.  One possible use is for either this style or
+the tt(completer) style to be defined with the tt(-e) option to
+tt(zstyle) to make the style conditional.
 )
 kindex(old-menu, completion style)
 item(tt(old-menu))(
 This is used by the tt(_oldlist) completer.  It controls how menu
 completion behaves when a completion has already been inserted and the
-user types a standard completion key type such as tt(TAB).  The default
+user types a standard completion key such as tt(TAB).  The default
 behaviour of tt(_oldlist) is that menu completion always continues
 with the existing list of completions.  If this style is set to
 `false', however, a new completion is started if the old list was
 generated by a different completion command; this is the behaviour without
-the  tt(_oldlist) completer.
+the tt(_oldlist) completer.
 
 For example, suppose you type tt(^Xc) to generate a list of corrections,
 and menu completion is started in one of the usual ways.  Usually, or with
@@ -2038,12 +2014,12 @@ kindex(original, completion style)
 item(tt(original))(
 This is used by the tt(_approximate) and tt(_correct)
 completers to decide if the original string should be added as
-one possible completion.  Normally, this is done only if there are
+a possible completion.  Normally, this is done only if there are
 at least two possible corrections, but if this style is set to `true', it
-is always added.  Note that these completers use this style after
-setting the completer field in the context name to
-tt(correct-)var(num) or tt(approximate-)var(num), where var(num) is
-the number of errors that were accepted.
+is always added.  Note that the style will be examined with the
+completer field in the context name set to tt(correct-)var(num) or
+tt(approximate-)var(num), where var(num) is the number of errors that
+were accepted.
 )
 kindex(packageset, completion style)
 item(tt(packageset))(
@@ -2067,30 +2043,29 @@ locations it will be used as the default.
 )
 kindex(pine-directory, completion style)
 item(tt(pine-directory))(
-If set, zsh will assume that PINE mailbox files can be found in
-the directory specified.  It defaults to `tt(~/mail)'.
+If set, specifies the directory containing PINE mailbox files.  It
+defaults to `tt(~/mail)'.
 )
 kindex(ports, completion style)
 item(tt(ports))(
-A style holding the service names of ports to complete.  If this is
-not set by the user, the service names from `tt(/etc/services)' will
-be used.
+A a list of Internet service names (network ports) to complete.  If this is
+not set, service names are taken from the file `tt(/etc/services)'.
 )
 kindex(prefix-hidden, completion style)
 item(tt(prefix-hidden))(
-This is used when matches with a common prefix are added (e.g. option
-names).  If it is `true', this prefix will not be shown in the list of
-matches.
+This is used for certain completions which share a common prefix, for
+example command options beginning with dashes.  If it is `true', the
+prefix will not be shown in the list of matches.
 
 The default value for this style is `false'.
 )
 kindex(prefix-needed, completion style)
 item(tt(prefix-needed))(
 This, too, is used for matches with a common prefix.  If it is set to
-`true' this common prefix has to be typed by the user to generate the
-matches.  E.g. for options this means that the `tt(-)', `tt(+)', or
-`tt(-)tt(-)' has to be on the line to make option names be completed at
-all.
+`true' this common prefix must be typed by the user to generate the
+matches.  In the case of command options, this means that the initial
+`tt(-)', `tt(+)', or `tt(-)tt(-)' must be typed explicitly before option
+names will be completed.
 
 The default value for this style is `true'.
 )
@@ -2099,42 +2074,44 @@ item(tt(preserve-prefix))(
 This style is used when completing path names.  Its value should be a
 pattern matching an initial prefix of the word to complete that should
 be left unchanged under all circumstances.  For example, on some Unices
-an initial `tt(//)' (double slash) has a special meaning and hence
-should be kept.  For that one could set this style to the string
-`tt(//)'.  As another example, setting this style to `tt(?:/)' under
-Cygwin would allow completion after `tt(a:/...)' and the like.
+an initial `tt(//)' (double slash) has a special meaning; setting
+this style to the string `tt(//)' will preserve it.  As another example,
+setting this style to `tt(?:/)' under Cygwin would allow completion
+after `tt(a:/...)' and so on.
 )
 kindex(range, completion style)
 item(tt(range))(
 This is used by the tt(_history) completer and the
 tt(_history_complete_word) bindable command to decide which words
-should be completed.  It may be set to a number, var(N), to say that
-only the last var(N) words from the history should be completed.  The
-value may also be of the form `var(max)tt(:)var(slice)'.  This means
-that first the last var(slice) words will be completed.  If that
+should be completed.  
+
+If it is a singe number, only the last var(N) words from the history
+will be completed.
+
+If it is a range of the form `var(max)tt(:)var(slice)',
+the last var(slice) words will be completed; then if that
 yields no matches, the var(slice) words before those will be tried and 
-so on, until either at least one match is generated or var(max) words
-have been tried.  The default is to complete all words from the
-history at once.
+so on.  This process stops either when at least one match was been
+found, or var(max) words have been tried.
+
+The default is to complete all words from the history at once.
 )
 kindex(regular, completion style)
 item(tt(regular))(
 This style is used by the tt(_expand_alias) completer and bindable 
-command.  If set to `true' (the default), regular aliases will be
-expanded but only in command position.  If it is set to `false', regular
-aliases will never be expanded and if it is set to the string
-`tt(always)', regular aliases will be expanded even if not in command
-position.
+command.  If set to `tt(true)' (the default), regular aliases will be
+expanded but only in command position.  If it is set to `tt(false)',
+regular aliases will never be expanded.   If it is set to `tt(always)',
+regular aliases will be expanded even if not in command position.
 )
 kindex(remote-access, completion style)
 item(tt(remote-access))(
-In order to generate matches for some commands such as tt(cvs) it is
-necessary to make connections to remote systems to retrieve the
-pertinent information. If this style is set to `false' such remote
-connections will not be made. Note that in some cases, in particular
-with tt(cvs), this may also prevent connections which are actually
-local because it may not be known if a certain command will make a
-remote connection.
+If set to tt(false), certain commands will be prevented from making
+Internet connections to retrieve remote information.  This includes the
+completion for the tt(CVS) command.
+
+It is not always possible to know if connections are in fact to a remote
+site, so some may be prevented unnecessarily.
 )
 kindex(remove-all-dups, completion style)
 item(tt(remove-all-dups))(
@@ -2148,7 +2125,7 @@ If this is set for the tt(default) tag, its
 value will be displayed during menu selection (see the tt(menu) style
 above) when the completion list does not fit on the screen as a
 whole.  The same escapes as for the tt(list-prompt) style are
-understood, but give the number of the match or line the mark is
+understood, except that the numbers refer to the match or line the mark is
 on.  A default prompt is used when the value is the empty string.
 )
 kindex(select-scroll, completion style)
@@ -2156,42 +2133,41 @@ item(tt(select-scroll))(
 This style is tested for the tt(default) tag and determines how a
 completion list is scrolled during a menu selection (see the tt(menu)
 style above) when the completion list does not fit on the screen as a
-whole.  Its value should be `tt(0)' (zero) to scroll by
-half-screenfuls, a positive integer to scroll by that many lines and a
-negative number to scroll by the number of lines of the screen minus
-that number (or plus the number, since it is negative).  The default is to
-scroll by single lines.
+whole.  If the value is `tt(0)' (zero), the list is scrolled by
+half-screenfuls; if it is a positive integer, the list is scrolled by the
+given number of lines; if it is a negative number, the list is scrolled by a
+screenful minus the absolute value of the given number of lines.
+The default is to scroll by single lines.
 )
 kindex(separate-sections, completion style)
 item(tt(separate-sections))(
 This style is used with the tt(manuals) tag when completing names of
 manual pages.  If it is `true', entries for different sections are
 added separately using tag names of the form `tt(manual.)var(X)',
-where var(X) is the section number.  This means that it is possible to
-make pages from different sections be listed separately by setting the
-tt(group-name) style.  The default for this style is `false'.
+where var(X) is the section number.  When the tt(group-name) style is
+also in effect, pages from different sections will appear separately.
+The default for this style is `false'.
 )
 kindex(single-ignored, completion style)
 item(tt(single-ignored))(
-This is used by the tt(_ignored) completer.  It specifies what
-should be done if it can generate only one match, which is often a
-special case.  If its value is `tt(show)', the single match will be
+This is used by the tt(_ignored) completer when there is only one match.
+If its value is `tt(show)', the single match will be
 displayed but not inserted.  If the value is `tt(menu)', then the single
 match and the original string are both added as matches and menu completion
-is started so that one can easily select either of them.
+is started, making it easy to select either of them.
 )
 kindex(sort, completion style)
 item(tt(sort))(
-If set to `true', completion functions that generate words from the
-history as possible matches sort these words alphabetically instead of
+If set to `true', completing words from the command
+history sorts the words alphabetically instead of
 keeping them in the order in which they appear in the history (from
 youngest to oldest).
 
-This is also used by the tt(_expand) completer.  Here, if it is set to
+This is also used by the tt(_expand) completer. If it is set to
 `true', the expansions generated will always be sorted.  If it is set
 to `tt(menu)', then the expansions are only sorted when they are offered 
-as single strings (not in the string containing all possible
-expansions).
+as single strings but not in the string containing all possible
+expansions.
 )
 kindex(special-dirs, completion style)
 item(tt(special-dirs))(
@@ -2200,20 +2176,19 @@ Normally, the completion code will not produce the directory names
 `true', it will add both `tt(.)' and `tt(..)' as possible completions;
 if it is set to `tt(..)', only `tt(..)' will be added.
 
-The following example sets tt(special-dirs) to `tt(..)' only when the
+The following example sets tt(special-dirs) to `tt(..)' when the
 current prefix is empty, is a single `tt(.)', or consists only of a path
-beginning with one or more `tt(../)', and otherwise sets it to `false'.
+beginning with `tt(../)'.  Otherwise the value is `false'.
 
 example(zstyle -e ':completion:*' special-dirs \ 
    '[[ $PREFIX = LPAR()../RPAR()#LPAR()|.|..RPAR() ]] && reply=LPAR()..RPAR()')
 )
 kindex(squeeze-slashes, completion style)
 item(tt(squeeze-slashes))(
-If set to `true', sequences of slashes (as in `tt(foo//bar)') will be
-treated as if they were only one slash when completing pathnames.  This
-is the usual behaviour of UNIX paths.  However, by default the file
-completion function behaves as if there were a `tt(*)' between
-the slashes.
+If set to `true', sequences of slashes in filename paths (for example in
+`tt(foo//bar)') will be treated as a single slash.  This is the usual
+behaviour of UNIX paths.  However, by default the file completion
+function behaves as if there were a `tt(*)' between the slashes.
 )
 kindex(stop, completion style)
 item(tt(stop))(
@@ -2227,7 +2202,7 @@ menu completion.
 kindex(strip-comments, completion style)
 item(tt(strip-comments))(
 If set to `true', this style causes non-essential comment text to be
-removed from the completion matches. Currently it is only used when
+removed from completion matches.  Currently it is only used when
 completing e-mail addresses where it removes any display name from the
 addresses, cutting them down to plain var(user@host) form.
 )
@@ -2252,9 +2227,9 @@ The default is `true'.
 kindex(suffix, completion style)
 item(tt(suffix))(
 This is used by the tt(_expand) completer if the word starts with a
-tilde or contains a parameter expansion. If it is set to `true', the word will
-only be expanded if it doesn't have a suffix, i.e. if it is something
-like `tt(~foo)' or `tt($foo)', but not if it is `tt(~foo/)' or
+tilde or contains a parameter expansion.  If it is set to `true', the
+word will only be expanded if it doesn't have a suffix, i.e. if it is
+something like `tt(~foo)' or `tt($foo)' rather than `tt(~foo/)' or
 `tt($foo/bar)', unless that suffix itself contains characters eligible
 for expansion.  The default for this style is `true'.
 )
@@ -2273,8 +2248,9 @@ For example:
 example(zstyle ':completion:*:complete:-command-:*' tag-order \ 
     'commands functions')
 
-specifies that completion in command position should offer only
-completions for external commands and shell functions immediately.
+specifies that completion in command position first offers
+external commands and shell functions.  Remaining tags will be tried if
+no completions are found.
 
 In addition to tag names, each string in the value may take one of the
 following forms:
@@ -2295,57 +2271,51 @@ the same as if all other possible tags for the context had been
 listed.
 )
 item(var(tag)tt(:)var(label) ...)(
-In strings not starting with an exclamation mark, it is also possible
-to specify tag labels instead of only tags, where var(tag) is one of
-the tags offered
-by the completion function for the current context and var(label) is a 
-name.  For this, the completion function will generate matches in the
-same way as for the var(tag) but it will use the var(label) in place
-of the tag in the context names used to look up styles.  If the
-var(label) starts with a hyphen, the var(tag) is prepended to the
+Here, var(tag) is one of the standard tags and var(label) is an
+arbitrary name.  Matches are generated as normal but the name var(label)
+is used in contexts instead of var(tag).  This is not useful in words
+starting with tt(!).
+
+If the var(label) starts with a hyphen, the var(tag) is prepended to the
 var(label) to form the name used for lookup.  This can be
 used to make the completion system try a certain tag more than once,
-supplying different style settings for each attempt, see below for an
+supplying different style settings for each attempt; see below for an
 example.
-
-The var(label) may optionally be followed by a second colon and a
-description.  This description will then be used for the `tt(%d)' in
+)
+item(var(tag)tt(:)var(label)tt(:)var(description))(
+As before, but tt(description) will replace the `tt(%d)' in
 the value of the tt(format) style instead of the default description
-supplied by the completion function.  Spaces in the description have to 
-be quoted by preceding them with a backslash and a `tt(%d)' appearing
-in the description is replaced with the description given by the
+supplied by the completion function.  Spaces in the description must
+be quoted with a backslash.  A `tt(%d)' appearing
+in var(description) is replaced with the description given by the
 completion function.
 )
 enditem()
 
-In each of the cases above, the tag may also be a pattern or more than 
-one pattern inside braces and separated by commas.  In this
-case all of the offered tags matching the pattern(s) will be used except 
-for those that are given explicitly in the same string.  There are
-probably two main uses of this.  One is the case where one wants to try
-one of the tags more than once, setting other styles differently for
-each try, but still wants to use all the other tags without having to
+In any of the forms above the tag may be a pattern or several
+patterns in the form `tt({)var(pat1)tt(,)var(pat2...)tt(})'.  In this
+case all matching tags will be used except 
+for any given explicitly in the same string.
+
+One use of these features is to try
+one tag more than once, setting other styles differently on
+each attempt, but still to use all the other tags without having to
 repeat them all.  For example, to make completion of function names in
 command position ignore all the completion functions starting with an
-underscore the first time completion is tried, one could do:
+underscore the first time completion is tried:
 
 example(zstyle ':completion:*:*:-command-:*' tag-order \ 
     'functions:-non-comp *' functions
 zstyle ':completion:*:functions-non-comp' ignored-patterns '_*')
 
-Here, the completion system will first try all tags offered, but will
-use the tag label tt(functions-non-comp) when looking up styles for
-the function names completed.  For this, the tt(ignored-patterns) style 
-is set to exclude functions starting with an underscore from the set
-of possible matches.  If none of the generated matches match the string 
-on the line, the completion system will use the second value of the
-tt(tag-order) style and complete functions names again, but this time
-using the name tt(functions) to look up styles, so that the
-tt(ignored-patterns) style is not used and all function names
-are considered.
+On the first attempt, all tags will be offered but the tt(functions) tag
+will be replaced by tt(functions-non-comp).  The tt(ignored-patterns) style 
+is set for this tag to exclude functions starting with an underscore.
+If there are no matches, the second value of the
+tt(tag-order) style is used which completes functions using the default
+tag, this time presumably including all function names.
 
-Of course, this can also be used to split the matches for one tag into 
-different groups. For example:
+The matches for one tag can be split into different groups.  For example:
 
 example(zstyle ':completion:*' tag-order \ 
     'options:-long:long\ options
@@ -2356,12 +2326,12 @@ zstyle ':completion:*:options-long' ignored-patterns '[-+](|-|[^-]*)'
 zstyle ':completion:*:options-short' ignored-patterns '--*' '[-+]?'
 zstyle ':completion:*:options-single-letter' ignored-patterns '???*')
 
-With the tt(group-names) style set, this makes options beginning with
+With the tt(group-names) style set, options beginning with
 `tt(-)tt(-)', options beginning with a single `tt(-)' or `tt(+)' but
-containing multiple characters, and single-letter options be displayed
-in separate groups with different descriptions.
+containing multiple characters, and single-letter options will be
+displayed in separate groups with different descriptions.
 
-The second interesting use of patterns is the case where one wants to
+Another use of patterns is to
 try multiple match specifications one after another.  The
 tt(matcher-list) style offers something similar, but it is tested very
 early in the completion system and hence can't be set for single
@@ -2369,6 +2339,7 @@ commands nor for more specific contexts.  Here is how to
 try normal completion without any match specification and, if that
 generates no matches, try again with case-insensitive matching, restricting
 the effect to arguments of the command tt(foo):
+
 example(zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
 zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}')
 
@@ -2379,9 +2350,9 @@ each has tt(-case) appended to its name for lookup of styles.  Hence this
 time the value for the tt(matcher) style from the second call to tt(zstyle)
 in the example is used to make completion case-insensitive.
 
-Using the tt(-e) option of the tt(zstyle) builtin command, it is
-possible to specify conditions saying when certain tags are to be
-used. For example:
+It is possible to use the tt(-e) option of the tt(zstyle) builtin
+command to specify conditions for the use of particular tags.  For
+example:
 
 example(zstyle -e '*:-command-:*' tag-order '
     if [[ -n $PREFIX ]]; then
@@ -2390,18 +2361,18 @@ example(zstyle -e '*:-command-:*' tag-order '
       reply=( - )
     fi')
 
-Makes completion in command position happen only if the string on 
-the line is not empty.  This is tested using the tt(PREFIX)
-parameter which is special in completion widgets; see
+Completion in command position will be attempted only if the string
+typed so far is not empty.  This is tested using the tt(PREFIX)
+special parameter; see
 ifzman(zshcompwid)\
 ifnzman(noderef(Completion Widgets))
-for a description of these special parameters.
-Setting tt(reply) to an empty array ensures that only the default
-behaviour of trying all tags at once is used and setting it to an
-array containing only a hyphen disables that default behaviour -- thus 
-keeping all tags from being tried.
+for a description of parameters which are special inside completion widgets.
+Setting tt(reply) to an empty array provides the default
+behaviour of trying all tags at once; setting it to an
+array containing only a hyphen disables the use of all tags and hence of
+all completions.
 
-If no style has been defined for a context, the strings
+If no tt(tag-order) style has been defined for a context, the strings
 `tt((|*-)argument-* (|*-)option-* values)' and `tt(options)' plus all
 tags offered by the completion function will be used to provide a
 sensible default behavior that causes arguments (whether normal command
@@ -2410,23 +2381,38 @@ most commands.
 )
 kindex(urls, completion style)
 item(tt(urls))(
-This is used together with the the tt(urls) tag by completion
-functions that generate URLs as possible matches.  If the value
-consists of more than one string or if the only string does not name a 
-file or directory, the strings are used as the URLs to complete.
+This is used together with the the tt(urls) tag by
+functions completing URLs.
+
+If the value consists of more than one string, or if the only string
+does not name a file or directory, the strings are used as the URLs to
+complete.
 
-If the value contains only one string and that is the name of a normal 
-file, the URLs are taken from that file (where the URLs may be
+If the value contains only one string which is the name of a normal 
+file the URLs are taken from that file (where the URLs may be
 separated by white space or newlines).
 
-Finally, if the only string in the value names a directory, that
-should contain sub-directories named after the
-retrieval methods which occur as the first part of a URL, i.e.
-`tt(http)', `tt(ftp)', `tt(bookmark)', and so on.  These
-sub-directories should contain files and other sub-directories whose
-pathnames are possible completions after the initial `tt(http://)',
-`tt(ftp://)', etc. See the description in the file tt(_urls) in the
-tt(User) sub-directory of the completion system for more information.
+Finally, if the only string in the value names a directory, the
+directory hierarchy rooted at this directory gives the completions.  The
+top level directory should be the file access method, such as
+`tt(http)', `tt(ftp)', `tt(bookmark)' and so on.  In many cases the next
+level of directories will be a filename.  The directory hierarchy can
+descend as deep as necessary.
+
+For example, 
+
+example(zstyle ':completion:*' urls ~/.urls
+mkdir -p ~/.urls/ftp/ftp.zsh.org/pub/development
+)
+
+allows completion of all the components of the URL
+tt(ftp://ftp.zsh.org/pub/development) after suitable commands such as
+`tt(netscape)' or `tt(lynx)'.  Note, however, that access methods and
+files are completed separately, so if the tt(hosts) style is set hosts
+can be completed without reference to the tt(urls) style.
+
+See the description in the function tt(_urls) itself
+for more information (e.g. `tt(more $^fpath/_urls(N))').
 )
 kindex(use-cache, completion style)
 item(tt(use-cache))(
@@ -2442,8 +2428,8 @@ tt(no), and tt(off), the completion system may use any completion
 specifications defined with the tt(compctl) builtin command.  If the
 style is unset, this is done only if the tt(zsh/compctl) module
 is loaded.  The string may also contain the substring `tt(first)' to
-make the definition for `tt(compctl -T)' be used, and the substring
-`tt(default)' to make the one for `tt(compctl -D)' be used.
+use completions defined with `tt(compctl -T)', and the substring
+`tt(default)' to use the completion defined with `tt(compctl -D)'.
 
 Note that this is only intended to smooth the transition from
 tt(compctl) to the new completion system and may disappear in the
@@ -2451,9 +2437,10 @@ future.
 
 Note also that the definitions from tt(compctl) will only be used if
 there is no specific completion function for the command in question.  For
-example, while completing arguments to the command tt(foo), if this was
-handled by a command function tt(_foo), tt(compctl) would never be tried,
-while if it was handled by tt(_default), tt(compctl) would be tried.
+example, if there is a function tt(_foo) to complete arguments to the
+command tt(foo), tt(compctl) will never be invoked for tt(foo).
+However, the tt(compctl) version will be tried if tt(foo) only uses
+default completion.
 )
 kindex(use-perl, completion style)
 item(tt(use-perl))(
@@ -2468,8 +2455,8 @@ extended depending on authorial frustration.
 )
 kindex(users, completion style)
 item(tt(users))(
-This may be set to a list of names that should be completed whenever 
-a username is needed. If it is not set or the string on the line
+This may be set to a list of usernames to be completed.
+If it is not set or the string on the line
 doesn't match any of the strings in this list, all usernames will be
 completed.
 )
@@ -2478,16 +2465,16 @@ item(tt(users-hosts))(
 The values of this style should be of the form
 `var(user)tt(@)var(host)' or `var(user)tt(:)var(host)'. It is used for
 commands that need pairs of
-user- and hostnames.  For such commands, only the pairs from this style 
-are used and if, for example, the username is already typed, then only 
-the hostnames for which there is a pair with that username is defined.
+user- and hostnames.  These commands will complete usernames from this
+style (only), and will restrict subsequent hostname completion to hosts
+paired with that user in one of the values of the style.
 
-If set for the tt(my-accounts) tag, this is used for commands such as
-tt(rlogin) and tt(ssh); in this case the style should contain the names of
-the user's own accounts on remote hosts.  If set for the tt(other-accounts)
-tag, it is used for commands such as tt(talk) and tt(finger) and should
-contain other people's accounts.  Finally, it may also be used by some
-commands with the tt(accounts) tag.
+It is possible to group values for sets of commands which allow a remote
+login, such as tt(rlogin) and tt(ssh), by using the tt(my-accounts) tag.
+Similarly, values for sets of commands which usually refer to the
+accounts of other people, such as tt(talk) and tt(finger), can be
+grouped by using the tt(other-accounts) tag.  More ambivalent commands
+may use the tt(accounts) tag.
 )
 kindex(users-hosts-ports, completion style)
 item(tt(users-hosts-ports))(
@@ -2496,11 +2483,9 @@ containing strings of the form `var(user)tt(@)var(host)tt(:)var(port)'.
 )
 kindex(verbose, completion style)
 item(tt(verbose))(
-This is used in several contexts to decide if only a simple or a
-verbose list of matches should be generated. For example some commands 
-show descriptions for option names if this style is `true'.
-
-The default value for this style is `true'.
+If set, as it is by default, the completion listing is more verbose.
+In particular many commands show descriptions for options if this
+style is `true'.
 )
 kindex(word, completion style)
 item(tt(word))(
@@ -2539,38 +2524,27 @@ value is zero, no other completers are tried and the tt(_main_complete)
 function returns.
 
 If the first argument to tt(_main_complete) is a single hyphen, the
-arguments will not be taken as names of completers. Instead, the
+arguments will not be taken as names of completers.  Instead, the
 second argument gives a name to use in the var(completer) field of the 
 context and the other arguments give a command name and arguments to
 call to generate the matches.
 
-The following completer functions are contained in the distribution (users
-may write their own):
+The following completer functions are contained in the distribution,
+although users may write their own.  Note that in contexts the leading
+underscore is stripped, for example basic completion is performed in the
+context `tt(:completion::complete:)var(...)'.
 
 cindex(completion system, completers)
 startitem()
 findex(_all_matches)
 item(tt(_all_matches))(
 This completer can be used to add a string consisting of all other
-matches.  To ensure, that this string is always added, this completer
-has to be used as the first completer in the list.  The
-tt(avoid-completer) style is used to decide if the string should be
-added.  This will only be done if the matches were generated by a
-completer not named by one of the values of the style.
-
-This function also uses the style tt(old-matches).  If it is set to
-`true' or to the string `tt(only)' and there is a list of matches from 
-a previous completion, those matches will be inserted in the command
-line.  If it is set to the the string `tt(only)', it will only insert
-an old list and won't add the string for all matches of the list
-currently being generated.
-
-With the tt(old-matches) style set, this completer should probably not 
-be called unconditionally.  Instead one could use the tt(-e) option of 
-the tt(zstyle) builtin command to add a condition to the tt(completer) 
-or to the tt(old-matches) style.  Alternatively, one could use the
-tt(_generic) function to bind tt(_all_matches) to a separate key
-binding, for example:
+matches.  As it influences later completers it must appear as the first
+completer in the list.  The list of all matches is affected by the
+tt(avoid-completer) and tt(old-matches) styles described above.
+
+It may be useful to use the tt(_generic) function described below
+to bind tt(_all_matches) to its own keystroke, for example:
 
 example(zle -C all-matches complete-word _generic
 bindkey '^Xa' all-matches
@@ -2579,9 +2553,9 @@ zstyle ':completion:all-matches::::' completer _all_matches)
 )
 findex(_approximate)
 item(tt(_approximate))(
-This completer function uses the tt(_complete) completer to generate
-a list of strings for the context the cursor is currently in, allowing 
-you to specify a maximum number of errors:  see the description of
+This is similar to the basic tt(_complete) completer but allows the
+completions to undergo corrections.  The maximum number of errors can be
+specified by the tt(max-errors) style; see the description of
 approximate matching in
 ifzman(\
 zmanref(zshexpn)
@@ -2589,9 +2563,8 @@ zmanref(zshexpn)
 ifnzman(\
 noderef(Filename Generation)
 )\
-for how errors are counted.  The resulting list of corrected and completed
-strings is then presented to the user.  The intended use of this completer
-function is to try after the normal tt(_complete) completer by setting:
+for how errors are counted.  Normally this completer will only be tried
+after the normal tt(_complete) completer:
 
 example(zstyle ':completion:*' completer _complete _approximate)
 
@@ -2607,19 +2580,16 @@ tt(format) style for the former may contain the additional sequences
 accepted to generate the corrections and the original string,
 respectively.
 
-As with all completers, tt(_approximate) uses its name without the
-underscore in the var(completer) field of the context name.  Once it
-has started trying to generate matches, it will append a minus sign
-and the number of errors accepted to its name.  tt(_approximate) will
-first look for completions with one error, then two, and on so up to the
-limit on the number of errors set by the tt(max-errors) style.
-Hence on the first try the completer field of the context contains
+The completer progressively increases the number of errors allowed up to
+the limit by the tt(max-errors) style, hence if a completion is found
+with one error, no completions with two errors will be shown, and so on.
+It modifies the completer name in the context to indicate the number of
+errors being tried: on the first try the completer field contains
 `tt(approximate-1)', on the second try `tt(approximate-2)', and so on.
 
 When tt(_approximate) is called from another function, the number of
-errors to accept may be given with the tt(-a) option.  Its argument
-should be the same as the value of the tt(max-errors) style, all in one
-string.
+errors to accept may be passed with the tt(-a) option.  The argument
+is in the same format as the tt(max-errors) style, all in one string.
 
 Note that this completer (and the tt(_correct) completer mentioned
 below) can be quite expensive to call, especially when a large number
@@ -2653,7 +2623,7 @@ To complete arguments of commands, tt(_complete) uses the utility function
 tt(_normal), which is in turn responsible for finding the particular
 function; it is described below.  Various contexts of the form
 tt(-)var(context)tt(-) are handled specifically. These are all
-mentioned above for the tt(#compdef) tag.
+mentioned above as possible arguments to the tt(#compdef) tag.
 
 Before trying to find a function for a specific context, tt(_complete) 
 checks if the parameter `tt(compcontext)' is set.  If it is set to an
@@ -2665,23 +2635,23 @@ descriptions for the matches.  If `tt(compcontext)' is set to a string
 containing colons, it should be of
 the form `var(tag)tt(:)var(descr)tt(:)var(action)'.  In this case the
 var(tag) and var(descr) give the tag and description to use and the
-var(action) says what should be completed in one of the forms
-described for the tt(_arguments) utility function below.
+var(action) indicates what should be completed in one of the forms
+accepted by the tt(_arguments) utility function described below.
 
 Finally, if `tt(compcontext)' is set to a string without colons, the
 value is taken as the name of the context to use and the function
 defined for that context will be called.  For this purpose, there is a
 special context named tt(-command-line-) that completes whole command
-lines (commands and their arguments) and is not used by the completion
-system itself, but has a function handling completion for it.
+lines (commands and their arguments).  This is not used by the completion
+system itself but is nonetheless handled when explicitly called.
 )
 findex(_correct)
 item(tt(_correct))(
 Generate corrections, but not completions, for the current word; this is
 similar to tt(_approximate) but will not allow any number of extra
-characters at the cursor as that completer does, hence this is
-similar to spell-checking.  It calls tt(_approximate) but uses a
-different var(completer) field in the context name.
+characters at the cursor as that completer does.  The effect is
+similar to spell-checking.  It is based on tt(_approximate), but the
+completer field in the context name is tt(correct).
 
 For example, with:
 
@@ -2697,8 +2667,8 @@ correcting completion will be tried, with the first one accepting two
 errors and the second one accepting three errors.
 
 When tt(_correct) is called as a function, the number of errors to accept
-may be given following the tt(-a) option.  The argument should be the same
-as the value of the tt(accept) style, all in one string.
+may be given following the tt(-a) option.  The argument is in the same
+form a values to the tt(accept) style, all in one string.
 
 This completer function is intended to be used without the
 tt(_approximate) completer or, as in the example, just before
@@ -2708,40 +2678,39 @@ generated by the tt(_correct) completer -- and probably more.
 )
 findex(_expand)
 item(tt(_expand))(
-This completer function does not really do completion, but instead
+This completer function does not really perform completion, but instead
 checks if the word on the command line is eligible for expansion and,
-if it is, gives detailed control over how this expansion is done.  When
-using this, one should not use the tt(expand-or-complete) widget, but
-instead use tt(complete-word), as tt(expand-or-complete)
-will expand the string on the line before the completion widget is
-called.  Also, this completer should be called before the tt(_complete) 
+if it is, gives detailed control over how this expansion is done.  For
+this to happen, the completion system needs to be invoked with
+tt(complete-word), not tt(expand-or-complete) (the default binding for
+tt(TAB)), as otherwise the string will be expanded by the shell's
+internal mechanism before the completion system is started.
+Note also this completer should be called before the tt(_complete) 
 completer function.
 
-The tags used when generating expansions are tt(all-expansions) for
-the string containing all possible expansions, tt(expansions) when
-adding the possible expansions as single matches and tt(original) when 
-adding the original string from the line.  In which order these strings 
-are generated and which of these strings are generated at all can be
-controlled by using the tt(group-order) style and by modifying the
-tt(tag-order) style, as usual.
+The tags used when generating expansions are tt(all-expansions) for the
+string containing all possible expansions, tt(expansions) when adding
+the possible expansions as single matches and tt(original) when adding
+the original string from the line.  The order in which these strings are
+generated, if at all, can be controlled by the tt(group-order) and
+tt(tag-order) styles, as usual.
 
 The format string for tt(all-expansions) and for tt(expansions) may
 contain the sequence `tt(%o)' which will be replaced by the original
 string from the line.
 
-Which kind of expansion is tried is controlled by the tt(substitute),
+The kind of expansion to be tried is controlled by the tt(substitute),
 tt(glob) and tt(subst-globs-only) styles.
 
-When tt(_expand) is called as a function, the different modes may be
-selected with options.  The tt(-s) to tt(substitute), tt(-g) to
-tt(glob) and tt(-o) to tt(subst-globs-only).
+It is also possible to call tt(_expand) as a function, in which case the
+different modes may be selected with options: tt(-s) for
+tt(substitute), tt(-g) for tt(glob) and tt(-o) for tt(subst-globs-only).
 )
 findex(_expand_alias)
 item(tt(_expand_alias))(
 If the word the cursor is on is an alias, it is expanded and no other
 completers are called.  The types of aliases which are to be expanded can
-be controlled with the tt(regular), tt(global) and tt(disabled)
-styles.
+be controlled with the styles tt(regular), tt(global) and tt(disabled).
 
 This function is also a bindable command, see
 ifzman(the section `Bindable Commands' below)\
@@ -2750,7 +2719,7 @@ ifnzman(noderef(Bindable Commands)).
 findex(_history)
 item(tt(_history))(
 Complete words from the shell's command  history.  This completer 
-uses the tt(remove-all-dups), and tt(sort) styles also used by the
+can be controlled by the tt(remove-all-dups), and tt(sort) styles as for the
 tt(_history_complete_word) bindable command, see
 ifzman(the section `Bindable Commands' below)\
 ifnzman(noderef(Bindable Commands))
@@ -2764,19 +2733,13 @@ The tt(ignored-patterns) style can be set to a list of patterns which are
 compared against possible completions; matching ones are removed.
 With this completer those matches can be reinstated, as
 if no tt(ignored-patterns) style were set.  The completer actually
-generates its own list of matches; which completers are used
-for this is determined in the same way as for the tt(_prefix)
-completer.
-
-The tt(single-ignored) style is used if only one
-match could be generated.  It can be set to tt(show) to prevent that match 
-from being displayed or inserted into the line, or it can be set to
-tt(menu), in which case the single match and the original string from the
-line will be offered in a menu completion.
+generates its own list of matches; which completers are invoked
+is determined in the same way as for the tt(_prefix) completer.
+The tt(single-ignored) style is also available as described above.
 )
 findex(_list)
 item(tt(_list))(
-This completer allows one to delay the insertion of matches until
+This completer allows the insertion of matches to be delayed until
 completion is attempted a second time without the word on the line
 being changed.  On the first attempt, only the list of matches will be
 shown.  It is affected by the styles tt(condition) and tt(word), see
@@ -2786,35 +2749,28 @@ ifnzman(noderef(Completion System Configuration)).
 findex(_match)
 item(tt(_match))(
 This completer is intended to be used after the tt(_complete)
-completer. It allows one to give patterns on the command line and
-to complete all strings matching these patterns from the set of
-possible completions for the context the cursor is in, without having
-to set the tt(GLOB_COMPLETE) option.
+completer.  It behaves similarly but the string on the command line may
+be a pattern to match against trial completions.  This gives the effect
+of the tt(GLOB_COMPLETE) option.
 
-Normally this will be done by taking the pattern from the line,
+Normally completion will be performed by taking the pattern from the line,
 inserting a `tt(*)' at the cursor position and comparing the resulting
-pattern with the possible completions generated.  However, if the
-tt(match-original) style has a value of tt(only), no `tt(*)' will be
-inserted.  If tt(match-original) has any other non-empty string as its
-value, this completer will first try to generate matches without, then
-with a `tt(*)' inserted at the cursor position.
+pattern with the possible completions generated.  This can be modified
+with the tt(match-original) style described above.
 
 The generated matches will be offered in a menu completion unless the
-tt(insert-unambiguous) style is set to `true'.  In
-this case menu completion will only be started if no unambiguous string
-could be generated that is at least as long as the original string.
-The style may also be set to the string `tt(pattern)'.  This will keep 
-the pattern on the line intact as long as there isn't an unambiguous
-completion with which it could be replaced.
+tt(insert-unambiguous) style is set to `true'; see the description above
+for other options for this style.
 
-Note that the matcher specifications defined globally or used by the
-completion functions will not be used.
+Note that matcher specifications defined globally or used by the
+completion functions (the styles tt(matcher-list) and tt(matcher)) will
+not be used.
 )
 findex(_menu)
 item(tt(_menu))(
 This completer is a simple example function implemented to show how
 menu completion can be done in shell code.  It should be used as the
-first completer and has the effect of making the code perform
+first completer and has the effect of making later completers perform
 menu completion.  Note that this is independent of the setting of the
 tt(MENU_COMPLETE) option and does not work with the other
 menu completion widgets such as tt(reverse-menu-complete), or
@@ -2838,15 +2794,15 @@ findex(_prefix)
 item(tt(_prefix))(
 This completer can be used to try completion with the suffix (everything
 after the cursor) ignored.  In other words, the suffix will not be
-considered to be
-part of the word to complete and hence does not need to be matched.  It
-uses the tt(completer) style to decide which other completers to call to
-try to generate matches.  If this style is unset, the list of completers
-set for the current context is used -- except, of course,
-the tt(_prefix) completer itself.  Furthermore, if this completer appears
+considered to be part of the word to complete.  The effect is similar
+to the tt(expand-or-complete-prefix) command.
+
+The tt(completer) style is used to decide which other completers are to
+be called to generate matches.  If this style is unset, the list of
+completers set for the current context is used -- except, of course, the
+tt(_prefix) completer itself.  Furthermore, if this completer appears
 more than once in the list of completers only those completers not
-already tried by the last invocation of tt(_prefix) will be
-called.
+already tried by the last invocation of tt(_prefix) will be called.
 
 For example, consider this global tt(completer) style:
 
@@ -2857,13 +2813,16 @@ Here, the tt(_prefix) completer tries normal completion but ignoring the
 suffix.  If that doesn't generate any matches, and neither does
 the call to the tt(_correct) completer after it, tt(_prefix) will 
 be called a second time and, now only trying correction with the
-suffix ignored.  If you want to use tt(_prefix) as the last resort and
-try only normal completion, you can use:
+suffix ignored.  On the second invocation the completer part of the
+context appears as `tt(foo)'.
+
+To use tt(_prefix) as the last resort and try only normal completion
+when it is invoked:
 
 example(zstyle ':completion:*' completer _complete ... _prefix
 zstyle ':completion::prefix:*' completer _complete)
 
-The tt(add-space) style is also used.  If it is set to `true' then
+The tt(add-space) style is also respected.  If it is set to `true' then
 tt(_prefix) will insert a space between the matches generated (if any) 
 and the suffix.
 
@@ -2875,9 +2834,9 @@ called and hence there will be no suffix.
 findex(bashcompinit)
 item(tt(bashcompinit))(
 This function provides compatibility with bash's programmable completion
-system. When run it will define the functions, tt(compgen) and
-tt(complete) which correspond to the bash builtins with the same names. It
-will then be possible to use completion specifications and functions
+system.  When run it will define the functions, tt(compgen) and
+tt(complete) which correspond to the bash builtins with the same names.
+It will then be possible to use completion specifications and functions
 written for bash.
 )
 enditem()
@@ -2931,37 +2890,38 @@ findex(_expand_alias (^Xa))
 item(tt(_expand_alias (^Xa)))(
 This function can be used as a completer and as a bindable command.
 It expands the word the cursor is on if it is an alias.  The types of
-aliases expanded can be controlled with the tt(regular), tt(global) and
-tt(disabled) styles.
+alias expanded can be controlled with the styles tt(regular), tt(global)
+and tt(disabled).
 
 When used as a bindable command there is one additional feature that
 can be selected by setting the tt(complete) style to `true'.  In this
-case, if the word isn't the name of an alias, tt(_expand_alias) tries
-to complete the word to a full alias name without expanding it (but
-leaving the cursor directly after the completed word so that invoking
-tt(_expand_alias) once more will expand the now-complete alias name).
+case, if the word is not the name of an alias, tt(_expand_alias) tries
+to complete the word to a full alias name without expanding it.  It
+leaves the cursor directly after the completed word so that invoking
+tt(_expand_alias) once more will expand the now-complete alias name.
 )
 findex(_expand_word (^Xe))
 item(tt(_expand_word (^Xe)))(
 Performs expansion on the current word:  equivalent to the standard
 tt(expand-word) command, but using the tt(_expand) completer.  Before
-calling it, the var(function) field is set to `tt(expand-word)'.
+calling it, the var(function) field of the context is set to
+`tt(expand-word)'.
 )
 findex(_generic)
 item(tt(_generic))(
 This function is not defined as a widget and not bound by
-default. However, it can be used to define a widget and will then
+default.  However, it can be used to define a widget and will then
 store the name of the widget in the var(function) field of the context 
-and call the completion system. This allows custom completion widgets
-with their own set of style settings to be easily defined. For example, 
-to define a widget that does normal completion and starts
-menu selection, one could do:
+and call the completion system.  This allows custom completion widgets
+with their own set of style settings to be defined easily.  For example, 
+to define a widget that performs normal completion and starts
+menu selection:
 
 example(zle -C foo complete-word _generic
 bindkey '...' foo
 zstyle ':completion:foo:*' menu yes select=1)
 )
-findex(_history_complete_word) (\e/))
+findex(_history_complete_word (\e/))
 item(tt(_history_complete_word) (\e/))(
 Complete words from the shell's command history. This uses the
 tt(list), tt(remove-all-dups), tt(sort), and tt(stop) styles.
@@ -3043,33 +3003,32 @@ sect(Utility Functions)
 cindex(completion system, utility functions)
 
 Descriptions follow for utility functions that may be
-useful when writing completion functions.  Most of these reside in the
-tt(Base) subdirectory. Like the example 
+useful when writing completion functions.  If functions are installed in
+subdirectories, most of these reside in the
+tt(Base) subdirectory.  Like the example 
 functions for commands in the distribution, the utility functions
 generating matches all follow the convention of returning zero if they
 generated completions and non-zero if no matching completions could be 
 added.
 
-When writing completion functions or other ZLE widgets that call
-completion, it might be interesting to know about two more features
-offered by the tt(_main_complete) function. The arrays
-tt(compprefuncs) and tt(comppostfuncs) may be set to contain names of
-functions that are to be called immediately before or after completion 
-has been tried. The functions will only be called once, unless they
-put themselves into the arrays again.
+Two more features are offered by the tt(_main_complete) function.  The
+arrays tt(compprefuncs) and tt(comppostfuncs) may contain
+names of functions that are to be called immediately before or after
+completion has been tried.  A function will only be called once unless
+it explicitly reinserts itself into the array.
 
 startitem()
 findex(_all_labels)
 item(tt(_all_labels) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(command) var(args) ... ])(
 This is a convenient interface to the tt(_next_label) function below,
 implementing the loop shown in the tt(_next_label) example.  The
-var(command) is the one that should be called to generate the matches. The
+var(command) and its arguments are called to generate the matches.  The
 options stored in the parameter var(name) will automatically be inserted
-into the var(args) given to the var(command).  Normally, they are put
+into the var(args) passed to the var(command).  Normally, they are put
 directly after the var(command), but if one of the var(args) is a single
-hyphen, they are inserted directly before that. If the hyphen is the last
-argument, that will be removed from the argument list before the
-var(command) is called. This allows tt(_all_labels) to be used in almost all
+hyphen, they are inserted directly before that.  If the hyphen is the last
+argument, it will be removed from the argument list before the
+var(command) is called.  This allows tt(_all_labels) to be used in almost all
 cases where the matches can be generated by a single call to the
 tt(compadd) builtin command or by a call to one of the utility functions.
 
@@ -3089,70 +3048,65 @@ those generated by tt(_all_labels).
 findex(_alternative)
 item(tt(_alternative) [ tt(-C) var(name) ] var(specs) ...)(
 This function is useful in simple cases where multiple tags are available.
-Essentially, it implements a loop like the one described for the tt(_tags)
-function above.
+Essentially it implements a loop like the one described for the tt(_tags)
+function below.
 
 The tags to use and the action to perform if a tag is requested are
 described using the var(specs) which are of the form:
-`var(tag)tt(:)var(descr)tt(:)var(action)'. The var(tag)s are offered using
+`var(tag)tt(:)var(descr)tt(:)var(action)'.  The var(tag)s are offered using
 tt(_tags) and if the tag is requested, the var(action) is executed with the
-given description var(descr).  The var(action)s supported are those used
-by the tt(_arguments) function (described below), without the
+given description var(descr).  The var(action)s are those accepted
+by the tt(_arguments) function (described below), excluding the
 `tt(->)var(state)' and `tt(=)var(...)' forms.
 
-For example, the var(action) may be a simple function call. With that
-one could do:
+For example, the var(action) may be a simple function call:
 
 example(_alternative \ 
     'users:user:_users' \ 
     'hosts:host:_hosts')
 
-to offer usernames and hostnames as possible matches (which are
-generated by the tt(_users) and tt(_hosts) functions respectively).
+offers usernames and hostnames as possible matches,
+generated by the tt(_users) and tt(_hosts) functions respectively.
 
-Note that, like tt(_arguments) this will also use tt(_all_labels) to execute 
-the actions, so one doesn't need to call that explicitly unless
-another tag is to be used, for example in a function called from
-tt(_alternative).
+Like tt(_arguments), this functions uses tt(_all_labels) to execute 
+the actions, which will loop over all sets of tags.  Special handling is
+only required if there is an additional valid tag, for example inside a
+function called from tt(_alternative).
 
 Like tt(_tags) this function supports the tt(-C) option to give a
 different name for the argument context field.
 )
 findex(_arguments)
 item(tt(_arguments) [ tt(-ACS) ] [ tt(-O) var(name) ] [ tt(-M) var(matchspec) ] [ tt(:) ] var(spec) ...)(
-This function can be used to complete words on the line by describing the
-options and arguments which may be passed to the command for which
-completion is being performed.  The description is given as arguments to
-this function, with each var(spec) describing one option or normal
-argument of the command.  To separate these var(spec)s from the
-options given to tt(_arguments) itself, they can be preceded by an
-argument containing a single colon.  The forms of var(spec)
-understood are:
+This function can be used to give a complete specification for
+completion for a command whose arguments follow standard UNIX option and
+argument conventions.  The following forms specify individual sets of
+options and arguments; to avoid ambiguity, these may be separated from the
+options to tt(_arguments) itself by a single colon.
 
 startitem()
 xitem(var(n)tt(:)var(message)tt(:)var(action))
 item(var(n)tt(::)var(message)tt(:)var(action))(
 This describes the var(n)'th normal argument.  The var(message) will be 
-printed above the matches generated and the var(action) says what can
+printed above the matches generated and the var(action) indiciates what can
 be completed in this position (see below).  If there are two colons
-before the var(message), this describes an optional argument.  If the
+before the var(message) the argument is optional.  If the
 var(message) contains only white space, nothing will be printed above
 the matches unless the action adds an explanation string itself.
 )
 xitem(tt(:)var(message)tt(:)var(action))
 item(tt(::)var(message)tt(:)var(action))(
-Like the previous one, but describing the em(next) argument. I.e. if
-you want to describe all arguments a command can get, you can leave
-out the numbers in the description and just use this form to describe
-them one after another in the order they have to appear on the line.
+Similar, but describes the em(next) argument, whatever number that
+happens to be.  If all arguments are specified in this form in the
+correct order the numbers are unnecessary.
 )
 xitem(tt(*:)var(message)tt(:)var(action))
 xitem(tt(*::)var(message)tt(:)var(action))
 item(tt(*:::)var(message)tt(:)var(action))(
 This describes how arguments (usually non-option arguments, those not
-beginning with tt(-) or tt(+)) are to be completed when no description
-with one of the first two forms was given. This also means that any number
-of arguments can be completed.
+beginning with tt(-) or tt(+)) are to be completed when neither
+of the first two forms was provided.  Any number of arguments can
+be completed in this fashion.
 
 With two colons before the var(message), the tt(words) special array and
 the tt(CURRENT) special parameter are modified to refer only to the
@@ -3160,53 +3114,41 @@ normal arguments when the var(action) is executed or evaluated.  With
 three colons before the var(message) they are modified to refer only to
 the normal arguments covered by this description.
 )
-item(var(optspec)[var(description) ...])(
-This describes an option and (if var(description) is given) the arguments
-that have to come after the option.  If no var(description) is given, this
-means to offer only the option name as a possible completion in the right
-places.  (Note that the brackets, above, around var(description), indicate
-that zero or more var(description)s may appear; but the brackets are not
-themselves part of this format.  If brackets are used, they are part of
-the var(optspec); see below.)
-
-In the descriptions below, the option names represented by var(optname)
-are normally taken to be multi-character names, and a word from the line
-is considered to contain only one option (or none).  By giving the tt(-s)
-option to tt(_arguments) before the first var(spec), each var(optname) is
-considered to be a single character and each word from the line may
-contain more than one such option letter.  However, words beginning with
-two hyphens (like `tt(-)tt(-prefix)') are still considered to contain only
-one option name.  This allows the use of the `tt(-s)' option to describe
-single-letter options together with such long option names.
-
-The tt(-s) option may be combined with the option tt(-w) to say that more
-option characters are to be expected even after an option that takes an
-argument.  For example, if a command takes the options `tt(a)' and `tt(b)',
-where `tt(a)' takes an argument in the next word, tt(_arguments) would
-normally not complete the other option directly after `tt(-a)', but it would
-allow that if given the tt(-w) option.
-
-Similarly, the option tt(-W) may be given together with tt(-s) to force
-completion of single-letter options even after options that get an
-argument in the same word.  For example, if a command takes the options
-`tt(a)' and `tt(b)', where `tt(a)' needs an argument in the same word,
-directly after the option character, tt(_arguments) would normally only
-execute the action for that argument and not offer other single-letter
-options as possible completions.  If given the tt(-W) option, it will
-offer other options as possible completions after executing the action
-for the argument.  Note that, depending on the action, this may mean
-that the other options can't really be completed, but at least they will
-be listed.  For more control, use an utility function like tt(_guard) in
-the argument's action.
-
-The forms of var(optspec) are:
+xitem(var(optspec))
+item(var(optspec):var(...))(
+This describes an option.  The colon indicates handling for one or more
+arguments to the option; if it is not present, the option is assumed to
+take no arguments.
+
+By default, options are multi-character name, one `tt(-)var(word)' per
+option.  With tt(-s), options may be single characters, with more than
+one option per word, although words starting with two hyphens, such as
+`tt(-)tt(-prefix)', are still considered complete option names.  This is
+suitable for standard GNU options.
+
+The combination of tt(-s) with tt(-w) allows single-letter options to be
+combined in a single word even if one or more of the options take
+arguments.  For example, if tt(-a) takes an argument, with no
+tt(-s) `tt(-ab)' is considered as a single (unhandled) option; with
+tt(-s) tt(-ab) is an option with the argument `tt(b)'; with both tt(-s)
+and tt(-w), tt(-ab) may be the option tt(-a) and the option(-b) with
+arguments still to come.
+
+The option tt(-W) takes this a stage further:  it is possible to
+complete single-letter options even after an argument that occurs in the
+same word.  However, it depends on the action performed whether options
+will really be completed at this point.  For more control, use a
+utility function like tt(_guard) as part of the action.
+
+If the option takes an argument, the forms given above are to be followed
+by one or more of the following var(optspec)s:
 
 startitem()
 item(tt(*)var(optspec))(
-If the option may be given more than once, a star (`tt(*)') must be
-added in front of one of the following forms of var(optspec).  Otherwise,
-if the option is already on the line and to the left of the cursor, it
-is not offered as a possible completion again.
+Here var(optspec) is one of the remaining forms below.  This indicates
+the following var(optspec) may be repeated.  Otherwise if the
+corresponding option is already present on the command line to the left
+of the cursor it will not be offered again.
 )
 xitem(tt(-)var(optname))
 item(tt(+)var(optname))(
@@ -3215,24 +3157,27 @@ with a minus or a plus sign, such as `tt(-foo)'.  The first argument for
 the option (if any) must follow as a em(separate) word directly after the
 option.
 
-If the command accepts the option with either a leading minus or a leading
-plus sign, use either `tt(-+)var(optname)' or `tt(+-)var(optname)' to
-define both variants at once.
+Either of `tt(-+)var(optname)' and `tt(+-)var(optname)' can be used to
+specify that tt(-)var(optname) and tt(+)var(optname) are both valid.
 
-In all the following forms, the leading `tt(-)' may be replaced or paired
-with `tt(+)' in this way.
+In all the remaining forms, the leading `tt(-)' may be replaced by or
+paired with `tt(+)' in this way.
 )
 item(tt(-)var(optname)tt(-))(
 The first argument of the option must come directly after the option name
-em(in the same word), as in `tt(-foo-:)var(...)'.
+em(in the same word).  For example, `tt(-foo-:)var(...)' specifies that
+the completed option and argument will look like `tt(-foo)var(arg)'.
 )
 item(tt(-)var(optname)tt(+))(
 The first argument may appear immediately after var(optname) in the same
-word, or may instead appear as a separate word after the option.
+word, or may appear as a separate word after the option.  For example,
+`tt(-foo+:)var(...)' specifies that the completed option and argument
+will look like either `tt(-foo)var(arg)' or `tt(-foo) var(arg)'.
 )
 item(tt(-)var(optname)tt(=))(
 The argument may appear as the next word, or in same word as the option
-name provided that it is separated from it by an equals sign.
+name provided that it is separated from it by an equals sign, for
+example `tt(-foo=)var(arg)' or `tt(-foo) var(arg)'.
 )
 item(tt(-)var(optname)tt(=-))(
 The argument to the option must appear after an equals sign in the same
@@ -3242,204 +3187,223 @@ item(var(optspec)tt([)var(explanation)tt(]))(
 An explanation string may be appended to any of the preceding forms of
 var(optspec) by enclosing it in brackets, as in `tt(-q[query operation])'.
 
-The tt(verbose) style is used to decide if these explanation strings
-should be displayed with the option in a completion listing.
+The tt(verbose) style is used to decide whether the explanation strings
+are displayed with the option in a completion listing.
 
 If no bracketed explanation string is given but the tt(auto-description)
 style is set and only one argument is described for this var(optspec), the
 value of the style is displayed, with any appearance of the sequence
-`tt(%d)' in it replaced by the var(message) of the first var(description)
+`tt(%d)' in it replaced by the var(message) of the first var(optarg)
 that follows the var(optspec); see below.
 )
 enditem()
 
-Note that the special meaning of a leading or trailing tt(-) or tt(+) in
-var(optspec) means that when the command to be completed accepts options
-like `tt(-+)' or `tt(-=)', the second character has to be quoted with a
-backslash, as in `tt(-\+)'.
+It is possible for options with a literal `PLUS()' or `tt(=)' to
+appear, but that character must be quoted, for example `tt(-\+)'.
 
-Each var(description) following an var(optspec) must take one of the
+Each var(optarg) following an var(optspec) must take one of the
 following forms:
 
 startitem()
 xitem(tt(:)var(message)tt(:)var(action))
 item(tt(::)var(message)tt(:)var(action))(
-Describes a mandatory argument with one colon, or an optional argument
-with two colons.  As in other forms of var(spec), the var(message) will be
-printed above the matches generated (unless it contains only white
-space, see above) and the var(action) says what can be
-completed in this position.
+An argument to the option; var(message) and var(action) are treated as
+for ordinary arguments.  In the first form, the argument is mandatory,
+and in the second form it is optional.
+
+This group may be repeated for options which take multiple arguments.
+In other words,
+tt(:)var(message1)tt(:)var(action1)tt(:)var(message2)tt(:)var(action2)
+specifies that the option takes two arguments.
 )
 xitem(tt(:*)var(pattern)tt(:)var(message)tt(:)var(action))
 xitem(tt(:*)var(pattern)tt(::)var(message)tt(:)var(action))
 item(tt(:*)var(pattern)tt(:::)var(message)tt(:)var(action))(
-This describes multiple arguments.  Only the em(last) description may be
+This describes multiple arguments.  Only the last var(optarg) for
+an option taking multiple arguments may be
 given in this form.  If the var(pattern) is empty (i.e., tt(:*:)), all
-following words on the line are to be completed as described by the
-var(action); otherwise, all words up to a word matching the var(pattern)
-are to be completed using the var(action).
+the remaining words on the line are to be completed as described by the
+var(action); otherwise, all the words up to a word matching the
+var(pattern) are to be completed using the var(action).
 
-When the var(message) is preceded by two colons, the tt(words) special
-array and the tt(CURRENT) special parameter are modified during the
-execution or evaluation of the var(action) to refer only to the words
-after the option.  When preceded by three colons, they are modified to
-refer only to the words covered by this description.
-
-Note that only one such `tt(:*)'-specification is useful
-and no other argument specification may be given after it.
+Multiple colons are treated as for the `tt(*:)var(...)' forms for
+ordinary arguments:  when the var(message) is preceded by two colons,
+the tt(words) special array and the tt(CURRENT) special parameter are
+modified during the execution or evaluation of the var(action) to refer
+only to the words after the option.  When preceded by three colons, they
+are modified to refer only to the words covered by this description.
 )
 enditem()
 )
 enditem()
 
-To include a colon in any var(optname), var(message), or var(action)
-anywhere above, it has to be preceded by a backslash, as `tt(\:)'.
-
-Each of the six forms of var(spec) (yes, there are six, keep track of
-the nestings) may be preceded by a list
-of option names and argument numbers with which the option or argument
-described is mutually exclusive.  This list is given in parentheses, as
-in `tt((-two -three 1)-one:...)' or `tt((-foo):...)'.  In the first
-example, the options `tt(-two)' and `tt(-three)' and the first
-argument will not be offered as possible completions if the option
-`tt(-one)' is on the line before the cursor, and in the second example
-the option `tt(-foo)' will not be offered if the argument described by
-the specification is on the line.
-
-The list may also contain a single star (tt(*)) as one of its elements to
-specify that the description for the rest arguments (i.e. a specification
-of the form `tt(*:...)') should not be used, a colon (tt(:)) to specify
-that the descriptions for all normal (non-option-) arguments should not be
-used and a hyphen (tt(-)) to specify that the descriptions for all options
-should not be used.  This paragraph desperately needs rewriting.
-
-To simplify writing writing functions that call tt(_arguments) more
-than once, the var(specs) may also start with the character `tt(!)'
-(exclamation mark) to make the spec em(not) be completed.  However, if
-this is used with one of the forms describing options, the option (and 
-its arguments, if it takes any) will be understood and skipped if they 
-appear on the command line.  It's just that the option itself will not
-be completed. This is intended to be used with an array containing the 
-options used in the first call to tt(arguments).  The second call can
-then use `tt(\!${^global_options})' to ignore those options and
-complete only the ones understood in the current context.
-
-In every case above, the var(action) determines how the possible
-completions should be generated.  In places where no sensible matches can
-be generated, the action should consist of only a space. This will make
-the var(message) be displayed but no possible completions listed. Note
-that even in this case the colon at the end of the var(message) is
-needed. The only case where it can be left is when neither a var(message),
-nor an var(action) is given.
+Any literal colon in an var(optname), var(message), or var(action)
+must be preceded by a backslash, `tt(\:)'.
+
+Each of the forms above may be preceded by a list in parentheses
+of option names and argument numbers.  If the given option is completed,
+the options and arguments indicated will not be offered.  For example, 
+`tt((-two -three 1)-one:...)' completes the option `tt(-one)'; if this
+appears on the command line, the options tt(-two) and tt(-three) and the
+first ordinary argument will not be completed after it.
+`tt((-foo):)var(...)' specifies an ordinary argument completion;
+tt(-foo) will not be completed if that argument is already present.
+
+Other items may appear in the list of excluded options to indicate
+various other items that should not be applied when the current
+specification is matched: a single star (tt(*)) for the rest arguments
+(i.e. a specification of the form `tt(*:...)'); a colon (tt(:))
+for all normal (non-option-) arguments; and a hyphen (tt(-)) for all
+options.  For example, if `tt((*))' appears before an option and the
+option appears on the command line, the list of remaining arguments
+(those shown in the above table beginning with `tt(*:)') will not be
+completed.
 
-Except for the `tt(->)var(string)' form below, the var(action) will be
-executed by calling the tt(_all_labels) function to process all tag labels,
-so one doesn't need to call that explicitly unless another tag is to
-be used, for example in a function called in the var(action).
+To aid in reuse of specifications, it is possible to precede any of the
+forms above with `tt(!)'; then the form will no longer be completed,
+although if the option or argument appears on the command line they will
+be skipped as normal.  The main use for this is when the arguments are
+given by an array, and tt(_arguments) is called repeatedly for more
+specific contexts: on the first call `tt(_arguments $global_options)' is
+used, and on subsequent calls `tt(_arguments !$^global_options)'.
 
-When only one of a fixed set of strings can be completed, the var(action)
-can consist of these strings as a list in parentheses, as in:
+In each of the forms above the var(action) determines how
+completions should be generated.  Except for the `tt(->)var(string)'
+form below, the var(action) will be executed by calling the
+tt(_all_labels) function to process all tag labels.  No special handling
+of tags is needed unless a function call introduces a new one.
 
-example(tt(:foo:LPAR()foo bar baz)tt(RPAR()))
+The forms for var(action) are as follows.
+
+startitem()
+item(tt( ) (single unquoted space))(
+This is useful where an argument is required but it is not possible or
+desirable to generate matches for it.  The
+var(message) will be displayed but no completions listed.  Note
+that even in this case the colon at the end of the var(message) is
+needed; it may only be omitted when neither a var(message)
+nor an var(action) is given.
+)
+item(tt(LPAR())var(item1) var(item2) var(...)tt(RPAR()))(
+One of a list of possible matches, for example:
 
-Such a list in doubled parentheses should contain strings consisting of
-the string to complete followed by `tt(\:)' and a description, as in:
+example(tt(:foo:LPAR()foo bar baz)tt(RPAR()))
+)
+item(tt(((var(item1)\:var(desc1) var(...)))))(
+Similar to the above, but with descriptions for each possible match.
+Note the backslash before the colon.  For example,
 
 example(tt(:foo:LPAR()LPAR()a\:bar b\:baz)tt(RPAR()RPAR()))
 
 The matches will be listed together with their descriptions if the
-tt(description) style for the tt(values) tag is set.
-
+tt(description) style is set in the context with the tt(values) tag.
+)
+item(tt(->)var(string))(
 vindex(context, use of)
 vindex(line, use of)
 vindex(opt_args, use of)
-An var(action) of the form `tt(->)var(string)' is used by functions
-that implement a state machine. In this case, the `var(string)'s (with
-all leading and trailing spaces and tabs removed) of all actions that
-have to be used will be stored in the global array tt(state).  The
-function returns with a non-zero return value if the cursor is not in
-a position where options can be completed or if the current word could 
-not be completed to an option.  But if the tt(-R) option is given to
-tt(_arguments), the function will instead return with a return
-value of 300 (to make it distinguishable from other return values)
-after setting the global `tt(context)', `tt(line)' and `tt(opt_args)'
-parameters as described below, and without resetting any changes made
-to the special parameters such as tt(PREFIX) and tt(words).  This
-enables wrapper functions around tt(_arguments) to be able to find out
-if they have to make sure that the special completion parameters are
-not reset when they return.
-
-Note that this means that a function calling tt(_arguments) with at least
-one action containing such a `tt(->)var(string)' has to declare
-appropriate local parameters as in:
+In this form, tt(_arguments) processes the arguments and options and then
+returns control to the calling function with parameters set to indicate the
+state of processing; the calling function then makes its own arrangements
+for generating completions.  For example, functions that implement a state
+machine can use this type of action.
+
+If tt(_arguments) handles the completion by itself, it returns status
+zero.  Otherwise, it returns a non-zero status; if this was because it
+encountered a `tt(->)var(string)' action, it will strip all leading and
+trailing whitespace from var(string) and set the array tt(state) to the set
+of all var(strings)s for which the action is to be performed.  Hence
+tt($state) must be tested to determine whether actions need to be handled.
+
+If the tt(-R) option is given to tt(_arguments), the function will instead
+return a status of 300 to indicate that tt($state) is valid.  In this case
+it also sets the global parameters `tt(context)', `tt(line)' and
+`tt(opt_args)' as described below, and does not reset any changes made to
+the special parameters such as tt(PREFIX) and tt(words).  This gives the
+calling function the choice of resetting these parameters or propagating
+changes in them.
+
+A function calling tt(_arguments) with at least
+one action containing a `tt(->)var(string)' therefore must declare
+appropriate local parameters:
 
 example(local context state line
 typeset -A opt_args)
 
-This will ensure that tt(_arguments) does not create unused global
-parameters.
-
+to avoid tt(_arguments) from altering the global environment.
+)
+item(tt({)var(eval-string)tt(}))(
 vindex(expl, use of)
-A string in braces is evaluated to generate the matches and if the
-var(action) does not begin with an opening parentheses or brace, it
-is also split into separate words and executed. If the var(action)
-starts with a space, this list of words will be invoked unchanged,
-otherwise it will be invoked with some extra strings placed after the
-first word which can be given as arguments to the tt(compadd) builtin
-command and which make sure that the var(message) given
-in the description will be shown above the matches. These arguments
-are taken from the array parameter `tt(expl)' which will be set up
-before executing the var(action) and hence may be used in it (normally 
-in an expansion like `tt($expl[@])').
-
+A string in braces is evaluated as shell code to generate matches.  If the
+var(eval-string) itself does not begin with an opening parenthesis or
+brace it is split into separate words before execution.
+)
+item(tt(= )var(action))(
 If the var(action) starts with `tt(= )' (an equals sign followed by a
 space), tt(_arguments) will insert the contents of the var(argument)
 field of the current context as the new first element in the tt(words) 
-special array and increments the value of the tt(CURRENT) special
-parameter. In other words, it inserts a dummy element in the tt(words) 
-array and makes tt(CURRENT) still point to the word in that array
-where the cursor is. This is only really useful when used with one of
-the forms that make tt(_arguments) modify the tt(words) array to
-contain only some of the words from the line, i.e. one of the argument 
-description forms where the var(message) is preceded by two or three
-colons. For example, when the function called in the action for such
-an argument itself uses tt(_arguments), the dummy element is needed to 
-make that second call to tt(_arguments) use all words from the
-restricted range for argument parsing. Without the inserted dummy
-element, the first word in the range would be taken (by the second
-tt(_arguments)) to be the command name and hence ignored.
-
-During the evaluation or execution of the action the array `tt(line)'
+special array and increment the value of the tt(CURRENT) special
+parameter.  This has the effect of inserting a dummy word onto the
+completion command line while not changing the point at which completion is
+taking place.
+
+This is most useful with one of the specifiers that restrict the words on
+the command line on which the var(action) is to operate (the two- and
+three-colon forms above).  One particular use is when an var(action) itself
+causes tt(_arguments) on a restricted range; it is necessary to use this
+trick to insert an appropriate command name into the range for the second
+call to tt(_arguments) to be able to parse the line.
+)
+xitem( var(word...))
+item(var(word...))(
+This covers all forms other than those above.  If the var(action)
+starts with a space, the remaining list of words will be invoked unchanged.
+
+Otherwise it will be invoked with some extra strings placed after the
+first word; these are to be passed down as options to the tt(compadd)
+builtin.  They ensure that the state specified by tt(_arguments), in
+particular the descriptions of options and arguments, is correctly passed
+to the completion command.  These additional arguments
+are taken from the array parameter `tt(expl)'; this will be set up
+before executing the var(action) and hence may be referred to inside it,
+typically in an expansion of the form `tt($expl[@])' which preserves empty
+elements of the array.
+)
+enditem()
+
+During the performance of the action the array `tt(line)'
 will be set to the command name and normal arguments from the command
-line, i.e. to the words from the command line excluding all options
-and their arguments. These are stored in the associative array
-`tt(opt_args)', using the option names as keys and their arguments as
-the values. For options that have more than one argument these are
-given as one string, separated by colons. All colons in the original
+line, i.e. the words from the command line excluding all options
+and their arguments.  Options are stored in the associative array
+`tt(opt_args)' with option names as keys and their arguments as
+the values.  For options that have more than one argument these are
+given as one string, separated by colons.  All colons in the original
 arguments are preceded with backslashes.
 
-The parameter `tt(context)' (set only in the calling function when
-using an action of the form `tt(->)var(string)', not during the
-evaluation of other var(action)s) is set to the automatically
-created context names. These are either strings of the form
-`tt(option)var(-opt)tt(-)var(n)' for the var(n)'th argument of the
-option var(-opt), or strings of the form `tt(argument-)var(n)' for
-the var(n)'th argument (for rest arguments the var(n) is the string
-`tt(rest)'). For example, when completing the argument of the tt(-o)
-option, the name is `tt(option-o-1)' and for the second normal
+The parameter `tt(context)' is set when returning to the calling function
+to perform an action of the form `tt(->)var(string)'.  It is set to an
+array of elements corresponding to the elements of tt($state).  Each
+element is a suitable name for the argument field of the context: either a
+string of the form `tt(option)var(-opt)tt(-)var(n)' for the var(n)'th
+argument of the option var(-opt), or a string of the form
+`tt(argument-)var(n)' for the var(n)'th argument.  For `rest' arguments,
+that is those in the list at the end not handled by position, var(n) is the
+string `tt(rest)'.  For example, when completing the argument of the tt(-o)
+option, the name is `tt(option-o-1)', while for the second normal
 (non-option-) argument it is `tt(argument-2)'.
 
-Also, during the evaluation of the var(action), the context name in
-the tt(curcontext) parameter is changed by appending the same
-string that is stored in the tt(context) parameter.
+Furthermore, during the evaluation of the var(action) the context name in
+the tt(curcontext) parameter is altered to append the same string that is
+stored in the tt(context) parameter.
 
-It is also possible to specify multiple sets of options and
+It is possible to specify multiple sets of options and
 arguments with the sets separated by single hyphens.  The specifications
-before the first hyphen are shared by all sets given after the first
-hyphen.  The first word in every other set gives the name of the
-set. This name may appear in exclusion lists in the specifications,
-either alone or before one of the possible values described above
-(with a `tt(-)' between the name and the rest).
+before the first hyphen (if any) are shared by all the remaining sets.
+The first word in every other set provides a name for the
+set which may appear in exclusion lists in specifications,
+either alone or before one of the possible values described above.
+In the second case a `tt(-)' should appear between this name and the
+remainder.
 
 For example:
 
@@ -3451,19 +3415,19 @@ example(_arguments \
     -d \ 
     ':arg:(x2 y2)')
 
-This defines two sets. When the command line contains the option
+This defines two sets.  When the command line contains the option
 `tt(-c)', the `tt(-d)' option and the argument will not be considered
-possible completions. When it contains `tt(-d)' or an argument, the
-option `tt(-c)' will not be completed any more, but if `tt(-a)' is
-given, both sets will still be considered valid, because it appears
-before the first hyphen, so both sets contain this option.
-
-If the name-string is of the form `tt(LPAR())var(name)tt(RPAR())' then 
-all specifications in the set have an implicit exclusion list
-containing the name of the set, i.e. all specifications are mutual
-exclusive with all other specifications in the same set. This is
+possible completions.  When it contains `tt(-d)' or an argument, the
+option `tt(-c)' will not be considered.  However, after `tt(-a)'
+both sets will still be considered valid.
+
+If the name given for one of the mutually exclusive sets is of the form
+`tt(LPAR())var(name)tt(RPAR())' then only one value from each set will ever
+be completed; more formally, all specifications are mutually
+exclusive to all other specifications in the same set.  This is
 useful for defining multiple sets of options which are mutually
-exclusive and in which the options are aliases for each other. E.g.:
+exclusive and in which the options are aliases for each other.  For
+example:
 
 example(_arguments \ 
     -a -b \ 
@@ -3472,105 +3436,113 @@ example(_arguments \
   - '(uncompress)' \ 
     {-d,--decompress}'[decompress]')
 
-Note that using multiple sets will be slower than using only one set
-because the completion code has to parse the command line once for
-every set. So more than one set should only be used if the command
-syntax is too complicated. Note also that an option specification with
-rest-arguments (as in `tt(-foo:*:...)') often allows the use of
-multiple sets to be avoided.
-
-To simplify the specifications for commands with standard option
-parsing, the options tt(-S) and tt(-A) may be given.  With tt(-S), no
-option will be completed after a `tt(-)tt(-)' on the line and this
-argument will otherwise be ignored. With tt(-A), no options will be
-completed after the first non-option argument on the line.  The tt(-A) 
-has to be followed by a pattern matching all strings which are not to
-be taken as arguments. For example, to make tt(_arguments) stop
-completing options after the first normal argument, but ignoring all
-strings starting with a hyphen even if they are not described by one
-of the var(optspec)s, one would use: `tt(-A "-*")'.
-
-Another option supported is `tt(-O) var(name)'. The var(name) will be
-taken as the name of an array and its elements will be given to
-functions called to generate matches when executing the
-var(actions). For example, this allows one to give options for the
-tt(compadd) builtin that should be used for all var(action)s.
-
-Also, the tt(-M) option followed by a string may be given before the
-first description. The string will be used as the match specification
-when completing option names and values instead of the default
-`tt(r:|[_-]=* r:|=*)'. 
-
-Finally, the option tt(-C) can be given to make tt(_arguments) modify
-the tt(curcontext) parameter when an action of the form
-`tt(->)var(state)' is used. This parameter is used to keep track of
-the current context and in this case it (and not the parameter
-tt(context) as explained above) has to be made local to make sure that 
-calling functions don't use the modified value. Also, the local
-version of tt(curcontext) has to be initialised with the old value as
-in:
+As the completion code has to parse the command line separately for each
+set this form of argument is slow and should only be used when necessary.
+A useful alternative is often an option specification with rest-arguments
+(as in `tt(-foo:*:...)'); here the option tt(-foo) swallows up all
+remaining arguments as described by the var(optarg) definitions.
+
+The options tt(-S) and tt(-A) are available to simplify the specifications
+for commands with standard option parsing.  With tt(-S), no option will be
+completed after a `tt(-)tt(-)' appearing on its own on the line; this
+argument will otherwise be ignored; hence in the line
+
+example(foobar -a -- -b)
+
+the `tt(-a)' is considered an option but the `tt(-b)' is considered an
+argument, while the `tt(-)tt(-)' is considered to be neither.
+
+With tt(-A), no options will be completed after the first non-option
+argument on the line.  The tt(-A) must be followed by a pattern matching
+all strings which are not to be taken as arguments.  For example, to make
+tt(_arguments) stop completing options after the first normal argument, but
+ignoring all strings starting with a hyphen even if they are not described
+by one of the var(optspec)s, the form is `tt(-A "-*")'.
+
+The option `tt(-O) var(name)' specifies the name of an array whose elements
+will be passed as arguments to functions called to execute var(actions).
+For example, this can be used to pass the same set of options for the
+tt(compadd) builtin to all var(action)s.
+
+The option `tt(-M) var(spec)' sets a match specification to use to
+completion option names and values.  It must appear before the first
+argument specification.  The default is `tt(r:|[_-]=* r:|=*)': this allows
+partial word completion after `tt(_)' and `tt(-)', for example `-f-b'
+can be completed to `tt(-foo-bar)'.
+
+The option tt(-C) tells tt(_arguments) to modify
+the tt(curcontext) parameter for an action of the form
+`tt(->)var(state)'.  This is the standard parameter used to keep track of
+the current context.  Here it should be made local to the calling function
+to avoid passing back the modified value and should be initialised to the
+current value at the start of the function:
 
 example(local curcontext="$curcontext")
 
-The function can also be made to automatically complete long options
-for commands that support the `tt(-)tt(-help)' option as, for example,
-most of the GNU commands do. For this, the string `tt(-)tt(-)' must be
-given as one argument and if it is, the command from the line is
-invoked with the `tt(-)tt(-help)' option and its output is parsed to find
-possible option names. Note that this means that you should be careful
-to make sure that this feature is not used for a command that does not
-support this option.
-
-For such automatically found options that get an argument after an
-`tt(=)', the function also tries
-to automatically find out what should be completed as the argument.
-The possible completions for option-arguments can be described with
-the arguments after the `tt(-)tt(-)' (which are not used as described
-above). Each argument contains one description of the form
-`var(pattern)tt(:)var(message)tt(:)var(action)'. The var(message) and
-the var(action) have the same format as for the normal option
-descriptions described above. The var(action) will be executed to
-complete arguments of options whose description in the output of the
-command from the line with the `tt(-)tt(-help)' option matches the
-var(pattern). For example:
+The option `tt(--)' allows tt(_arguments) to work out the names of long
+options that support the `tt(-)tt(-help)' option which is standard in many
+GNU commands.  The command word is called with the argument
+`tt(-)tt(-help)' and the output examined for option names.  Clearly, it can
+be dangerous to pass this to commands which may not support this option as
+the behaviour of the command is unspecified.
+
+In addition to options, `tt(_arguments -)tt(-)' will try to deduce the
+types of arguments available for options when the form
+`tt(-)tt(-)var(opt)=var(val)' is valid.  It is also possible to provide
+hints by examining the help text of the command and adding specifiers of
+the form `var(pattern)tt(:)var(message)tt(:)var(action)'; note that normal
+tt(_arguments) specifiers are not used.  The var(pattern) is matched
+against the help text for an option, and if it matches the var(message) and
+var(action) are used as for other argument specifiers.  For example:
 
 example(_arguments -- '*\*:toggle:(yes no)' \ 
               '*=FILE*:file:_files' \ 
-              '*=DIR*:directory:_files -/')
+              '*=DIR*:directory:_files -/' \ 
+              '*=PATH*:directory:_files -/')
 
 Here, `tt(yes)' and `tt(no)' will be completed as the argument of
-options whose description ends in a star, file names for options that
-contain the substring `tt(=FILE)' in the description, and paths for
-options whose description contains `tt(=DIR)'. In fact, the last two
-patterns are not needed since this function always completes files
-for option descriptions containing `tt(=FILE)' and paths for option
-descriptions that contain `tt(=DIR)' or `tt(=PATH)'. These builtin
-patterns can be overridden by patterns given as arguments, however.
+options whose description ends in a star; file names will be completed for
+options that contain the substring `tt(=FILE)' in the description; and
+directories will be completed for options whose description contains
+`tt(=DIR)' or `tt(=PATH)'.  The last three are in fact the default and so
+need not be given explicitly, although it is possible to override the use
+of these patterns.  A typical help text which uses this feature is:
+
+example(  -C, --directory=DIR          change to directory DIR)
+
+so that the above specifications will cause directories to be completed
+after `tt(--directory)', though not after `tt(-C)'.
 
 Note also that tt(_arguments) tries to find out automatically if the
-argument for an option is optional. If it fails to automatically
-detect this, the colon before the var(message) can be doubled to tell
-it about this as described for the normal option descriptions above.
+argument for an option is optional.  This can be specified explicitly by
+doubling the colon before the var(message).
 
 If the var(pattern) ends in `tt((-))', this will removed from the
 pattern and the var(action) will be used only directly after the
-`tt(=)', not in the next word. I.e., this is like a normal
-specification as described above using `tt(=-)'.
-
-The option `tt(-i) var(patterns)' (which must be given after the
-`tt(-)tt(-)') can be used to give patterns for options which should not be
-completed. The patterns can be given as the name of an array parameter
-or as a literal list in parentheses. E.g. `tt(-i
-"LPAR()-)tt(-(en|dis)able-FEATURE*RPAR()")' will make the options
-`tt(-)tt(-enable-FEATURE)' and `tt(-)tt(-disable-FEATURE)' be ignored. The
-option `tt(-s) var(pairs)' (again, after the `tt(-)tt(-)') can be used to
-describe option aliases. Each var(pair) consists of a pattern and a
-replacement. E.g. some tt(configure)-scripts describe options only as
-`tt(-)tt(-enable-foo)', but also accept `tt(-)tt(-disable-foo)'. To allow
-completion of the second form, one would use `tt(-s "LPAR()#-)tt(-enable-
--)tt(-disable-RPAR()")'.
+`tt(=)', not in the next word.  This is the behaviour of a normal
+specification defined with the form `tt(=-)'.
 
-Example:
+The `tt(_arguments -)tt(-)' can be followed by the option `tt(-i)
+var(patterns)' to give patterns for options which are not to be
+completed.  The patterns can be given as the name of an array parameter
+or as a literal list in parentheses.  For example,
+
+example(_arguments -- -i \ 
+    "LPAR()-tt(-(en|dis)able-FEATURE*RPAR()"))
+
+will cause completion to ignore the options
+`tt(-)tt(-enable-FEATURE)' and `tt(-)tt(-disable-FEATURE)' (this example is
+useful with GNU tt(configure)).
+
+The `tt(_arguments -)tt(-)' form can also be followed by the option `tt(-s)
+var(pair)' to describe option aliases.  Each var(pair) consists of a
+pattern and a replacement.  For example, some tt(configure)-scripts
+describe options only as `tt(-)tt(-enable-foo)', but also accept
+`tt(-)tt(-disable-foo)'.  To allow completion of the second form:
+
+example(_arguments -- -s "LPAR()#-tt(-enable- -)tt(-disable-RPAR()"))
+
+Here is a more general example of the use of tt(_arguments):
 
 example(_arguments '-l+:left border:' \ 
            '-format:paper size:(letter A4)' \ 
@@ -3579,32 +3551,34 @@ example(_arguments '-l+:left border:' \
            '*:page number:')
 
 This describes three options: `tt(-l)', `tt(-format)', and
-`tt(-copy)'. The first one gets one argument described as `var(left
+`tt(-copy)'.  The first takes one argument described as `var(left
 border)' for which no completion will be offered because of the empty
-action. The argument may come directly after the `tt(-l)' or it may be 
-given as the next word on the line. The `tt(-format)' option gets one
-argument (in the next word) described as `var(paper size)' for which
-only the strings `tt(letter)' and `tt(A4)' will be completed. The
-`tt(-copy)' option differs from the first two in that it may appear
-more than once on the command line and in that it accepts two
-arguments. The first one is mandatory and will be completed as a
-filename. The second one is optional (because of the second colon
-before the description `var(resolution)') and will be completed from
-the strings `tt(300)' and `tt(600)'.
+action.  Its argument may come directly after the `tt(-l)' or it may be 
+given as the next word on the line.
+
+The `tt(-format)' option takes one
+argument in the next word, described as `var(paper size)' for which
+only the strings `tt(letter)' and `tt(A4)' will be completed.
+
+The `tt(-copy)' option may appear more than once on the command line and
+takes two arguments.  The first is mandatory and will be completed as a
+filename.  The second is optional (because of the second colon before
+the description `var(resolution)') and will be completed from the strings
+`tt(300)' and `tt(600)'.
 
 The last two descriptions say what should be completed as
-arguments. The first one describes the first argument as a
+arguments.  The first describes the first argument as a
 `var(postscript file)' and makes files ending in `tt(ps)' or `tt(eps)' 
-be completed. The last description says that all other arguments are
-`var(page numbers)' but does not give possible completions.
+be completed.  The last description gives all other arguments the
+description `var(page numbers)' but does not offer completions.
 )
 findex(_cache_invalid)
 item(tt(_cache_invalid) var(cache_identifier))(
-This function returns 0 if the completions cache corresponding to the
-given cache identifier needs rebuilding.  It determines this by
-looking up the tt(cache-policy) style for the current context, and
-if it exists, runs the function of the same name, supplying the full
-path to the relevant cache file as the only argument.
+This function returns status zero if the completions cache corresponding to
+the given cache identifier needs rebuilding.  It determines this by
+looking up the tt(cache-policy) style for the current context.
+This should provide a function name which is run with the full path to the
+relevant cache file as the only argument.
 
 Example:
 
@@ -3617,94 +3591,99 @@ example(_example_caching_policy () {
 findex(_call_function)
 item(tt(_call_function) var(return) var(name) [ var(args) ... ])(
 If a function var(name) exists, it is called with the arguments
-var(args). Unless it is the empty string or a single hyphen,
-var(return) is taken as the name of a parameter and the return status
-from the called function is stored in it.
+var(args).  The var(return) argument gives the name of a parameter in which
+the return status from the function var(name); if var(return) is empty or a
+single hyphen it is ignored.
+
 The return value of tt(_call_function) itself is zero if the function
 var(name) exists and was called and non-zero otherwise.
 )
 findex(_call_program)
 item(tt(_call_program) var(tag) var(string) ...)(
-This function is used in places where a command is called, making it
-possible for the user to override the default command call.  It looks up
-the tt(command) style with the supplied var(tag).  If the style is set, its
-value is used as the command to execute.
-
-In any case, the var(string)s from the call to tt(_call_program) or from the
-style are concatenated with spaces between them and the resulting
-string is evaluated.  The return value is the return value of the
-command called.
+This function provides a mechanism for the user to override the use of an
+external command.  It looks up the tt(command) style with the supplied
+var(tag).  If the style is set, its value is used as the command to
+execute.  The var(string)s from the call to tt(_call_program), or from the
+style if set, are concatenated with spaces between them and the resulting
+string is evaluated.  The return value is the return value of the command
+called.
 )
 findex(_combination)
-item(tt(_combination) [ tt(-s) var(pattern) ] var(tag) var(style) var(specs) ... var(field) var(opts) ...)(
-This function is used to complete combinations of values such as pairs 
-of hostnames and usernames.  The possible values will be taken from the 
-var(style) whose name is given as the second argument.  The first argument
-is the var(tag) to use to do the lookup.
-
-The style name should consist of multiple parts separated by
-hyphens which are then used as field names.  Known values for such
-fields can be given after the second argument in arguments of the form 
-`var(field)tt(=)var(pattern)'.  The first argument without an equals sign 
-is taken as the name of the field for which completions should be
-generated.
-
-The matches generated will be taken from the value of the style.  These 
-values should contain the possible values for the combinations where
-the values for the different fields are separated by colons or
-characters matching the pattern given after the tt(-s) option to
-tt(_combination); normally this is used to define character classes
-like the `tt(-s "[:@]")' used for the tt(users-hosts) style.
-
-Only the values for the requested fields for which the patterns given
-in the `var(field)tt(=)var(pattern)' match the respective fields in
-the strings from the style value are generated as possible matches.
-
-If no style with the given name is defined for the given tag but a
-function named with the name of the requested field preceded by an
+item(tt(_combination) [ tt(-s) var(pattern) ] var(tag) var(style) var(spec) ... var(field) var(opts) ...)(
+This function is used to complete combinations of values,  for example
+pairs of hostnames and usernames.  The var(style) argument gives the style
+which defines the pairs; it is looked up in a context with the var(tag)
+specified.
+
+The style name consists of field names separated by hyphens, for example
+`tt(users-hosts-ports)'.  For each field for a value is already known, a
+var(spec) of the form `var(field)tt(=)var(pattern)' is given.  For example,
+if the command line so far specifies a user `tt(pws)', the argument
+`tt(users=pws)' should appear.
+
+The next argument with no equals sign is taken as the name of the field
+for which completions should be generated (presumably not one of the
+var(field)s for which the value is known).
+
+The matches generated will be taken from the value of the style.  These
+should contain the possible values for the combinations in the appropriate
+order (users, hosts, ports in the example above).  The different fields
+the values for the different fields are separated by colons.  This
+can be altered with the option tt(-s) to tt(_combination) which specifies a
+pattern.  Typically this is a character class, as for example
+`tt(-s "[:@]")' in the case of the tt(users-hosts) style.    Each
+`var(field)tt(=)var(pattern)' specification restricts the
+completions which apply to elements of the style with appropriately
+matching fields.
+
+If no style with the given name is defined for the given tag,
+or if none of the strings in style's value match, but a
+function name of the required field preceded by an
 underscore is defined, that function will be called to generate the
-matches.  This is also done if none of the strings in the value of the
-style match all the patterns given as arguments.
+matches.  For example, if there is no `tt(users-hosts-ports)' or no
+matching hostname when a host is required, the function `tt(_hosts)' will
+automatically be called.
 
 If the same name is used for more than one field, in both the
-`var(field)tt(=)var(pattern)' and the argument that gives the field
-name to complete for, the number of the field (starting with one) may
+`var(field)tt(=)var(pattern)' and the argument that gives the name of the
+field to be completed, the number of the field (starting with one) may
 be given after the fieldname, separated from it by a colon.
 
-All arguments after the requested field name are passed to
+All arguments after the required field name are passed to
 tt(compadd) when generating matches from the style value, or to 
 the functions for the fields if they are called.
 )
 findex(_describe)
 item(tt(_describe) [ tt(-o) | tt(-t) var(tag) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)(
-This function is useful for preparing a list of command options or
-arguments, together with their descriptions var(descr), as matches.
+This option associates completions with descriptions.
 Multiple groups separated by tt(-)tt(-) can be supplied, potentially with
 different completion options var(opts).
 
 The var(descr) is taken as a string to display above the matches if the
-tt(format) style for the tt(descriptions) tag is set.  After this come one
-or two names of arrays followed by options to pass to tt(compadd).  The
+tt(format) style for the tt(descriptions) tag is set.  This is followed by
+one or two names of arrays followed by options to pass to tt(compadd).  The
 first array contains the possible completions with their descriptions in
 the form `var(completion)tt(:)var(description)'.  If a second array is
-given, it should have the same number of elements as the first one and the
-corresponding elements are added as possible completions instead of the
-var(completion) strings from the first array.  The completion list will
-retain the descriptions from the first array.  Finally, a set of completion
-options can appear.
+given, it should have the same number of elements as the first; in this
+case the corresponding elements are added as possible completions instead
+of the var(completion) strings from the first array.  The completion list
+will retain the descriptions from the first array.  Finally, a set of
+completion options can appear.
 
 If the option `tt(-o)' appears before the first argument, the matches added
-will be treated as option names (typically following a `tt(-)',
-`tt(-)tt(-)' or `tt(+)' on the command line).  This makes tt(_describe) use
-the tt(prefix-hidden), tt(prefix-needed) and tt(verbose) styles to find out
-if the strings should be added at all and if the descriptions should be
-shown.  Without the `tt(-o)' option, only the tt(verbose) style is used.
-With the tt(-t) option a var(tag) can be specified that should be used
-instead of the default `tt(values)' or, if the tt(-o) option is given,
-`tt(options)'.
+will be treated as names of command options (N.B. not shell options),
+typically following a `tt(-)', `tt(-)tt(-)' or `tt(+)' on the command
+line.  In this case tt(_describe) uses the tt(prefix-hidden),
+tt(prefix-needed) and tt(verbose) styles to find out if the strings should
+be added as completions and if the descriptions should be shown.  Without
+the `tt(-o)' option, only the tt(verbose) style is used to decide how
+descriptions are shown.
+
+With the tt(-t) option a var(tag) can be specified.  The default is
+`tt(values)' or, if the tt(-o) option is given, `tt(options)'.
 
 If selected by the tt(list-grouped) style, strings with the same
-description will be added in a way that they appear together in the list.
+description will appear together in the list.
 
 tt(_describe) uses the tt(_all_labels) function to generate the matches, so
 it does not need to appear inside a loop over tag labels.