zsh-workers/9809

1 files changed, 81 insertions, 76 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 119ff8f2b..92693b22e 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -12,12 +12,6 @@ completion code.  The shell functions of the second set which implement
 completion behaviour and which may be bound to keystrokes, are referred to
 as `widgets'.
 
-Note also, that it is possible to use old completion definitions using 
-the tt(compctl) builtin command together with the functions for the
-new completion system. To enable this, the tt(_default) function from
-the tt(Base) directory of the distribution should be copied and
-modified as described in that file.
-
 startmenu()
 menu(Initialization)
 menu(Completion System Configuration)
@@ -66,11 +60,7 @@ information, and your tt(.zshrc) will not be altered at all.
 After initialization all the builtin completion widgets such as
 tt(expand-or-complete) will be redefined to use the new completion system.
 Should you need to, you can still bind keys to the old functions by putting
-a `tt(.)' in front, e.g. `tt(.expand-or-complete)'. Note that this
-means that the tt(zsh/complist) module has to be loaded before the
-completion system is initialized (i.e. the tt(compinit) function is
-called) to make sure that the tt(menu-select) widget defined by it
-will be redefined, too.
+a `tt(.)' in front, e.g. `tt(.expand-or-complete)'.
 
 subsect(Use of compinit)
 findex(compinit)
