zsh-workers/7827

2 files changed, 28 insertions, 28 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 8025c7ad2..2f228d3ff 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -583,34 +583,17 @@ preference to tt(description_format). The latter is used only if the
 former is unset or set to the empty string.
 )
 item(tt(_display))(
-This function generates a display list usable for the `tt(-y)' option
-of tt(compadd) and tt(compgen). For this it takes its second argument
-as an array of possible matches with descriptions. The array may
-either be given as the name of an array parameter or directly as a
-list of words in parentheses.
-
-Each element of the array should contain a match, optionally followed
-by a colon and the description for this match. With this
-tt(_display) builds a string with one match and its description per
-line. Matches witout descriptions are appended at the end and aligned
-in multiple columns. After that, the first argument is taken as a
-parameter name and the string built is stored in it.
-
-Before the building the list, however, this function first uses
-tt(compadd) to remove all strings from the array that don't match the
-string on the line (so that they don't appear in the list). This means 
-that the special parameters tt(PREFIX) and tt(SUFFIX) have to be set
-up correctly before this function is called. This call to tt(compadd)
-also uses the other arguments given to tt(_display), by directly
-giving them to tt(compadd).
-
-Finally, if the array is given as the name of a parameter, this
-paramete will be changed to include only those strings that match the
-string on the line.
+This function generates a display list usable for the `tt(-d)' option
+of tt(compadd). For this it takes its arguments except the first one
+as possible matches with descriptions. The strings should contain the
+match, optionally followed by a colon and the description for this
+match. From this tt(_display) builds an array with elements containing 
+the matches and their descriptions, where the descriptions are aligned.
+After that, the first argument is taken as a parameter name and the
+array built is stored in it.
 
 The return value of tt(_display) is zero if there was at least one
-matching string and the display string could be built and non-zero
-otherwise.
+match with a description non-zero otherwise.
 )
 item(tt(_multi_parts))(
 This function gets two arguments: a separator character and an
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 6fbd3ca15..2c68e5d64 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -366,11 +366,11 @@ otherwise.
 )
 findex(compadd)
 cindex(completion widgets, adding specified matches)
-xitem(tt(compadd) [ tt(-qQfenUam) ] [ tt(-F) var(array) ])
+xitem(tt(compadd) [ tt(-qQfenUaml) ] [ 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) ])
-xitem([ tt(-W) var(file-prefix) ] [ tt(-y) var(array) ])
+xitem([ tt(-W) var(file-prefix) ] [ tt(-y) var(array) ] [ tt(-d) var(array) ])
 xitem([ tt(-J) var(name) ] [ tt(-V) var(name) ] [ tt(-X) var(explanation) ])
 xitem([ tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ])
 xitem([ tt(-M) var(match-spec) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ])
@@ -436,6 +436,23 @@ is like the tt(-y) option of the tt(compctl) builtin command but the
 var(array) argument may only be the name of an array parameter or a
 literal array in parentheses containing the strings to display.
 )
+item(tt(-d) var(array))(
+This adds per-match display strings. The var(array) should contain one 
+element per var(word) given. The completion code will then display the 
+first element instead of the first var(word), and so on. The
+var(array) may be given as the name of a array parameter or directly
+as a space-separated list of words in parentheses.
+
+If there are fewer display strings than var(words), the leftover
+var(words) will be displayed unchanged and if there are more display
+strings than var(words), the leftover display strings will be silently
+ignored.
+)
+item(tt(-l))(
+This option only has an effect if used together with the tt(-d)
+options. If it is given, the display strings are listed one per line,
+not arrayed in columns.
+)
 item(tt(-J) var(name))(
 As for tt(compctl) and tt(compgen), this gives the name of the group
 of matches the words should be stored in.