PATCH: small doc patch

[Sven Wischnowsky <wischnow@xxxxxxxxxxxxxxxxxxxxxxx>]

I forgot to mention in the docs that `_arguments' and `_values' (and
`_alternative', but that is not yet documented) now support the option 
`-O name'. The `name' is take as the name of an array and its elements 
are given as arguments to `compadd' and the action(s) executed. This
allows one to give common options to them (e.g. a `-M ...' that should 
be used everywhere).

I used this in functions like `_command_names' and with it functions
like this one that otherwise already allowed the use of `_alternative' 
became very simple. In fact, in many cases where it was possible to
use `_alternative' the code became much simpler, smaller, cleaner --
and much more powerful at the same time. May be a good sign, that.

Btw, turning the config keys into styles will be quite easy, too (even 
with the the simple functions we have now). In most cases it will be
enough to replace uses of `$compconfig' with calls to `_style'. There
is only that type-stuff. But when this is settled we can even get rid
of uglynesses like these colon-separated lists we have now (e.g. 
`completer' will be turned into an `array-style'). I'm planning to
change `componf' (before it is finally removed) to internally use
`compstyle' and print a warning message and the equivalent `compstyle' 
calls so that the transition for you will become easy. Ok?

One other thing I forgot to mention is that I tried to use as few
different tag-names as possible (hm, maybe I said that already? I'm
too lazy to look now...). In some cases I may have failed to do so. In 
some cases I may also have used bad context names. Or too many context 
names (did I say that the first argument of `_tags' and `_alternative' 
may be a list of context names separated by colons; no I think I
didn't say that). Or too many calls to `_tags' -- when functions call
other functions there may be more than one call for a context. In some 
cases we may want this (because only the calling function knows the
real context name), in other we probably don't want it. Or maybe we
want to remove this multiple-context thing altogether and make it a
calling convention that every completion function gets the context
name as the first argument. Functions like `_arguments' will then use
the one they have build because they know better. (Hm, this actually
sounds like a good idea. Or maybe we make this with a parameter made
local in `_main_complete' and functions that change the context. Hm,
that sounds even better. Damn, why didn't I think of that before...)

(Whew. That, the yet-unchanged functions, the docs, the C-code, lots
of testing, the context stuff, this and that... Uff. Forgive me, I'm
rather exhausted at the moment. Weekend.)

Bye
 Sven

diff -u olddoc/Zsh/compsys.yo Doc/Zsh/compsys.yo
--- olddoc/Zsh/compsys.yo	Fri Nov 12 15:56:16 1999
+++ Doc/Zsh/compsys.yo	Fri Nov 12 16:19:30 1999
@@ -938,6 +938,12 @@
 name. This allows the use of the `tt(-s)' option to describe
 single-letter options together with such long option names.
 
+Another option supported is `tt(-O) var(name)'. The var(name) will be
+taken as the name of an array and its elements will be given to
+functions called to generate matches when executing the
+var(actions). For example, this allows one to give options for the
+tt(compadd) builtin that should be used.
+
 Also, the tt(-M) option followed by a string may be given before the
 first description. The string will be used as the match specification
 when completing option names and values instead of the default
@@ -1034,11 +1040,18 @@
 )
 item(tt(_values))(
 This is used to complete values (strings) and their arguments or
-lists of such values. If the first argument is the option `tt(-s)',
-the second argument is used as the character that separates multiple
-values.
+lists of such values.
+
+If the first argument is the option `tt(-O) var(name)', this will be
+used in the same way as by the tt(_arguments) function. I.e. the
+elements of the var(name) array will be given to calls to tt(compadd)
+and when executing an action.
+
+Otherwise, if the first argument (or the first argument after the
+`tt(-O) var(name)' option if that is used) is the option `tt(-s)', the
+second argument is used as the character that separates multiple values.
 
-The first argument (after the option and separator character if they
+The first argument (after the options and separator character if they
 are given) is used as a string to print as a description before
 listing the values.
 

--
Sven Wischnowsky                         wischnow@xxxxxxxxxxxxxxxxxxxxxxx