54665: new utility function for mixing in extra values

1 files changed, 18 insertions, 0 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 9d20ea116..e08ca30ec 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -4911,6 +4911,24 @@ Finally, the tt(_path_files) function  uses the styles tt(expand),
 tt(ambiguous), tt(special-dirs), tt(list-suffixes) and tt(file-sort)
 described above.
 )
+findex(_phony)
+item(tt(_phony) ... [ var(word) ... ] [ [ tt(--) ] var(function) [ tt(-) ] ... ])(
+This function allows extra matches to be mixed in with the matches
+generated by a function.  Sometimes a command accepts special values like
+`tt(any)', `tt(all)', or `tt(none)' to be specified but the applicable
+completion function only generates real values.
+
+tt(_phony) takes all the same arguments as tt(compadd).  With the exception
+of `tt(-a)', `tt(-d)', `tt(-k)' and `tt(-l)', these are passed on to the
+following function.  Unless there is only one word, a `tt(--)' separator is
+needed to indicate where the words finish and the function begins.  You can
+also omit the function in which case an empty input won't match the phony
+values, allowing descriptions to be displayed. This is useful where real
+values can't be generated and tt(_message -e) would otherwise be used.
+
+To ensure that real and phony matches are grouped together, any options
+defining the match group should be passed to tt(_phony).
+)
 findex(_pick_variant)
 redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ @ @ @ @ @ ))ifnztexi(              )))
 xitem(tt(_pick_variant )[ tt(-b) var(builtin-label) ] [ tt(-c) var(command) ] [ tt(-r) var(name) ])