Completion System Configuration
===============================

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.

Overview
--------

When completion is attempted somewhere on a command line the completion
system first tries to find out the context where completion was tried.
The context depends on such things as the name of the command when
completing an argument, and possibly also the name of an option when
completing an argument to that option.

The `context' of a completion is a string consisting of multiple
fields. This is used to look up styles that can be used to configure the
completion system.  Since it is not possible to build the whole context
string in advance, completion functions may modify some of the fields
and hence the context used for lookup may vary during the same call to
the completion system.

The context string always consists of the following fields, separated
by colons and with a leading colon before the first:

   * The literal string completion, saying that this style is used by
     the completion system.

   * The FUNCTION; in many cases this field will be blank, but when the
     completion system is called from other functions, like predict-on
     or one of the functions in the Command directory of the
     distribution, this field contains the name of that function, often
     in an abbreviated form.

   * The COMPLETER currently active, which is the name of the function
     without the leading underscore.  A `completer' is in overall
     control of how completion is to be performed; `complete' is the
     basic one for ordinary completion, but completers may perform
     various related tasks such as correction, or modify the behaviour
     of a later completer (see Control Functions for more
     information).

   * The CONTEXT or COMMAND.  This is either one of the special context
     names such as -condition- as explained for the _complete completer
     below, or the name of the command we are completing arguments for.
     Completion functions for commands that have sub-commands usually
     modify this field to contain the name of the command followed by a
     minus sign and the sub-command (e.g. the completion function for
     the cvs command sets this field to strings such as cvs-add when
     completing for the add sub-command).

   * The ARGUMENT, describing which argument we are completing.
     Normally this is either a string of the form argument-N, where N
     is the number of the argument or it is a string of the form
     option-OPT-N when completing the N'th argument of the option OPT.

   * The TAG.  Tags are used to discriminate between the types of
     matches a completion function can generate in a certain context.

As an example, the context name

     :completion::complete:dvips:option-o-1:files

says that normal completion was attempted on an argument of the dvips
command (more precisely: completion was attempted on the first argument
after the -o option) and the completion function will generate
filenames for this context.

In many of the possible contexts the completion system can generate
matches, often multiple types of matches.  These types are represented
as simple names called `tags'.  The completion system will decide
internally what sort of tags are allowed; a list of the standard
possibilities is given below.  To determine in which order the tags are
to be used by the completion function, the `tag-order' style for the
appropriate context may be set, as described in the list of standard
styles below.  Only those types of matches whose tags were selected by
this style will be produced, and in the order given, although the
default is to try all relevant tags in an order determined by the
particular completion in use.

The _complete_help bindable command described in Bindable Commands
can be invoked to find out the context and tag names and
styles used at a particular point in completion.  It shows the list of
contexts and tags that would be used in if completion were tried at the
current cursor position.  Hence one can easily find out all the
information needed to change the behaviour of the tag-order style for a
particular context.

Completion behaviour can be modified by various other styles defined
with the zstyle builtin command (see The zsh/zutil Module).  When
looking up styles the completion system uses full context names,
including the tag.

Styles determine such things as how the matches are generated; some of
them correspond to shell options (for example, the use of menu
completion), but styles provide more specific control.  They can have
any number of strings as their value.  Looking up the value of a style
therefore consists of two things:  the context, which may be matched as
a pattern, and the name of the style itself, which must be given
exactly.

For example, many completion functions can generate matches in a simple
and a verbose form and use the verbose style to decide which form
should be used.  To make all such functions use the verbose form, put

     zstyle ':completion:*' verbose yes

in one of the startup files like .zshrc; this sort of style can also be
configured with the compinstall function.  This definition simply means
that the verbose style has yes as its value in every context inside the
completion system.  If the context pattern were `*', the verbose style
would have this value anywhere the style mechanism is used, not just in
completion.

As a more specific example, the completion function for the kill
builtin command uses the verbose style to decide if jobs and processes
are listed only as job numbers and process identifiers or if they are
listed with the full job texts and the command lines of the processes
(the latter is achieved by calling the ps command).  To make this
builtin list the matches only as numbers one could call:

     zstyle ':completion:*:*:kill:*' verbose no

Furthermore, if one wanted to see the command lines for processes but
not the job texts one could use the fact that the context name contains
the tag name when styles are looked up.  As the function for the kill
builtin command uses the tags jobs and processes, we can use:

     zstyle ':completion:*:*:kill:*:jobs' verbose no

To have more control over when certain values for styles are used one
can use the special parameters available in completion widgets (see
Completion Widgets)) and the -e option to zstyle that makes the
value be evaluated when looked up.  For example, to make the completer
style have a different value when completing for the cvs command, one
could use the words special array:

     zstyle -e ':completion:*' completer '
         if [[ $words[1] = cvs ]]; then
           reply=(_complete)
         else
           reply=(_complete _approximate)
         fi'

One should be careful not to use too complicated code with this option,
at least for the styles that are looked up quite often.  These are
basically those that define some global completion behaviour but allow
that to be different for all matches or groups of matches (such as the
menu and list-rows-first styles).  Alternatively one can always use a
less general pattern for the context than in the example above and use
a second call to zstyle with a generic pattern and without using the -e
option to define the default behaviour.

