unposted: complete compsys.yo rewrite

1 files changed, 383 insertions, 355 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 9b00bf1a2..4065b3cbe 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -3050,13 +3050,13 @@ tt(compadd) with additional options which will take precedence over
 those generated by tt(_all_labels).
 )
 findex(_alternative)
-item(tt(_alternative) [ tt(-C) var(name) ] var(specs) ...)(
+item(tt(_alternative) [ tt(-C) var(name) ] var(spec) ...)(
 This function is useful in simple cases where multiple tags are available.
 Essentially it implements a loop like the one described for the tt(_tags)
 function below.
 
 The tags to use and the action to perform if a tag is requested are
-described using the var(specs) which are of the form:
+described using the var(spec)s which are of the form:
 `var(tag)tt(:)var(descr)tt(:)var(action)'.  The var(tag)s are offered using
 tt(_tags) and if the tag is requested, the var(action) is executed with the
 given description var(descr).  The var(action)s are those accepted
@@ -3144,8 +3144,8 @@ same word.  However, it depends on the action performed whether options
 will really be completed at this point.  For more control, use a
 utility function like tt(_guard) as part of the action.
 
-If the option takes an argument, the forms given above are to be followed
-by one or more of the following var(optspec)s:
+The following forms are available for the initial var(optspec), whether
+or not the option has arguments.
 
 startitem()
 item(tt(*)var(optspec))(
@@ -3700,40 +3700,51 @@ tt(_describe) uses the tt(_all_labels) function to generate the matches, so
 it does not need to appear inside a loop over tag labels.
 )
 findex(_description)
-item(tt(_description) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])(
-This function is called before completions are added (typically by a call
-to tt(compadd)); it tests various styles and arranges for any necessary
-options to be passed on to tt(compadd).  The styles are tested in the
-current context using the given var(tag); options are put into the array
-called var(name) for passing on to tt(compadd); the description for the
-current set of matches is passed in var(descr).  The styles tested are:
-tt(format) (which is first tested for the given var(tag) and then for the
-tt(descriptions) tag if that isn't defined), tt(hidden), tt(matcher),
-tt(ignored-patterns) and tt(group-name) (the last are tested only for the
-tag given as the first argument).  This function also calls the tt(_setup)
-function which tests some more styles.
+item(tt(_description) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(spec) ... ])(
+This function is not to be confused with the previous one; it is used as
+a helper function for creating options to tt(compadd).  It is buried
+inside many of the higher level completion functions and so often does
+not need to be called directly.
+
+The styles listed below are tested in the current context using the
+given var(tag).  The resulting options for tt(compadd) are put into the
+array named var(name) (this is traditionally `tt(expl)', but this
+convention is not enforced).  The description for the corresponding set
+of matches is passed to the function in var(descr).
+
+The styles tested are: tt(format), tt(hidden), tt(matcher),
+tt(ignored-patterns) and tt(group-name).  The tt(format) style is first
+tested for the given var(tag) and then for the tt(descriptions) tag if
+no value was found, while the remainder are only tested for the tag
+given as the first argument.  The function also calls tt(_setup)
+which tests some more styles.
 
 The string returned by the tt(format) style (if any) will be modified so
 that the sequence `tt(%d)' is replaced by the var(descr) given as the third
 argument without any leading or trailing white space.  If, after
 removing the white space, the var(descr) is the empty string, the format
 style will not be used and the options put into the var(name) array will
-not contain an explanation string to be displayed above the matches.  If
-tt(_description) is called with more than three arguments,
-the additional var(specs) should be of the form `var(char)tt(:)var(str)'
-and every appearance of `tt(%)var(char)' in the format string will be
-replaced by var(string).  If the tt(-x) option is given, the
-description will be added using the tt(-x) option instead of the
-default tt(-X), i.e. the description will even be displayed if no
-matches are added for the description.
-
-The options placed in the array will also make sure that the matches
-are placed in a separate group, depending on the value of the
-tt(group-name) style.  Normally a sorted group will be used for this
-(with the `tt(-J)' option), but if an option starting with `tt(-V)',
-`tt(-J)', `tt(-1)', or `tt(-2)' is given, that option will be included
-in the array, so that it is possible to make the group unsorted by
-giving the option `tt(-V)', `tt(-1V)', or `tt(-2V)'. 
+not contain an explanation string to be displayed above the matches.
+
+If tt(_description) is called with more than three arguments,
+the additional var(spec)s should be of the form `var(char)tt(:)var(str)'.
+These supply escape sequence replacements for the tt(format) style:
+every appearance of `tt(%)var(char)' will be
+replaced by var(string).
+
+If the tt(-x) option is given, the description will be passed to
+tt(compadd) using the tt(-x) option instead of the default tt(-X).  This
+means that the description will be displayed even if there are no
+corresponding matches.
+
+The options placed in the array var(name) take account of the
+tt(group-name) style, so matches are placed in a separate group where
+necessary.  The group normally has its elements sorted (by passing the
+option tt(-J) to tt(compadd)), but if an option starting with `tt(-V)',
+`tt(-J)', `tt(-1)', or `tt(-2)' is passed to tt(_description), that
+option will be included in the array.  Hence it is possible for the
+completion group to be unsorted by giving the option `tt(-V)',
+`tt(-1V)', or `tt(-2V)'.
 
 In most cases, the function will be used like this:
 
@@ -3747,120 +3758,117 @@ a similar format; this ensures that user-specified styles are correctly
 passed down to the builtins which implement the internals of completion.
 )
 findex(_dispatch)
