PATCH: 3.1.6-pws-11: Completion suggestions + fixes + sorting tags

[Peter Stephenson <pws@xxxxxxxxxxxxxxxxxxxxxxxx>]

Here are some points for discussion.  Anything I thought was unambiguously
wrong is in the patch below.  I know compinstall still needs rewriting
completely.  Probably it should also convert a 3.1.6 installation into a
3.1.7 one.

1. One significant change which I have hubristically included in the patch
   is the addition of the sort-tags style.  This is a simpler alternative
   to redefining _sort_tags.  For example,

   zstyle :completion:complete::gunzip: sort-tags \
    'globbed-files directories' all-files

   will try globbed files and directories first at the same time,
   then all-files.  This allows you to do everything you could with
   specifying priorities much more simply.

2. I don't really like the way ZLS_COLORS is sidelined.  There doesn't seem
   to be any point in it if you're using new completion.  Perhaps if it's
   set when completion is initialised it could be set to the default for
   the list-colors style.

3. I'm also not that keen on the default style for process completion.
   If you type `disown <TAB>', nothing happens because it needs you to type
   a `%'.  This is a bit silly in this case, since real process numbers
   can't be used.  The same is true of many of the other builtins.

   Also, if you just have one process and hit tab, it shows up as a number
   and you don't get a list.  It's a bit uninformative just being told you
   are going to disown %1 (and at that point it's too late to ask for a
   list).  It would be quite nice to get process to show up as %name if
   that's unambiguous and numbers otherwise.

4. There's no real problem about proliferating tags, I don't think, because
   they are specific to particular contexts.  To cut down the number of
   tags listed in the main list in the manual, would it be better to move
   tags only used in one context, e.g. for the users-hosts lookup etc.,
   into the description of that context?  Then the tags list would only be
   of those that are used throughout completion.  A counter-argument is
   that you then don't know what tags to use if you're adding a new
   function/context.

   Various style entries talk about `the default tag'.  This is not
   mentioned in the section on tags, nor is there apparently any indication
   that there is a default tag.  It might be nice to say why it's
   necessary, which I'm not absolutely clear about.  For example, as
   instructed I have '*:default' for list-colors.  But shouldn't '*' be
   enough, given that all `default' means is `not if there's anything more
   specific', which is already implied by the pattern-lookup rules?
   `default' should only be necessary as an alternative to some other
   options, whereas here there don't seem to be any.  On what occasions do
   I actually need the word `default' to remove ambiguity?

   Is the `cvs' tag really necessary?  The documentation says:
     used only to look up the value of the tt(disable-stat) style
   in which case, surely the context is already specific enough,
   i.e. shouldn't the context already be `:complete::cvs:'?

   On the same theme again, what about the `paths' tag in _path_files,
   used with various styles for file insertion?  I suppose it's there
   because otherwise the context is rather non-specific, e.g. just
   :completion:complete.  But it's still a little confusing in that
   it doesn't currently add any information.  I suppose it's future-proof
   in case other contexts start using cursor etc.  Plus of course
   there's nothing to stop you turning it into a wildcard.  I suppose
   the dilemma really is that you want to be in some specific context
   that is the parent of all the more specific file contexts, but
   that would make the context in the latter case unnecessarily complex.

5. I'm also not sure why there isn't always a final : at the end of a
   context like there is at the beginning, and for the same reason.
   It doesn't happen if the last entry is a tag, but (see 7.)
   it seems to me the context should be pretty much transparent
   as to what each element actually represents.

6. Incremental completion may be missing a few things, for example
   a way of switching it off after it's completed a word with tab, it
   annoys me that it doesn't, and an option to complete unambiguous bits
   automatically.  The function doesn't seem to be described anywhere, but
   I think someone already suggested the zle functions needed their own
   manual entry.

7. I haven't altered this, but it's a little confusing that we have two
   notions of context described in the manual:  one without :completion
   in front and no tag behind, and one with.  It should be possible to
   rewrite the description or if necessary the code, so that the context
   is a unique string up to the depth we have currently reached
   (i.e. the tag is added if and only if it's relevant, the :completion
   is always present).

7. The description of the `glob' style refers to a `complete' style, which
   doesn't seem to exist.

