[PATCH] docs: clarify `_arguments -A` behaviour

[dana <dana@xxxxxxx>]

i realised that after all this time i didn't *really* know what the
behaviour of `_arguments -A` was. i knew when to use it, but the
explanation didn't help me understand the actual mechanics or benefit
of the pattern argument

i hope this is clearer

dana


diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 06b08cc72..b1c4d30ad 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -3743,11 +3743,13 @@ argument, and the `tt(-)tt(-)' is considered to be neither.
 )
 item(tt(-A) var(pat))(
 Do not complete options after the first non-option
-argument on the line.  var(pat) is a pattern matching
-all strings which are not to be taken as arguments.  For example, to make
-tt(_arguments) stop completing options after the first normal argument, but
-ignoring all strings starting with a hyphen even if they are not described
-by one of the var(optspec)s, the form is `tt(-A "-*")'.
+argument on the line.  Any such argument that matches var(pat)
+is ignored (as if it didn't appear on the line) until another
+non-option argument is encountered that doesn't match it.  This
+is most often used in the form `tt(-A "-*")' to prevent the
+function from treating an option not described by one of the
+var(optspecs) as a non-option argument and refusing to complete
+further options, which might be annoying.
 )
 item(tt(-O) var(name))(
 Pass the elements of the array var(name) as arguments to functions called to