2 files changed, 62 insertions, 23 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 11837cb49..0b1e9fda3 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -901,6 +901,18 @@ the description for this argument.  Depending on personal preferences,
 it may be useful to set this style to something like `tt(specify: %d)'. 
 Note that this may not work for some commands.
 )
+kindex(avoid-completer, completion style)
+item(tt(avoid-completer))(
+This is used by the tt(_all_matches) completer to decide if the string 
+consisting of all matches should be added to the list currently being
+generated.  Its value is a list of names of completers.  If any of
+these is the name of the completer that generated the matches in this
+completion, the string will not be added.
+
+The default value for this style is `tt(_expand _old_list _correct
+_approximate)', i.e. it contains the completers for which a string
+with all matches will almost never be wanted.
+)
 kindex(cache-path, completion style)
 item(tt(cache-path))(
 This style defines the path where any cache files containing dumped
@@ -966,14 +978,6 @@ i.e. normally only completion will be done, first using the
 tt(ignored-patterns) style and the tt($fignore) array and then without 
 ignoring matches.
 )
-kindex(completions, completion style)
-item(tt(completions))(
-This style is used by the tt(_expand) completer function. If it is set 
-to `true', the completer will not generate expansions, but instead the
-completions will be generated as normal and all of them will be
-inserted into the command line.  This style is most useful when set
-only for very specific completion contexts.
-)
 kindex(condition, completion style)
 item(tt(condition))(
 This style is used by the tt(_list) completer function to decide if
@@ -1159,7 +1163,7 @@ ifnzman(noderef(The zsh/zutil Module))\
 )
 kindex(glob, completion style)
 item(tt(glob))(
-Like tt(completions), this is used by the tt(_expand) completer.  If
+This is used by the tt(_expand) completer.  If
 it is set to `true' (the default), globbing will be attempted on the
 words resulting from substitution (see the tt(substitute) style) or
 the original string from the line.
@@ -1650,6 +1654,15 @@ first attempt.  By using the tt(_oldlist) completer and setting this style
 to tt(_match), the list of matches generated on the first attempt will be
 used again.
 )
+kindex(old-matches, completion style)
+item(tt(old-matches))(
+This is used by the tt(_all_matches) completer to decide if an old
+list of matches should be used if one exists.  It may be set to one of 
+the `true' values or to the string `tt(only)' to use such a list.  If
+it is set to `tt(only)', tt(_all_matches) will only use an old list
+and won't have any effect on the list of matches currently being
+generated.
+)
 kindex(old-menu, completion style)
 item(tt(old-menu))(
 This is used by the tt(_oldlist) completer.  It controls how menu
@@ -2109,6 +2122,34 @@ may write their own):
 
 cindex(completion system, completers)
 startitem()
+findex(_all_matches)
+item(tt(_all_matches))(
+This completer can be used to add a string consisting of all other
+matches.  To ensure, that this string is always added, this completer
+has to be used as the first completer in the list.  The
+tt(avoid-completer) style is used to decide if the string should be
+added.  This will only be done if the matches were generated by a
+completer not named by one of the values of the style.
+
+This function also uses the style tt(old-matches).  If it is set to
+`true' or to the string `tt(only)' and there is a list of matches from 
+a previous completion, those matches will be inserted in the command
+line.  If it is set to the the string `tt(only)', it will only insert
+an old list and won't add the string for all matches of the list
+currently being generated.
+
+With the tt(old-matches) style set, this completer should probably not 
+be called unconditionally.  Instead one could use the tt(-e) option of 
+the tt(zstyle) builtin command to add a condition to the tt(completer) 
+or to the tt(old-matches) style.  Alternatively, one could use the
+tt(_generic) function to bind tt(_all_matches) to a separate key
+binding, for example:
+
+example(zle -C all-matches complete-word _generic
+bindkey '^Xa' all-matches
+zstyle ':completion:all-matches:*' old-matches only
+zstyle ':completion:all-matches:*' completer _all_matches)
+)
 findex(_approximate)
 item(tt(_approximate))(
 This completer function uses the tt(_complete) completer to generate
@@ -2312,14 +2353,9 @@ string from the line.
 Which kind of expansion is tried is controlled by the tt(substitute),
 tt(glob) and tt(subst-globs-only) styles.
 
-There is another style, tt(completions), which causes tt(_expand) to
-unconditionally insert all em(completions) generated for the current
-word (even if the word is empty).
-
 When tt(_expand) is called as a function, the different modes may be
-selected with options.  The tt(-c) corresponds to the tt(completions)
-style, tt(-s) to tt(substitute), tt(-g) to tt(glob) and tt(-o) to
-tt(subst-globs-only).
+selected with options.  The tt(-s) to tt(substitute), tt(-g) to
+tt(glob) and tt(-o) to tt(subst-globs-only).
 )
 findex(_history)
 item(tt(_history))(
@@ -2495,12 +2531,6 @@ 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 var(function) field is set to `tt(expand-word)'.
-
-The tt(completions) style is also tested in the resulting context.  When
-it is true, the list of functions from the tt(completer) style is shifted
-to remove any that would be called ahead of tt(_expand).  If tt(_expand)
-does not appear in the tt(completer) style, then only the two completers
-tt(_expand) and tt(_complete) are used (in that order).
 )
 findex(_generic)
 item(tt(_generic))(
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 5747e3d22..e793085af 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -418,7 +418,7 @@ sect(Builtin Commands)
 startitem()
 findex(compadd)
 cindex(completion widgets, adding specified matches)
-xitem(tt(compadd) [ tt(-akqQfenUl12) ] [ tt(-F) var(array) ])
+xitem(tt(compadd) [ tt(-akqQfenUl12C) ] [ tt(-F) var(array) ])
 xitem([ tt(-P) var(prefix) ] [ tt(-S) var(suffix) ])
 xitem([ tt(-p) var(hidden-prefix) ] [ tt(-s) var(hidden-suffix) ])
 xitem([ tt(-i) var(ignored-prefix) ] [ tt(-I) var(ignored-suffix) ])
@@ -640,6 +640,15 @@ in turn matches what is on the line.  If the var(n)'th var(word) does not
 match, the var(n)'th element of the var(array) is removed.  Elements
 for which the corresponding var(word) is matched are retained.
 )
+item(tt(-C))(
+This option adds a special match which expands to all other metches
+when inserted into the line, even those that are added after this
+option is used.  Together with the tt(-d) option it is possible to
+specify a string that should be displayed in the list for this special 
+match.  If no string is given, it will be shown as a string containing 
+the strings that would be inserted for the other matches, truncated to 
+the width of the screen.
+)
 xitem(tt(-))
 item(tt(-)tt(-))(
 This flag ends the list of flags and options. All arguments after it