trying to improve _expand; new keep-prefix style, add-space gives more control (11815)

1 files changed, 24 insertions, 3 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index d88fbc77b..24ada7446 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -784,10 +784,15 @@ kindex(add-space, completion style)
 item(tt(add-space))(
 This style is used by the tt(_expand) completer.  If it is `true' (the
 default), a space will be inserted after all words resulting from the 
-expansion (except for directory names which get a slash).
+expansion (except for directory names which get a slash).  The value
+may also be the string `tt(file)' to make the completer add a space
+only to names of existing files.  Finally, the `true' values and
+`tt(file)' may be combined with `tt(subst)' to keep the completer from 
+adding a space when the resulting words were generated by expanding a
+substitution such as `tt($LPAR()...RPAR())' and `tt(${...})'.
 
-It is also used by the tt(_prefix) completer to decide if a space should
-be inserted before the suffix.
+It is also used by the tt(_prefix) completer as a simple boolean value
+to decide if a space should be inserted before the suffix.
 )
 kindex(ambiguous, completion style)
 item(tt(ambiguous))(
@@ -1283,6 +1288,22 @@ in the context name to one of tt(correct-)var(num) or
 tt(approximate-)var(num), where var(num) is the number of errors that
 were accepted.
 )
+kindex(keep-prefix, completion style)
+item(tt(keep-prefix))(
+This style is used by the tt(_expand) completer.  If it is `true', the
+completer will try to keep a prefix containing a tilde or parameter
+expansion.  I.e., the string `tt(~/f*)' would be expanded to
+`tt(~/foo)' instead of `tt(/home/user/foo)'.  If the style is set to
+`tt(changed)' (the default), the prefix will only be left unchanged if
+there were other changes between the expanded words and the original
+word from the command line.  Any other value makes the prefix be
+expanded unconditionally.
+
+Note that with one of the `true' values, the tt(_expand) completer
+returns if there is only one expansion and that is, after restoring
+the original prefix, the same as the original word.  This means that
+other completers will be called immediately after tt(_expand).
+)
 kindex(last-prompt, completion style)
 item(tt(last-prompt))(
 This is used to determine if the completion code should try to put the