1 files changed, 93 insertions, 1 deletions
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 7d7e688b0..0a626f4e1 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -186,6 +186,18 @@ normally be shown only if there are at least two matches in the
 list. Setting tt(force_list) to an non-empty string makes the list be
 shown even if there is only one match.
 )
+item(tt(list_max))(
+Initially this is set to the value of the tt(LISTMAX) parameter.
+Completion widgets may set it to any other numeric value and the value 
+stored at when the widget finishes will be used in the same way the
+value of tt(LISTMAX) is used.
+)
+item(tt(last_prompt))(
+If this is set to an non-empty string, the completion code will move
+the cursor back to the previous prompt after the list of completions
+has been displayed. Initially this is set depending on the setting of
+the tt(ALWAYS_LAST_PROMPT) option.
+)
 item(tt(insert))(
 This will be unset by the completon code if the contents of the
 command line will not be changed. It is set to tt(unambiguous),
@@ -193,6 +205,62 @@ tt(menu), or tt(automenu) if a common unambiguous string will be
 inserted or if the first match will be inserted and menu completion
 will be started (due to tt(MENU_COMPLETE) or tt(AUTO_MENU) being set), 
 respectively.
+
+On exit it may be set to any of the values above with the obvious
+result or to a number or a string of the form
+`var(group):var(match)'. If it is set to a number the match whose
+number is given will be inserted in the command line. A string like
+`tt(2:4)' specifies which match from which group should be
+inserted. In this example the fourth match of the second group is
+inserted. All groups and matches are number from one upwards. In the
+value of this key, negative numbers count backward from the last match 
+or group (with `tt(-1)' selecting the last match or group) and values
+out of the range from one to the number of matches or groups are
+wrapped around (so that a value of zero selects the last match and a
+value equal to the number of matches or groups plus one selects the
+first one).
+)
+item(tt(to_end))(
+On entry to the completion widget this is set to tt(single) if the
+cursor would be moved to the end of the word only if completion
+generated only one match and that is inserted into the line. Depending 
+on the original position of the cursor and the setting of the option
+tt(ALWAYS_TO_END) this may also be set to the string tt(match) if the
+cursor would be moved to the end if a whole match would be inserted
+(either if there is only one match or if menucompletion is used).
+
+The value of this key after the completion widget exits will be used
+to determin when the cursor will be moved to the end of the string
+inserted into the line. If it is unset or set to the empty string, the 
+cursor will never be moved to the end. If it is set to tt(single), it
+will be moved to the end only if completion generated only one
+match. A value of tt(always) says to move the cursor always to the end 
+(even with normal completion when an unambiguous string is inserted),
+and any other value says to move the cursor to the end when a full
+match is inserted (a single match or the first match when using
+menucompletion).
+)
+item(tt(old_list))(
+This is set to tt(yes) if there is still a valid list of completions
+from a previous completion at the time the widget is invoked. Such a
+list exists if it was generated by the previous key press. If the list 
+is also shown on the screen, the value of this key is tt(shown).
+
+After the widget has exited the value of this key is only used if it
+was set to tt(keep). In this case, the completion code will continue
+to use this old list. If the widget generated new matches, they will
+not be used.
+)
+item(tt(old_insert))(
+On entry to the widget this will be set to the number of the match of
+an old list of completions that is currently inserted in the command
+line. If no match has been inserted, this is unset.
+
+As with tt(old_list), the value of this key will only be used if it is 
+the string tt(keep). If it was set to this value by the widget and
+there was an old match inserted in the line, this match will be kept
+and if the value of the tt(insert) key says that another match should
+be inserted, this will be inserted after the old one.
 )
 item(tt(exact))(
 This is set to tt(accept) if an exact match would be accepted by the
@@ -268,7 +336,8 @@ xitem([ tt(-i) var(ignored-prefix) ] [ tt(-I) var(ignored-suffix) ])
 xitem([ tt(-W) var(file-prefix) ])
 xitem([ tt(-J) var(name) ] [ tt(-V) var(name) ] [ tt(-X) var(explanation) ])
 xitem([ tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ])
-item([ tt(-M) var(match-spec) ] [ tt(--) ] [ var(words) ... ])(
+xitem([ tt(-M) var(match-spec) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ])
+item([ tt(--) ] [ var(words) ... ])(
 
 This builtin command can be used to add matches and directly control
 all the information the completion code stores with each possible
@@ -437,6 +506,23 @@ Note that with tt(compadd) this option does not automatically turn on
 menu completion if tt(AUTO_LIST) is set as the same options for the
 tt(compctl) and tt(compgen) builtin command do.
 )
+item(tt(-O) var(array))(
+If this option is given, the var(words) are em(not) added to the set of
+possible completions. Instead, matching is done as usual and all
+var(words) given as arguments that are matched will be stored in the
+array parameter whose name is given as var(array).
+)
+item(tt(-A) var(array))(
+Like the tt(-O) option this keeps the var(words) from being stored as
+possible completions. The matching words are instead stored in the array
+parameter given as var(array). In difference to the tt(-O) option this
+does not store the unchanged var(words) given as arguments, but instead
+the strings the completion code generated while matching. For example,
+with a matching specification of `tt(-M "L:|no=")', the string `tt(nof)'
+on the line and the string `tt(foo)' as one of the var(words), this option
+will make the string `tt(nofoo)' be stored in the array, whereas the tt(-O)
+option stores the `tt(foo)' originally given.
+)
 item(tt(-), tt(--))(
 This flag ends the list of flags and options. All arguments after it
 will be taken as the words to use as matches even if they begin with
@@ -596,3 +682,9 @@ tt(complete-history LPAR()RPAR() { compgen -H 0 '' })))
 
 In this the function will complete words from the history matching the 
 current word.
+
+For a description of the example completion system from the
+distributions, see
+ifzman(zmanref(zshcompsys))\
+ifnzman(noderef(Completion System))\
+.