-item(tt(_dispatch) var(context strings ...))(
-This looks up the functions defined for the var(strings) one after
-another until it finds one that is defined. That function is then
-called to generate the matches.  Normally, the last var(string) is the
-one used to look up the default completion.
-
-This function is the one responsible for setting the parameter
-tt($service) (to the var(strings) as they are tried) and for setting
-the var(context/command) field of the tt($curcontext) parameter (to
-the var(context) given as the first argument).
+item(tt(_dispatch) var(context string ...))(
+This sets the current context to var(context) and looks for completion
+functions to handle this context by hunting through the list of command
+names or special contexts (as described above for tt(compdef))
+given as var(string ...).  The first completion function to be defined
+for one of the contexts in the list is used to generate matches.
+Typically, the last var(string) is tt(-default-) to cause the function
+for default completion to be used as a fallback.
+
+The function sets the parameter
+tt($service) to the var(string) being tried, and sets
+the var(context/command) field (the fourth) of the tt($curcontext)
+parameter to the var(context) given as the first argument.
 )
 findex(_files)
 item(tt(_files))(
-The function tt(_files) uses the tt(file-patterns) style and calls
-tt(_path_files) with all the arguments it was passed except for tt(-g) 
-and tt(-/).  These two options are used depending on the setting of the 
-tt(file-patterns) style.
+The function tt(_files) calls tt(_path_files) with all the arguments it
+was passed except for tt(-g) and tt(-/).  The use of these two options
+depends on the setting of the  tt(file-patterns) style.
 
-See tt(_path_files) below for a description of the full set of options
-accepted by tt(_files).
+This function accepts the full set of options allowed by
+tt(_path_files), described below.
 )
 findex(_gnu_generic)
 item(tt(_gnu_generic))(
 This function is a simple wrapper around the tt(_arguments) function
-described above.  It can be used to automatically complete long
-options for commands that understand the `tt(-)tt(-help)' option.
-It is not intended to be used from completion functions but as a
-top-level completion function in its own right.  For example, to
-enable option completion for the commands tt(foo) and tt(bar), one
-would call:
+described above.  It can be used to determine automatically the long
+options understood by commands that produce a list when passed the
+option `tt(-)tt(-help)'.  It is intended to be used as a top-level
+completion function in its own right.  For example, to enable option
+completion for the commands tt(foo) and tt(bar), use
 
 example(compdef _gnu_generic foo bar)
 
-in one of the initialization files after the call to tt(compinit).
+after the call to tt(compinit).
 
-The default installation uses this function only to generate
-completions for some GNU-commands because to complete the options, the 
-command has to be called and hence it shouldn't be used if one can't
-be sure that the command understands the `tt(-)tt(-help)' option.
+The completion system as supplied is conservative in its use of this
+function, since it is important to be sure the command understands the
+option `tt(-)'tt(-help)'.
 )
 findex(_guard)
 item(tt(_guard) [ var(options) ] var(pattern descr))(
-This function is intended to be used in an action of functions like
-tt(_arguments).  It returns immediately with a non-zero return value if
+This function is intended to be used in the var(action) for
+the specifications passed to tt(_arguments) and similar functions.  It
+returns immediately with a non-zero return value if
 the string to be completed does not match the var(pattern).  If the
-pattern matches, the var(descr) is displayed and the function returns
-zero if the word to complete is not empty and non-zero otherwise.
+pattern matches, the var(descr) is displayed; the function then returns
+zero if the word to complete is not empty, non-zero otherwise.
 
-The var(pattern) may be preceded by those options understood by
+The var(pattern) may be preceded by any of the options understood by
 tt(compadd) that are passed down from tt(_description), namely tt(-M),
 tt(-J), tt(-V), tt(-1), tt(-2), tt(-n), tt(-F) and tt(-X).  All of these
-options will be ignored.
+options will be ignored.  This fits in conveniently with the
+argument-passing conventions of actions for tt(_arguments).
 
 As an example, consider a command taking the options tt(-n) and
-tt(-none), where tt(-n) has to be followed by a numeric value in the
+tt(-none), where tt(-n) must be followed by a numeric value in the
 same word.  By using:
 
 example(_argument '-n-: :_guard "[0-9]#" "numeric value"' '-none')
 
 tt(_arguments) can be made to both display the message `tt(numeric
 value)' and complete options after `tt(-n<TAB>)'.  If the `tt(-n)' is
-already followed by one or more digits (matching the pattern given to
-tt(_guard)), only the message will be displayed and if the `tt(-n)' is
+already followed by one or more digits (the pattern passed to
+tt(_guard)) only the message will be displayed; if the `tt(-n)' is
 followed by another character, only options are completed.
 )
 findex(_message)
 xitem(tt(_message) [ tt(-r12) ] [ tt(-VJ) var(group) ] var(descr))
 item(tt(_message -e) [ var(tag) ] var(descr))(
-The var(descr) is used like the third
-argument to the tt(_description) function. However, the resulting
+The var(descr) is used in the same way as the third
+argument to the tt(_description) function, except that the resulting
 string will always be shown whether or not matches were
-generated. This is useful to display help texts in places where no
-completions can be generated automatically.
+generated.  This is useful for displaying a help message in places where
+no completions can be generated.
 
-This function also uses the tt(format) style for the tt(messages) tag in
-preference to the tt(format) style for the tt(descriptions) tag. The
-latter is used only if the former is unset.
+The tt(format) style is examined with the tt(messages) tag to find a
+message; the usual tag, tt(descriptions), is used only if the style is
+not set with the former.
 
-If the tt(-r) option is given, no style is used and the var(descr) is
-used literally as the string to display. This is only used in cases
-where that string is taken from some pre-processed argument list
-containing an expanded description.
+If the tt(-r) option is given, no style is used; the var(descr) is
+taken literally as the string to display.  This is most useful
+when the var(descr) comes from a pre-processed argument list
+which already contains an expanded description.
 
 The tt(-12VJ) options and the var(group) are passed to tt(compadd) and
 hence determine the group the message string is added to.
 
-In the second form, the var(descr) is added like a description added
-by tt(_description) under the given var(tag), but the var(descr) will
-always be shown even if no matches are added for the var(tag).  If the
-var(tag) is omitted, it is taken from the tt(curtag) parameter which
-is set by the functions dealing with tags so it should contain the
-right one in almost all cases.
+The second form gives a description for completions with the tag
+var(tag) to be shown even if there are no matches for that tag.  The tag
+can be omitted and if so the tag is taken from the parameter
+tt($curtag); this is maintained by the completion system and so is
+usually correct.
 )
 findex(_multi_parts)
 item(tt(_multi_parts) var(sep) var(array))(
-This function receives two arguments: a separator character and an
-array.  As usual, the var(array) may be either the
+The argument var(sep) is a separator character.
+The var(array) may be either the
 name of an array parameter or a literal array in the form
-`tt(LPAR()foo bar)tt(RPAR())' (i.e. a list of words separated by white 
-space in parentheses).  With these arguments, this function will
-complete to strings from the array where the parts separated by the
-separator character are completed independently.  For example, the
-tt(_tar) function from the distribution caches the pathnames from the
-tar file in an array, and then calls this function to complete these
-names in the way normal filenames are completed by the
-tt(_path_files) function, by using `tt(_multi_parts) tt(/)
-var(patharray)'.
-
-If the tt(-i) option is present, then any time there is a unique match it
-will immediately be inserted even if that requires additional separators to
-be inserted as well.  When completing from a fixed set of possible
-completions which are really words, this is often the expected behaviour;
-however, if tt(_multi_parts) should behave like completing pathnames, the
-tt(-i) option should not be used.
+`tt(LPAR()foo bar)tt(RPAR())', a parenthesised list of words separated
+by whitespace.  The possible completions are the
+strings from the array.  However, each chunk delimited by var(sep) will be
+completed separately.  For example, the tt(_tar) function uses
+`tt(_multi_parts) tt(/) var(patharray)' to complete partial file paths
+from the given array of complete file paths.
+
+The tt(-i) option causes tt(_multi_parts) to insert a unique match even
+that requires multiple separators to be inserted.  This is not usually
+the expected behaviour with filenames, but certain other types of
+completion, for example those with a fixed set of possibilities, may be
+more suited to this form.
 
 Like other utility functions, this function accepts the `tt(-V)',
 `tt(-J)', `tt(-1)', `tt(-2)', `tt(-n)', `tt(-f)', `tt(-X)', `tt(-M)',
@@ -3869,27 +3877,27 @@ them to the tt(compadd) builtin.
 )
 findex(_next_label)
 item(tt(_next_label) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(options) ... ])(
-This function should be called repeatedly to generate the tag
-labels. On each call it will check if another tag label is to be used 
-and, if there is at least one, zero is returned. If no more tag
-labels are to be used, a non-zero status is returned.
-
-The tt(-x12VJ) options and the first three arguments are given to the
-tt(_description) function using the tag label instead of the first
-argument as appropriate. The var(options) given after the var(descr)
-should be other options to be used for tt(compadd) or whatever
-function is to be called to add the matches. tt(_next_label) will store these 
-var(options) in the parameter whose var(name) is given as the second
-argument. This is done in such a way that the description given by the 
-user to the tt(tag-order) style is preferred over the one given to
+This function is used to implement the loop over different tag
+labels for a particular tag as describe above for the tt(tag-order)
+style.  On each call it checks to see if there are any more tag labels; if
+there is it returns status zero, otherwise non-zero.
+As this function requires a current tag to be set, it must always follow
+a call to tt(_tags) or tt(_requested).
+
+The tt(-x12VJ) options and the first three arguments are passed to the
+tt(_description) function.  Where appropriate the var(tag) will be
+replaced by a tag label in this call.  Any description given in
+the tt(tag-order) style is preferred to the var(descr) passed to
 tt(_next_label).
 
-Note that this function must not be called without a previous call to
-tt(_tags) or tt(_requested) because it uses the tag label
-for the current tag found by these functions.
+The var(options) given after the var(descr)
+are set in the parameter given by var(name), and hence are to be passed
+to tt(compadd) or whatever function is called to add the matches.
 
-A normal use of this function for the tag labels of the tag tt(foo)
-looks like this:
+Here is a typical use of this function for the tag tt(foo).  The call to
+tt(_requested) determines if tag tt(foo) is required at all; the loop
+over tt(_next_label) handles any labels defined for the tag in the
+tt(tag-order) style.
 
 example(local expl ret=1
 ...
@@ -3900,37 +3908,39 @@ if _requested foo; then
   done
   ...
 fi
-return ret
-)
+return ret)
 )
 findex(_normal)
 item(tt(_normal))(
-This function is used for normal command completion.  It has two tasks:
-completing the first word on the command line as the name of a command, and
-completing the arguments to this command.  In the second case, the name of
-the command is looked up to see if special completions exists, including
-completions defined for patterns which match the name.  If none is found,
-completion is performed for the context tt(-default-).
-
-The function can also be called by other completion functions which need to
-treat a range of words as a command line.  For example, the function to
-complete after the pre-command specifiers such as tt(nohup) removes the
+This is the standard function called to handled completion outside
+nay special var(-context-).  It is called both to complete the command
+word and also the arguments for a command.  In the second case,
+tt(_normal) looks for a special completion for that command, and if
+there is none it uses the completion for the tt(-default-) context.
+
+A second use is to rexamine the command line specified by the tt($words)
+array and the tt($CURRENT) parameter after those have been modified.
+For example, the function tt(_precommand), which
+completes after pre-command specifiers such as tt(nohup), removes the
 first word from the tt(words) array, decrements the tt(CURRENT) parameter,
-then calls tt(_normal) again, with the effect that `tt(nohup) var(cmd ...)'
-is treated the same way as `var(cmd ...)'.
+then calls tt(_normal) again.  The effect is that `tt(nohup) var(cmd ...)'
+is treated in the same way as `var(cmd ...)'.
 
-If the command name matches a pattern, the parameter tt(_compskip) is
-checked after the call to the corresponding completion function.  This has
-the same effect here as in the tt(-first-) context: if it is set, no more
-completion functions are called even if there are no matches so far.
+If the command name matches one of the patterns given by one of the
+options tt(-p) or tt(-P) to tt(compdef), the corresponding completion
+function is called and then the parameter tt(_compskip) is
+checked.  If it is set completion is terminated at that point even if
+no matches have been found.  This is the same effect as in the
+tt(-first-) context.
 )
 findex(_options)
 item(tt(_options))(
-This can be used to complete option names.  It uses a matching
-specification that ignores a leading `tt(no)', ignores underscores and 
-allows the user to type upper-case letters which will match their
-lower-case counterparts.  All arguments passed to this function are
-propagated unchanged to the tt(compadd) builtin.
+This can be used to complete the names of shell options.  It provides a
+matcher specification that ignores a leading `tt(no)', ignores
+underscores and allows upper-case letters to
+match their lower-case counterparts (for example, `tt(glob)',
+`tt(noglob)', `tt(NO_GLOB)' are all completed).  Any arguments
+are propagated to the tt(compadd) builtin.
 )
 findex(_options_set)
 findex(_options_unset)
