1 files changed, 79 insertions, 2 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 2de4e4bd7..477fbdc77 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -17,6 +17,7 @@ menu(Initialization)
 menu(Control Functions)
 menu(Completion Functions)
 menu(Completion Directories)
+menu(Bindable Commands)
 endmenu()
 
 texinode(Initialization)(Control Functions)()(Completion System)
@@ -248,6 +249,11 @@ of the completer functions to decide if other completers should be
 called. If the return value is zero, no other completers are tried and the
 tt(_main_complete) function returns.
 
+The widget function tt(_main_complete) also uses the configuration key 
+tt(last_prompt). If this is set to tt(always), 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):
 
@@ -578,7 +584,10 @@ it is set to tt(never), this will not be done (the behaviour without the
 tt(_oldlist) completer).  If it is unset, or any other value, then the
 existing list of completions will be displayed if it is not already;
 otherwise, the standard completion list will be generated:  this is the
-default behaviour of tt(_oldlist).
+default behaviour of tt(_oldlist). However, if there is an old list
+and this key contains the name of the completer function that
+generated the list, then the old list will be used even if it was
+generated by a widget which does not listing.
 
 For example, suppose you type tt(^Xc) to use the tt(_correct_word)
 widget, which generates a list of corrections for the word under the
@@ -586,6 +595,14 @@ cursor.  Usually, typing tt(^D) would generate a standard list of
 completions for the word on the command line, and show that.  With
 tt(_oldlist), it will instead show the list of corrections already
 generated.
+
+As another example consider the tt(_match) completer: with the
+tt(match_insert) key set to tt(unambig) it inserts only an
+unambiguous prefix string if there is any. But since this may remove
+parts of the original pattern, attempting completion again may result
+in more matches than on the first attempt. But by using the
+tt(_oldlist) completer and setting this key to tt(_match), the list of 
+matches generated on the first attempt will be used again.
 )
 item(tt(oldlist_menu))(
 Controls how menu completion behaves when a completion has already been
@@ -769,7 +786,7 @@ on words starting with two hyphens.
 )
 enditem()
 
-texinode(Completion Directories)()(Completion Functions)(Completion System)
+texinode(Completion Directories)(Bindable Commands)(Completion Functions)(Completion System)
 sect(Completion Directories)
 
 In the source distribution, the files are contained in various
@@ -802,3 +819,63 @@ Functions which implement special types of completion to be bound to
 keystrokes rather than called by context.
 )
 enditem()
+
+texinode(Bindable Commands)()(Completion Directories)(Completion System)
+sect(Bindable Commands)
+
+In addition to the context-dependent completions provided, which are
+expected to work in an intuitively obvious way, there are a few widgets
+implementing special behaviour which can be bound separately to keys.  The
+following is a list of these and their default bindings.
+
+startitem()
+item(tt(_correct_filename (^XC)))(
+Correct the filename path at the cursor position.  Allows up to six errors
+in the name.  Can also be correctly called with an argument to correct
+a filepath, independently of zle.
+)
+item(tt(_correct_word) (^Xc))(
+Performs correction of the current argument using the usual contextual
+completions as possible choices.
+)
+item(tt(_expand_word (^Xe)))(
+Performs expansion on the current word:  equivalent to the standard
+tt(expand-word) command, but using all the `tt(expand_*)' configuration
+keys described previously.  In addition, each such key can be overridden by
+a key starting with the string `tt(expandword_)'; for example, the
+tt(expandword_substitute) key if defined overrides the
+tt(expand_substitute) key.
+)
+item(tt(_history_complete_word) (\e/))(
+Complete words from the shell's command history.
+)
+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.
+)
+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
+be a set of words beginning `tt(_)', for example `tt(_files -/)', in which
+case the function with any arguments will be called to generate the
+completions.  Unambiguous parts of the function name will be completed
+automatically (normal completion is not available at this point) until a
+space is typed.
+
+Otherwise, any other string, for example `tt(-b)', will be passed as
+arguments to tt(compgen) and should hence be a set of flags specifying the
+type of completion.
+
+A very restricted set of editing commands is available when reading the
+string:  `tt(DEL)' and `tt(^H)' delete the last character; `tt(^U)' deletes
+the line, and `tt(^C)' and `tt(^G)' abort the function, while `tt(RET)'
+accepts the completion.  Note the string is used verbatim as a command
+line, so arguments must be quoted in accordance with standard shell rules.
+
+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.
+)
+enditem()