43602: Clarify behaviour of `compdef -p`

2 files changed, 9 insertions, 1 deletions

diff --git a/ChangeLog b/ChangeLog
index ddcf717cc..b814a1c14 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2018-10-10  dana  <dana@dana.is>
+
+	* 43602: Doc/Zsh/compsys.yo: Clarify behaviour of `compdef -p`
+
 2018-10-10  Peter Stephenson  <p.stephenson@samsung.com>
 
 	* unposted: Test/C03traps.ztst: Another couple of tests for
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 65f596752..a5a9e5b5d 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -489,7 +489,11 @@ The parameter tt($_compskip) may be set by any function defined for a
 pattern context.  If it is set to a value containing the substring
 `tt(patterns)' none of the pattern-functions will be called; if it is
 set to a value containing the substring `tt(all)', no other function
-will be called.
+will be called.  Setting tt($_compskip) in this manner is of particular
+utility when using the tt(-p) option, as otherwise the dispatcher will
+move on to additional functions (likely the default one) after calling
+the pattern-context one, which can mangle the display of completion
+possibilities if not handled properly.
 
 The form with tt(-k) defines a widget with the same name as the var(function)
 that will be called for each of the var(key-sequence)s; this is like the