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

1 files changed, 195 insertions, 197 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 8834fd489..af17d9434 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -66,13 +66,14 @@ tt(compinstall) it will be called automatically from your tt(.zshrc).
 
 To initialize the system, the function tt(compinit) should be in a
 directory mentioned in the tt($fpath) variable, and should be autoloaded
-(`tt(autoload -U compinit)' is recommended).  When run, it will define a
+(`tt(autoload -U compinit)' is recommended), and then run simply as
+`tt(compinit)'.  This will define a
 few utility functions, arrange for all the necessary shell functions to be
 autoloaded, and will then re-bind all keys that do completion to use the
-new system. Note that this means that the tt(zsh/complist) module has
-to be loaded before the completion system is initialized (i.e. the
-tt(compinit) function is called) to make sure that the tt(menu-select)
-widget defined by it will be redefined, too.
+new system.  If you use the tt(menu-select) widget, which is part of the
+tt(zsh/complist) module, you should make sure that that module is loaded
+before the call to tt(compinit) to make sure that that widget is also
+re-bound.
 
 Should you need to use the original completion commands, you can still
 bind keys to the old functions by putting a `tt(.)' in front of the
@@ -84,14 +85,14 @@ default, although it can be turned off by calling tt(compinit) with the
 option tt(-D).  The dumped file is tt(.zcompdump) in the same
 directory as the startup files (i.e. tt($ZDOTDIR) or tt($HOME));
 alternatively, an explicit file name can be given by `tt(compinit -d)
-var(dumpfile)'.  On the next call to tt(compinit), the dumped file will be
-read instead of a full initialization.
+var(dumpfile)'.  On the next call to tt(compinit), it will read the dumped
+file instead of performing a full initialization.
 
 If the number of completion files changes, tt(compinit) will recognise this
 and produce a new dump file.  However, if the name of a function or the
 arguments in the first line of a tt(#compdef) function (as described below)
-change, it is easiest to delete the dump file by hand so that the next time
-tt(compinit) will re-create it.
+change, it is easiest to delete the dump file by hand so that
+tt(compinit) will re-create it the next time it is run.
 
 The dumping is actually done by another function, tt(compdump), but you
 will only need to run this yourself if you change the configuration
@@ -109,13 +110,12 @@ The convention for autoloaded functions used in completion is that they
 start with an underscore; as already mentioned, the tt(fpath/FPATH)
 parameter must contain the directory in which they are stored.  If tt(zsh)
 was properly installed on your system, then tt(fpath/FPATH) automatically
-contains the required directories.
+contains the required directories for the standard functions.
 
 For incomplete installations, if tt(compinit) does not find enough files
 beginning with an underscore (fewer than twenty) in the search path, it
 will try to find more by adding the directory tt(_compdir) to the search
-path; if you have run tt(compinstall), this will be set automatically.
-Furthermore, if the directory in question ends in the path segment
+path.  Furthermore, if the directory in question ends in the path segment
 tt(Core), or has a subdirectory named tt(Core), tt(compinit) will add all
 subdirectories of the directory where tt(Core) is to the path: this allows
 the functions to be in the same format as in the tt(zsh) source
@@ -124,7 +124,7 @@ distribution.
 cindex(compdef, use of by compinit)
 When tt(compinit) is run, it searches all such files accessible via
 tt(fpath/FPATH) and reads the first line of each of them.  This line should
-contain one of the tags described below. Files whose first line does not
+contain one of the tags described below.  Files whose first line does not
 start with one of these tags are not considered to be part of the
 completion system and will not be treated specially.
 
@@ -150,23 +150,22 @@ completion function for the command on the line could be found.
 )
 item(tt(#compdef -k) var(style key-sequences...))(
 This can be used to bind special completion functions to the
-var(key-sequences).  It creates a widget behaving like the builtin widget
-var(style), which must be one of those that perform completion, namely
-tt(complete-word), tt(delete-char-or-list), tt(expand-or-complete),
-tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete),
-tt(menu-expand-or-complete), or tt(reverse-menu-complete). If the
-tt(zsh/complist) module is loaded (see
+var(key-sequences) specified.  It creates a widget behaving like the
+builtin widget var(style), which must be one of those that perform
+completion, namely tt(complete-word), tt(delete-char-or-list),
+tt(expand-or-complete), tt(expand-or-complete-prefix), tt(list-choices),
+tt(menu-complete), tt(menu-expand-or-complete), or
+tt(reverse-menu-complete).  If the tt(zsh/complist) module is loaded (see
 ifzman(zmanref(zshmodules))\
 ifnzman(noderef(The zsh/complist Module))\
-), the tt(menu-select) widget can be used, too.  Note that the
-bindings will not be used if the key is already bound (that
-is, is bound to something other than tt(undefined-key)).
+), the same happens to the tt(menu-select) widget.
 
 The widget is then bound to all the var(key-sequences) given, if any: when
 one of the var(key-sequences) is typed, the function in the file will
-be invoked to generate the matches. The widget created has the same
-name as the file and can also be bound to other keys using tt(bindkey) 
-as usual.
+be invoked to generate the matches.  Note that a key will not be re-bound
+if if it already was (that is, was bound to something other than
+tt(undefined-key)).  The widget created has the same name as the file and
+can be bound to any other keys using tt(bindkey) as usual.
 )
 item(tt(#compdef -K) var(widget-name) var(style) var(key-sequences) ...)(
 This is similar to tt(-k), with the same var(style) and var(key-sequences)
@@ -191,27 +190,24 @@ when invoked.  Typically they are to be called from within one of the
 completion functions.
 
 The var(options) will be given to the tt(autoload) builtin command
-when making the function autoloaded. Note that the tt(-U) flag is
-always used. Most often, this will be tt(+X) to force the function
-to be loaded immediately.
+when making the function autoloaded.  Most often, this will be tt(+X) to
+force the function to be loaded immediately.  Note that the tt(-U) flag is
+always implicitly added.
 )
 enditem()
 
-Note that the tt(#) is part of the tag name and no white space is allowed
-after it.  The tt(#compdef) tags use the tt(compdef) function described
-below; the main difference is that the name of the function is supplied
-implicitly.
+The tt(#) is part of the tag name and no white space is allowed after it.
+The tt(#compdef) tags use the tt(compdef) function described below; the
+main difference is that the name of the function is supplied implicitly.
 
 Note also that the functions for the completion system assume that the
-tt(KSH_AUTOLOAD) option is not set, they can't be loaded when it is
-set. But when you can't or don't want to unset tt(KSH_AUTOLOAD) and
-still want to use the completion system, you can simply use one or
-more tt(zwc) file(s) created with the tt(zcompile) builtin command
-with the tt(-z) option to load the functions for the completion system 
-from (see
+tt(KSH_AUTOLOAD) option is not set and cannot be loaded when it is
+set.  To avoid having to unset tt(KSH_AUTOLOAD), you can instead use one or
+more tt(zwc) file(s) which have been created with the command tt(zcompile
+-z) to load the functions for the completion system; see
 ifzman(zmanref(zshbuiltins))\
 ifnzman(noderef(Shell Builtin Commands))\
-). This forces the functions to be autoloaded the way zsh normally
+.  This forces the functions to be autoloaded the way zsh normally
 loads functions.
 
 subsect(Functions)
@@ -284,15 +280,15 @@ was tried.  The context depends on such things as the name of the
 command when completing an argument, and possibily also
 the name of an option when completing an argument to that option.
 
-For the context a name consisting of multiple fields is built. This
-name is then used to look up styles that can be used to configure the
-completion system. Since it is not possible to build the whole context 
-name in advance, completion functions may modify some of the fields and 
-hence the context name used for lookup may vary during the same call
+The `context' of a completion is a string consisting of multiple fields. This
+is used to look up styles that can be used to configure the
+completion system.  Since it is not possible to build the whole context 
+string in advance, completion functions may modify some of the fields and 
+hence the context used for lookup may vary during the same call
 to the completion system.
 
-The context name always consists of the following fields, separated
-by colons:
+The context string always consists of the following fields, separated
+by colons and with a leading colon before the first:
 
 startitemize()
 itemiz(\
@@ -303,12 +299,12 @@ itemiz(\
 The var(function); in many cases this field will be blank, but when
 the completion system is called from other functions, like
 tt(predict-on) or one of the functions in the tt(Command) directory of 
-the distribution, this field contains the (probably abbreviated) name
-of that function.
+the distribution, this field contains the name of that function, often
+in an abbreviated form.
 )
 itemiz(\
-The var(completer) currently active, i.e. the name of the completer
-function without the leading underscore. Such a completer is in
+The var(completer) currently active, which is the name of the function
+without the leading underscore.  A `completer' is in
 overall control of how completion is to be performed; `tt(complete)'
 is the basic one for ordinary completion, but completers may perform
 various related tasks such as correction, or modify the behaviour of a
@@ -318,10 +314,10 @@ ifnzman(noderef(Control Functions))
 for more information).  
 )
 itemiz(\
-The var(context) or var(command). This is either one of the special
+The var(context) or var(command).  This is either one of the special
 context names such as tt(-condition-) as explained for the
 tt(_complete) completer below, or the name of the command we are
-completing arguments for. Completion functions for commands that have
+completing arguments for.  Completion functions for commands that have
 sub-commands usually modify this field to contain the name of the
 command followed by a minus sign and the sub-command (e.g. the
 completion function for the tt(cvs) command sets this field to strings
@@ -329,15 +325,14 @@ such as tt(cvs-add) when completing for the tt(add) sub-command).
 )
 itemiz(\
 The var(argument), describing which argument we are
-completing. Normally this is either a string of the form
+completing.  Normally this is either a string of the form
 tt(argument-)var(n), where var(n) is the number of the argument or it
 is a string of the form tt(option-)var(opt)tt(-)var(n) when completing the
 var(n)'th argument of the option var(opt).
 )
 itemiz(\
-The var(tag). Tags are used for two purposes:  to describe the types
-of matches a completion function can generate for a certain context
-and to simplify the definition of styles that are tested.
+The var(tag).  Tags are used to discriminate between the types
+of matches a completion function can generate in a certain context.
 )
 enditemize()
 
@@ -358,17 +353,18 @@ below.  To determine in which order the tags are to be used by the
 completion function, the `tt(tag-order)' style for the appropriate
 context may be set, as described in the list of standard styles below.
 Only those types of matches whose tags were selected by this style
-will be produced, and in the order given.
+will be produced, and in the order given, although the default is to try
+all relevant tags in an order determined by the particular completion in
+use.
 
 The tt(_complete_help) bindable command described in 
 ifzman(the section `Bindable Commands' below)\
 ifnzman(noderef(Bindable Commands))
-can be invoked to find out the context and tag names and styles used at a particular
-point in completion.  It shows a list of context names and the 
-tag names used in those contexts if completion were tried at the
-current cursor position.  Hence one can easily find out all the
-information needed to change the behaviour of the tt(tag-order) style
-for a particular context.
+can be invoked to find out the context and tag names and styles used at a
+particular point in completion.  It shows the list of contexts and tags 
+that would be used in if completion were tried at the current cursor
+position.  Hence one can easily find out all the information needed to
+change the behaviour of the tt(tag-order) style for a particular context.
 
 Completion behaviour can be modified by various other
 styles defined with the tt(zstyle) builtin command (\
@@ -386,22 +382,23 @@ the style itself, which must be given exactly.
 
 For example, many completion functions can generate matches in a
 simple and a verbose form and use the tt(verbose) style to decide
-which form should be used. To make all such functions always use the
-verbose form one can simply call
+which form should be used.  To make all such functions use the verbose form,
+put
 
 example(zstyle ':completion:*' verbose yes)
 
-in one of the startup files like tt(.zshrc). This definition simply
+in one of the startup files like tt(.zshrc); this sort of style can also be
+configured with the tt(compinstall) function.  This definition simply
 means that the tt(verbose) style has tt(yes) as its value in every
-context inside the completion system.  If the pattern were `tt(*)', it
-would mean that the verbose style had this value anywhere the style
-mechanism is used.
+context inside the completion system.  If the context pattern were `tt(*)',
+the verbose style would have this value anywhere the style mechanism is
+used, not just in completion.
 
 As a more specific example, the completion function for the tt(kill)
 builtin command uses the tt(verbose) style to decide if jobs and processes
 are listed only as job numbers and process identifiers or if they are
 listed with the full job texts and the command lines of the processes (the
-latter is achieved by calling the tt(ps) command). To make this builtin
+latter is achieved by calling the tt(ps) command).  To make this builtin
 list the matches only as numbers one could call:
 
 example(zstyle ':completion:*:*:kill:*' verbose no)
@@ -420,18 +417,17 @@ preferred over patterns (for example, `tt(:completion::complete:foo)' is
 more specific than `tt(:completion::complete:*')), and longer patterns are
 preferred over shorter patterns.
 
-As for tags, completion functions can use any number of styles, so
-there can't be a complete list. However, the following two sections
+As with tags, completion functions can use any style they choose, so
+there can't be a complete list.  However, the following two sections
 list those tags and styles that are used in many places of the
 completion system.
 
 subsect(Standard Tags)
 cindex(completion system, tags)
 
-Here are the tags currently used by the completion system. Note that
-some of these tags are not actually used while generating matches,
-but are only used by some completion functions when looking up
-styles.
+Here are the tags currently used by the completion system.  Some of them
+are only used when looking up styles and do not refer to a particular type
+of match.
 
 startitem()
 kindex(accounts, completion tag)
@@ -440,12 +436,13 @@ used to look up the tt(users-hosts) style
 )
 kindex(all-files, completion tag)
 item(tt(all-files))(
-for the names of all files
+for the names of all files (as distinct from a particular subset, see the
+tt(globbed-files) tag).
 )
 kindex(all-expansions, completion tag)
 item(tt(all-expansions))(
-used by the tt(_expand) completer when adding the string containing
-all expansions
+used by the tt(_expand) completer when adding the single string containing
+all possible expansions
 )
 kindex(arguments, completion tag)
 item(tt(arguments))(
@@ -457,8 +454,8 @@ for names of array parameters
 )
 kindex(association-keys, completion tag)
 item(tt(association-keys))(
-for keys of associative arrays (e.g. when completing inside a
-subscript of such a parameter)
+for keys of associative arrays; used when completing inside a
+subscript of a parameter of this type
 )
 kindex(bookmarks, completion tag)
 item(tt(bookmarks))(
@@ -523,7 +520,8 @@ for network domains
 )
 kindex(expansions, completion tag)
 item(tt(expansions))(
-used by the tt(_expand) completer for possible expansions
+used by the tt(_expand) completer for individual possibilities resulting
+from expansion of a word
 )
 kindex(extensions, completion tag)
 item(tt(extensions))(
@@ -531,8 +529,8 @@ for X server extensions
 )
 kindex(files, completion tag)
 item(tt(files))(
-used by completion functions that can complete some kind of filenames
-and different types of matches
+the generic file-matching tag used by completion functions that can
+complete the names of some kind of file
 )
 kindex(fonts, completion tag)
 item(tt(fonts))(
@@ -540,8 +538,8 @@ used for X font names
 )
 kindex(functions, completion tag)
 item(tt(functions))(
-names of functions (shell functions or other kinds of functions for
-some commands)
+names of functions, normally shell functions although certain commands may
+understand other kinds of function
 )
 kindex(globbed-files, completion tag)
 item(tt(globbed-files))(
@@ -578,8 +576,8 @@ for names of X keysyms
 )
 kindex(local-directories, completion tag)
 item(tt(local-directories))(
-for names of directories in the current working directory when
-completing for the tt(cd) builtin command
+for names of directories which are subdirectories of the current working
+directory when completing for the tt(cd) and related builtin commands
 )
 kindex(libraries, completion tag)
 item(tt(libraries))(
@@ -595,7 +593,7 @@ for names of manual pages
 )
 kindex(maps, completion tag)
 item(tt(maps))(
-for map names (e.g. YP maps)
+for map names (e.g. NIS maps)
 )
 kindex(messages, completion tag)
 item(tt(messages))(
@@ -623,7 +621,7 @@ for all kinds of names
 )
 kindex(nicknames, completion tag)
 item(tt(nicknames))(
-for nicknames of YP maps
+for nicknames of NIS maps
 )
 kindex(options, completion tag)
 item(tt(options))(
@@ -648,8 +646,8 @@ for names of parameters
 )
 kindex(path-directories, completion tag)
 item(tt(path-directories))(
-for names of directories in directories from the tt(cdpath) array when
-completing for the tt(cd) builtin command
+for names of directories found by searching the tt(cdpath) array when
+completing for the tt(cd) and related builtin commands
 )
 kindex(paths, completion tag)
 item(tt(paths))(
@@ -658,7 +656,7 @@ tt(special-dirs) styles
 )
 kindex(pods, completion tag)
 item(tt(pods))(
-for perl pods
+for perl pods (documentation files)
 )
 kindex(ports, completion tag)
 item(tt(ports))(
@@ -754,26 +752,27 @@ enditem()
 subsect(Standard Styles)
 cindex(completion system, styles)
 
-Here are the names of the styles used by the completion system. Note
+Here are the names of the styles used by the completion system.  Note
 that the values of several of these styles represent boolean
-values. In all these cases any of the strings `tt(true)', `tt(on)',
+values; here, any of the strings `tt(true)', `tt(on)',
 `tt(yes)', and `tt(1)' can be used for the truth value `true' and
 the strings `tt(false)', `tt(off)', `tt(no)', and `tt(0)' are
 interpreted as `false'.  The behavior for any other value is undefined 
 unless the description for the particular style mentions other
-possible values.
+possible values; in particular, the default value may be either on or off
+if the style is not set.
 
 startitem()
 kindex(accept-exact, completion style)
 item(tt(accept-exact))(
 This is tested for the default tag and the tags used when generating
-matches. If it is set to `true' for at least one match which is the
+matches.  If it is set to `true' for at least one match which is the
 same as the string on the line, this match will immediately be
 accepted.
 )
 kindex(add-space, completion style)
 item(tt(add-space))(
-This style is used by the tt(_expand) completer. If it is `true' (the
+This style is used by the tt(_expand) completer.  If it is `true' (the
 default), a space will be inserted after all words resulting from the 
 expansion (except for directory names which get a slash).
 
@@ -782,19 +781,17 @@ be inserted before the suffix.
 )
 kindex(ambiguous, completion style)
 item(tt(ambiguous))(
-This is used with the tt(paths) tag by the function
-generating filenames as matches to find out if the cursor should be left
-after the first ambiguous pathname component even when menucompletion
-is used.
+This applies when completing non-final components of filename paths.
+If it is set, the cursor is left after the first ambiguous component, even
+if menucompletion is in use.  It is tested with the tt(paths) tag.
 )
 kindex(assign-list, completion style)
 item(tt(assign-list))(
 When completing after an equal sign, the completion system normally
-completes only one filename.  But when completing the value for some
-parameters or after other strings separated by an equal sign from a
-value, a colon-separated list of filenames is needed. This style
-can be set to a list of patterns matching the names of parameters for
-which such a colon-separated list of filenames should be completed.
+completes only one filename.  In some cases, particularly for certain
+parameters such as tt(PATH), a list of filenames separated by colons is
+required.  This style can be set to a list of patterns matching the names
+of such parameters.
 
 The default is to complete lists when the word on the line already
 contains a colon.
@@ -803,8 +800,8 @@ kindex(auto-description, completion style)
 item(tt(auto-description))(
 If set, this style's value will be used as the description for options which
 are not described by the completion functions, but that have exactly
-one argument. The sequence `tt(%d)' in the value will be replaced by
-the description for this argument. Depending on personal preferences,
+one argument.  The sequence `tt(%d)' in the value will be replaced by
+the description for this argument.  Depending on personal preferences,
 it may be useful to set this style to something like `tt(specify: %d)'. 
 Note that this may not work for some commands.
 )
@@ -818,27 +815,26 @@ further effect.
 )
 kindex(command, completion style)
 item(tt(command))(
-This style can be used to override the defaults in several completion
-functions for how commands are called to generate information about
-possible matches. The strings in the value are joined with spaces
-between them to build the command line to execute. If the value starts 
-with a hyphen the string built will be prepended to the default
-supplied by the completion function. This allows one to easily stick a 
-tt(builtin) or tt(command) in front of the default in case one has,
-for example, a shell function with the same name as the command
-called, but for completion purposes one needs to ensure that the real
-command is called.
-
-For example, the function generating process IDs as matches uses this
+In many places, completion functions need to call external commands to
+generate the list of completions.  This style can be used to override the
+command which is called in some such cases.  The elements of the value are
+joined with spaces to form a command line to execute.  The value can also
+start with a hyphen, in which case the usual command will be added to the
+end; this is most useful for putting `tt(builtin)' or `tt(command)' in
+front to make sure the appropriate version of a command is called, for
+example to avoid calling a shell function with the same name as an external
+command.
+
+As an example, the function generating process IDs as matches uses this
 style with the tt(processes) tag to generate the IDs to complete and when
 the tt(verbose) style is `true', it uses this style with the
-tt(processes-list) tag to generate the strings to display. When using
+tt(processes-list) tag to generate the strings to display.  When using
 different values for these two tags one should ensure that the process
 IDs appear in the same order in both lists.
 )
 kindex(completer, completion style)
 item(tt(completer))(
-The strings given as the value of this style give the names of the
+The strings given as the value of this style provide the names of the
 completer functions to use. The available completer functions are
 described in
 ifzman(the section `Control Functions' below)\
@@ -849,29 +845,29 @@ Each string may be the name of a completer function or a string of the
 form `var(function)tt(:)var(name)'. In the first case the
 var(completer) field of the context will contain the name of the
 completer without the leading underscore and with all other
-underscores replaced with hyphens. In the second case the
+underscores replaced by hyphens.  In the second case the
 var(function) is the name of the completer to call, but the context
 will contain the var(name) in the var(completer) field of the
-context. If the var(name) starts with a hyphen, the string for the
+context.  If the var(name) starts with a hyphen, the string for the
 context will be build from the name of the completer function as in
-the first case with the var(name) appended to it. For example: 
+the first case with the var(name) appended to it.  For example: 
 
 example(zstyle ':completion:*' completer _complete _complete:-foo)
 
 Here, completion will call the tt(_complete) completer twice, once
 using `tt(complete)' and once using `tt(complete-foo)' in the
-var(completer) field of the context. Normally, using the same
+var(completer) field of the context.  Normally, using the same
 completer more than once makes only sense when used with the
 `var(functions)tt(:)var(name)' form, because otherwise the context
-name will be the same in all calls to the completer (possible
+name will be the same in all calls to the completer; possible
 exceptions to this rule are the tt(_ignored) and tt(_prefix)
-completers).
+completers.
 
 Note that the widget functions from the distribution that call the
 completion code (namely, the tt(incremental-complete-word) and the
 tt(predict-on) widgets) set up their top-level context name before
-calling completion. This allows one to define different sets of
-completer functions for normal completion and for these widgets. For
+calling completion.  This allows one to define different sets of
+completer functions for normal completion and for these widgets.  For
 example, to use completion, approximation and correction for normal
 completion, completion and correction for incremental completion and
 only completion for prediction one could use:
@@ -901,9 +897,9 @@ item(tt(condition))(
 This style is used by the tt(_list) completer function.
 
 If it is not set or set to the empty string, the insertion of
-matches will be delayed unconditionally. If it is set, the value
+matches will be delayed unconditionally.  If it is set, the value
 should be an expression usable inside a `tt($((...)))'
-arithmetical expression. In this case, delaying will be done if the
+arithmetical expression.  In this case, delaying will be done if the
 expression evaluates to `tt(1)'. For example, with
 
 example(zstyle ':completion:*:list:::' condition '${NUMERIC:-1} != 1')
@@ -918,15 +914,15 @@ cursor after completion has been tried.  Values are:
 
 startitem()
 item(tt(complete))(
-The cursor is left at the place where completion left it, but only if
-it is after a character equal to the one just inserted by the user. If 
+The cursor is left where it was when completion finished, but only if
+it is after a character equal to the one just inserted by the user.  If 
 it is after another character, this value is the same as `tt(key)'.
 )
 item(tt(key))(
 The cursor is left
 after the var(n)th occurrence of the character just inserted, where
 var(n) is the number of times that character appeared in the word
-before completion was attempted. In short, this has the effect of
+before completion was attempted.  In short, this has the effect of
 leaving the cursor after the character just typed even if the
 completion code found out that no other characters need to be inserted 
 at that position.
@@ -940,23 +936,24 @@ kindex(disable-stat, completion style)
 item(tt(disable-stat))(
 This is used with an empty tag by the function completing for the
 tt(cvs) command to decide if the tt(zsh/stat) module should be used to
-generate only names of modified files in the appropriate places.
+generate names of modified files in the appropriate places (this is its
+only use).  If set, completion will use the tt(ls) command.
 )
 kindex(domains, completion style)
 item(tt(domains))(
 If set, gives the names of network domains that should be
-completed. If this is not set by the user domain names mentioned in
-tt(/etc/resolv.conf) will be used.
+completed.  If this is not set by the user domain names will be taken from
+the file tt(/etc/resolv.conf).
 )
 kindex(expand, completion style)
 item(tt(expand))(
 This style is used when completing strings consisting of multiple
-parts, such as path names. If its
+parts, such as path names.  If its
 value contains the string `tt(prefix)', the partially typed word from
 the line will be expanded as far as possible even if trailing parts
-can not be completed. If it contains the string `tt(suffix)'
+cannot be completed.  If it contains the string `tt(suffix)'
 and normal (non-menu-) completion is used, matching names for
-components after the first ambiguous one will be added, too. This
+components after the first ambiguous one will also be added.  This
 means that the resulting string is the longest unambiguous string
 possible, but if menucompletion is started on the list of matches
 generated this way (e.g. due to the option tt(AUTO_MENU) being set),
@@ -966,35 +963,35 @@ components after the first ambiguous one.
 kindex(file-patterns, completion style)
 item(tt(file-patterns))(
 In most places where filenames are completed, the function tt(_files)
-is used which can be configured with this style. If the style is
+is used which can be configured with this style.  If the style is
 unset, tt(_files) offers, one after another, up to three tags:
 `tt(globbed-files)',
 `tt(directories)' and `tt(all-files)', depending on the types of files
 expected by the caller of tt(_files).
 
 If the tt(file-patterns) style is set, the default tags are not
-used. Instead, the value of the style says which tags and which
-patterns are to be offered. The strings in the value contain
+used.  Instead, the value of the style says which tags and which
+patterns are to be offered.  The strings in the value contain
 specifications of the form
 `var(pattern)tt(:)var(tag)'; each string may contain any number of
-such specifications. The var(pattern) gives a glob 
+such specifications.  The var(pattern) gives a glob 
 pattern that is to be used to generate
-filenames. If it contains the sequence `tt(%p)', that is replaced by
+filenames.  If it contains the sequence `tt(%p)', that is replaced by
 the pattern(s) given by the calling function.
-Colons in the pattern have to be preceded by a backslash to
-make them distinguishable from the colon before the var(tag). If more
+Colons in the pattern must be preceded by a backslash to
+make them distinguishable from the colon before the var(tag).  If more
 than one pattern is needed, the patterns can be given inside braces,
-separated by commas. The
+separated by commas.  The
 var(tag)s of all strings in the value will be offered by tt(_files)
-(again, one after another) and used when looking up other styles. For
+(again, one after another) and used when looking up other styles.  For
 strings containing more than one specification, the filenames for all
-specifications will be generated at the same try. If
-no `tt(:)var(tag)' is given the `tt(files)' tag will be used. The
+specifications will be generated at the same try.  If
+no `tt(:)var(tag)' is given the `tt(files)' tag will be used.  The
 var(tag) may also be
-followed by an optional second colon and a description. If that is
+followed by an optional second colon and a description.  If that is
 given, this description will be used for the `tt(%d)' in the value of
 the tt(format) style (if that is set) instead of the default
-description supplied by the completion function. If the description
+description supplied by the completion function.  If the description
 given here contains itself a `tt(%d)', that is replaced with the
 description supplied by the completion function.
 
@@ -1007,9 +1004,9 @@ example(zstyle ':completion:*:*:rm:*' file-patterns \
 
 Another interesting example is to change the default behaviour that
 makes completion first offer files matching the patterns given by the
-calling function, then directories and then all files. Many people 
+calling function, then directories and then all files.  Many people 
 prefer to get both the files matching the given patterns and the
-directories in the first try and all files at the second try. To
+directories in the first try and all files at the second try.  To
 achieve this, one could do:
 
 example(zstyle ':completion:*' file-patterns \ 
@@ -1023,25 +1020,25 @@ kindex(file-sort, completion style)
 item(tt(file-sort))(
 The completion function that generates filenames as possible matches
 uses this style with the tt(files) tag to determine in which order the 
-names should be listed and completed when using menucompletion. The
+names should be listed and completed when using menucompletion.  The
 value may be one of `tt(size)' to sort them by the size of the file,
 `tt(links)' to sort them by the number of links to the file,
 `tt(modification)' (or `tt(time)' or `tt(date)') to sort them by the last
 modification time, `tt(access)' to sort them by the last access time, or
 `tt(inode)' (or `tt(change)') to sort them by the last inode change
-time. Any other value (or not setting this style at all) makes them be 
-sorted alphabetically by name. If the value contains the string
+time.  If the style is set to any other value, or is unset, files will be
+sorted alphabetically by name.  If the value contains the string
 `tt(reverse)', sorting is done in decreasing order.
 )
 kindex(force-list, completion style)
 item(tt(force-list))(
-If the completion code would show a list of completions at all, this
-style controls whether the list is shown even in cases when it would
-normally not do that. For example, normally the list is only shown if
-there are at least two different matches. By setting this style to
+This forces a list of completions to be shown at any point where listing is
+done, even in cases where the list would usually be suppressed.
+For example, normally the list is only shown if
+there are at least two different matches.  By setting this style to
 `tt(always)', the list will always be shown, even if there is only a
-single match which is immediately accepted. The style may also
-be set to a number. In this case the list will be shown if there are
+single match which is immediately accepted.  The style may also
+be set to a number.  In this case the list will be shown if there are
 at least that many matches, even if they would all insert the same
 string.
 
@@ -1052,33 +1049,33 @@ for certain types of matches.
 kindex(format, completion style)
 item(tt(format))(
 If this is set for the tt(descriptions) tag, its value is used as a
-string to display above matches in completion lists. The sequence
+string to display above matches in completion lists.  The sequence
 `tt(%d)' in this string will be replaced with a short description of
-what these matches are. This string may also contain the sequences to
+what these matches are.  This string may also contain the sequences to
 specify output attributes, such as `tt(%B)', `tt(%S)' and
 `tt(%{)...tt(%})'.
 
 For the same purpose, this style is also tested with the tags used
 when matches are generated before it is tested for the
-tt(descriptions) tag. This gives the possibility to define different
+tt(descriptions) tag.  This gives the possibility to define different
 format strings for different types of matches.
 
 Note also that some completer functions define additional
-`tt(%)'-sequences. These are described for the completer functions that 
+`tt(%)'-sequences.  These are described for the completer functions that 
 make use of them.
 
 For the tt(messages) tag, this defines a string used by some
-completion functions to display messages. Here, the `tt(%d)' is
+completion functions to display messages.  Here, the `tt(%d)' is
 replaced with the message given by the completion function.
 
-Finally, for the tt(warnings) tag, it is printed when no matches could 
-be generated at all. In this case the `tt(%d)' is replaced with the
-descriptions for the matches that were expected. If the value does not 
-contain a `tt(%d)', then those descriptions are added in the same way
-as matches are added, i.e. they appear below the value for the
-tt(format) style laid out in columns. The descriptions are added as if 
-for the tag tt(warnings) so that you can use the tt(list-colors) style 
-for that tag to highlight them.
+Finally, when set with the tt(warnings) tag, the format string is printed
+when no matches could be generated at all.  In this case the `tt(%d)' is
+replaced with the descriptions for the matches that were expected.  If the
+value does not contain a `tt(%d)', then those descriptions are added in the
+same way as matches are added, i.e. they appear below the value for the
+tt(format) style laid out in columns.  The descriptions are added as if for
+the tag tt(warnings) so that you can use the tt(list-colors) style for that
+tag to highlight them.
 
 The `tt(%)' for the sequences that are replaced by strings provided by 
 the completion functions like the `tt(%d)' may be followed by field
@@ -1101,11 +1098,11 @@ kindex(group-name, completion style)
 item(tt(group-name))(
 The completion system can put different types of matches in different
 groups which are then displayed separately in the list of possible
-completions. This style can be used to give the names for these groups
-for particular tags. For example, in command position the completion
+completions.  This style can be used to give the names for these groups
+for particular tags.  For example, in command position the completion
 system generates names of builtin and external commands, names of
 aliases, shell functions and parameters and reserved words as possible
-completions. To have the external commands and shell functions listed
+completions.  To have the external commands and shell functions listed
 separately, one can set:
 
 example(zstyle ':completion:*:*:-command-:*:commands' group-name commands
@@ -1129,7 +1126,7 @@ item(tt(group-order))(
 This style is to be used together with the tt(group-name) style. Once
 different types of matches are put into different groups, this style
 can be used to define in which order these groups should appear in the 
-list. The strings in the value are taken as group names and the named
+list.  The strings in the value are taken as group names and the named
 groups will be shown in the order in which their names appear in the
 value. All groups whose names are not given in the value of this style 
 will appear in the order defined by the function generating the
@@ -1153,12 +1150,12 @@ item(tt(hidden))(
 If this is set to one of the `true' values, the matches for the tags
 for which this is set will not appear in the list; only the
 description for the matches as set with the tt(format) style will be
-shown. If this is set to `tt(all)', not even the description will be
+shown.  If this is set to `tt(all)', not even the description will be
 displayed.
 
-Note that the matches will still be completed, they are just not shown 
-in the list. To avoid having matches considered as possible
-completions at all the tt(tag-order) style can be modified as described
+Note that the matches will still be completed; they are just not shown 
+in the list.  To avoid having matches considered as possible
+completions at all, the tt(tag-order) style can be modified as described
 below.
 )
 kindex(hosts, completion style)
@@ -1169,20 +1166,20 @@ is not set by the user the hostnames in `tt(/etc/hosts)' will be used.
 kindex(hosts-ports, completion style)
 item(tt(hosts-ports))(
 This style is used by commands that need or accept hostnames and
-ports. The strings in the value should be of the form
-`var(host)tt(:)var(port)'. These hostnames and ports are completed
+ports.  The strings in the value should be of the form
+`var(host)tt(:)var(port)'.  These hostnames and ports are completed
 depending on the information already on the line, so that if, for
-example, the hostname is already typed, only those ports will be
-completed for which pairs with the hostname from the line exist.
+example, the hostname is already typed, only those ports specified for that
+host will be completed.  Multiple ports for the same host may appear.
 )
 kindex(ignore-line, completion style)
 item(tt(ignore-line))(
-This style is tested for the tags used when generating matches. If it
+This style is tested for the tags used when generating matches.  If it
 is set to `true', then none of the words that are already on the line
 will be considered possible completions.
 
 Note that you almost certainly don't want to set this for a general
-context such as `tt(:completion:*)'. This is because it would disallow
+context such as `tt(:completion:*)'.  This is because it would disallow
 completion of, for example, options multiple times even if the command
 in question accepts the option more than once.
 )
@@ -1226,10 +1223,11 @@ it is possible to complete these directories nonetheless.
 )
 kindex(ignored-patterns, completion style)
 item(tt(ignored-patterns))(
-This style is used with the tags for adding matches and defines a couple
-of patterns. All matches that are also matched by any of these patterns
-are ignored (not offered as completions) until the tt(_ignored) completer
-is tried (see the tt(completer) style).  This is a more configurable
+This style can be used to specify a list of patterns which are tested
+against against the trial completions in a given context; any matching
+completions will be removed from the list of possibilities.  The
+tt(_ignored) completer can appear in the list of completers to produce a
+list which includes these matches once more.  This is a more configurable
 version of the shell parameter tt($fignore).
 
 Note that during the execution of completion functions, the