@@ -3941,21 +3951,23 @@ matching specification used in the tt(_options) function.
 Note that you need to uncomment a few lines in the tt(_main_complete)
 function for these functions to work properly.  The lines in question
 are used to store the option settings in effect before the completion
-widget locally sets the options it needs.  Hence these options are not
+widget locally sets the options it needs.  Hence these functions are not
 generally used by the completion system.
 )
 findex(_parameters)
 item(tt(_parameters))(
-This should be used to complete parameter names.  tt(_parameters) can
-take a tt(-g var(pattern)) option which specifies that only parameters
-whose type matches the var(pattern) should be completed.  Strings of
-the same form as those returned by the tt(t) parameter expansion flag
-are used here when matching the type.  All other arguments are passed
-unchanged to the tt(compadd) builtin.
+This is used to complete the names of shell parameters.
+
+The option `tt(-g var(pattern))' limits the completion to parameters
+whose type matches the var(pattern).  The type of a parameter is that
+shown by `tt(print ${(t))var(param)tt(})', hence judicious use of
+`tt(*)' in var(pattern) is probably necessary.
+
+All other arguments are passed to the tt(compadd) builtin.
 )
 findex(_path_files)
 item(tt(_path_files))(
-The function tt(_path_files) is used throughout the completion system
+This function is used throughout the completion system
 to complete filenames.  It allows completion of partial paths.  For
 example, the string `tt(/u/i/s/sig)' may be completed to
 `tt(/usr/include/sys/signal.h)'.
@@ -3974,57 +3986,82 @@ Specifies that only files matching the var(pattern) should be completed.
 )
 item(tt(-W) var(paths))(
 Specifies path prefixes that are to be prepended to the string from the
-line to generate the filenames but that should not be inserted in the line
-or shown in a completion listing.  Here, var(paths) may be the name of an
-array parameter, a literal list of paths enclosed in parentheses or an
-absolute pathname.
-)
-item(tt(-F))(
-This option from the tt(compadd) builtin gives direct control over which
+command line to generate the filenames but that should not be inserted
+as completions nor shown in completion listings.  Here, var(paths) may be
+the name of an array parameter, a literal list of paths enclosed in
+parentheses or an absolute pathname.
+)
+item(tt(-F) var(ignored-files))(
+This behaves as for the corresponding option to the tt(compadd) builtin.
+It gives direct control over which
 filenames should be ignored.  If the option is not present, the
 tt(ignored-patterns) style is used.
 )
 enditem()
 
-These functions also accept the `tt(-J)', `tt(-V)', `tt(-1)',
-`tt(-2)', `tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)', `tt(-q)',
-`tt(-r)', and `tt(-R)' options from the tt(compadd) builtin.
+Both tt(_path_files) and tt(_files) also accept the following options
+which are passed to tt(compadd): `tt(-J)', `tt(-V)',
+`tt(-1)', `tt(-2)', `tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)',
+`tt(-q)', `tt(-r)', and `tt(-R)'.
 
 Finally, the tt(_path_files) function  uses the styles tt(expand),
-tt(ambiguous), tt(special-dirs), tt(list-suffixes) and tt(file-sort).
+tt(ambiguous), tt(special-dirs), tt(list-suffixes) and tt(file-sort)
+described above.
 )
 findex(_pick_variant)
