New upstream version 5.8

1 files changed, 5602 insertions, 0 deletions

diff --git a/Doc/zshcompsys.1 b/Doc/zshcompsys.1
new file mode 100644
index 000000000..9532b8624
--- /dev/null
+++ b/Doc/zshcompsys.1
@@ -0,0 +1,5602 @@
+.TH "ZSHCOMPSYS" "1" "February 14, 2020" "zsh 5\&.8"
+.SH "NAME"
+zshcompsys \- zsh completion system
+.\" Yodl file: Zsh/compsys.yo
+.SH "DESCRIPTION"
+.PP
+This describes the shell code for the `new\&' completion system, referred
+to as \fBcompsys\fP\&.  It is written in shell functions based on the
+features described in
+\fIzshcompwid\fP(1)\&.
+.PP
+The features are contextual, sensitive to the point at which completion is
+started\&.  Many completions are already provided\&.
+For this reason, a user can perform a great many tasks without
+knowing any details beyond how to initialize the system, which is
+described
+below in INITIALIZATION\&.
+.PP
+The context that decides what completion is to be performed may be
+.PD 0
+.TP
+.PD
+\(bu
+an argument or option position: these describe the position on the
+command line at which completion is requested\&.  For example `first argument
+to rmdir, the word being completed names a directory\&';
+
+.TP
+\(bu
+a special context, denoting an element in the shell\&'s syntax\&.  For example
+`a word in command position\&' or `an array subscript'\&.
+
+.PP
+A full context specification contains other elements, as we shall describe\&.
+.PP
+Besides commands names and contexts, the system employs two more
+concepts, \fIstyles\fP and \fItags\fP\&.  These provide ways for the user
+to configure the system\&'s behaviour\&.
+.PP
+Tags play a dual role\&.  They serve as a classification system for
+the matches, typically indicating a class of object that the user
+may need to distinguish\&.  For example, when completing arguments of the
+\fBls\fP command the user may prefer to try \fBfiles\fP before \fBdirectories\fP,
+so both of these are tags\&.  They also appear as the rightmost
+element in a context specification\&.
+.PP
+Styles modify various operations of the completion system, such as
+output formatting, but also what kinds of completers are used (and in
+what order), or which tags are examined\&.  Styles may accept arguments
+and are manipulated using the \fBzstyle\fP command described in
+see \fIzshmodules\fP(1)\&.
+.PP
+In summary, tags describe \fIwhat\fP the completion objects are, and style
+\fBhow\fP they are to be completed\&.  At various points of execution, the
+completion system checks what styles and/or tags are defined for the
+current context, and uses that to modify its behavior\&.  The full
+description of context handling, which determines how tags and other
+elements of the context influence the behaviour of styles, is described
+below in COMPLETION SYSTEM CONFIGURATION\&.
+.PP
+When a completion is requested, a dispatcher function is called;
+see the description of \fB_main_complete\fP in the list of control functions
+below\&. This dispatcher decides which function should
+be called to produce the completions, and calls it\&. The result is
+passed to one or more \fIcompleters\fP, functions that implement
+individual completion strategies: simple completion, error correction,
+completion with error correction, menu selection, etc\&.
+.PP
+More generally, the shell functions contained in the completion system are
+of two types:
+.PD 0
+.TP
+.PD
+\(bu
+those beginning `\fBcomp\fP\&' are to be called directly; there are only
+a few of these;
+
+.TP
+\(bu
+those beginning `\fB_\fP\&' are called by the
+completion code\&.  The shell functions of this set, which implement
+completion behaviour and may be bound to keystrokes, are referred to
+as `widgets\&'\&.  These proliferate as new completions are required\&.
+
+.PP
+.PP
+.SH "INITIALIZATION"
+.PP
+If the system was installed completely, it should be enough to
+call the shell function \fBcompinit\fP from your initialization file; see the
+next section\&.  However, the function \fBcompinstall\fP can be run by a user
+to configure various aspects of the completion system\&.
+.PP
+Usually, \fBcompinstall\fP will insert code into \fB\&.zshrc\fP, although if
+that is not writable it will save it in another file and tell you that
+file\&'s location\&.  Note that it is up to you to make sure that the lines
+added to \fB\&.zshrc\fP are actually run; you may, for example, need to move
+them to an earlier place in the file if \fB\&.zshrc\fP usually returns early\&.
+So long as you keep them all together (including the comment lines at the
+start and finish), you can rerun \fBcompinstall\fP and it will correctly
+locate and modify these lines\&.  Note, however, that any code you add to
+this section by hand is likely to be lost if you rerun \fBcompinstall\fP,
+although lines using the command `\fBzstyle\fP\&' should be gracefully handled\&.
+.PP
+The new code will take effect next time you start the shell, or run
+\fB\&.zshrc\fP by hand; there is also an option to make them take effect
+immediately\&.  However, if \fBcompinstall\fP has removed definitions, you will
+need to restart the shell to see the changes\&.
+.PP
+To run \fBcompinstall\fP you will need to make sure it is in a directory
+mentioned in your \fBfpath\fP parameter, which should already be the case if
+zsh was properly configured as long as your startup files do not remove the
+appropriate directories from \fBfpath\fP\&.  Then it must be autoloaded
+(`\fBautoload \-U compinstall\fP\&' is recommended)\&.  You can abort the
+installation any time you are being prompted for information, and your
+\fB\&.zshrc\fP will not be altered at all; changes only take place right at the
+end, where you are specifically asked for confirmation\&.
+.PP
+.SS "Use of compinit"
+.PP
+This section describes the use of \fBcompinit\fP to initialize completion for
+the current session when called directly; if you have run
+\fBcompinstall\fP it will be called automatically from your \fB\&.zshrc\fP\&.
+.PP
+To initialize the system, the function \fBcompinit\fP should be in a
+directory mentioned in the \fBfpath\fP parameter, and should be autoloaded
+(`\fBautoload \-U compinit\fP\&' is recommended), and then run simply as
+`\fBcompinit\fP\&'\&.  This will define a
+few utility functions, arrange for all the necessary shell functions to be
+autoloaded, and will then re\-define all widgets that do completion to use the
+new system\&.  If you use the \fBmenu\-select\fP widget, which is part of the
+\fBzsh/complist\fP module, you should make sure that that module is loaded
+before the call to \fBcompinit\fP so that that widget is also
+re\-defined\&.  If completion styles (see below) are set up to perform
+expansion as well as completion by default, and the TAB key is bound to
+\fBexpand\-or\-complete\fP, \fBcompinit\fP will rebind it to \fBcomplete\-word\fP;
+this is necessary to use the correct form of expansion\&.
+.PP
+Should you need to use the original completion commands, you can still
+bind keys to the old widgets by putting a `\fB\&.\fP\&' in front of the
+widget name, e\&.g\&. `\fB\&.expand\-or\-complete\fP\&'\&.
+.PP
+To speed up the running of \fBcompinit\fP, it can be made to produce a dumped
+configuration that will be read in on future invocations; this is the
+default, but can be turned off by calling \fBcompinit\fP with the
+option \fB\-D\fP\&.  The dumped file is \fB\&.zcompdump\fP in the same
+directory as the startup files (i\&.e\&. \fB$ZDOTDIR\fP or \fB$HOME\fP);
+alternatively, an explicit file name can be given by `\fBcompinit \-d\fP
+\fIdumpfile\fP\&'\&.  The next invocation of \fBcompinit\fP will read the dumped
+file instead of performing a full initialization\&.
+.PP
+If the number of completion files changes, \fBcompinit\fP will recognise this
+and produce a new dump file\&.  However, if the name of a function or the
+arguments in the first line of a \fB#compdef\fP function (as described below)
+change, it is easiest to delete the dump file by hand so that
+\fBcompinit\fP will re\-create it the next time it is run\&.  The check
+performed to see if there are new functions can be omitted by giving
+the option \fB\-C\fP\&.  In this case the dump file will only be created if
+there isn\&'t one already\&.
+.PP
+The dumping is actually done by another function, \fBcompdump\fP, but you
+will only need to run this yourself if you change the configuration
+(e\&.g\&. using \fBcompdef\fP) and then want to dump the new one\&.  The name of
+the old dumped file will be remembered for this purpose\&.
+.PP
+If the parameter \fB_compdir\fP is set, \fBcompinit\fP uses it as a directory
+where completion functions can be found; this is only necessary if they are
+not already in the function search path\&.
+.PP
+For security reasons \fBcompinit\fP also checks if the completion system
+would use files not owned by root or by the current user, or files in
+directories that are world\- or group\-writable or that are not owned by 
+root or by the current user\&.  If such files or directories are found,
+\fBcompinit\fP will ask if the completion system should really be used\&.  To
+avoid these tests and make all files found be used without asking, use the
+option \fB\-u\fP, and to make \fBcompinit\fP silently ignore all insecure files
+and directories use the option \fB\-i\fP\&.  This security check is skipped
+entirely when the \fB\-C\fP option is given\&.
+.PP
+The security check can be retried at any time by running the function
+\fBcompaudit\fP\&.  This is the same check used by \fBcompinit\fP, but when it
+is executed directly any changes to \fBfpath\fP are made local to the
+function so they do not persist\&.  The directories to be checked may be
+passed as arguments; if none are given, \fBcompaudit\fP uses \fBfpath\fP and
+\fB_compdir\fP to find completion system directories, adding missing ones
+to \fBfpath\fP as necessary\&.  To force a check of exactly the directories
+currently named in \fBfpath\fP, set \fB_compdir\fP to an empty string before
+calling \fBcompaudit\fP or \fBcompinit\fP\&.
+.PP
+The function \fBbashcompinit\fP provides compatibility with bash\&'s programmable
+completion system\&.  When run it will define the functions, \fBcompgen\fP and
+\fBcomplete\fP which correspond to the bash builtins with the same names\&.
+It will then be possible to use completion specifications and functions
+written for bash\&.
+.PP
+.SS "Autoloaded files"
+.PP
+The convention for autoloaded functions used in completion is that they
+start with an underscore; as already mentioned, the \fBfpath/FPATH\fP
+parameter must contain the directory in which they are stored\&.  If \fBzsh\fP
+was properly installed on your system, then \fBfpath/FPATH\fP automatically
+contains the required directories for the standard functions\&.
+.PP
+For incomplete installations, if \fBcompinit\fP does not find enough files
+beginning with an underscore (fewer than twenty) in the search path, it
+will try to find more by adding the directory \fB_compdir\fP to the search
+path\&.  If that directory has a subdirectory named \fBBase\fP, all
+subdirectories will be added to the path\&.  Furthermore, if the subdirectory
+\fBBase\fP has a subdirectory named \fBCore\fP, \fBcompinit\fP will add all
+subdirectories of the subdirectories to the path: this allows
+the functions to be in the same format as in the \fBzsh\fP source
+distribution\&.
+.PP
+When \fBcompinit\fP is run, it searches all such files accessible via
+\fBfpath/FPATH\fP and reads the first line of each of them\&.  This line should
+contain one of the tags described below\&.  Files whose first line does not
+start with one of these tags are not considered to be part of the
+completion system and will not be treated specially\&.
+.PP
+The tags are:
+.PP
+.PD 0
+.TP
+.PD
+\fB#compdef\fP \fIname\fP \&.\&.\&. [ \fB\-\fP{\fBp\fP|\fBP\fP} \fIpattern\fP \&.\&.\&. [ \fB\-N\fP \fIname\fP \&.\&.\&. ] ]
+The file will be made autoloadable and the function defined 
+in it will be called when completing \fIname\fPs, each of which is
+either the name of a command whose arguments are to be completed or one of
+a number of special contexts in the form \fB\-\fP\fIcontext\fP\fB\-\fP described
+below\&.
+.RS
+.PP
+Each \fIname\fP may also be of the form `\fIcmd\fP\fB=\fP\fIservice\fP\&'\&.
+When completing the command \fIcmd\fP, the function typically behaves as
+if the command (or special context) \fIservice\fP 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 \fB$service\fP when calling the function;
+the function may choose to interpret this how it wishes, and simpler
+functions will probably ignore it\&.
+.PP
+If the \fB#compdef\fP line contains one of the options \fB\-p\fP or \fB\-P\fP,
+the words following are taken to be patterns\&.  The function will be
+called when completion is attempted for a command or context that matches
+one of the patterns\&.  The options \fB\-p\fP and \fB\-P\fP are used to specify
+patterns to be tried before or after other completions respectively\&.
+Hence \fB\-P\fP may be used to specify default actions\&.
+.PP
+The option \fB\-N\fP is used after a list following \fB\-p\fP or \fB\-P\fP; it
+specifies that remaining words no longer define patterns\&.  It is
+possible to toggle between the three options as many times as necessary\&.
+.RE
+.TP
+\fB#compdef \-k\fP \fIstyle key\-sequence\fP \&.\&.\&.
+This option creates a widget behaving like the
+builtin widget \fIstyle\fP and binds it to the given \fIkey\-sequence\fPs,
+if any\&.  The \fIstyle\fP must be one of the builtin widgets that perform
+completion, namely \fBcomplete\-word\fP, \fBdelete\-char\-or\-list\fP,
+\fBexpand\-or\-complete\fP, \fBexpand\-or\-complete\-prefix\fP, \fBlist\-choices\fP,
+\fBmenu\-complete\fP, \fBmenu\-expand\-or\-complete\fP, or
+\fBreverse\-menu\-complete\fP\&.  If the \fBzsh/complist\fP module is loaded (see
+\fIzshmodules\fP(1)) the widget \fBmenu\-select\fP is also available\&.
+.RS
+.PP
+When one of the \fIkey\-sequence\fPs is typed, the function in the file will
+be invoked to generate the matches\&.  Note that a key will not be re\-bound
+if it already was (that is, was bound to something other than
+\fBundefined\-key\fP)\&.  The widget created has the same name as the file and
+can be bound to any other keys using \fBbindkey\fP as usual\&.
+.RE
+.TP
+\fB#compdef \-K\fP \fIwidget\-name\fP \fIstyle\fP \fIkey\-sequence\fP [ \fIname\fP \fIstyle\fP \fIseq\fP \&.\&.\&. ]
+This is similar to \fB\-k\fP except that only one \fIkey\-sequence\fP
+argument may be given for each \fIwidget\-name\fP \fIstyle\fP pair\&.
+However, the entire set of three arguments may be repeated with a
+different set of arguments\&.  Note in particular that the
+\fIwidget\-name\fP must be distinct in each set\&.  If it does not begin with
+`\fB_\fP\&' this will be added\&.  The \fIwidget\-name\fP should not clash with
+the name of any existing widget: names based on the name of the function
+are most useful\&.  For example,
+.RS
+.PP
+.RS
+.nf
+\fB#compdef \-K _foo_complete complete\-word "^X^C" \e 
+  _foo_list list\-choices "^X^D"\fP
+.fi
+.RE
+.PP
+(all on one line) defines a widget \fB_foo_complete\fP for completion, bound
+to `\fB^X^C\fP\&', and a widget \fB_foo_list\fP for listing, bound to `\fB^X^D\fP'\&.
+.RE
+.TP
+\fB#autoload\fP [ \fIoptions\fP ]
+Functions with the \fB#autoload\fP 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 \fIoptions\fP supplied
+will be passed to the \fBautoload\fP builtin; a typical use is \fB+X\fP to
+force the function to be loaded immediately\&.  Note that the \fB\-U\fP and
+\fB\-z\fP flags are always added implicitly\&.
+.PP
+The \fB#\fP is part of the tag name and no white space is allowed after it\&.
+The \fB#compdef\fP tags use the \fBcompdef\fP function described below; the
+main difference is that the name of the function is supplied implicitly\&.
+.PP
+The special contexts for which completion functions can be defined are:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-array\-value\-\fP
+The right hand side of an array\-assignment
+(`\fIname\fP\fB=(\fP\fI\&.\&.\&.\fP\fB)\fP\&')
+.TP
+\fB\-brace\-parameter\-\fP
+The name of a parameter expansion within braces (`\fB${\fP\fI\&.\&.\&.\fP\fB}\fP\&')
+.TP
+\fB\-assign\-parameter\-\fP
+The name of a parameter in an assignment, i\&.e\&. on the left hand side of
+an `\fB=\fP\&'
+.TP
+\fB\-command\-\fP
+A word in command position
+.TP
+\fB\-condition\-\fP
+A word inside a condition (`\fB[[\fP\fI\&.\&.\&.\fP\fB]]\fP\&')
+.TP
+\fB\-default\-\fP
+Any word for which no other completion is defined
+.TP
+\fB\-equal\-\fP
+A word beginning with an equals sign
+.TP
+\fB\-first\-\fP
+This is tried before any other completion function\&.  The function called
+may set the \fB_compskip\fP parameter to one of various values: 
+\fBall\fP: no further completion is attempted; a string
+containing the substring \fBpatterns\fP: no pattern completion functions
+will be called; a string containing \fBdefault\fP: the
+function for the `\fB\-default\-\fP\&' context will not be called, but
+functions defined for commands will be\&.
+.TP
+\fB\-math\-\fP
+Inside mathematical contexts, such as
+`\fB((\fP\fI\&.\&.\&.\fP\fB))\fP\&'
+.TP
+\fB\-parameter\-\fP
+The name of a parameter expansion (`\fB$\fP\fI\&.\&.\&.\fP\&')
+.TP
+\fB\-redirect\-\fP
+The word after a redirection operator\&.
+.TP
+\fB\-subscript\-\fP
+The contents of a parameter subscript\&.
+.TP
+\fB\-tilde\-\fP
+After an initial tilde (`\fB~\fP\&'), but before the first slash
+in the word\&.
+.TP
+\fB\-value\-\fP
+On the right hand side of an assignment\&.
+.PP
+Default implementations are supplied for each of these
+contexts\&.  In most cases the context \fB\-\fP\fIcontext\fP\fB\-\fP is
+implemented by a corresponding function \fB_\fP\fIcontext\fP, for example
+the context `\fB\-tilde\-\fP\&' and the function `\fB_tilde\fP')\&.
+.PP
+The contexts \fB\-redirect\-\fP and \fB\-value\-\fP allow extra context\-specific
+information\&.  (Internally, this is handled by the functions for each
+context calling the function \fB_dispatch\fP\&.)  The extra
+information is added separated by commas\&.
+.PP
+For the \fB\-redirect\-\fP context, the extra information is in the form
+`\fB\-redirect\-,\fP\fIop\fP\fB,\fP\fIcommand\fP\&', where \fIop\fP is the
+redirection operator and \fIcommand\fP is the name of the command on
+the line\&.  If there is no command on the line yet, the \fIcommand\fP
+field will be empty\&.
+.PP
+For the \fB\-value\-\fP context, the form is
+`\fB\-value\-,\fP\fIname\fP\fB,\fP\fIcommand\fP\&', where \fIname\fP is the name of
+the parameter on the left hand side of the assignment\&.
+In the case of elements of an associative array, for
+example `\fBassoc=(key <TAB>\fP\&', \fIname\fP is expanded to
+`\fIname\fP\fB\-\fP\fIkey\fP\&'\&.  In certain special contexts, such as
+completing after `\fBmake CFLAGS=\fP\&', the \fIcommand\fP part gives the
+name of the command, here \fBmake\fP; otherwise it is empty\&.
+.PP
+It is not necessary to define fully specific completions as the
+functions provided will try to generate completions by progressively
+replacing the elements with `\fB\-default\-\fP\&'\&.  For example, when
+completing after `\fBfoo=<TAB>\fP\&', \fB_value\fP will try the names
+`\fB\-value\-,foo,\fP\&' (note the empty \fIcommand\fP part),
+`\fB\-value\-,foo,\-default\-\fP\&' and`\fB\-value\-,\-default\-,\-default\-\fP', in
+that order, until it finds a function to handle the context\&.
+.PP
+As an example:
+.PP
+.RS
+.nf
+\fBcompdef \&'_files \-g "*\&.log"' '\-redirect\-,2>,\-default\-'\fP
+.fi
+.RE
+.PP
+completes files matching `\fB*\&.log\fP\&' after `\fB2> <TAB>\fP' for any
+command with no more specific handler defined\&.
+.PP
+Also:
+.PP
+.RS
+.nf
+\fBcompdef _foo \-value\-,\-default\-,\-default\-\fP
+.fi
+.RE
+.PP
+specifies that \fB_foo\fP provides completions for the values of
+parameters for which no special function has been defined\&.  This is
+usually handled by the function \fB_value\fP itself\&.
+.PP
+The same lookup rules are used when looking up styles (as described
+below); for example
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*:*:\-redirect\-,2>,*:*' file\-patterns '*\&.log'\fP
+.fi
+.RE
+.PP
+is another way to make completion after `\fB2> <TAB>\fP\&' complete files
+matching `\fB*\&.log\fP\&'\&.
+.PP
+.SS "Functions"
+.PP
+The following function is defined by \fBcompinit\fP and may be called
+directly\&.
+.PP
+.PD 0
+
+.TP
+.PD 0
+\fBcompdef\fP [ \fB\-ane\fP ] \fIfunction name\fP \&.\&.\&. [ \fB\-\fP{\fBp\fP|\fBP\fP} \fIpattern\fP \&.\&.\&. [ \fB\-N\fP \fIname\fP \&.\&.\&.]]
+.TP
+.PD 0
+\fBcompdef \-d\fP \fIname\fP \&.\&.\&.
+.TP
+.PD 0
+\fBcompdef \-k\fP [ \fB\-an\fP ] \fIfunction style key\-sequence\fP [ \fIkey\-sequence\fP \&.\&.\&. ]
+.TP
+.PD
+\fBcompdef \-K\fP [ \fB\-an\fP ] \fIfunction name style key\-seq\fP [ \fIname style seq\fP \&.\&.\&. ]
+The first form defines the \fIfunction\fP to call for completion in the
+given contexts as described for the \fB#compdef\fP tag above\&.
+.RS
+.PP
+Alternatively, all the arguments may have the form
+`\fIcmd\fP\fB=\fP\fIservice\fP\&'\&.  Here \fIservice\fP should already have been
+defined by `\fIcmd1\fP\fB=\fP\fIservice\fP\&' lines in \fB#compdef\fP files, as
+described above\&.  The argument for \fIcmd\fP will be completed in the
+same way as \fIservice\fP\&.
+.PP
+The \fIfunction\fP argument may alternatively be a string containing
+almost any shell code\&.  If the string contains an equal sign, the above
+will take precedence\&.  The option \fB\-e\fP may be used to specify the first
+argument is to be evaluated as shell code even if it contains an equal
+sign\&.  The string will be executed using the \fBeval\fP 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
+`\fB\&.h\fP\&' as arguments to the command \fBfoo\fP:
+.PP
+.RS
+.nf
+\fBcompdef \&'_files \-g "*\&.h"' foo\fP
+.fi
+.RE
+.PP
+The option \fB\-n\fP prevents any completions already defined for the
+command or context from being overwritten\&.
+.PP
+The option \fB\-d\fP deletes any completion defined for the command or
+contexts listed\&.
+.PP
+The \fIname\fPs may also contain \fB\-p\fP, \fB\-P\fP and \fB\-N\fP options as
+described for the \fB#compdef\fP tag\&.  The effect on the argument list is
+identical, switching between definitions of patterns tried initially,
+patterns tried finally, and normal commands and contexts\&.
+.PP
+The parameter \fB$_compskip\fP may be set by any function defined for a
+pattern context\&.  If it is set to a value containing the substring
+`\fBpatterns\fP\&' none of the pattern\-functions will be called; if it is
+set to a value containing the substring `\fBall\fP\&', no other function
+will be called\&.  Setting \fB$_compskip\fP in this manner is of particular
+utility when using the \fB\-p\fP option, as otherwise the dispatcher will
+move on to additional functions (likely the default one) after calling
+the pattern\-context one, which can mangle the display of completion
+possibilities if not handled properly\&.
+.PP
+The form with \fB\-k\fP defines a widget with the same name as the \fIfunction\fP
+that will be called for each of the \fIkey\-sequence\fPs; this is like the
+\fB#compdef \-k\fP tag\&.  The function should generate the completions needed
+and will otherwise behave like the builtin widget whose name is given as
+the \fIstyle\fP argument\&.  The widgets usable for this are:
+\fBcomplete\-word\fP, \fBdelete\-char\-or\-list\fP, \fBexpand\-or\-complete\fP,
+\fBexpand\-or\-complete\-prefix\fP, \fBlist\-choices\fP, \fBmenu\-complete\fP,
+\fBmenu\-expand\-or\-complete\fP, and \fBreverse\-menu\-complete\fP, as well as
+\fBmenu\-select\fP if the \fBzsh/complist\fP module is loaded\&.  The option \fB\-n\fP
+prevents the key being bound if it is already to bound to something other
+than \fBundefined\-key\fP\&.
+.PP
+The form with \fB\-K\fP is similar and defines multiple widgets based on the
+same \fIfunction\fP, each of which requires the set of three arguments
+\fIname\fP, \fIstyle\fP and \fIkey\-seq\fPuence, where the latter two are as
+for \fB\-k\fP and the first must be a unique widget name beginning with an
+underscore\&.
+.PP
+Wherever applicable, the \fB\-a\fP option makes the \fIfunction\fP
+autoloadable, equivalent to \fBautoload \-U \fP\fIfunction\fP\&.
+.RE
+.PP
+The function \fBcompdef\fP can be used to associate existing completion
+functions with new commands\&.  For example,
+.PP
+.RS
+.nf
+\fBcompdef _pids foo\fP
+.fi
+.RE
+.PP
+uses the function \fB_pids\fP to complete process IDs for the command \fBfoo\fP\&.
+.PP
+Note also the \fB_gnu_generic\fP function described below, which can be
+used to complete options for commands that understand the
+`\fB\-\fP\fB\-help\fP\&' option\&.
+.PP
+.SH "COMPLETION SYSTEM CONFIGURATION"
+.PP
+This section gives a short overview of how the completion system works,
+and then more detail on how users can configure how and when matches are
+generated\&.
+.PP
+.SS "Overview"
+.PP
+When completion is attempted somewhere on the command line the
+completion system begins building the context\&.  The context represents
+everything that the shell knows about the meaning of the command line
+and the significance of the cursor position\&.  This takes account of a
+number of things including the command word (such as `\fBgrep\fP\&' or
+`\fBzsh\fP\&') and options to which the current word may be an argument
+(such as the `\fB\-o\fP\&' option to \fBzsh\fP which takes a shell option as an
+argument)\&.
+.PP
+The context starts out very generic ("we are beginning a completion")
+and becomes more specific as more is learned ("the current word is in a
+position that is usually a command name" or "the current word might be a
+variable name" and so on)\&.  Therefore the context will vary during the
+same call to the completion system\&.
+.PP
+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\&.  Note that a user of the completion system
+rarely needs to compose a context string, unless for example a new
+function is being written to perform completion for a new command\&.  What a
+user may need to do is compose a \fIstyle\fP pattern, which is matched
+against a context when needed to look up context\-sensitive options that
+configure the completion system\&.
+.PP
+The next few paragraphs explain how a context is composed within the
+completion function suite\&.  Following that is discussion of how \fIstyles\fP
+are defined\&.  Styles determine such things as how the matches are
+generated, similarly to shell options but with much more control\&.  They
+are defined with the \fBzstyle\fP builtin command (see \fIzshmodules\fP(1))\&.
+.PP
+The context string always consists of a fixed set of fields, separated
+by colons and with a leading colon before the first\&.  Fields which are
+not yet known are left empty, but the surrounding colons appear anyway\&.
+The fields are always in the order
+\fB:completion:\fP\fIfunction\fP\fB:\fP\fIcompleter\fP\fB:\fP\fIcommand\fP\fB:\fP\fIargument\fP\fB:\fP\fItag\fP\&.  These have the following meaning:
+.PP
+.PD 0
+.TP
+.PD
+\(bu
+The literal string \fBcompletion\fP, saying that this style is used by
+the completion system\&.  This distinguishes the context from those used
+by, for example, zle widgets and ZFTP functions\&.
+
+.TP
+\(bu
+The \fIfunction\fP, 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 \fBpredict\-on\fP and the various
+functions in the \fBWidget\fP directory of the distribution to the name of
+that function, often in an abbreviated form\&.
+
+.TP
+\(bu
+The \fIcompleter\fP currently active, the name of the function without the
+leading underscore and with other underscores converted to hyphens\&.  A
+`completer\&' is in overall control of how completion is to be performed;
+`\fBcomplete\fP\&' is the simplest, but other completers exist to perform
+related tasks such as correction, or to modify the behaviour of a later
+completer\&.  See
+the section `Control Functions\&' below 
+for more information\&.  
+
+.TP
+\(bu
+The \fIcommand\fP or a special \fB\-\fP\fIcontext\fP\fB\-\fP, just at it appears
+following the \fB#compdef\fP tag or the \fBcompdef\fP 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 \fBcvs\fP
+command sets this field to \fBcvs\-add\fP when completing arguments to
+the \fBadd\fP subcommand\&.
+
+.TP
+\(bu
+The \fIargument\fP; this indicates which command line or option argument
+we are completing\&.  For command arguments this generally takes the form
+\fBargument\-\fP\fIn\fP, where \fIn\fP is the number of the argument,
+and for arguments to options the form \fBoption\-\fP\fIopt\fP\fB\-\fP\fIn\fP
+where \fIn\fP is the number of the argument to option \fIopt\fP\&.  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\&.
+
+.TP
+\(bu
+The \fItag\fP\&.  As described previously, tags are used to discriminate between
+the types of matches a completion function can generate in a certain context\&.
+Any completion function may use any tag name it likes, but a list of the
+more common ones is given below\&.
+
+.PP
+The context is gradually put together as the functions are executed, starting
+with the main entry point, which adds \fB:completion:\fP and the \fIfunction\fP
+element if necessary\&.  The completer then adds the \fIcompleter\fP element\&.
+The contextual completion adds the \fIcommand\fP and \fIargument\fP options\&.
+Finally, the \fItag\fP is added when the types of completion are known\&.
+For example, the context name
+.PP
+.RS
+.nf
+\fB\fB:completion::complete:dvips:option\-o\-1:files\fP\fP
+.fi
+.RE
+.PP
+says that normal completion was attempted as the first argument to the
+option \fB\-o\fP of the command \fBdvips\fP:
+.PP
+.RS
+.nf
+\fB\fBdvips \-o \&.\&.\&.\fP\fP
+.fi
+.RE
+.PP
+and the completion function will generate filenames\&.
+.PP
+Usually completion will be tried for all possible tags in an order given
+by the completion function\&.  However, this can be altered by using the
+\fBtag\-order\fP style\&.  Completion is then restricted to the list of given
+tags in the given order\&.
+.PP
+The \fB_complete_help\fP bindable command shows all the contexts and tags
+available for completion at a particular point\&.  This provides an easy
+way of finding information for \fBtag\-order\fP and other styles\&.  It is
+described in
+the section `Bindable Commands\&' below\&.
+.PP
+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 is matched to the most specific (best
+fitting) style pattern, and the name of the style itself, which must be
+matched exactly\&.  The following examples demonstrate that style patterns
+may be loosely defined for styles that apply broadly, or as tightly
+defined as desired for styles that apply in narrower circumstances\&.
+.PP
+For example, many completion functions can generate matches in a
+simple and a verbose form and use the \fBverbose\fP style to decide
+which form should be used\&.  To make all such functions use the verbose form,
+put
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' verbose yes\fP
+.fi
+.RE
+.PP
+in a startup file (probably \fB\&.zshrc\fP)\&.
+This gives the \fBverbose\fP style the value \fByes\fP in every
+context inside the completion system, unless that context has a more
+specific definition\&.  It is best to avoid giving the context as `\fB*\fP\&'
+in case the style has some meaning outside the completion system\&.
+.PP
+Many such general purpose styles can be configured simply by using the
+\fBcompinstall\fP function\&.
+.PP
+A more specific example of the use of the \fBverbose\fP style is by the
+completion for the \fBkill\fP 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:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*:*:kill:*:*' verbose no\fP
+.fi
+.RE
+.PP
+For even more control, the style can use one of the tags `\fBjobs\fP\&' or
+`\fBprocesses\fP\&'\&.  To turn off verbose display only for jobs:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*:*:kill:*:jobs' verbose no\fP
+.fi
+.RE
+.PP
+The \fB\-e\fP option to \fBzstyle\fP even allows completion function code to
+appear as the argument to a style; this requires some understanding of
+the internals of completion functions (see
+see \fIzshcompwid\fP(1)))\&.  For example,
+.PP
+.RS
+.nf
+\fB\fBzstyle \-e \&':completion:*' hosts 'reply=($myhosts)'\fP\fP
+.fi
+.RE
+.PP
+This forces the value of the \fBhosts\fP style to be read from the
+variable \fBmyhosts\fP each time a host name is needed; this is useful
+if the value of \fBmyhosts\fP can change dynamically\&.
+For another useful example, see the example in the description of the
+\fBfile\-list\fP style below\&.  This form can be
+slow and should be avoided for commonly examined styles such
+as \fBmenu\fP and \fBlist\-rows\-first\fP\&.
+.PP
+Note that the order in which styles are \fIdefined\fP does not matter; the
+style mechanism uses the most specific possible match for a particular
+style to determine the set of values\&.  More precisely, strings are
+preferred over patterns (for example, `\fB:completion::complete:::foo\fP\&' is
+more specific than `\fB:completion::complete:::*\&'\fP), and longer patterns are
+preferred over shorter patterns\&.
+.PP
+A good rule of thumb is that any completion style pattern that needs to
+include more than one wildcard (\fB*\fP) and that does not end in a tag
+name, should include all six colons (\fB:\fP), possibly surrounding
+additional wildcards\&.
+.PP
+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\&.
+.PP
+.SS "Standard Tags"
+.PP
+Some of the following are only used when looking up particular styles
+and do not refer to a type of match\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBaccounts\fP
+used to look up the \fBusers\-hosts\fP style
+.TP
+\fBall\-expansions\fP
+used by the \fB_expand\fP completer when adding the single string containing
+all possible expansions
+.TP
+\fBall\-files\fP
+for the names of all files (as distinct from a particular subset, see the
+\fBglobbed\-files\fP tag)\&.
+.TP
+\fBarguments\fP
+for arguments to a command
+.TP
+\fBarrays\fP
+for names of array parameters
+.TP
+\fBassociation\-keys\fP
+for keys of associative arrays; used when completing inside a
+subscript to a parameter of this type
+.TP
+\fBbookmarks\fP
+when completing bookmarks (e\&.g\&. for URLs and the \fBzftp\fP function suite)
+.TP
+\fBbuiltins\fP
+for names of builtin commands
+.TP
+\fBcharacters\fP
+for single characters in arguments of commands such as \fBstty\fP\&.   Also used
+when completing character classes after an opening bracket
+.TP
+\fBcolormapids\fP
+for X colormap ids
+.TP
+\fBcolors\fP
+for color names
+.TP
+\fBcommands\fP
+for names of external commands\&.  Also used by complex commands such as
+\fBcvs\fP when completing names subcommands\&.
+.TP
+\fBcontexts\fP
+for contexts in arguments to the \fBzstyle\fP builtin command
+.TP
+\fBcorrections\fP
+used by the \fB_approximate\fP and \fB_correct\fP completers for possible
+corrections
+.TP
+\fBcursors\fP
+for cursor names used by X programs
+.TP
+\fBdefault\fP
+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 \fIfunction\fP field of the context name is set
+.TP
+\fBdescriptions\fP
+used when looking up the value of the \fBformat\fP style to generate
+descriptions for types of matches
+.TP
+\fBdevices\fP
+for names of device special files
+.TP
+\fBdirectories\fP
+for names of directories \-\- \fBlocal\-directories\fP is used instead
+when completing arguments of \fBcd\fP and related builtin commands when
+the \fBcdpath\fP array is set
+.TP
+\fBdirectory\-stack\fP
+for entries in the directory stack
+.TP
+\fBdisplays\fP
+for X display names
+.TP
+\fBdomains\fP
+for network domains
+.TP
+\fBemail\-\fP\fIplugin\fP
+for email addresses from the `\fB_email\-\fP\fIplugin\fP\&' backend of \fB_email_addresses\fP
+.TP
+\fBexpansions\fP
+used by the \fB_expand\fP completer for individual words (as opposed to
+the complete set of expansions) resulting from the expansion of a word
+on the command line
+.TP
+\fBextensions\fP
+for X server extensions
+.TP
+\fBfile\-descriptors\fP
+for numbers of open file descriptors
+.TP
+\fBfiles\fP
+the generic file\-matching tag used by functions completing filenames
+.TP
+\fBfonts\fP
+for X font names
+.TP
+\fBfstypes\fP
+for file system types (e\&.g\&. for the \fBmount\fP command)
+.TP
+\fBfunctions\fP
+names of functions \-\- normally shell functions, although certain
+commands may understand other kinds of function
+.TP
+\fBglobbed\-files\fP
+for filenames when the name has been generated by pattern matching
+.TP
+\fBgroups\fP
+for names of user groups
+.TP
+\fBhistory\-words\fP
+for words from the history
+.TP
+\fBhosts\fP
+for hostnames
+.TP
+\fBindexes\fP
+for array indexes
+.TP
+\fBjobs\fP
+for jobs (as listed by the `\fBjobs\fP\&' builtin)
+.TP
+\fBinterfaces\fP
+for network interfaces
+.TP
+\fBkeymaps\fP
+for names of zsh keymaps
+.TP
+\fBkeysyms\fP
+for names of X keysyms
+.TP
+\fBlibraries\fP
+for names of system libraries
+.TP
+\fBlimits\fP
+for system limits
+.TP
+\fBlocal\-directories\fP
+for names of directories that are subdirectories of the current working
+directory when completing arguments of \fBcd\fP and related builtin
+commands (compare \fBpath\-directories\fP) \-\- when the \fBcdpath\fP
+array is unset, \fBdirectories\fP is used instead
+.TP
+\fBmanuals\fP
+for names of manual pages
+.TP
+\fBmailboxes\fP
+for e\-mail folders
+.TP
+\fBmaps\fP
+for map names (e\&.g\&. NIS maps)
+.TP
+\fBmessages\fP
+used to look up the \fBformat\fP style for messages
+.TP
+\fBmodifiers\fP
+for names of X modifiers
+.TP
+\fBmodules\fP
+for modules (e\&.g\&. \fBzsh\fP modules)
+.TP
+\fBmy\-accounts\fP
+used to look up the \fBusers\-hosts\fP style
+.TP
+\fBnamed\-directories\fP
+for named directories (you wouldn\&'t have guessed that, would you?)
+.TP
+\fBnames\fP
+for all kinds of names
+.TP
+\fBnewsgroups\fP
+for USENET groups
+.TP
+\fBnicknames\fP
+for nicknames of NIS maps
+.TP
+\fBoptions\fP
+for command options
+.TP
+\fBoriginal\fP
+used by the \fB_approximate\fP, \fB_correct\fP and \fB_expand\fP completers when
+offering the original string as a match
+.TP
+\fBother\-accounts\fP
+used to look up the \fBusers\-hosts\fP style
+.TP
+\fBother\-files\fP
+for the names of any non\-directory files\&.  This is used instead
+of \fBall\-files\fP when the \fBlist\-dirs\-first\fP style is in effect\&.
+.TP
+\fBpackages\fP
+for packages (e\&.g\&. \fBrpm\fP or installed \fBDebian\fP packages)
+.TP
+\fBparameters\fP
+for names of parameters
+.TP
+\fBpath\-directories\fP
+for names of directories found by searching the \fBcdpath\fP array when
+completing arguments of \fBcd\fP and related builtin commands (compare
+\fBlocal\-directories\fP)
+.TP
+\fBpaths\fP
+used to look up the values of the \fBexpand\fP, \fBambiguous\fP and
+\fBspecial\-dirs\fP styles
+.TP
+\fBpods\fP
+for perl pods (documentation files)
+.TP
+\fBports\fP
+for communication ports
+.TP
+\fBprefixes\fP
+for prefixes (like those of a URL)
+.TP
+\fBprinters\fP
+for print queue names
+.TP
+\fBprocesses\fP
+for process identifiers
+.TP
+\fBprocesses\-names\fP
+used to look up the \fBcommand\fP style when generating the names of
+processes for \fBkillall\fP
+.TP
+\fBsequences\fP
+for sequences (e\&.g\&. \fBmh\fP sequences)
+.TP
+\fBsessions\fP
+for sessions in the \fBzftp\fP function suite
+.TP
+\fBsignals\fP
+for signal names
+.TP
+\fBstrings\fP
+for strings (e\&.g\&. the replacement strings for the \fBcd\fP builtin
+command)
+.TP
+\fBstyles\fP
+for styles used by the zstyle builtin command
+.TP
+\fBsuffixes\fP
+for filename extensions
+.TP
+\fBtags\fP
+for tags (e\&.g\&. \fBrpm\fP tags)
+.TP
+\fBtargets\fP
+for makefile targets
+.TP
+\fBtime\-zones\fP
+for time zones (e\&.g\&. when setting the \fBTZ\fP parameter)
+.TP
+\fBtypes\fP
+for types of whatever (e\&.g\&. address types for the \fBxhost\fP command)
+.TP
+\fBurls\fP
+used to look up the \fBurls\fP and \fBlocal\fP styles when completing URLs
+.TP
+\fBusers\fP
+for usernames
+.TP
+\fBvalues\fP
+for one of a set of values in certain lists
+.TP
+\fBvariant\fP
+used by \fB_pick_variant\fP to look up the command to run when determining
+what program is installed for a particular command name\&.
+.TP
+\fBvisuals\fP
+for X visuals
+.TP
+\fBwarnings\fP
+used to look up the \fBformat\fP style for warnings
+.TP
+\fBwidgets\fP
+for zsh widget names
+.TP
+\fBwindows\fP
+for IDs of X windows
+.TP
+\fBzsh\-options\fP
+for shell options
+.PP
+.SS "Standard Styles"
+.PP
+Note that the values of several of these styles represent boolean
+values\&.  Any of the strings `\fBtrue\fP\&', `\fBon\fP',
+`\fByes\fP\&', and `\fB1\fP' can be used for the value `true' and
+any of the strings `\fBfalse\fP\&', `\fBoff\fP', `\fBno\fP', and `\fB0\fP' 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\&.
+.PP
+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
+\fBdefault\fP tag\&.  The most notable styles of this type are \fBmenu\fP, 
+\fBlist\-colors\fP and styles controlling completion listing such as 
+\fBlist\-packed\fP and \fBlast\-prompt\fP\&.  When tested for the \fBdefault\fP
+tag, only the \fIfunction\fP field of the context will be set so that
+a style using the \fBdefault\fP tag will normally be defined along the lines of:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*:default' menu \&.\&.\&.\fP
+.fi
+.RE
+.PP
+.PD 0
+.TP
+.PD
+\fBaccept\-exact\fP
+This is tested for the \fBdefault\fP 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)\&.
+.RS
+.PP
+When completing pathnames (where the tag used is `\fBpaths\fP\&')
+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\&.
+.PP
+This style is also used by the \fB_expand\fP completer to decide if
+words beginning with a tilde or parameter expansion should be
+expanded\&.  For example, if there are parameters
+\fBfoo\fP and \fBfoobar\fP, the string `\fB$foo\fP\&' will only be expanded if 
+\fBaccept\-exact\fP is set to `true\&'; otherwise the completion system will
+be allowed to complete \fB$foo\fP to \fB$foobar\fP\&. If the style is set to
+`\fBcontinue\fP\&', \fB_expand\fP will add the expansion as a match and the completion
+system will also be allowed to continue\&.
+.RE
+.TP
+\fBaccept\-exact\-dirs\fP
+This is used by filename completion\&.  Unlike \fBaccept\-exact\fP it is
+a boolean\&.  By default, filename completion examines all components
+of a path to see if there are completions of that component, even if
+the component matches an existing directory\&.  For example, when
+completion after \fB/usr/bin/\fP, the function examines possible
+completions to \fB/usr\fP\&.
+.RS
+.PP
+When this style is `true\&', any prefix of a path that matches an existing
+directory is accepted without any attempt to complete it further\&.
+Hence, in the given example, the path \fB/usr/bin/\fP is accepted
+immediately and completion tried in that directory\&.
+.PP
+This style is also useful when completing after directories that
+magically appear when referenced, such as ZFS \fB\&.zfs\fP directories
+or NetApp \fB\&.snapshot\fP directories\&.  When the style is set the
+shell does not check for the existence of the directory within the
+parent directory\&.
+.PP
+If you wish to inhibit this behaviour entirely, set the \fBpath\-completion\fP
+style (see below) to `false\&'\&.
+.RE
+.TP
+\fBadd\-space\fP
+This style is used by the \fB_expand\fP completer\&.  If it is `true\&' (the
+default), a space will be inserted after all words resulting from the 
+expansion, or a slash in the case of directory names\&.  If the value
+is `\fBfile\fP\&', the completer will only add a space
+to names of existing files\&.  Either a boolean `true\&' or the value
+`\fBfile\fP\&' may be combined with `\fBsubst\fP', in which case the completer
+will not add a space to words generated from the expansion of a
+substitution of the form `\fB$(\fP\fI\&.\&.\&.\fP\fB)\fP\&' or `\fB${\fP\fI\&.\&.\&.\fP\fB}\fP'\&.
+.RS
+.PP
+The \fB_prefix\fP completer uses this style as a simple boolean value
+to decide if a space should be inserted before the suffix\&.
+.RE
+.TP
+\fBambiguous\fP
+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 \fBpaths\fP tag\&.
+.TP
+\fBassign\-list\fP
+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 \fBPATH\fP and similar parameters\&.  This style can be set to a
+list of patterns matching the names of such parameters\&.
+.RS
+.PP
+The default is to complete lists when the word on the line already
+contains a colon\&.
+.RE
+.TP
+\fBauto\-description\fP
+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 `\fB%d\fP\&' in the value will be replaced by
+the description for this argument\&.  Depending on personal preferences,
+it may be useful to set this style to something like `\fBspecify: %d\fP\&'\&. 
+Note that this may not work for some commands\&.
+.TP
+\fBavoid\-completer\fP
+This is used by the \fB_all_matches\fP completer to decide if the string 
+consisting of all matches should be added to the list currently being
+generated\&.  Its value is a list of names of completers\&.  If any of
+these is the name of the completer that generated the matches in this
+completion, the string will not be added\&.
+.RS
+.PP
+The default value for this style is `\fB_expand _old_list _correct
+_approximate\fP\&', i\&.e\&. it contains the completers for which a string
+with all matches will almost never be wanted\&.
+.RE
+.TP
+\fBcache\-path\fP
+This style defines the path where any cache files containing dumped
+completion data are stored\&.  It defaults to `\fB$ZDOTDIR/\&.zcompcache\fP\&', or
+`\fB$HOME/\&.zcompcache\fP\&' if \fB$ZDOTDIR\fP is not defined\&.  The completion
+cache will not be used unless the \fBuse\-cache\fP style is set\&.
+.TP
+\fBcache\-policy\fP
+This style defines the function that will be used to determine whether
+a cache needs rebuilding\&.  See the section on the \fB_cache_invalid\fP
+function below\&.
+.TP
+\fBcall\-command\fP
+This style is used in the function for commands such as \fBmake\fP and
+\fBant\fP where calling the command directly to generate matches suffers
+problems such as being slow or, as in the case of \fBmake\fP can
+potentially cause actions in the makefile to be executed\&. If it is set
+to `true\&' the command is called to generate matches\&. The default value
+of this style is `false\&'\&.
+.TP
+\fBcommand\fP
+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 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 `\fBbuiltin\fP\&' or `\fBcommand\fP' in
+front to make sure the appropriate version of a command is called, for
+example to avoid calling a shell function with the same name as an external
+command\&.
+.RS
+.PP
+As an example, the completion function for process IDs uses this
+style with the \fBprocesses\fP tag to generate the IDs to complete and
+the list of processes to display (if the \fBverbose\fP style is `true\&')\&.
+The list produced by the command should look like the output of the
+\fBps\fP command\&.  The first line is not displayed, but is searched for
+the string `\fBPID\fP\&' (or `\fBpid\fP') to find the position of the
+process IDs in the following lines\&.  If the line does not contain
+`\fBPID\fP\&', the first numbers in each of the other lines are taken as the 
+process IDs to complete\&.
+.PP
+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\&.
+.RE
+.TP
+\fBcommand\-path\fP
+This is a list of directories to search for commands to complete\&.  The
+default for this style is the value of the special parameter \fBpath\fP\&.
+.TP
+\fBcommands\fP
+This is used by the function completing sub\-commands for the system
+initialisation scripts (residing in \fB/etc/init\&.d\fP or somewhere not
+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 `\fBstart\fP\&' and `\fBstop\fP'\&.
+.TP
+\fBcomplete\fP
+This is used by the \fB_expand_alias\fP function when invoked as a
+bindable command\&.  If set to `true\&' and the word on the command
+line is not the name of an alias, matching alias names will be
+completed\&.
+.TP
+\fBcomplete\-options\fP
+This is used by the completer for \fBcd\fP, \fBchdir\fP and \fBpushd\fP\&.
+For these commands a \fB\-\fP is used to introduce a directory stack entry
+and completion of these is far more common than completing options\&.
+Hence unless the value of this style is `true\&' options will not be
+completed, even after an initial \fB\-\fP\&.  If it is `true\&', options will
+be completed after an initial \fB\-\fP unless there is a preceding
+\fB\-\fP\fB\-\fP on the command line\&.
+.TP
+\fBcompleter\fP
+The strings given as the value of this style provide the names of the
+completer functions to use\&. The available completer functions are
+described in
+the section `Control Functions\&' below\&.
+.RS
+.PP
+Each string may be either the name of a completer function or a string
+of the form `\fIfunction\fP\fB:\fP\fIname\fP\&'\&.  In the first case the
+\fIcompleter\fP 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
+\fIfunction\fP is the name of the completer to call, but the context
+will contain the user\-defined \fIname\fP in the \fIcompleter\fP field of
+the context\&.  If the \fIname\fP 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 \fIname\fP appended to it\&.  For example: 
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' completer _complete _complete:\-foo\fP
+.fi
+.RE
+.PP
+Here, completion will call the \fB_complete\fP completer twice, once
+using `\fBcomplete\fP\&' and once using `\fBcomplete\-foo\fP' in the
+\fIcompleter\fP field of the context\&.  Normally, using the same
+completer more than once only makes sense when used with the
+`\fIfunctions\fP\fB:\fP\fIname\fP\&' form, because otherwise the context
+name will be the same in all calls to the completer; possible
+exceptions to this rule are the \fB_ignored\fP and \fB_prefix\fP
+completers\&.
+.PP
+The default value for this style is `\fB_complete _ignored\fP\&':
+only completion will be done, first using the \fBignored\-patterns\fP style
+and the \fB$fignore\fP array and then without ignoring matches\&.
+.RE
+.TP
+\fBcondition\fP
+This style is used by the \fB_list\fP completer function to decide if
+insertion of matches should be delayed unconditionally\&. The default is 
+`true\&'\&.
+.TP
+\fBdelimiters\fP
+This style is used when adding a delimiter for use with history
+modifiers or glob qualifiers that have delimited arguments\&.  It is
+an array of preferred delimiters to add\&.  Non\-special characters are
+preferred as the completion system may otherwise become confused\&.
+The default list is \fB:\fP, \fB+\fP, \fB/\fP, \fB\-\fP, \fB%\fP\&.  The list
+may be empty to force a delimiter to be typed\&.
+.TP
+\fBdisabled\fP
+If this is set to `true\&', the \fB_expand_alias\fP completer and bindable 
+command will try to expand disabled aliases, too\&.  The default is
+`false\&'\&.
+.TP
+\fBdomains\fP
+A list of names of network domains for completion\&.
+If this is not set, domain names will be taken from
+the file \fB/etc/resolv\&.conf\fP\&.
+.TP
+\fBenviron\fP
+The environ style is used when completing for `\fBsudo\fP\&'\&.  It is set to an
+array of `\fIVAR\fP\fB=\fP\fIvalue\fP\&' assignments to be exported into the
+local environment before the completion for the target command is invoked\&.
+.RS
+.nf
+\fBzstyle \&':completion:*:sudo::' environ \e 
+  PATH="/sbin:/usr/sbin:$PATH" HOME="/root"\fP
+.fi
+.RE
+.TP
+\fBexpand\fP
+This style is used when completing strings consisting of multiple
+parts, such as path names\&.
+.RS
+.PP
+If one of its values is the string `\fBprefix\fP\&', the partially typed
+word from the line will be expanded as far as possible even if trailing
+parts cannot be completed\&.
+.PP
+If one of its values is the string `\fBsuffix\fP\&', 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\&.
+.RE
+.TP
+\fBfake\fP
+This style may be set for any completion context\&.  It
+specifies additional strings that will always be completed in that
+context\&.  The form of each string is `\fIvalue\fP\fB:\fP\fIdescription\fP\&'; 
+the colon and description may be omitted, but any literal colons in
+\fIvalue\fP must be quoted with a backslash\&.  Any \fIdescription\fP
+provided is shown alongside the value in completion listings\&.
+.RS
+.PP
+It is important to use a sufficiently restrictive context when specifying
+fake strings\&.  Note that the styles \fBfake\-files\fP and \fBfake\-parameters\fP
+provide additional features when completing files or parameters\&.
+.RE
+.TP
+\fBfake\-always\fP
+This works identically to the \fBfake\fP style except that
+the \fBignored\-patterns\fP style is not applied to it\&.  This makes it
+possible to override a set of matches completely by setting the
+ignored patterns to `\fB*\fP\&'\&.
+.RS
+.PP
+The following shows a way of supplementing any tag with arbitrary data, but
+having it behave for display purposes like a separate tag\&.  In this example
+we use the features of the \fBtag\-order\fP style to divide the
+\fBnamed\-directories\fP tag into two when performing completion with
+the standard completer \fBcomplete\fP for arguments of \fBcd\fP\&.  The tag
+\fBnamed\-directories\-normal\fP behaves as normal, but the tag
+\fBnamed\-directories\-mine\fP contains a fixed set of directories\&.
+This has the effect of adding the match group `\fBextra directories\fP\&' with
+the given completions\&.
+.PP
+.RS
+.nf
+\fBzstyle \&':completion::complete:cd:*' tag\-order \e 
+  \&'named\-directories:\-mine:extra\e directories
+  named\-directories:\-normal:named\e directories *\&'
+zstyle \&':completion::complete:cd:*:named\-directories\-mine' \e 
+  fake\-always mydir1 mydir2
+zstyle \&':completion::complete:cd:*:named\-directories\-mine' \e 
+  ignored\-patterns \&'*'\fP
+.fi
+.RE
+.RE
+.TP
+\fBfake\-files\fP
+This style is used when completing files and looked up 
+without a tag\&.  Its values are of the form
+`\fIdir\fP\fB:\fP\fInames\&.\&.\&.\fP\&'\&.  This will add the \fInames\fP (strings
+separated by spaces) as
+possible matches when completing in the directory \fIdir\fP, even if no 
+such files really exist\&.  The dir may be a pattern; pattern characters
+or colons in \fIdir\fP should be quoted with a backslash to be treated
+literally\&.
+.RS
+.PP
+This can be useful on systems that support special file systems whose
+top\-level pathnames can not be listed or generated with glob patterns
+(but see \fBaccept\-exact\-dirs\fP for a more general way of dealing
+with this problem)\&.  It can also be used for directories for which one
+does not have read permission\&.
+.PP
+The pattern form can be used to add a certain `magic\&' entry
+to all directories on a particular file system\&.
+.RE
+.TP
+\fBfake\-parameters\fP
+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 `\fBscalar\fP\&', `\fBarray\fP' or `\fBinteger\fP')\&.  If the type is
+given, the name will only be completed if parameters of that type are
+required in the particular context\&.  Names for which no type is
+specified will always be completed\&.
+.TP
+\fBfile\-list\fP
+This style controls whether files completed using the standard builtin
+mechanism are to be listed with a long list similar to \fBls \-l\fP\&.
+Note that this feature uses the shell module
+\fBzsh/stat\fP for file information; this loads the builtin \fBstat\fP
+which will replace any external \fBstat\fP executable\&.  To avoid
+this the following code can be included in an initialization file:
+.RS
+.PP
+.RS
+.nf
+\fBzmodload \-i zsh/stat
+disable stat\fP
+.fi
+.RE
+.PP
+The style may either be set to a `true\&' value (or `\fBall\fP'), or
+one of the values `\fBinsert\fP\&' or `\fBlist\fP', indicating that files
+are to be listed in long format in all circumstances, or when
+attempting to insert a file name, or when listing file names
+without attempting to insert one\&.
+.PP
+More generally, the value may be an array of any of the above values,
+optionally followed by \fB=\fP\fInum\fP\&.  If \fInum\fP is present it
+gives the maximum number of matches for which long listing style
+will be used\&.  For example,
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' file\-list list=20 insert=10\fP
+.fi
+.RE
+.PP
+specifies that long format will be used when listing up to 20 files
+or inserting a file with up to 10 matches (assuming a listing
+is to be shown at all, for example on an ambiguous completion), else short
+format will be used\&.
+.PP
+.RS
+.nf
+\fBzstyle \-e \&':completion:*' file\-list \e 
+       \&'(( ${+NUMERIC} )) && reply=(true)'\fP
+.fi
+.RE
+.PP
+specifies that long format will be used any time a numeric argument is
+supplied, else short format\&.
+.RE
+.TP
+\fBfile\-patterns\fP
+This is used by the standard function for completing filenames,
+\fB_files\fP\&.  If the style is unset up to three tags are offered,
+`\fBglobbed\-files\fP\&',`\fBdirectories\fP' and `\fBall\-files\fP', depending on
+the types of files  expected by the caller of \fB_files\fP\&.  The first two
+(`\fBglobbed\-files\fP\&' and `\fBdirectories\fP') are normally offered
+together to make it easier to complete files in sub\-directories\&.
+.RS
+.PP
+The \fBfile\-patterns\fP style provides alternatives to the default tags,
+which are not used\&.  Its value consists of elements of the form
+`\fIpattern\fP\fB:\fP\fItag\fP\&'; each string may contain any number of
+such specifications separated by spaces\&.
+.PP
+The \fIpattern\fP is a pattern that is to be used to generate filenames\&.
+Any occurrence of the sequence `\fB%p\fP\&' is replaced by any
+pattern(s)
+passed by the function calling \fB_files\fP\&.  Colons in the pattern must
+be preceded by a backslash to make them distinguishable from the colon
+before the \fItag\fP\&.  If more than one pattern is needed, the patterns
+can be given inside braces, separated by commas\&.
+.PP
+The \fItag\fPs of all strings in the value will be offered by \fB_files\fP
+and used when looking up other styles\&.  Any \fItag\fPs in the same
+word will be offered at the same time and before later words\&.
+If no `\fB:\fP\fItag\fP\&' is given the `\fBfiles\fP' tag will be used\&.
+.PP
+The \fItag\fP may also be followed by an optional second colon and a
+description, which will be used for the `\fB%d\fP\&' in the value of
+the \fBformat\fP style (if that is set) instead of the default
+description supplied by the completion function\&.  If the description
+given here contains itself a `\fB%d\fP\&', that is replaced with the
+description supplied by the completion function\&.
+.PP
+For example, to make the \fBrm\fP command first complete only names of
+object files and then the names of all files if there is no matching
+object file:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*:*:rm:*:*' file\-patterns \e 
+    \&'*\&.o:object\-files' '%p:all\-files'\fP
+.fi
+.RE
+.PP
+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:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' file\-patterns \e 
+    \&'%p:globbed\-files' '*(\-/):directories' '*:all\-files'\fP
+.fi
+.RE
+.PP
+This works even where there is no special pattern: \fB_files\fP matches
+all files using the pattern `\fB*\fP\&' 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\&.
+.PP
+During the execution of completion functions, the \fBEXTENDED_GLOB\fP
+option is in effect, so the characters `\fB#\fP\&', `\fB~\fP' and `\fB^\fP' have
+special meanings in the patterns\&.
+.RE
+.TP
+\fBfile\-sort\fP
+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: `\fBsize\fP\&' to sort by the size of the file;
+`\fBlinks\fP\&' to sort by the number of links to the file;
+`\fBmodification\fP\&' (or `\fBtime\fP' or `\fBdate\fP') to sort by the last
+modification time; `\fBaccess\fP\&' to sort by the last access time; and
+`\fBinode\fP\&' (or `\fBchange\fP') 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
+`\fBreverse\fP\&', sorting is done in the opposite order\&.  If the value
+contains the string `\fBfollow\fP\&', timestamps are associated with the
+targets of symbolic links; the default is to use the timestamps
+of the links themselves\&.
+.TP
+\fBfile\-split\-chars\fP
+A set of characters that will cause \fIall\fP file completions for
+the given context to be split at the point where any of the characters
+occurs\&.  A typical use is to set the style to \fB:\fP; then everything
+up to and including the last \fB:\fP in the string so far is ignored when
+completing files\&.  As this is quite heavy\-handed, it is usually
+preferable to update completion functions for contexts where this
+behaviour is useful\&.
+.TP
+\fBfilter\fP
+The \fBldap\fP plugin of email address completion (see \fB_email_addresses\fP) uses
+this style to specify
+the attributes to match against when filtering entries\&.  So for example, if
+the style is set to `\fBsn\fP\&', 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
+\fBcommand\fP style to specify how to connect to your LDAP server\&.
+.TP
+\fBforce\-list\fP
+This forces a list of completions to be shown at any point where listing is
+done, even in cases where the list would usually be suppressed\&.
+For example, normally the list is only shown if
+there are at least two different matches\&.  By setting this style to
+`\fBalways\fP\&', the list will always be shown, even if there is only a
+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\&.
+.RS
+.PP
+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\&.
+.RE
+.TP
+\fBformat\fP
+If this is set for the \fBdescriptions\fP tag, its value is used as a
+string to display above matches in completion lists\&.  The sequence
+`\fB%d\fP\&' in this string will be replaced with a short description of
+what these matches are\&.  This string may also contain the output
+attribute sequences understood by \fBcompadd \-X\fP
+(see
+\fIzshcompwid\fP(1))\&.
+.RS
+.PP
+The style is tested with each tag valid for the current completion
+before it is tested for the \fBdescriptions\fP tag\&.  Hence different format 
+strings can be defined for different types of match\&.
+.PP
+Note also that some completer functions define additional
+`\fB%\fP\&'\-sequences\&.  These are described for the completer functions that 
+make use of them\&.
+.PP
+Some completion functions display messages that may be customised by
+setting this style for the \fBmessages\fP tag\&.  Here, the `\fB%d\fP\&' is
+replaced with a message given by the completion function\&.
+.PP
+Finally, the format string is looked up with the \fBwarnings\fP tag, 
+for use when no matches could be generated at all\&.  In this case the
+`\fB%d\fP\&' is replaced with the descriptions for the matches that were
+expected separated by spaces\&.  The sequence `\fB%D\fP\&' is replaced with
+the same descriptions separated by newlines\&.
+.PP
+It is possible to use printf\-style field width specifiers with `\fB%d\fP\&'
+and similar escape sequences\&.  This is handled by the \fBzformat\fP
+builtin command from the \fBzsh/zutil\fP module, see
+\fIzshmodules\fP(1)\&.
+.RE
+.TP
+\fBglob\fP
+This is used by the \fB_expand\fP completer\&.  If
+it is set to `true\&' (the default), globbing will be attempted on the
+words resulting from a previous substitution (see the \fBsubstitute\fP
+style) or else the original string from the line\&.
+.TP
+\fBglobal\fP
+If this is set to `true\&' (the default), the \fB_expand_alias\fP
+completer and bindable command will try to expand global aliases\&.
+.TP
+\fBgroup\-name\fP
+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:
+.RS
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*:*:\-command\-:*:commands' \e 
+       group\-name commands
+zstyle \&':completion:*:*:\-command\-:*:functions' \e 
+       group\-name functions\fP
+.fi
+.RE
+.PP
+As a consequence, any match with the same tag will be displayed in the
+same group\&.
+.PP
+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:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' group\-name ''\fP
+.fi
+.RE
+.PP
+All matches for which no group name is defined will be put in a group
+named \fB\-default\-\fP\&.
+.RE
+.TP
+\fBgroup\-order\fP
+This style is additional to the \fBgroup\-name\fP style to specify the
+order for display of the groups defined by that style (compare \fBtag\-order\fP,
+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\&.
+.RS
+.PP
+For example, to have names of builtin commands, shell functions and
+external commands appear in that order when completing in command
+position:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*:*:\-command\-:*:*' group\-order \e 
+       builtins functions commands\fP
+.fi
+.RE
+.RE
+.TP
+\fBgroups\fP
+A list of names of UNIX groups\&.  If this is not set,
+group names are taken from the YP database or the file `\fB/etc/group\fP\&'\&.
+.TP
+\fBhidden\fP
+If this is set to `true\&', matches for the given context
+will not be listed, although
+any description for the matches set with the \fBformat\fP style will be
+shown\&.  If it is set to `\fBall\fP\&', not even the description will be
+displayed\&.
+.RS
+.PP
+Note that the matches will still be completed; they are just not shown 
+in the list\&.  To avoid having matches considered as possible
+completions at all, the \fBtag\-order\fP style can be modified as described
+below\&.
+.RE
+.TP
+\fBhosts\fP
+A list of names of hosts that should be completed\&.  If this is not set,
+hostnames are taken from the file `\fB/etc/hosts\fP\&'\&.
+.TP
+\fBhosts\-ports\fP
+This style is used by commands that need or accept hostnames and
+network ports\&.  The strings in the value should be of the form
+`\fIhost\fP\fB:\fP\fIport\fP\&'\&.  Valid ports are determined by the presence
+of hostnames; multiple ports for the same host may appear\&.
+.TP
+\fBignore\-line\fP
+This is tested for each tag valid for the current completion\&.  If
+it is set to `true\&', none of the words that are already on the line
+will be considered as possible completions\&.  If it is set to
+`\fBcurrent\fP\&', the word the cursor is on will not be considered as a
+possible completion\&.  The value `\fBcurrent\-shown\fP\&' is similar but only
+applies if the list of completions is currently shown on the screen\&.
+Finally, if the style is set to `\fBother\fP\&', all words on the line except
+for the current one will be excluded from the possible completions\&.
+.RS
+.PP
+The values `\fBcurrent\fP\&' and `\fBcurrent\-shown\fP' are a bit like the
+opposite of the \fBaccept\-exact\fP style:  only strings with
+missing characters will be completed\&.
+.PP
+Note that you almost certainly don\&'t want to set this to `true' or
+`\fBother\fP\&' for a general
+context such as `\fB:completion:*\fP\&'\&.  This is because it would disallow
+completion of, for example, options multiple times even if the command
+in question accepts the option more than once\&.
+.RE
+.TP
+\fBignore\-parents\fP
+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:
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fBparent\fP
+The name of any directory whose path is already contained in the word on
+the line is ignored\&.  For example, when completing after \fBfoo/\&.\&./\fP, the
+directory \fBfoo\fP will not be considered a valid completion\&.
+.TP
+\fBpwd\fP
+The name of the current working directory will not be completed; hence,
+for example, completion after \fB\&.\&./\fP will not use the name of the current
+directory\&.
+.PP
+In addition, the value may include one or both of:
+.PP
+.PD 0
+.TP
+.PD
+\fB\&.\&.\fP
+Ignore the specified directories only when the word on the line contains
+the substring `\fB\&.\&./\fP\&'\&.
+.TP
+\fBdirectory\fP
+Ignore the specified directories only when names of directories are
+completed, not when completing names of files\&.
+.PP
+Excluded values act in a similar fashion to values of the
+\fBignored\-patterns\fP style, so they can be restored to consideration by
+the \fB_ignored\fP completer\&.
+.RE
+.TP
+\fBextra\-verbose\fP
+If set, the completion listing is more verbose at the cost of
+a probable decrease in completion speed\&.  Completion performance
+will suffer if this style is set to `true\&'\&.
+.TP
+\fBignored\-patterns\fP
+A list of patterns; any trial completion matching one of the patterns
+will be excluded from consideration\&.  The
+\fB_ignored\fP completer can appear in the list of completers to
+restore the ignored matches\&.  This is a more configurable
+version of the shell parameter \fB$fignore\fP\&.
+.RS
+.PP
+Note that the
+\fBEXTENDED_GLOB\fP option is set during the execution of completion
+functions, so the characters `\fB#\fP\&', `\fB~\fP' and `\fB^\fP' have special
+meanings in the patterns\&.
+.RE
+.TP
+\fBinsert\fP
+This style is used by the \fB_all_matches\fP completer to decide whether to
+insert the list of all matches unconditionally instead of adding the
+list as another match\&.
+.TP
+\fBinsert\-ids\fP
+When completing process IDs, for example as arguments to the \fBkill\fP and
+\fBwait\fP 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 `\fBmenu\fP\&') the name will be converted
+immediately to a set of possible IDs, and menu completion will be started
+to cycle through them\&.
+.RS
+.PP
+If the value of the style is `\fBsingle\fP\&',
+the shell will wait until the user has typed enough to make the command
+unique before converting the name to an ID; attempts at completion will
+be unsuccessful 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\&.
+.RE
+.TP
+\fBinsert\-tab\fP
+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 it is set to `false\&', completion will be done even there\&.
+.RS
+.PP
+The value may also contain the substrings `\fBpending\fP\&' or
+`\fBpending=\fP\fIval\fP\&'\&.  In this case, the typed character will be
+inserted instead of starting completion when there is unprocessed input
+pending\&.  If a \fIval\fP 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 \fB$PENDING\fP special parameter from the
+\fBzsh/zle\fP module being set properly which is not guaranteed on all
+platforms\&.
+.PP
+The default value of this style is `true\&' except for completion within
+\fBvared\fP builtin command where it is `false\&'\&.
+.RE
+.TP
+\fBinsert\-unambiguous\fP
+This is used by the \fB_match\fP and \fB_approximate\fP completers\&.
+These completers are often used with menu completion since the word typed
+may bear little resemblance to the final completion\&.
+However, if this 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\&.
+.RS
+.PP
+In the case of the \fB_approximate\fP completer, the completer
+field in the context will already have been set to one of
+\fBcorrect\-\fP\fInum\fP or \fBapproximate\-\fP\fInum\fP, where \fInum\fP is the
+number of errors that were accepted\&.
+.PP
+In the case of the \fB_match\fP completer, the style may also be set to
+the string `\fBpattern\fP\&'\&.  Then the pattern on the line is left
+unchanged if it does not match unambiguously\&.
+.RE
+.TP
+\fBgain\-privileges\fP
+If set to \fBtrue\fP, this style enables the use of commands like \fBsudo\fP
+or \fBdoas\fP to gain extra privileges when retrieving information for
+completion\&. This is only done when a command such as \fBsudo\fP appears on
+the command\-line\&. To force the use of, e\&.g\&. \fBsudo\fP or to override any
+prefix that might be added due to \fBgain\-privileges\fP, the \fBcommand\fP
+style can be used with a value that begins with a hyphen\&.
+.TP
+\fBkeep\-prefix\fP
+This style is used by the \fB_expand\fP completer\&.  If it is `true\&', the
+completer will try to keep a prefix containing a tilde or parameter
+expansion\&.  Hence, for example, the string `\fB~/f*\fP\&' would be expanded to
+`\fB~/foo\fP\&' instead of `\fB/home/user/foo\fP'\&.  If the style is set to
+`\fBchanged\fP\&' (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 forces the prefix to be
+expanded unconditionally\&.
+.RS
+.PP
+The behaviour of \fB_expand\fP when this style is `true\&' is to cause \fB_expand\fP
+to give up when a single expansion with the restored prefix is the same
+as the original; hence any remaining completers may be called\&.
+.RE
+.TP
+\fBlast\-prompt\fP
+This is a more flexible form of the \fBALWAYS_LAST_PROMPT\fP 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
+\fBdefault\fP 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 \fBALWAYS_LAST_PROMPT\fP option this is independent of the
+numeric argument\&.
+.TP
+\fBknown\-hosts\-files\fP
+This style should contain a list of files to search for host names and
+(if the \fBuse\-ip\fP style is set) IP addresses in a format compatible with
+ssh \fBknown_hosts\fP files\&.  If it is not set, the files
+\fB/etc/ssh/ssh_known_hosts\fP and \fB~/\&.ssh/known_hosts\fP are used\&.
+.TP
+\fBlist\fP
+This style is used by the \fB_history_complete_word\fP bindable command\&.
+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 \fBAUTO_LIST\fP\&.  The context
+always starts with `\fB:completion:history\-words\fP\&'\&.
+.TP
+\fBlist\-colors\fP
+If the \fBzsh/complist\fP module is loaded, this style can be used to set
+color specifications\&.  This mechanism replaces the use of the
+\fBZLS_COLORS\fP and \fBZLS_COLOURS\fP parameters described in
+the section `The zsh/complist Module\&' in \fIzshmodules\fP(1), but the syntax is the same\&.
+.RS
+.PP
+If this style is set for the \fBdefault\fP 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 \fBgroup\-name\fP
+style must be set to an empty string\&.  
+.PP
+In addition to setting styles for specific tags, it is also possible to
+use group names specified explicitly by the \fBgroup\-name\fP tag together
+with the `\fB(group)\fP\&' syntax allowed by the \fBZLS_COLORS\fP and
+\fBZLS_COLOURS\fP parameters and simply using the \fBdefault\fP tag\&.
+.PP
+It is possible to use any color specifications already set up for the GNU
+version of the \fBls\fP command:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*:default' list\-colors \e 
+       ${(s\&.:\&.)LS_COLORS}\fP
+.fi
+.RE
+.PP
+The default colors are the same as for the GNU \fBls\fP command and can be
+obtained by setting the style to an empty string (i\&.e\&. \fB\&''\fP)\&.
+.RE
+.TP
+\fBlist\-dirs\-first\fP
+This is used by file completion\&.  If set, directories to be completed
+are listed separately from and before completion for other files,
+regardless of tag ordering\&.  In addition, the tag \fBother\-files\fP
+is used in place of \fBall\-files\fP for the remaining files, to indicate
+that no directories are presented with that tag\&.
+.TP
+\fBlist\-grouped\fP
+If this style is `true\&' (the default), the completion system will try to
+make certain completion listings more compact by grouping matches\&.
+For example, options for commands that have the same description (shown
+when the \fBverbose\fP style is set to `true\&') will appear as a single
+entry\&.  However, menu selection can be used to cycle through all the
+matches\&.
+.TP
+\fBlist\-packed\fP
+This is tested for each tag valid in the current context as well as the
+\fBdefault\fP tag\&.  If it is set to `true\&', the corresponding matches
+appear in listings as if the \fBLIST_PACKED\fP option were set\&.  If it is
+set to `false\&', they are listed normally\&.
+.TP
+\fBlist\-prompt\fP
+If this style is set for the \fBdefault\fP tag,
+completion lists that don\&'t fit on the screen can be scrolled (see
+the description of the \fBzsh/complist\fP module in \fIzshmodules\fP(1))\&.  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\&.
+.RS
+.PP
+The value may contain the escape sequences:
+`\fB%l\fP\&' or `\fB%L\fP', which will be replaced by the number of the last line
+displayed and the total number of lines; `\fB%m\fP\&' or `\fB%M\fP', 
+the number of the  last match shown and the total number of
+matches; and `\fB%p\fP\&' and `\fB%P\fP', `\fBTop\fP'
+when at the beginning of the list, `\fBBottom\fP\&' when at the end and 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 `\fB%S\fP\&', `\fB%s\fP', `\fB%B\fP', `\fB%b\fP', `\fB%U\fP',
+`\fB%u\fP\&' for entering and leaving the display modes
+standout, bold and underline, and `\fB%F\fP\&', `\fB%f\fP', `\fB%K\fP', `\fB%k\fP' for
+changing the foreground background colour, are also available, as is the form
+`\fB%{\fP\&.\&.\&.\fB%}\fP\&' for enclosing escape sequences which display with zero
+(or, with a numeric argument, some other) width\&.
+.PP
+After deleting this prompt the variable \fBLISTPROMPT\fP should be unset for
+the removal to take effect\&.
+.RE
+.TP
+\fBlist\-rows\-first\fP
+This style is tested in the same way as the \fBlist\-packed\fP style and
+determines whether matches are to be listed in a rows\-first fashion as
+if the \fBLIST_ROWS_FIRST\fP option were set\&.
+.TP
+\fBlist\-suffixes\fP
+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\&.
+.TP
+\fBlist\-separator\fP
+The value of this style is used in completion listing to separate the
+string to complete from a description when possible (e\&.g\&. when
+completing options)\&.  It defaults to `\fB\-\fP\fB\-\fP\&' (two hyphens)\&.
+.TP
+\fBlocal\fP
+This is for use with functions that complete URLs for which the
+corresponding files are available directly from the file 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\&.
+.RS
+.PP
+For example:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' local toast \e 
+    /var/http/public/toast public_html\fP
+.fi
+.RE
+.PP
+Completion after `\fBhttp://toast/stuff/\fP\&' will look for files in the
+directory \fB/var/http/public/toast/stuff\fP,  while completion after
+`\fBhttp://toast/~yousir/\fP\&' will look for files in the directory
+\fB~yousir/public_html\fP\&.
+.RE
+.TP
+\fBmail\-directory\fP
+If set, zsh will assume that mailbox files can be found in
+the directory specified\&.  It defaults to `\fB~/Mail\fP\&'\&.
+.TP
+\fBmatch\-original\fP
+This is used by the \fB_match\fP completer\&.  If it is set to
+\fBonly\fP, \fB_match\fP will try to generate matches without inserting a
+`\fB*\fP\&' at the cursor position\&.  If set to any other non\-empty value,
+it will first try to generate matches without inserting the `\fB*\fP\&'
+and if that yields no matches, it will try again with the `\fB*\fP\&'
+inserted\&.  If it is unset or set to the empty string, matching will
+only be performed with the `\fB*\fP\&' inserted\&.
+.TP
+\fBmatcher\fP
+This style is tested separately for each tag valid in the current
+context\&.  Its value is placed before any match specifications given by the
+\fBmatcher\-list\fP style so can override them via the use of an \fBx:\fP
+specification\&.  The value should be in the form described in
+the section `Completion Matching Control\&' in \fIzshcompwid\fP(1)\&.  For examples of this, see the description of the \fBtag\-order\fP style\&.
+.RS
+.PP
+For notes comparing the use of this and the \fBmatcher\-list\fP style, see
+under the description of the \fBtag\-order\fP style\&.
+.RE
+.TP
+\fBmatcher\-list\fP
+This style can be set to a list of match specifications that are to
+be applied everywhere\&. Match specifications are described in
+the section `Completion Matching Control\&' in \fIzshcompwid\fP(1)\&.
+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:
+.RS
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' matcher\-list '' 'm:{a\-zA\-Z}={A\-Za\-z}'\fP
+.fi
+.RE
+.PP
+By default each specification replaces the previous one; however, if a
+specification is prefixed with \fB+\fP, it is added to the existing list\&.
+Hence it is possible to create increasingly general specifications
+without repetition:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' matcher\-list \e 
+       \&'' '+m:{a\-z}={A\-Z}' '+m:{A\-Z}={a\-z}'\fP
+.fi
+.RE
+.PP
+It is possible to create match specifications valid for particular
+completers by using the third field of the context\&.  This applies only
+to completers that override the global matcher\-list, which as of this
+writing includes only \fB_prefix\fP and \fB_ignored\fP\&.  For example, to
+use the completers \fB_complete\fP and \fB_prefix\fP but allow
+case\-insensitive completion only with \fB_complete\fP:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' completer _complete _prefix
+zstyle \&':completion:*:complete:*:*:*' matcher\-list \e 
+       \&'' 'm:{a\-zA\-Z}={A\-Za\-z}'\fP
+.fi
+.RE
+.PP
+User\-defined names, as explained for the \fBcompleter\fP 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:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' completer \e 
+    _complete _correct _complete:foo
+zstyle \&':completion:*:complete:*:*:*' matcher\-list \e 
+    \&'' 'm:{a\-zA\-Z}={A\-Za\-z}'
+zstyle \&':completion:*:foo:*:*:*' matcher\-list \e 
+    \&'m:{a\-zA\-Z}={A\-Za\-z} r:|[\-_\&./]=* r:|=*'\fP
+.fi
+.RE
+.PP
+If the style is unset in any context no match specification is applied\&.
+Note also that some completers such as \fB_correct\fP and \fB_approximate\fP
+do not use the match specifications at all, though these completers will
+only ever be called once even if the \fBmatcher\-list\fP contains more than
+one element\&.
+.PP
+Where multiple specifications are useful, note that the \fIentire\fP
+completion is done for each element of \fBmatcher\-list\fP, which can
+quickly reduce the shell\&'s performance\&.  As a rough rule of thumb,
+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\&.
+.PP
+If there is no current matcher or it is empty, and the option
+\fBNO_CASE_GLOB\fP is in effect, the matching for files is performed
+case\-insensitively in any case\&.  However, any matcher must
+explicitly specify case\-insensitive matching if that is required\&.
+.PP
+For notes comparing the use of this and the \fBmatcher\fP style, see
+under the description of the \fBtag\-order\fP style\&.
+.RE
+.TP
+\fBmax\-errors\fP
+This is used by the \fB_approximate\fP and \fB_correct\fP completer functions
+to determine the maximum number of errors to allow\&.  The completer will try
+to generate completions by first allowing one error, then two errors, and
+so on, until either a match or matches were found or the maximum number of
+errors given by this style has been reached\&.
+.RS
+.PP
+If the value for this style contains the string `\fBnumeric\fP\&', the 
+completer function will take any numeric argument as the
+maximum number of errors allowed\&. For example, with
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*:approximate:::' max\-errors 2 numeric\fP
+.fi
+.RE
+.PP
+two errors are allowed if no numeric argument is given, but with
+a numeric argument of six (as in `\fBESC\-6 TAB\fP\&'), up to six
+errors are accepted\&.  Hence with a value of `\fB0 numeric\fP\&', no correcting
+completion will be attempted unless a numeric argument is given\&.
+.PP
+If the value contains the string `\fBnot\-numeric\fP\&', the completer
+will \fInot\fP try to generate corrected
+completions when given a numeric argument, so in this case the number given
+should be greater than zero\&.  For example, `\fB2 not\-numeric\fP\&' specifies that
+correcting completion with two errors will usually be performed, but if a
+numeric argument is given, correcting completion will not be
+performed\&.
+.PP
+The default value for this style is `\fB2 numeric\fP\&'\&.
+.RE
+.TP
+\fBmax\-matches\-width\fP
+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 \fBverbose\fP 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\&.
+.RS
+.PP
+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\&.
+.RE
+.TP
+\fBmenu\fP
+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 `\fBdefault\fP\&' tag\&.
+.RS
+.PP
+If none of the values found in this way is `true\&' but at least
+one is set to `\fBauto\fP\&', the shell behaves as if the \fBAUTO_MENU\fP
+option is set\&.
+.PP
+If one of the values is explicitly set to `false\&', menu
+completion will be explicitly turned off, overriding the
+\fBMENU_COMPLETE\fP option and other settings\&.
+.PP
+In the form `\fByes=\fP\fInum\fP\&', where `\fByes\fP' may be any of the
+`true\&' values (`\fByes\fP', `\fBtrue\fP', `\fBon\fP' and `\fB1\fP'),
+menu completion will be turned on if there are at least \fInum\fP matches\&.
+In the form `\fByes=long\fP\&', menu completion will be turned on
+if the list does not fit on 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 `\fByes=long\-list\fP\&'
+(Typically, the value `\fBselect=long\-list\fP\&' described later is more
+useful as it provides control over scrolling\&.)
+.PP
+Similarly, with any of the `false\&' values (as in `\fBno=10\fP'), menu
+completion will \fInot\fP be used if there are \fInum\fP or more matches\&.  
+.PP
+The value of this widget also controls menu selection, as implemented by
+the \fBzsh/complist\fP module\&.  The following values may appear either
+alongside or instead of the values above\&.
+.PP
+If the value contains the string `\fBselect\fP\&', menu selection
+will be started unconditionally\&.
+.PP
+In the form `\fBselect=\fP\fInum\fP\&', menu selection will only be started if
+there are at least \fInum\fP matches\&.  If the values for more than one
+tag provide a number, the smallest number is taken\&.
+.PP
+Menu selection can be turned off explicitly by defining a value
+containing the string`\fBno\-select\fP\&'\&.
+.PP
+It is also possible to start menu selection only if the list of
+matches does not fit on the screen by using the value
+`\fBselect=long\fP\&'\&.  To start menu selection even if the current widget
+only performs listing, use the value `\fBselect=long\-list\fP\&'\&.
+.PP
+To turn on menu completion or menu selection when there are a certain
+number of matches \fIor\fP the list of matches does not fit on the
+screen, both of `\fByes=\fP\&' and `\fBselect=\fP' may be given twice, once
+with a number and once with `\fBlong\fP\&' or `\fBlong\-list\fP'\&.
+.PP
+Finally, it is possible to activate two special modes of menu selection\&.
+The word `\fBinteractive\fP\&' in the value causes interactive mode
+to be entered immediately when menu selection is started; see
+the description of the \fBzsh/complist\fP module in \fIzshmodules\fP(1)
+for a description of interactive mode\&.  Including the string
+`\fBsearch\fP\&' does the same for incremental search mode\&.  To select backward
+incremental search, include the string `\fBsearch\-backward\fP\&'\&.
+.RE
+.TP
+\fBmuttrc\fP
+If set, gives the location of the mutt configuration file\&.  It defaults
+to `\fB~/\&.muttrc\fP\&'\&.
+.TP
+\fBnumbers\fP
+This is used with the \fBjobs\fP tag\&.  If it is `true\&', the shell 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 `\fB1\fP\&', strings will
+only be used if all jobs differ in the first word on their command lines\&.
+.TP
+\fBold\-list\fP
+This is used by the \fB_oldlist\fP completer\&.  If it is set to `\fBalways\fP\&',
+then standard widgets which perform listing will retain the current list of
+matches, however they were generated; this can be turned off explicitly
+with the value `\fBnever\fP\&', giving the behaviour without the \fB_oldlist\fP
+completer\&.  If the style is unset, or any other value, then the existing
+list of completions is displayed if it is not already; otherwise, the
+standard completion list is generated; this is the default behaviour of
+\fB_oldlist\fP\&.  However, if there is an old list and this style contains
+the name of the completer function that generated the list, then the
+old list will be used even if it was generated by a widget which does
+not do listing\&.
+.RS
+.PP
+For example, suppose you type \fB^Xc\fP to use the \fB_correct_word\fP
+widget, which generates a list of corrections for the word under the
+cursor\&.  Usually, typing \fB^D\fP would generate a standard list of
+completions for the word on the command line, and show that\&.  With
+\fB_oldlist\fP, it will instead show the list of corrections already
+generated\&.
+.PP
+As another example consider the \fB_match\fP completer: with the
+\fBinsert\-unambiguous\fP style set to `true\&' it inserts only a common prefix
+string, if there is any\&.  However, this may remove parts of the original
+pattern, so that further completion could produce more matches than on the
+first attempt\&.  By using the \fB_oldlist\fP completer and setting this style
+to \fB_match\fP, the list of matches generated on the first attempt will be
+used again\&.
+.RE
+.TP
+\fBold\-matches\fP
+This is used by the \fB_all_matches\fP completer to decide if an old
+list of matches should be used if one exists\&.  This is selected by one of
+the `true\&' values or by the string `\fBonly\fP'\&.  If
+the value is `\fBonly\fP\&', \fB_all_matches\fP will only use an old list
+and won\&'t have any effect on the list of matches currently being
+generated\&.
+.RS
+.PP
+If this style is set it is generally unwise to call the \fB_all_matches\fP
+completer unconditionally\&.  One possible use is for either this style or
+the \fBcompleter\fP style to be defined with the \fB\-e\fP option to
+\fBzstyle\fP to make the style conditional\&.
+.RE
+.TP
+\fBold\-menu\fP
+This is used by the \fB_oldlist\fP completer\&.  It controls how menu
+completion behaves when a completion has already been inserted and the
+user types a standard completion key such as \fBTAB\fP\&.  The default
+behaviour of \fB_oldlist\fP 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 \fB_oldlist\fP completer\&.
+.RS
+.PP
+For example, suppose you type \fB^Xc\fP to generate a list of corrections,
+and menu completion is started in one of the usual ways\&.  Usually, or with
+this style set to `false\&', typing \fBTAB\fP at this point would start
+trying to complete the line as it now appears\&.  With \fB_oldlist\fP, it
+instead continues to cycle through the list of corrections\&.
+.RE
+.TP
+\fBoriginal\fP
+This is used by the \fB_approximate\fP and \fB_correct\fP
+completers to decide if the original string should be added as
+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 the style will be examined with the
+completer field in the context name set to \fBcorrect\-\fP\fInum\fP or
+\fBapproximate\-\fP\fInum\fP, where \fInum\fP is the number of errors that
+were accepted\&.
+.TP
+\fBpackageset\fP
+This style is used when completing arguments of the Debian `\fBdpkg\fP\&'
+program\&.  It contains an override for the default package set
+for a given context\&.  For example,
+.RS
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*:complete:dpkg:option\-\-status\-1:*' \e 
+               packageset avail\fP
+.fi
+.RE
+.PP
+causes available packages, rather than only installed packages,
+to be completed for `\fBdpkg \-\fP\fB\-status\fP\&'\&.
+.RE
+.TP
+\fBpath\fP
+The function that completes color names uses this style with the 
+\fBcolors\fP tag\&.  The value should be the pathname of a file
+containing color names in the format of an X11 \fBrgb\&.txt\fP file\&.  If
+the style is not set but this file is found in one of various standard
+locations it will be used as the default\&.
+.TP
+\fBpath\-completion\fP
+This is used by filename completion\&.  By default, filename completion
+examines all components of a path to see if there are completions of
+that component\&.  For example, \fB/u/b/z\fP can be completed to
+\fB/usr/bin/zsh\fP\&.  Explicitly setting this style to `false\&' inhibits this
+behaviour for path components up to the \fB/\fP before the cursor; this
+overrides the setting of \fBaccept\-exact\-dirs\fP\&.
+.RS
+.PP
+Even with the style set to `false\&', it is still possible to complete
+multiple paths by setting the option \fBCOMPLETE_IN_WORD\fP and moving the
+cursor back to the first component in the path to be completed\&.  For
+example, \fB/u/b/z\fP can be completed to \fB/usr/bin/zsh\fP if the cursor is
+after the \fB/u\fP\&.
+.RE
+.TP
+\fBpine\-directory\fP
+If set, specifies the directory containing PINE mailbox files\&.  There
+is no default, since recursively searching this directory is inconvenient
+for anyone who doesn\&'t use PINE\&.
+.TP
+\fBports\fP
+A list of Internet service names (network ports) to complete\&.  If this is
+not set, service names are taken from the file `\fB/etc/services\fP\&'\&.
+.TP
+\fBprefix\-hidden\fP
+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\&.
+.RS
+.PP
+The default value for this style is `false\&'\&.
+.RE
+.TP
+\fBprefix\-needed\fP
+This style is also relevant for matches with a common prefix\&.  If it is
+set to `true\&' this common prefix must be typed by the user to generate
+the matches\&.
+.RS
+.PP
+The style is applicable to the \fBoptions\fP, \fBsignals\fP, \fBjobs\fP,
+\fBfunctions\fP, and \fBparameters\fP completion tags\&.
+.PP
+For command options, this means that the initial `\fB\-\fP\&', `\fB+\fP', or
+`\fB\-\fP\fB\-\fP\&' must be typed explicitly before option names will be
+completed\&.
+.PP
+For signals, an initial `\fB\-\fP\&' is required before signal names will
+be completed\&.
+.PP
+For jobs, an initial `\fB%\fP\&' is required before job names will be
+completed\&.
+.PP
+For function and parameter names, an initial `\fB_\fP\&' or `\fB\&.\fP' is
+required before function or parameter names starting with those
+characters will be completed\&.
+.PP
+The default value for this style is `false\&' for \fBfunction\fP and
+\fBparameter\fP completions, and  `true\&' otherwise\&.
+.RE
+.TP
+\fBpreserve\-prefix\fP
+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 `\fB//\fP\&' (double slash) has a special meaning; setting
+this style to the string `\fB//\fP\&' will preserve it\&.  As another example,
+setting this style to `\fB?:/\fP\&' under Cygwin would allow completion
+after `\fBa:/\&.\&.\&.\fP\&' and so on\&.
+.TP
+\fBrange\fP
+This is used by the \fB_history\fP completer and the
+\fB_history_complete_word\fP bindable command to decide which words
+should be completed\&.  
+.RS
+.PP
+If it is a single number, only the last \fIN\fP words from the history
+will be completed\&.
+.PP
+If it is a range of the form `\fImax\fP\fB:\fP\fIslice\fP\&',
+the last \fIslice\fP words will be completed; then if that
+yields no matches, the \fIslice\fP words before those will be tried and 
+so on\&.  This process stops either when at least one match has been
+found, or \fImax\fP words have been tried\&.
+.PP
+The default is to complete all words from the history at once\&.
+.RE
+.TP
+\fBrecursive\-files\fP
+If this style is set, its value is an array of patterns to be
+tested against `\fB$PWD/\fP\&': note the trailing slash, which allows
+directories in the pattern to be delimited unambiguously by including
+slashes on both sides\&.  If an ordinary file completion fails
+and the word on the command line does not yet have a directory part to its
+name, the style is retrieved using the same tag as for the completion
+just attempted, then the elements tested against \fB$PWD/\fP in turn\&.
+If one matches, then the shell reattempts completion by prepending the word
+on the command line with each directory in the expansion of \fB**/*(/)\fP
+in turn\&.  Typically the elements of the style will be set to restrict
+the number of directories beneath the current one to a manageable
+number, for example `\fB*/\&.git/*\fP\&'\&.
+.RS
+.PP
+For example,
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' recursive\-files '*/zsh/*'\fP
+.fi
+.RE
+.PP
+If the current directory is \fB/home/pws/zsh/Src\fP, then
+\fBzle_tr\fP\fITAB\fP can be completed to \fBZle/zle_tricky\&.c\fP\&.
+.RE
+.TP
+\fBregular\fP
+This style is used by the \fB_expand_alias\fP 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\&.   If it is set to `\fBalways\fP\&',
+regular aliases will be expanded even if not in command position\&.
+.TP
+\fBrehash\fP
+If this is set when completing external commands, the internal
+list (hash) of commands will be updated for each search by issuing
+the \fBrehash\fP command\&.  There is a speed penalty for this which
+is only likely to be noticeable when directories in the path have
+slow file access\&.
+.TP
+\fBremote\-access\fP
+If set to `false\&', certain commands will be prevented from making
+Internet connections to retrieve remote information\&.  This includes the
+completion for the \fBCVS\fP command\&.
+.RS
+.PP
+It is not always possible to know if connections are in fact to a remote
+site, so some may be prevented unnecessarily\&.
+.RE
+.TP
+\fBremove\-all\-dups\fP
+The \fB_history_complete_word\fP bindable command and the \fB_history\fP
+completer use this to decide if all duplicate matches should be
+removed, rather than just consecutive duplicates\&.
+.TP
+\fBselect\-prompt\fP
+If this is set for the \fBdefault\fP tag, its
+value will be displayed during menu selection (see the \fBmenu\fP style
+above) when the completion list does not fit on the screen as a
+whole\&.  The same escapes as for the \fBlist\-prompt\fP style are
+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\&.
+.TP
+\fBselect\-scroll\fP
+This style is tested for the \fBdefault\fP tag and determines how a
+completion list is scrolled during a menu selection (see the \fBmenu\fP
+style above) when the completion list does not fit on the screen as a
+whole\&.  If the value is `\fB0\fP\&' (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\&.
+.TP
+\fBseparate\-sections\fP
+This style is used with the \fBmanuals\fP tag when completing names of
+manual pages\&.  If it is `true\&', entries for different sections are
+added separately using tag names of the form `\fBmanual\&.\fP\fIX\fP\&',
+where \fIX\fP is the section number\&.  When the \fBgroup\-name\fP style is
+also in effect, pages from different sections will appear separately\&.
+This style is also used similarly with the \fBwords\fP style when
+completing words for the dict command\&. It allows words from different
+dictionary databases to be added separately\&.
+The default for this style is `false\&'\&.
+.TP
+\fBshow\-ambiguity\fP
+If the \fBzsh/complist\fP module is loaded, this style can be used to
+highlight the first ambiguous character in completion lists\&. The
+value is either a color indication such as those supported by the
+\fBlist\-colors\fP style or, with a value of `true\&', a default of
+underlining is selected\&. The highlighting is only applied if the
+completion display strings correspond to the actual matches\&.
+.TP
+\fBshow\-completer\fP
+Tested whenever a new completer is tried\&.  If it is `true\&', the completion
+system outputs a progress message in the listing area showing what
+completer is being tried\&.  The message will be overwritten by any output
+when completions are found and is removed after completion is finished\&.
+.TP
+\fBsingle\-ignored\fP
+This is used by the \fB_ignored\fP completer when there is only one match\&.
+If its value is `\fBshow\fP\&', the single match will be
+displayed but not inserted\&.  If the value is `\fBmenu\fP\&', then the single
+match and the original string are both added as matches and menu completion
+is started, making it easy to select either of them\&.
+.TP
+\fBsort\fP
+This allows the standard ordering of matches to be overridden\&.
+.RS
+.PP
+If its value is `\fBtrue\fP\&' or `\fBfalse\fP', sorting is enabled or disabled\&.
+Additionally the values associated with the `\fB\-o\fP\&' option to \fBcompadd\fP can
+also be listed: \fBmatch\fP, \fBnosort\fP, \fBnumeric\fP, \fBreverse\fP\&.  If it is not
+set for the context, the standard behaviour of the calling widget is used\&.
+.PP
+The style is tested first against the full context including the tag, and
+if that fails to produce a value against the context without the tag\&.
+.PP
+In many cases where a calling widget explicitly selects a particular ordering
+in lieu of the default, a value of `\fBtrue\fP\&' is not honoured\&.  An example of
+where this is not the case is for command history where the default of sorting
+matches chronologically may be overridden by setting the style to `true\&'\&.
+.PP
+In the \fB_expand\fP completer, if it is set to
+`true\&', the expansions generated will always be sorted\&.  If it is set
+to `\fBmenu\fP\&', then the expansions are only sorted when they are offered 
+as single strings but not in the string containing all possible
+expansions\&.
+.RE
+.TP
+\fBspecial\-dirs\fP
+Normally, the completion code will not produce the directory names
+`\fB\&.\fP\&' and `\fB\&.\&.\fP' as possible completions\&.  If this style is set to
+`true\&', it will add both `\fB\&.\fP' and `\fB\&.\&.\fP' as possible completions;
+if it is set to `\fB\&.\&.\fP\&', only `\fB\&.\&.\fP' will be added\&.
+.RS
+.PP
+The following example sets \fBspecial\-dirs\fP to `\fB\&.\&.\fP\&' when the
+current prefix is empty, is a single `\fB\&.\fP\&', or consists only of a path
+beginning with `\fB\&.\&./\fP\&'\&.  Otherwise the value is `false'\&.
+.PP
+.RS
+.nf
+\fBzstyle \-e \&':completion:*' special\-dirs \e 
+   \&'[[ $PREFIX = (\&.\&./)#(|\&.|\&.\&.) ]] && reply=(\&.\&.)'\fP
+.fi
+.RE
+.RE
+.TP
+\fBsqueeze\-slashes\fP
+If set to `true\&', sequences of slashes in filename paths (for example in
+`\fBfoo//bar\fP\&') 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 `\fB*\fP\&' between the slashes\&.
+.TP
+\fBstop\fP
+If set to `true\&', the \fB_history_complete_word\fP bindable
+command will stop once when reaching the beginning or end of the
+history\&.  Invoking \fB_history_complete_word\fP will then wrap around to 
+the opposite end of the history\&.  If this style is set to `false\&' (the 
+default), \fB_history_complete_word\fP will loop immediately as in a
+menu completion\&.
+.TP
+\fBstrip\-comments\fP
+If set to `true\&', this style causes non\-essential comment text to be
+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 \fIuser@host\fP form\&.
+.TP
+\fBsubst\-globs\-only\fP
+This is used by the \fB_expand\fP completer\&.  If it is set to `true\&',
+the expansion will only be used if it resulted from globbing; hence,
+if expansions resulted from the use of the \fBsubstitute\fP style
+described below, but these were not further changed by globbing, the
+expansions will be rejected\&.
+.RS
+.PP
+The default for this style is `false\&'\&.
+.RE
+.TP
+\fBsubstitute\fP
+This boolean style controls whether the \fB_expand\fP completer will
+first try to expand all substitutions in the string (such as
+`\fB$(\fP\fI\&.\&.\&.\fP\fB)\fP\&' and `\fB${\fP\fI\&.\&.\&.\fP\fB}\fP')\&.
+.RS
+.PP
+The default is `true\&'\&.
+.RE
+.TP
+\fBsuffix\fP
+This is used by the \fB_expand\fP 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 `\fB~foo\fP\&' or `\fB$foo\fP' rather than `\fB~foo/\fP' or
+`\fB$foo/bar\fP\&', unless that suffix itself contains characters eligible
+for expansion\&.  The default for this style is `true\&'\&.
+.TP
+\fBtag\-order\fP
+This provides a mechanism for sorting how the tags available in a
+particular context will be used\&.
+.RS
+.PP
+The values for the style are sets of space\-separated lists of tags\&.
+The tags in each value will be tried at the same time; if no match is
+found, the next value is used\&.  (See the \fBfile\-patterns\fP style for
+an exception to this behavior\&.)
+.PP
+For example:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*:complete:\-command\-:*:*' tag\-order \e 
+    \&'commands functions'\fP
+.fi
+.RE
+.PP
+specifies that completion in command position first offers
+external commands and shell functions\&.  Remaining tags will be tried if
+no completions are found\&.
+.PP
+In addition to tag names, each string in the value may take one of the
+following forms:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-\fP
+If any value consists of only a hyphen,
+then \fIonly\fP the tags specified in the other values are
+generated\&.  Normally all tags not explicitly selected are tried last
+if the specified tags fail to generate any matches\&.  This means 
+that a single value consisting only of a single hyphen
+turns off completion\&.
+.TP
+\fB!\fP \fItags\fP\&.\&.\&.
+A string starting with an exclamation mark
+specifies names of tags that are \fInot\fP to be used\&.  The effect is
+the same as if all other possible tags for the context had been
+listed\&.
+.TP
+\fItag\fP\fB:\fP\fIlabel\fP \&.\&.\&.
+Here, \fItag\fP is one of the standard tags and \fIlabel\fP is an
+arbitrary name\&.  Matches are generated as normal but the name \fIlabel\fP
+is used in contexts instead of \fItag\fP\&.  This is not useful in words
+starting with \fB!\fP\&.
+.RS
+.PP
+If the \fIlabel\fP starts with a hyphen, the \fItag\fP is prepended to the
+\fIlabel\fP 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
+example\&.
+.RE
+.TP
+\fItag\fP\fB:\fP\fIlabel\fP\fB:\fP\fIdescription\fP
+As before, but \fBdescription\fP will replace the `\fB%d\fP\&' in
+the value of the \fBformat\fP style instead of the default description
+supplied by the completion function\&.  Spaces in the description must
+be quoted with a backslash\&.  A `\fB%d\fP\&' appearing
+in \fIdescription\fP is replaced with the description given by the
+completion function\&.
+.PP
+In any of the forms above the tag may be a pattern or several
+patterns in the form `\fB{\fP\fIpat1\fP\fB,\fP\fIpat2\&.\&.\&.\fP\fB}\fP\&'\&.  In this
+case all matching tags will be used except 
+for any given explicitly in the same string\&.
+.PP
+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:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*:*:\-command\-:*:*' tag\-order \e 
+    \&'functions:\-non\-comp *' functions
+zstyle \&':completion:*:functions\-non\-comp' \e 
+    ignored\-patterns \&'_*'\fP
+.fi
+.RE
+.PP
+On the first attempt, all tags will be offered but the \fBfunctions\fP tag
+will be replaced by \fBfunctions\-non\-comp\fP\&.  The \fBignored\-patterns\fP style 
+is set for this tag to exclude functions starting with an underscore\&.
+If there are no matches, the second value of the
+\fBtag\-order\fP style is used which completes functions using the default
+tag, this time presumably including all function names\&.
+.PP
+The matches for one tag can be split into different groups\&.  For example:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' tag\-order \e 
+    \&'options:\-long:long\e options
+     options:\-short:short\e options
+     options:\-single\-letter:single\e letter\e options\&'
+zstyle \&':completion:*:options\-long' \e 
+     ignored\-patterns \&'[\-+](|\-|[^\-]*)'
+zstyle \&':completion:*:options\-short' \e 
+     ignored\-patterns \&'\-\-*' '[\-+]?'
+zstyle \&':completion:*:options\-single\-letter' \e 
+     ignored\-patterns \&'???*'\fP
+.fi
+.RE
+.PP
+With the \fBgroup\-names\fP style set, options beginning with
+`\fB\-\fP\fB\-\fP\&', options beginning with a single `\fB\-\fP' or `\fB+\fP' but
+containing multiple characters, and single\-letter options will be
+displayed in separate groups with different descriptions\&.
+.PP
+Another use of patterns is to
+try multiple match specifications one after another\&.  The
+\fBmatcher\-list\fP style offers something similar, but it is tested very
+early in the completion system and hence can\&'t be set for single
+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 \fBfoo\fP:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*:*:foo:*:*' tag\-order '*' '*:\-case'
+zstyle \&':completion:*\-case' matcher 'm:{a\-z}={A\-Z}'\fP
+.fi
+.RE
+.PP
+First, all the tags offered when completing after \fBfoo\fP are tried using
+the normal tag name\&.  If that generates no matches, the second value of
+\fBtag\-order\fP is used, which tries all tags again except that this time
+each has \fB\-case\fP appended to its name for lookup of styles\&.  Hence this
+time the value for the \fBmatcher\fP style from the second call to \fBzstyle\fP
+in the example is used to make completion case\-insensitive\&.
+.PP
+It is possible to use the \fB\-e\fP option of the \fBzstyle\fP builtin
+command to specify conditions for the use of particular tags\&.  For
+example:
+.PP
+.RS
+.nf
+\fBzstyle \-e \&'*:\-command\-:*' tag\-order '
+    if [[ \-n $PREFIX$SUFFIX ]]; then
+      reply=( )
+    else
+      reply=( \- )
+    fi\&'\fP
+.fi
+.RE
+.PP
+Completion in command position will be attempted only if the string
+typed so far is not empty\&.  This is tested using the \fBPREFIX\fP
+special parameter; see
+zshcompwid
+for a description of parameters which are special inside completion widgets\&.
+Setting \fBreply\fP 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\&.
+.PP
+If no \fBtag\-order\fP style has been defined for a context, the strings
+`\fB(|*\-)argument\-* (|*\-)option\-* values\fP\&' and `\fBoptions\fP' plus all
+tags offered by the completion function will be used to provide a
+sensible default behavior that causes arguments (whether normal command
+arguments or arguments of options) to be completed before option names for
+most commands\&.
+.RE
+.TP
+\fBurls\fP
+This is used together with the \fBurls\fP tag by
+functions completing URLs\&.
+.RS
+.PP
+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\&.
+.PP
+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)\&.
+.PP
+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
+`\fBhttp\fP\&', `\fBftp\fP', `\fBbookmark\fP' and so on\&.  In many cases the next
+level of directories will be a filename\&.  The directory hierarchy can
+descend as deep as necessary\&.
+.PP
+For example, 
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' urls ~/\&.urls
+mkdir \-p ~/\&.urls/ftp/ftp\&.zsh\&.org/pub
+\fP
+.fi
+.RE
+.PP
+allows completion of all the components of the URL
+\fBftp://ftp\&.zsh\&.org/pub\fP after suitable commands such as
+`\fBnetscape\fP\&' or `\fBlynx\fP'\&.  Note, however, that access methods and
+files are completed separately, so if the \fBhosts\fP style is set hosts
+can be completed without reference to the \fBurls\fP style\&.
+.PP
+See the description in the function \fB_urls\fP itself
+for more information (e\&.g\&. `\fBmore $^fpath/_urls(N)\fP\&')\&.
+.RE
+.TP
+\fBuse\-cache\fP
+If this is set, the completion caching layer is activated for any completions
+which use it (via the \fB_store_cache\fP, \fB_retrieve_cache\fP, and
+\fB_cache_invalid\fP functions)\&.  The directory containing the cache
+files can be changed with the \fBcache\-path\fP style\&.
+.TP
+\fBuse\-compctl\fP
+If this style is set to a string \fInot\fP equal to \fBfalse\fP, \fB0\fP,
+\fBno\fP, and \fBoff\fP, the completion system may use any completion
+specifications defined with the \fBcompctl\fP builtin command\&.  If the
+style is unset, this is done only if the \fBzsh/compctl\fP module
+is loaded\&.  The string may also contain the substring `\fBfirst\fP\&' to
+use completions defined with `\fBcompctl \-T\fP\&', and the substring
+`\fBdefault\fP\&' to use the completion defined with `\fBcompctl \-D\fP'\&.
+.RS
+.PP
+Note that this is only intended to smooth the transition from
+\fBcompctl\fP to the new completion system and may disappear in the
+future\&.
+.PP
+Note also that the definitions from \fBcompctl\fP will only be used if
+there is no specific completion function for the command in question\&.  For
+example, if there is a function \fB_foo\fP to complete arguments to the
+command \fBfoo\fP, \fBcompctl\fP will never be invoked for \fBfoo\fP\&.
+However, the \fBcompctl\fP version will be tried if \fBfoo\fP only uses
+default completion\&.
+.RE
+.TP
+\fBuse\-ip\fP
+By default, the function \fB_hosts\fP that completes host names strips
+IP addresses from entries read from host databases such as NIS and
+ssh files\&.  If this style is `true\&', the corresponding IP addresses
+can be completed as well\&.  This style is not use in any context
+where the \fBhosts\fP style is set; note also it must be set before
+the cache of host names is generated (typically the first completion
+attempt)\&.
+.TP
+\fBusers\fP
+This may be set to a list of usernames to be completed\&.
+If it is not set all usernames will be completed\&.
+Note that if it is set only that list of users will be completed;
+this is because on some systems querying all users can take
+a prohibitive amount of time\&.
+.TP
+\fBusers\-hosts\fP
+The values of this style should be of the form
+`\fIuser\fP\fB@\fP\fIhost\fP\&' or `\fIuser\fP\fB:\fP\fIhost\fP'\&. It is used for
+commands that need pairs of
+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\&.
+.RS
+.PP
+It is possible to group values for sets of commands which allow a remote
+login, such as \fBrlogin\fP and \fBssh\fP, by using the \fBmy\-accounts\fP tag\&.
+Similarly, values for sets of commands which usually refer to the
+accounts of other people, such as \fBtalk\fP and \fBfinger\fP, can be
+grouped by using the \fBother\-accounts\fP tag\&.  More ambivalent commands
+may use the \fBaccounts\fP tag\&.
+.RE
+.TP
+\fBusers\-hosts\-ports\fP
+Like \fBusers\-hosts\fP but used for commands like \fBtelnet\fP and
+containing strings of the form `\fIuser\fP\fB@\fP\fIhost\fP\fB:\fP\fIport\fP\&'\&.
+.TP
+\fBverbose\fP
+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\&'\&.
+.TP
+\fBword\fP
+This is used by the \fB_list\fP completer, which prevents the insertion of
+completions until a second completion attempt when the line has not
+changed\&.  The normal way of finding out if the line has changed is to
+compare its entire contents between the two occasions\&.  If this style is
+`true\&', the comparison is instead performed only on the current word\&.
+Hence if completion is performed on another word with the same contents,
+completion will not be delayed\&.
+.PP
+.SH "CONTROL FUNCTIONS"
+.PP
+The initialization script \fBcompinit\fP redefines all the widgets
+which perform completion to call the supplied widget function
+\fB_main_complete\fP\&.  This function acts as a wrapper calling the
+so\-called `completer\&' functions that generate matches\&.  If
+\fB_main_complete\fP is called with arguments, these are taken as the
+names of completer functions to be called in the order given\&.  If no
+arguments are given, the set of functions to try is taken from the
+\fBcompleter\fP style\&.  For example, to use normal completion and
+correction if that doesn\&'t generate any matches:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' completer _complete _correct\fP
+.fi
+.RE
+.PP
+after calling \fBcompinit\fP\&. The default value for this style is
+`\fB_complete _ignored\fP\&', i\&.e\&. normally only ordinary completion is tried,
+first with the effect of the \fBignored\-patterns\fP style and then without
+it\&.  The \fB_main_complete\fP function uses the return status of the completer
+functions to decide if other completers should be called\&.  If the return
+status is zero, no other completers are tried and the \fB_main_complete\fP
+function returns\&.
+.PP
+If the first argument to \fB_main_complete\fP is a single hyphen, the
+arguments will not be taken as names of completers\&.  Instead, the
+second argument gives a name to use in the \fIcompleter\fP field of the 
+context and the other arguments give a command name and arguments to
+call to generate the matches\&.
+.PP
+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 `\fB:completion::complete:\fP\fI\&.\&.\&.\fP\&'\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB_all_matches\fP
+This completer can be used to add a string consisting of all other
+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
+\fBavoid\-completer\fP and \fBold\-matches\fP styles described above\&.
+.RS
+.PP
+It may be useful to use the \fB_generic\fP function described below
+to bind \fB_all_matches\fP to its own keystroke, for example:
+.PP
+.RS
+.nf
+\fBzle \-C all\-matches complete\-word _generic
+bindkey \&'^Xa' all\-matches
+zstyle \&':completion:all\-matches:*' old\-matches only
+zstyle \&':completion:all\-matches::::' completer _all_matches\fP
+.fi
+.RE
+.PP
+Note that this does not generate completions by itself:  first use
+any of the standard ways of generating a list of completions,
+then use \fB^Xa\fP to show all matches\&.  It is possible instead to
+add a standard completer to the list and request that the
+list of all matches should be directly inserted:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:all\-matches::::' completer \e 
+       _all_matches _complete
+zstyle \&':completion:all\-matches:*' insert true\fP
+.fi
+.RE
+.PP
+In this case the \fBold\-matches\fP style should not be set\&.
+.RE
+.TP
+\fB_approximate\fP
+This is similar to the basic \fB_complete\fP completer but allows the
+completions to undergo corrections\&.  The maximum number of errors can be
+specified by the \fBmax\-errors\fP style; see the description of
+approximate matching in
+\fIzshexpn\fP(1)
+for how errors are counted\&.  Normally this completer will only be tried
+after the normal \fB_complete\fP completer:
+.RS
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' completer _complete _approximate\fP
+.fi
+.RE
+.PP
+This will give correcting completion if and only if
+normal completion yields no possible completions\&.  When
+corrected completions are found, the completer will normally start
+menu completion allowing you to cycle through these strings\&.
+.PP
+This completer uses the tags \fBcorrections\fP and \fBoriginal\fP when
+generating the possible corrections and the original string\&.  The
+\fBformat\fP style for the former may contain the additional sequences
+`\fB%e\fP\&' and `\fB%o\fP' which will be replaced by the number of errors
+accepted to generate the corrections and the original string,
+respectively\&.
+.PP
+The completer progressively increases the number of errors allowed up to
+the limit by the \fBmax\-errors\fP 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
+`\fBapproximate\-1\fP\&', on the second try `\fBapproximate\-2\fP', and so on\&.
+.PP
+When \fB_approximate\fP is called from another function, the number of
+errors to accept may be passed with the \fB\-a\fP option\&.  The argument
+is in the same format as the \fBmax\-errors\fP style, all in one string\&.
+.PP
+Note that this completer (and the \fB_correct\fP completer mentioned
+below) can be quite expensive to call, especially when a large number
+of errors are allowed\&.  One way to avoid this is to set up the
+\fBcompleter\fP style using the \fB\-e\fP option to zstyle so that some
+completers are only used when completion is attempted a second time on 
+the same string, e\&.g\&.:
+.PP
+.RS
+.nf
+\fBzstyle \-e \&':completion:*' completer '
+  if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then
+    _last_try="$HISTNO$BUFFER$CURSOR"
+    reply=(_complete _match _prefix)
+  else
+    reply=(_ignored _correct _approximate)
+  fi\&'\fP
+.fi
+.RE
+.PP
+This uses the \fBHISTNO\fP parameter and the \fBBUFFER\fP and \fBCURSOR\fP
+special parameters that are available inside zle and completion
+widgets to find out if the command line hasn\&'t changed since the last
+time completion was tried\&.  Only then are the \fB_ignored\fP,
+\fB_correct\fP and \fB_approximate\fP completers called\&.
+.RE
+.TP
+\fB_canonical_paths\fP [ \fB\-A\fP \fIvar\fP ] [ \fB\-N\fP ] [ \fB\-MJV12nfX\fP ] \fItag\fP \fIdescr\fP [ \fIpaths\fP \&.\&.\&. ]
+This completion function completes all paths given to it, and also tries to
+offer completions which point to the same file as one of the paths given
+(relative path when an absolute path is given, and vice versa; when \fB\&.\&.\fP\&'s
+are present in the word to be completed; and some paths got from symlinks)\&.
+.RS
+.PP
+\fB\-A\fP, if specified, takes the paths from the array variable specified\&. Paths can
+also be specified on the command line as shown above\&.  \fB\-N\fP, if specified,
+prevents canonicalizing the paths given before using them for completion, in
+case they are already so\&. The options \fB\-M\fP, \fB\-J\fP, \fB\-V\fP, \fB\-1\fP, \fB\-2\fP,
+\fB\-n\fP, \fB\-F\fP, \fB\-X\fP are passed to \fBcompadd\fP\&.
+.PP
+See \fB_description\fP for a description of \fItag\fP and \fIdescr\fP\&.
+.RE
+.TP
+\fB_cmdambivalent\fP
+Completes the remaining positional arguments as an external command\&.
+The external command and its arguments are completed as separate arguments
+(in a manner appropriate for completing \fB/usr/bin/env\fP)
+if there are two or more remaining positional arguments on the command line,
+and as a quoted command string (in the manner of \fBsystem(\&.\&.\&.)\fP) otherwise\&.
+See also \fB_cmdstring\fP and \fB_precommand\fP\&.
+.RS
+.PP
+This function takes no arguments\&.
+.RE
+.TP
+\fB_cmdstring\fP
+Completes an external command as a single argument, as for
+\fBsystem(\&.\&.\&.)\fP\&.
+.TP
+\fB_complete\fP
+This completer generates all possible completions in a context\-sensitive
+manner, i\&.e\&. using the settings defined with the \fBcompdef\fP function
+explained above and the current settings of all special parameters\&.
+This gives the normal completion behaviour\&.
+.RS
+.PP
+To complete arguments of commands, \fB_complete\fP uses the utility function
+\fB_normal\fP, which is in turn responsible for finding the particular
+function; it is described below\&.  Various contexts of the form
+\fB\-\fP\fIcontext\fP\fB\-\fP are handled specifically\&. These are all
+mentioned above as possible arguments to the \fB#compdef\fP tag\&.
+.PP
+Before trying to find a function for a specific context, \fB_complete\fP 
+checks if the parameter `\fBcompcontext\fP\&' is set\&. Setting
+`\fBcompcontext\fP\&' allows the usual completion dispatching to be
+overridden which is useful in places such as a function that uses
+\fBvared\fP for input\&. If it is set to an array, the elements are taken
+to be the possible matches which will be completed using the tag
+`\fBvalues\fP\&' and the description `\fBvalue\fP'\&. If it is set to an
+associative array, the keys are used as the possible completions and
+the values (if non\-empty) are used as descriptions for the matches\&.  If
+`\fBcompcontext\fP\&' is set to a string containing colons, it should be of
+the form `\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP\&'\&.  In this case the
+\fItag\fP and \fIdescr\fP give the tag and description to use and the
+\fIaction\fP indicates what should be completed in one of the forms
+accepted by the \fB_arguments\fP utility function described below\&.
+.PP
+Finally, if `\fBcompcontext\fP\&' 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 \fB\-command\-line\-\fP that completes whole command
+lines (commands and their arguments)\&.  This is not used by the completion
+system itself but is nonetheless handled when explicitly called\&.
+.RE
+.TP
+\fB_correct\fP
+Generate corrections, but not completions, for the current word; this is
+similar to \fB_approximate\fP but will not allow any number of extra
+characters at the cursor as that completer does\&.  The effect is
+similar to spell\-checking\&.  It is based on \fB_approximate\fP, but the
+completer field in the context name is \fBcorrect\fP\&.
+.RS
+.PP
+For example, with:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:::::' completer \e 
+       _complete _correct _approximate
+zstyle \&':completion:*:correct:::' max\-errors 2 not\-numeric
+zstyle \&':completion:*:approximate:::' max\-errors 3 numeric\fP
+.fi
+.RE
+.PP
+correction will accept up to two errors\&.  If a numeric argument is
+given, correction will not be performed, but correcting completion
+will be, and will accept as many errors as given by the numeric
+argument\&.  Without a numeric argument, first correction and then
+correcting completion will be tried, with the first one accepting two
+errors and the second one accepting three errors\&.
+.PP
+When \fB_correct\fP is called as a function, the number of errors to accept
+may be given following the \fB\-a\fP option\&.  The argument is in the same
+form a values to the \fBaccept\fP style, all in one string\&.
+.PP
+This completer function is intended to be used without the
+\fB_approximate\fP completer or, as in the example, just before
+it\&.  Using it after the \fB_approximate\fP completer is useless since
+\fB_approximate\fP will at least generate the corrected strings
+generated by the \fB_correct\fP completer \-\- and probably more\&.
+.RE
+.TP
+\fB_expand\fP
+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\&.  For
+this to happen, the completion system needs to be invoked with
+\fBcomplete\-word\fP, not \fBexpand\-or\-complete\fP (the default binding for
+\fBTAB\fP), 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 \fB_complete\fP 
+completer function\&.
+.RS
+.PP
+The tags used when generating expansions are \fBall\-expansions\fP for the
+string containing all possible expansions, \fBexpansions\fP when adding
+the possible expansions as single matches and \fBoriginal\fP when adding
+the original string from the line\&.  The order in which these strings are
+generated, if at all, can be controlled by the \fBgroup\-order\fP and
+\fBtag\-order\fP styles, as usual\&.
+.PP
+The format string for \fBall\-expansions\fP and for \fBexpansions\fP may
+contain the sequence `\fB%o\fP\&' which will be replaced by the original
+string from the line\&.
+.PP
+The kind of expansion to be tried is controlled by the \fBsubstitute\fP,
+\fBglob\fP and \fBsubst\-globs\-only\fP styles\&.
+.PP
+It is also possible to call \fB_expand\fP as a function, in which case the
+different modes may be selected with options: \fB\-s\fP for
+\fBsubstitute\fP, \fB\-g\fP for \fBglob\fP and \fB\-o\fP for \fBsubst\-globs\-only\fP\&.
+.RE
+.TP
+\fB_expand_alias\fP
+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 styles \fBregular\fP, \fBglobal\fP and \fBdisabled\fP\&.
+.RS
+.PP
+This function is also a bindable command, see
+the section `Bindable Commands\&' below\&.
+.RE
+.TP
+\fB_extensions\fP
+If the cursor follows the string `\fB*\&.\fP\&', filename extensions are
+completed\&. The extensions are taken from files in current directory or a
+directory specified at the beginning of the current word\&. For exact matches,
+completion continues to allow other completers such as \fB_expand\fP to
+expand the pattern\&. The standard \fBadd\-space\fP and \fBprefix\-hidden\fP
+styles are observed\&.
+.TP
+\fB_external_pwds\fP
+Completes current directories of other zsh processes belonging to the
+current user\&.
+.RS
+.PP
+This is intended to be used via \fB_generic\fP, bound to a custom key
+combination\&. Note that pattern matching is enabled so matching is
+performed similar to how it works with the \fB_match\fP completer\&.
+.RE
+.TP
+\fB_history\fP
+Complete words from the shell\&'s command  history\&.  This completer 
+can be controlled by the \fBremove\-all\-dups\fP, and \fBsort\fP styles as for the
+\fB_history_complete_word\fP bindable command, see
+the section `Bindable Commands\&' below
+and
+the section `Completion System Configuration\&' above\&.
+.TP
+\fB_ignored\fP
+The \fBignored\-patterns\fP 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 \fBignored\-patterns\fP style were set\&.  The completer actually
+generates its own list of matches; which completers are invoked
+is determined in the same way as for the \fB_prefix\fP completer\&.
+The \fBsingle\-ignored\fP style is also available as described above\&.
+.TP
+\fB_list\fP
+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 \fBcondition\fP and \fBword\fP, see
+the section `Completion System Configuration\&' above\&.
+.TP
+\fB_match\fP
+This completer is intended to be used after the \fB_complete\fP
+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 \fBGLOB_COMPLETE\fP option\&.
+.RS
+.PP
+Normally completion will be performed by taking the pattern from the line,
+inserting a `\fB*\fP\&' at the cursor position and comparing the resulting
+pattern with the possible completions generated\&.  This can be modified
+with the \fBmatch\-original\fP style described above\&.
+.PP
+The generated matches will be offered in a menu completion unless the
+\fBinsert\-unambiguous\fP style is set to `true\&'; see the description above
+for other options for this style\&.
+.PP
+Note that matcher specifications defined globally or used by the
+completion functions (the styles \fBmatcher\-list\fP and \fBmatcher\fP) will
+not be used\&.
+.RE
+.TP
+\fB_menu\fP
+This completer was written as simple example function to show how menu
+completion can be enabled in shell code\&. However, it has the notable
+effect of disabling menu selection which can be useful with
+\fB_generic\fP based widgets\&. It should be used as the first completer in
+the list\&.  Note that this is independent of the setting of the
+\fBMENU_COMPLETE\fP option and does not work with the other menu
+completion widgets such as \fBreverse\-menu\-complete\fP, or
+\fBaccept\-and\-menu\-complete\fP\&.
+.TP
+\fB_oldlist\fP
+This completer controls how the standard completion widgets behave
+when there is an existing list of completions which may have been
+generated by a special completion (i\&.e\&. a separately\-bound completion
+command)\&.  It allows the ordinary completion keys to continue to use the
+list of completions thus generated, instead of producing a new list of
+ordinary contextual completions\&.
+It should appear in the list of completers before any of
+the widgets which generate matches\&.  It uses two styles: \fBold\-list\fP and
+\fBold\-menu\fP, see
+the section `Completion System Configuration\&' above\&.
+.TP
+\fB_precommand\fP
+Complete an external command in word\-separated arguments, as for
+\fBexec\fP and \fB/usr/bin/env\fP\&.
+.TP
+\fB_prefix\fP
+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\&.  The effect is similar
+to the \fBexpand\-or\-complete\-prefix\fP command\&.
+.RS
+.PP
+The \fBcompleter\fP 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
+\fB_prefix\fP 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 \fB_prefix\fP will be called\&.
+.PP
+For example, consider this global \fBcompleter\fP style:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' completer \e 
+    _complete _prefix _correct _prefix:foo\fP
+.fi
+.RE
+.PP
+Here, the \fB_prefix\fP completer tries normal completion but ignoring the
+suffix\&.  If that doesn\&'t generate any matches, and neither does
+the call to the \fB_correct\fP completer after it, \fB_prefix\fP will 
+be called a second time and, now only trying correction with the
+suffix ignored\&.  On the second invocation the completer part of the
+context appears as `\fBfoo\fP\&'\&.
+.PP
+To use \fB_prefix\fP as the last resort and try only normal completion
+when it is invoked:
+.PP
+.RS
+.nf
+\fBzstyle \&':completion:*' completer _complete \&.\&.\&. _prefix
+zstyle \&':completion::prefix:*' completer _complete\fP
+.fi
+.RE
+.PP
+The \fBadd\-space\fP style is also respected\&.  If it is set to `true\&' then
+\fB_prefix\fP will insert a space between the matches generated (if any) 
+and the suffix\&.
+.PP
+Note that this completer is only useful if the
+\fBCOMPLETE_IN_WORD\fP option is set; otherwise, the cursor will
+be moved to the end of the current word before the completion code is
+called and hence there will be no suffix\&.
+.RE
+.TP
+\fB_user_expand\fP
+This completer behaves similarly to the \fB_expand\fP completer but
+instead performs expansions defined by users\&.  The styles \fBadd\-space\fP and
+\fBsort\fP styles specific to the \fB_expand\fP completer are usable with
+\fB_user_expand\fP in addition to other styles handled more generally by
+the completion system\&.  The tag \fBall\-expansions\fP is also available\&.
+.RS
+.PP
+The expansion depends on the array style \fBuser\-expand\fP being defined
+for the current context; remember that the context for completers is less
+specific than that for contextual completion as the full context has not
+yet been determined\&.  Elements of the array may have one of the following
+forms:
+.PP
+.PD 0
+.TP
+\fB$\fP\fIhash\fP
+
+\fIhash\fP is the name of an associative array\&.  Note this is not a full
+parameter expression, merely a \fB$\fP, suitably quoted to prevent immediate
+expansion, followed by the name of an associative array\&.  If the trial
+expansion word matches a key in \fIhash\fP, the resulting expansion is the
+corresponding value\&.
+.PP
+.TP
+\fI_func\fP
+
+\fI_func\fP is the name of a shell function whose name must begin with
+\fB_\fP but is not otherwise special to the completion system\&.  The function
+is called with the trial word as an argument\&.  If the word is to be
+expanded, the function should set the array \fBreply\fP to a list of
+expansions\&.  Optionally, it can set \fBREPLY\fP to a word that will
+be used as a description for the set of expansions\&.
+The return status of the function is irrelevant\&.
+.PP
+.PD
+.RE
+.PP
+.SH "BINDABLE COMMANDS"
+.PP
+In addition to the context\-dependent completions provided, which are
+expected to work in an intuitively obvious way, there are a few widgets
+implementing special behaviour which can be bound separately to keys\&.  The
+following is a list of these and their default bindings\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB_bash_completions\fP
+This function is used by two widgets, \fB_bash_complete\-word\fP and
+\fB_bash_list\-choices\fP\&.  It exists to provide compatibility with
+completion bindings in bash\&.  The last character of the binding determines
+what is completed: `\fB!\fP\&', command names; `\fB$\fP', environment variables;
+`\fB@\fP\&', host names; `\fB/\fP', file names; `\fB~\fP' user names\&.  In bash, the
+binding preceded by `\fB\ee\fP\&' gives completion, and preceded by `\fB^X\fP'
+lists options\&.  As some of these bindings clash with standard zsh
+bindings, only `\fB\ee~\fP\&' and `\fB^X~\fP' are bound by default\&.  To add the
+rest, the following should be added to \fB\&.zshrc\fP after \fBcompinit\fP has
+been run:
+.RS
+.PP
+.RS
+.nf
+\fBfor key in \&'!' '$' '@' '/' '~'; do
+  bindkey "\ee$key" _bash_complete\-word
+  bindkey "^X$key" _bash_list\-choices
+done\fP
+.fi
+.RE
+.PP
+This includes the bindings for `\fB~\fP\&' in case they were already bound to
+something else; the completion code does not override user bindings\&.
+.RE
+.TP
+\fB_correct_filename\fP (\fB^XC\fP)
+Correct the filename path at the cursor position\&.  Allows up to six errors
+in the name\&.  Can also be called with an argument to correct
+a filename path, independently of zle; the correction is printed on
+standard output\&.
+.TP
+\fB_correct_word\fP (\fB^Xc\fP)
+Performs correction of the current argument using the usual contextual
+completions as possible choices\&. This stores the string
+`\fBcorrect\-word\fP\&' in the \fIfunction\fP field of the context name and
+then calls the \fB_correct\fP completer\&.
+.TP
+\fB_expand_alias\fP (\fB^Xa\fP)
+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
+alias expanded can be controlled with the styles \fBregular\fP, \fBglobal\fP
+and \fBdisabled\fP\&.
+.RS
+.PP
+When used as a bindable command there is one additional feature that
+can be selected by setting the \fBcomplete\fP style to `true\&'\&.  In this
+case, if the word is not the name of an alias, \fB_expand_alias\fP 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
+\fB_expand_alias\fP once more will expand the now\-complete alias name\&.
+.RE
+.TP
+\fB_expand_word\fP (\fB^Xe\fP)
+Performs expansion on the current word:  equivalent to the standard
+\fBexpand\-word\fP command, but using the \fB_expand\fP completer\&.  Before
+calling it, the \fIfunction\fP field of the context is set to
+`\fBexpand\-word\fP\&'\&.
+.TP
+\fB_generic\fP
+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
+store the name of the widget in the \fIfunction\fP field of the context 
+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:
+.RS
+.PP
+.RS
+.nf
+\fBzle \-C foo complete\-word _generic
+bindkey \&'\&.\&.\&.' foo
+zstyle \&':completion:foo:*' menu yes select=1\fP
+.fi
+.RE
+.PP
+Note in particular that the \fBcompleter\fP style may be set for the context
+in order to change the set of functions used to generate possible matches\&.
+If \fB_generic\fP is called with arguments, those are passed through to
+\fB_main_complete\fP as the list of completers in place of those defined by
+the \fBcompleter\fP style\&.
+.RE
+.TP
+\fB_history_complete_word\fP (\fB\ee/\fP)
+Complete words from the shell\&'s command history\&. This uses the
+\fBlist\fP, \fBremove\-all\-dups\fP, \fBsort\fP, and \fBstop\fP styles\&.
+.TP
+\fB_most_recent_file\fP (\fB^Xm\fP)
+Complete the name of the most recently modified file matching the pattern
+on the command line (which may be blank)\&.  If given a numeric argument
+\fIN\fP, complete the \fIN\fPth most recently modified file\&.  Note the
+completion, if any, is always unique\&.
+.TP
+\fB_next_tags\fP (\fB^Xn\fP)
+This command alters the set of matches used to that for the next tag, or
+set of tags, either as given by the \fBtag\-order\fP style or as set by
+default; these matches would otherwise not be available\&.
+Successive invocations of the command cycle through all possible sets of
+tags\&.
+.TP
+\fB_read_comp\fP (\fB^X^R\fP)
+Prompt the user for a string, and use that to perform completion on the
+current word\&.  There are two possibilities for the string\&.  First, it can
+be a set of words beginning `\fB_\fP\&', for example `\fB_files \-/\fP', in which
+case the function with any arguments will be called to generate the
+completions\&.  Unambiguous parts of the function name will be completed
+automatically (normal completion is not available at this point) until a
+space is typed\&.
+.RS
+.PP
+Second, any other string will be passed as a set of arguments to
+\fBcompadd\fP and should hence be an expression specifying what should
+be completed\&.
+.PP
+A very restricted set of editing commands is available when reading the
+string:  `\fBDEL\fP\&' and `\fB^H\fP' delete the last character; `\fB^U\fP' deletes
+the line, and `\fB^C\fP\&' and `\fB^G\fP' abort the function, while `\fBRET\fP'
+accepts the completion\&.  Note the string is used verbatim as a command
+line, so arguments must be quoted in accordance with standard shell rules\&.
+.PP
+Once a string has been read, the next call to \fB_read_comp\fP will use the
+existing string instead of reading a new one\&.  To force a new string to be
+read, call \fB_read_comp\fP with a numeric argument\&.
+.RE
+.TP
+\fB_complete_debug\fP (\fB^X?\fP)
+This widget performs ordinary completion, but captures in a temporary file
+a trace of the shell commands executed by the completion system\&.  Each
+completion attempt gets its own file\&.  A command to view each of these
+files is pushed onto the editor buffer stack\&.
+.TP
+\fB_complete_help\fP (\fB^Xh\fP)
+This widget displays information about the context names, 
+the tags, and the completion functions used 
+when completing at the current cursor position\&. If given a numeric
+argument other than \fB1\fP (as in `\fBESC\-2 ^Xh\fP\&'), then the styles
+used and the contexts for which they are used will be shown, too\&.
+.RS
+.PP
+Note that the information about styles may be incomplete; it depends on the
+information available from the completion functions called, which in turn
+is determined by the user\&'s own styles and other settings\&.
+.RE
+.TP
+\fB_complete_help_generic\fP
+Unlike other commands listed here, this must be created as a normal ZLE
+widget rather than a completion widget (i\&.e\&. with \fBzle \-N\fP)\&.  It
+is used for generating help with a widget bound to the \fB_generic\fP
+widget that is described above\&.
+.RS
+.PP
+If this widget is created using the name of the function, as it is by
+default, then when executed it will read a key sequence\&.  This is expected
+to be bound to a call to a completion function that uses the \fB_generic\fP
+widget\&.  That widget will be executed, and information provided in
+the same format that the \fB_complete_help\fP widget displays for
+contextual completion\&.
+.PP
+If the widget\&'s name contains \fBdebug\fP, for example if it is created
+as `\fBzle \-N _complete_debug_generic _complete_help_generic\fP\&', it
+will read and execute the keystring for a generic widget as before,
+but then generate debugging information as done by \fB_complete_debug\fP
+for contextual completion\&.
+.PP
+If the widget\&'s name contains \fBnoread\fP, it will not read a keystring
+but instead arrange that the next use of a generic widget run in
+the same shell will have the effect as described above\&.
+.PP
+The widget works by setting the shell parameter
+\fBZSH_TRACE_GENERIC_WIDGET\fP which is read by \fB_generic\fP\&.  Unsetting
+the parameter cancels any pending effect of the \fBnoread\fP form\&.
+.PP
+For example, after executing the following:
+.PP
+.RS
+.nf
+\fBzle \-N _complete_debug_generic _complete_help_generic
+bindkey \&'^x:' _complete_debug_generic\fP
+.fi
+.RE
+.PP
+typing `\fBC\-x :\fP\&' followed by the key sequence for a generic widget
+will cause trace output for that widget to be saved to a file\&.
+.RE
+.TP
+\fB_complete_tag\fP (\fB^Xt\fP)
+This widget completes symbol tags created by the \fBetags\fP or \fBctags\fP
+programmes (note there is no connection with the completion system\&'s tags)
+stored in a file \fBTAGS\fP, in the format used by \fBetags\fP, or \fBtags\fP, in the
+format created by \fBctags\fP\&.  It will look back up the path hierarchy for
+the first occurrence of either file; if both exist, the file \fBTAGS\fP is
+preferred\&.  You can specify the full path to a \fBTAGS\fP or \fBtags\fP file by
+setting the parameter \fB$TAGSFILE\fP or \fB$tagsfile\fP respectively\&.
+The corresponding completion tags used are \fBetags\fP and \fBvtags\fP, after
+emacs and vi respectively\&.
+.PP
+.SH "UTILITY FUNCTIONS"
+.PP
+Descriptions follow for utility functions that may be
+useful when writing completion functions\&.  If functions are installed in
+subdirectories, most of these reside in the
+\fBBase\fP subdirectory\&.  Like the example 
+functions for commands in the distribution, the utility functions
+generating matches all follow the convention of returning status zero if they
+generated completions and non\-zero if no matching completions could be 
+added\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB_absolute_command_paths\fP
+This function completes external commands as absolute paths (unlike
+\fB_command_names \-e\fP which completes their basenames)\&.  It takes no
+arguments\&.
+.TP
+\fB_all_labels\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP [ \fIcommand\fP \fIarg\fP \&.\&.\&. ]
+This is a convenient interface to the \fB_next_label\fP function below,
+implementing the loop shown in the \fB_next_label\fP example\&.  The
+\fIcommand\fP and its arguments are called to generate the matches\&.  The
+options stored in the parameter \fIname\fP will automatically be inserted
+into the \fIarg\fPs passed to the \fIcommand\fP\&.  Normally, they are put
+directly after the \fIcommand\fP, but if one of the \fIarg\fPs is a single
+hyphen, they are inserted directly before that\&.  If the hyphen is the last
+argument, it will be removed from the argument list before the
+\fIcommand\fP is called\&.  This allows \fB_all_labels\fP to be used in almost all
+cases where the matches can be generated by a single call to the
+\fBcompadd\fP builtin command or by a call to one of the utility functions\&.
+.RS
+.PP
+For example:
+.PP
+.RS
+.nf
+\fBlocal expl
+\&.\&.\&.
+if _requested foo; then
+  \&.\&.\&.
+  _all_labels foo expl \&'\&.\&.\&.' compadd \&.\&.\&. \- $matches
+fi\fP
+.fi
+.RE
+.PP
+Will complete the strings from the \fBmatches\fP parameter, using
+\fBcompadd\fP with additional options which will take precedence over
+those generated by \fB_all_labels\fP\&.
+.RE
+.TP
+\fB_alternative\fP [ \fB\-O\fP \fIname\fP ] [ \fB\-C\fP \fIname\fP ] \fIspec\fP \&.\&.\&.
+This function is useful in simple cases where multiple tags are available\&.
+Essentially it implements a loop like the one described for the \fB_tags\fP
+function below\&.
+.RS
+.PP
+The tags to use and the action to perform if a tag is requested are
+described using the \fIspec\fPs which are of the form:
+`\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP\&'\&.  The \fItag\fPs are offered using
+\fB_tags\fP and if the tag is requested, the \fIaction\fP is executed with the
+given description \fIdescr\fP\&.  The \fIaction\fPs are those accepted
+by the \fB_arguments\fP function (described below), excluding the
+`\fB\->\fP\fIstate\fP\&' and `\fB=\fP\fI\&.\&.\&.\fP' forms\&.
+.PP
+For example, the \fIaction\fP may be a simple function call:
+.PP
+.RS
+.nf
+\fB_alternative \e 
+    \&'users:user:_users' \e 
+    \&'hosts:host:_hosts'\fP
+.fi
+.RE
+.PP
+offers usernames and hostnames as possible matches,
+generated by the \fB_users\fP and \fB_hosts\fP functions respectively\&.
+.PP
+Like \fB_arguments\fP, this function uses \fB_all_labels\fP 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 \fB_alternative\fP\&.
+.PP
+The option `\fB\-O\fP \fIname\fP\&' is used in the same way as by the
+\fB_arguments\fP function\&.  In other words, the elements of the \fIname\fP
+array will be passed to \fBcompadd\fP when executing an action\&.
+.PP
+Like \fB_tags\fP this function supports the \fB\-C\fP option to give a
+different name for the argument context field\&.
+.RE
+
+.TP
+.PD 0
+\fB_arguments \fP[ \fB\-nswWCRS\fP ] [ \fB\-A\fP \fIpat\fP ] [ \fB\-O\fP \fIname\fP ] [ \fB\-M\fP \fImatchspec\fP ]
+.TP
+.PD 0
+\fB           \fP[ \fB:\fP ] \fIspec\fP \&.\&.\&.
+.TP
+.PD 0
+\fB_arguments \fP[ \fIopt\fP \&.\&.\&. ] \fB\-\fP\fB\-\fP [ \fB\-l\fP ] [ \fB\-i\fP \fIpats\fP ] [ \fB\-s\fP \fIpair\fP ]
+.TP
+.PD
+\fB           \fP[ \fIhelpspec\fP \&.\&.\&.]
+This function can be used to give a complete specification for completion
+for a command whose arguments follow standard UNIX option and argument
+conventions\&.
+.RS
+.PP
+\fIOptions Overview\fP
+.PP
+Options to \fB_arguments\fP itself must be in separate words, i\&.e\&. \fB\-s \-w\fP,
+not \fB\-sw\fP\&.  The options are followed by \fIspec\fPs that describe options and
+arguments of the analyzed command\&.  To avoid ambiguity, all
+options to \fB_arguments\fP itself may be separated from the \fIspec\fP forms
+by a single colon\&.
+.PP
+The `\fB\-\fP\fB\-\fP\&'
+form is used to intuit \fIspec\fP forms from the help output of the command
+being analyzed, and is described in detail below\&.  The \fIopts\fP for the
+`\fB\-\fP\fB\-\fP\&' form are otherwise the same options as the first form\&.  Note
+that `\fB\-s\fP\&' following `\fB\-\fP\fB\-\fP' has a distinct meaning from `\fB\-s\fP'
+preceding `\fB\-\fP\fB\-\fP\&', and both may appear\&.
+.PP
+The option switches \fB\-s\fP, \fB\-S\fP, \fB\-A\fP, \fB\-w\fP, and \fB\-W\fP affect how
+\fB_arguments\fP parses the analyzed command line\&'s options\&.  These switches are
+useful for commands with standard argument parsing\&.
+.PP
+The options of \fB_arguments\fP have the following meanings:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-n\fP
+With this option, \fB_arguments\fP sets the parameter \fBNORMARG\fP
+to the position of the first normal argument in the \fB$words\fP array,
+i\&.e\&. the position after the end of the options\&.  If that argument
+has not been reached, \fBNORMARG\fP is set to \fB\-1\fP\&.  The caller
+should declare `\fBinteger NORMARG\fP\&' if the \fB\-n\fP option is passed;
+otherwise the parameter is not used\&.
+.TP
+\fB\-s\fP
+Enable \fIoption stacking\fP for single\-letter options, whereby multiple
+single\-letter options may be combined into a single word\&.  For example,
+the two options `\fB\-x\fP\&' and `\fB\-y\fP' may be combined into
+a single word `\fB\-xy\fP\&'\&.  By default, every word corresponds to a single
+option name (`\fB\-xy\fP\&' is a single option named `\fBxy\fP')\&.
+.RS
+.PP
+Options beginning with a single hyphen or plus sign are eligible for stacking;
+words beginning with two hyphens are not\&.
+.PP
+Note that \fB\-s\fP after \fB\-\fP\fB\-\fP has a different meaning, which is documented
+in the segment entitled `Deriving \fIspec\fP forms from the help output\&'\&.
+.RE
+.TP
+\fB\-w\fP
+In combination with \fB\-s\fP, allow option stacking
+even if one or more of the options take
+arguments\&.  For example, if \fB\-x\fP takes an argument, with no
+\fB\-s\fP, `\fB\-xy\fP\&' is considered as a single (unhandled) option; with
+\fB\-s\fP, \fB\-xy\fP is an option with the argument `\fBy\fP\&'; with both \fB\-s\fP
+and \fB\-w\fP, \fB\-xy\fP is the option \fB\-x\fP and the option \fB\-y\fP with
+arguments to \fB\-x\fP (and to \fB\-y\fP, if it takes arguments) still to come
+in subsequent words\&.
+.TP
+\fB\-W\fP
+This option takes \fB\-w\fP 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 \fB_guard\fP as part of the action\&.
+.TP
+\fB\-C\fP
+Modify the \fBcurcontext\fP parameter for an action of the form `\fB\->\fP\fIstate\fP\&'\&.
+This is discussed in detail below\&.
+.TP
+\fB\-R\fP
+Return status 300 instead of zero when a \fB$state\fP is to
+be handled, in the `\fB\->\fP\fIstring\fP\&' syntax\&.
+.TP
+\fB\-S\fP
+Do not complete options after a `\fB\-\fP\fB\-\fP\&' appearing on the line,
+and ignore the `\fB\-\fP\fB\-\fP\&'\&.  For example, with \fB\-S\fP, in the line
+.RS
+.PP
+.RS
+.nf
+\fBfoobar \-x \-\- \-y\fP
+.fi
+.RE
+.PP
+the `\fB\-x\fP\&' is considered an option, the `\fB\-y\fP' is considered an
+argument, and the `\fB\-\fP\fB\-\fP\&' is considered to be neither\&.
+.RE
+.TP
+\fB\-A\fP \fIpat\fP
+Do not complete options after the first non\-option
+argument on the line\&.  \fIpat\fP is a pattern matching
+all strings which are not to be taken as arguments\&.  For example, to make
+\fB_arguments\fP 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 \fIoptspec\fPs, the form is `\fB\-A "\-*"\fP\&'\&.
+.TP
+\fB\-O\fP \fIname\fP
+Pass the elements of the array \fIname\fP as arguments to functions called to
+execute \fIaction\fPs\&.
+This is discussed in detail below\&.
+.TP
+\fB\-M\fP \fImatchspec\fP
+Use the match specification \fImatchspec\fP for completing option names and values\&.
+The default \fImatchspec\fP allows partial word completion after `\fB_\fP\&' and
+`\fB\-\fP\&', such as completing `\fB\-f\-b\fP' to `\fB\-foo\-bar\fP'\&.  The default
+\fImatchspec\fP is:
+.RS
+.nf
+\fB\fBr:|[_\-]=* r:|=*\fP\fP
+.fi
+.RE
+.PP
+\fI\fIspec\fPs: overview\fP
+.PP
+Each of the following forms is a \fIspec\fP describing individual sets of
+options or arguments on the command line being analyzed\&.
+.PP
+.PD 0
+.TP
+.PD 0
+\fIn\fP\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD
+\fIn\fP\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP
+This describes the \fIn\fP\&'th normal argument\&.  The \fImessage\fP will be 
+printed above the matches generated and the \fIaction\fP indicates what can
+be completed in this position (see below)\&.  If there are two colons
+before the \fImessage\fP the argument is optional\&.  If the
+\fImessage\fP contains only white space, nothing will be printed above
+the matches unless the action adds an explanation string itself\&.
+.TP
+.PD 0
+\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD
+\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP
+Similar, but describes the \fInext\fP argument, whatever number that
+happens to be\&.  If all arguments are specified in this form in the
+correct order the numbers are unnecessary\&.
+.TP
+.PD 0
+\fB*:\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD 0
+\fB*::\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD
+\fB*:::\fP\fImessage\fP\fB:\fP\fIaction\fP
+This describes how arguments (usually non\-option arguments, those not
+beginning with \fB\-\fP or \fB+\fP) are to be completed when neither
+of the first two forms was provided\&.  Any number of arguments can
+be completed in this fashion\&.
+.RS
+.PP
+With two colons before the \fImessage\fP, the \fBwords\fP special array and
+the \fBCURRENT\fP special parameter are modified to refer only to the
+normal arguments when the \fIaction\fP is executed or evaluated\&.  With
+three colons before the \fImessage\fP they are modified to refer only to
+the normal arguments covered by this description\&.
+.RE
+.TP
+.PD 0
+\fIoptspec\fP
+.TP
+.PD
+\fIoptspec\fP\fB:\fP\fI\&.\&.\&.\fP
+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\&.
+.RS
+.PP
+The following forms are available for the initial \fIoptspec\fP, whether
+or not the option has arguments\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB*\fP\fIoptspec\fP
+Here \fIoptspec\fP is one of the remaining forms below\&.  This indicates
+the following \fIoptspec\fP 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\&.
+.TP
+.PD 0
+\fB\-\fP\fIoptname\fP
+.TP
+.PD
+\fB+\fP\fIoptname\fP
+In the simplest form the \fIoptspec\fP is just the option name beginning
+with a minus or a plus sign, such as `\fB\-foo\fP\&'\&.  The first argument for
+the option (if any) must follow as a \fIseparate\fP word directly after the
+option\&.
+.RS
+.PP
+Either of `\fB\-+\fP\fIoptname\fP\&' and `\fB+\-\fP\fIoptname\fP' can be used to
+specify that \fB\-\fP\fIoptname\fP and \fB+\fP\fIoptname\fP are both valid\&.
+.PP
+In all the remaining forms, the leading `\fB\-\fP\&' may be replaced by or
+paired with `\fB+\fP\&' in this way\&.
+.RE
+.TP
+\fB\-\fP\fIoptname\fP\fB\-\fP
+The first argument of the option must come directly after the option name
+\fIin the same word\fP\&.  For example, `\fB\-foo\-:\fP\fI\&.\&.\&.\fP\&' specifies that
+the completed option and argument will look like `\fB\-foo\fP\fIarg\fP\&'\&.
+.TP
+\fB\-\fP\fIoptname\fP\fB+\fP
+The first argument may appear immediately after \fIoptname\fP in the same
+word, or may appear as a separate word after the option\&.  For example,
+`\fB\-foo+:\fP\fI\&.\&.\&.\fP\&' specifies that the completed option and argument
+will look like either `\fB\-foo\fP\fIarg\fP\&' or `\fB\-foo\fP \fIarg\fP'\&.
+.TP
+\fB\-\fP\fIoptname\fP\fB=\fP
+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, for
+example `\fB\-foo=\fP\fIarg\fP\&' or `\fB\-foo\fP \fIarg\fP'\&.
+.TP
+\fB\-\fP\fIoptname\fP\fB=\-\fP
+The argument to the option must appear after an equals sign in the same
+word, and may not be given in the next argument\&.
+.TP
+\fIoptspec\fP\fB[\fP\fIexplanation\fP\fB]\fP
+An explanation string may be appended to any of the preceding forms of
+\fIoptspec\fP by enclosing it in brackets, as in `\fB\-q[query operation]\fP\&'\&.
+.RS
+.PP
+The \fBverbose\fP style is used to decide whether the explanation strings
+are displayed with the option in a completion listing\&.
+.PP
+If no bracketed explanation string is given but the \fBauto\-description\fP
+style is set and only one argument is described for this \fIoptspec\fP, the
+value of the style is displayed, with any appearance of the sequence
+`\fB%d\fP\&' in it replaced by the \fImessage\fP of the first \fIoptarg\fP
+that follows the \fIoptspec\fP; see below\&.
+.RE
+.PP
+It is possible for options with a literal `\fB+\fP\&' or `\fB=\fP' to
+appear, but that character must be quoted, for example `\fB\-\e+\fP\&'\&.
+.PP
+Each \fIoptarg\fP following an \fIoptspec\fP must take one of the
+following forms:
+.PP
+.PD 0
+.TP
+.PD 0
+\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD
+\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP
+An argument to the option; \fImessage\fP and \fIaction\fP are treated as
+for ordinary arguments\&.  In the first form, the argument is mandatory,
+and in the second form it is optional\&.
+.RS
+.PP
+This group may be repeated for options which take multiple arguments\&.
+In other words,
+\fB:\fP\fImessage1\fP\fB:\fP\fIaction1\fP\fB:\fP\fImessage2\fP\fB:\fP\fIaction2\fP
+specifies that the option takes two arguments\&.
+.RE
+.TP
+.PD 0
+\fB:*\fP\fIpattern\fP\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD 0
+\fB:*\fP\fIpattern\fP\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD
+\fB:*\fP\fIpattern\fP\fB:::\fP\fImessage\fP\fB:\fP\fIaction\fP
+This describes multiple arguments\&.  Only the last \fIoptarg\fP for
+an option taking multiple arguments may be
+given in this form\&.  If the \fIpattern\fP is empty (i\&.e\&. \fB:*:\fP), all
+the remaining words on the line are to be completed as described by the
+\fIaction\fP; otherwise, all the words up to and including a word matching
+the \fIpattern\fP are to be completed using the \fIaction\fP\&.
+.RS
+.PP
+Multiple colons are treated as for the `\fB*:\fP\fI\&.\&.\&.\fP\&' forms for
+ordinary arguments:  when the \fImessage\fP is preceded by two colons,
+the \fBwords\fP special array and the \fBCURRENT\fP special parameter are
+modified during the execution or evaluation of the \fIaction\fP 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\&.
+.RE
+.RE
+.PP
+Any literal colon in an \fIoptname\fP, \fImessage\fP, or \fIaction\fP
+must be preceded by a backslash, `\fB\e:\fP\&'\&.
+.PP
+Each of the forms above may be preceded by a list in parentheses
+of option names and argument numbers\&.  If the given option is on
+the command line, the options and arguments indicated in parentheses
+will not be offered\&.  For example, 
+`\fB(\-two \-three 1)\-one:\fP\fI\&.\&.\&.\fP\&' completes the option `\fB\-one\fP'; if this
+appears on the command line, the options \fB\-two\fP and \fB\-three\fP and the
+first ordinary argument will not be completed after it\&.
+`\fB(\-foo):\fP\fI\&.\&.\&.\fP\&' specifies an ordinary argument completion;
+\fB\-foo\fP will not be completed if that argument is already present\&.
+.PP
+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 (\fB*\fP) for the rest arguments
+(i\&.e\&. a specification of the form `\fB*:\fP\fI\&.\&.\&.\fP\&'); a colon (\fB:\fP)
+for all normal (non\-option\-) arguments; and a hyphen (\fB\-\fP) for all
+options\&.  For example, if `\fB(*)\fP\&' 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 `\fB*:\fP\&') will not be
+completed\&.
+.PP
+To aid in reuse of specifications, it is possible to precede any of the
+forms above with `\fB!\fP\&'; 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 \fB_arguments\fP is called repeatedly for more
+specific contexts: on the first call `\fB_arguments $global_options\fP\&' is
+used, and on subsequent calls `\fB_arguments !$^global_options\fP\&'\&.
+.PP
+\fI\fIspec\fPs: actions\fP
+.PP
+In each of the forms above the \fIaction\fP determines how
+completions should be generated\&.  Except for the `\fB\->\fP\fIstring\fP\&'
+form below, the \fIaction\fP will be executed by calling the
+\fB_all_labels\fP function to process all tag labels\&.  No special handling
+of tags is needed unless a function call introduces a new one\&.
+.PP
+The functions called to execute \fIaction\fPs will be called with the
+elements of the array named by the `\fB\-O\fP \fIname\fP\&' option as arguments\&.
+This can be used, for example, to pass the same set of options for the
+\fBcompadd\fP builtin to all \fIaction\fPs\&.
+.PP
+The forms for \fIaction\fP are as follows\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB \fP(single unquoted space)
+This is useful where an argument is required but it is not possible or
+desirable to generate matches for it\&.  The
+\fImessage\fP will be displayed but no completions listed\&.  Note
+that even in this case the colon at the end of the \fImessage\fP is
+needed; it may only be omitted when neither a \fImessage\fP
+nor an \fIaction\fP is given\&.
+.TP
+\fB(\fP\fIitem1\fP \fIitem2\fP \fI\&.\&.\&.\fP\fB)\fP
+One of a list of possible matches, for example:
+.RS
+.PP
+.RS
+.nf
+\fB\fB:foo:(foo bar baz\fP\fB)\fP\fP
+.fi
+.RE
+.RE
+.TP
+\fB((\fIitem1\fP\e:\fIdesc1\fP \fI\&.\&.\&.\fP))\fP
+Similar to the above, but with descriptions for each possible match\&.
+Note the backslash before the colon\&.  For example,
+.RS
+.PP
+.RS
+.nf
+\fB\fB:foo:((a\e:bar b\e:baz\fP\fB))\fP\fP
+.fi
+.RE
+.PP
+The matches will be listed together with their descriptions if the
+\fBdescription\fP style is set with the \fBvalues\fP tag in the context\&.
+.RE
+.TP
+\fB\->\fP\fIstring\fP
+In this form, \fB_arguments\fP 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\&.
+.RS
+.PP
+Where \fB_arguments\fP encounters \fIaction\fP in the `\fB\->\fP\fIstring\fP\&'
+format, it will strip all leading and trailing whitespace from \fIstring\fP
+and set the array \fBstate\fP to the set of all \fIstring\fPs for which an
+action is to be performed\&.  The elements of the array \fBstate_descr\fP are
+assigned the corresponding \fImessage\fP field from each \fIoptarg\fP
+containing such an \fIaction\fP\&.
+.PP
+By default and in common with all other well behaved completion
+functions, _arguments returns status zero if it was able to add matches and
+non\-zero otherwise\&. However, if the \fB\-R\fP option is given,
+\fB_arguments\fP will instead return a status of 300 to indicate that
+\fB$state\fP is to be handled\&.
+.PP
+In addition to \fB$state\fP and \fB$state_descr\fP, \fB_arguments\fP also
+sets the global
+parameters `\fBcontext\fP\&', `\fBline\fP' and `\fBopt_args\fP' as described
+below, and does not reset any changes made to the special parameters
+such as \fBPREFIX\fP and \fBwords\fP\&.  This gives the calling function the
+choice of resetting these parameters or propagating changes in them\&.
+.PP
+A function calling \fB_arguments\fP with at least
+one action containing a `\fB\->\fP\fIstring\fP\&' must therefore declare
+appropriate local parameters:
+.PP
+.RS
+.nf
+\fBlocal context state state_descr line
+typeset \-A opt_args\fP
+.fi
+.RE
+.PP
+to prevent \fB_arguments\fP from altering the global environment\&.
+.RE
+.TP
+\fB{\fP\fIeval\-string\fP\fB}\fP
+A string in braces is evaluated as shell code to generate matches\&.  If the
+\fIeval\-string\fP itself does not begin with an opening parenthesis or
+brace it is split into separate words before execution\&.
+.TP
+\fB= \fP\fIaction\fP
+If the \fIaction\fP starts with `\fB= \fP\&' (an equals sign followed by a
+space), \fB_arguments\fP will insert the contents of the \fIargument\fP
+field of the current context as the new first element in the \fBwords\fP 
+special array and increment the value of the \fBCURRENT\fP 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\&.
+.RS
+.PP
+This is most useful with one of the specifiers that restrict the words on
+the command line on which the \fIaction\fP is to operate (the two\- and
+three\-colon forms above)\&.  One particular use is when an \fIaction\fP itself
+causes \fB_arguments\fP 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 \fB_arguments\fP to be able to parse the line\&.
+.RE
+.TP
+.PD 0
+\fI\fB \fPword\&.\&.\&.\fP
+.TP
+.PD
+\fIword\&.\&.\&.\fP
+This covers all forms other than those above\&.  If the \fIaction\fP
+starts with a space, the remaining list of words will be invoked unchanged\&.
+.RS
+.PP
+Otherwise it will be invoked with some extra strings placed after the
+first word; these are to be passed down as options to the \fBcompadd\fP
+builtin\&.  They ensure that the state specified by \fB_arguments\fP, in
+particular the descriptions of options and arguments, is correctly passed
+to the completion command\&.  These additional arguments
+are taken from the array parameter `\fBexpl\fP\&'; this will be set up
+before executing the \fIaction\fP and hence may be referred to inside it,
+typically in an expansion of the form `\fB$expl[@]\fP\&' which preserves empty
+elements of the array\&.
+.RE
+.PP
+During the performance of the action the array `\fBline\fP\&' will be set to
+the normal arguments from the command line, i\&.e\&. the words from the
+command line after the command name excluding all options and their
+arguments\&.  Options are stored in the associative array
+`\fBopt_args\fP\&' 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 and backslashes
+in the original arguments are preceded with backslashes\&.
+.PP
+The parameter `\fBcontext\fP\&' is set when returning to the calling function
+to perform an action of the form `\fB\->\fP\fIstring\fP\&'\&.  It is set to an
+array of elements corresponding to the elements of \fB$state\fP\&.  Each
+element is a suitable name for the argument field of the context: either a
+string of the form `\fBoption\fP\fI\-opt\fP\fB\-\fP\fIn\fP\&' for the \fIn\fP'th
+argument of the option \fI\-opt\fP, or a string of the form
+`\fBargument\-\fP\fIn\fP\&' for the \fIn\fP'th argument\&.  For `rest' arguments,
+that is those in the list at the end not handled by position, \fIn\fP is the
+string `\fBrest\fP\&'\&.  For example, when completing the argument of the \fB\-o\fP
+option, the name is `\fBoption\-o\-1\fP\&', while for the second normal
+(non\-option\-) argument it is `\fBargument\-2\fP\&'\&.
+.PP
+Furthermore, during the evaluation of the \fIaction\fP the context name in
+the \fBcurcontext\fP parameter is altered to append the same string that is
+stored in the \fBcontext\fP parameter\&.
+.PP
+The option \fB\-C\fP tells \fB_arguments\fP to modify the \fBcurcontext\fP
+parameter for an action of the form `\fB\->\fP\fIstate\fP\&'\&.  This is the
+standard parameter used to keep track of the current context\&.  Here it
+(and not the \fBcontext\fP array) 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:
+.PP
+.RS
+.nf
+\fBlocal curcontext="$curcontext"\fP
+.fi
+.RE
+.PP
+This is useful where it is not possible for multiple states to be valid
+together\&.
+.PP
+\fIGrouping Options\fP
+.PP
+Options can be grouped to simplify exclusion lists\&. A group is
+introduced with `\fB+\fP\&' followed by a name for the group in the
+subsequent word\&. Whole groups can then be referenced in an exclusion
+list or a group name can be used to disambiguate between two forms of
+the same option\&. For example:
+.PP
+.RS
+.nf
+\fB_arguments \e 
+    \&'(group2\-\-x)\-a' \e 
+  + group1 \e 
+    \-m \e 
+    \&'(group2)\-n' \e 
+  + group2 \e 
+    \-x \-y\fP
+.fi
+.RE
+.PP
+If the name of a group is specified in the form
+`\fB(\fP\fIname\fP\fB)\fP\&' then only one value from that group
+will ever be completed; more formally, all specifications are mutually
+exclusive to all other specifications in that group\&. This is useful for
+defining options that are aliases for each other\&. For example:
+.PP
+.RS
+.nf
+\fB_arguments \e 
+    \-a \-b \e 
+  + \&'(operation)' \e 
+    {\-c,\-\-compress}\&'[compress]' \e 
+    {\-d,\-\-decompress}\&'[decompress]' \e 
+    {\-l,\-\-list}\&'[list]'\fP
+.fi
+.RE
+.PP
+If an option in a group appears on the command line, it is stored in the
+associative array `\fBopt_args\fP\&' with '\fIgroup\fP\fB\-\fP\fIoption\fP'
+as a key\&.  In the example above, a key `\fBoperation\-\-c\fP\&' is used if the option
+`\fB\-c\fP\&' is present on the command line\&.
+.PP
+\fISpecifying Multiple Sets of Arguments\fP
+.PP
+It is possible to specify multiple sets of options and arguments with
+the sets separated by single hyphens\&. This differs from groups in that
+sets are considered to be mutually exclusive of each other\&.
+.PP
+Specifications before the first set and from any group are common to
+all sets\&. For example:
+.PP
+.RS
+.nf
+\fB_arguments \e 
+    \-a \e 
+  \- set1 \e 
+    \-c \e 
+  \- set2 \e 
+    \-d \e 
+    \&':arg:(x2 y2)'\fP
+.fi
+.RE
+.PP
+This defines two sets\&.  When the command line contains the option
+`\fB\-c\fP\&', the `\fB\-d\fP' option and the argument will not be considered
+possible completions\&.  When it contains `\fB\-d\fP\&' or an argument, the
+option `\fB\-c\fP\&' will not be considered\&.  However, after `\fB\-a\fP'
+both sets will still be considered valid\&.
+.PP
+As for groups, the name of a set may appear in exclusion lists, either
+alone or preceding a normal option or argument specification\&.
+.PP
+The completion code has to parse the command line separately for each
+set\&. This can be slow so sets should only be used when necessary\&.
+A useful alternative is often an option specification with rest\-arguments
+(as in `\fB\-foo:*:\&.\&.\&.\fP\&'); here the option \fB\-foo\fP swallows up all
+remaining arguments as described by the \fIoptarg\fP definitions\&.
+.PP
+\fIDeriving \fIspec\fP forms from the help output\fP
+.PP
+The option `\fB\-\fP\fB\-\fP\&' allows \fB_arguments\fP to work out the names of long
+options that support the `\fB\-\fP\fB\-help\fP\&' option which is standard in many
+GNU commands\&.  The command word is called with the argument
+`\fB\-\fP\fB\-help\fP\&' 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\&.
+.PP
+In addition to options, `\fB_arguments \-\fP\fB\-\fP\&' will try to deduce the
+types of arguments available for options when the form
+`\fB\-\fP\fB\-\fP\fIopt\fP\fB=\fP\fIval\fP\&' is valid\&.  It is also possible to provide
+hints by examining the help text of the command and adding \fIhelpspec\fP of
+the form `\fIpattern\fP\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP\&'; note that other
+\fB_arguments\fP \fIspec\fP forms are not used\&.  The \fIpattern\fP is matched
+against the help text for an option, and if it matches the \fImessage\fP and
+\fIaction\fP are used as for other argument specifiers\&.  The special case
+of `\fB*:\fP\&' means both \fImessage\fP and \fIaction\fP are empty, which has
+the effect of causing options having no description in the help output to
+be ordered in listings ahead of options that have a description\&.
+.PP
+For example:
+.PP
+.RS
+.nf
+\fB_arguments \-\- \&'*\e*:toggle:(yes no)' \e 
+              \&'*=FILE*:file:_files' \e 
+              \&'*=DIR*:directory:_files \-/' \e 
+              \&'*=PATH*:directory:_files \-/'\fP
+.fi
+.RE
+.PP
+Here, `\fByes\fP\&' and `\fBno\fP' will be completed as the argument of
+options whose description ends in a star; file names will be completed for
+options that contain the substring `\fB=FILE\fP\&' in the description; and
+directories will be completed for options whose description contains
+`\fB=DIR\fP\&' or `\fB=PATH\fP'\&.  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:
+.PP
+.RS
+.nf
+\fB  \-C, \-\-directory=DIR          change to directory DIR\fP
+.fi
+.RE
+.PP
+so that the above specifications will cause directories to be completed
+after `\fB\-\fP\fB\-directory\fP\&', though not after `\fB\-C\fP'\&.
+.PP
+Note also that \fB_arguments\fP tries to find out automatically if the
+argument for an option is optional\&.  This can be specified explicitly by
+doubling the colon before the \fImessage\fP\&.
+.PP
+If the \fIpattern\fP ends in `\fB(\-)\fP\&', this will be removed from the
+pattern and the \fIaction\fP will be used only directly after the
+`\fB=\fP\&', not in the next word\&.  This is the behaviour of a normal
+specification defined with the form `\fB=\-\fP\&'\&.
+.PP
+By default, the command (with the option `\fB\-\-help\fP\&') is run after
+resetting all the locale categories (except for \fBLC_CTYPE\fP) to `\fBC\fP\&'\&.
+If the localized help output is known to work, the option `\fB\-l\fP\&' can
+be specified after the `\fB_arguments \-\fP\fB\-\fP\&' so that the command is
+run in the current locale\&.
+.PP
+The `\fB_arguments \-\fP\fB\-\fP\&' can be followed by the option `\fB\-i\fP
+\fIpatterns\fP\&' 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,
+.PP
+.RS
+.nf
+\fB_arguments \-\- \-i \e 
+    "(\-\-(en|dis)able\-FEATURE*)"\fP
+.fi
+.RE
+.PP
+will cause completion to ignore the options
+`\fB\-\fP\fB\-enable\-FEATURE\fP\&' and `\fB\-\fP\fB\-disable\-FEATURE\fP' (this example is
+useful with GNU \fBconfigure\fP)\&.
+.PP
+The `\fB_arguments \-\fP\fB\-\fP\&' form can also be followed by the option `\fB\-s\fP
+\fIpair\fP\&' to describe option aliases\&.  The \fIpair\fP consists of a list
+of alternating patterns and corresponding replacements, enclosed in parens
+and quoted so that it forms a single argument word in the \fB_arguments\fP
+call\&.
+.PP
+For example, some \fBconfigure\fP\-script help output describes options only
+as `\fB\-\fP\fB\-enable\-foo\fP\&', but the script also accepts the negated form
+`\fB\-\fP\fB\-disable\-foo\fP\&'\&.  To allow completion of the second form:
+.PP
+.RS
+.nf
+\fB_arguments \-\- \-s "((#s)\-\-enable\- \-\-disable\-)"\fP
+.fi
+.RE
+.PP
+\fIMiscellaneous notes\fP
+.PP
+Finally, note that \fB_arguments\fP generally expects to be the primary
+function handling any completion for which it is used\&.  It may have side
+effects which change the treatment of any matches added by other functions
+called after it\&.  To combine \fB_arguments\fP with other functions, those
+functions should be called either before \fB_arguments\fP, as an \fIaction\fP
+within a \fIspec\fP, or in handlers for `\fB\->\fP\fIstate\fP\&' actions\&.
+.PP
+Here is a more general example of the use of \fB_arguments\fP:
+.PP
+.RS
+.nf
+\fB_arguments \&'\-l+:left border:' \e 
+           \&'\-format:paper size:(letter A4)' \e 
+           \&'*\-copy:output file:_files::resolution:(300 600)' \e 
+           \&':postscript file:_files \-g \e*\&.\e(ps\e|eps\e)' \e 
+           \&'*:page number:'\fP
+.fi
+.RE
+.PP
+This describes three options: `\fB\-l\fP\&', `\fB\-format\fP', and
+`\fB\-copy\fP\&'\&.  The first takes one argument described as `\fIleft
+border\fP\&' for which no completion will be offered because of the empty
+action\&.  Its argument may come directly after the `\fB\-l\fP\&' or it may be 
+given as the next word on the line\&.
+.PP
+The `\fB\-format\fP\&' option takes one
+argument in the next word, described as `\fIpaper size\fP\&' for which
+only the strings `\fBletter\fP\&' and `\fBA4\fP' will be completed\&.
+.PP
+The `\fB\-copy\fP\&' 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 `\fIresolution\fP\&') and will be completed from the strings
+`\fB300\fP\&' and `\fB600\fP'\&.
+.PP
+The last two descriptions say what should be completed as
+arguments\&.  The first describes the first argument as a
+`\fIpostscript file\fP\&' and makes files ending in `\fBps\fP' or `\fBeps\fP' 
+be completed\&.  The last description gives all other arguments the
+description `\fIpage numbers\fP\&' but does not offer completions\&.
+.RE
+.TP
+\fB_cache_invalid\fP \fIcache_identifier\fP
+This function returns status zero if the completions cache corresponding to
+the given cache identifier needs rebuilding\&.  It determines this by
+looking up the \fBcache\-policy\fP 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\&.
+.RS
+.PP
+Example:
+.PP
+.RS
+.nf
+\fB_example_caching_policy () {
+    # rebuild if cache is more than a week old
+    local \-a oldp
+    oldp=( "$1"(Nm+7) )
+    (( $#oldp ))
+}\fP
+.fi
+.RE
+.RE
+.TP
+\fB_call_function\fP \fIreturn\fP \fIname\fP [ \fIarg\fP \&.\&.\&. ]
+If a function \fIname\fP exists, it is called with the arguments
+\fIarg\fPs\&.  The \fIreturn\fP argument gives the name of a parameter in which
+the return status from the function \fIname\fP should be stored; if \fIreturn\fP
+is empty or a single hyphen it is ignored\&.
+.RS
+.PP
+The return status of \fB_call_function\fP itself is zero if the function
+\fIname\fP exists and was called and non\-zero otherwise\&.
+.RE
+.TP
+\fB_call_program\fP [ \fB\-l\fP ] [ \fB\-p\fP ] \fItag\fP \fIstring\fP \&.\&.\&.
+This function provides a mechanism for the user to override the use of an
+external command\&.  It looks up the \fBcommand\fP style with the supplied
+\fItag\fP\&.  If the style is set, its value is used as the command to
+execute\&.  The \fIstring\fPs from the call to \fB_call_program\fP, or from the
+style if set, are concatenated with spaces between them and the resulting
+string is evaluated\&.  The return status is the return status of the command
+called\&.
+.RS
+.PP
+By default, the command is run in an environment where all the locale
+categories (except for \fBLC_CTYPE\fP) are reset to `\fBC\fP\&' by calling the
+utility function \fB_comp_locale\fP (see below)\&. If the option `\fB\-l\fP\&' is
+given, the command is run with the current locale\&.
+.PP
+If the option `\fB\-p\fP\&' is supplied it indicates that the command
+output is influenced by the permissions it is run with\&. If the
+\fBgain\-privileges\fP style is set to true, \fB_call_program\fP will make
+use of commands such as \fBsudo\fP, if present on the command\-line, to
+match the permissions to whatever the final command is likely to run
+under\&. When looking up the \fBgain\-privileges\fP and \fBcommand\fP styles,
+the command component of the zstyle context will end with a slash
+(`\fB/\fP\&') followed by the command that would be used to gain privileges\&.
+.RE
+.TP
+\fB_combination\fP [ \fB\-s\fP \fIpattern\fP ] \fItag\fP \fIstyle\fP \fIspec\fP \&.\&.\&. \fIfield\fP \fIopts\fP \&.\&.\&.
+This function is used to complete combinations of values,  for example
+pairs of hostnames and usernames\&.  The \fIstyle\fP argument gives the style
+which defines the pairs; it is looked up in a context with the \fItag\fP
+specified\&.
+.RS
+.PP
+The style name consists of field names separated by hyphens, for example
+`\fBusers\-hosts\-ports\fP\&'\&.  For each field for a value is already known, a
+\fIspec\fP of the form `\fIfield\fP\fB=\fP\fIpattern\fP\&' is given\&.  For example,
+if the command line so far specifies a user `\fBpws\fP\&', the argument
+`\fBusers=pws\fP\&' should appear\&.
+.PP
+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
+\fIfield\fPs for which the value is known)\&.
+.PP
+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 values for the different fields are separated by colons\&.  This
+can be altered with the option \fB\-s\fP to \fB_combination\fP which specifies a
+pattern\&.  Typically this is a character class, as for example
+`\fB\-s "[:@]"\fP\&' in the case of the \fBusers\-hosts\fP style\&.    Each
+`\fIfield\fP\fB=\fP\fIpattern\fP\&' specification restricts the
+completions which apply to elements of the style with appropriately
+matching fields\&.
+.PP
+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\&.  For example, if there is no `\fBusers\-hosts\-ports\fP\&' or no
+matching hostname when a host is required, the function `\fB_hosts\fP\&' will
+automatically be called\&.
+.PP
+If the same name is used for more than one field, in both the
+`\fIfield\fP\fB=\fP\fIpattern\fP\&' 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\&.
+.PP
+All arguments after the required field name are passed to
+\fBcompadd\fP when generating matches from the style value, or to 
+the functions for the fields if they are called\&.
+.RE
+.TP
+\fB_command_names\fP [ \fB\-e\fP | \fB\-\fP ]
+This function completes words that are valid at command position: names of
+aliases, builtins, hashed commands, functions, and so on\&.  With the \fB\-e\fP
+flag, only hashed commands are completed\&.  The \fB\-\fP flag is ignored\&.
+.TP
+\fB_comp_locale\fP
+This function resets all the locale categories other than \fBLC_CTYPE\fP to
+`\fBC\fP\&' so that the output from external commands can be easily analyzed by
+the completion system\&. \fBLC_CTYPE\fP retains the current value (taking
+\fBLC_ALL\fP and \fBLANG\fP into account), ensuring that non\-ASCII characters
+in file names are still handled properly\&.
+.RS
+.PP
+This function should normally be run only in a subshell, because the new
+locale is exported to the environment\&. Typical usage would be
+`\fB$(_comp_locale; \fP\fIcommand\fP \&.\&.\&.\fB)\fP\&'\&.
+.RE
+.TP
+\fB_completers\fP [ \fB\-p\fP ]
+This function completes names of completers\&.
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fB\-p\fP
+Include the leading underscore (`\fB_\fP\&') in the matches\&.
+.RE
+
+.TP
+.PD 0
+\fB_describe \fP[\fB\-12JVx\fP] [ \fB\-oO\fP | \fB\-t\fP \fItag\fP ] \fIdescr\fP \fIname1\fP [ \fIname2\fP ] [ \fIopt\fP \&.\&.\&. ]
+.TP
+.PD
+\fB          \fP[ \fB\-\fP\fB\-\fP \fIname1\fP [ \fIname2\fP ] [ \fIopt\fP \&.\&.\&. ] \&.\&.\&. ]
+This function associates completions with descriptions\&.
+Multiple groups separated by \fB\-\fP\fB\-\fP can be supplied, potentially with
+different completion options \fIopt\fPs\&.
+.RS
+.PP
+The \fIdescr\fP is taken as a string to display above the matches if the
+\fBformat\fP style for the \fBdescriptions\fP tag is set\&.  This is followed by
+one or two names of arrays followed by options to pass to \fBcompadd\fP\&.  The
+array \fIname1\fP contains the possible completions with their descriptions in
+the form `\fIcompletion\fP\fB:\fP\fIdescription\fP\&'\&.  Any literal colons in
+\fIcompletion\fP must be quoted with a backslash\&.  If a \fIname2\fP is
+given, it should have the same number of elements as \fIname1\fP; in this
+case the corresponding elements are added as possible completions instead
+of the \fIcompletion\fP strings from \fIname1\fP\&.  The completion list
+will retain the descriptions from \fIname1\fP\&.  Finally, a set of
+completion options can appear\&.
+.PP
+If the option `\fB\-o\fP\&' appears before the first argument, the matches added
+will be treated as names of command options (N\&.B\&. not shell options),
+typically following a `\fB\-\fP\&', `\fB\-\fP\fB\-\fP' or `\fB+\fP' on the command
+line\&.  In this case \fB_describe\fP uses the \fBprefix\-hidden\fP,
+\fBprefix\-needed\fP and \fBverbose\fP styles to find out if the strings should
+be added as completions and if the descriptions should be shown\&.  Without
+the `\fB\-o\fP\&' option, only the \fBverbose\fP style is used to decide how
+descriptions are shown\&.  If `\fB\-O\fP\&' is used instead of `\fB\-o\fP', command
+options are completed as above but \fB_describe\fP will not handle the
+\fBprefix\-needed\fP style\&.
+.PP
+With the \fB\-t\fP option a \fItag\fP can be specified\&.  The default is
+`\fBvalues\fP\&' or, if the \fB\-o\fP option is given, `\fBoptions\fP'\&.
+.PP
+The options \fB\-1\fP, \fB\-2\fP, \fB\-J\fP, \fB\-V\fP, \fB\-x\fP are passed to
+\fB_next_label\fP\&.
+.PP
+If selected by the \fBlist\-grouped\fP style, strings with the same
+description will appear together in the list\&.
+.PP
+\fB_describe\fP uses the \fB_all_labels\fP function to generate the matches, so
+it does not need to appear inside a loop over tag labels\&.
+.RE
+.TP
+\fB_description\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP [ \fIspec\fP \&.\&.\&. ]
+This function is not to be confused with the previous one; it is used as
+a helper function for creating options to \fBcompadd\fP\&.  It is buried
+inside many of the higher level completion functions and so often does
+not need to be called directly\&.
+.RS
+.PP
+The styles listed below are tested in the current context using the
+given \fItag\fP\&.  The resulting options for \fBcompadd\fP are put into the
+array named \fIname\fP (this is traditionally `\fBexpl\fP\&', but this
+convention is not enforced)\&.  The description for the corresponding set
+of matches is passed to the function in \fIdescr\fP\&.
+.PP
+The styles tested are: \fBformat\fP, \fBhidden\fP, \fBmatcher\fP,
+\fBignore\-line\fP, \fBignored\-patterns\fP, \fBgroup\-name\fP and \fBsort\fP\&.
+The \fBformat\fP style is first tested for the given \fItag\fP and then for
+the \fBdescriptions\fP tag if no value was found, while the remainder are
+only tested for the tag given as the first argument\&.  The function also
+calls \fB_setup\fP which tests some more styles\&.
+.PP
+The string returned by the \fBformat\fP style (if any) will be modified so
+that the sequence `\fB%d\fP\&' is replaced by the \fIdescr\fP given as the third
+argument without any leading or trailing white space\&.  If, after
+removing the white space, the \fIdescr\fP is the empty string, the format
+style will not be used and the options put into the \fIname\fP array will
+not contain an explanation string to be displayed above the matches\&.
+.PP
+If \fB_description\fP is called with more than three arguments,
+the additional \fIspec\fPs should be of the form `\fIchar\fP\fB:\fP\fIstr\fP\&'\&.
+These supply escape sequence replacements for the \fBformat\fP style:
+every appearance of `\fB%\fP\fIchar\fP\&' will be
+replaced by \fIstring\fP\&.
+.PP
+If the \fB\-x\fP option is given, the description will be passed to
+\fBcompadd\fP using the \fB\-x\fP option instead of the default \fB\-X\fP\&.  This
+means that the description will be displayed even if there are no
+corresponding matches\&.
+.PP
+The options placed in the array \fIname\fP take account of the
+\fBgroup\-name\fP style, so matches are placed in a separate group where
+necessary\&.  The group normally has its elements sorted (by passing the
+option \fB\-J\fP to \fBcompadd\fP), but if an option starting with `\fB\-V\fP\&',
+`\fB\-J\fP\&', `\fB\-1\fP', or `\fB\-2\fP' is passed to \fB_description\fP, that
+option will be included in the array\&.  Hence it is possible for the
+completion group to be unsorted by giving the option `\fB\-V\fP\&',
+`\fB\-1V\fP\&', or `\fB\-2V\fP'\&.
+.PP
+In most cases, the function will be used like this:
+.PP
+.RS
+.nf
+\fBlocal expl
+_description files expl file
+compadd "$expl[@]" \- "$files[@]"\fP
+.fi
+.RE
+.PP
+Note the use of the parameter \fBexpl\fP, the hyphen, and the list of
+matches\&.  Almost all calls to \fBcompadd\fP within the completion system use
+a similar format; this ensures that user\-specified styles are correctly
+passed down to the builtins which implement the internals of completion\&.
+.RE
+.TP
+\fB_dir_list\fP [ \fB\-s\fP \fIsep\fP ] [ \fB\-S\fP ]
+Complete a list of directory names separated by colons
+(the same format as \fB$PATH\fP)\&.
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fB\-s\fP \fIsep\fP
+Use \fIsep\fP as separator between items\&.
+\fIsep\fP defaults to a colon (`\fB:\fP\&')\&.
+.TP
+\fB\-S\fP
+Add \fIsep\fP instead of slash (`\fB/\fP\&') as an autoremoveable suffix\&.
+.RE
+.TP
+\fB_dispatch\fP \fIcontext string\fP \&.\&.\&.
+This sets the current context to \fIcontext\fP and looks for completion
+functions to handle this context by hunting through the list of command
+names or special contexts (as described above for \fBcompdef\fP)
+given as \fIstring\fPs\&.  The first completion function to be defined
+for one of the contexts in the list is used to generate matches\&.
+Typically, the last \fIstring\fP is \fB\-default\-\fP to cause the function
+for default completion to be used as a fallback\&.
+.RS
+.PP
+The function sets the parameter
+\fB$service\fP to the \fIstring\fP being tried, and sets
+the \fIcontext/command\fP field (the fourth) of the \fB$curcontext\fP
+parameter to the \fIcontext\fP given as the first argument\&.
+.RE
+.TP
+\fB_email_addresses\fP [ \fB\-c\fP ] [ \fB\-n\fP \fIplugin\fP ]
+Complete email addresses\&.  Addresses are provided by plugins\&.
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fB\-c\fP
+Complete bare \fBlocalhost@domain\&.tld\fP addresses, without a name part or
+a comment\&.
+Without this option, RFC822 `\fIFirstname Lastname\fP \fB<\fP\fIaddress\fP\fB>\fP\&'
+strings are completed\&.
+.TP
+\fB\-n\fP \fIplugin\fP
+Complete aliases from \fIplugin\fP\&.  
+.PP
+The following plugins are available by default:
+\fB_email\-ldap\fP (see the \fBfilter\fP style),
+\fB_email\-local\fP (completes \fIuser\fP\fB@\fP\fIhostname\fP Unix addresses),
+\fB_email\-mail\fP (completes aliases from \fB~/\&.mailrc\fP),
+\fB_email\-mush\fP,
+\fB_email\-mutt\fP,
+and
+\fB_email\-pine\fP\&.
+.PP
+Addresses from the \fB_email\-\fP\fIfoo\fP plugin are added under the
+tag `\fBemail\-\fP\fIfoo\fP\&'\&.
+.PP
+\fIWriting plugins\fP
+.PP
+Plugins are written as separate functions with names starting with `\fB_email\-\fP\&'\&.
+They are invoked with the \fB\-c\fP option and \fBcompadd\fP options\&.
+They should either do their own completion or
+set the \fB$reply\fP array to a list of `\fIalias\fP\fB:\fP\fIaddress\fP\&' elements and return \fB300\fP\&.
+New plugins will be picked up and run automatically\&.
+.RE
+.TP
+\fB_files\fP
+The function \fB_files\fP is a wrapper around \fB_path_files\fP\&. It supports
+all of the same functionality, with some enhancements \-\- notably, it
+respects the \fBlist\-dirs\-first\fP style, and it allows users to override
+the behaviour of the \fB\-g\fP and \fB\-/\fP options with the \fBfile\-patterns\fP
+style\&. \fB_files\fP should therefore be preferred over \fB_path_files\fP in
+most cases\&.
+.RS
+.PP
+This function accepts the full set of options allowed by
+\fB_path_files\fP, described below\&.
+.RE
+.TP
+\fB_gnu_generic\fP
+This function is a simple wrapper around the \fB_arguments\fP function
+described above\&.  It can be used to determine automatically the long
+options understood by commands that produce a list when passed the
+option `\fB\-\fP\fB\-help\fP\&'\&.  It is intended to be used as a top\-level
+completion function in its own right\&.  For example, to enable option
+completion for the commands \fBfoo\fP and \fBbar\fP, use
+.RS
+.PP
+.RS
+.nf
+\fBcompdef _gnu_generic foo bar\fP
+.fi
+.RE
+.PP
+after the call to \fBcompinit\fP\&.
+.PP
+The completion system as supplied is conservative in its use of this
+function, since it is important to be sure the command understands the
+option `\fB\-\fP\fB\-help\fP\&'\&.
+.RE
+.TP
+\fB_guard\fP [ \fIoptions\fP ] \fIpattern descr\fP
+This function displays \fIdescr\fP if \fIpattern\fP matches the string to
+be completed\&.  It is intended to be used in the \fIaction\fP for the
+specifications passed to \fB_arguments\fP and similar functions\&.
+.RS
+.PP
+The return status is zero if the message was displayed and the word to
+complete is not empty, and non\-zero otherwise\&.
+.PP
+The \fIpattern\fP may be preceded by any of the options understood by
+\fBcompadd\fP that are passed down from \fB_description\fP, namely \fB\-M\fP,
+\fB\-J\fP, \fB\-V\fP, \fB\-1\fP, \fB\-2\fP, \fB\-n\fP, \fB\-F\fP and \fB\-X\fP\&.  All of these
+options will be ignored\&.  This fits in conveniently with the
+argument\-passing conventions of actions for \fB_arguments\fP\&.
+.PP
+As an example, consider a command taking the options \fB\-n\fP and
+\fB\-none\fP, where \fB\-n\fP must be followed by a numeric value in the
+same word\&.  By using:
+.PP
+.RS
+.nf
+\fB_arguments \&'\-n\-: :_guard "[0\-9]#" "numeric value"' '\-none'\fP
+.fi
+.RE
+.PP
+\fB_arguments\fP can be made to both display the message `\fBnumeric
+value\fP\&' and complete options after `\fB\-n<TAB>\fP'\&.  If the `\fB\-n\fP' is
+already followed by one or more digits (the pattern passed to
+\fB_guard\fP) only the message will be displayed; if the `\fB\-n\fP\&' is
+followed by another character, only options are completed\&.
+.RE
+.TP
+.PD 0
+\fB_message\fP [ \fB\-r12\fP ] [ \fB\-VJ\fP \fIgroup\fP ] \fIdescr\fP
+.TP
+.PD
+\fB_message \-e\fP [ \fItag\fP ] \fIdescr\fP
+The \fIdescr\fP is used in the same way as the third
+argument to the \fB_description\fP function, except that the resulting
+string will always be shown whether or not matches were
+generated\&.  This is useful for displaying a help message in places where
+no completions can be generated\&.
+.RS
+.PP
+The \fBformat\fP style is examined with the \fBmessages\fP tag to find a
+message; the usual tag, \fBdescriptions\fP, is used only if the style is
+not set with the former\&.
+.PP
+If the \fB\-r\fP option is given, no style is used; the \fIdescr\fP is
+taken literally as the string to display\&.  This is most useful
+when the \fIdescr\fP comes from a pre\-processed argument list
+which already contains an expanded description\&.  Note that this
+option does not disable the `\fB%\fP\&'\-sequence parsing done by
+\fBcompadd\fP\&.
+.PP
+The \fB\-12VJ\fP options and the \fIgroup\fP are passed to \fBcompadd\fP and
+hence determine the group the message string is added to\&.
+.PP
+The second \fB\-e\fP form gives a description for completions with the tag
+\fItag\fP to be shown even if there are no matches for that tag\&.  This form
+is called by \fB_arguments\fP in the event that there is no action for an
+option specification\&.  The tag can be omitted and if so the tag is taken
+from the parameter \fB$curtag\fP; this is maintained by the completion
+system and so is usually correct\&.  Note that if there are no matches at
+the time this function is called, \fBcompstate[insert]\fP is cleared, so
+additional matches generated later are not inserted on the command line\&.
+.RE
+.TP
+\fB_multi_parts\fP [ \fB\-i\fP ] \fIsep\fP \fIarray\fP
+The argument \fIsep\fP is a separator character\&.
+The \fIarray\fP may be either the
+name of an array parameter or a literal array in the form
+`\fB(foo bar\fP\fB)\fP\&', a parenthesised list of words separated
+by whitespace\&.  The possible completions are the
+strings from the array\&.  However, each chunk delimited by \fIsep\fP will be
+completed separately\&.  For example, the \fB_tar\fP function uses
+`\fB_multi_parts\fP \fB/\fP \fIpatharray\fP\&' to complete partial file paths
+from the given array of complete file paths\&.
+.RS
+.PP
+The \fB\-i\fP option causes \fB_multi_parts\fP to insert a unique match even
+if that requires multiple separators to be inserted\&.  This is not usually
+the expected behaviour with filenames, but certain other types of
+completion, for example those with a fixed set of possibilities, may be
+more suited to this form\&.
+.PP
+Like other utility functions, this function accepts the `\fB\-V\fP\&',
+`\fB\-J\fP\&', `\fB\-1\fP', `\fB\-2\fP', `\fB\-n\fP', `\fB\-f\fP', `\fB\-X\fP', `\fB\-M\fP',
+`\fB\-P\fP\&', `\fB\-S\fP', `\fB\-r\fP', `\fB\-R\fP', and `\fB\-q\fP' options and passes
+them to the \fBcompadd\fP builtin\&.
+.RE
+.TP
+\fB_next_label\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP [ \fIoption\fP \&.\&.\&. ]
+This function is used to implement the loop over different tag
+labels for a particular tag as described above for the \fBtag\-order\fP
+style\&.  On each call it checks to see if there are any more tag labels; if
+there is it returns status zero, otherwise non\-zero\&.
+As this function requires a current tag to be set, it must always follow
+a call to \fB_tags\fP or \fB_requested\fP\&.
+.RS
+.PP
+The \fB\-x12VJ\fP options and the first three arguments are passed to the
+\fB_description\fP function\&.  Where appropriate the \fItag\fP will be
+replaced by a tag label in this call\&.  Any description given in
+the \fBtag\-order\fP style is preferred to the \fIdescr\fP passed to
+\fB_next_label\fP\&.
+.PP
+The \fIoption\fPs given after the \fIdescr\fP
+are set in the parameter given by \fIname\fP, and hence are to be passed
+to \fBcompadd\fP or whatever function is called to add the matches\&.
+.PP
+Here is a typical use of this function for the tag \fBfoo\fP\&.  The call to
+\fB_requested\fP determines if tag \fBfoo\fP is required at all; the loop
+over \fB_next_label\fP handles any labels defined for the tag in the
+\fBtag\-order\fP style\&.
+.PP
+.RS
+.nf
+\fBlocal expl ret=1
+\&.\&.\&.
+if _requested foo; then
+  \&.\&.\&.
+  while _next_label foo expl \&'\&.\&.\&.'; do
+    compadd "$expl[@]" \&.\&.\&. && ret=0
+  done
+  \&.\&.\&.
+fi
+return ret\fP
+.fi
+.RE
+.RE
+.TP
+\fB_normal\fP [ \fB\-P\fP | \fB\-p\fP \fIprecommand\fP ]
+This is the standard function called to handle completion outside
+any special \fB\-\fP\fIcontext\fP\fB\-\fP\&.  It is called both to complete the command
+word and also the arguments for a command\&.  In the second case,
+\fB_normal\fP looks for a special completion for that command, and if
+there is none it uses the completion for the \fB\-default\-\fP context\&.
+.RS
+.PP
+A second use is to reexamine the command line specified by the \fB$words\fP
+array and the \fB$CURRENT\fP parameter after those have been modified\&.
+For example, the function \fB_precommand\fP, which
+completes after precommand specifiers such as \fBnohup\fP, removes the
+first word from the \fBwords\fP array, decrements the \fBCURRENT\fP parameter,
+then calls `\fB_normal \-p $service\fP\&'\&.  The effect is that
+`\fBnohup\fP \fIcmd \&.\&.\&.\fP\&' is treated in the same way as `\fIcmd \&.\&.\&.\fP'\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB\-P\fP
+Reset the list of precommands\&. This option should be used if completing
+a command line which allows internal commands (e\&.g\&. builtins and
+functions) regardless of prior precommands (e\&.g\&. `\fBzsh \-c\fP\&')\&.
+.TP
+\fB\-p\fP \fIprecommand\fP
+Append \fIprecommand\fP to the list of precommands\&. This option should be
+used in nearly all cases in which \fB\-P\fP is not applicable\&.
+.PP
+If the command name matches one of the patterns given by one of the
+options \fB\-p\fP or \fB\-P\fP to \fBcompdef\fP, the corresponding completion
+function is called and then the parameter \fB_compskip\fP is
+checked\&.  If it is set completion is terminated at that point even if
+no matches have been found\&.  This is the same effect as in the
+\fB\-first\-\fP context\&.
+.RE
+.TP
+\fB_options\fP
+This can be used to complete the names of shell options\&.  It provides a
+matcher specification that ignores a leading `\fBno\fP\&', ignores
+underscores and allows upper\-case letters to
+match their lower\-case counterparts (for example, `\fBglob\fP\&',
+`\fBnoglob\fP\&', `\fBNO_GLOB\fP' are all completed)\&.  Any arguments
+are propagated to the \fBcompadd\fP builtin\&.
+.TP
+\fB_options_set\fP and \fB_options_unset\fP
+These functions complete only set or unset options, with the same
+matching specification used in the \fB_options\fP function\&.
+.RS
+.PP
+Note that you need to uncomment a few lines in the \fB_main_complete\fP
+function for these functions to work properly\&.  The lines in question
+are used to store the option settings in effect before the completion
+widget locally sets the options it needs\&.  Hence these functions are not
+generally used by the completion system\&.
+.RE
+.TP
+\fB_parameters\fP
+This is used to complete the names of shell parameters\&.
+.RS
+.PP
+The option `\fB\-g\fP \fIpattern\fP\&' limits the completion to parameters
+whose type matches the \fIpattern\fP\&.  The type of a parameter is that
+shown by `\fBprint ${(t)\fP\fIparam\fP\fB}\fP\&', hence judicious use of
+`\fB*\fP\&' in \fIpattern\fP is probably necessary\&.
+.PP
+All other arguments are passed to the \fBcompadd\fP builtin\&.
+.RE
+.TP
+\fB_path_files\fP
+This function is used throughout the completion system
+to complete filenames\&.  It allows completion of partial paths\&.  For
+example, the string `\fB/u/i/s/sig\fP\&' may be completed to
+`\fB/usr/include/sys/signal\&.h\fP\&'\&.
+.RS
+.PP
+The options accepted by both \fB_path_files\fP and \fB_files\fP are:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-f\fP
+Complete all filenames\&.  This is the default\&.
+.TP
+\fB\-/\fP
+Specifies that only directories should be completed\&.
+.TP
+\fB\-g\fP \fIpattern\fP
+Specifies that only files matching the \fIpattern\fP should be completed\&.
+.TP
+\fB\-W\fP \fIpaths\fP
+Specifies path prefixes that are to be prepended to the string from the
+command line to generate the filenames but that should not be inserted
+as completions nor shown in completion listings\&.  Here, \fIpaths\fP may be
+the name of an array parameter, a literal list of paths enclosed in
+parentheses or an absolute pathname\&.
+.TP
+\fB\-F\fP \fIignored\-files\fP
+This behaves as for the corresponding option to the \fBcompadd\fP builtin\&.
+It gives direct control over which
+filenames should be ignored\&.  If the option is not present, the
+\fBignored\-patterns\fP style is used\&.
+.PP
+Both \fB_path_files\fP and \fB_files\fP also accept the following options
+which are passed to \fBcompadd\fP: `\fB\-J\fP\&', `\fB\-V\fP',
+`\fB\-1\fP\&', `\fB\-2\fP', `\fB\-n\fP', `\fB\-X\fP', `\fB\-M\fP', `\fB\-P\fP', `\fB\-S\fP',
+`\fB\-q\fP\&', `\fB\-r\fP', and `\fB\-R\fP'\&.
+.PP
+Finally, the \fB_path_files\fP function  uses the styles \fBexpand\fP,
+\fBambiguous\fP, \fBspecial\-dirs\fP, \fBlist\-suffixes\fP and \fBfile\-sort\fP
+described above\&.
+.RE
+
+.TP
+.PD 0
+\fB_pick_variant \fP[ \fB\-b\fP \fIbuiltin\-label\fP ] [ \fB\-c\fP \fIcommand\fP ] [ \fB\-r\fP \fIname\fP ]
+.TP
+.PD
+\fB              \fP\fIlabel\fP\fB=\fP\fIpattern\fP \&.\&.\&. \fIlabel\fP [ \fIarg\fP \&.\&.\&. ]
+This function is used to resolve situations where a single command name
+requires more than one type of handling, either because it
+has more than one variant or because there is a name clash between two
+different commands\&.
+.RS
+.PP
+The command to run is taken from the first element of the array
+\fBwords\fP unless this is overridden by the option \fB\-c\fP\&.  This command
+is run and its output is compared with a series of patterns\&.  Arguments
+to be passed to the command can be specified at the end after all the
+other arguments\&.  The patterns to try in order are given by the arguments
+\fIlabel\fP\fB=\fP\fIpattern\fP; if the output of `\fIcommand\fP \fIarg\fP
+\&.\&.\&.\&' contains \fIpattern\fP, then \fIlabel\fP is selected as the label
+for the command variant\&.  If none of the patterns match, the final
+command label is selected and status 1 is returned\&.
+.PP
+If the `\fB\-b\fP \fIbuiltin\-label\fP\&' is given, the command is tested to
+see if it is provided as a shell builtin, possibly autoloaded; if so,
+the label \fIbuiltin\-label\fP is selected as the label for the variant\&.
+.PP
+If the `\fB\-r\fP \fIname\fP\&' is given, the \fIlabel\fP picked is stored in
+the parameter named \fIname\fP\&.
+.PP
+The results are also cached in the \fB_cmd_variant\fP associative array
+indexed by the name of the command run\&.
+.RE
+.TP
+\fB_regex_arguments\fP \fIname\fP \fIspec\fP \&.\&.\&.
+This function generates a completion function \fIname\fP which matches
+the specifications \fIspec\fPs, a set of regular expressions as
+described below\&.  After running \fB_regex_arguments\fP, the function
+\fIname\fP should be called as a normal completion function\&.
+The pattern to be matched is given by the contents of
+the \fBwords\fP array up to the current cursor position joined together
+with null characters; no quotation is applied\&.
+.RS
+.PP
+The arguments are grouped as sets of alternatives separated by `\fB|\fP\&',
+which are tried one after the other until one matches\&.  Each alternative
+consists of a one or more specifications which are tried left to right,
+with each pattern matched being stripped in turn from the command line
+being tested, until all of the group succeeds or until one fails; in the
+latter case, the next alternative is tried\&.  This structure can be
+repeated to arbitrary depth by using parentheses; matching proceeds from
+inside to outside\&.
+.PP
+A special procedure is applied if no test succeeds but the remaining
+command line string contains no null character (implying the remaining
+word is the one for which completions are to be generated)\&.  The
+completion target is restricted to the remaining word and any
+\fIaction\fPs for the corresponding patterns are executed\&.  In this case,
+nothing is stripped from the command line string\&.  The order of
+evaluation of the \fIaction\fPs can be determined by the \fBtag\-order\fP
+style; the various formats supported by \fB_alternative\fP can be used
+in \fIaction\fP\&.  The \fIdescr\fP is used for setting up the array
+parameter \fBexpl\fP\&.
+.PP
+Specification arguments take one of following forms, in which
+metacharacters such as `\fB(\fP\&', `\fB)\fP', `\fB#\fP' and `\fB|\fP'
+should be quoted\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB/\fP\fIpattern\fP\fB/\fP [\fB%\fP\fIlookahead\fP\fB%\fP] [\fB\-\fP\fIguard\fP] [\fB:\fP\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP]
+This is a single primitive component\&.
+The function tests whether the combined pattern
+`\fB(#b)((#B)\fP\fIpattern\fP\fB)\fP\fIlookahead\fP\fB*\fP\&' matches
+the command line string\&.  If so, `\fIguard\fP\&' is evaluated and
+its return status is examined to determine if the test has succeeded\&.
+The \fIpattern\fP string `\fB[]\fP\&' is guaranteed never to match\&.
+The \fIlookahead\fP is not stripped from the command line before the next
+pattern is examined\&.
+.RS
+.PP
+The argument starting with \fB:\fP is used in the same manner as an argument to
+\fB_alternative\fP\&.
+.PP
+A component is used as follows: \fIpattern\fP is tested to
+see if the component already exists on the command line\&.  If
+it does, any following specifications are examined to find something to
+complete\&.  If a component is reached but no such pattern exists yet on the
+command line, the string containing the \fIaction\fP is used to generate
+matches to insert at that point\&.
+.RE
+.TP
+\fB/\fP\fIpattern\fP\fB/+\fP [\fB%\fP\fIlookahead\fP\fB%\fP] [\fB\-\fP\fIguard\fP] [\fB:\fP\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP]
+This is similar to `\fB/\fP\fIpattern\fP\fB/\fP \&.\&.\&.\&' but the left part of the
+command line string (i\&.e\&. the part already matched by previous patterns)
+is also considered part of the completion target\&.
+.TP
+\fB/\fP\fIpattern\fP\fB/\-\fP [\fB%\fP\fIlookahead\fP\fB%\fP] [\fB\-\fP\fIguard\fP] [\fB:\fP\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP]
+This is similar to `\fB/\fP\fIpattern\fP\fB/\fP \&.\&.\&.\&' but the \fIaction\fPs of the
+current and previously matched patterns are ignored even if the
+following `\fIpattern\fP\&' matches the empty string\&.
+.TP
+\fB(\fP \fIspec\fP \fB)\fP
+Parentheses may be used to groups \fIspec\fPs; note each parenthesis
+is a single argument to \fB_regex_arguments\fP\&.
+.TP
+\fIspec\fP \fB#\fP
+This allows any number of repetitions of \fIspec\fP\&.
+.TP
+\fIspec\fP \fIspec\fP
+The two \fIspec\fPs are to be matched one after the other as described
+above\&.
+.TP
+\fIspec\fP \fB|\fP \fIspec\fP
+Either of the two \fIspec\fPs can be matched\&.
+.PP
+The function \fB_regex_words\fP can be used as a helper function to
+generate matches for a set of alternative words possibly with
+their own arguments as a command line argument\&.
+.PP
+Examples:
+.PP
+.RS
+.nf
+\fB_regex_arguments _tst /$\&'[^\e0]#\e0'/ \e 
+    /$\&'[^\e0]#\e0'/ :'compadd aaa'\fP
+.fi
+.RE
+.PP
+This generates a function \fB_tst\fP that completes \fBaaa\fP as its only
+argument\&.  The \fItag\fP and \fIdescription\fP for the action have been
+omitted for brevity (this works but is not recommended in normal use)\&.
+The first component matches the command word, which is arbitrary; the
+second matches  any argument\&.  As the argument is also arbitrary, any
+following component would not depend on \fBaaa\fP being present\&.
+.PP
+.RS
+.nf
+\fB_regex_arguments _tst /$\&'[^\e0]#\e0'/ \e 
+    /$\&'aaa\e0'/ :'compadd aaa'\fP
+.fi
+.RE
+.PP
+This is a more typical use; it is similar, but any following patterns
+would only match if \fBaaa\fP was present as the first argument\&.
+.PP
+.RS
+.nf
+\fB_regex_arguments _tst /$\&'[^\e0]#\e0'/ \e( \e 
+    /$\&'aaa\e0'/ :'compadd aaa' \e 
+    /$\&'bbb\e0'/ :'compadd bbb' \e) \e#\fP
+.fi
+.RE
+.PP
+In this example, an indefinite number of command arguments may be
+completed\&.  Odd arguments are completed as \fBaaa\fP and even arguments
+as \fBbbb\fP\&.  Completion fails unless the set of \fBaaa\fP and \fBbbb\fP
+arguments before the current one is matched correctly\&.
+.PP
+.RS
+.nf
+\fB_regex_arguments _tst /$\&'[^\e0]#\e0'/ \e 
+    \e( /$\&'aaa\e0'/ :'compadd aaa' \e| \e 
+    /$\&'bbb\e0'/ :'compadd bbb' \e) \e#\fP
+.fi
+.RE
+.PP
+This is similar, but either \fBaaa\fP or \fBbbb\fP may be completed for
+any argument\&.  In this case \fB_regex_words\fP could be used to generate
+a suitable expression for the arguments\&.
+.PP
+.RE
+.TP
+\fB_regex_words\fP \fItag\fP \fIdescription\fP \fIspec\fP \&.\&.\&.
+This function can be used to generate arguments for the
+\fB_regex_arguments\fP command which may be inserted at any point where
+a set of rules is expected\&.  The \fItag\fP and \fIdescription\fP give a
+standard tag and description pertaining to the current context\&.  Each
+\fIspec\fP contains two or three arguments separated by a colon: note
+that there is no leading colon in this case\&.
+.RS
+.PP
+Each \fIspec\fP gives one of a set of words that may be completed at
+this point, together with arguments\&.  It is thus roughly equivalent to
+the \fB_arguments\fP function when used in normal (non\-regex) completion\&.
+.PP
+The part of the \fIspec\fP before the first colon is the word to be
+completed\&.  This may contain a \fB*\fP; the entire word, before and after
+the \fB*\fP is completed, but only the text before the \fB*\fP is required
+for the context to be matched, so that further arguments may be
+completed after the abbreviated form\&.
+.PP
+The second part of \fIspec\fP is a description for the word being
+completed\&.
+.PP
+The optional third part of the \fIspec\fP describes how words following
+the one being completed are themselves to be completed\&.  It will be
+evaluated in order to avoid problems with quoting\&.  This means that
+typically it contains a reference to an array containing previously
+generated regex arguments\&.
+.PP
+The option \fB\-t\fP \fIterm\fP specifies a terminator for the word
+instead of the usual space\&.  This is handled as an auto\-removable suffix
+in the manner of the option \fB\-s\fP \fIsep\fP to \fB_values\fP\&.
+.PP
+The result of the processing by \fB_regex_words\fP is placed in the array
+\fBreply\fP, which should be made local to the calling function\&.
+If the set of words and arguments may be matched repeatedly, a \fB#\fP
+should be appended to the generated array at that point\&.
+.PP
+For example:
+.PP
+.RS
+.nf
+\fBlocal \-a reply
+_regex_words mydb\-commands \&'mydb commands' \e 
+  \&'add:add an entry to mydb:$mydb_add_cmds' \e 
+  \&'show:show entries in mydb'
+_regex_arguments _mydb "$reply[@]"
+_mydb "$@"\fP
+.fi
+.RE
+.PP
+This shows a completion function for a command \fBmydb\fP which takes
+two command arguments, \fBadd\fP and \fBshow\fP\&.  \fBshow\fP takes no arguments,
+while the arguments for \fBadd\fP have already been prepared in an
+array \fBmydb_add_cmds\fP, quite possibly by a previous call to
+\fB_regex_words\fP\&.
+.RE
+.TP
+\fB_requested\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP [ \fIname\fP \fIdescr\fP [ \fIcommand\fP [ \fIarg\fP \&.\&.\&. ] ]
+This function is called to decide whether a tag already registered by a
+call to \fB_tags\fP (see below) has been requested by the user and hence
+completion should be performed for it\&.  It returns status zero if the
+tag is requested and non\-zero otherwise\&.  The function is typically used
+as part of a loop over different tags as follows:
+.RS
+.PP
+.RS
+.nf
+\fB_tags foo bar baz
+while _tags; do
+  if _requested foo; then
+    \&.\&.\&. # perform completion for foo
+  fi
+  \&.\&.\&. # test the tags bar and baz in the same way
+  \&.\&.\&. # exit loop if matches were generated
+done\fP
+.fi
+.RE
+.PP
+Note that the test for whether matches were generated is not performed
+until the end of the \fB_tags\fP loop\&.  This is so that the user can set
+the \fBtag\-order\fP style to specify a set of tags to be completed at the
+same time\&.
+.PP
+If \fIname\fP and \fIdescr\fP are given, \fB_requested\fP calls the
+\fB_description\fP function with these arguments together with the options
+passed to \fB_requested\fP\&.
+.PP
+If \fIcommand\fP is given, the \fB_all_labels\fP function will be called
+immediately with the same arguments\&.  In simple cases this makes it
+possible to perform the test for the tag and the matching in one go\&.
+For example:
+.PP
+.RS
+.nf
+\fBlocal expl ret=1
+_tags foo bar baz
+while _tags; do
+  _requested foo expl \&'description' \e 
+      compadd foobar foobaz && ret=0
+  \&.\&.\&.
+  (( ret )) || break
+done\fP
+.fi
+.RE
+.PP
+If the \fIcommand\fP is not \fBcompadd\fP, it must nevertheless be prepared
+to handle the same options\&.
+.RE
+.TP
+\fB_retrieve_cache\fP \fIcache_identifier\fP
+This function retrieves completion information from the file given by
+\fIcache_identifier\fP, stored in a directory specified by the
+\fBcache\-path\fP style which defaults to \fB~/\&.zcompcache\fP\&.  The return status
+is zero if retrieval was successful\&.  It will only attempt retrieval
+if the \fBuse\-cache\fP style is set, so you can call this function
+without worrying about whether the user wanted to use the caching
+layer\&.
+.RS
+.PP
+See \fB_store_cache\fP below for more details\&.
+.RE
+.TP
+\fB_sep_parts\fP
+This function is passed alternating arrays and separators as arguments\&.
+The arrays specify completions for parts of strings to be separated by the
+separators\&.  The arrays may be the names of array parameters or
+a quoted list of words in parentheses\&.  For example, with the array
+`\fBhosts=(ftp news)\fP\&' the call `\fB_sep_parts '(foo bar)' @ hosts\fP' will
+complete the string  `\fBf\fP\&' to `\fBfoo\fP' and the string `\fBb@n\fP' to
+`\fBbar@news\fP\&'\&.
+.RS
+.PP
+This function accepts the \fBcompadd\fP options `\fB\-V\fP\&', `\fB\-J\fP',
+`\fB\-1\fP\&', `\fB\-2\fP', `\fB\-n\fP', `\fB\-X\fP', `\fB\-M\fP', `\fB\-P\fP', `\fB\-S\fP',
+`\fB\-r\fP\&', `\fB\-R\fP', and `\fB\-q\fP' and passes them on to the \fBcompadd\fP
+builtin used to add the matches\&.
+.RE
+.TP
+\fB_sequence\fP [ \fB\-s\fP \fIsep\fP ] [ \fB\-n\fP \fImax\fP ] [ \fB\-d\fP ] \fIfunction\fP [ \fB\-\fP ] \&.\&.\&.
+This function is a wrapper to other functions for completing items in a
+separated list\&. The same function is used to complete each item in the
+list\&. The separator is specified with the \fB\-s\fP option\&. If \fB\-s\fP is
+omitted it will use `\fB,\fP\&'\&. Duplicate values are not matched unless
+\fB\-d\fP is specified\&. If there is a fixed or maximum number of items in
+the list, this can be specified with the \fB\-n\fP option\&.
+.RS
+.PP
+Common \fBcompadd\fP options are passed on to the function\&. It is possible
+to use \fBcompadd\fP directly with \fB_sequence\fP, though \fB_values\fP may
+be more appropriate in this situation\&.
+.RE
+.TP
+\fB_setup\fP \fItag\fP [ \fIgroup\fP ]
+This function sets up the special
+parameters used by the completion system appropriately for the \fItag\fP
+given as the first argument\&.  It uses the styles \fBlist\-colors\fP,
+\fBlist\-packed\fP, \fBlist\-rows\-first\fP, \fBlast\-prompt\fP, \fBaccept\-exact\fP,
+\fBmenu\fP and \fBforce\-list\fP\&.
+.RS
+.PP
+The optional \fIgroup\fP supplies the name of the group in which the
+matches will be placed\&.  If it is not given, the \fItag\fP is used as
+the group name\&.
+.PP
+This function is called automatically from \fB_description\fP
+and hence is not normally called explicitly\&.
+.RE
+.TP
+\fB_store_cache\fP \fIcache_identifier\fP \fIparam\fP \&.\&.\&.
+This function, together with \fB_retrieve_cache\fP and
+\fB_cache_invalid\fP, implements a caching layer which can be used
+in any completion function\&.  Data obtained by
+costly operations are stored in parameters;
+this function then dumps the values of those parameters to a file\&.  The
+data can then be retrieved quickly from that file via \fB_retrieve_cache\fP,
+even in different instances of the shell\&.
+.RS
+.PP
+The \fIcache_identifier\fP specifies the file which the data should be
+dumped to\&.  The file is stored in a directory specified by the
+\fBcache\-path\fP style which defaults to \fB~/\&.zcompcache\fP\&.  The remaining
+\fIparam\fPs arguments are the parameters to dump to the file\&.
+.PP
+The return status is zero if storage was successful\&.  The function will
+only attempt storage if the \fBuse\-cache\fP style is set, so you can
+call this function without worrying about whether the user wanted to
+use the caching layer\&.
+.PP
+The completion function may avoid calling \fB_retrieve_cache\fP when it
+already has the completion data available as parameters\&. 
+However, in that case it should
+call \fB_cache_invalid\fP to check whether the data in the parameters and
+in the cache are still valid\&.
+.PP
+See the _perl_modules completion function for a simple example of
+the usage of the caching layer\&.
+.RE
+.TP
+\fB_tags\fP [ [ \fB\-C\fP \fIname\fP ] \fItag\fP \&.\&.\&. ]
+If called with arguments, these are taken to be the names of tags
+valid for completions in the current context\&.  These tags are stored
+internally and sorted by using the \fBtag\-order\fP style\&.
+.RS
+.PP
+Next, \fB_tags\fP is called repeatedly without arguments from the same
+completion function\&.  This successively selects the first, second,
+etc\&. set of tags requested by the user\&.  The return status is zero if at
+least one of the tags is requested and non\-zero otherwise\&.  To test if a
+particular tag is to be tried, the \fB_requested\fP function should be
+called (see above)\&.
+.PP
+If `\fB\-C\fP \fIname\fP\&' is given, \fIname\fP is temporarily stored in the
+\fIargument\fP field (the fifth) of the context in the \fBcurcontext\fP parameter
+during the call to \fB_tags\fP; the field is restored on exit\&.  This
+allows \fB_tags\fP to use a more 
+specific context without having to change and reset the
+\fBcurcontext\fP parameter (which has the same effect)\&.
+.RE
+.TP
+\fB_tilde_files\fP
+Like \fB_files\fP, but resolve leading tildes according to the rules of
+filename expansion, so the suggested completions don\&'t start with
+a `\fB~\fP\&' even if the filename on the command\-line does\&.
+.TP
+\fB_values\fP [ \fB\-O\fP \fIname\fP ] [ \fB\-s\fP \fIsep\fP ] [ \fB\-S\fP \fIsep\fP ] [ \fB\-wC\fP ] \fIdesc\fP \fIspec\fP \&.\&.\&.
+This is used to complete arbitrary keywords (values) and their arguments,
+or lists of such combinations\&.
+.RS
+.PP
+If the first argument is the option `\fB\-O\fP \fIname\fP\&', it will be used
+in the same way as by the \fB_arguments\fP function\&.  In other words, the
+elements of the \fIname\fP array will be passed to \fBcompadd\fP
+when executing an action\&.
+.PP
+If the first argument (or the first argument after `\fB\-O\fP \fIname\fP\&')
+is `\fB\-s\fP\&', the next argument is used as the character that separates
+multiple values\&.  This character is automatically added after each value
+in an auto\-removable fashion (see below); all values completed by
+`\fB_values \-s\fP\&' appear in the same word on the command line, unlike
+completion using \fB_arguments\fP\&.  If this option is not present, only a
+single value will be completed per word\&.
+.PP
+Normally, \fB_values\fP will only use the current word to determine
+which values are already present on the command line and hence are not
+to be completed again\&.  If the \fB\-w\fP option is given, other arguments
+are examined as well\&.
+.PP
+The first non\-option argument, \fIdesc\fP, is used as a string to print as a
+description before listing the values\&.
+.PP
+All other arguments describe the possible values and their
+arguments in the same format used for the description of options by
+the \fB_arguments\fP function (see above)\&.  The only differences are that
+no minus or plus sign is required at the beginning,
+values can have only one argument, and the forms of action
+beginning with an equal sign are not supported\&.
+.PP
+The character separating a value from its argument can be set using the
+option \fB\-S\fP (like \fB\-s\fP, followed by the character to use as the
+separator in the next argument)\&.  By default the equals
+sign will be used as the separator between values and arguments\&.
+.PP
+Example:
+.PP
+.RS
+.nf
+\fB_values \-s , \&'description' \e 
+        \&'*foo[bar]' \e 
+        \&'(two)*one[number]:first count:' \e 
+        \&'two[another number]::second count:(1 2 3)'\fP
+.fi
+.RE
+.PP
+This describes three possible values: `\fBfoo\fP\&', `\fBone\fP', and
+`\fBtwo\fP\&'\&.  The first is described as `\fBbar\fP', takes no argument 
+and may appear more than once\&.  The second is described as
+`\fBnumber\fP\&', may appear more than once, and takes one mandatory
+argument described as `\fBfirst count\fP\&'; no action is
+specified, so it will not be completed\&.  The
+`\fB(two)\fP\&' at the beginning says that if the value `\fBone\fP' is on
+the line, the value `\fBtwo\fP\&' will no longer be considered a possible
+completion\&.  Finally, the last value (`\fBtwo\fP\&') is described
+as `\fBanother number\fP\&' and takes an optional argument described as
+`\fBsecond count\fP\&' for which the completions (to appear after an
+`\fB=\fP\&') are `\fB1\fP', `\fB2\fP', and `\fB3\fP'\&.  The \fB_values\fP function
+will complete lists of these values separated by commas\&.
+.PP
+Like \fB_arguments\fP, this function temporarily adds another context name
+component to the arguments element (the fifth) of the current context
+while executing the \fIaction\fP\&.  Here this name is just the name of the
+value for which the argument is completed\&.
+.PP
+The style \fBverbose\fP is used to decide if the descriptions for the
+values (but not those for the arguments) should be printed\&.
+.PP
+The associative array \fBval_args\fP is used to report values and their
+arguments; this works similarly to the \fBopt_args\fP associative array
+used by \fB_arguments\fP\&.  Hence the function calling \fB_values\fP should
+declare the local parameters \fBstate\fP, \fBstate_descr\fP, \fBline\fP,
+\fBcontext\fP and \fBval_args\fP:
+.PP
+.RS
+.nf
+\fBlocal context state state_descr line
+typeset \-A val_args\fP
+.fi
+.RE
+.PP
+when using an action of the form `\fB\->\fP\fIstring\fP\&'\&.  With this
+function the \fBcontext\fP parameter will be set to the name of the
+value whose argument is to be completed\&.  Note that for \fB_values\fP,
+the \fBstate\fP and \fBstate_descr\fP are scalars rather than arrays\&.
+Only a single matching state is returned\&.
+.PP
+Note also that \fB_values\fP normally adds the character used as the
+separator between values as an auto\-removable suffix (similar to a
+`\fB/\fP\&' after a directory)\&.  However, this is not possible for a
+`\fB\->\fP\fIstring\fP\&' action as the matches for the argument are
+generated by the calling function\&.  To get the usual behaviour,
+the calling function can add the separator \fIx\fP as a suffix by
+passing the options `\fB\-qS\fP \fIx\fP\&' either directly or indirectly to
+\fBcompadd\fP\&.
+.PP
+The option \fB\-C\fP is treated in the same way as it is by \fB_arguments\fP\&.
+In that case the parameter \fBcurcontext\fP should be made local instead 
+of \fBcontext\fP (as described above)\&.
+.RE
+.TP
+\fB_wanted\fP [ \fB\-x\fP ] [ \fB\-C\fP \fIname\fP ]  [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP \fIcommand\fP [ \fIarg\fP \&.\&.\&.]
+In many contexts, completion can only generate one particular set of
+matches, usually corresponding to a single tag\&.  However, it is
+still necessary to decide whether the user requires matches of this type\&.
+This function is useful in such a case\&.
+.RS
+.PP
+The arguments to \fB_wanted\fP are the same as those to \fB_requested\fP,
+i\&.e\&. arguments to be passed to \fB_description\fP\&.  However, in this case
+the \fIcommand\fP is not optional;  all the processing of tags, including
+the loop over both tags and tag labels and the generation of matches,
+is carried out automatically by \fB_wanted\fP\&.
+.PP
+Hence to offer only one tag and immediately add the corresponding
+matches with the given description:
+.PP
+.RS
+.nf
+\fBlocal expl
+_wanted tag expl \&'description' \e 
+    compadd matches\&.\&.\&.\fP
+.fi
+.RE
+.PP
+Note that, as for \fB_requested\fP, the \fIcommand\fP must be able to
+accept options to be passed down to \fBcompadd\fP\&.
+.PP
+Like \fB_tags\fP this function supports the \fB\-C\fP option to give a
+different name for the argument context field\&.  The \fB\-x\fP option has
+the same meaning as for \fB_description\fP\&.
+.RE
+.TP
+\fB_widgets\fP [ \fB\-g\fP \fIpattern\fP ]
+This function completes names of zle widgets (see
+the section `Widgets\&' in \fIzshzle\fP(1))\&.  The \fIpattern\fP, if present, is matched against values of the \fB$widgets\fP
+special parameter, documented in 
+the section `The zsh/zleparameter Module\&' in \fIzshmodules\fP(1)\&.
+.PP
+.SH "COMPLETION SYSTEM VARIABLES"
+.PP
+There are some standard variables, initialised by the \fB_main_complete\fP
+function and then used from other functions\&.
+.PP
+The standard variables are:
+.PP
+.PD 0
+.TP
+.PD
+\fB_comp_caller_options\fP
+The completion system uses \fBsetopt\fP to set a number of options\&. This
+allows functions to be written without concern for compatibility with
+every possible combination of user options\&. However, sometimes completion
+needs to know what the user\&'s option preferences are\&. These are saved
+in the \fB_comp_caller_options\fP associative array\&. Option names, spelled
+in lowercase without underscores, are mapped to one or other of the
+strings `\fBon\fP\&' and `\fBoff\fP'\&.
+.RS
+.PP
+.TP
+\fB_comp_priv_prefix\fP
+Completion functions such as \fB_sudo\fP can set the \fB_comp_priv_prefix\fP
+array to a command prefix that may then be used by \fB_call_program\fP to
+match the privileges when calling programs to generate matches\&.
+.PP
+Two more features are offered by the \fB_main_complete\fP function\&.  The
+arrays \fBcompprefuncs\fP and \fBcomppostfuncs\fP 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\&.
+.PP
+.SH "COMPLETION DIRECTORIES"
+.PP
+In the source distribution, the files are contained in various
+subdirectories of the \fBCompletion\fP directory\&.  They may have been
+installed in the same structure, or into one single function directory\&.
+The following is a description of the files found in the original directory
+structure\&.  If you wish to alter an installed file, you will need to copy
+it to some directory which appears earlier in your \fBfpath\fP than the
+standard directory where it appears\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBBase\fP
+The core functions and special completion widgets automatically bound
+to keys\&.  You will certainly need most of these, though will
+probably not need to alter them\&.  Many of these are documented above\&.
+.TP
+\fBZsh\fP
+Functions for completing arguments of shell builtin commands and
+utility functions for this\&.  Some of these are also used by functions from
+the \fBUnix\fP directory\&.
+.TP
+\fBUnix\fP
+Functions for completing arguments of external commands and suites of
+commands\&.  They may need modifying for your system, although in many cases
+some attempt is made to decide which version of a command is present\&.  For
+example, completion for the \fBmount\fP command tries to determine the system
+it is running on, while completion for many other utilities try to decide
+whether the GNU version of the command is in use, and hence whether the
+\fB\-\fP\fB\-help\fP option is supported\&.
+.TP
+\fBX\fP, \fBAIX\fP, \fBBSD\fP, \&.\&.\&.
+Completion and utility function for commands available only on some systems\&.
+These are not arranged hierarchically, so, for example, both the
+\fBLinux\fP and \fBDebian\fP directories, as well as the \fBX\fP directory,
+may be useful on your system\&.