PATCH: completion docs

[Sven Wischnowsky <wischnow@xxxxxxxxxxxxxxxxxxxxxxx>]

Some fixes and cleanups for the completion docs (compwid and compsys)
and changes to _sort_tags to make it look more like what's in the
docs.


I think there is something wrong with the automatic module-reference
stuff. In the printed version I get stray `+'s after each module
reference and at least at one place (compwid.yo:276) even without a
module reference. So it may be something different altogether, I
haven't investigated any further.


And a question: $_compdir is supposed to be user-visible, shouldn't it 
be called $compdir then?

Bye
 Sven

Index: Completion/Core/_sort_tags
===================================================================
RCS file: /cvsroot/zsh/zsh/Completion/Core/_sort_tags,v
retrieving revision 1.1.1.7
diff -u -r1.1.1.7 _sort_tags
--- Completion/Core/_sort_tags	2000/03/15 10:37:30	1.1.1.7
+++ Completion/Core/_sort_tags	2000/05/02 08:11:30
@@ -1,30 +1,19 @@
 #autoload
 
-comptry arguments values
+comptry -m '(|*-)argument-* (|*-)option-* values'
 comptry options
 
-case "$curcontext" in
 # Some silly examples commented out:
 #
-# *:*:*:*p[bgpn]m:*)           # change the order for file-completion
-#   comptry globbed-files directories
-#   comptry all-files
-#   ;;
-# *:*:*:dvips:-o*)            # automatic context set by _arguments
-#   comptry all-files
-#   return
-#   ;;
+# case "$curcontext" in
 # *:*:*:kill:*)
 #   comptry processes
-#   return                  # this return ensures that we use only processes
+#   return 1                 # this return ensures that we use only processes
 #   ;;
-*)
-  comptry globbed-files
-  comptry directories
-  comptry all-files
-  ;;
-esac
-
-comptry "$@"
+# *:*:*:-command-*)
+#   comptry commands functions
+#   comptry builtins aliases
+#   ;;                       # no return, reserved-words and params after this
+# esac
 
 return 0
Index: Doc/Zsh/compsys.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/compsys.yo,v
retrieving revision 1.28
diff -u -r1.28 compsys.yo
--- Doc/Zsh/compsys.yo	2000/04/30 10:04:29	1.28
+++ Doc/Zsh/compsys.yo	2000/05/02 08:11:31
@@ -155,7 +155,7 @@
 tt(complete-word), tt(delete-char-or-list), tt(expand-or-complete),
 tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete),
 tt(menu-expand-or-complete), or tt(reverse-menu-complete). If the
-tt(complist) module is loaded (see
+tt(zsh/complist) module is loaded (see
 ifzman(zmanref(zshmodules))\
 ifnzman(noderef(The zsh/complist Module))\
 ), the tt(menu-select) widget can be used, too.  Note that the
@@ -170,7 +170,7 @@
 )
 item(tt(#compdef -K) var(widget-name) var(style) var(key-sequences) ...)(
 This is similar to tt(-k), with the same var(style) and var(key-sequences)
-arguments arguments, preceeded by a string giving the name of a widget.
+arguments, preceeded by a string giving the name of a widget.
 In this case only one var(key-sequences) argument may be given, but the
 entire set of three arguments may be repeated with a different set of
 arguments.  In particular, the var(widget-name) must be distinct in each
@@ -185,7 +185,7 @@
 to `tt(^X^C)', and a widget tt(_foo_list) for listing, bound to `tt(^X^D)'.
 )
 item(tt(#autoload) [ var(options) ])(
-This is used for files defining utility function that are not to be
+This is used for files defining utility functions that are not to be
 called directly as completion functions but should be loaded automatically
 when invoked.  Typically they are to be called from within one of the
 completion functions.
@@ -193,7 +193,7 @@
 The var(options) will be given to the tt(autoload) builtin command
 when making the function autoloaded. Note that the tt(-U) flag is
 always used. Most often, this will be tt(+X) to force the function
-being loaded immediately.
+to be loaded immediately.
 )
 enditem()
 
@@ -287,7 +287,7 @@
 For the context a name consisting of multiple fields is built. This
 name is then used to look up styles that can be used to configure the
 completion system. Since it is not possible to build the whole context 
-name in advance, completion function may modify some of the fields and 
+name in advance, completion functions may modify some of the fields and 
 hence the context name used for lookup may vary during the same call
 to the completion system.
 
@@ -331,7 +331,7 @@
 The var(argument), describing which argument we are
 completing. Normally this is either a string of the form
 tt(argument-)var(n), where var(n) is the number of the argument or it
-is a string of the form tt(-)var(opt)tt(-)var(n) when completing the
+is a string of the form tt(option-)var(opt)tt(-)var(n) when completing the
 var(n)'th argument of the option var(opt).
 )
 itemiz(\
@@ -416,8 +416,8 @@
 Note that the order in which styles are em(defined) does not matter; the
 style mechanism uses the most specific possible match for a particular
 style to determine the set of values.  More precisely, strings are
-preferred over patterns (for example, `tt(:completion:complete:foo)' is
-more specific than `tt(:completion:complete:*')), and longer patterns are
+preferred over patterns (for example, `tt(:completion::complete:foo)' is
+more specific than `tt(:completion::complete:*')), and longer patterns are
 preferred over shorter patterns.
 
 As for tags, completion functions can use any number of styles, so
@@ -731,7 +731,7 @@
 kindex(version, completion tag)
 item(tt(version))(
 used by tt(_call) to look up the command to run to determine the installed
-version of various other commands (currently tt(diff) and tt(make)).
+version of various other commands (such as tt(diff) and tt(make)).
 )
 kindex(warnings, completion tag)
 item(tt(warnings))(
@@ -773,11 +773,11 @@
 )
 kindex(add-space, completion style)
 item(tt(add-space))(
-This style is used by the tt(_expand) completer. If it `true' (the
-default), a space will be inserted after all words resulting forom the 
+This style is used by the tt(_expand) completer. If it is `true' (the
+default), a space will be inserted after all words resulting from the 
 expansion (except for directory names which get a slash).
 
-It is also used by tt(_prefix) completers to decide if a space should
+It is also used by the tt(_prefix) completer to decide if a space should
 be inserted before the suffix.
 )
 kindex(ambiguous, completion style)
@@ -830,7 +830,7 @@
 command is called.
 
 For example, the function generating process IDs as matches uses this
-style with the tt(processes) tag to generate the IDs to complete and iwhen
+style with the tt(processes) tag to generate the IDs to complete and when
 the tt(verbose) style is `true', it uses this style with the
 tt(processes-list) tag to generate the strings to display. When using
 different values for these two tags one should ensure that the process
@@ -854,7 +854,7 @@
 will contain the var(name) in the var(completer) field of the
 context. If the var(name) starts with a hyphen, the string for the
 context will be build from the name of the completer function as in
-the first case with the var(name) will be appended to it. For example: 
+the first case with the var(name) appended to it. For example: 
 
 example(zstyle ':completion:*' completer _complete _complete:-foo)
 
@@ -864,7 +864,7 @@
 completer more than once makes only sense when used with the
 `var(functions)tt(:)var(name)' form, because otherwise the context
 name will be the same in all calls to the completer (possible
-exception to this rule are the tt(_ignored) and tt(_prefix)
+exceptions to this rule are the tt(_ignored) and tt(_prefix)
 completers).
 
 Note that the widget functions from the distribution that call the
@@ -883,7 +883,7 @@
 The default value for this style is tt(_complete _ignored),
 i.e. normally only completion will be done, first using the
 tt(ignored-patterns) style and the tt($fignore) array and then without 
-ignoring matches because of these.
+ignoring matches.
 )
 kindex(completions, completion style)
 item(tt(completions))(
@@ -906,7 +906,7 @@
 arithmetical expression. In this case, delaying will be done if the
 expression evaluates to `tt(1)'. For example, with
 
-example(zstyle ':completion:*:list:::' condition 'NUMERIC != 1')
+example(zstyle ':completion:*:list:::' condition '${NUMERIC:-1} != 1')
 
 delaying will be done only if given an explicit numeric argument
 other than `tt(1)'.
@@ -938,7 +938,7 @@
 )
 kindex(disable-stat, completion style)
 item(tt(disable-stat))(
-This is used with the an empty tag by the function completing for the
+This is used with an empty tag by the function completing for the
 tt(cvs) command to decide if the tt(zsh/stat) module should be used to
 generate only names of modified files in the appropriate places.
 )
@@ -1007,9 +1007,9 @@
 
 Another interesting example is to change the default behaviour that
 makes completion first offer files matching the patterns given by the
-calling function, then the directories and then all files. Many people 
+calling function, then directories and then all files. Many people 
 prefer to get both the files matching the given patterns and the
-directories in the first try and all files as the second try. To
+directories in the first try and all files at the second try. To
 achieve this, one could do:
 
 example(zstyle ':completion:*' file-patterns \ 
@@ -1025,7 +1025,7 @@
 uses this style with the tt(files) tag to determine in which order the 
 names should be listed and completed when using menucompletion. The
 value may be one of `tt(size)' to sort them by the size of the file,
-tt(links) to sort them by the number of links to the file,
+`tt(links)' to sort them by the number of links to the file,
 `tt(modification)' (or `tt(time)' or `tt(date)') to sort them by the last
 modification time, `tt(access)' to sort them by the last access time, or
 `tt(inode)' (or `tt(change)') to sort them by the last inode change
@@ -1039,7 +1039,8 @@
 string to display above matches in completion lists. The sequence
 `tt(%d)' in this string will be replaced with a short description of
 what these matches are. This string may also contain the sequences to
-specify output attributes, such as `tt(%b)' and `tt(%s)'.
+specify output attributes, such as `tt(%B)', `tt(%S)' and
+`tt(%{)...tt(%})'.
 
 For the same purpose, this style is also tested with the tags used
 when matches are generated before it is tested for the
@@ -1063,10 +1064,10 @@
 for the tag tt(warnings) so that you can use the tt(list-colors) style 
 for that tag to highlight them.
 
-Here and in all other cases where the completion system uses `tt(%)'
-sequences, the `tt(%)' may be followed by field width specifications as 
-described for the tt(zformat) builtin command from the tt(zutil)
-module, see
+The `tt(%)' for the sequences that are replaced by strings provided by 
+the completion functions like the `tt(%d)' may be followed by field
+width specifications as  described for the tt(zformat) builtin command
+from the tt(zutil) module, see
 ifzman(zmanref(zshmodules))\
 ifnzman(noderef(The zsh/zutil Module))\
 .
@@ -1084,10 +1085,10 @@
 item(tt(group-name))(
 The completion system can put different types of matches in different
 groups which are then displayed separately in the list of possible
-completions. This style can be use to give the names for these groups
+completions. This style can be used to give the names for these groups
 for particular tags. For example, in command position the completion
 system generates names of builtin and external commands, names of
-aliases and shell functions and reserved words as possible
+aliases, shell functions and parameters and reserved words as possible
 completions. To have the external commands and shell functions listed
 separately, one can set:
 
@@ -1232,9 +1233,10 @@
 )
 kindex(list, completion style)
 item(tt(list))(
-This is used by the tt(_history_complete_word) bindable command
-(context `tt(:completion:history-words)') and by the
-tt(incremental-complete-word) widget (context `tt(:completion:incremental)).
+This style is used by the tt(_history_complete_word) bindable command
+(using the context prefix `tt(:completion:history-words)') and by the
+tt(incremental-complete-word) widget (using the context prefix
+`tt(:completion:incremental)).
 
 The tt(_history_complete_word) bindable command uses this style to
 decide if the available matches should be shown.
@@ -1298,7 +1300,7 @@
 last match shown and the total number of matches and `tt(%p)' and
 `tt(%P)' will be replaced by `tt(Top)' when at the beginning of the
 list, `tt(Bottom)' when at the end and the position shown in percent
-of the total length. In each of these cases the form with the
+of the total length otherwise. In each of these cases the form with the
 uppercase letter is replaced by a string of fixed width, padded to the 
 right with spaces. As
 usual, the `tt(%S)', `tt(%s)', `tt(%B)', `tt(%b)', `tt(%U)', `tt(%u)',
@@ -1330,7 +1332,8 @@
 `tt(*)' at the cursor position.  If set to any other non-empty value,
 it will first try to generate matches without inserting the `tt(*)'
 and if that yields no matches, it will try again with the `tt(*)'
-inserted.
+inserted. If it is unset or set to the empty string, matching will
+only be done with the `tt(*)' inserted.
 )
 kindex(matcher, completion style)
 item(tt(matcher))(
@@ -1360,7 +1363,8 @@
 completer, one would do:
 
 example(zstyle ':completion:*' completer _complete _prefix
-zstyle ':completion:*:complete:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}')
+zstyle ':completion:*:complete:*' matcher-list \ 
+       '' 'm:{a-zA-Z}={A-Za-z}')
 
 Note that the tt(completer) style allows to give user-defined names to 
 use in the context instead of the name of the completer.
@@ -1483,7 +1487,7 @@
 )
 kindex(old-menu, completion style)
 item(tt(old-menu))(
-This is used by the tt(_oldlist) completer. Here it controls how menu
+This is used by the tt(_oldlist) completer. It controls how menu
 completion behaves when a completion has already been inserted and the
 user types a standard completion key type such as tt(TAB). The default
 behaviour of tt(_oldlist) is that menu completion always continues
@@ -1496,7 +1500,7 @@
 and menu completion is started in one of the usual ways.  Usually, typing
 tt(TAB) at this point would start trying to complete the line as it now
 appears.  With tt(_oldlist), it instead continues to cycle through the
-list of completions.
+list of corrections.
 )
 kindex(original, completion style)
 item(tt(original))(
@@ -1515,7 +1519,8 @@
 program.  It contains an override for the default package set
 for a given context.  For example,
 
-example(zstyle ':completion:*:complete:dpkg:option--status-1:' packageset avail)
+example(zstyle ':completion:*:complete:dpkg:option--status-1:*' \ 
+               packageset avail)
 
 causes available packages, rather than only installed packages,
 to be completed for `dpkg --status'.
@@ -1596,9 +1601,9 @@
 )
 kindex(remove-all-dups, completion style)
 item(tt(remove-all-dups))(
-The tt(_history_complete_word) bindable command uses this to decide if 
-all duplicate matches should be removed, rather than just consecutive
-duplicates.
+The tt(_history_complete_word) bindable command and the tt(_history)
+completer use this to decide if all duplicate matches should be
+removed, rather than just consecutive duplicates.
 )
 kindex(select-prompt, completion style)
 item(tt(select-prompt))(
@@ -1681,12 +1686,12 @@
 )
 kindex(substitute, completion style)
 item(tt(substitute))(
-If this is unset or set to the empty string, the tt(_expand) completer
-will first try to expand all substitutions in the string (such as
-`tt($LPAR()...RPAR())' and `tt(${...})'). If this is set to an
-non-empty string it should be an expression usable inside a `tt($((...)))'
-arithmetical expression. In this case, expansion of substitutions will
-be done if the expression evaluates to `tt(1)'. For example, with
+This style controls if the tt(_expand) completer will first try to
+expand all substitutions in the string (such as `tt($LPAR()...RPAR())'
+and `tt(${...})'). It should be set to an non-empty string which is
+an expression usable inside a `tt($((...)))' arithmetical
+expression. Expansion of substitutions will be done if the expression
+evaluates to `tt(1)'. For example, with
 
 example(zstyle ':completion:*:expand:::' substitute '${NUMERIC:-1} != 1')
 
@@ -1705,12 +1710,12 @@
 
 For example:
 
-example(zstyle ':completion:*:complete:gunzip:*' tag-order \ 
-    arguments options)
+example(zstyle ':completion:*:complete:-command-:*' tag-order \ 
+    'commands functions')
 
-specifies that completion after tt(gunzip) should offer completions for
-both arguments and options immediately, instead of offering first
-arguments and then option as usual.
+specifies that completion in command position after tt(gunzip) should
+offer only completions for external commands and shell functions
+immediately.
 
 In addition to tag names, each string in the value may take one of the
 following forms:
@@ -1778,7 +1783,7 @@
 line is not empty (this is tested using the tt(PREFIX)
 parameter which is special in completion widgets, see
 ifzman(zshcompwid)\
-ifnzman(the section noderef(Completion System))
+ifnzman(noderef(Completion Widgets))
 for a description of these special parameters).
 )
 enditem()
@@ -1805,14 +1810,14 @@
 of possible matches. If none of the generated matches match the string 
 on the line, the completion system will use the second value of the
 tt(tag-order) style and complete functions names again, but this time
-using so name tt(functions) to look up styles, so that the
+using the name tt(functions) to look up styles, so that the
 tt(ignored-patterns) style is not used and all function names
 are considered.
 
 Of course, this can also be used to split the matches for one tag into 
 different groups. For example:
 
-example(zstyle ':completion:*' tag-order \
+example(zstyle ':completion:*' tag-order \ 
     'options:-long:long\ options
      options:-short:short\ options
      options:-single-letter:single\ letter\ options'
@@ -1832,7 +1837,7 @@
 early in the completion system and hence can't be set for single
 commands nor for more specific contexts. So, to make completion for
 the arguments of the command tt(foo), and only for this command, first
-try normal completion with out any match specification and, if that
+try normal completion without any match specification and, if that
 generates no matches, try again with case-insensitive matching, one
 could do:
 example(zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
@@ -1847,9 +1852,12 @@
 style from the second call to tt(zstyle) in the example is used
 to make completion case-insensitive.
 
-If no style has been defined for a context, the strings `tt(arguments
-values)' and `tt(options)' plus all tags offered by the completion
-function will be used to provide a sensible default behavior.
+If no style has been defined for a context, the strings
+`tt((|*-)argument-* (|*-)option-* values)' and `tt(options)' plus all
+tags offered by the completion function will be used to provide a
+sensible default behavior that makes arguments (normal ones or
+arguments to options) for most commands be completed before option
+names. 
 )
 kindex(use-compctl, completion style)
 item(tt(use-compctl))(
@@ -1933,8 +1941,9 @@
 example(zstyle ':completion:*' completer _complete _correct)
 
 after calling tt(compinit). The default value for this style 
-is `tt(_complete)', i.e. normally only ordinary
-completion is tried. The tt(_main_complete) function uses the return
+is `tt(_complete _ignored)', i.e. normally only ordinary
+completion is tried, first using the tt(ignored-patterns) style and
+then without using it. The tt(_main_complete) function uses the return
 value of the completer functions to decide if other completers should be
 called. If the return value is zero, no other completers are tried and the
 tt(_main_complete) function returns.
@@ -1959,8 +1968,7 @@
 startitem()
 kindex(-equal-, completion context)
 item(tt(-equal-))(
-for completion after an equal sign, other than one occurring in a
-shell-variable assignment.
+for completion of words beginning with an equal sign
 )
 kindex(-tilde-, completion context)
 item(tt(-tilde-))(
@@ -2057,7 +2065,7 @@
 menucompletion allowing you to cycle through these strings.
 
 This completer uses the tags tt(corrections) and tt(original) when
-generating the possible coprrections and the original string. The
+generating the possible corrections and the original string. The
 tt(format) style for the former may contain the additional sequences
 `tt(%e)' and `tt(%o)' which will be replaced by the number of errors
 accepted to generate the corrections and the original string,
@@ -2142,10 +2150,10 @@
 contain the sequence `tt(%o)' which will be replaced by the original
 string from the line.
 
-Which kind of expansion is tried is controlled by the tt(substitute)
-and tt(glob) styles. Note that neither of these has a default value so 
-that they have to be set to make tt(_expand) generate any expansions
-at all.
+Which kind of expansion is tried is controlled by the tt(substitute),
+tt(glob) and tt(subts-globs-only) styles. Note that neither of these
+has a default value so that they have to be set to make tt(_expand)
+generate any expansions at all.
 
 In a different mode selected by the tt(completions) style, all
 em(completions) generated for the string on the line are inserted.
@@ -2193,7 +2201,7 @@
 
 For example, consider this global tt(completer) style:
 
-example(zstyle ':completion:*' completer \
+example(zstyle ':completion:*' completer \ 
     _complete _prefix _correct _prefix:foo)
 
 This makes the tt(_prefix) completer try normal completion with the
@@ -2201,7 +2209,7 @@
 the call to the tt(_correct) completer after it, then tt(_prefix) will 
 be called a second time and will now only try correction with the
 suffix ignored. If you want to use tt(_prefix) as the last resort and
-want it to try only normal completion, you need to call:
+want it to try only normal completion, you can use:
 
 example(zstyle ':completion:*' completer _complete ... _prefix
 zstyle ':completion::prefix:*' completer _complete)
@@ -2352,7 +2360,7 @@
 called, the information about the styles may be
 incomplete. I.e. depending on the settings for some styles other
 styles may be used, and, depending on the user's settings, only the
-first sort of styles may be detected by tt(_complete_help).
+first sort of styles may be found by tt(_complete_help).
 )
 findex(_complete_debug (^X?))
 item(tt(_complete_debug (^X?)))(
@@ -2369,7 +2377,7 @@
 
 Descriptions follow for utility functions that may be
 useful when writing completion functions.  Most of these reside in the
-tt(Core) subdirectory except where noted. Like the example 
+tt(Core) subdirectory. Like the example 
 functions for commands in the distribution, the utility functions
 generating matches all follow the convention of returning zero if they
 generated completions and non-zero if no matching completions could be 
@@ -2381,7 +2389,7 @@
 tt(compprefuncs) and tt(comppostfuncs) may be set to contain names of
 functions that are to be called immediately before or after completion 
 has been tried. The functions will only be called once, unless they
-put themselves into the array again.
+put themselves into the arrays again.
 
 startitem()
 findex(_funcall)
@@ -2442,9 +2450,10 @@
 which guarantee that the matches are generated as requested by the
 user. The styles tested are: tt(format) (which is first tested for the
 given tag and then for the tt(descriptions) tag if that isn't
-defined), tt(hidden) and tt(group-name) (the last two are tested only
-for the tag given as the first argument). This function also calls the
-tt(_setup) function which tests some more styles.
+defined), tt(hidden), tt(matcher), tt(ignored-patterns) and
+tt(group-name) (the last are tested only for the tag given as the
+first argument). This function also calls the tt(_setup) function
+which tests some more styles.
 
 The format string from the style (if any) will be modified so that the 
 sequence `tt(%d)' is replaced by the var(descr) given as the third
@@ -2523,7 +2532,7 @@
 
 The tt(-12JV) options and the first three arguments are given to the
 tt(_desciption) function using the tag label instead of the first
-argument is appropriate. The var(options) given after the var(descr)
+argument as appropriate. The var(options) given after the var(descr)
 should be other options to be used for tt(compadd) or whatever
 function is to be called to add the matches. tt(_next_label) will store these 
 var(options) in the parameter whose var(name) is given as the second
@@ -2535,7 +2544,7 @@
 tt(_tags) or tt(_requested) because it uses the tag label
 for the current tag found by these functions.
 
-A normal use of this function for the tag labels for the tag tt(foo)
+A normal use of this function for the tag labels of the tag tt(foo)
 looks like this:
 
 example(local expl ret=1
@@ -2642,7 +2651,7 @@
 item(tt(_alternative) [ tt(-C) var(name) ] var(specs) ...)(
 This function is useful if you offer multiple tags and building the
 matches for them is easy enough. It basically implements a loop like
-the one described for the tt(_tags) function above above.
+the one described for the tt(_tags) function above.
 
 The tags to use and what to do if the tags are requested are described 
 using the var(specs) which are of the form:
@@ -2671,7 +2680,7 @@
 different name for the argument context field.
 )
 findex(_describe)
-item(tt(_describe) var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)(
+item(tt(_describe) [ tt(-o) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)(
 This function can be used to add options or values with descriptions
 as matches. The var(descr) is taken as a string to display above
 the matches if the tt(format) style for the tt(descriptions) tag is set.
@@ -2682,7 +2691,7 @@
 by a colon from the completion string). If the second array is given,
 it should have the same number of elements as the first one and these
 elements are added as possible completions instead of the strings from 
-the first array. In any case, however, the completion list will show
+the first array. In any case, however, the completion list will contain
 the strings from the first array.
 
 Any number of array/option sequences may be given separated by
@@ -2775,7 +2784,7 @@
 item(tt(-F))(
 This option from the tt(compadd) builtin gives direct control over which
 filenames should be ignored. If no such option is given, the
-tt(ignored-suffixes) style is used.
+tt(ignored-patterns) style is used.
 )
 enditem()
 
@@ -2784,7 +2793,7 @@
 `tt(-r)', and `tt(-R)' options from the tt(compadd) builtin.
 
 Finally, the tt(_path_files) function  uses the styles tt(expand),
-tt(ambiguous) and tt(special-dirs) with the tt(paths) tag.
+tt(ambiguous) and tt(special-dirs) and tt(file-sort).
 )
 findex(_parameters)
 item(tt(_parameters))(
@@ -2812,9 +2821,6 @@
 )
 findex(_arguments)
 item(tt(_arguments) var(specs) ...)(
-This function resides in the tt(Base) subdirectory of the example
-completion system because it is not used by the core system.
-
 This function can be used to complete words on the line by simply
 describing the arguments the command on the line gets. The description 
 is given as arguments to this function, with each var(spec) describing
@@ -2862,8 +2868,8 @@
 are to be completed as described by the var(action), in the second
 form all words up to a word matching the given var(pattern) are to be
 completed using the var(action). The `tt(*)' or the var(pattern) may
-also be separated from the var(message) by two or three colons. With
-two colons the tt(words) special array and the tt(CURRENT) special
+also be separated from the var(message) by two or three colons. In
+this case, the tt(words) special array and the tt(CURRENT) special
 parameter are modified to refer only to the words after the option
 (with two colons) or to the words covered by this description (with
 three colons) during the execution or evaluation of the
@@ -2874,14 +2880,17 @@
 beginning with a minus or a plus sign, such as `tt(-foo)'. If the
 command accepts the option both with a leading minus and a plus sign,
 one can use either tt(-+foo) or tt(+-foo) to define both options at
-once. In this
-case, the first argument for the option (if any) has to come as a
+once.
+
+In these
+cases, the first argument for the option (if any) has to come as a
 separate word directly after the option and the option may appear only 
-once on the line (and if it is already on the line, the option name
+once on the line (and if it is already on the line and to the left of
+the cursor, the option name
 will not be offered as a possible completion again). If the first
 argument for the option has to come directly after the option name
 em(in the same word), a minus sign should be added to the end of the
-var(opt-spec), as in `tt(-foo-)'. If the first argument may be given
+var(opt-spec), as in `tt(-foo-:)var(...)'. If the first argument may be given
 in one string with the option name, but may also be given as a
 separate argument after the option, a plus sign should be used
 instead. If the argument may be given as the next string or in same
@@ -2961,7 +2970,7 @@
 before executing the var(action) and hence may be used in it (normally 
 in an expansion like `tt($expl[@])').
 
-If the var(action) starts with `tt(= )' (an equals sign followed by a
+If the var(action) starts with `tt(= )' (an equal sign followed by a
 space), tt(_arguments) will insert the contents of the var(argument)
 field of the current context as the new first element in the tt(words) 
 special array and increments the value of the tt(CURRENT) special
@@ -3002,14 +3011,14 @@
 given as one string, separated by colons. All colons in the original
 arguments are preceded with backslashes.
 
-The parameter `tt(context)'
-will be set to the automatically created context names. This are either
-strings of the form `tt(option)var(-opt)tt(-)var(n)' for the var(n)'th argument 
-of the option var(-opt), or a string of the form `tt(argument-)var(n)' 
-for the var(n)'th argument (for rest arguments the var(n) is the
-string `tt(rest)'). For example, when completing the argument of the tt(-o)
-option, the name is `tt(option-o-1)' and for the second normal (non-option-)
-argument it is `tt(argument-2)'.
+The parameter `tt(context)' will be set to the automatically created
+context names. These are either strings of the form
+`tt(option)var(-opt)tt(-)var(n)' for the var(n)'th argument of the
+option var(-opt), or strings of the form `tt(argument-)var(n)' for
+the var(n)'th argument (for rest arguments the var(n) is the string
+`tt(rest)'). For example, when completing the argument of the tt(-o)
+option, the name is `tt(option-o-1)' and for the second normal
+(non-option-) argument it is `tt(argument-2)'.
 
 Also, during the evaluation of the var(action), the context name in
 the tt(curcontext) parameter will be changed by appending the same
@@ -3105,7 +3114,7 @@
 example(_arguments '-l+:left border:' \ 
            '-format:paper size:(letter A4)' \ 
            '*-copy:output file:_files::resolution:(300 600)' \ 
-           ':postscript file:_files -g *.(ps|eps)' \ 
+           ':postscript file:_files -g \*.\(ps\|eps\)' \ 
            '*:page number:')
 
 This describes three options: `tt(-l)', `tt(-format)', and
@@ -3136,17 +3145,17 @@
 the first hyphen are shared by all sets given after the first
 hyphen. The first word in every other set gives the name of the
 set. This name may appear in exclusion lists in the specifications,
-either alone or before (with a `tt(-)' between the name and the rest)
-one of the possible values described for tt(_arguments) above.
+either alone or before one of the possible values described for
+tt(_arguments) above (with a `tt(-)' between the name and the rest).
 
 For example:
 
-example(_argument_sets \
-    -a \
-  - set1 \
-    -c \
-  - set2 \
-    -d \
+example(_argument_sets \ 
+    -a \ 
+  - set1 \ 
+    -c \ 
+  - set2 \ 
+    -d \ 
     ':arg:(x2 y2)')
 
 This defines two sets. When the command line contains the option
@@ -3238,13 +3247,13 @@
 findex(_regex_arguments)
 item(tt(_regex_arguments) var(name) var(specs) ...)(
 This function is a compiler to generate a completion function.  The
-first argument specifies the name of a generated function while the
+first argument specifies the name of the generated function while the
 remaining arguments specify a completion as a set of regular
 expressions with actions.  The generated function has the structure of a
-finite-state machine whose state corresponds to the state (i.e. the
+finite-state machine whose states corresponds to the state (i.e. the
 context) of the completion. This state machine uses a command line,
 which comes from concatentating the tt(words) array up to the current
-cursor position using null characters as a separator with no extra
+cursor position using null characters as separators with no extra
 quotation.  This is analysed and at the end the appropriate action is
 executed.
 
@@ -3255,7 +3264,7 @@
 startitem()
 item(tt(/)var(pattern)tt(/) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(action)])(
 This is a primitive element, corresponding to one
-state of the compiled state machine.  The state is entered if the pattern
+state of the compiled state machine.  The state is entered if
 `tt((#b)LPAR()(#B))var(pattern)tt(RPAR()(#B))var(lookahead)tt(*)' matches
 the command line string.  If it is matched, `var(guard)' is evaluated and
 its return status is examined; if this is successful, the state is entered,
@@ -3263,36 +3272,36 @@
 string `tt([])' is guaranteed never to match.
 
 If the test succeeds and the state is entered, the left part of the
-command line string matched as `var(pattern)' is removed and the 
+command line string matched as var(pattern) is removed and the 
 next state is tried, proceeding from inside to outside and from left to
 right.
 
 If no test succeeds and the remaining command line string contains no null
 character, the completion target is restricted to the remainder of the
-command line string and `var(action)'s for the target are evaluated.
+command line string and var(action)s for the target are evaluated.
 In this case, nothing is actually removed from the command line string
-so that any previous or neighbouring state may also have `var(actions)'s.
+so that any previous or neighbouring state may also have var(actions)s.
 )
 item(tt(/)var(pattern)tt(/+) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(action)])(
 This is similar to `tt(/)var(pattern)tt(/) ...' but the left part of
 command line string is also considered as part of the completion target.
 )
 item(tt(/)var(pattern)tt(/-) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(action)])(
-This is similar to `tt(/)var(pattern)tt(/) ...' but `var(action)'s of the
+This is similar to `tt(/)var(pattern)tt(/) ...' but the var(action)s of the
 current and previous states are ignored even if the following state's
 `var(pattern)' matches the empty string.
 )
 item(tt(LPAR()) var(spec) tt(RPAR()))(
-This groups `var(spec)'.
+This groups var(spec)s.
 )
 item(var(spec) tt(#))(
-This allows any number of repetitions of `var(spec)'.
+This allows any number of repetitions of var(spec).
 )
 item(var(spec) var(spec))(
-This represents the concatenation of two `var(spec)'s.
+This represents the concatenation of two var(spec)s.
 )
 item(var(spec) tt(|) var(spec))(
-Either of two `var(spec)'s can be matched.
+Either of the two var(spec)s can be matched.
 )
 enditem()
 )
@@ -3343,56 +3352,54 @@
 
 Inside such functions the name of the current context can
 be accessed using the tt(curcontext) parameter. For example, the
-function generating file names (called tt(_files)) in the completion
-system is often called to generate only filenames matching a given
-glob pattern, in which case it uses the tags tt(globbed-files),
-tt(directories), and tt(all-files).  This means that the function
-offers to generate filenames matching the pattern, names of
-directories or all filenames as possible matches. Example:
+function used in command position (called tt(_command_names)) in the
+completion can generate names of external and builtin commands, names
+of shell functions, aliases and parameters and reserved words.
 
+Example:
+
 example(_sort_tags() {
   case $curcontext in
-  (*::dvips:*)
-    comptry globbed-files directories
-    comptry all-files
+  (*:-command-:*)
+    comptry commands functions
+    comptry builtins aliases
     ;;
   (*)
-    comptry globbed-files
-    comptry directories
-    comptry all-files
+    .comptry "$@"
     ;;
   esac
+  return 1
 })
 
-Every call to the tt(comptry) function (actually a builtin
-command defined by the tt(zsh/computil) module) gives a
-set of tags to use; as soon as one of the completion system produces
-some matches for one set,
-subsequent sets have no effect.  Hence in the example
-this means that for the tt(dvips) command on the first attempt the
-names of DVI files and directories will be generated (first call to
-tt(comptry)). If none of those names match the string from the command
-line the completion function will generate all filenames as
-possible matches (second call to tt(comptry)).
+Every call to the tt(comptry) builtin command gives a
+set of tags to use; as soon as completion system produces
+some matches for one set, subsequent sets have no effect.  Hence in
+the example this means that in command position on the first attempt
+only names of external commands and shell functions will be generated
+(first call to tt(comptry)). If none of those names match the string
+from the command line the completion function will generate names of
+builtin commands and aliases as possible matches (second call to
+tt(comptry)).
 
 For all other context names the second case-pattern matches, so that
-normally the completion functions will only try the filenames matching 
-the glob pattern (if any glob pattern is used). If that doesn't yield
-any matches, names of directories are generated, and if that doesn't
-yield any matching names either, all filenames will be generated.
-
-In every context the function may call tt(comptry) as
-often as it wants. Also, every string may be given as argument, even
-if no tag with such a name was offered by the completion
-function. This allows one to give a preferred ordering for some common 
-tag sets without having to worry about sensible patterns for context
-names. For example, many completion functions can generate both
-arguments and option names for commands. These functions normally use
-the tags tt(arguments) and tt(options). Depending on your preference
-you may write in your sorting function:
+normally the completion functions will try all tags offered. The
+return value means that the calling function, tt(_tags), will not use
+all offered tags as a default, so in the first case names or
+parameters and reserved words will never be completed.
+
+In every context the function may call tt(comptry) as often as it
+wants. Also, every string may be given as argument, even if no tag
+with such a name was offered by the completion function. This allows
+one to give a preferred ordering for some common tag sets without
+having to worry about sensible patterns for context names. For
+example, many completion functions can generate both arguments and
+option names for commands. These functions normally use the tags
+like tt(argument-)var(num), tt(option-)var(name)tt(-)var(num) and
+tt(options). Depending on your preference you may write in your
+sorting function:
 
 example(_sort_tags() {
-  comptry arguments options
+  comptry -m '(|*-)argument-* (|*-)option-* options'
   case $curcontext in
   ...
   esac
@@ -3401,7 +3408,7 @@
 or
 
 example(_sort_tags() {
-  comptry arguments
+  comptry -m '(|*-)argument-* (|*-)option-*'
   comptry options
   case $curcontext in
   ...
@@ -3415,34 +3422,6 @@
 for the argument, which normally means that you have to type the
 hyphen the option names start with yourself to see the list of option
 names that can be completed.
-
-Since the completion functions are free to choose the tag names they
-use, there can't be a complete list. So to make sure that all types of 
-matches are eventually tried as completions, one should  use a call to 
-tt(comptry) with all arguments at the end of the sorting function. For
-those contexts where one really wants to make sure that certain tags are
-never used one can then use a call to tt(return) to circumvent that
-last tt(comptry). For example:
-
-example(_sort_tags() {
-  ...
-  case $curcontext in
-  (*::kill:*)
-    comptry processes
-    return
-    ;;
-  esac
-  comptry "$@"
-})
-
-The completion function for the tt(kill) builtin command offers the
-tags tt(jobs) and tt(processes) which represent job references
-(e.g. `tt(%1)') and process identifiers respectively. The function
-above makes sure that for this builtin command only process
-identifiers are generated as possible matches by using only the
-tt(processes) tag in a call to tt(comptry). The immediate call to
-tt(return) then makes sure that the default tt(comptry) at the end is
-not executed.
 
 With the tt(-s) option, each tag given to tt(comptry) will be put in a 
 separate set. With the tt(-m) option, the arguments are treated in the 
Index: Doc/Zsh/compwid.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/compwid.yo,v
retrieving revision 1.7
diff -u -r1.7 compwid.yo
--- Doc/Zsh/compwid.yo	2000/04/28 13:20:12	1.7
+++ Doc/Zsh/compwid.yo	2000/05/02 08:11:32
@@ -255,7 +255,7 @@
 This gives the number of lines that are needed to display the full
 list of completions. Note that to calculate the total number of lines
 to display you need to add the number of lines needed for the command
-line to this value, this is available as the value of the tt(BLINES)
+line to this value, this is available as the value of the tt(BUFFERLINES)
 special parameter.
 )
 vindex(last_prompt, compstate)
@@ -272,9 +272,9 @@
 not to be changed; if set to tt(unambiguous), any prefix common to all
 matches is to be inserted; if set to tt(automenu-unambiguous), the
 common prefix is to be inserted and the next invocation of the
-completion code may start menu-completion (due to the tt(AUTO_MENU)
-option being set); if set to tt(menu) or tt(automenu) menu-completion
-will be started for the matches currently generated due to (in the
+completion code may start menucompletion (due to the tt(AUTO_MENU)
+option being set); if set to tt(menu) or tt(automenu) menucompletion
+will be started for the matches currently generated (in the
 latter case this will happen because the tt(AUTO_MENU) is set).
 
 On exit it may be set to any of the values above (where setting it to
@@ -282,14 +282,14 @@
 case the match whose number is given will be inserted into the command line.
 Negative numbers count backward from the last match (with `tt(-1)'
 selecting the last match) and out-of-range values are wrapped
-around, so that a value of zero selects the last match group and a value
+around, so that a value of zero selects the last match and a value
 one more than the maximum selects the first. Unless the value of this
-key ends in a space, the match is inserted as in a menu-completion,
+key ends in a space, the match is inserted as in a menucompletion,
 i.e. without automatically appending a space.
 
 Both tt(menu) and tt(automenu) may also specify the the number of the
 match to insert, given after a colon.  For example, `tt(menu:2)' says
-to start menu-completion, beginning with the second match.
+to start menucompletion, beginning with the second match.
 
 Finally, it may also be set to tt(all), which makes all matches
 generated be inserted into the line.
@@ -339,6 +339,9 @@
 Controls the behaviour when the tt(REC_EXACT) option is set.  It will be
 set to tt(accept) if an exact match would be accepted, and will be unset
 otherwise.
+
+If it was set when at least one match equal to the string on the line
+was generated, the match is accepted.
 )
 vindex(exact_string, compstate)
 item(tt(exact_string))(
@@ -348,21 +351,21 @@
 item(tt(pattern_match))(
 Locally controls the behaviour given by the tt(GLOB_COMPLETE) option.
 Initially it is set to `tt(*)' if and only if the option is set.
-The completion widget may set it to either of these two values, or to any
+The completion widget may set it to this value, to an empty string
+(which has the same effect as unsetting it), or to any
 other non-empty string.  If it is non-empty, unquoted metacharacters on the
 command line will be treated as patterns; if it is `tt(*)', then
 additionally a wildcard `tt(*)' is assumed at the cursor position; if
 it is empty or unset, metacharacters will be treated literally.
 
-Note that the matcher specifications given globally or to one of the
-builtin commands adding matches are not used if this is set to a
-non-empty string.
+Note that the matcher specifications given to the tt(compadd) builtin
+command are not used if this is set to a non-empty string.
 )
 vindex(pattern_insert, compstate)
 item(tt(pattern_insert))(
-Normally this is set to tt(menu), which specifies that menu-completion will
+Normally this is set to tt(menu), which specifies that menucompletion will
 be used whenever the matches were generated using pattern matching. If it
-is set to any other non-empty string by the user and menu-completion is
+is set to any other non-empty string by the user and menucompletion is
 not selected by other option settings, the code will insert an
 unambiguous string for the generated matches as with normal completion.
 )
@@ -394,8 +397,8 @@
 xitem([ tt(-W) var(file-prefix) ] [ tt(-d) var(array) ])
 xitem([ tt(-J) var(name) ] [ tt(-V) var(name) ] [ tt(-X) var(explanation) ])
 xitem([ tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ])
-xitem([ tt(-M) var(match-spec) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ])
-item([ tt(-D) var(array) ] [ tt(--) ] [ var(words) ... ])(
+xitem([ tt(-D) var(array) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ])
+item([ tt(-M) var(match-spec) ] [ tt(--) ] [ var(words) ... ])(
 
 This builtin command can be used to add matches directly and control
 all the information the completion code stores with each possible
@@ -417,7 +420,7 @@
 listing completions, given with the tt(-p) option; for example,
 functions that do filename generation might specify
 a common path prefix this way. var(<word>) is the part of the match that
-should appear in the list of completions, one of the tt(words) given at the
+should appear in the list of completions, one of the var(words) given at the
 end. The suffixes var(<hsuf>), var(<asuf>) and var(<isuf>) correspond to
 the prefixes var(<hpre>), var(<apre>) and var(<ipre>) and are given by the
 options tt(-s), tt(-S) and tt(-I), respectively.
@@ -431,7 +434,7 @@
 metacharacters in it will not be quoted when the string is inserted.
 )
 item(tt(-S) var(suffix))(
-Like tt(-P) but gives a string to be inserted after the match.
+Like tt(-P), but gives a string to be inserted after the match.
 )
 item(tt(-p) var(hidden-prefix))(
 This gives a string that should be inserted into the command line before the
@@ -744,9 +747,11 @@
 command line) map onto the characters in the list of matches produced by
 the completion code (referred to here as the trial completions). Note
 that this is not used if the command line contains a glob pattern and
-the tt(GLOB_COMPLETE) option is set.
+the tt(GLOB_COMPLETE) option is set or the tt(pattern_match) of the
+tt(compstate) special association is set to a non-empty string.
 
-The var(spec) consists of one or more matching descriptions separated by
+The var(spec) given as argument to the tt(-m) option consists of one
+or more matching descriptions separated by
 whitespace. Each description consists of a letter followed by a colon,
 then the patterns describing which character sequences on the line match
 which character sequences in the trial completion.  Any sequence of characters not
@@ -777,7 +782,7 @@
 trial completion strings.
 
 If no var(lpat) is given, but a var(ranchor), this matches the gap
-between substrings matched by var(lanchor) an var(ranchor). Unlike
+between substrings matched by var(lanchor) and var(ranchor). Unlike
 var(lanchor), the var(ranchor) only needs to match the trial
 completion string.
 )
@@ -862,25 +867,25 @@
 example(compadd -M 'm:{a-zA-Z}={A-Za-z}' ... )
 
 A nice example for the use of tt(*) patterns is partial word
-completion. Sometimes you would like to make strings like tt(c.s.u)
-complete to strings like tt(comp.source.unix), i.e. the word on the
+completion. Sometimes you would like to make strings like `tt(c.s.u)'
+complete to strings like `tt(comp.source.unix)', i.e. the word on the
 command line consists of multiple parts, separated by a dot in this
 example, where each part should be completed separately --- note,
-however, that the case where each part of the word, i.e. tt(comp),
-tt(source) and tt(unix) in this example, is to be completed separately
-is a different problem to be solved by extended completion.  The
-example can be handled by:
+however, that the case where each part of the word, i.e. `tt(comp)',
+`tt(source)' and `tt(unix)' in this example, is to be completed separately
+is a different problem to be solved by the implementation of the
+completion widget.  The example can be handled by:
 
 example(compadd -M 'r:|.=* r:|=*' \ 
   - comp.sources.unix comp.sources.misc ...)
 
-The first specification says that tt(lpat) is the empty string, while
-tt(anchor) is a dot; tt(tpat) is tt(*), so this can match anything
+The first specification says that var(lpat) is the empty string, while
+var(anchor) is a dot; var(tpat) is tt(*), so this can match anything
 except for the `tt(.)' from the anchor in
-the trial completion word.  So in tt(c.s.u), the matcher sees tt(c),
+the trial completion word.  So in `tt(c.s.u)', the matcher sees `tt(c)',
 followed by the empty string, followed by the anchor `tt(.)', and
 likewise for the second dot, and replaces the empty strings before the
-anchors, giving tt(c)[tt(omp)]tt(.s)[tt(ources)]tt(.u)[tt(nix)], where
+anchors, giving `tt(c)[tt(omp)]tt(.s)[tt(ources)]tt(.u)[tt(nix)]', where
 the last part of the completion is just as normal.
 
 With the pattern shown above, the string `tt(c.u)' could not be
@@ -898,7 +903,7 @@
 typed so far, i.e. it will only insert new characters at the cursor
 position rather then at the end.  However in our example we would like
 the code to recognise matches which contain extra characters after the
-string on the line (the tt(nix) in the example).  Hence we say that the
+string on the line (the `tt(nix)' in the example).  Hence we say that the
 empty string at the end of the string on the line matches any characters
 at the end of the trial completion.
 
@@ -913,7 +918,7 @@
 completion.
 
 The specifications with both a left and a right anchor are useful to
-complete partial words whose parts are not really separated by some
+complete partial words whose parts are not separated by some
 special character. For example, in some places strings have to be
 completed that are formed `tt(LikeThis)' (i.e. the separate parts are
 determined by a leading uppercase letter) or maybe one has to
@@ -923,11 +928,11 @@
 example(compadd -M 'r:|[A-Z0-9]=* r:|=*' LikeTHIS FooHoo foo123 bar234)
 
 But with this, the string `tt(H)' would be completed to `tt(FooHoo)'
-em(and) tt(LikeTHIS) and `tt(2)' would be completed to the other two
+em(and) `tt(LikeTHIS)' and `tt(2)' would be completed to the other two
 strings because characters can be inserted before every uppercase
 letter and digit. To avoid this one would use:
 
-example(compadd -M 'r:[^A-Z0-9]||[A-Z0-9]=* r:|=*' \
+example(compadd -M 'r:[^A-Z0-9]||[A-Z0-9]=* r:|=*' \ 
     LikeTHIS FooHoo foo123 bar234)
 
 By using these two anchors, a `tt(H)' matches only uppercase `H's that 
@@ -939,9 +944,8 @@
 ifzman(zmanref(zshcompsys))\
 ifnzman(noderef(Completion System))\
 ), users can define match specifications that are to be used for
-specific contexts by using the tt(matcher) style and match
-specifications that are to be used everywhere can be defined by the
-use of the tt(_matcher) completer.
+specific contexts by using the tt(matcher) and tt(matcher-list)
+styles. The values for the latter will be used everywhere.
 
 texinode(Examples)()(Matching Control)(Completion Widgets)
 sect(Examples)

--
Sven Wischnowsky                         wischnow@xxxxxxxxxxxxxxxxxxxxxxx