manual/9058

1 files changed, 47 insertions, 64 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index ba863cfe8..07dca151c 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -302,13 +302,11 @@ In many of the possible contexts the completion system can generate
 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.
+below.  To determine in which order the tags are to be used by the
+completion function, the `tt(tag-order)' style for the appropriate
+context may be set, as described in the list of standard styles below.
+Only those types of matches whose tags were selected by this style
+will be produced, and in the order given.
 
 The tt(_complete_help) bindable command described in 
 ifzman(the section `Bindable Commands' below)\
@@ -317,8 +315,8 @@ 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.  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.
+information needed to change the behaviour of the tt(tag-order) style
+for a particular context.
 
 Completion behaviour can be modified by various other
 `styles' defined with the tt(zstyle) builtin command
@@ -756,9 +754,9 @@ ifnzman(noderef(The zutil Module))\
 .
 )
 item(tt(glob))(
-Like tt(complete), this is used by the tt(_expand) completer.
+Like tt(completions), this is used by the tt(_expand) completer.
 
-The value is used like the one for tt(complete) and if it evaluates to 
+The value is used like the one for tt(completions) and if it evaluates to 
 `tt(1)', globbing will be attempted on the words resulting from
 substitution (see the tt(substitute) style) or the original string
 from the line.
@@ -819,7 +817,7 @@ displayed.
 
 Note that the matches will still be completed, they are just not shown 
 in the list. To avoid having matches considered as possible
-completions at all the tt(_sort_tags) function can be modified as described
+completions at all the tt(tag-order) style can be modified as described
 below.
 )
 item(tt(hosts))(
@@ -1012,6 +1010,15 @@ tt(TAB) at this point would start trying to complete the line as it now
 appears.  With tt(_oldlist), it will instead continue to cycle through the
 list of completions.
 )
+item(tt(numbers))(
+This is used with the tt(jobs) tag. If it is `true', the completions
+will use the job numbers instead of the shortest unambiguous strings
+of the jobs' command lines. If the value is a number, job numbers will 
+only be used if for at least one of the jobs that many (or more) words 
+from the command line string have to be used to make the strings
+unambiguous. E.g. if it is set to `tt(1)', strings will only be used
+if all jobs differ in the first word on their command lines.
+)
 item(tt(original))(
 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
@@ -1096,10 +1103,9 @@ to tt(menu), then the expansions are only sorted when they are offered
 as single strings (not in the string containing all possible
 expansions).
 )
-item(tt(sort-tags))(
+item(tt(tag-order))(
 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.
+particular context will be used.
 
 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
@@ -1108,18 +1114,27 @@ found, the next value is used.
 For example,
 
 example(
-  zstyle :completion:complete::gunzip: sort-tags \ 
+  zstyle :completion:complete::gunzip: tag-order \ 
     '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.
+will be tried.  If any string in the value consists of only a hyphen
+(`tt(-)'), then only the tags selected by the other strings will be
+generated. Normally all tags not explicitly selected will be tried at
+the end if the selected tags did not generate any matches.  This means 
+that a value of only one hyphen turns off completion in a particular
+context.
+
+Strings in the value may also be of the form `var(func)tt(())'. In
+this case the function var(func) will be called which can then define
+in which order tags are to be used based on additional context
+information. See the tt(_sort_tags) function below for a description
+of how such functions can be implemented.
 
-If no style has been defined for a context, the tt(_sort_tags) function
-provides defaults, as given below.
+If no style has been defined for a context, all tags will be used.
 )
 item(tt(special-dirs))(
 Normally, the completion code will not produce the directory names
@@ -1133,11 +1148,6 @@ command will always insert matches as if menucompletion were started
 and it will stop when the last match is inserted. If this style is set
 to tt(verbose) a message will be displayed when the last match is reached.
 )
-item(tt(strings))(
-This is used with the tt(jobs) tag. If it is `true', the completions
-will use the shortest unambiguous strings of the jobs' command lines
-instead of the job numbers.
-)
 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
@@ -1399,7 +1409,7 @@ adding the possible expansions as single matches and tt(original) when
 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) style or tt(_sort_tags) function, as usual.
+tt(tag-order) style, 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
@@ -1642,7 +1652,7 @@ item(tt(_tags) [ tt(-C) var(name) [ var(tags) ... ] ])(
 If called with arguments, these are taken as the names of the tags for 
 the types of matches the calling completion function can generate in
 the current context. These tags are stored internally and sorted by
-calling the tt(_sort_tags) function. Following calls to this function
+using the tt(tag-order) style. Following calls to this function
 without arguments from the same function will then select the first,
 second, etc. set of tags requested by the user. To test if a certain
 tag should be tried, the tt(_requested) function has to be called (see 
@@ -1654,10 +1664,9 @@ non-zero otherwise.
 This function also accepts the tt(-C) option followed by a
 var(name). This name is temporarily (i.e. not visible outside
 tt(_tags)) appended (with a colon before it) to the contents of the
-tt(curcontext) parameter. This allows to make tt(_tags) and
-tt(_sort_tags) use a more specific context name without having to
-change and reset the tt(curcontext) parameter (which would otherwise
-have the same effect).
+tt(curcontext) parameter. This allows to make tt(_tags) use a more
+specific context name without having to change and reset the
+tt(curcontext) parameter (which would otherwise have the same effect).
 )
 findex(_requested)
 item(tt(_requested) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])(
@@ -2313,12 +2322,10 @@ 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.
+As described above for the tt(tag-order) style, this is only provided
+to show how functions that sort tags can be implemented.
 
-Inside the tt(_sort_tags) function the name of the current context can
+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
@@ -2357,7 +2364,7 @@ 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
+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 
@@ -2365,7 +2372,7 @@ 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:
+you may write in your sorting function:
 
 example(_sort_tags() {
   comptry arguments options
@@ -2395,8 +2402,8 @@ 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
+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:
 
@@ -2419,30 +2426,6 @@ 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()