1 files changed, 36 insertions, 17 deletions
diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
index c488f8b02..e72a2b712 100644
--- a/Doc/Zsh/mod_zutil.yo
+++ b/Doc/Zsh/mod_zutil.yo
@@ -111,28 +111,47 @@ The resulting strings are stored in the var(array).
 item(tt(zregexparse))(
 This implements the internals of the `tt(_regex_arguments)'.
 )
-item(tt(zparseopts) [ tt(-D) ] var(specs))(
-This builtin can be used to parse the positional arguments and put
-options found in them into separate arrays. Each var(spec) describes
-one option which is given as its first character. If the second
-character is either `tt(:)' or `tt(+)', the option takes an argument
-(either directly following the option in the same word or in the next
-word). After the option character or the `tt(:)' or `tt(+)' follows
-the name of the array in which the option should be stored. The only
-difference between the form with a `t(:)' and the one with a `tt(+)'
-is that in the first case the option and its argument will be put in
-the array only once (later occurrences overwriting earlier ones),
-whereas with `tt(+)' all occurrences are moved to the array.
+item(tt(zparseopts) [ tt(-D) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] var(specs))(
+This builtin simplifies the parsing of options in the positional
+parameters. Each var(spec) describes one option and should be of the
+form `var(name)[tt(+)][tt(:)[tt(:)][tt(-)]][tt(=)var(array)]'. The var(name)
+is the name of the option (without the leading `tt(-)'). If only that
+is given, the option takes no argument and if it is found in the
+positional parameters it will be placed in the var(array) given with
+the tt(-a) option. If the optional `tt(=)var(array)' is given, it will 
+be put into that array instead. If one or two colons are given, the
+option takes an argument. With one colon, this argument is mandatory
+and with two colons it is optional. The argument will be inserted into 
+the var(array), too. For mandatory arguments it is added as a separate 
+string and for optional arguments it is put into one string together
+with the option name unless the `tt(-)' option is given. In this case
+the argument will be put into the same word even for mandatory
+arguments (note that this makes empty strings as arguments
+indistinguishable). Finally, if the `tt(+)' is given and the option
+appears more than once in the positional parameters, it will be
+inserted more than once in the var(array), too. Without the `tt(+)'
+the option will be inserted only once in the var(array) with arguments 
+of later options overwriting earlier once. If any of the special
+character needs to appear in the option name it must be preceded by a
+backslash.
+
+If the tt(-A) option is given, the options and their values will also
+be put into an associative array with the option names as keys and the 
+arguments (if any) as the values. Note that it is an error to give
+var(specs) without a `tt(=)var(array)' and not use either the tt(-a)
+or tt(-A) option.
 
 If the tt(-D) option is given, all options found are removed from the
-positional parameters leaving only those strings that did not match
-any of the var(specs).
+positional parameters leaving only the strings from the first one that 
+was not described by any of the var(specs) to the last (note that this 
+is the usual rule used by tt(zparseopts) to find out when to stop
+processing options).
 
-For example, calling `tt(zparseopts afoo b:bar c+bar)' with the
+For example, calling `tt(zparseopts a=foo b:=bar c+:=bar)' with the
 strings `tt(-a)', `tt(-bx)', `tt(-c)', `tt(y)', `tt(-cz)', `tt(baz)'
 and `tt(-cend)' as positional arguments will set the array tt(foo) to
 contain the element `tt(-a)' and the array tt(bar) to the strings
-`tt(-bx)', `tt(-cy)' and `tt(-cz)'. The `tt(baz)' and any strings
-after it will not be used.
+`tt(-b)', `tt(x)', `tt(-c)', `tt(y)', `tt(-c)', and `tt(z)'. The
+`tt(baz)' and all strings after it will not be used.
 )
 enditem()