Things in the patch, apart from the `sort-tags' style:
 - compconf was using the `accept' style, which is now max-errors.
 - I've converted _description in _mh to _wanted, since you get better
   output from ^Xh.  I don't know of any other consequences of the change.
 - I've `improved' the new sections on styles and tags in the compsys.yo
   manual page, by trying to simplify the explanations and be a bit more
   specific.  I've moved the detail description of _sort_tags in the
   function section, since presumably it's not the first thing a user will
   need to know and it interrupts the more general description.
   I'm hoping that the necessity of altering it will be largely eliminated.
 - I've rewritten the _regex_arguments documentation, possibly mangling
   it in places.
 - incremental-complete-word was still using _style.  I've tried to replace
   this, but I wasn't watching properly when _style was around, so this
   needs checking, but it seems to be OK.

Index: Completion/Core/_sort_tags
===================================================================
RCS file: /home/pws/CVSROOT/projects/zsh/Completion/Core/_sort_tags,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 _sort_tags
--- Completion/Core/_sort_tags	1999/11/28 17:42:27	1.1.1.1
+++ Completion/Core/_sort_tags	1999/12/14 21:06:05
@@ -1,28 +1,39 @@
 #autoload
 
-comptry arguments values
-comptry options
+local stags tag
 
-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
-#   ;;
-# *::kill:*)
-#   comptry processes
-#   return                  # this return ensures that we use only processes
-#   ;;
-*)
-  comptry globbed-files
-  comptry directories
-  comptry all-files
-  ;;
-esac
+if zstyle -a ":completion${curcontext}" sort-tags stags; then
 
-comptry "$@"
+  for tag in $stags; do
+    [[ $tag != '' ]] && comptry ${=tag}
+  done
+
+else
+
+  comptry arguments 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
+  #   ;;
+  # *::kill:*)
+  #   comptry processes
+  #   return                  # this return ensures that we use only processes
+  #   ;;
+  *)
+    comptry globbed-files
+    comptry directories
+    comptry all-files
+    ;;
+  esac
+
+  comptry "$@"
+fi
Index: Completion/Core/compinit
===================================================================
RCS file: /home/pws/CVSROOT/projects/zsh/Completion/Core/compinit,v
retrieving revision 1.5
diff -u -r1.5 compinit
--- Completion/Core/compinit	1999/12/13 20:35:59	1.5
+++ Completion/Core/compinit	1999/12/14 15:13:15
@@ -488,7 +488,7 @@
 zstyle ':completion:*'        verbose       'yes'
 zstyle ':completion:*'        prefix-needed 'yes'
 zstyle ':completion:*'        prefix-hidden 'no'
-zstyle ':completion:correct'  accept        '2n'
+zstyle ':completion:correct'  max-errors    '2' numeric
 zstyle ':completion:correct'  prompt        'correct to:'
 zstyle ':completion:*'        completer     '_complete'
 zstyle ':completion*:default' list-colors   no=0 fi=0 di=0 ln=0 pi=0 so=0 bd=0 cd=0 ex=0
Index: Completion/User/_mh
===================================================================
RCS file: /home/pws/CVSROOT/projects/zsh/Completion/User/_mh,v
retrieving revision 1.2
diff -u -r1.2 _mh
--- Completion/User/_mh	1999/12/03 19:01:24	1.2
+++ Completion/User/_mh	1999/12/14 15:35:19
@@ -35,9 +35,7 @@
     mhpath=$(mhpath)
   fi
 
-  # painless, or what?
-  _description files expl 'MH folder'
-  _path_files "$expl[@]" -W mhpath -/
+  _wanted files expl 'MH folder' && _path_files "$expl[@]" -W mhpath -/
 elif [[ "$prev" = -(editor|(whatnow|rmm|show|more)proc) ]]; then
   _command_names -e
 elif [[ "$prev" = -file ]]; then
