about summary refs log tree commit diff
path: root/Doc/Zsh/compsys.yo
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/Zsh/compsys.yo')
-rw-r--r--Doc/Zsh/compsys.yo375
1 files changed, 197 insertions, 178 deletions
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 7054f8a27..7558e14c8 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -234,7 +234,7 @@ the tt(#compdef -p) function tag.
 The form with tt(-P) is like the third, but the var(function) will be
 called only if no function for the command itself was found or if one
 was found and it set the tt(_compskip) parameter to a value em(not)
-containing the substring `tt(patterns)'.
+containing the substring tt(patterns).
 
 The form with tt(-k) defines a widget with the same name as the var(function)
 which will be called for each of the var(key-sequences); this is like the
@@ -267,7 +267,8 @@ Several aspects of the completion system can be configured by the
 user. This function allows to define so-called styles that are used by 
 various completion functions. These styles are associated with
 patterns that are compared to context names used by the completion
-system. The configuration possibilities are explained in detail in
+system. The possible ways to configure the completion system are
+explained in detail in
 ifzman(the section `Completion System Configuration' below)\
 ifnzman(noderef(Completion System Configuration))\
 .
@@ -316,7 +317,7 @@ to, say, correction, which can also be done using the function based
 completion system (see
 ifzman(the section `Control Functions' below)\
 ifnzman(noderef(Control Functions)) 
-for more information). And the tt(::dvips:) shows that we are
+for more information). The tt(::dvips:) shows that we are
 completing arguments for the tt(dvips) command. Such a doubled colon
 will appear only before and after the name of the command, but note
 that the second colon after the command name is really only added when 
@@ -344,8 +345,7 @@ system is often called to generate only filenames matching a given
 glob pattern and then uses the tags tt(globbed-files),
 tt(directories), and tt(all-files). This means that the function
 offers to generate filenames matching the pattern, names of
-directories or all filenames as possible matches. Now, if the user has
-this definition for tt(_sort_tags):
+directories or all filenames as possible matches. Example:
 
 example(_sort_tags() {
   case $curcontext in
@@ -451,8 +451,8 @@ current cursor position. This allows one to easily find out all the
 information needed to change the tt(_sort_tags) function when one
 wants to change the way matches are generated for that context.
 
-But the tt(_sort_tags) function is only one half of the configuration
-possibilities of the completion system. The other half uses the
+But the completion system can not only be configured by supplying a
+specialized tt(_sort_tags) function. There are also the
 `styles' defined with the tt(compstyle) function mentioned in
 ifzman(the section `Initialization' above)\
 ifnzman(noderef(Initialization))\
@@ -759,8 +759,10 @@ Here are the names of the styles used by the completion system. Note
 that the values of several of these styles represent boolean
 values. In all these cases any of the strings `tt(true)', `tt(on)',
 `tt(yes)', and `tt(1)' can be used for the truth value `true' and
-every other value (or if the style is not set at all for the context
-in which it is looked up) stands for `false'.
+the strings `tt(false)', `tt(off)', `tt(no)', and `tt(0)' are
+interpreted as `false'.  The behavior for any other value is undefined 
+unless the description for the particular style mentions other
+possible values.
 
 startitem()
 item(tt(accept-exact))(
@@ -795,6 +797,19 @@ described in
 ifzman(the section `Control Functions' below)\
 ifnzman(noderef(Control Functions))\
 .
+
+Note that the widget functions from the distribution that call the
+completion code (namely, the tt(incremental-complete-word) and the
+tt(predict-on) widgets) set up their top-level context name before
+calling completion. This allows one to define different sets of
+completer functions for normal completion and for these widgets. For
+example, to use completion, approximation and correction for normal
+completion, completion and correction for incremental completion and
+only completion for prediction one could use:
+
+example(compstyle '*' completer _complete _correct _approximate
+compstyle ':incremental' completer _complete _correct
+compstyle ':predict' completer _complete)
 )
 item(tt(completions))(
 This style is used by the tt(_expand) completer function.
@@ -822,7 +837,7 @@ other than `tt(1)'.
 )
 item(tt(cursor))(
 This is used together with the tt(paths) tag by the function
-generating filenames as matches to find out if the cursor will be left
+generating filenames as matches to find out if the cursor should be left
 after the first ambiguous pathname component even when menucompletion
 is used.
 )
@@ -832,10 +847,17 @@ tt(cvs) command to decide if the tt(stat) module should be used to
 generate only names of modified files in the appropriate places.
 )
 item(tt(expand))(
-Like tt(cursor), this style is used with the tt(paths) tag. If it is
-set to `true', the partially typed path from the line will be
-expanded as far as possible even if trailing pathname components can
-not be completed.
+Like tt(cursor), this style is used with the tt(paths) tag. If its
+value contains the string tt(prefix), the partially typed path from
+the line will be expanded as far as possible even if trailing pathname
+components can not be completed. If it contains the string tt(suffix)
+and normal (non-menu-) completion is used, matching names for
+components after the first ambiguous one will be added, too. This
+means that the resulting string is the longest unambiguous string
+possible, but if menucompletion is started on the list of matches
+generated this way (e.g. due to the option tt(AUTO_MENU) being set),
+this will also cycle through the names of the files in pathname
+components after the first ambiguous one.
 )
 item(tt(format))(
 If this is set for the tt(descriptions) tag, its value is used as a
@@ -845,11 +867,11 @@ what these matches are. This string may also contain the sequences to
 specify output attributes, such as `tt(%b)' and `tt(%s)'.
 
 For the same purpose, this style is also tested with the tags used
-when matches are generated em(before it is tested for the
-tt(descriptions) tag). This gives the possibility to define different
+when matches are generated before it is tested for the
+tt(descriptions) tag. This gives the possibility to define different
 format strings for different types of matches.
 
-Not also that some completer functions define additional
+Note also that some completer functions define additional
 `tt(%)'-sequences. These are described for the completer function that 
 make use of them.
 
@@ -893,7 +915,7 @@ different types of matches displayed separately, one can just set:
 example(compstyle '*' group-name '')
 
 All matches for which no group name is defined will be put in a group
-named `tt(-default-)'.
+named tt(-default-).
 )
 item(tt(group-order))(
 This style is to be used together with the tt(group-name) style. Once
@@ -924,7 +946,7 @@ shown. If this is set to tt(all), not even the description will be
 displayed.
 
 Note that the matches will still be completed, they are just not shown 
-in the list. To avoid having some matches to considered possible
+in the list. To avoid having some matches to be considered possible
 completions one can modify the tt(_sort_tags) function as described
 above.
 )
@@ -956,7 +978,7 @@ completion only if no unambiguous string could be generated that is at
 least as long as the original string from the line.
 )
 item(tt(last-prompt))(
-This is used to determine if thecompletion code should try to put the
+This is used to determine if the completion code should try to put the
 cursor back onto the previous command line after showing a completion
 listing (as for the tt(ALWAYS_LAST_PROMPT) option). Like several other 
 styles it is tested for the tt(default) tag and all tags used when
@@ -1056,7 +1078,7 @@ generate completions by first allowing one error, then two errors, and
 so on, until either a match was found or the maximum number of errors
 given by this style has been reached.
 
-If the value for this style contains the string `tt(numeric)', the 
+If the value for this style contains the string tt(numeric), the 
 completer function will take any numeric argument as the
 maximum number of errors allowed. For example, with
 
@@ -1067,7 +1089,7 @@ with a numeric argument of six (as in `tt(ESC-6 TAB)'), up to six
 errors are accepted.  Hence with a value of `tt(0 numeric)', no correcting
 completion will be attempted unless a numeric argument is given.
 
-If the value contains the string `tt(not-numeric)', tt(_approximate)
+If the value contains the string tt(not-numeric), tt(_approximate)
 will em(not) try to generate corrected
 completions when given a numeric argument, so in this case the number given
 should be greater than zero.  For example, `tt(2 not-numeric)' specifies that
@@ -1082,22 +1104,24 @@ matches for the given tag (or always in case of the tt(default) tag)
 are generated. If none of these values is defined for any of the tags
 used, but for at least one of these tags the value is the string
 tt(auto), this says that the same behavior as for the tt(AUTO_MENU)
-options should be used. Finally, if menu-completion is started by some 
+option should be used. Finally, if menucompletion is started by some 
 other means (e.g. by setting the tt(MENU_COMPLETE) option) and the
 value for one of the tags used is `false' (i.e. tt(no), tt(false),
-tt(0), or tt(off)), then menu-completion will em(not) be started for
+tt(0), or tt(off)), then menucompletion will em(not) be started for
 this completions. Note that the values defined for normal tags
 override the value set for the tt(default) tag.
 
 Either instead of or in addition to one of the values above, the value
 for this style may also contain the string tt(select), optionally
-followed by an equal sign and a number. In this case menu-selection
+followed by an equal sign and a number. In this case menuselection
 (as defined by the tt(computil) module) will be started. Without the
 optional number, it will be started unconditionally and with a number
 it will be started only if at least that many matches are generated
 (if the values for more than one tag defines such a number, the
-smallest one is taken). Starting menu-selection can explicitly be
-turned off by defining a value containing the string tt(no-select).
+smallest one is taken). Starting menuselection can explicitly be
+turned off by defining a value containing the string
+tt(no-select). Note that all this only works if the tt(complist)
+module is explicitly loaded by the user, though.
 
 This is also used by the tt(_oldlist) completer. Here it controls how menu
 completion behaves when a completion has already been inserted and the