@@ -85,7 +75,10 @@ directory mentioned in the tt($fpath) variable, and should be autoloaded
 (`tt(autoload -U compinit)' is recommended).  When run, it will define a
 few utility functions, arrange for all the necessary shell functions to be
 autoloaded, and will then re-bind all keys that do completion to use the
-new system.
+new system. Note that this means that the tt(zsh/complist) module has
+to be loaded before the completion system is initialized (i.e. the
+tt(compinit) function is called) to make sure that the tt(menu-select)
+widget defined by it will be redefined, too.
 
 To speed up the running of tt(compinit), it can be made to produce a dumped
 configuration which will be read in on future invocations; this is the
@@ -207,7 +200,7 @@ implicitly.
 
 subsect(Functions)
 
-The tt(compinit) file defines the following functions, which may
+The tt(compinit) file defines the following function, which may
 also be called directly by the user.
 
 findex(compdef)
@@ -275,7 +268,14 @@ 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 context names always consists of the following fields, separated
+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 
+hence the context name used for lookup may vary during the same call
+to the completion system.
+
+The context name always consists of the following fields, separated
 by colons:
 
 startitem()
@@ -305,11 +305,11 @@ item()(
 The var(context) or var(command). This is either one of the special
 context names such as tt(-condition-) as explained for the
 tt(_complete) completer below, or the name of the command we are
-completing arguments for. Commands that have sub-commands usually
-modify this field to contain the name of the command followed by a
-minus sign and the sub-command (e.g. the completion function for the
-tt(cvs) command sets this field to striings such as tt(cvs-add) when
-completing for the tt(add) sub-command).
+completing arguments for. Completion functions for commands that have
+sub-commands usually modify this field to contain the name of the
+command followed by a minus sign and the sub-command (e.g. the
+completion function for the tt(cvs) command sets this field to strings
+such as tt(cvs-add) when completing for the tt(add) sub-command).
 )
 item()(
 The var(argument), describing which argument we are
@@ -319,18 +319,18 @@ is a string of the form tt(-)var(opt)tt(-)var(n) when completing the
 var(n)'th argument of the option var(opt).
 )
 item()(
-The var(tag). Tags are used for two purposes: completion functions use 
-them to describe the types of matches they can generate for a certain
-context and they use them to simplify the definition of styles that
-are tested.
+The var(tag). Tags are used for two purposes:  to describe the types
+of matches a completion function can generate for a certain context
+and to simplify the definition of styles that are tested.
 )
 enditem()
 
-As an example, leaving out the var(tag) for the moment, the context name
+As an example, the context name
 `tt(:completion::complete:dvips:-o-1:files)' says that normal
 completion was attempted on an argument of the tt(dvips)
-command. More precisely: completion was attempted on the first
-argument after the tt(-o) option.
+command (more precisely: completion was attempted on the first
+argument after the tt(-o) option) and the completion function will
+generate filenames for this context.
 
 In many of the possible contexts the completion system can generate
 matches, often multiple types of matches.  These types are represented as
@@ -353,7 +353,7 @@ 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
+styles defined with the tt(zstyle) builtin command
 (see
 ifzman(zmanref(zshmodules))\
 ifnzman(noderef(The zsh/zutil Module))).
@@ -390,9 +390,9 @@ list the matches only as numbers one could call:
 example(zstyle ':completion:*:*:kill:*' verbose no)
 
 Furthermore, 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.  As the function for the tt(kill)
-builtin command uses the tags tt(jobs) and tt(processes), we have:
+job texts one could use the fact that the context name contains the tag name
+when styles are looked up.  As the function for the tt(kill)
+builtin command uses the tags tt(jobs) and tt(processes), we can use:
 
 example(zstyle ':completion:*:*:kill:*:jobs' verbose no)
 
@@ -710,9 +710,9 @@ example, to use completion, approximation and correction for normal
 completion, completion and correction for incremental completion and
 only completion for prediction one could use:
 
-example(zstyle ':completion:::::' completer _complete _correct _approximate
-zstyle ':completion:incremental::::' completer _complete _correct
-zstyle ':completion:predict::::' completer _complete)
+example(zstyle ':completion:*' completer _complete _correct _approximate
+zstyle ':completion:incremental:*' completer _complete _correct
+zstyle ':completion:predict:*' completer _complete)
 
 The default value for this style is tt(_complete), i.e. normally only
 completion will be done.
@@ -799,7 +799,7 @@ in certain contexts. It is tested by tt(_files) and, if called
 directly, tt(_path_files) with the tags mentioned above. If it is set
 for these tags, the value is taken as a list of glob-patterns that
 should be used to select filenames when completing for the tag. Note
-that with tt(_files), calling completion function may specify that
+that with tt(_files), calling completion functions may specify that
 all files are to be completed. Normally this would make tt(_files) use 
 only the tt(all-files) tag, but if this style is set for any of the
 other two tags (tt(globbed-files) and tt(directories)), these tags
@@ -832,7 +832,7 @@ tt(descriptions) tag. This gives the possibility to define different
 format strings for different types of matches.
 
 Note also that some completer functions define additional
-`tt(%)'-sequences. These are described for the completer function that 
+`tt(%)'-sequences. These are described for the completer functions that 
 make use of them.
 
 For the tt(messages) tag, this defines a string used by some
@@ -844,7 +844,7 @@ be generated at all. In this case the `tt(%d)' is replaced with the
 descriptions for the matches that were expected.
 
 Here and in all other cases where the completion system uses `tt(%)'
-sequences, the `tt(%)' may be followed by field with specifications as 
+sequences, the `tt(%)' may be followed by field width specifications as 
 described for the tt(zformat) builtin command from the tt(zutil)
 module, see
 ifzman(zmanref(zshmodules))\
@@ -899,7 +899,7 @@ For example, to have names of builtin commands, shell functions and
 external commands appear in this order when completing in command
 position one would set:
 
-example(zstyle ':completion:*:*:-command-' group-order builtins functions commands)
+example(zstyle ':completion:*:*:-command-:*' group-order builtins functions commands)
 )
 item(tt(groups))(
 A style holding the names of the groups that should be completed. If
@@ -958,8 +958,8 @@ will be placed in the alternate set of completions so that they will
 be completed if there are no other possible completions.
 )
 item(tt(ignored-patterns))(
-This style is used with the tags used when adding matches and gives a
-number of patterns. All matches that are matched by any of these
+This style is used with the tags used when adding matches and defines a
+couple of patterns. All matches that are matched by any of these
 patterns will be ignored as long as there are other matches not
 matched by any of the patterns.  It is a more configurable version
 of the shell parameter tt($fignore).
@@ -1119,8 +1119,8 @@ normal completion without a match specification and with
 case-insensitive matching first, correction if that doesn't generate
 any matches and partial-word completion if that doesn't yield any
 matches either. In such a case one can give the tt(_complete)
-completer more than once in the tt(completer) style and give different
-match specification to them, as in:
+completer more than once in the tt(completer) style and define different
+match specifications for them, as in:
 
 example(zstyle ':completion:*' completer _complete _correct _complete
 zstyle ':completion:*:complete-1:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'
@@ -1161,7 +1161,7 @@ correcting completion with two errors will usually be performed, but if a
 numeric argument is given, correcting completion will not be
 performed.
 
-The default value for this style contains tt(2) and tt(numeric).
+The default value for this style is `tt(2 numeric)'.
 )
 item(tt(menu))(
 This style is tested for the tt(default) tag and the tags used when
@@ -1175,7 +1175,7 @@ option should be used. Finally, if menucompletion is started by some
 other means (e.g. by setting the tt(MENU_COMPLETE) option) and the
 value for one of the tags used is `false' (i.e. tt(no), tt(false),
 tt(0), or tt(off)), then menucompletion will em(not) be started for
-this completions. Note that the values defined for normal tags
+this completion. Note that the values defined for normal tags
 override the value set for the tt(default) tag.
 
 Either instead of or in addition to one of the values above, the value
@@ -1184,11 +1184,10 @@ followed by an equal sign and a number. In this case menuselection
 (as defined by the tt(zsh/computil) module) will be started. Without the
 optional number, it will be started unconditionally and with a number
 it will be started only if at least that many matches are generated
-(if the values for more than one tag defines such a number, the
+(if the values for more than one tag define such a number, the
 smallest one is taken). Starting menuselection can explicitly be
 turned off by defining a value containing the string
-tt(no-select). Note that all this only works if the tt(complist)
-module is explicitly loaded by the user, though.
+tt(no-select).
 
 This is also used by the tt(_oldlist) completer. Here it controls how menu
 completion behaves when a completion has already been inserted and the
@@ -1217,7 +1216,8 @@ 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
-be added as one possible completion. Normally, this is done only if there
+be added as one possible completion. Normally, this is done only if
+there are
 at least  two possible corrections, but if this style is set to `true', it
 will always be added. Note that these completers use this style after
 setting the completer field in the context name to
@@ -1235,7 +1235,7 @@ item(tt(packageset))(
 A style containing an override for the default package set
 for that context.  For example,
 
-example(zstyle :completion:*:complete:dpkg:--status-1: packageset avail)
+example(zstyle ':completion:*:complete:dpkg:--status-1:' packageset avail)
 
 will cause available packages, rather than only installed packages,
 to be completed for `dpkg --status'.
@@ -1370,10 +1370,8 @@ found, the next value is used.
 
 For example,
 
-example(
-  zstyle ':completion:*:complete:gunzip:*' tag-order \ 
-    'globbed-files directories' all-files
-)
+example(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
@@ -1397,7 +1395,7 @@ of how such functions can be implemented.
 If no style has been defined for a context, the strings tt(arguments
 values), tt(options), tt(globbed-files), tt(directories) and
 tt(all-files) plus all tags offered by the completion function will be 
-used.
+used to provide a sensible default behavior.
 )
 item(tt(use-compctl))(
 If this style is set to a string not equal to tt(false), tt(0),
@@ -1412,7 +1410,7 @@ Note that this is only intended to smooth the transition from
 tt(compctl) to the new completion system and may disappear in the
 future.
 
-Note also, that the definitions from tt(compctl) will only be used if
+Note also that the definitions from tt(compctl) will only be used if
 there is no special completion function for the command completion is
 done upon.
 )
@@ -1431,9 +1429,9 @@ the hostnames for which there is a pair with that username is defined.
 
 If set for the tt(my-accounts) tag, this is used for commands such as
 tt(rlogin) and tt(ssh). I.e. the style should contain the names of the 
-user's own accounts. With the tt(other-accounts) this is used for
+user's own accounts. With the tt(other-accounts) tag this is used for
 commands such as tt(talk) and tt(finger) and should contain other
-people's accounts. Finally, this may also used by some commands with
+people's accounts. Finally, this may also be used by some commands with
 the tt(accounts) tag.
 )
 item(tt(verbose))(
@@ -1467,10 +1465,10 @@ arguments are given, the set of functions to try is taken from the
 tt(completer) style. For example, to use normal completion and
 correction if that doesn't generate any matches:
 
-example(zstyle ':completion:::::' completer _complete _correct)
+example(zstyle ':completion:*' completer _complete _correct)
 
-after calling tt(compinit). The default value for this style set up
-in tt(compinit) is `tt(_complete)', i.e. normally only ordinary
+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
 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
@@ -1539,7 +1537,7 @@ for adding completions before any other completion functions are
 tried; if this
 function sets the tt(_compskip) parameter to tt(all), no other
 completion functions will be called, if it is set to a string
-containing the string tt(patterns), no pattern completion functions
+containing the substring tt(patterns), no pattern completion functions
 will be called, and if it is set to a string containing tt(default)
 the function for the `tt(-default-)' context will not be called, but
 functions defined for commands will.
@@ -1579,7 +1577,7 @@ counted. The resulting list of corrected and completed strings is then
 presented to the user. The intended use of this completer function is to
 try after the normal tt(_complete) completer by setting:
 
-example(zstyle ':completion:::::' completer _complete _approximate)
+example(zstyle ':completion:*' completer _complete _approximate)
 
 This will give correcting completion if and only if
 normal completion doesn't yield any possible completions. When
@@ -1594,17 +1592,17 @@ accepted to generate the corrections and the original string,
 respectively.
 
 Like all completers tt(_approximate) uses its name without the
-undersccore as the top-level context name. Once it has started trying
-to generate matches, it will add another context name component
-containing the number of errors accepted in this attempt. So on the
-first try the context name starts with `tt(:approximate:1)', on the
-second try with `tt(:approximate:2)', and so on.
+undersccore in the var(completer) field of the context name. Once it
+has started trying to generate matches, it will append a minus sign
+and the number of errors accepted in this attempt to its name. So on the
+first try the field contains `tt(approximate-1)', on the
+second try `tt(approximate-2)', and so on.
 )
 findex(_correct)
 item(tt(_correct))(
 Generate corrections (but not completions) for the current word; this is
 similar to spell-checking.  This calls tt(_approximate) but uses a
-different top-level context name.
+different var(completer) field in the context name.
 
 For example, with:
 
@@ -1672,6 +1670,11 @@ The format string for tt(all-expansions) and for tt(expansions) may
 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)
+nad 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.
+
 In a different mode selected by the tt(completions) style, all
 em(completions) generated for the string on the line are inserted.
 )
