zsh-workers/8227

3 files changed, 39 insertions, 10 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 8c393620e..82265ffd0 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -318,6 +318,12 @@ 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.
 
+Immediately before returning the tt(_main_complete) function calls all
+functions whose names are given in the tt(comppostfuncs) array and
+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 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
@@ -1718,10 +1724,14 @@ common prefix different from the word on the line or if there is such
 a common prefix, respectively. The sequence `tt(%c)' 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 and `tt(%a)' is replaced by an empty string if
+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.
+-alt-)' if the matches are in the alternate set, and if the
+tt(incremental_list) key (see below) 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.
 )
 item(tt(incremental_stop))(
 This gives a pattern matching (keyboard-) keys which will cause
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 6681e7b15..e0ab37fb5 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -184,10 +184,13 @@ When completing inside quotes, this contains the quotation character
 is unset.
 )
 item(tt(nmatches))(
-The number of matches generated and accepted by the completion code so far.
+The number of matches generated and accepted by the completion code so
+far, excluding those matches that are only accepted by ignoring the
+tt(fignore) parameter and the tt(-a) option of the tt(compadd) builtin 
+command.
 )
-item(tt(normal_nmatches))(
-Like tt(nmatches), but counts only matches in the normal set. I.e. file
+item(tt(alternate_nmatches))(
+Like tt(nmatches), but counts only matches in the alternate set. I.e. file
 names with one of the suffixes from the tt(fignore) array and matches
 put into the alternate set using the tt(-a) option of the tt(compadd)
 builtin command (see below) are not counted.
@@ -216,11 +219,14 @@ sets it to any other string, they will not be restored.
 )
 item(tt(list))(
 This controls whether or how the list of matches will be displayed.  If it
-is unset or empty they will never be listed; if is set to tt(list), they
-will always be listed; if tt(autolist) or tt(ambiguous), they will be
-listed when the tt(AUTO_LIST) or tt(LIST_AMBIGUOUS) options respectively
-would normally cause them to be.  It will be set appropriately on entry to
-a completion widget and may be changed there.
+is unset or empty they will never be listed; if its value begins with
+tt(list), they will always be listed; if it begins with tt(autolist)
+or tt(ambiguous), they will be listed when the tt(AUTO_LIST) or
+tt(LIST_AMBIGUOUS) options respectively would normally cause them to
+be.  Finally, if the value contains the string tt(explanations), only
+the explanation strings, if any, will be listed. It will be set
+appropriately on entry to a completion widget and may be changed
+there.
 )
 item(tt(force_list))(
 If the value for the tt(list) key is tt(autolist) or tt(ambiguous), the list will
@@ -233,6 +239,13 @@ Initially this is set to the value of the tt(LISTMAX) parameter.
 It may be set to any other numeric value; when the widget exits this value
 will be used in the same way as the value of tt(LISTMAX).
 )
+item(tt(list_lines))(
+This gives the number of lines that are needed to display the full
+list of completions. Note that to calculate the total number of lines
+to display you need to add the number of lines needed for the command
+line to this value, this is available as the value of the tt(BLINES)
+special parameter.
+)
 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
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index e04737da9..86de87fff 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -141,6 +141,12 @@ The part of the buffer that lies to the right of the cursor position.
 If it is assigned to, only that part of the buffer is replaced, and the
 cursor remains between the old tt($LBUFFER) and the new tt($RBUFFER).
 )
+vindex(BLINES)
+item(tt(BLINES))(
+The number of screen lines needed for the edit buffer currently
+displayed on screen (i.e. without any changes to the preceding
+parameters done after the last redisplay).
+)
 vindex(PREBUFFER)
 item(tt(PREBUFFER) (scalar))(
 In a multi-line input at the secondary prompt, this read-only parameter