@@ -1122,7 +1146,7 @@ two possible corrections, but if this style is set to `true', it will
 always be added.
 
 For the tt(_match) completer, if this style is set to
-`tt(only)', it will try to generate matches without inserting a
+tt(only), it will try to generate matches without inserting a
 `tt(*)' at the cursor position. If set to any other non-empty value,
 it will first try to generate matches without inserting the `tt(*)'
 and if that yields no matches, it will try again with the `tt(*)'
@@ -1140,7 +1164,9 @@ tt(User) sub-directory of the completion system for more information.
 
 Also, the function that completes color names uses this style with the 
 tt(colors) tag. Here, the value should be the pathname of a file
-containing color names in the format of an X11 tt(rgb.txt) file.
+containing color names in the format of an X11 tt(rgb.txt) file. That
+file (if it can be found) will be used as the default if the style is
+not set.
 )
 item(tt(ports))(
 A style holding the service names of ports to complete. If this is
@@ -1156,7 +1182,7 @@ item(tt(prefix-needed))(
 This, too, is used for matches with a common prefix. If it is set to
 `true' this common prefix has to be typed by the user to generate the
 matches. E.g. for options this means that the `tt(-)', `tt(+)', or
-`tt(--)' has to be on the line to make option names be completed at
+`tt(-)tt(-)' has to be on the line to make option names be completed at
 all.
 )
 item(tt(prompt))(
@@ -1172,12 +1198,12 @@ is replaced by the name of the completer function that generated the
 matches (without the leading underscore). Finally, `tt(%n)' is
 replaced by the number of matches generated, `tt(%a)' is replaced by
 an empty string if the matches are in the normal set (i.e. the one
-without file names with one of the suffixes from the tt(fignore)
-array) and with `tt( -alt-)' if the matches are in the alternate set,
-and if the tt(list) style is set, `tt(%l)' is replaced by `tt(...)' if
-the list of matches is too long to fit on the screen and with an empty
-string otherwise. If tt(incremental_list) is not set or set to an
-empty string, `tt(%l)' will always be removed.
+without file names with one of the suffixes from the
+tt(ignored-suffixes) style) and with `tt( -alt-)' if the matches are
+in the alternate set, and if the tt(list) style is set, `tt(%l)' is
+replaced by `tt(...)' if the list of matches is too long to fit on the
+screen and with an empty string otherwise. If the tt(list) style is
+`false', `tt(%l)' will always be removed.
 )
 item(tt(remove-all-dups))(
 The tt(_history_complete_word) bindable command uses this to decide if 
@@ -1197,8 +1223,8 @@ as single strings (not in the string containing all possible
 expansions).
 )
 item(tt(stop))(
-If set to a non-empty string, the tt(_history_complete_word) bindable
-command will always insert matches as if menu-completion were started
+If set to `true', the tt(_history_complete_word) bindable
+command will always insert matches as if menucompletion were started
 and it will stop when the last match is inserted. If this style is set
 to tt(verbose) a message will be displayed when the last match is reached.
 )
@@ -1230,7 +1256,7 @@ item(tt(users-hosts))(
 The values of this style should be of the form
 `var(user)tt(:)var(host)'. It is used for commands that need pairs of
 user- and hostnames. For such commands, only the pairs from this style 
-are used and if, for example, the hostname is already typed, then only 
+are used and if, for example, the username is already typed, then only 
 the hostnames for which there is a pair with that username is defined.
 
 If set for the tt(my-accounts) tag, this is used for commands such as
@@ -1271,7 +1297,7 @@ correction if that doesn't generate any matches:
 
 example(compstyle '*' completer _complete _correct)
 
-after sourcing tt(compinit). The default value for this style set up
+after calling tt(compinit). The default value for this style set up
 in tt(compinit) is `tt(_complete)', i.e. normally only ordinary
 completion is tried. The tt(_main_complete) function uses the return
 value of the completer functions to decide if other completers should be
@@ -1284,19 +1310,15 @@ then resets it to an empty array. This can be used by completion
 functions or by other ZLE widgets calling completion to register code
 that is to be executed after all matches have been added.
 
-The widget function tt(_main_complete) also uses the style 
-tt(last-prompt). If this is set to `true', the cursor is moved up
-to the last prompt after printing a list of matches even if a numeric
-argument was given.
-
 The following completer functions are contained in the distribution (users
 may write their own):
 
 cindex(completion system, completers)
 startitem()
+findex(_complete)
 item(tt(_complete))(
 This completer generates all possible completions in a context-sensitive
-manner, i.e. using the tt(compdef) function
+manner, i.e. using the settings defined with the tt(compdef) function
 explained above and the current settings of all special parameters.
 
 To complete arguments of commands, tt(_complete) uses the utility function
@@ -1341,13 +1363,13 @@ for completing the name of a parameter expansion within braces
 (`tt(${...})').
 )
 item(tt(-first-))(
-for adding completions before any other other completion functions are
+for adding completions before any other completion functions are
 tried; if this
-function sets the tt(_compskip) parameter to `tt(all)', no other
+function sets the tt(_compskip) parameter to tt(all), no other
 completion functions will be called, if it is set to a string
-containing `tt(patterns)', no pattern completion functions will be
-called, and if it is set to a string containing `tt(default)' the
-function for the `tt(-default-)' context will not be called, but
+containing the string tt(patterns), no pattern completion functions
+will be called, and if it is set to a string containing tt(default)
+the function for the `tt(-default-)' context will not be called, but
 functions defined for commands will.
 )
 item(tt(-default-))(
@@ -1367,20 +1389,8 @@ Before trying to find a function for a specific context, tt(_complete)
 checks if the parameter `tt(compcontext)' is set to a non-empty
 value. If it is, the value is taken as the name of the context to use
 and the function defined for that context will be called.
-
-Note that the widget functions from the distribution that call the
-completion code (namely, the tt(incremental-complete-word) and the
-tt(predict-on) widgets) set up their top-level context name before
-calling completion. This allows one to define different sets of
-completer functions for normal completion and for these widgets. For
-example, to use completion, approximation and correction for normal
-completion, completion and correction for incremental completion and
-only completion for prediction one could use:
-
-example(compstyle '*' completer _complete _correct _approximate
-compstyle ':incremental' completer _complete _correct
-compstyle ':predict' completer _complete)
 )
+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 
@@ -1406,7 +1416,7 @@ menucompletion allowing you to cycle through these strings.
 
 This completer uses the tags tt(corrections) and tt(original) when
 generating the possible coprrections and the original string. The
-tt(format) style for the former may contain the additional seuqences
+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.
@@ -1418,6 +1428,7 @@ containing the number of errors accepted in this attempt. So on the
 first try the context name starts with `tt(:approximate:1)', on the
 second try with `tt(:approximate:2)', and so on.
 )
+findex(_correct)
 item(tt(_correct))(
 Generate corrections (but not completions) for the current word; this is
 similar to spell-checking.  This calls tt(_approximate) but uses a
@@ -1426,7 +1437,7 @@ different top-level context name.
 For example, with:
 
 example(compstyle '*' completer _complete _correct _approximate
-compstyle ':correct' accept 2 not-numeric'
+compstyle ':correct' accept 2 not-numeric
 compstyle ':approximate' accept 3 numeric)
 
 correction will accept up to two errors. If a numeric argument is
@@ -1442,6 +1453,7 @@ it. Using it after the tt(_approximate) completer is useless since
 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
@@ -1452,7 +1464,7 @@ 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(original) style has a value of `tt(only)', no `tt(*)' will be
+tt(original) style has a value of tt(only), no `tt(*)' will be
 inserted. If tt(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.
@@ -1465,6 +1477,7 @@ 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
 checks if the word on the command line is eligible for expansion and,
@@ -1490,6 +1503,7 @@ string from the line.
 In a different mode selected by the tt(completions) style, all
 em(completions) generated for the string on the line are inserted.
 )
+findex(_list)
 item(tt(_list))(
 This completer allows one to delay the insertion of matches until
 completion is attempted a second time without the word on the line
@@ -1498,6 +1512,7 @@ shown. Styles used are tt(condition) and tt(word), see
 ifzman(the section `Completion System Configuration' above)\
 ifnzman(noderef(Completion System Configuration)).
 )
+findex(_menu)
 item(tt(_menu))(
 This completer is a simple example function implemented to show how
 menucompletion can be done in shell code. It should be used as the
@@ -1507,6 +1522,7 @@ tt(MENU_COMPLETE) option and does not work with the other
 menucompletion 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
 when there is an existing list of completions which may have been
@@ -1529,6 +1545,7 @@ implementing special behaviour which can be bound separately to keys.  The
 following is a list of these and their default bindings.
 
 startitem()
+findex(_bash_completions)
 item(tt(_bash_completions))(
 This function is used by two widgets, tt(_bash_complete-word) and
 tt(_bash_list-choices).  It exists to provide compatibility with
@@ -1549,31 +1566,38 @@ done)
 This includes the bindings for `tt(~)' in case they were already bound to
 something else; the completion code does not override user bindings.
 )
+findex(_correct_filename (^XC))
 item(tt(_correct_filename (^XC)))(
 Correct the filename path at the cursor position.  Allows up to six errors
 in the name.  Can also be called with an argument to correct
 a filename path, independently of zle; the correction is printed on
 standard output.
 )
+findex(_correct_word) (^Xc)
 item(tt(_correct_word) (^Xc))(
 Performs correction of the current argument using the usual contextual
 completions as possible choices. This uses the top-level context name
 `tt(:correct-word)' and then calls the tt(_correct) completer.
 )
+findex(_expand_word (^Xe))
 item(tt(_expand_word (^Xe)))(
 Performs expansion on the current word:  equivalent to the standard
 tt(expand-word) command, but using the tt(_expand) completer. Before
 calling it, the top-level context name is set to `tt(:expand-word)'.
 )
+findex(_history_complete_word) (\e/)
 item(tt(_history_complete_word) (\e/))(
-Complete words from the shell's command history.
+Complete words from the shell's command history. This uses the
+tt(list), tt(remove-all-dups), tt(sort), and tt(stop) styles.
 )
+findex(_most_recent_file (^Xm))
 item(tt(_most_recent_file (^Xm)))(
 Complete the name of the most recently modified file matching the pattern
 on the command line (which may be blank).  If given a numeric argument
 var(N), complete the var(N)th most recently modified file.  Note the
 completion, if any, is always unique.
 )
+findex(_read_comp (^X^R))
 item(tt(_read_comp (^X^R)))(
 Prompt the user for a string, and use that to perform completion on the
 current word.  There are two possibilities for the string.  First, it can
@@ -1597,6 +1621,7 @@ Once a string has been read, the next call to tt(_read_comp) will use the
 existing string instead of reading a new one.  To force a new string to be
 read, call tt(_read_comp) with a numeric argument.
 )
+findex(_complete_help (^Xh))
 item(tt(_complete_help (^Xh)))(
 This widget displays information about the context names and tags used 
 when completing at the current cursor position.
@@ -1625,7 +1650,8 @@ 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.
 )
-item(tt(_compalso))(
+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
@@ -1633,6 +1659,7 @@ example, the function completing inside subscripts might use
 `tt(_compalso -math-)' to include the completions generated for
 mathematical environments.
 )
+findex(_normal)
 item(tt(_normal))(
 This function is used for normal command completion.  If
 completion is attempted on the first word, command names are
@@ -1652,31 +1679,31 @@ 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.
 )
-item(tt(_description))(
-The first three arguments to this function are: a group name,
-the name of an array and a string. It tests if some styles for the tag 
-and stores options usable for tt(compadd) in the array 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)
-and tt(group-name) (the last two are tested only for the tag given as
-the first argument). This function also calls the tt(_setup) function
-which tests some more styles.
+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) and tt(group-name) (the last two 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 string given as the third
+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 extra arguments should be of the form
+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).
 
-These options placed in the array will also make sure that the matches
+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)' or
-`tt(-J)' 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(-V1)', or `tt(-V2)'. 
+(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:
 
@@ -1684,8 +1711,9 @@ example(local expl
 _description expl files file
 compadd "$expl[@]" - "$files[@]")
 )
