PATCH: Alphabetize itemized lists in compsys.yo

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxxxxxxxxx>]

This patch doesn't make any wording changes (except to delete a stray
`/usr/' that crept in to the middle of some unrelated text somehow) but
it significantly rearranges the lists of completers, context names within
the _complete description, and bindable commands.  Consequently I did
change `above' to `below' and vice-versa in a few places (I may not have
got them all).

Index: Doc/Zsh/compsys.yo
===================================================================
@@ -2014,6 +2014,49 @@
 
 cindex(completion system, completers)
 startitem()
+findex(_approximate)
+item(tt(_approximate))(
+This completer function uses the tt(_complete) completer to generate
+a list of strings for the context the cursor is currently in, allowing 
+you to specify a maximum number of errors:  see the description of
+approximate matching in
+ifzman(\
+zmanref(zshexpn)
+)\
+ifnzman(\
+noderef(Filename Generation)
+)\
+for how errors are counted.  The resulting list of corrected and completed
+strings is then presented to the user.  The intended use of this completer
+function is to try after the normal tt(_complete) completer by setting:
+
+example(zstyle ':completion:*' completer _complete _approximate)
+
+This will give correcting completion if and only if
+normal completion yields no possible completions.  When
+corrected completions are found, the completer will normally start
+menu completion allowing you to cycle through these strings.
+
+This completer uses the tags tt(corrections) and tt(original) when
+generating the possible corrections and the original string.  The
+tt(format) style for the former may contain the additional sequences
+`tt(%e)' and `tt(%o)' which will be replaced by the number of errors
+accepted to generate the corrections and the original string,
+respectively.
+
+As with all completers, tt(_approximate) uses its name without the
+underscore in the var(completer) field of the context name.  Once it
+has started trying to generate matches, it will append a minus sign
+and the number of errors accepted to its name.  tt(_approximate) will
+first look for completions with one error, then two, and on so up to the
+limit on the number of errors set by the tt(max-errors) style.
+Hence on the first try the completer field of the context contains
+`tt(approximate-1)', on the second try `tt(approximate-2)', and so on.
+
+When tt(_approximate) is called from another function, the number of errors
+to accept may be given with the tt(-a) option.  Its argument should be
+the same as the value of the tt(max-errors) style, all in one string.
+)
 findex(_complete)
 item(tt(_complete))(
 This completer generates all possible completions in a context-sensitive
@@ -2028,48 +2071,31 @@
 handled specially.  These are:
 
 startitem()
-kindex(-equal-, completion context)
-item(tt(-equal-))(
-for completion of words beginning with an equal sign
-)
-kindex(-tilde-, completion context)
-item(tt(-tilde-))(
-for completion after a tilde (`tt(~)') character, but before a slash.
-)
-kindex(-redirect-, completion context)
-item(tt(-redirect-))(
-for completion after a redirection operator.
-)
-kindex(-math-, completion context)
-item(tt(-math-))(
-for completion inside mathematical contexts, such as
-`tt(LPAR()LPAR())...tt(RPAR()RPAR())'.
-)
-kindex(-subscript-, completion context)
-item(tt(-subscript-))(
-for completion inside subscripts.
-)
-kindex(-value-, completion context)
-item(tt(-value-))(
-for completion on the right hand side of an assignment.
-)
 kindex(-array-value-, completion context)
 item(tt(-array-value-))(
 for completion on the right hand side of an array-assignment
 (`tt(foo=LPAR()...RPAR())').
 )
+kindex(-brace-parameter-, completion context)
+item(tt(-brace-parameter-))(
+for completing the name of a parameter expansion within braces
+(`tt(${...})').
+)
+kindex(-command-, completion context)
+item(tt(-command-))(
+for completing in a command position.
+)
 kindex(-condition-, completion context)
 item(tt(-condition-))(
 for completion inside conditions (`tt([[...]])').
 )
-kindex(-parameter-, completion context)
-item(tt(-parameter-))(
-for completing the name of a parameter expansion (`tt($...)').
+kindex(-default-, completion context)
+item(tt(-default-))(
+for generating completions when no special completion function is used.
 )
-kindex(-brace-parameter-, completion context)
-item(tt(-brace-parameter-))(
-for completing the name of a parameter expansion within braces
-(`tt(${...})').
+kindex(-equal-, completion context)
+item(tt(-equal-))(
+for completion of words beginning with an equal sign
 )
 kindex(-first-, completion context)
 item(tt(-first-))(
@@ -2082,13 +2108,30 @@
 the function for the `tt(-default-)' context will not be called, but
 functions defined for commands will.
 )
-kindex(-default-, completion context)
-item(tt(-default-))(
-for generating completions when no special completion function is used.
+kindex(-math-, completion context)
+item(tt(-math-))(
+for completion inside mathematical contexts, such as
+`tt(LPAR()LPAR())...tt(RPAR()RPAR())'.
 )
-kindex(-command-, completion context)
-item(tt(-command-))(
-for completing in a command position.
+kindex(-parameter-, completion context)
+item(tt(-parameter-))(
+for completing the name of a parameter expansion (`tt($...)').
+)
+kindex(-redirect-, completion context)
+item(tt(-redirect-))(
+for completion after a redirection operator.
+)
+kindex(-subscript-, completion context)
+item(tt(-subscript-))(
+for completion inside subscripts.
+)
+kindex(-tilde-, completion context)
+item(tt(-tilde-))(
+for completion after a tilde (`tt(~)') character, but before a slash.
+)
+kindex(-value-, completion context)
+item(tt(-value-))(
+for completion on the right hand side of an assignment.
 )
 enditem()
 
@@ -2106,49 +2149,6 @@
 not used by the completion system itself, but has a function handling
 completion for it.
 )
-findex(_approximate)
-item(tt(_approximate))(
-This completer function uses the tt(_complete) completer to generate
-a list of strings for the context the cursor is currently in, allowing 
-you to specify a maximum number of errors:  see the description of
-approximate matching in
-ifzman(\
-zmanref(zshexpn)
-)\
-ifnzman(\
-noderef(Filename Generation)
-)\
-for how errors are counted.  The resulting list of corrected and completed
-strings is then presented to the user.  The intended use of this completer
-function is to try after the normal tt(_complete) completer by setting:
-
-example(zstyle ':completion:*' completer _complete _approximate)
-
-This will give correcting completion if and only if
-normal completion yields no possible completions.  When
-corrected completions are found, the completer will normally start
-menu completion allowing you to cycle through these strings.
-
-This completer uses the tags tt(corrections) and tt(original) when
-generating the possible corrections and the original string.  The
-tt(format) style for the former may contain the additional sequences
-`tt(%e)' and `tt(%o)' which will be replaced by the number of errors
-accepted to generate the corrections and the original string,
-respectively.
-
-As with all completers, tt(_approximate) uses its name without the
-underscore in the var(completer) field of the context name.  Once it
-has started trying to generate matches, it will append a minus sign
-and the number of errors accepted to its name.  tt(_approximate) will
-first look for completions with one error, then two, and on so up to the
-limit on the number of errors set by the tt(max-errors) style.
-Hence on the first try the completer field of the context contains
-`tt(approximate-1)', on the second try `tt(approximate-2)', and so on.
-
-When tt(_approximate) is called from another function, the number of errors
-to accept may be given with the tt(-a) option.  Its argument should be
-the same as the value of the tt(max-errors) style, all in one string.
-)
 findex(_correct)
 item(tt(_correct))(
 Generate corrections, but not completions, for the current word; this is
@@ -2180,30 +2180,6 @@
 tt(_approximate) will at least generate the corrected strings
 generated by the tt(_correct) completer -- and probably more.
 )
-findex(_match)
-item(tt(_match))(
-This completer is intended to be used after the tt(_complete)
-completer. It allows one to give patterns on the command line and
-to complete all strings matching these patterns from the set of
-possible completions for the context the cursor is in, without having
-to set the tt(GLOB_COMPLETE) option.
-
-Normally this will be done by taking the pattern from the line,
-inserting a `tt(*)' at the cursor position and comparing the resulting
-pattern with the possible completions generated.  However, if the
-tt(match-original) style has a value of tt(only), no `tt(*)' will be
-inserted.  If tt(match-original) has any other non-empty string as its
-value, this completer will first try to generate matches without, then
-with a `tt(*)' inserted at the cursor position.
-
-The generated matches will be offered in a menu completion unless the
-tt(insert-unambiguous) style is set to `true'.  In
-this case menu completion will only be started if no unambiguous string
-could be generated that is at least as long as the original string.
-
-Note that the matcher specifications defined globally or used by the
-completion functions will not be used.
-)
 findex(_expand)
 item(tt(_expand))(
 This completer function does not really do completion, but instead
@@ -2247,9 +2223,28 @@
 Complete words from the shell's command  history.  This completer 
 uses the tt(remove-all-dups), and tt(sort) styles also used by the
 tt(_history_complete_word) bindable command, see
+ifzman(the section `Bindable Commands' below)\
+ifnzman(noderef(Bindable Commands))
+and
 ifzman(the section `Completion System Configuration' above)\
 ifnzman(noderef(Completion System Configuration)).
 )
+findex(_ignored)
+item(tt(_ignored))(
+The tt(ignored-patterns) style can be set to a list of patterns which are
+compared against possible completions; matching ones are removed.
+With this completer those matches can be reinstated, as
+if no tt(ignored-patterns) style were set.  The completer actually
+generates its own list of matches; which completers are used
+for this is determined in the same way as for the tt(_prefix)
+completer.
+
+The tt(single-ignored) style is used if only one
+match could be generated.  It can be set to tt(show) to prevent that match 
+from being displayed or inserted into the line, or it can be set to
+tt(menu), in which case the single match and the original string from the
+line will be offered in a menu completion.
+)
 findex(_list)
 item(tt(_list))(
 This completer allows one to delay the insertion of matches until
@@ -2259,6 +2254,40 @@
 ifzman(the section `Completion System Configuration' above)\
 ifnzman(noderef(Completion System Configuration)).
 )
+findex(_match)
+item(tt(_match))(
+This completer is intended to be used after the tt(_complete)
+completer. It allows one to give patterns on the command line and
+to complete all strings matching these patterns from the set of
+possible completions for the context the cursor is in, without having
+to set the tt(GLOB_COMPLETE) option.
+
+Normally this will be done by taking the pattern from the line,
+inserting a `tt(*)' at the cursor position and comparing the resulting
+pattern with the possible completions generated.  However, if the
+tt(match-original) style has a value of tt(only), no `tt(*)' will be
+inserted.  If tt(match-original) has any other non-empty string as its
+value, this completer will first try to generate matches without, then
+with a `tt(*)' inserted at the cursor position.
+
+The generated matches will be offered in a menu completion unless the
+tt(insert-unambiguous) style is set to `true'.  In
+this case menu completion will only be started if no unambiguous string
+could be generated that is at least as long as the original string.
+
+Note that the matcher specifications defined globally or used by the
+completion functions will not be used.
+)
+findex(_menu)
+item(tt(_menu))(
+This completer is a simple example function implemented to show how
+menu completion can be done in shell code.  It should be used as the
+first completer and has the effect of making the code perform
+menu completion.  Note that this is independent of the setting of the
+tt(MENU_COMPLETE) option and does not work with the other
+menu completion widgets such as tt(reverse-menu-complete), or
+tt(accept-and-menu-complete).
+)
 findex(_oldlist)
 item(tt(_oldlist))(
 This completer controls how the standard completion widgets behave
@@ -2311,34 +2340,8 @@
 be moved to the end of the current word before the completion code is
 called and hence there will be no suffix.
 )
-findex(_ignored)
-item(tt(_ignored))(
-The tt(ignored-patterns) style can be set to a list of patterns which are
-compared against possible completions; matching ones are removed.
-With this completer those matches can be reinstated, as
-if no tt(ignored-patterns) style were set.  The completer actually
-generates its own list of matches; which completers are used
-for this is determined in the same way as for the tt(_prefix)
-completer.
+enditem()
 
-The tt(single-ignored) style is used if only one
-match could be generated.  It can be set to tt(show) to prevent that match 
-from being displayed or inserted into the line, or it can be set to
-tt(menu), in which case the single match and the original string from the
-line will be offered in a menu completion.
-)
-findex(_menu)
-item(tt(_menu))(
-This completer is a simple example function implemented to show how
-menu completion can be done in shell code.  It should be used as the
-first completer and has the effect of making the code perform
-menu completion.  Note that this is independent of the setting of the
-tt(MENU_COMPLETE) option and does not work with the other
-menu completion widgets such as tt(reverse-menu-complete), or
-tt(accept/usr/-and-menu-complete).
-)
-enditem()
-
 texinode(Bindable Commands)(Completion Functions)(Control Functions)(Completion System)
 sect(Bindable Commands)
 cindex(completion system, bindable commands)
@@ -2480,186 +2483,19 @@
 put themselves into the arrays again.
 
 startitem()
-findex(_funcall)
-item(tt(_funcall) var(return) var(name) [ var(args) ... ])(
-If a function var(name) exists, it is called with the arguments
-var(args). Unless it is the empty string or a single hyphen,
-var(return) is taken as the name of a parameter and the return status
-from the called function is stored in it.
-The return value of tt(_funcall) itself is zero if the function
-var(name) exists and was called and non-zero otherwise.
-)
-findex(_compalso)
-item(tt(_compalso) var(names) ...)(
-This function looks up the definitions for the context and command
-names given as arguments and calls the handler functions for them if
-there is a definition (given with the tt(compdef) function). For
-example, the function completing inside subscripts might use
-`tt(_compalso -math-)' to include the completions generated for
-mathematical environments.
-)
-findex(_call)
-item(tt(_call) var(tag) var(string) ...)(
-This function is used in places where a command is called and the user 
-should have the possibility to override the default for calling this
-command. It looks up the tt(command) style with the supplied
-var(tag). If the style is set, its value is used as the command to
-execute.
-
-In any case, the var(strings) from the call to tt(_call) or from the
-style are concatenated with spaces between them and the resulting
-string is evaluated. The return value is the return value of the
-command called.
-)
-findex(_normal)
-item(tt(_normal))(
-This function is used for normal command completion.  If
-completion is attempted on the first word, command names are
-completed. Otherwise, the arguments are completed by calling the
-functions defined for this command, including those functions defined
-for patterns matching the command name. This function can also be
-called by other completion functions if they have to complete a range
-of words as a separate command. For example, the function to complete after
-the pre-command specifiers such as tt(nohup) removes the first word from
-the tt(words) array, decrements the tt(CURRENT) parameter, then calls this
-function.
-
-When calling a function defined for a pattern, this function also
-checks if the parameter tt(_compskip) is set and uses the value in the 
-same way it is used after calling the completion function for the
-tt(-first-) context. With this 
-one can write a pattern completion function that keeps other functions 
-from being tried simply by setting this parameter to any value.
-)
-findex(_description)
-item(tt(_description) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])(
-This function tests some styles for the var(tag) and and stores
-options usable for tt(compadd) in the array with the given var(name)
-which guarantee that the matches are generated as requested by the
-user. The styles tested are: tt(format) (which is first tested for the
-given 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.
-
-The format string from the style (if any) will be modified so that the 
-sequence `tt(%d)' is replaced by the var(descr) given as the third
-argument. If tt(_description) is called with more than three
-arguments, these 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).
-
-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 a 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)'. 
-
-In most cases, this function will be used like this:
-
-example(local expl
-_description files expl file
-compadd "$expl[@]" - "$files[@]")
-)
-findex(_message)
-item(tt(_message) [ -r ] var(descr))(
-The var(descr) is used like the third
-argument to the tt(_description) function. However, 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.
-
-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.
-
-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.
-)
-findex(_setup)
-item(tt(_setup) var(tag))(
-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).
-
-Note that this function is called automatically from tt(_description)
-so that one normally doesn't have to call it explicitly.
-)
-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 
-below).
-
-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 to make tt(_tags) use a more
-specific context name without having to change and reset the
-tt(curcontext) parameter (which would otherwise have the same effect).
-)
-findex(_next_label)
-item(tt(_next_label) [ 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(-12JV) 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
-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.
-
-A normal use of this function for the tag labels of the tag tt(foo)
-looks like this:
-
-example(local expl ret=1
-...
-if _requested foo; then
-  ...
-  while _next_label foo expl '...'; do
-    compadd "$expl[@]" ... && ret=0
-  done
-  ...
-fi
-return ret
-)
-)
 findex(_all_labels)
 item(tt(_all_labels) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(command) var(args) ... ])(
-This is a convenient interface to the tt(_next_label) function, implementing
-the loop shown in the example above. The var(command) is the one that
-should be called to generate the matches. The options stored in the
-parameter var(name) will automatically be inserted into the var(args)
-given to the var(command). Normally, they are put directly after the
-var(command), but if one of the var(args) is a single hyphen, they are 
-inserted directly before that. If the hyphen is the last argument,
-that will be removed from the argument list before the var(command) is 
-called. This allows to use tt(_all_labels) in almost all cases where the
-matches can be generated by a single call to the tt(compadd) builtin
-command or by a call to one of the utility functions.
+This is a convenient interface to the tt(_next_label) function below,
+implementing the loop shown in the tt(_next_label) example.  The
+var(command) is the one that should be called to generate the matches. The
+options stored in the parameter var(name) will automatically be inserted
+into the var(args) given to the var(command).  Normally, they are put
+directly after the var(command), but if one of the var(args) is a single
+hyphen, they are inserted directly before that. If the hyphen is the last
+argument, that will be removed from the argument list before the
+var(command) is called. This allows to use tt(_all_labels) in almost all
+cases where the matches can be generated by a single call to the
+tt(compadd) builtin command or by a call to one of the utility functions.
 
 For example:
 
@@ -2674,72 +2510,11 @@
 tt(compadd) with additional options which will take precedence over
 those generated by tt(_all_labels).
 )
-findex(_requested)
-item(tt(_requested) [ tt(-12VJ) ] var(tag) [ var(name) var(descr) [ var(command) var(args) ... ] ])(
-A function that uses tt(_tags) to register tags and then calls it to
-loop over the requested sets of tags should call this function to
-check if a certain tag is currently requested. This normally has to be 
-done in a loop such as:
-
-example(_tags foo bar baz
-while _tags; do
-  if _requested foo; then
-    ...
-  fi
-  ... # test other tags
-  ... # exit loop if matches were generated
-done)
-
-So, the first argument for tt(_requested) is used as the name of a tag 
-and if that tag is currently requested, the return value is zero (and
-non-zero otherwise).
-
-If the var(name) and the var(descr) are given, tt(_requested) calls the
-tt(_description) function with these arguments, including the options.
-
-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. E.g.:
-
-example(local expl ret=1
-_tags foo bar baz
-while _tags; do
-  _requested foo expl 'description' \ 
-      compadd foobar foobaz && ret=0
-  ...
-  (( ret )) || break
-done)
-)
-findex(_wanted)
-item(tt(_wanted) [ tt(-C) var(name) ]  [ tt(-12VJ) ] var(tag) var(name) var(descr) var(command) var(args) ...)(
-In many contexts only one type of matches can be generated but even
-then it should be tested if the tag representing those matches is
-requested by the user. This function makes that easier.
-
-Like tt(_requested) it gets arguments as for tt(_description).
-With the var(tag) it calls tt(_tags) and if that returns zero 
-(i.e. the var(tag) is requested by the user) it calls tt(_description). So, 
-if you want to offer only one tag and immediatly want to use the
-description built, you can just do:
-
-example(_wanted tag expl 'description' \ 
-    compadd matches...)
-
-Unlike tt(_requested), however, tt(_wanted) can not be called without
-the var(command). That's because tt(_wanted) also implements the loop
-over the tags, not only the one for the labels.
-
-Like tt(_tags) this function supports the tt(-C) option to give a
-different name for the argument context field.
-)
 findex(_alternative)
 item(tt(_alternative) [ tt(-C) var(name) ] var(specs) ...)(
 This function is useful if you offer multiple tags and building the
 matches for them is easy enough. It basically implements a loop like
-the one described for the tt(_tags) function above.
+the one described for the tt(_tags) function below.
 
 The tags to use and what to do if the tags are requested are described 
 using the var(specs) which are of the form:
@@ -2767,154 +2542,14 @@
 Like tt(_tags) this function supports the tt(-C) option to give a
 different name for the argument context field.
 )
-findex(_describe)
-item(tt(_describe) [ tt(-o) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)(
-This function can be used to add options or values with descriptions
-as matches. The var(descr) is taken as a string to display above
-the matches if the tt(format) style for the tt(descriptions) tag is set.
-
-After this one or two names of arrays followed by options to give
-to tt(compadd) must be given. The first array contains the possible
-completions with their descriptions (with the description separated
-by a colon from the completion string). If the second array is given,
-it should have the same number of elements as the first one and these
-elements are added as possible completions instead of the strings from 
-the first array. In any case, however, the completion list will contain
-the strings from the first array.
+findex(_arguments)
+item(tt(_arguments) var(specs) ...)(
+This function can be used to complete words on the line by simply
+describing the arguments the command on the line gets. The description 
+is given as arguments to this function, with each var(spec) describing
+one option or normal argument of the command. The descriptions
+understood are:
 
-Any number of array/option sequences may be given separated by
-`tt(-)tt(-)'. This allows one to display matches together that need
-to be added with different options for tt(compadd).
-
-Before the first argument, the option `tt(-o)' may be given. It says
-that the matches added are option names. This will make tt(_describe)
-use the tt(prefix-hidden), tt(prefix-needed) and tt(verbose) styles
-to find out if the strings should be added at all and if the
-descriptions should be shown. Without the `tt(-o)' option, only the
-tt(verbose) style is used.
-
-tt(_describe) uses the tt(_all_labels) function to generate the matches, so
-that one doesn't need to put it into a loop over the tag labels.
-)
-findex(_multi_parts)
-item(tt(_multi_parts) var(sep) var(array))(
-This function gets two arguments: a separator character and an
-array.  As usual, 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.
-
-If given the tt(-i) option a single match left will be accepted
-immediatly even if that means that additional parts for which no
-separators were on the line are to be inserted. When completing from a 
-fixed set of possible completions which are really words, this is
-often the expected behaviour. But if tt(_multi_parts) should behave
-like completing pathnames, the tt(-i) option should not be used.
-
-Like other utility functions, this function accepts the `tt(-V)',
-`tt(-J)', `tt(-1)', `tt(-2)', `tt(-n)', `tt(-f)', `tt(-X)', `tt(-M)', `tt(-P)',
-`tt(-S)', `tt(-r)', `tt(-R)', and `tt(-q)' options and passes them to
-the tt(compadd) builtin.
-)
-findex(_sep_parts)
-item(tt(_sep_parts))(
-This function gets as arguments alternating arrays and separators.
-The arrays specify completions for parts of strings to be separated by the
-separators. The arrays may be the names of array parameters or
-a quoted list of words in parentheses. For example, with the array
-`tt(hosts=(ftp news))' the call `tt(_sep_parts '(foo bar)' @ hosts)' will
-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.
-)
-findex(_path_files)
-findex(_files)
-item(tt(_path_files) and tt(_files))(
-The function tt(_path_files) is used throughout the shell code
-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)'.
-
-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.
-
-Options accepted by both tt(_path_files) and tt(_files) are:
-
-startitem()
-item(tt(-f))(
-Complete all filenames.  This is the default.
-)
-item(tt(-/))(
-Specifies that only directories should be completed.
-)
-item(tt(-g) var(pattern))(
-Says 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. The 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
-filenames should be ignored. If no such option is given, 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.
-
-Finally, the tt(_path_files) function  uses the styles tt(expand),
-tt(ambiguous) and tt(special-dirs) and tt(file-sort).
-)
-findex(_parameters)
-item(tt(_parameters))(
-This should be used to complete parameter names. All arguments are
-passed unchanged to the tt(compadd) builtin.
-)
-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, making them match their
-lower-case counterparts. All arguments passed to this function are
-propagated unchanged to the tt(compadd) builtin.
-)
-findex(_set_options)
-findex(_unset_options)
-item(tt(_set_options) and tt(_unset_options))(
-These functions complete only set or unset options, with the same
-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.
-)
-findex(_arguments)
-item(tt(_arguments) var(specs) ...)(
-This function can be used to complete words on the line by simply
-describing the arguments the command on the line gets. The description 
-is given as arguments to this function, with each var(spec) describing
-one option or normal argument of the command. The descriptions
-understood are:
-
 startitem()
 item(var(n)tt(:)var(message)tt(:)var(action))(
 This describes the var(n)'th normal argument. The var(message) will be 
@@ -3289,77 +2924,296 @@
 array and the options in the tt(opt_args) association are prefixed
 with the set names and a hyphen.
 )
-findex(_values)
-item(tt(_values) var(specs) ...)(
-This is used to complete values (strings) and their arguments or
-lists of such values.
-
-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. I.e. 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.
+findex(_call)
+item(tt(_call) var(tag) var(string) ...)(
+This function is used in places where a command is called and the user 
+should have the possibility to override the default for calling this
+command. It looks up the tt(command) style with the supplied
+var(tag). If the style is set, its value is used as the command to
+execute.
 
-The 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.
+In any case, the var(strings) from the call to tt(_call) or from the
+style are concatenated with spaces between them and the resulting
+string is evaluated. The return value is the return value of the
+command called.
+)
+findex(_combination)
+item(tt(_combination) [ tt(-s) var(pattern) ] var(tag) var(style) var(specs) ... var(field) var(opts) ...)(
+This function is used to complete combinations of values such as pairs 
+of hostnames and usernames. The possible values will be taken from the 
+var(style) whose name is given as the second argument. The first argument
+is the var(tag) to use to do the lookup.
 
-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 difference is that
-there is no required minus or plus sign at the beginning and that
-values can have only one argument.
+The style name should consist of multiple parts separated by
+hyphens which are then used as fieldnames. Known values for such
+fields can be given after the second argument in arguments of the form 
+`var(field)tt(=)var(pattern)'. The first argument without a equal sign 
+is taken as the name of the field for which completions should be
+generated.
 
-Example:
+The matches generated will be taken from the value of the style. These 
+values should contain the possible values for the combinations where
+the values for the different fields are separated by colons or
+characters matching the pattern given after the tt(-s) option to
+tt(_combination) (normally this is used to define character classes
+like the `tt(-s "[:@]")' used for the tt(users-hosts) style).
 
-example(_values -s , 'description' \ 
-        '*foo[bar]' \ 
-        '(two)*one[number]:first count:' \ 
-        'two[another number]::second count:(1 2 3)')
+Only the values for the requested fields for which the patterns given
+in the `var(field)tt(=)var(pattern)' match the respective fields in
+the strings from the style value are generated as possible matches.
 
-This describes three possible values: `tt(foo)', `tt(one)', and
-`tt(two)'. The first one is described as `tt(bar)', gets no argument 
-and may appear more than once. The second one is described as
-`tt(number)', may appear more than once, and gets one mandatory
-argument described as `tt(first count)' for which no action is
-specified so that it will not be completed automatically. 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
-as `tt(another number)' and gets 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.
+If no style with the given name is defined for the given tag but a
+function named with the name of the requested field preceded by an
+underscore is defined, that function will be called to generate the
+matches. This is also done if none of the strings in the value of the
+style match all the patterns given as arguments.
 
-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.
+If the same name is used for more than one field, in both the
+`var(field)tt(=)var(pattern)' and the argument that gives the field
+name to complete for, the number of the field (starting with one) may
+be given after the fieldname, separated from it by a colon.
 
-To decide if the descriptions for the values (not those for the
-arguments) should be printed, the tt(verbose) is used.
+All arguments after the requested fieldname are given to the
+tt(compadd) used (when generating matches from the style value) and to 
+the functions for the fields if they are called.
+)
+findex(_compalso)
+item(tt(_compalso) var(names) ...)(
+This function looks up the definitions for the context and command
+names given as arguments and calls the handler functions for them if
+there is a definition (given with the tt(compdef) function). For
+example, the function completing inside subscripts might use
+`tt(_compalso -math-)' to include the completions generated for
+mathematical environments.
+)
+findex(_describe)
+item(tt(_describe) [ tt(-o) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)(
+This function can be used to add options or values with descriptions
+as matches. The var(descr) is taken as a string to display above
+the matches if the tt(format) style for the tt(descriptions) tag is set.
 
-One last difference to tt(_arguments) is that this function uses the
-associative array
-tt(val_args) to report values and their arguments (but 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:
+After this one or two names of arrays followed by options to give
+to tt(compadd) must be given. The first array contains the possible
+completions with their descriptions (with the description separated
+by a colon from the completion string). If the second array is given,
+it should have the same number of elements as the first one and these
+elements are added as possible completions instead of the strings from 
+the first array. In any case, however, the completion list will contain
+the strings from the first array.
 
-example(local context state line
-typeset -A val_args)
+Any number of array/option sequences may be given separated by
+`tt(-)tt(-)'. This allows one to display matches together that need
+to be added with different options for tt(compadd).
 
-when using an action of the form `tt(->)var(string)'. With this
-function the tt(context) parameter will be set to the name of the
-value whose argument is to be completed.
+Before the first argument, the option `tt(-o)' may be given. It says
+that the matches added are option names. This will make tt(_describe)
+use the tt(prefix-hidden), tt(prefix-needed) and tt(verbose) styles
+to find out if the strings should be added at all and if the
+descriptions should be shown. Without the `tt(-o)' option, only the
+tt(verbose) style is used.
 
-Like tt(_arguments), tt(_values) also supports the tt(-C) option in
-which case you have to make the parameter tt(curcontext) local instead 
-of tt(context) (as described above).
+tt(_describe) uses the tt(_all_labels) function to generate the matches, so
+that one doesn't need to put it into a loop over the tag labels.
+)
+findex(_description)
+item(tt(_description) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])(
+This function tests some styles for the var(tag) and and stores
+options usable for tt(compadd) in the array with the given var(name)
+which guarantee that the matches are generated as requested by the
+user. The styles tested are: tt(format) (which is first tested for the
+given 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.
+
+The format string from the style (if any) will be modified so that the 
+sequence `tt(%d)' is replaced by the var(descr) given as the third
+argument. If tt(_description) is called with more than three
+arguments, these 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).
+
+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 a 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)'. 
+
+In most cases, this function will be used like this:
+
+example(local expl
+_description files expl file
+compadd "$expl[@]" - "$files[@]")
+)
+findex(_funcall)
+item(tt(_funcall) var(return) var(name) [ var(args) ... ])(
+If a function var(name) exists, it is called with the arguments
+var(args). Unless it is the empty string or a single hyphen,
+var(return) is taken as the name of a parameter and the return status
+from the called function is stored in it.
+The return value of tt(_funcall) itself is zero if the function
+var(name) exists and was called and non-zero otherwise.
+)
+findex(_message)
+item(tt(_message) [ -r ] var(descr))(
+The var(descr) is used like the third
+argument to the tt(_description) function. However, 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.
+
+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.
+
+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.
+)
+findex(_multi_parts)
+item(tt(_multi_parts) var(sep) var(array))(
+This function gets two arguments: a separator character and an
+array.  As usual, 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.
+
+If given the tt(-i) option a single match left will be accepted
+immediatly even if that means that additional parts for which no
+separators were on the line are to be inserted. When completing from a 
+fixed set of possible completions which are really words, this is
+often the expected behaviour. But if tt(_multi_parts) should behave
+like completing pathnames, the tt(-i) option should not be used.
+
+Like other utility functions, this function accepts the `tt(-V)',
+`tt(-J)', `tt(-1)', `tt(-2)', `tt(-n)', `tt(-f)', `tt(-X)', `tt(-M)', `tt(-P)',
+`tt(-S)', `tt(-r)', `tt(-R)', and `tt(-q)' options and passes them to
+the tt(compadd) builtin.
+)
+findex(_next_label)
+item(tt(_next_label) [ 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(-12JV) 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
+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.
+
+A normal use of this function for the tag labels of the tag tt(foo)
+looks like this:
+
+example(local expl ret=1
+...
+if _requested foo; then
+  ...
+  while _next_label foo expl '...'; do
+    compadd "$expl[@]" ... && ret=0
+  done
+  ...
+fi
+return ret
+)
+)
+findex(_normal)
+item(tt(_normal))(
+This function is used for normal command completion.  If
+completion is attempted on the first word, command names are
+completed. Otherwise, the arguments are completed by calling the
+functions defined for this command, including those functions defined
+for patterns matching the command name. This function can also be
+called by other completion functions if they have to complete a range
+of words as a separate command. For example, the function to complete after
+the pre-command specifiers such as tt(nohup) removes the first word from
+the tt(words) array, decrements the tt(CURRENT) parameter, then calls this
+function.
+
+When calling a function defined for a pattern, this function also
+checks if the parameter tt(_compskip) is set and uses the value in the 
+same way it is used after calling the completion function for the
+tt(-first-) context. With this 
+one can write a pattern completion function that keeps other functions 
+from being tried simply by setting this parameter to any value.
+)
+findex(_parameters)
+item(tt(_parameters))(
+This should be used to complete parameter names. All arguments are
+passed unchanged to the tt(compadd) builtin.
+)
+findex(_path_files)
+findex(_files)
+item(tt(_path_files) and tt(_files))(
+The function tt(_path_files) is used throughout the shell code
+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)'.
+
+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.
+
+Options accepted by both tt(_path_files) and tt(_files) are:
+
+startitem()
+item(tt(-f))(
+Complete all filenames.  This is the default.
+)
+item(tt(-/))(
+Specifies that only directories should be completed.
+)
+item(tt(-g) var(pattern))(
+Says 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. The 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
+filenames should be ignored. If no such option is given, 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.
+
+Finally, the tt(_path_files) function  uses the styles tt(expand),
+tt(ambiguous) and tt(special-dirs) and tt(file-sort).
+)
+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, making them match their
+lower-case counterparts. All arguments passed to this function are
+propagated unchanged to the tt(compadd) builtin.
 )
 findex(_regex_arguments)
 item(tt(_regex_arguments) var(name) var(specs) ...)(
@@ -3426,46 +3280,80 @@
 )
 enditem()
 )
-findex(_combination)
-item(tt(_combination) [ tt(-s) var(pattern) ] var(tag) var(style) var(specs) ... var(field) var(opts) ...)(
-This function is used to complete combinations of values such as pairs 
-of hostnames and usernames. The possible values will be taken from the 
-var(style) whose name is given as the second argument. The first argument
-is the var(tag) to use to do the lookup.
+findex(_requested)
+item(tt(_requested) [ tt(-12VJ) ] var(tag) [ var(name) var(descr) [ var(command) var(args) ... ] ])(
+A function that uses tt(_tags) to register tags and then calls it to
+loop over the requested sets of tags should call this function to
+check if a certain tag is currently requested. This normally has to be 
+done in a loop such as:
 
-The style name should consist of multiple parts separated by
-hyphens which are then used as fieldnames. Known values for such
-fields can be given after the second argument in arguments of the form 
-`var(field)tt(=)var(pattern)'. The first argument without a equal sign 
-is taken as the name of the field for which completions should be
-generated.
+example(_tags foo bar baz
+while _tags; do
+  if _requested foo; then
+    ...
+  fi
+  ... # test other tags
+  ... # exit loop if matches were generated
+done)
 
-The matches generated will be taken from the value of the style. These 
-values should contain the possible values for the combinations where
-the values for the different fields are separated by colons or
-characters matching the pattern given after the tt(-s) option to
-tt(_combination) (normally this is used to define character classes
-like the `tt(-s "[:@]")' used for the tt(users-hosts) style).
+So, the first argument for tt(_requested) is used as the name of a tag 
+and if that tag is currently requested, the return value is zero (and
+non-zero otherwise).
 
-Only the values for the requested fields for which the patterns given
-in the `var(field)tt(=)var(pattern)' match the respective fields in
-the strings from the style value are generated as possible matches.
+If the var(name) and the var(descr) are given, tt(_requested) calls the
+tt(_description) function with these arguments, including the options.
 
-If no style with the given name is defined for the given tag but a
-function named with the name of the requested field preceded by an
-underscore is defined, that function will be called to generate the
-matches. This is also done if none of the strings in the value of the
-style match all the patterns given as arguments.
+If the var(command) is given, the tt(_all_labels) function will be called
+immediately with the same arguments.
 
-If the same name is used for more than one field, in both the
-`var(field)tt(=)var(pattern)' and the argument that gives the field
-name to complete for, the number of the field (starting with one) may
-be given after the fieldname, separated from it by a colon.
+This is often useful to do both the testing of the tag,
+getting the description for the matches and adding the matches at
+once. E.g.:
 
-All arguments after the requested fieldname are given to the
-tt(compadd) used (when generating matches from the style value) and to 
-the functions for the fields if they are called.
+example(local expl ret=1
+_tags foo bar baz
+while _tags; do
+  _requested foo expl 'description' \ 
+      compadd foobar foobaz && ret=0
+  ...
+  (( ret )) || break
+done)
 )
+findex(_sep_parts)
+item(tt(_sep_parts))(
+This function gets as arguments alternating arrays and separators.
+The arrays specify completions for parts of strings to be separated by the
+separators. The arrays may be the names of array parameters or
+a quoted list of words in parentheses. For example, with the array
+`tt(hosts=(ftp news))' the call `tt(_sep_parts '(foo bar)' @ hosts)' will
+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.
+)
+findex(_set_options)
+findex(_unset_options)
+item(tt(_set_options) and tt(_unset_options))(
+These functions complete only set or unset options, with the same
+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.
+)
+findex(_setup)
+item(tt(_setup) var(tag))(
+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).
+
+Note that this function is called automatically from tt(_description)
+so that one normally doesn't have to call it explicitly.
+)
 findex(_sort_tags)
 item(tt(_sort_tags) var(tag) ...)(
 As described above for the tt(tag-order) style, this is only provided
@@ -3549,7 +3437,121 @@
 same way as the the values for the tt(tag-order) style (except for the 
 `tt(!...)', `tt(-)' and `tt(foo())' forms).
 )
+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 to make tt(_tags) use a more
+specific context name without having to change and reset the
+tt(curcontext) parameter (which would otherwise have the same effect).
+)
+findex(_wanted)
+item(tt(_wanted) [ tt(-C) var(name) ]  [ tt(-12VJ) ] var(tag) var(name) var(descr) var(command) var(args) ...)(
+In many contexts only one type of matches can be generated but even
+then it should be tested if the tag representing those matches is
+requested by the user. This function makes that easier.
+
+Like tt(_requested) it gets arguments as for tt(_description).
+With the var(tag) it calls tt(_tags) and if that returns zero 
+(i.e. the var(tag) is requested by the user) it calls tt(_description). So, 
+if you want to offer only one tag and immediatly want to use the
+description built, you can just do:
+
+example(_wanted tag expl 'description' \ 
+    compadd matches...)
+
+Unlike tt(_requested), however, tt(_wanted) can not be called without
+the var(command). That's because tt(_wanted) also implements the loop
+over the tags, not only the one for the labels.
+
+Like tt(_tags) this function supports the tt(-C) option to give a
+different name for the argument context field.
+)
+findex(_values)
+item(tt(_values) var(specs) ...)(
+This is used to complete values (strings) and their arguments or
+lists of such values.
+
+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. I.e. 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.
+
+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.
+
+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 difference is that
+there is no required minus or plus sign at the beginning and that
+values can have only one argument.
+
+Example:
 
+example(_values -s , 'description' \ 
+        '*foo[bar]' \ 
+        '(two)*one[number]:first count:' \ 
+        'two[another number]::second count:(1 2 3)')
+
+This describes three possible values: `tt(foo)', `tt(one)', and
+`tt(two)'. The first one is described as `tt(bar)', gets no argument 
+and may appear more than once. The second one is described as
+`tt(number)', may appear more than once, and gets one mandatory
+argument described as `tt(first count)' for which no action is
+specified so that it will not be completed automatically. 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
+as `tt(another number)' and gets 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 tt(verbose) is used.
+
+One last difference to tt(_arguments) is that this function uses the
+associative array
+tt(val_args) to report values and their arguments (but 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:
+
+example(local context state line
+typeset -A val_args)
+
+when using an action of the form `tt(->)var(string)'. With this
+function the tt(context) parameter will be set to the name of the
+value whose argument is to be completed.
+
+Like tt(_arguments), tt(_values) also supports the tt(-C) option in
+which case you have to make the parameter tt(curcontext) local instead 
+of tt(context) (as described above).
+)
 enditem()
 
 texinode(Completion Directories)()(Completion Functions)(Completion System)

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com