-item(tt(_pick_variant [ tt(-c) var(command) ] [ tt(-r) var(name) ] var(command)tt(=)var(pattern) ... var(command) [ var(args) ... ]))(
-This function is used to resolve situations where a command has more
-than one variant, each requiring different handling or where there is a
-name clash between two different commands.
-
-_pick_variant does this by running the command and comparing its output
-against a series of patterns. The command to run is taken from the
-first element of the var(words) array unless specified with the tt(-c)
-option. Arguments to be passed on to it can be specified at the end
-after all the other arguments. The patterns are specified by the series
-of var(command)tt(=)var(pattern) arguments where var(command) is a
-label used to describe each command. If none of the patterns match, the
-final command label is taken and 1 is returned.
-
-The results are cached in the var(_cmd_variant) associative array so
-the calling function can either look up the result in there or it can
-pass the name of a parameter with the tt(-r) option which will be set
-to the result.
+item(tt(_pick_variant [ tt(-c) var(command) ] [ tt(-r) var(name) ] var(label)tt(=)var(pattern) ... var(label) [ var(args) ... ]))(
+This function is used to resolve situations where a single command name
+requires more than one type of handling, either because it
+has more than one variant because there is a name clash between two
+different commands.
+
+The command to run is taken from the first element of the array
+tt(words) unless this is overridden by the option tt(-c).  This command
+is run and its output is compared with a series of patterns.  Arguments
+to be passed to the command can be specified at the end after all the
+other arguments.  The patterns to try in order are given by the arguments
+var(label)tt(=)var(pattern); if the output of `var(command) var(args)
+tt(...)' contains var(pattern), then tt(label) is selected as the label
+for the command variant.  If none of the patterns match, the final
+command label is selected and status 1 is returned.
+
+If the `tt(-r) var(name)' is given, the var(label) picked is stored in
+the parameter named var(name).
+
+The results are also cached in the var(_cmd_variant) associative array
+indexed by the name of the command run.
 )
 findex(_regex_arguments)
-item(tt(_regex_arguments) var(name) var(specs) ...)(
-This function is a compiler to generate a completion function.  The
-first argument specifies the name of the generated function while the
-remaining arguments specify a completion as a set of regular
-expressions with actions.  The generated function has the structure of a
-finite-state machine whose states correspond to the state (i.e. the
-context) of the completion. This state machine uses a command line,
-which comes from the concatenation of the tt(words) array up to the
-current cursor position using null characters as separators with no extra
-quotation.  This is analysed and at the end the appropriate action is
-executed.
+item(tt(_regex_arguments) var(name) var(spec) ...)(
+This function generates a completion function var(name) which matches
+the specifications var(spec) tt(...), a set of regular expressions as
+described below.  After running tt(_regex_arguments), the function
+var(name) should be called at the appropriate point.
+The pattern to be matched is given by the contents of
+the tt(words) array up to the current cursor position joined together
+with null characters; no quotation is applied.
+
+The arguments are grouped as sets of alternatives separated by `tt(|)',
+which are tried one after the other until one matches.  Each alternative
+consists of a one or more specifications which are tried left to right,
+with each pattern matched being stripped in turn from the command line
+being tested, until all of the group succeeds or until one fails; in the
+latter case, the next alternative is tried.  This structure can be
+repeated to arbitrary depth by using parentheses; matching proceeds from
+inside to outside.
+
+COMMENT(I think I've got this wrong, but I can't think what else it
+could mean.  Actually, it still doesn't mean very much.)\
+A special procedure is applied if no test succeeds but the remaining
+command line string contains no null character (implying the remaining
+word is the one for which completions are to be generated).  The
+completion target is restricted to the remaining word and any
+var(action)s for the corresponding patterns are executed.  In this case,
+nothing is stripped from the command line string.  The order of
+evaluation of the var(action)s can be determined by the tt(tag-order)
+style; the various formats supported by tt(_alternative) can be used
+in var(action).  The var(descr) is used for setting up the array
+parameter tt(expl).
 
 Specification arguments take one of following forms, in which
 metacharacters such as `tt(LPAR())', `tt(RPAR())', `tt(#)' and `tt(|)'
@@ -4032,46 +4069,35 @@ should be quoted.
 
 startitem()
 item(tt(/)var(pattern)tt(/) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(tag)tt(:)var(descr)tt(:)var(action)])(
-This is a primitive element, corresponding to one
-state of the compiled state machine.  The state is entered if
-`tt((#b)LPAR()(#B))var(pattern)tt(RPAR()(#B))var(lookahead)tt(*)' matches
-the command line string.  If it matches, `var(guard)' is evaluated and
-its return status is examined; if this is successful, the state is entered,
-otherwise the test fails and other candidates are tried.  The var(pattern)
-string `tt([])' is guaranteed never to match.
-
-If the test succeeds and the state is entered, the left part of the
-command line string matched as var(pattern) is removed and the 
-next state is tried, proceeding from inside to outside and from left to
-right.
-
-If no test succeeds and the remaining command line string contains no null
-character, the completion target is restricted to the remainder of the
-command line string and var(action)s for the target are executed.
-In this case, nothing is actually removed from the command line string
-so that any previous or neighbouring state may also have var(actions)s.
-var(actions)s evaluation are ordered by the tt(tag-order) style and specified
-var(tag) by tt(_alternative).  So, the various formats supported by
-tt(_alternative) can be used in var(action).  var(descr) is used for
-setting up the array parameter tt(expl).
+This is a single privitive component.
+The function tests whether the combined pattern
+`tt((#b)LPAR()(#B))var(pattern)tt(RPAR())var(lookahead)tt(*)' matches
+the command line string.  If so, `var(guard)' is evaluated and
+its return status is examined to determine if the test has succeeded.
+The var(pattern) string `tt([])' is guaranteed never to match.
+The var(lookahead) is not stripped from the command line before the next
+pattern is examined.
 )
 item(tt(/)var(pattern)tt(/+) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(tag)tt(:)var(descr)tt(:)var(action)])(
 This is similar to `tt(/)var(pattern)tt(/) ...' but the left part of the
-command line string is also considered as part of the completion target.
+command line string (i.e. the part already matched by previous patterns)
+is also considered part of the completion target.
 )
 item(tt(/)var(pattern)tt(/-) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(tag)tt(:)var(descr)tt(:)var(action)])(
 This is similar to `tt(/)var(pattern)tt(/) ...' but the var(action)s of the
-current and previous states are ignored even if the following state's
-`var(pattern)' matches the empty string.
+current and previously matched patterns are ignored even if the
+following `var(pattern)' matches the empty string.
 )
 item(tt(LPAR()) var(spec) tt(RPAR()))(
-This groups var(spec)s.
+Parentheses may be used to groups var(spec)s; note each parenthesis
+is a single argument to tt(_regex_arguments).
 )
 item(var(spec) tt(#))(
 This allows any number of repetitions of var(spec).
 )
 item(var(spec) var(spec))(
-This represents the concatenation of two var(spec)s.
+The two var(spec)s are to be matched one after the other as described
+above.
 )
 item(var(spec) tt(|) var(spec))(
 Either of the two var(spec)s can be matched.
@@ -4081,10 +4107,10 @@ enditem()
 findex(_requested)
 item(tt(_requested) [ tt(-x) ] [ tt(-12VJ) ] var(tag) [ var(name) var(descr) [ var(command) var(args) ... ] ])(
 This function is called to decide whether a tag already registered by a
-call to tt(_tags) (see below) is requested and hence completion should be
-performed for it; it returns status zero if the tag is requested and
-non-zero otherwise.  This will usually be done in a loop such as the
-following:
+call to tt(_tags) (see below) has been requested by the user and hence
+completion should be performed for it.  It returns status zero if the
+tag is requested and non-zero otherwise.  The function is typically used
+as part of a loop over different tags as follows:
 
 example(_tags foo bar baz
 while _tags; do
@@ -4096,17 +4122,18 @@ while _tags; do
 done)
 
 Note that the test for whether matches were generated is not performed
-until the end of the tt(_tags) loop.  This is so that the user can specify
-a set of tags to be tested at the same time in the tt(tag-order)
-parameter.
+until the end of the tt(_tags) loop.  This is so that the user can set
+the tt(tag-order) style to specify a set of tags to be tested at the
+same time.
 
-If the var(name) and the var(descr) are given, tt(_requested) calls the
-tt(_description) function with these arguments, including the options.
+If var(name) and var(descr) are given, tt(_requested) calls the
+tt(_description) function with these arguments together with the options
+passed to tt(_requested).
 
-If the var(command) is given, the tt(_all_labels) function will be called
-immediately with the same arguments.  This is often useful to do both the
-testing of the tag, getting the description for the matches and adding the
-matches at once.  For example:
+If var(command) is given, the tt(_all_labels) function will be called
+immediately with the same arguments.  In simple cases this makes it
+possible to perform the test for the tag and the matching in one go.
+For example:
 
 example(local expl ret=1
 _tags foo bar baz
@@ -4117,14 +4144,14 @@ while _tags; do
   (( ret )) || break
 done)
 
-Note that this means that the var(command) has to accept the options
-that have to be passed down to tt(compadd).
+If the var(command) is not tt(compadd), it must nevertheless be prepared
+to handle the same options.
 )
 findex(_retrieve_cache)
 item(tt(_retrieve_cache) var(cache_identifier))(
 This function retrieves completion information from the file given by
 var(cache_identifier), stored in a directory specified by the
-tt(cache-path) style (defaults to tt(~/.zsh/cache)).  The return value
+tt(cache-path) style which defaults to tt(~/.zsh/cache).  The return value
 is zero if retrieval was successful.  It will only attempt retrieval
 if the tt(use-cache) style is set, so you can call this function
 without worrying about whether the user wanted to use the caching
@@ -4142,110 +4169,112 @@ a quoted list of words in parentheses.  For example, with the array
 complete the string  `tt(f)' to `tt(foo)' and the string `tt(b@n)' to
 `tt(bar@news)'.
 
-This function passes the `tt(-V)', `tt(-J)', `tt(-1)', `tt(-2)',
-`tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)', `tt(-r)', `tt(-R)',
-and `tt(-q)' options and their arguments to the tt(compadd) builtin
-used to add the matches.
+This function accepts the tt(compadd) options `tt(-V)', `tt(-J)',
+`tt(-1)', `tt(-2)', `tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)',
+`tt(-r)', `tt(-R)', and `tt(-q)' and passes them on to the tt(compadd)
+builtin used to add the matches.
 )
 findex(_setup)
 item(tt(_setup) var(tag) [ var(group) ])(
-This function expects a tag as its argument and sets up the special
-parameters used by the completion system appropriately for the tag,
-using styles such as tt(list-colors) and tt(last-prompt).
-
-The optional var(group) gives the name of the group in which the
-matches will be placed. If it is not given, the var(tag) is used as
+This function sets up the special
+parameters used by the completion system appropriately for the var(tag)
+given as the first argument.  It uses the styles tt(list-colors),
+tt(list-packed), tt(list-rows-first), tt(last-promp), tt(accept-exact),
+tt(menu) and tt(force-list).
+
+The optional var(group) supplies the name of the group in which the
+matches will be placed.  If it is not given, the var(tag) is used as
 the group name.
 
-Note that this function is called automatically from tt(_description)
-so that one normally doesn't have to call it explicitly.
+This function is called automatically from tt(_description)
+and hence is not normally called explicitly.
 )
 findex(_store_cache)
-item(tt(_store_cache) var(cache_identifier) var(vars) ...)(
-This function, when combined with tt(_retrieve_cache) and
-tt(_cache_invalid), makes it easy to implement a caching layer for
-your completion functions.  If a completion function needs to perform
-a costly operation in order to generate data which is used to
-calculate completions, you can store that data in variables, and use
-this function to dump the values of those variables to a file.  Then,
-if they are needed in subsequent shell invocations, they can be
-retrieved quickly from that file via tt(_retrieve_cache), avoiding the
-need for repeating the costly operation.
+item(tt(_store_cache) var(cache_identifier) var(params) ...)(
+This function, together with tt(_retrieve_cache) and
+tt(_cache_invalid), implements a caching layer which can be used
+in any completion functions.  Data obtained by
+costly operations are stored in parameters;
+this function then dumps the values of those parameters to a file.  The
+data can then be retrieved quickly from that file via tt(_retrieve_cache),
+even in different instances of the shell.
 
 The var(cache_identifier) specifies the file which the data should be
-dumped to, and is stored in a directory specified by the
-tt(cache-path) style (defaults to tt(~/.zsh/cache)).  The remaining
-var(vars) arguments are the variables to dump to the file.
+dumped to.  The file is stored in a directory specified by the
+tt(cache-path) style which defaults to tt(~/.zsh/cache).  The remaining
+var(params) arguments are the parameters to dump to the file.
 
 The return value is zero if storage was successful.  The function will
 only attempt storage if the tt(use-cache) style is set, so you can
 call this function without worrying about whether the user wanted to
 use the caching layer.
 
-If your completion function avoids calling _retrieve_cache when it
-already has the completion data in the environment, it should probably
-at least call tt(_cache_invalid) to check whether this data and the
-data cached on disk is still valid.
+The completion function may avoid calling tt(_retrieve_cache) when it
+already has the completion data available as parameters. 
+However, in that case it should
+call tt(_cache_invalid) to check whether the data in the parameters and
+in the cache are still valid.
 
 See the _perl_modules completion function for a simple example of
-usage of this caching layer.
+the usage of the caching layer.
 )
 findex(_tags)
-item(tt(_tags) [ tt(-C) var(name) [ var(tags) ... ] ])(
-If called with arguments, these are taken as the names of the tags for 
-the types of matches the calling completion function can generate in
-the current context.  These tags are stored internally and sorted by
-using the tt(tag-order) style.  Following calls to this function
-without arguments from the same function will then select the first,
-second, etc. set of tags requested by the user.  To test if a certain
-tag should be tried, the tt(_requested) function has to be called (see 
-above).
-
-The return value is zero if at least one of the tags is requested and
-non-zero otherwise. 
-
-This function also accepts the tt(-C) option followed by a
-var(name). This name is temporarily (i.e. not visible outside
-tt(_tags)) stored in the argument field of the context name in the
-tt(curcontext) parameter. This allows tt(_tags) to be made to use a more
-specific context name without having to change and reset the
-tt(curcontext) parameter (which would otherwise have the same effect).
+item(tt(_tags) [ [ tt(-C) var(name) ] var(tags) ... ])(
+If called with arguments, these are taken to be the names of tags
+valid for completions in the current context.  These tags are stored
+internally and sorted by using the tt(tag-order) style.
+
+Next, tt(_tags) is called repeatedly without arguments from the same
+comletion function.  This successively selects the first, second,
+etc. set of tags requested by the user.  The return value is zero if at
+least one of the tags is requested and non-zero otherwise.  To test if a
+particular tag is to be tried, the tt(_requested) function should be
+called (see above).
+
+If `tt(-C) var(name)' is given, var(name) is temporarily stored in the
+argument field (the fifth) of the context in the tt(curcontext) parameter
+during the call to tt(_tags); the field is restored on exit.  This
+allows tt(_tags) to use a more 
+specific context without having to change and reset the
+tt(curcontext) parameter (which has the same effect).
 )
 findex(_values)
-item(tt(_values) var(specs) ...)(
-This is used to complete values (strings) and their arguments or
-lists of such values.  It can be used in two ways.
-
-If the first argument is the option `tt(-O) var(name)', this will be used
-in the same way as by the tt(_arguments) function, in other words the
-elements of the var(name) array will be given to calls to tt(compadd)
-and when executing an action.
-
-Otherwise, if the first argument (or the first argument after the
-`tt(-O) var(name)' option if that is used) is the option `tt(-s)', the
-next argument is used as the character that separates multiple values.
-Thus the values completed appear in the same word on the command line,
-unlike completion using tt(_arguments).
+item(tt(_values) [ -O var(name) ] [ -s var(sep) ] [ -S var(sep) ] [ -C ] var(desc) var(spec) ...)(
+This is used to complete arbitrary keywords (values) and their arguments,
+or lists of such combinations.
+
+If the first argument is the option `tt(-O) var(name)', it will be used
+in the same way as by the tt(_arguments) function.  In other words, the
+elements of the var(name) array will be passed to tt(compadd)
+when executing an action.
+
+If the first argument (or the first argument after `tt(-O) var(name)')
+is `tt(-s)', the next argument is used as the character that separates
+multiple values.  This character is automatically added after each value
+in an auto-removable fashion (see below); all values completed by
+`tt(_values -s)' appear in the same word on the command line, unlike
+completion using tt(_arguments).  If this option is not present, only a
+single value will be completed per word.
 
 Normally, tt(_values) will only use the current word to determine
-which values are already present on the command line.  If the tt(-w)
-option is given, the other arguments are used, too.
+which values are already present on the command line and hence are not
+to be completed again.  If the tt(-w) option is given, other arguments
+are examined as well.
 
-The first argument (after the options and separator character if they
-are given) is used as a string to print as a description before
-listing the values.
+The first non-option argument is used as a string to print as a
+description before listing the values.
 
 All other arguments describe the possible values and their
 arguments in the same format used for the description of options by
 the tt(_arguments) function (see above).  The only differences are that
-no minus or plus sign is required at the beginning, that
-values can have only one argument and that those forms of actions
+no minus or plus sign is required at the beginning,
+values can have only one argument, and the forms of action
 beginning with an equal sign are not supported.
 
 The character separating a value from its argument can be set using the
 option tt(-S) (like tt(-s), followed by the character to use as the
-separator in the next argument).  If this option is not used, the equal
-sign will be used as the separator.
+separator in the next argument).  By default the equal
+sign will be used to separator values and arguments.
 
 Example:
 
@@ -4258,31 +4287,29 @@ This describes three possible values: `tt(foo)', `tt(one)', and
 `tt(two)'.  The first is described as `tt(bar)', takes no argument 
 and may appear more than once.  The second is described as
 `tt(number)', may appear more than once, and takes one mandatory
-argument described as `tt(first count)' for which no action is
-specified so that it will not be completed automatically.  The
+argument described as `tt(first count)'; no action is
+specified, so it will not be completed.  The
 `tt((two))' at the beginning says that if the value `tt(one)' is on
-the line, the value `tt(two)' will not be considered to be a possible
-completion anymore.  Finally, the last value (`tt(two)') is described
+the line, the value `tt(two)' will no longer be considered a possible
+completion.  Finally, the last value (`tt(two)') is described
 as `tt(another number)' and takes an optional argument described as
-`tt(second count)' which will be completed from the strings `tt(1)',
-`tt(2)', and `tt(3)'. The tt(_values) function will complete lists of
-these values separated by commas.
-
-Like tt(_arguments) this function temporarily adds another context
-name component to the current context name while executing the
-var(action).  Here this name is just the name of the value for which
-the argument is completed.
-
-To decide if the descriptions for the values (not those for the
-arguments) should be printed, the style tt(verbose) is used.
-
-One last difference from tt(_arguments) is that this function uses the
-associative array
-tt(val_args) to report values and their arguments, although otherwise this
-is the same as the tt(opt_args) association used by
-tt(_arguments).  This also means that the function calling tt(_values) 
-should declare the tt(state), tt(line), tt(context) and tt(val_args)
-parameters as in:
+`tt(second count)' for which the completions (to appear after an
+`tt(=)') are `tt(1)', `tt(2)', and `tt(3)'.  The tt(_values) function
+will complete lists of these values separated by commas.
+
+Like tt(_arguments), this function temporarily adds another context name
+component to the arguments element (the fifth) of the current context
+while executing the var(action).  Here this name is just the name of the
+value for which the argument is completed.
+
+The style tt(verbose) is used to decide if the descriptions for the
+values (but not those for the arguments) should be printed.
+
+The associative array tt(val_args) is used to report values and their
+arguments; this works similarly to the tt(opt_args) associative array
+used by tt(_arguments).  Hence the function calling tt(_values) should
+declare the local parameters tt(state), tt(line), tt(context) and
+tt(val_args):
 
 example(local context state line
 typeset -A val_args)
@@ -4292,45 +4319,43 @@ function the tt(context) parameter will be set to the name of the
 value whose argument is to be completed.
 
 Note also that tt(_values) normally adds the character used as the
-separator between values as an auto-removable suffix so that users don't
-have to type it themselves.  But when using a `tt(->)var(string)' action
-tt(_values) can't do that because the matches for the argument will be
+separator between values as an auto-removable suffix (similar to a
+`tt(/)' after a directory).  However, this is not possible for a
+`tt(->)var(string)' action as the matches for the argument are
 generated by the calling function.  To get the usual behaviour, the
-implementor of the calling function has to add the suffix directly by
-passing the options `tt(-qS) var(x)' (where var(x) is the separator
-character specified with the tt(-s) option of tt(_values)) to the
-function generating the matches or to the tt(compadd) builtin.
+the calling function can add the separator var(x) as a suffix by
+passing the options `tt(-qS) var(x)' either directly or indirectly to
+tt(compadd).
 
-Like tt(_arguments), tt(_values) supports the tt(-C) option in
-which case you have to make the parameter tt(curcontext) local instead 
+The option tt(-C) is treated in the same way as it is by tt(_arguments).
+In that case the parameter tt(curcontext) should be made local instead 
 of tt(context) (as described above).
 )
 findex(_wanted)
 item(tt(_wanted) [ tt(-x) ] [ tt(-C) var(name) ]  [ tt(-12VJ) ] var(tag) var(name) var(descr) var(command) var(args) ...)(
-In many contexts, completion will generate one particular set of
-matches (usually corresponding to a single tag); however, it is
+In many contexts, completion can only generate one particular set of
+matches, usually corresponding to a single tag.  However, it is
 still necessary to decide whether the user requires matches of this type.
 This function is useful in such a case.
 
-Like tt(_requested), it should be passed arguments as for tt(_description).
-It calls tt(_tags) with the given var(tag) and if that returns zero 
-(so that the var(tag) is requested by the user) it calls
-tt(_description).  Hence to offer only one tag and immediately
-use the description generated:
+The arguments to tt(_wanted) are the same as those to tt(_requested),
+i.e. arguments to be passed to tt(_description).  However, in this case
+the var(command) is not optional;  all the processing of tags, including
+the loop over both tags and tags labels and the generation of matches,
+is carried out automatically by tt(_wanted).  This also means that
+tt(_wanted) should not be called inside a tt(_tags) loop.
+
+Hence to offer only one tag and immediately add the corresponding
+matches with the given description:
 
 example(_wanted tag expl 'description' \ 
     compadd matches...)
 
-Unlike tt(_requested), however, tt(_wanted) cannot be called without
-the var(command).  This is because tt(_wanted) also implements the loop
-over the tags, not just the one for the labels; conversely, it should not
-be called in the middle of a tt(_tags) loop.
-
-Note that, as for tt(_requested), the var(command) has to accept the options
-that have to be passed down to tt(compadd).
+Note that, as for tt(_requested), the var(command) must be able to
+accept options to be passed down to tt(compadd).
 
 Like tt(_tags) this function supports the tt(-C) option to give a
-different name for the argument context field. The tt(-x) option has
+different name for the argument context field.  The tt(-x) option has
 the same meaning as for tt(_description).
 )
 enditem()
@@ -4365,9 +4390,12 @@ some attempt is made to decide which version of a command is present.  For
 example, completion for the tt(mount) command tries to determine the system
 it is running on, while completion for many other utilities try to decide
 whether the GNU version of the command is in use, and hence whether the
-tt(--help) option is supported..
+tt(--help) option is supported.
 )
 item(tt(X), tt(AIX), tt(BSD), ...)(
 Completion and utility function for commands available only on some systems.
+These are not arranged hierarchically, so, for example, both the
+tt(Linux) and tt(Debian) directories, as well as the tt(X) directory,
+may be useful on your system.
 )
 enditem()