-item(tt(_message))(
-This function takes one argument which is used like the second
+findex(_message)
+item(tt(_message) var(descr))(
+The var(descr) used like the third
 argument to the tt(_description) function. However, the resulting
 string will always be shown, not only if some matches were
 generated. This is useful to display help texts in places where no
@@ -1695,15 +1723,17 @@ 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.
 )
-item(tt(_setup))(
+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 don't have to call it explicitly.
+so that one normally doesn't have to call it explicitly.
 )
-item(tt(_tags))(
+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
@@ -1716,14 +1746,16 @@ 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 name. This
-name is temporarily (i.e. not visible outside tt(_tags)) appended
-(with a colon before it) to the contents of the tt(curcontext)
-parameter. This allows to make tt(_tags) and tt(_sort_tags) use a
-more specific context name without having to change and reset the
-tt(curcontext) parameter (which would otherwise have the same effect).
+This function also accepts the tt(-C) option followed by a
+var(name). This name is temporarily (i.e. not visible outside
+tt(_tags)) appended (with a colon before it) to the contents of the
+tt(curcontext) parameter. This allows to make tt(_tags) and
+tt(_sort_tags) 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(_requested))(
+findex(_requested)
+item(tt(_requested) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])(
 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 
@@ -1743,9 +1775,7 @@ and if that tag is currently requested, the return value is zero (and
 non-zero otherwise).
 
 If more than one argument is given, tt(_requested) calls the
-tt(_description) function with all arguments and if the first argument 
-is a option string starting with tt(-J) or tt(-V), the argument after
-it is taken as the name of the tag.
+tt(_description) function with all arguments, including the options.
 This is often useful to do both the testing of the tag and
 getting the description for the matches one is about to add at
 once. E.g.:
@@ -1759,14 +1789,15 @@ while _tags; do
   (( ret )) || break
 done)
 )