@@ -1704,7 +1707,7 @@ the tt(completer) style to decide which other completers to call to
 try to generate matches. If this style is unset, the completers
 currently used by the whole completion are used -- except, of course,
 the tt(_prefix) completer itself. Also, if this completer appears more
-than once in the list of completers to use only those completers not
+than once in the list of completers only those completers not
 already tried by the last invocation of tt(_prefix) will be
 called. The completer field used to look up styles contains the string 
 `tt(prefix-)var(n)', where `var(n)' is the number of the call to
@@ -1712,17 +1715,17 @@ tt(_prefix).
 
 For example, consider this global tt(completer) style:
 
-example(zstyle ':completion:::::' completer _complete _prefix _correct _prefix)
+example(zstyle ':completion:*' completer _complete _prefix _correct _prefix)
 
 This makes the tt(_prefix) completer try normal completion with the
 suffix ignored. If that doesn't generate any matches and neither does
 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 do:
+want it to try only normal completion, you need to call:
 
-example(zstyle ':completion:::::' completer _complete ... _prefix
-zstyle ':completion::prefix-1:::' completer _complete)
+example(zstyle ':completion:*' completer _complete ... _prefix
+zstyle ':completion::prefix-1:*' completer _complete)
 
 The tt(add-space) style is used, too. If it is set to `true' then
 tt(_prefix) will insert a space between the matches generated (if any) 
@@ -1786,14 +1789,15 @@ standard output.
 findex(_correct_word) (^Xc)
 item(tt(_correct_word) (^Xc))(
 Performs correction of the current argument using the usual contextual
-completions as possible choices. This uses the top-level context name
-`tt(:correct-word)' and then calls the tt(_correct) completer.
+completions as possible choices. This stores the string
+`tt(correct-word)' in the var(function) field of the context name and
+then calls the tt(_correct) completer.
 )
 findex(_expand_word (^Xe))
 item(tt(_expand_word (^Xe)))(
 Performs expansion on the current word:  equivalent to the standard
 tt(expand-word) command, but using the tt(_expand) completer. Before
-calling it, the top-level context name is set to `tt(:expand-word)'.
+calling it, the var(function) field is set to `tt(expand-word)'.
 )
 findex(_history_complete_word) (\e/)
 item(tt(_history_complete_word) (\e/))(
@@ -1833,7 +1837,8 @@ read, call tt(_read_comp) with a numeric argument.
 )
 findex(_complete_help (^Xh))
 item(tt(_complete_help (^Xh)))(
-This widget displays information about the context names and tags used 
+This widget displays information about the context names, including
+the tags, and the completion functions used 
 when completing at the current cursor position.
 )
 enditem()