PATCH: manual, was Re: Reading completion manual

[Sven Wischnowsky <wischnow@xxxxxxxxxxxxxxxxxxxxxxx>]

Here is a patch for the docs that hopefully make things clearer.


Bye
 Sven

diff -u od/Zsh/compctl.yo Doc/Zsh/compctl.yo
--- od/Zsh/compctl.yo	Tue Mar  2 14:33:21 1999
+++ Doc/Zsh/compctl.yo	Wed Mar  3 10:42:09 1999
@@ -434,9 +434,19 @@
 )
 item(tt(-X) var(explanation))(
 Print var(explanation) when trying completion on the current set of
-options. A `tt(%n)' in this string is replaced by the number of matches.
+options. A `tt(%n)' in this string is replaced by the number of
+matches that were added for this explanation string.
 The explanation only appears if completion was tried and there was
-no unique match, or when listing completions.
+no unique match, or when listing completions. Explanation strings 
+will be listed together with the matches of the group specified
+together with the tt(-X) option (using the tt(-J) or tt(-V)
+option). If the same explanation string is given to multiple tt(-X)
+options, the string appears only once (for each group) and the number
+of matches shown for the `tt(%n)' is the total number of all matches
+for each of these uses. In any case, the explanation string will only
+be shown if there was at least one match added for the explanation
+string.
+
 The sequences tt(%B), tt(%b), tt(%S), tt(%s), tt(%U), and tt(%u) specify
 output attributes (bold, standout, and underline) as in prompts.
 )
diff -u od/Zsh/compwid.yo Doc/Zsh/compwid.yo
--- od/Zsh/compwid.yo	Tue Mar  2 14:33:22 1999
+++ Doc/Zsh/compwid.yo	Wed Mar  3 10:53:02 1999
@@ -241,6 +241,24 @@
 all the information the completion code stores with each possible
 match.
 
+The completion code breaks the string to complete into six fields in
+the order: var(<ipre><apre><hpre><word><hsuf><asuf>). The first field
+is an ignored prefix taken from the line, the contents of the
+tt(IPREFIX) parameter plus the string given with the tt(-i)
+option. With the tt(-U) option given, only the string from the tt(-i)
+option is used. The field var(<apre>) is a optional prefix string that 
+should automatically be added by the completion code, this is what can 
+be gievn with the tt(-P) option. The var(<hpre>) field is a string
+that is considered part of the match but that should not be shown when 
+listing completions, it is given with the tt(-p) option. E.g. for
+functions that do filename generation, one might want to use this for
+a common path prefix. var(<word>) is the part of the match that should 
+appear in the list of completions, one of the tt(words) given at the
+end. The field var(<hsuf>) is like var(<hpre>) but gives a suffix that 
+should be matched but will not be listed. Finally, var(<asuf>) is the
+suffix given with tt(-S) that should automatically be added by the
+completion code.
+
 The supported flags are:
 
 startitem()
@@ -254,7 +272,9 @@
 )
 item(tt(-p) var(hidden-prefix))(
 This gives a string that should be inserted in the line before the
-match but that should not appear in the list of matches.
+match but that should not appear in the list of matches. Unless the
+tt(-U) option is given, the string on the line has to match this
+string.
 )
 item(tt(-s) var(hidden-suffix))(
 Like `tt(-p)', but gives a string to insert after the match.
@@ -383,7 +403,7 @@
 item(tt(compcall) [ tt(-TD) ])(
 
 This allows one to use completion definitions given with the
-tt(compctl) builtin from within completion widgets. It makes
+tt(compctl) builtin from within completion widgets. It makes the
 completion code complete the current word according to the
 tt(compctl)s defined. Normally only tt(compctl)s given for specific
 commands are used. To make the code use the completion flags given to
@@ -391,6 +411,10 @@
 tt(compctl). Likewise, the tt(-D) flag to tt(compcall) makes the
 default completion flags given to tt(compctl) with the tt(-D) option
 be used.
+
+The return value can be used to test if a matching tt(compctl)
+definition was found. It is non-zero if a tt(compctl) was found and
+zero otherwise.
 )
 enditem()
 

--
Sven Wischnowsky                         wischnow@xxxxxxxxxxxxxxxxxxxxxxx