-item(tt(_wanted))(
+findex(_wanted)
+item(tt(_wanted) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])(
 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 tag it calls tt(_tags) and if that returns zero 
-(i.e. the tag is requested by the user) it calls tt(_description). So, 
+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:
 
@@ -1779,13 +1810,14 @@ that adds a description itself, you only need to call tt(_tags) as in:
 
 example(_tags tag && _helper)
 )
-item(tt(_alternative))(
+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 above.
 
 The tags to use and what to do if the tags are requested are described 
-using the arguments which are of the form:
+using the var(specs) 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 var(descr) (description). The var(action)s
@@ -1805,13 +1837,14 @@ generated by the tt(_users) and tt(_hosts) functions respectively).
 Like tt(_tags) this function supports the tt(-C) option to give an
 additional context name component.
 )
+findex(_style)
 item(tt(_style))(
 This function is used to look up the values of styles defined by the
 user. In its simplest form, it is called with two arguments: a tag and 
 a style-name. The tag (if non-empty) is temporarily appended to the
 current context name (preceded by a colon) and the patterns defined by 
 the user with the tt(compstyle) function will be compared to that
-combined name. If any of those pattern matches the name and the given
+combined name. If any of those patterns match the name and the given
 style is defined for it and its boolean value is `true' (i.e. its
 value is one of `tt(true)', `tt(on)', `tt(yes)', and `tt(1)'), tt(_style)
 returns zero and non-zero otherwise. If you want to test the style not 
@@ -1819,12 +1852,6 @@ only for a boolean value, you can give a third argument which is then
 used as a pattern and tt(_style) returns zero if the pattern matches
 the value defined for the style.
 
-The tt(-t) and tt(-f) options can be used to test for slightly
-different interpretions of boolean values. If they are given with a
-tag and a style-name as arguments, the return value is zero only if
-the style is set and the value is equal (or, in case of then tt(-f)
-option: unequal) to one of the values mentioned above.
-
 If you want to retrieve the value defined for the style, you can use
 one of the options tt(-b) (to retrieve it as a boolean value, i.e. one 
 of tt(yes) or tt(no)), tt(-s) (to get it as a scalar, i.e. a string
@@ -1848,13 +1875,14 @@ array into the parameter tt(tmp):
 example(local tmp
 _style -a foo path tmp)
 
-In any case, the return value of this function is zero, if a
+In any case, the return value of this function is zero if a
 definition for the style was found and non-zero if no definition was
 found.
 )
-item(tt(_describe))(
+findex(_describe)
+item(tt(_describe) 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 first argument is taken as a string to display above
+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
@@ -1870,16 +1898,17 @@ 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, two options may be given. A `tt(-o)' says
+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(description) styles
+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(description) style is used.
+tt(verbose) style is used.
 )
-item(tt(_multi_parts))(
+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 array may be either the
+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
@@ -1891,9 +1920,11 @@ names in the way normal filenames are completed by the
 tt(_path_files) function.
 
 Like other utility functions, this function accepts the `tt(-V)',
-`tt(-J)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)', `tt(-r)', `tt(-R)', and
-`tt(-q)' options and passes them to the tt(compadd) builtin.
+`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 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
@@ -1903,10 +1934,13 @@ 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(-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 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
@@ -1923,41 +1957,25 @@ array parameter or a literal list of paths enclosed in parentheses.
 Additionally, the `tt(-F)'
 option from the tt(compadd) builtin is supported, giving direct control
 over which filenames should be ignored. If no such option is given,
-the tt(fignore) parameter is used.
+the tt(ignored-suffixes) style is used.
 
 The function tt(_files) calls tt(_path_files) with all the arguments
 it was passed and, if that generated no matches, calls tt(_path_files) again
 without any tt(-g) or tt(-/) option, thus generating all filenames.
 
-These functions also accept the `tt(-J)', `tt(-V)', `tt(-X)',
-`tt(-M)', `tt(-P)', `tt(-S)', `tt(-q)', `tt(-r)', and `tt(-R)' options
-from the tt(compadd) builtin.
+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 supports two styles.
-startitem()
-item(tt(expand))(
-If this is set to a string containing `tt(prefix)', the partially
-typed path from the line will be expanded as far as possible even if
-trailing pathname components can not be completed. If it contains the
-substring `tt(suffix)' and normal (non-menu-) completion is used,
-matching names for components after the first ambiguous one will be
-added, too. This means that the resulting string is the longest
-unambiguous string possible, but if menu-completion is started on the
-list of matches generated this way (e.g. due to the option
-tt(AUTO_MENU) being set), this will also cycle through the names
-of the files in pathname components after the first ambiguous one.
-)
-item(tt(cursor))(
-If this is set to `true', the cursor will be left after the first
-ambiguous pathname component even when menucompletion is used.
-)
-enditem()
+Finally, the tt(_path_files) function  uses the styles tt(expand) and
+tt(cursor) with the tt(paths) tag.
 )
+findex(_parameters)
 item(tt(_parameters))(
-This should be used to complete parameter names if you need some of the
-extra options of tt(compadd). All arguments are passed unchanged to
-the tt(compadd) builtin.
+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 
@@ -1965,6 +1983,8 @@ 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.
@@ -1974,13 +1994,14 @@ 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.
 )
-item(tt(_arguments))(
+findex(_arguments)
+item(tt(_arguments) var(specs) ...)(
 This function resides in the tt(Base) subdirectory of the example
 completion system because it is not used by the core system.
 
 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 argument describing
+is given as arguments to this function, with each var(spec) describing
 one option or normal argument of the command. The descriptions
 understood are:
 
@@ -2045,13 +2066,11 @@ var(opt-spec), as in `tt(-foo-)'. If the first argument may be given
 in one string with the option name, but may also be given as a
 separate argument after the option, a plus sign should be used
 instead. If the argument may be given as the next string or in same
-string as the option name but separated by it from an equal sign, a
+string as the option name but separated from it by an equal sign, a
 `tt(=)' should be used instead of the minus or plus sign.
 
 If the option may be given more than once, a star
-(`tt(*)') has to be added in front of the var(opt-spec) because
-otherwise it is not offered as a possible completion again if it is
-already on the line.
+(`tt(*)') has to be added in front of the var(opt-spec).
 
 An var(opt-spec) may also contain a list of other option names with
 which the option described is mutually exclusive. Such a list is given 
@@ -2064,7 +2083,7 @@ should not be used if the option described is on the line.
 
 Finally, the var(opt-spec) may contain a explanation string. This is
 given in brackets at the end, as in `tt(-q[query operation])'. The
-tt(description) style for the tt(options) tag is used to decide if these
+tt(verbose) style is used to decide if these
 explanation strings should be printed when options are listed. If no
 explanation string is given but the tt(auto-describe) style is
 set and only one argument is described for this var(opt-spec), the
@@ -2076,7 +2095,7 @@ enditem()
 
 In each of the cases above, the var(action) says how the possible
 completions should be generated. In cases where only one of a fixed
-set of strings can be completed, these string can directly be given as 
+set of strings can be completed, these strings can directly be given as 
 a list in parentheses, as in `tt(:foo:(foo bar baz))'. Such a list in
 doubled parentheses, as in `tt(:foo:((a\:bar b\:baz)))' should contain 
 strings consisting of the string to complete followed by a colon
@@ -2226,14 +2245,10 @@ or as a literal list in parentheses. E.g. `tt(-i
 option `tt(-s) var(pairs)' (again, after the `tt(-)tt(-)') can be used to
 describe option aliases. Each var(pair) consists of a pattern and a
 replacement. E.g. some tt(configure)-scripts describe options only as
-`tt(-)tt(-enable-foo)', but also accept `tt(disable-foo)'. To allow
+`tt(-)tt(-enable-foo)', but also accept `tt(-)tt(-disable-foo)'. To allow
 completion of the second form, one would use `tt(-s "LPAR()#-)tt(-enable-
 -)tt(-disable-RPAR()")'.
 
-Finally, this function uses the styles tt(description),
-tt(prefix-hidden) and tt(prefix-needed) with the tt(options) tag when
-generating option names as matches.
-
 Example:
 
 example(_arguments '-l+:left border:' \ 
@@ -2262,7 +2277,8 @@ arguments. The first one describes the first argument as a
 be completed. The last description says that all other arguments are
 `var(page numbers)' but does not give possible completions.
 )
-item(tt(_values))(
+findex(_values)
+item(tt(_values) var(specs) ...)(
 This is used to complete values (strings) and their arguments or
 lists of such values.
 
@@ -2300,7 +2316,7 @@ 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 any more. Finally, the last value (`tt(two)') is described
+completion anymore. Finally, the last value (`tt(two)') is described
 as `tt(another number)' and gets an optional argument decribed 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
@@ -2312,8 +2328,7 @@ 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(description) for the
-tt(values) tag is used.
+arguments) should be printed, the tt(verbose) is used.
 
 One last difference to tt(_arguments) is that this function uses the
 associative array
@@ -2334,7 +2349,8 @@ 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).
 )
-item(tt(_regex_arguments))(
+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 generated function and rest arguments
 specifies a completion specification in the notation like regular
@@ -2396,16 +2412,17 @@ This is alternation of two `var(spec)'s.
 )
 enditem()
 )
-item(tt(_combination))(
+findex(_combination)
+item(tt(_combination) [ tt(-s) var(spec) ] 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 
-style whose name is given as the second argument. The first argument
-is the tag to use to do the lookup.
+var(style) whose name is given as the second argument. The first argument
+is the var(tag) to use to do the lookup.
 
-The style name should consist of multiple parts separated with
+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(fiels)tt(=)var(pattern)'. The first argument without a equal sign 
+`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.
 
@@ -2419,7 +2436,7 @@ in the `var(field)tt(=)var(pattern)' match the respective fields in
 the strings from the style value are generated as possible matches.
 
 If no style with the given name is defined for the given tag but a
-function named with the name of the requestd field preceded by an
+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.
@@ -2427,7 +2444,7 @@ style match all the patterns given as 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).
+be given after the fieldname, separated from it by a colon.
 
 All arguments after the requested fieldname are given to the
 tt(compadd) used (when generating matches from the style value) and to 
@@ -2458,7 +2475,9 @@ any of the standard completion functions.  You may want to edit some of
 these files.
 )
 item(tt(Builtins))(
-Functions for completing arguments of shell builtin commands.
+Functions for completing arguments of shell builtin commands and
+utility functions for this (which are also used by functions from the
+tt(User) directory).
 )
 item(tt(User))(
 Functions for completing arguments of external commands and suites of