@@ -50,8 +48,8 @@
   [[ -d $mhlib ]] || { mhlib=$(mhparam mhlproc); mhlib=$mhlib:h; }
   mhfpath=($mymhdir $mhlib)
 
-  _description files expl 'MH template file'
-  _files "$expl[@]" -W mhfpath -g '*(.)'
+  _wanted files expl 'MH template file' &&
+    _files "$expl[@]" -W mhfpath -g '*(.)'
 elif [[ "$prev" = -(no|)cc ]]; then
   _wanted -C "$prev" values expl 'CC address' &&
       compadd "$expl[@]" all to cc me
Index: Doc/Zsh/compsys.yo
===================================================================
RCS file: /home/pws/CVSROOT/projects/zsh/Doc/Zsh/compsys.yo,v
retrieving revision 1.13
diff -u -r1.13 compsys.yo
--- Doc/Zsh/compsys.yo	1999/12/13 21:04:03	1.13
+++ Doc/Zsh/compsys.yo	1999/12/14 21:23:36
@@ -264,180 +264,78 @@
 sect(Completion System Configuration)
 cindex(completion system, configuration)
 
-The completion system allows users to configure many aspects of how
-and when matches are generated. After a short overview of how the
-completion system works, this section describes how this can be done.
+This section gives a short overview of how the completion system works,
+and then more detail on how users can configure how and when matches are
+generated.
 
 subsect(Overview)
 
 When completion is attempted somewhere on a command line the
 completion system first tries to find out the context where completion 
-was tried. Such a context depends, for example, on the name of the
-command when completing an argument. Or it may depend on both the name 
-of a command and the name of an option when completing after one that
-takes arguments.
-
-The completion system represents such a context as a hierarchical name 
-with components separated by colons. For example the name
-tt(:complete::dvips::-o-1) is used when completing the first argument of 
-the tt(-o) option of the tt(dvips) command. The tt(:complete) at the
-beginning just says that we are currently trying completion as opposed 
-to, say, correction, which can also be done using the function based
-completion system (see
+was tried.  The context depends on such things as the name of the
+command when completing an argument, and possibily also
+the name of an option when completing an argument to that option.
+
+The completion system represents contexts as hierarchical name s
+with components separated by colons. For example, take the context
+`tt(:complete::dvips::-o-1)'.  The tt(:complete) at the
+beginning is the `completer', which is in overall control of how completion
+is to be performed; `tt(complete)' is the basic one for
+ordinary completion, but completers may perform various related tasks
+such as correction, or modify the behaviour of a later completer (see
 ifzman(the section `Control Functions' below)\
 ifnzman(noderef(Control Functions)) 
-for more information). The tt(::dvips:) shows that we are
-completing arguments for the tt(dvips) command. Such a doubled colon
+for more information).  Strictly, the completer is `tt(_complete)', but the
+underscore is omitted from the context; this is also true of `tt(correct)',
+`tt(approximate)', etc.  The tt(::dvips:) shows that we are
+completing arguments for the tt(dvips) command.  The doubled colon
 will appear only before and after the name of the command, but note
-that the second colon after the command name is really only added when 
+that the second colon after the command name is only added when 
 there is at least one more component (otherwise the whole name ends in 
-a colon).
+a colon, e.g. `tt(...dvips:)').  Finally, the string tt(-o-1) says that we
+are completing the first argument of the option `tt(-o)' to the command.
+Note that the existence of a context like this does not necessarily mean it
+is handled specially by the completion system; this is determined by trying
+to match the context as specifically as possible, as described below.
 
 In many of the possible contexts the completion system can generate
-matches, and often it can generate multiple types of matches. Whenever 
-a completion function is about to generate such matches it first calls 
-a utility function, telling it what types of matches can be
-generated. These types are represented as simple names called
-`tags'. This utility function in turn calls another function
-(tt(_sort_tags)) and gives the list of tags to it as
-arguments. The function tt(_sort_tags) can then say in which order the 
-tags are to be used by the completion function. The function will 
-only generate those types of matches whose tags were selected by the
-user's implementation of the tt(_sort_tags) function. And it will
-try to generate the different types of matches in the order in which
-they were specified by tt(_sort_tags).
-
-Inside the tt(_sort_tags) function 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 and then 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:
-
-example(_sort_tags() {
-  case $curcontext in
-  (*::dvips:*)
-    comptry globbed-files directories
-    comptry all-files
-    ;;
-  (*)
-    comptry globbed-files
-    comptry directories
-    comptry all-files
-    ;;
-  esac
-})
-
-Every call to the tt(comptry) function (well, it's actually a builtin
-command defined by the tt(computil) module, but never mind) gives a
-set of tags to use. So, the first call says which tags are to be used 
-first. If there are no matches for those tags, the tags from the
-second call to tt(comptry) will be tried, and so on. 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)).
-
-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 tt(_sort_tags) 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 tt(_sort_tags) function:
-
-example(_sort_tags() {
-  comptry arguments options
-  case $curcontext in
-  ...
-  esac
-})
+matches, often multiple types of matches.  These types are represented as
+simple names called `tags'.  The completion system will decide internally
+what sort of tags are allowed; a list of the standard possibilities is given
+below.  The list of tags is passed as the arguments of the function
+(tt(_sort_tags)), which can then determine the order in which the  tags are
+to be used by the completion function.  Only those types of matches whose
+tags were selected by the tt(_sort_tags) function will be produced, and in
+the order given.  Instead of altering tt(_sort_tags), you may define
+a `tt(sort-tags)' style for the appropriate context, as described in the
+list of standard styles below.
 