Note that the order in which styles are _defined_ does not matter; the
style mechanism uses the most specific possible match for a particular
style to determine the set of values.  More precisely, strings are
preferred over patterns (for example, `:completion::complete:foo' is
more specific than `:completion::complete:*'), and longer patterns are
preferred over shorter patterns.

As with tags, completion functions can use any style they choose, so
there can't be a complete list.  However, the following two sections
list those tags and styles that are used in many places of the
completion system.

Standard Tags
-------------

Here are the tags currently used by the completion system.  Some of them
are only used when looking up styles and do not refer to a particular
type of match.

accounts
     used to look up the users-hosts style

all-expansions
     used by the _expand completer when adding the single string
     containing all possible expansions

all-files
     for the names of all files (as distinct from a particular subset,
     see the globbed-files tag).

arguments
     when an argument of a command may be completed

arrays
     for names of array parameters

association-keys
     for keys of associative arrays; used when completing inside a
     subscript of a parameter of this type

bookmarks
     when completing bookmarks (e.g. for URLs and the zftp function
     suite)

builtins
     for names of builtin commands

characters
     used for commands like stty when completing characters; also used
     when completing character classes after a opening bracket

colormapids
     for X colormap ids

colors
     for color names

commands
     for names of external commands and names of sub-commands (used by
     some commands like cvs)

contexts
     for contexts used by the zstyle builtin command

corrections
     used by the _approximate and _correct completers for the possible
     corrections

cursors
     for cursor names used by X programs

default
     used to look up default values for various styles that may also be
     set for tags that are used when generating matches; note that this
     tag is used when only the FUNCTION field of the context name is
     set up

descriptions
     used when looking up the value of the format style for descriptions

devices
     for names of device special files

directories
     for names of directories

directory-stack
     for entries in the directory stack

displays
     for X display names

domains
     for network domains

expansions
     used by the _expand completer for individual possibilities
     resulting from expansion of a word

extensions
     for X server extensions

file-descriptors
     for the numbers of open file descriptors

files
     the generic file-matching tag used by completion functions that can
     complete the names of some kind of file

fonts
     used for X font names

functions
     names of functions, normally shell functions although certain
     commands may understand other kinds of function

globbed-files
     for names of files matching the glob pattern used by completion
     functions that expect a certain type of file

groups
     used when completing names of user groups

history-words
     for words from the history

hosts
     for hostnames

indexes
     used for array indexes

jobs
     used for jobs

keymaps
     for names of zsh keymaps

keysyms
     for names of X keysyms

libraries
     for names of system libraries

limits
     for system limits

local-directories
     for names of directories which are subdirectories of the current
     working directory when completing for the cd and related builtin
     commands

manuals
     for names of manual pages

maps
     for map names (e.g. NIS maps)

messages
     used to look up the format style for messages

modifiers
     for names of X modifiers

modules
     for modules (e.g. zsh modules)

my-accounts
     used to look up the users-hosts style

named-directories
     for named directories (you wouldn't have guessed that, would you?)

names
     for all kinds of names

nicknames
     for nicknames of NIS maps

options
     for command options

original
     used by the _approximate, _correct and _expand completers when
     adding the original string

other-accounts
     used to look up the users-hosts style

packages
     for packages (e.g. rpm or installed Debian packages)

parameters
     for names of parameters

path-directories
     for names of directories found by searching the cdpath array when
     completing for the cd and related builtin commands

paths
     used to look up the values of the expand, ambiguous and
     special-dirs styles

pods
     for perl pods (documentation files)

ports
     for communication ports

prefixes
     for prefixes (like those of a URL)

printers
     for printer names

processes
     for process identifiers

processes-names
     used to look up the command style when generating the names of
     processes for killall

sequences
     for sequences (e.g. mh sequences)

sessions
     for sessions in the zftp function suite

signals
     for signal names

strings
     for strings (e.g. the replacement strings for the cd builtin
     command)

styles
     for styles used by the zstyle builtin command

tags
     for tags (e.g. rpm tags)

targets
     for makefile targets

types
     for types of whatever (e.g. address types for the xhost command)

urls
     used to look up the urls and local styles when completing URLs

users
     for usernames

values
     when completing a value out of a set of values (or a list of such
     values)

version
     used by _call_program to look up the command to run to determine
     the installed version of various other commands (such as diff and
     make).

warnings
     used to look up the format style for warnings

widgets
     for zsh widget names

windows
     for IDs of X windows

zsh-options
     for shell options

Standard Styles
---------------

Here are the names of the styles used by the completion system.  Note
that the values of several of these styles represent boolean values;
here, any of the strings `true', `on', `yes', and `1' can be used for
the truth value `true' and the strings `false', `off', `no', and `0' are
interpreted as `false'.  The behavior for any other value is undefined
unless the description for the particular style mentions other possible
values; in particular, the default value may be either on or off if the
style is not set.

Some of these styles are tested for every tag used to add possible
matches and for the default tag (most notably menu, list-colors and the
styles controlling the completion listing like list-packed and
last-prompt). When tested for the default tag, only the FUNCTION field
of the context will be set up, so the default value will normally be
set like:

     zstyle ':completion:*:default' menu ...

accept-exact
     This is tested for the default tag and the tags used when
     generating matches.  If it is set to `true' for at least one match
     which is the same as the string on the line, this match will
     immediately be accepted.

     When completing pathnames (where it is looked up for the paths
     tag), this style also accepts any number of patterns as the value.
     If this is used, pathnames matching one of these patterns will be
     accepted immediately even if the command line contains some more
     partially typed pathname components and these match no file under
     the directory accepted.

     Note that this is also used by the _expand completer to decide if
     words beginning with a tilde or parameter expansion should be
     expanded. This means that if, for example, there are parameters
     foo and foobar, the string `$foo' will only be expanded if
     accept-exact is set to `true'.

add-space
     This style is used by the _expand completer.  If it is `true' (the
     default), a space will be inserted after all words resulting from
     the expansion (except for directory names which get a slash).  The
     value may also be the string `file' to make the completer add a
     space only to names of existing files.  Finally, the `true' values
     and `file' may be combined with `subst' to keep the completer from
     adding a space when the resulting words were generated by
     expanding a substitution of the form `$(...)' or `${...}'.

     It is also used by the _prefix completer as a simple boolean value
     to decide if a space should be inserted before the suffix.

ambiguous
     This applies when completing non-final components of filename
     paths.  If it is set, the cursor is left after the first ambiguous
     component, even if menu completion is in use.  It is tested with
     the paths tag.

assign-list
     When completing after an equals sign, the completion system
     normally completes only one filename.  In some cases, particularly
     for certain parameters such as PATH, a list of filenames separated
     by colons is required.  This style can be set to a list of
     patterns matching the names of such parameters.

     The default is to complete lists when the word on the line already
     contains a colon.

auto-description
     If set, this style's value will be used as the description for
     options which are not described by the completion functions, but
     that have exactly one argument.  The sequence `%d' in the value
     will be replaced by the description for this argument.  Depending
     on personal preferences, it may be useful to set this style to
     something like `specify: %d'.  Note that this may not work for
     some commands.

avoid-completer
     This is used by the _all_matches 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.

     The default value for this style is `_expand _old_list _correct
     _approximate', i.e. it contains the completers for which a string
     with all matches will almost never be wanted.

cache-path
     This style defines the path where any cache files containing dumped
     completion data are stored.  Defaults to `$ZDOTDIR/.zcompcache', or
     `$HOME/.zcompcache' if $ZDOTDIR is not defined.  The completion
     layer will not be used unless the use-cache style is set.

call-command
     Currently this is only used by the function completing make
     targets.  If it is set to `true' and the installed version of the
     make command allows it, make is called in a way to generate all
     possible targets.  The default value of this style is `false'
     because calling make can potentially take a very long time and in
     some cases may even cause actions from the makefile be executed
     despite the options given to make.

command
     In many places, completion functions need to call external
     commands to generate the list of completions.  This style can be
     used to override the command which is called in some such cases.
     The elements of the value are 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 `builtin' or `command' in front to make sure
     the appropriate version of a command is called, for example to
     avoid calling a shell function with the same name as an external
     command.

     As an example, the function generating process IDs as matches uses
     this style with the processes tag to generate the IDs to complete
     and the list of processes to display (if the verbose style is
     `true').  The list produced by the command should look like the
     output of the ps command.  The first line is not displayed, but is
     searched for the string `PID' (or `pid') to find the position of
     the process IDs in the following lines.  If the line does not
     contain `PID', the first numbers in each of the other lines are
     taken as the process IDs to complete.

     Note that the completion function generally has to call the command
     every time it is called.  Because of that care should be taken to
     specify only commands that take a short time to run (and that will
     eventually stop at all).

commands
     This is used by the function completing sub-commands for the system
     initialisation scripts (residing in /etc/init.d or somewhere not
     too far away from that).  It's 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 `start' and `stop'.

complete
     This is used by the _expand_alias function when invoked as a
     bindable command.  If it set to `true' and the word on the command
     line is not the name of an alias, matching alias names will be
     completed.

completer
     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 Control Functions.

     Each string may be the name of a completer function or a string of
     the form `FUNCTION:NAME'. In the first case the COMPLETER field of
     the context will contain the name of the completer without the
     leading underscore and with all other underscores replaced by
     hyphens.  In the second case the FUNCTION is the name of the
     completer to call, but the context will contain the NAME in the
     COMPLETER field of the context.  If the NAME starts with a hyphen,
     the string for the context will be build from the name of the
     completer function as in the first case with the NAME appended to
     it.  For example:

          zstyle ':completion:*' completer _complete _complete:-foo

     Here, completion will call the _complete completer twice, once
     using `complete' and once using `complete-foo' in the COMPLETER
     field of the context.  Normally, using the same completer more
     than once makes only sense when used with the `FUNCTIONS:NAME'
     form, because otherwise the context name will be the same in all
     calls to the completer; possible exceptions to this rule are the
     _ignored and _prefix completers.

     The default value for this style is _complete _ignored, i.e.
     normally only completion will be done, first using the
     ignored-patterns style and the $fignore array and then without
     ignoring matches.

condition
     This style is used by the _list completer function to decide if
     insertion of matches should be delayed unconditionally. The
     default is `true'.

disabled
     If this is set to `true', the _expand_alias completer and bindable
     command will try to expand disabled aliases, too.  The default is
     `false'.

disable-stat
     This is used with an empty tag by the function completing for the
     cvs command to decide if the zsh/stat module should be used to
     generate names of modified files in the appropriate places (this
     is its only use).  If set, completion will use the ls command.

domains
     If set, gives the names of network domains that should be
     completed.  If this is not set by the user domain names will be
     taken from the file /etc/resolv.conf.

expand
     This style is used when completing strings consisting of multiple
     parts, such as path names.  If one of its values is the string
     `prefix', the partially typed word from the line will be expanded
     as far as possible even if trailing parts cannot be completed.  If
     one of its values is the string `suffix', matching names for
     components after the first ambiguous one will also be added.  This
     means that the resulting string is the longest unambiguous string
     possible, but if menu completion is started on the list of matches
     generated this way, this will also cycle through the names of the
     files in pathname components after the first ambiguous one.

fake-files
     This style is used when completing files and looked up without a
     tag.  Its values are of the form `DIR:NAMES...'.  This will add
     the NAMES (strings separated by spaces) as possible matches when
     completing in the directory DIR, even if no such files really
     exist.

     This can be useful on systems that support special filesystems
     whose top-level pathnames can not be listed or generated with glob
     patterns.  It can also be used for directories for which one does
     not have read permission.

fake-parameters
     This is used by the completion function generating parameter names
     as matches.  Its values are names of parameters which might not
     yet be set, but which should be completed nonetheless.  Each name
     may also be followed by a colon and a string specifying the type
     of the parameter (like `scalar', `array' or `integer').  If such a
     type is given, the name will only be completed if parameters of
     that type are requested in the particular context.  Names for
     which no type is specified will always be completed.

file-patterns
     In most places where filenames are completed, the function _files
     is used which can be configured with this style.  If the style is
     unset, _files offers, one after another, up to three tags:
     `globbed-files', `directories' and `all-files', depending on the
     types of files expected by the caller of _files.

     If the file-patterns style is set, the default tags are not used.
     Instead, the value of the style says which tags and which patterns
     are to be offered.  The strings in the value contain
     specifications of the form `PATTERN:TAG'; each string may contain
     any number of such specifications.  The PATTERN gives a glob
     pattern that is to be used to generate filenames.  If it contains
     the sequence `%p', that is replaced by the pattern(s) given by the
     calling function.  Colons in the pattern must be preceded by a
     backslash to make them distinguishable from the colon before the
     TAG.  If more than one pattern is needed, the patterns can be
     given inside braces, separated by commas.  The TAGs of all strings
     in the value will be offered by _files (again, one after another)
     and used when looking up other styles.  For strings containing
     more than one specification, the filenames for all specifications
     will be generated at the same try.  If no `:TAG' is given the
     `files' tag will be used.  The TAG may also be followed by an
     optional second colon and a description.  If that is given, this
     description will be used for the `%d' in the value of the format
     style (if that is set) instead of the default description supplied
     by the completion function.  If the description given here
     contains itself a `%d', that is replaced with the description
     supplied by the completion function.

     For example, to make the rm command first complete only names of
     object files and the names of all files if no object file matches
     the string on the line, one would do:

          zstyle ':completion:*:*:rm:*' file-patterns \
              '*.o:object-files' '%p:all-files'

     Another interesting example is to change the default behaviour that
     makes completion first offer files matching the patterns given by
     the calling function, then directories and then all files.  Many
     people prefer to get both the files matching the given patterns
     and the directories in the first try and all files at the second
     try.  To achieve this, one could do:

          zstyle ':completion:*' file-patterns \
              '%p:globbed-files *(-/):directories' '*:all-files'

     This works even for contexts in which all files would be completed,
     because _files will not try a pattern more than once and it stops
     when the pattern `*' was tried.

     Note also that during the execution of completion functions, the
     EXTENDED_GLOB option is in effect, so the characters `#', `~' and
     `^' have special meanings in the patterns.

file-sort
     The completion function that generates filenames as possible
     matches uses this style without a tag to determine in which order
     the names should be listed and completed when using menu
     completion.  The value may be one of `size' to sort them by the
     size of the file, `links' to sort them by the number of links to
     the file, `modification' (or `time' or `date') to sort them by the
     last modification time, `access' to sort them by the last access
     time, or `inode' (or `change') to sort them 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 `reverse', sorting is done in decreasing order.

force-list
     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
     `always', the list will always be shown, even if there is only a
     single match which is immediately accepted.  The style may also be
     set to a number.  In this case the list will be shown if there are
     at least that many matches, even if they would all insert the same
     string.

     This style is tested for the default tag and all tags used when
     generating matches. This allows one to turn unconditional listing
     on for certain types of matches.

format
     If this is set for the descriptions tag, its value is used as a
     string to display above matches in completion lists.  The sequence
     `%d' in this string will be replaced with a short description of
     what these matches are.  This string may also contain the
     sequences to specify output attributes, such as `%B', `%S' and
     `%{...%}'.

     For the same purpose, this style is also tested with the tags used
     when matches are generated before it is tested for the descriptions
     tag.  This provides the possibility of defining different format
     strings for different types of matches.

     Note also that some completer functions define additional
     `%'-sequences.  These are described for the completer functions
     that make use of them.

     For the messages tag, this style defines a string used by some
     completion functions to display messages.  Here, the `%d' is
     replaced with a message given by the completion function.

     Finally, when set with the warnings tag, the format string is
     printed when no matches could be generated at all.  In this case
     the `%d' is replaced with the descriptions for the matches that
     were expected separated by spaces and the sequence `%D' is
     replaced with those descriptions separated by newlines.

     The `%' for the sequences that are replaced by strings provided by
     the completion functions like the `%d' may be followed by field
     width specifications as  described for the zformat builtin command
     from the zsh/zutil module, see The zsh/zutil Module.

glob
     This is used by the _expand completer.  If it is set to `true'
     (the default), globbing will be attempted on the words resulting
     from substitution (see the substitute style) or the original
     string from the line.

global
     If this is set to `true' (the default), the _expand_alias
     completer and bindable command will try to expand global aliases.

group-name
     The completion system can put different types of matches in
     different groups which are then displayed separately in the list
     of possible completions.  This style can be used to give the names
     for these groups for particular tags.  For example, in command
     position the completion system generates names of builtin and
     external commands, names of aliases, shell functions and
     parameters and reserved words as possible completions.  To have
     the external commands and shell functions listed separately, one
     can set:

          zstyle ':completion:*:*:-command-:*:commands' group-name commands
          zstyle ':completion:*:*:-command-:*:functions' group-name functions

     This also means that if the same name is used for different types
     of matches, then those matches will be displayed together in the
     same group.

     If the name given is the empty string, then the name of the tag for
     the matches will be used as the name of the group. So, to have all
     different types of matches displayed separately, one can just set:

          zstyle ':completion:*' group-name ''

     All matches for which no group name is defined will be put in a
     group named -default-.

group-order
     This style is to be used together with the group-name style.  Once
     different types of matches are put into different groups, this
     style can be used to define in which order these groups should
     appear when listing (compare tag-order, which determines which
     completions appear at all).  The strings in the value are taken as
     group names and the named groups will be shown in the order in
     which their names appear in the value.  All groups whose names are
     not given in the value of this style will appear in the order
     defined by the function generating the matches.

     For example, to have names of builtin commands, shell functions and
     external commands appear in this order when completing in command
     position one would set:

          zstyle ':completion:*:*:-command-:*' group-order \
                 builtins functions commands

groups
     A style holding the names of the groups that should be completed.
     If this is not set by the user, the group names from the YP
     database or the file `/etc/group' will be used.

hidden
     If this is set to one of the `true' values, the matches for the
     tags for which this is set will not appear in the list; only the
     description for the matches as set with the format style will be
     shown.  If this is set to `all', not even the description will be
     displayed.

     Note that the matches will still be completed; they are just not
     shown in the list.  To avoid having matches considered as possible
     completions at all, the tag-order style can be modified as
     described below.

hosts
     A style holding the names of hosts that should be completed. If
     this is not set by the user the hostnames in `/etc/hosts' will be
     used.

hosts-ports
     This style is used by commands that need or accept hostnames and
     ports.  The strings in the value should be of the form
     `HOST:PORT'.  These hostnames and ports are completed depending on
     the information already on the line, so that if, for example, the
     hostname is already typed, only those ports specified for that
     host will be completed.  Multiple ports for the same host may
     appear.

ignore-line
     This style is tested for the tags used when generating matches.
     If it is set to `true', then none of the words that are already on
     the line will be considered possible completions.  If it is set to
     `current', the word the cursor is on will not be considered a
     possible completion.  The same happens if the value is
     `current-shown', but only if the list of completions is currently
     shown on the screen.  Finally, if it is set to `other' all words
     except the current one will not be considered to be a possible
     completion.

     The values `current' and `current-shown' are a bit like the
     opposite of accept-exact. They mean that only strings with missing
     characters will be completed.

     Note that you almost certainly don't want to set this to `true' or
     `other' for a general context such as `:completion:*'.  This is
     because it would disallow completion of, for example, options
     multiple times even if the command in question accepts the option
     more than once.

ignore-parents
     The style is tested by the function completing pathnames without a
     tag 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:

    parent
          The name of any directory whose path is already contained in
          the word on the line is ignored.  For example, when
          completing after foo/../, the directory foo will not be
          considered a valid completion.

    pwd
          The name of the current working directory will not be
          completed, so that, for example, completion after ../ will
          not use the name of the current directory.

     In addition, the value may include one or both of:

    ..
          Ignore the specified directories only when the word on the
          line contains the substring `../'.

    directory
          Ignore only when names of directories are completed, not when
          completing names of files.

     Note that names of directories ignored because of one of the tests
     will be ignored in the same way as the matches ignored because of
     the ignored-patterns style.  I.e., by using the _ignored completer
     it is possible to complete these directories nonetheless.

ignored-patterns
     This style can be used to specify a list of patterns which are
     tested against against the trial completions in a given context;
     any matching completions will be removed from the list of
     possibilities.  The _ignored completer can appear in the list of
     completers to produce a list which includes these matches once
     more.  This is a more configurable version of the shell parameter
     $fignore.

     Note that during the execution of completion functions, the
     EXTENDED_GLOB option is in effect, so the characters `#', `~' and
     `^' have special meanings in the patterns.

insert-ids
     When completing process IDs, for example as arguments to the kill
     and wait builtins, completion allows the user to type the name of a
     command, which will 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 `menu') the name
     will be converted immediately to a set of possible IDs, and menu
     completion will be started to cycle through them.  If the value of
     the style is `single', however, the shell will wait until the user
     has typed enough to make the command unique before converting the
     name to an ID; the user must type any additional characters
     required.  If the value is any other string, menu completion will
     be started when the string typed by the user is longer than the
     common prefix of the corresponding IDs.

insert-tab
     If this has one of the `true' values, the completion system will
     insert a TAB character (assuming it was used to start completion)
     instead of performing completion when there is no non-blank
     character to the left of the cursor.  If set to `false',
     completion will be done even there.

     The value may also contain the substrings `pending' or
     `pending=VAL' to make the character typed to start completion be
     inserted instead of completion being tried when there is input
     pending which has not yet been processed by the shell. If a VAL is
     given, completion will not be done if there are at least that many
     characters of unprocessed input. This is often useful to have set
     when pasting characters into a terminal. Note however, that it
     relies on the $PENDING special parameter from the zsh/zle module
     being set properly which is not guaranteed on all platforms.

     The default value of this style is `true' unless when completing
     inside the vared builtin command, where it defaults to `false'.

insert-unambiguous
     This is used by the _match and _approximate completer functions,
     where the possible completions may not have a common prefix so
     that menu completion is often the most useful may of choosing
     completions.  If the style is set to `true', the completer will
     start menu completion only if no unambiguous string could be
     generated that is at least as long as the original string typed by
     the user.  Note that the _approximate completer uses it after
     setting the completer field in the context name to one of
     correct-NUM or approximate-NUM, where NUM is the number of errors
     that were accepted.

     When used for the _match completer, the style may also be set to
     the string `pattern'.  This makes the pattern on the line be left
     unchanged if it didn't match unambiguously.

keep-prefix
     This style is used by the _expand completer.  If it is `true', the
     completer will try to keep a prefix containing a tilde or parameter
     expansion.  I.e., the string `~/f*' would be expanded to `~/foo'
     instead of `/home/user/foo'.  If the style is set to `changed'
     (the default), the prefix will only be left unchanged if there
     were other changes between the expanded words and the original
     word from the command line.  Any other value makes the prefix be
     expanded unconditionally.

     Note that with one of the `true' values, the _expand completer
     returns if there is only one expansion and that is, after restoring
     the original prefix, the same as the original word.  This means
     that other completers will be called immediately after _expand.

last-prompt
     This is used to determine if the completion code should try to put
     the cursor back onto the previous command line after showing a
     completion listing (as for the ALWAYS_LAST_PROMPT option).  As
     with several other styles, it is tested for the default tag as
     well as all the possible tags when generating matches.  The cursor
     will be moved back to the previous line if this style is `true'
     for all types of matches added.  Note also that this is
     independent of the numeric argument, unlike the ALWAYS_LAST_PROMPT
     option.

list
     This style is used by the _history_complete_word bindable command.
     If it is set to `true' it has no effect, but if it is set to
     `false' the matches will not be listed, overriding the setting of
     the options that control listing behaviour, especially AUTO_LIST.
     Use the context prefix `:completion:history-words'.

list-colors
     If the zsh/complist module is used, this style can be used to set
     color specifications as with the ZLS_COLORS and ZLS_COLOURS
     parameters, which will not be honored under this completion system
     (see The zsh/complist Module).

     If this style is set for the default tag, the strings in the value
     are taken as specifications that are to be used everywhere.  If it
     is set for other tags, the specifications are used only for
     matches of the type described by the tag.  For this to work best,
     the group-name style must be set to an empty string.  If the
     group-name tag specifies other names for the groups the matches in
     these groups can be colored by using these names together with the
     `(group)...'  syntax described for the ZLS_COLORS and ZLS_COLOURS
     parameters and adding the specifications to the value for this
     style with the default tag (although in most cases it should work
     by setting this style for the appropriate tags).

     It is possible to use the same specifications set up for the GNU
     version of the ls command:

          zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS}

     The default colors are the same as for the GNU ls command and can
     be obtained by setting the style to an empty string (i.e. '').

list-packed
     Like the list-colors style, this is tested with the default tag
     and all tags used when generating matches.  If it is set to `true'
     for a tag, the matches added for it will be listed as if the
     LIST_PACKED option were set.  If it is set to `false', they are
     listed normally.

list-prompt
     If this style is set for the default tag, completion lists that
     don't fit on the screen can be scrolled (see The zsh/complist Module).
     The value, if not the empty string, will
     be displayed after every screenful and the shell will prompt for a
     key press; if the style is set to the empty string, a default
     prompt will be used.  The value may contain the escape sequences
     `%l' or `%L', which will be replaced by the number of the last line
     displayed and the total number of lines; `%m' or `%M', which will
     be replaced by the number of the  last match shown and the total
     number of matches; and `%p' and `%P', which will be replaced by
     `Top' when at the beginning of the list, `Bottom' when at the end
     and the position shown in percent of the total length otherwise.
     In each of these cases the form with the uppercase letter is
     replaced by a string of fixed width, padded to the  right with
     spaces.  As in other prompt strings, the escape sequences `%S',
     `%s', `%B', `%b', `%U', `%u', and `%{...%}' for entering and
     leaving the display modes standout, bold and underline are also
     available.

list-rows-first
     This style is tested in the same way as the list-packed style and
     determines if matches are to be listed in a rows-first fashion, as
     for the LIST_ROWS_FIRST option.

list-suffixes
     This style is used by the function used to complete filenames.  If
     completion is attempted on a string containing multiple partially
     typed pathname components and this style is set to `true', all
     components starting with the first one for which more than one
     match could be generated will be shown.

local
     This style is used by completion functions which generate URLs as
     possible matches to add suitable matches when a URL points to a
     local web server, that is, one whose files are available directly
     on the local file system.  Its value should consist of three
     strings: a hostname, the path to the default web pages for the
     server and the directory name used by a user placing web pages
     within their home area.  For example, completion after
     `http://toast/~yousir/' will attempt to match the name `toast'
     against the first argument to the style, and if successful will
     look in the directory under ~yousir given by the third argument to
     the style for possible completions.

match-original
     This is used by the _match completer.  If it is set to only,
     _match will try to generate matches without inserting a `*' at the
     cursor position.  If set to any other non-empty value, it will
     first try to generate matches without inserting the `*' and if
     that yields no matches, it will try again with the `*' inserted.
     If it is unset or set to the empty string, matching will only be
     done with the `*' inserted.

matcher
     This style is tested for tags used when generating matches.  Its
     value is used as an match specification additional to any given by
     the matcher-list style which should be in the form described in
     Matching Control.

matcher-list
     This style is used by the main completion function to retrieve
     match specifications that are to be used everywhere.  Its value
     should be a list of such specifications.  The completion system
     will try them one after another for each completer selected. For
     example, to first try simple completion and, if that generates no
     matches, case-insensitive completion one would do:

          zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'

     By default every specification replaces previous ones. If
     specification is prefixed with +, it is added to the existing
     list. This allows testing more general patterns without repeating
     the whole list every time, as in:

          zstyle ':completion:*' matcher-list '' '+m{a-Z}={A-Z}' '+m{A-Z}={a-z}'

     The style allows even finer control by specifying a particular
     completer, without the leading underscore, in the third field of
     the completion context.  For example, if one uses the completers
     _complete and _prefix but wants to try case-insensitive completion
     only when using the _complete completer, one would do:

          zstyle ':completion:*' completer _complete _prefix
          zstyle ':completion:*:complete:*' matcher-list \
                 '' 'm:{a-zA-Z}={A-Za-z}'

     Note that the completer style allows user-defined names to be used
     in the context instead of the name of the completer.  This is
     useful if, for example, one wants to try normal completion without
     a match specification and with case-insensitive matching first,
     correction if that doesn't generate any matches and partial-word
     completion if that doesn't yield any matches either.  In this case
     one can give the _complete completer more than once in the
     completer style and define different match specifications for each
     occurrence, as in:

          zstyle ':completion:*' completer _complete _correct _complete:foo
          zstyle ':completion:*:complete:*' matcher-list \
              '' 'm:{a-zA-Z}={A-Za-z}'
          zstyle ':completion:*:foo:*' matcher-list \
              'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*'

     If the style is unset in any context no match specification is
     applied; further, some completers such as _correct and
     _approximate do not use the match specifications at all.  However,
     it is always safe to use the simple form for this style (as in the
     first example above), since any completers which do not use match
     specifications will only ever be called once, rather than once per
     specification.

     Since the specification-strings in this style have to be tried one
     after another, it is a good idea to keep their number low.  In
     most cases one to three strings (each of which may, without to
     large a performance hit, consist of more than one single match
     specification) will give acceptable performance.

max-errors
     This is used by the _approximate and _correct 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.

     If the value for this style contains the string `numeric', the
     completer function will take any numeric argument as the maximum
     number of errors allowed. For example, with

          zstyle ':completion:*:approximate:::' max-errors 2 numeric

     two errors are allowed if no numeric argument is given, but with a
     numeric argument of six (as in `ESC-6 TAB'), up to six errors are
     accepted.  Hence with a value of `0 numeric', no correcting
     completion will be attempted unless a numeric argument is given.

     If the value contains the string `not-numeric', the completer will
     _not_ try to generate corrected completions when given a numeric
     argument, so in this case the number given should be greater than
     zero.  For example, `2 not-numeric' specifies that correcting
     completion with two errors will usually be performed, but if a
     numeric argument is given, correcting completion will not be
     performed.

     The default value for this style is `2 numeric'.

menu
     If this is set to true in a given context, using any of the tags
     defined for a given completion, menu completion will be used.  The
     tag `default' can be used to set the default value, but a specific
     tag will take precedence.  If none of the values found in this way
     is true but at least one is set to `auto' the behaviour will be as
     for the AUTO_MENU option.  Finally, if one of the values is
     explicitly set to false, menu completion will be turned off even
     if it would otherwise be active (for example, with the
     MENU_COMPLETE option).

     Using the form `yes=NUM', where `yes' may be any of the true
     values (`yes', `true', `on' and `1') turns on menu completion if
     there at least NUM matches.  Using this for one of the `false'
     values (as in `no=10') makes menu completion _not_ be used if
     there are NUM or more matches.  Of course, this is only useful
     when menu completion is normally used, e.g. by setting the
     MENU_COMPLETE option.  The `true' values may also be used in the
     form `yes=long' to turn on menu completion if the list does not
     fit onto the screen.  This will start menu completion only if
     normal completion was attempted, not when only the list of
     possible completions was requested.  To start menu completion even
     then, the value `yes=long-list' can be used.

     In addition to (or instead of) the above possibilities, the value
     may contain the string `select', optionally followed by an equals
     sign and a number.  In this case menu selection (as defined by the
     zsh/complist module) will be started.  Without the optional
     number, it will be started unconditionally and with a number it
     will be started only if at least that many matches are generated;
     if the values for more than one tag provide a number, the smallest
     number is taken.  Menu selection can be turned off explicitly by
     defining a value containing the string `no-select'.

     It is also possible to start menu selection only if the list of
     matches does not fit on the screen by using the value
     `select=long'.  This will only start menu selection if the widget
     invoked does completion, not simply listing as done by
     delete-char-or-list; to start menu selection even here, use the
     value `select=long-list'.

     To turn on menu completion or menu selection when a certain number
     of matches is generated _or_ the list of matches does not fit onto
     the screen, both of `yes=' and `select=' can be given twice, once
     with a number and once with `long' or `long-list'.

numbers
     This is used with the jobs tag.  If it is `true', the shell will
     complete the job numbers instead of the shortest unambiguous
     strings of the jobs' command lines.  If the value is a number, job
     numbers will only be used if that many words from the job
     descriptions are required to resolve ambiguities.  For example, if
     the value is `1', strings will only be used if all jobs differ in
     the first word on their command lines.

old-list
     This is used by the _oldlist completer.  If it is set to `always',
     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 `never', giving the behaviour
     without the _oldlist 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 _oldlist.  However, if
     there is an old list and this style contains the name of the
     completer function that generated the list, then the old list will
     be used even if it was generated by a widget which does not do
     listing.

     For example, suppose you type ^Xc to use the _correct_word widget,
     which generates a list of corrections for the word under the
     cursor.  Usually, typing ^D would generate a standard list of
     completions for the word on the command line, and show that.  With
     _oldlist, it will instead show the list of corrections already
     generated.

     As another example consider the _match completer: with the
     insert-unambiguous 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 _oldlist
     completer and setting this style to _match, the list of matches
     generated on the first attempt will be used again.

old-matches
     This is used by the _all_matches completer to decide if an old
     list of matches should be used if one exists.  It may be set to
     one of the `true' values or to the string `only' to use such a
     list.  If it is set to `only', _all_matches will only use an old
     list and won't have any effect on the list of matches currently
     being generated.

old-menu
     This is used by the _oldlist completer.  It controls how menu
     completion behaves when a completion has already been inserted and
     the user types a standard completion key type such as TAB.  The
     default behaviour of _oldlist is that menu completion always
     continues with the existing list of completions.  If this style is
     set to `false', however, a new completion is started if the old
     list was generated by a different completion command; this is the
     behaviour without the  _oldlist completer.

     For example, suppose you type ^Xc 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 TAB at
     this point would start trying to complete the line as it now
     appears.  With _oldlist, it instead continues to cycle through the
     list of corrections.

original
     This is used by the _approximate and _correct completers to decide
     if the original string should be added as one possible completion.
     Normally, this is done only if there are at least two possible
     corrections, but if this style is set to `true', it is always
     added.  Note that these completers use this style after setting
     the completer field in the context name to correct-NUM or
     approximate-NUM, where NUM is the number of errors that were
     accepted.

packageset
     This style is used when completing arguments of the Debian `dpkg'
     program.  It contains an override for the default package set for
     a given context.  For example,

          zstyle ':completion:*:complete:dpkg:option--status-1:*' \
                         packageset avail

     causes available packages, rather than only installed packages, to
     be completed for `dpkg -status'.

path
     The function that completes color names uses this style with the
     colors tag.  The value should be the pathname of a file containing
     color names in the format of an X11 rgb.txt 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.

ports
     A style holding the service names of ports to complete.  If this is
     not set by the user, the service names from `/etc/services' will
     be used.

prefix-hidden
     This is used when matches with a common prefix are added (e.g.
     option names).  If it is `true', this prefix will not be shown in
     the list of matches.

     The default value for this style is `false'.

prefix-needed
     This, too, is used for matches with a common prefix.  If it is set
     to `true' this common prefix has to be typed by the user to
     generate the matches.  E.g. for options this means that the `-',
     `+', or `--' has to be on the line to make option names be
     completed at all.

     The default style for this style is `true'.

preserve-prefix
     This style is used when completing path names.  Its value should
     be a pattern matching an initial prefix of the word to complete
     that should be left unchanged under all circumstances.  For
     example, on some Unices an initial `//' (double slash) has a
     special meaning and hence should be kept.  For that one could set
     this style to the string `//'.  As another example, setting this
     style to `?:/' under Cygwin would allow completion after `a:/...'
     and the like.

range
     This is used by the _history completer and the
     _history_complete_word bindable command to decide which words
     should be completed.  It may be set to a number, N, to say that
     only the last N words from the history should be completed.  The
     value may also be of the form `MAX:SLICE'.  This means that first
     the last SLICE words will be completed.  If that yields no
     matches, the SLICE words before those will be tried and so on,
     until either at least one match is generated or MAX words have
     been tried.  The default is to complete all words from the history
     at once.

regular
     This style is used by the _expand_alias completer and bindable
     command.  If set to `true' (the default), regular aliases will be
     expanded but only in command position.  If it is set to `false',
     regular aliases will never be expanded and if it is set to the
     string `always', regular aliases will be expanded even if not in
     command position.

remove-all-dups
     The _history_complete_word bindable command and the _history
     completer use this to decide if all duplicate matches should be
     removed, rather than just consecutive duplicates.

select-prompt
     If this is set for the default tag, its value will be displayed
     during menu selection (see the menu style above) when the
     completion list does not fit on the screen as a whole.  The same
     escapes as for the list-prompt style are understood, but give the
     number of the match or line the mark is on.  A default prompt is
     used when the value is the empty string.

select-scroll
     This style is tested for the default tag and determines how a
     completion list is scrolled during a menu selection (see the menu
     style above) when the completion list does not fit on the screen
     as a whole.  Its value should be `0' (zero) to scroll by
     half-screenfuls, a positive integer to scroll by that many lines
     and a negative number to scroll by the number of lines of the
     screen minus that number (or plus the number, since it is
     negative).  The default is to scroll by single lines.

single-ignored
     This is used by the _ignored completer.  It specifies what should
     be done if it can generate only one match, which is often a
     special case.  If its value is `show', the single match will be
     displayed but not inserted.  If the value is `menu', then the
     single match and the original string are both added as matches and
     menu completion is started so that one can easily select either of
     them.

sort
     If set to `true', completion functions that generate words from the
     history as possible matches sort these words alphabetically
     instead of keeping them in the order in which they appear in the
     history (from youngest to oldest).

     This is also used by the _expand completer.  Here, if it is set to
     `true', the expansions generated will always be sorted.  If it is
     set to `menu', then the expansions are only sorted when they are
     offered as single strings (not in the string containing all
     possible expansions).

special-dirs
     Normally, the completion code will not produce the directory names
     `.' and `..' as possible completions.  If this style is set to
     `true', it will add both `.' and `..' as possible completions; if
     it is set to `..', only `..' will be added.

squeeze-slashes
     If set to `true', sequences of slashes (as in `foo//bar') will be
     treated as if they were only one slash when completing pathnames.
     This is the usual behaviour of UNIX paths.  However, by default
     the file completion function behaves as if there were a `*' between
     the slashes.

stop
     If set to `true', the _history_complete_word bindable command will
     stop once when reaching the beginning or end of the history.
     Invoking _history_complete_word will then wrap around to the
     opposite end of the history.  If this style is set to `false' (the
     default), _history_complete_word will loop immediately as in a
     menu completion.

subst-globs-only
     This is used by the _expand 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 substitute style
     described below, but these were not further changed by globbing,
     the expansions will be rejected.

     The default for this style is `false'.

substitute
     This boolean style controls whether the _expand completer will
     first try to expand all substitutions in the string (such as
     `$(...)' and `${...}').

     The default is `true'.

suffix
     This is used by the _expand completer if the word starts with a
     tilde or contains a parameter expansion. If it is set to `true',
     the word will only be expanded if it doesn't have a suffix, i.e.
     if it is something like `~foo' or `$foo', but not if it is `~foo/'
     or `$foo/bar', unless that suffix itself contains characters
     eligible for expansion.  The default for this style is `true'.

tag-order
     This provides a mechanism for sorting how the tags available in a
     particular context will be used.

     The values for the style are sets of space-separated lists of tags.
     The tags in each value will be tried at the same time; if no match
     is found, the next value is used.  (See the file-patterns style for
     an exception to this behavior.)

     For example:

          zstyle ':completion:*:complete:-command-:*' tag-order \
              'commands functions'

     specifies that completion in command position should offer only
     completions for external commands and shell functions immediately.

     In addition to tag names, each string in the value may take one of
     the following forms:

    -
          If any string in the value consists of only a hyphen, then
          _only_ the tags specified by the other strings in the value
          are generated.  Normally all tags not explicitly selected are
          tried last if the specified tags fail to generate any
          matches.  This means that a value consisting only of a single
          hyphen turns off completion.

    ! TAGS...
          A string starting with an exclamation mark specifies names of
          tags that are _not_ to be used.  The effect is the same as if
          all other possible tags for the context had been listed.

    TAG:LABEL ...
          In strings not starting with an exclamation mark, it is also
          possible to specify tag labels instead of only tags, where
          TAG is one of the tags offered by the completion function for
          the current context and LABEL is a name.  For this, the
          completion function will generate matches in the same way as
          for the TAG but it will use the LABEL in place of the tag in
          the context names used to look up styles.  If the LABEL
          starts with a hyphen, the TAG is prepended to the LABEL to
          form the name used for lookup.  This can be used to make the
          completion system try a certain tag more than once, supplying
          different style settings for each attempt, see below for an
          example.

          The LABEL may optionally be followed by a second colon and a
          description.  This description will then be used for the `%d'
          in the value of the format style instead of the default
          description supplied by the completion function.  Spaces in
          the description have to be quoted by preceding them with a
          backslash and a `%d' appearing in the description is replaced
          with the description given by the completion function.

     In each of the cases above, the tag may also be a pattern or more
     than one pattern inside braces and separated by commas.  In this
     case all of the offered tags matching the pattern(s) will be used
     except for those that are given explicitly in the same string.
     There are probably two main uses of this.  One is the case where
     one wants to try one of the tags more than once, setting other
     styles differently for each try, but still wants to use all the
     other tags without having to repeat them all.  For example, to
     make completion of function names in command position ignore all
     the completion functions starting with an underscore the first
     time completion is tried, one could do:

          zstyle ':completion:*:*:-command-:*' tag-order \
              'functions:-non-comp *' functions
          zstyle ':completion:*:functions-non-comp' ignored-patterns '_*'

     Here, the completion system will first try all tags offered, but
     will use the tag label functions-non-comp when looking up styles
     for the function names completed.  For this, the ignored-patterns
     style is set to exclude functions starting with an underscore from
     the set of possible matches.  If none of the generated matches
     match the string on the line, the completion system will use the
     second value of the tag-order style and complete functions names
     again, but this time using the name functions to look up styles,
     so that the ignored-patterns style is not used and all function
     names are considered.

     Of course, this can also be used to split the matches for one tag
     into different groups. For example:

          zstyle ':completion:*' tag-order \
              'options:-long:long\ options
               options:-short:short\ options
               options:-single-letter:single\ letter\ options'

          zstyle ':completion:*:options-long' ignored-patterns '[-+](|-|[^-]*)'
          zstyle ':completion:*:options-short' ignored-patterns '--*' '[-+]?'
          zstyle ':completion:*:options-single-letter' ignored-patterns '???*'

     With the group-names style set, this makes options beginning with
     `--', options beginning with a single `-' or `+' but containing
     multiple characters, and single-letter options be displayed in
     separate groups with different descriptions.

     The second interesting use of patterns is the case where one wants
     to try multiple match specifications one after another.  The
     matcher-list style offers something similar, but it is tested very
     early in the completion system and hence can't be set for single
     commands 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 foo:
          zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
          zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'

     First, all the tags offered when completing after foo are tried
     using the normal tag name.  If that generates no matches, the
     second value of tag-order is used, which tries all tags again
     except that this time each has -case appended to its name for
     lookup of styles.  Hence this time the value for the matcher style
     from the second call to zstyle in the example is used to make
     completion case-insensitive.

     Using the -e option of the zstyle builtin command, it is possible
     to specify conditions saying when certain tags are to be used. For
     example:

          zstyle -e '*:-command-:*' tag-order '
              if [[ -n $PREFIX ]]; then
                reply=( )
              else
                reply=( - )
              fi'

     Makes completion in command position happen only if the string on
     the line is not empty.  This is tested using the PREFIX parameter
     which is special in completion widgets; see Completion Widgets
     for a description of these special parameters.  Setting
     reply to an empty array ensures that only the default behaviour of
     trying all tags at once is used and setting it to an array
     containing only a hyphen disables that default behaviour - thus
     keeping all tags from being tried.

     If no style has been defined for a context, the strings
     `(|*-)argument-* (|*-)option-* values' and `options' 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.

urls
     This is used together with the the urls tag by completion
     functions that generate URLs as possible matches.  If the value
     consists of more than one string or if the only string does not
     name a file or directory, the strings are used as the URLs to
     complete.

     If the value contains only one string and that is the name of a
     normal file, the URLs are taken from that file (where the URLs may
     be separated by white space or newlines).

     Finally, if the only string in the value names a directory, that
     should contain sub-directories named after the retrieval methods
     which occur as the first part of a URL, i.e.  `http', `ftp',
     `bookmark', and so on.  These sub-directories should contain files
     and other sub-directories whose pathnames are possible completions
     after the initial `http://', `ftp://', etc. See the description in
     the file _urls in the User sub-directory of the completion system
     for more information.

use-cache
     If this is set, the completion caching layer is activated for any
     completions which use it (via the _store_cache, _retrieve_cache,
     and _cache_invalid functions).  The directory containing the cache
     files can be changed with the cache-path style.

use-compctl
     If this style is set to a string _not_ equal to false, 0, no, and
     off, the completion system may use any completion specifications
     defined with the compctl builtin command.  If the style is unset,
     this is done only if the zsh/compctl module is loaded.  The string
     may also contain the substring `first' to make the definition for
     `compctl -T' be used, and the substring `default' to make the one
     for `compctl -D' be used.

     Note that this is only intended to smooth the transition from
     compctl to the new completion system and may disappear in the
     future.

     Note also that the definitions from compctl will only be used if
     there is no specific completion function for the command in
     question.  For example, while completing arguments to the command
     foo, if this was handled by a command function _foo, compctl would
     never be tried, while if it was handled by _default, compctl would
     be tried.

users
     This may be set to a list of names that should be completed
     whenever a username is needed. If it is not set or the string on
     the line doesn't match any of the strings in this list, all
     usernames will be completed.

users-hosts
     The values of this style should be of the form `USER@HOST' or
     `USER:HOST'. It is used for commands that need pairs of user- and
     hostnames.  For such commands, only the pairs from this style are
     used and if, for example, the username is already typed, then only
     the hostnames for which there is a pair with that username is
     defined.

     If set for the my-accounts tag, this is used for commands such as
     rlogin and ssh; in this case the style should contain the names of
     the user's own accounts on remote hosts.  If set for the
     other-accounts tag, it is used for commands such as talk and
     finger and should contain other people's accounts.  Finally, it
     may also be used by some commands with the accounts tag.

users-hosts-ports
     Like users-hosts but used for commands like telnet and containing
     strings of the form `USER@HOST:PORT'.

verbose
     This is used in several contexts to decide if only a simple or a
     verbose list of matches should be generated. For example some
     commands show descriptions for option names if this style is
     `true'.

     The default value for this style is `true'.

word
     This is used by the _list 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.