-or
-
-example(_sort_tags() {
-  comptry arguments
-  comptry options
-  case $curcontext in
-  ...
-  esac
-})
-
-The former always adds both the matches for the argument and the
-option names as possible matches. The latter makes the matches for the 
-arguments be preferred. In this case option names are only generated
-as matches if the string on the line matches no possible completion
-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 tt(_sort_tags). 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.
-
 The tt(_complete_help) bindable command described in 
 ifzman(the section `Bindable Commands' below)\
 ifnzman(noderef(Bindable Commands))
-can be used to find out the contexts and tag names used by completion
-functions. If it is invoked, it shows a list of context names and the
+can be invoked to find out the context and tag names used at a particular
+point in completion.  It shows a list of context names and the 
 tag names used in those contexts if completion were tried at the
-current cursor position. This allows one to easily find out all the
-information needed to change the tt(_sort_tags) function when one
-wants to change the way matches are generated for that context.
-
-But the completion system can not only be configured by supplying a
-specialized tt(_sort_tags) function. It also uses `styles' defined
-with the tt(zstyle) builtin command (see
+current cursor position.  Hence one can easily find out all the
+information needed to change the behaviour of the tt(_sort_tags) function
+or the tt(sort_tags) style for a particular context.
+
+Completion behaviour can be modified by various other
+`styles' defined with the tt(zstyle) builtin command
+(see
 ifzman(zmanref(zshmodules))\
-ifnzman(noderef(The zutil Module))\
-) using the prefix `tt(:completion)' and the context name when testing 
-and retrieving values.
+ifnzman(noderef(The zutil Module))).
+The full context used in looking up styles is the prefix `tt(:completion)'
+followed by the context as described above, followed by another colon and
+the name of the tag currently being tried for completion.
+
+Styles determine such things as how the matches are generated; some of them
+correspond to shell options (for example, the use of menu completion), but
+styles provide more specific control.  They can have any number of strings as
+their value.  Looking up the value of a style therefore consists of two
+things:  the context, which may be matched as a pattern, and the name of
+the style itself, which must be given exactly.
 
-For some tags the completion functions look up the definition of
-certain styles set for the current context. These styles can have any
-number of strings as their values and specify, for example, how the
-matches are generated. The tt(zstyle) builtin command defines mappings
-between patterns and style names with their values. Whenever a
-completion function looks up the value of a style it uses the name of
-the current context followed by a colon and the name of a tag. This
-combined name and the name of a style is then compared to all patterns
-and the value of the style for the first matching pattern is used.
-
 For example, many completion functions can generate matches in a
 simple and a verbose form and use the tt(verbose) style to decide
 which form should be used. To make all such functions always use the
@@ -447,29 +345,32 @@
 
 in one of the startup files like tt(.zshrc). This definition simply
 means that the tt(verbose) style has tt(yes) as its value in every
-context.
-
-The completion function for the tt(kill) builtin command uses this
-style to decide if jobs and processes are listed only as job numbers
-and process identifiers or if they are listed with the full job texts
-and the command lines of the processes (the latter is achieved by
-calling the tt(ps) command). To make this builtin list the matches
-only as numbers one could call:
+context inside the completion system.  If the pattern were `tt(*)', it
+would mean that the verbose style had this value anywhere the style
+mechanism is used.
+
+As a more specific example, the completion function for the tt(kill)
+builtin command uses the tt(verbose) style to decide if jobs and processes
+are listed only as job numbers and process identifiers or if they are
+listed with the full job texts and the command lines of the processes (the
+latter is achieved by calling the tt(ps) command). To make this builtin
+list the matches only as numbers one could call:
 
 example(zstyle ':completion:*::kill:*' verbose no)
 
-And if one wants to see the command lines for processes but not the
+Furhtermore, if one wanted to see the command lines for processes but not the
 job texts one could use the fact that the tag name is appended to the
-context name when styles are looked up and instead of the previous
-call use (remember that the function for the tt(kill) builtin command
-uses the tags tt(jobs) and tt(processes)): 
+context name when styles are looked up.  As the function for the tt(kill)
+builtin command uses the tags tt(jobs) and tt(processes), we have:
 
 example(zstyle ':completion:*::kill:*:jobs' verbose no)
 
-Due to the ordering tt(zstyle) does with the patterns defined, the
-last two examples could be defined after the first one because both
-`tt(*::kill:*)' and `tt(*::kill:*:jobs)' are considered to be more
-specific then the pattern `tt(*)' from the first example.
+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 shorter patterns.
 
 As for tags, completion functions can use any number of styles, so
 there can't be a complete list. However, the following two sections
@@ -480,8 +381,8 @@
 cindex(completion system, tags)
 
 Here are the tags currently used by the completion system. Note that
-some of these tags are not really used when generating mathes but
-instead are only used by some completion functions when looking up
+some of these tags are not actually used while generating matches,
+but are only used by some completion functions when looking up
 styles.
 
 startitem()
@@ -523,7 +424,8 @@
 commands like tt(cvs))
 )
 item(tt(corrections))(
-used by the tt(_approximate) completer for the possible corrections
+used by the tt(_approximate) and tt(_correct) completers for the possible
+corrections
 )
 item(tt(cursors))(
 for cursor names used by X programs
@@ -630,8 +532,8 @@
 for command options
 )
 item(tt(original))(
-used by the tt(_approximate) and tt(_expand) completers when adding
-the original string
+used by the tt(_approximate), tt(_correct) and tt(_expand) completers when
+adding the original string
 )
 item(tt(other-accounts))(
 used to look up the tt(users-hosts) style
@@ -730,7 +632,7 @@
 item(tt(accept-exact))(
 This is tested for the default tag and the tags used when generating
 matches. If it is set to `true' for at least one match which is the
-same as the string on the line, this match will immediatly be
+same as the string on the line, this match will immediately be
 accepted.
 )
 item(tt(arguments))(
@@ -787,8 +689,8 @@
 This style is used by the tt(_list) completer function.
 
 If it is not set or set to the empty string, the insertion of
-matches will be delayed unconditionally. If this value is set, it
-should be set to an expression usable inside a `tt($((...)))'
+matches will be delayed unconditionally. If it is set, the value
+should be an expression usable inside a `tt($((...)))'
 arithmetical expression. In this case, delaying will be done if the
 expression evaluates to `tt(1)'. For example, with
 
@@ -910,15 +812,15 @@
 )
 item(tt(hidden))(
 If this is set to one of the `true' values, the matches for the tags
-for which this is set will not appear in the list, only the
+for which this is set will not appear in the list; only the
 description for the matches as set with the tt(format) style will be
 shown. If this is set to tt(all), not even the description will be
 displayed.
 
 Note that the matches will still be completed, they are just not shown 
-in the list. To avoid having some matches to be considered possible
-completions one can modify the tt(_sort_tags) function as described
-above.
+in the list. To avoid having matches considered as possible
+completions at all the tt(_sort_tags) function can be modified as described
+below.
 )
 item(tt(hosts))(
 A style holding the names of hosts that should be completed. If this
@@ -939,7 +841,8 @@
 item(tt(ignored-suffixes))(
 This style is used with the tt(files) tag and gives suffixes of
 filenames to ignore. The matches ignored will only be completed when
-there are no other matches.
+there are no other matches.  It it is a more configurable version
+of the shell parameter tt($fignore).
 )
 item(tt(insert-unambiguous))(
 This is used by the tt(_match) and tt(_approximate) completer
@@ -958,9 +861,10 @@
 tt(ALWAYS_LAST_PROMPT) option.
 )
 item(tt(list))(
-This is used by the tt(_oldlist) completer, the
-tt(_history_complete_word) bindable command and by the
-tt(incremental-complete-word) widget.
+This is used by the tt(_oldlist) completer (context
+`tt(:completion:oldlist)'), the tt(_history_complete_word) bindable command
+(context `tt(:completion:history-words)') and by the
+tt(incremental-complete-word) widget (context `tt(:completion:incremental)).
 
 For tt(_oldlist), if this is set to tt(always), then standard
 widgets which perform listing will retain the current list of matches,
@@ -1042,9 +946,9 @@
 area.
 )
 item(tt(max-errors))(
-This is used by the tt(_approximate) completer function to determine
-the maximum number of errors to accept. The completer will try to
-generate completions by first allowing one error, then two errors, and
+This is used by the tt(_approximate) and tt(_correct) completer functions
+to determine the maximum number of errors to accept. The completer will try
+to generate completions by first allowing one error, then two errors, and
 so on, until either a match was found or the maximum number of errors
 given by this style has been reached.
 
@@ -1059,7 +963,7 @@
 errors are accepted.  Hence with a value of `tt(0 numeric)', no correcting
 completion will be attempted unless a numeric argument is given.
 
-If the value contains the string tt(not-numeric), tt(_approximate)
+If the value contains the string tt(not-numeric), the completer
 will em(not) try to generate corrected
 completions when given a numeric argument, so in this case the number given
 should be greater than zero.  For example, `tt(2 not-numeric)' specifies that
@@ -1109,11 +1013,11 @@
 list of completions.
 )
 item(tt(original))(
-This is used by the tt(_approximate) and tt(_match) completers. The
-first one uses it to decide if the original string should be added as
-one possible completion. Normally, this is done only if there at least 
-two possible corrections, but if this style is set to `true', it will
-always be added.
+This is used by the tt(_approximate), tt(_correct) and tt(_match)
+completers. The first two use it to decide if the original string should
+be added as one possible completion. Normally, this is done only if there
+at least  two possible corrections, but if this style is set to `true', it
+will always be added.
 
 For the tt(_match) completer, if this style is set to
 tt(only), it will try to generate matches without inserting a
@@ -1192,6 +1096,31 @@
 as single strings (not in the string containing all possible
 expansions).
 )
+item(tt(sort-tags))(
+This provides a mechanism for sorting how the tags available in a
+particular context will be used.  It assumes you have not redefined the
+standard tt(_sort_tags) function.
+
+The values for the style are sets of space-separated lists of tags.
+The tags in each value will be tried at the same time; if no match is
+found, the next value is used.
+
+For example,
+
+example(
+  zstyle :completion:complete::gunzip: sort-tags \ 
+    'globbed-files directories' all-files
+)
+
+specifies that, when completing arguments of the command tt(gunzip),
+files generated by patterns (in this case, those ending in tt(.gz)) and
+any directories will be presented first, and if that fails, any other files
+will be tried.  If no valid tags are present, nothing will be completed. so
+this can be used to turn off completion in a particular context.
+
+If no style has been defined for a context, the tt(_sort_tags) function
+provides defaults, as given below.
+)
 item(tt(special-dirs))(
 Normally, the completion code will not produce the directory names
 tt(.) and tt(..) as possible completions. If this style is set to
@@ -1469,7 +1398,7 @@
 adding the original string from the line. In which order these strings 
 are generated and which of these strings are generated at all can be
 controlled by using the tt(group-order) style and by modifying the
-tt(_sort_tags) function, as usual.
+tt(sort-tags) style or tt(_sort_tags) function, as usual.
 
 The format string for tt(all-expansions) and for tt(expansions) may
 contain the sequence `tt(%o)' which will be replaced by the original
@@ -1582,7 +1511,7 @@
 automatically (normal completion is not available at this point) until a
 space is typed.
 
-Otherwise, any other string, will be passed as arguments to
+Any other string will be passed as a set of arguments to
 tt(compadd) and should hence be an expression specifying what should
 be completed.
 
@@ -1688,9 +1617,9 @@
 )
 findex(_message)
 item(tt(_message) var(descr))(
-The var(descr) used like the third
+The var(descr) is used like the third
 argument to the tt(_description) function. However, the resulting
-string will always be shown, not only if some matches were
+string will always be shown whether or not matches were
 generated. This is useful to display help texts in places where no
 completions can be generated automatically.
 
@@ -2285,63 +2214,61 @@
 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 generated function and rest arguments
-specifies a completion specification in the notation like regular
-expression with acions.  The generated function is formed as a state
-machine whose state corresponds each part of the specification of the
-completion. The state machine runs on a command line and evaluate actions
-when the command line is exhausted.  The command line is represented by
-single string that is generated by concatinating unquoted tt(words)
-(before tt(CURRENT)) and tt(PREFIX) using the null character as a
-separator.
+first argument specifies the name of a 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
+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
+quotation.  This is analysed and at the end the appropriate action is
+executed.
+
+Specification arguments take one of following forms, in which
+metacharacters such as `tt(LPAR())', `tt(RPAR())', `tt(#)' and `tt(|)'
+should be quoted.
 
-The specification is one of following forms.  (Metacharacters such as
-`tt(LPAR())', `tt(RPAR())', `tt(#)' and `tt(|)' should be quoted.)
 startitem()
 item(tt(/)var(pattern)tt(/) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(action)])(
-This is a primitive element for the specification and corresponds to the
-state of the compiled state machine.  When the state machine is trying to
-enter to this state, the state machine tries to match the pattern
-`tt((#b)LPAR()(#B))var(pattern)tt(RPAR()(#B))var(lookahead)tt(*)' against to
+This is a primitive element, corresponding to one
+state of the compiled state machine.  The state is entered if the pattern
+`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 it is success, the state machine is
-entered to this state.  Otherwise when the pattern match or the guard
-evaluation is failed, the state machine is failed to enter to this state
-and other candidates are tried.  If `var(pattern)' is the string `tt([])',
-it is treated as the pattern which never match.
-
-When the state machine is entered to this state, the left part of the
-command line string matched against to `var(pattern)' is removed and next
-states of this state are tried to enter with inner-to-outer, left-to-right
-fashion.
-
-If all tries are failed and remaining command line string contains no null
-character, completion target is restricted to correspondence of remaining
-command line string and `var(action)'s for the target is evaluated.  Since
-this state may not remove non-empty string from command line string,
-prior states and its neighborhoods may have `var(actions)'s for the
-target.
+its return status is examined; if this is successful, the state is entered,
+else the test fails and other candidates are tried.  The var(pattern)
+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 
+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.
+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.
 )
 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 this
-and prior states are ignored even if following state's `var(pattern)'
-matches empty string.
+This is similar to `tt(/)var(pattern)tt(/) ...' but `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)'.
 )
 item(var(spec) tt(#))(
-This is repetation of `var(spec)'.
+This allows any number of repetitions of `var(spec)'.
 )
 item(var(spec) var(spec))(
-This is concatination of two `var(spec)'s.
+This represents the concatenation of two `var(spec)'s.
 )
 item(var(spec) tt(|) var(spec))(
-This is alternation of two `var(spec)'s.
+Either of two `var(spec)'s can be matched.
 )
 enditem()
 )
@@ -2383,6 +2310,140 @@
 tt(compadd) used (when generating matches from the style value) and to 
 the functions for the fields if they are called.
 )
+findex(_sort_tags)
+item(tt(_sort_tags) var(tag) ...)(
+As described above, this may be redefined by the user, although a default
+implementation is provided.  In most cases, you will probably find it
+easier to define a tt(sort-tags) style for the context whose behaviour you
+wish to alter.
+
+Inside the tt(_sort_tags) function 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:
+
+example(_sort_tags() {
+  case $curcontext in
+  (*::dvips:*)
+    comptry globbed-files directories
+    comptry all-files
+    ;;
+  (*)
+    comptry globbed-files
+    comptry directories
+    comptry all-files
+    ;;
+  esac
+})
+
+Every call to the tt(comptry) function (actually a builtin
+command defined by the tt(computil) module) gives a
+set of tags to use; as soon as tt(comptry) produces some matches,
+subsequent calls 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)).
+
+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 tt(_sort_tags) 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 tt(_sort_tags) function:
+
+example(_sort_tags() {
+  comptry arguments options
+  case $curcontext in
+  ...
+  esac
+})
+
+or
+
+example(_sort_tags() {
+  comptry arguments
+  comptry options
+  case $curcontext in
+  ...
+  esac
+})
+
+The former always adds both the matches for the argument and the
+option names as possible matches. The latter forces matches for the
+arguments to be preferred. In this case option names are only generated
+as matches if the string on the line matches no possible completion
+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 tt(_sort_tags). 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.
+
+The default implementation of tt(_sort_tags) is the following:
+
+example(_sort_tags() {
+  local stags tag
+
+  if zstyle -a ":completion${curcontext}" sort-tags stags; then
+    for tag in $stags; do
+      [[ $tags != '' ]] && comptry ${=tag}
+    done
+
+  else		   
+    comptry arguments values
+    comptry options
+    case "$curcontext" in
+      (*) comptry globbed-files
+  	  comptry directories
+  	  comptry all-files
+          ;;
+    esac
+    comptry "$@"
+  fi
+})
+
+)
+
 enditem()
 
 texinode(Completion Directories)()(Completion Functions)(Completion System)
Index: Functions/Zle/incremental-complete-word
===================================================================
RCS file: /home/pws/CVSROOT/projects/zsh/Functions/Zle/incremental-complete-word,v
retrieving revision 1.3
diff -u -r1.3 incremental-complete-word
--- Functions/Zle/incremental-complete-word	1999/12/10 19:45:21	1.3
+++ Functions/Zle/incremental-complete-word	1999/12/14 17:04:26
@@ -20,11 +20,12 @@
   local lastl lastr wid twid num alt post toolong
   local curcontext="${curcontext}:incremental" stop brk
 
-  _style -s '' prompt pmpt || pmpt='incremental (%c): %u%s  %l}'
-  _style -s '' stop stop
-  _style -s '' break brk
+  zstyle -s ":completion${curcontext}" prompt pmpt ||
+    pmpt='incremental (%c): %u%s  %l'
+  zstyle -s ":completion${curcontext}" stop stop
+  zstyle -s ":completion${curcontext}" break brk
 
-  if _style '' list; then
+  if zstyle -t ":completion${curcontext}" list; then
     wid=list-choices
     post=( icw-list-helper )
   else

-- 
Peter Stephenson <pws@xxxxxxxxxxxxxxxxxxxxxxxx>