zsh-workers/9677

3 files changed, 28 insertions, 61 deletions

diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo
index b65666d5d..e8e47b1a2 100644
--- a/Doc/Zsh/compctl.yo
+++ b/Doc/Zsh/compctl.yo
@@ -131,10 +131,19 @@ the default.  In other words, completion will subsequently use the
 options specified by the tt(-D) flag.
 
 The form with tt(-M) as the first and only option defines global
-matching specifications, as described in 
+matching specifications (see
 ifzman(zshcompwid)\
 ifnzman(noderef(Matching Control))\
-.
+). The match specifications given will be used for every completion
+attempt (only when using tt(compctl), not with the new completion
+system) and are tried in the order in which they are defined until one 
+generates at least one match. E.g.:
+
+example(compctl -M '' 'm:{a-zA-Z}={A-Za-z}')
+
+This will first try completion without any global match specifications 
+(the empty string) and, if that generates no matches, will try case
+insensitive completion.
 
 texinode(Option Flags)(Alternative Completion)(Command Flags)(Programmable Completion Using compctl)
 sect(Option Flags)
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index c1b89ad56..88903fe53 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -12,17 +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 that with the function-based completions described here, it
-is also possible to use the 
-tt(compmatchers) special array to specify
-global matching control, such as case-insensitivity (`tt(abc)' will complete
-to a string beginning `tt(ABC)'), or wildcard behaviour on
-certain anchors (`tt(a-d)' will complete to abc-def as if there were a
-`tt(*)' after the `a').  See
-ifzman(the section `Matching Control' in zmanref(zshcompwid))\
-ifnzman(noderef(Matching Control))
-for further details.
-
 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
@@ -1594,7 +1583,8 @@ This completer allows to define a match specification (see
 ifzman(the section `Matching Control' in zmanref(zshcompwid))\
 ifnzman(noderef(Matching Control))\
 ) that is to be used by all following completers. This is comparable
-to the tt(compmatchers) special array, but gives finer control. The match
+to the global match specifications that can be defined for the
+tt(compctl) builtin, but gives much better control. The match
 specification to use is looked up using the tt(matcher) style. For
 this, the completer field of the context name will contain the string
 `tt(matcher-)var(n)', where `var(n)' is the number of the call to
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 99611f68b..d56c5e5d3 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -207,21 +207,6 @@ names with one of the suffixes from the tt(fignore) array and matches
 put into the alternate set using the tt(-a) option of the tt(compadd)
 builtin command (see below) are not counted.
 )
-item(tt(matcher))(
-When completion is performed with a global match specification as defined
-by
-
-indent(tt(compmatchers=)tt(LPAR()) var(spec1 ... specN ...) tt(RPAR()))
-
-this gives the number of the specification string currently in use.
-In this case, matching is performed with each specification in turn.
-)
-item(tt(matcher_string))(
-The global match specification string var(specN) currently used.
-)
-item(tt(total_matchers))(
-The total number of global match specifications.
-)
 item(tt(restore))(
 This is set to tt(auto) before a function is entered, which forces the
 special parameters mentioned above (tt(words), tt(CURRENT), tt(PREFIX),
@@ -741,7 +726,7 @@ enditem()
 texinode(Matching Control)(Examples)(Condition Codes)(Completion Widgets)
 sect(Matching Control)
 
-It is possible by use of the tt(compmatchers) special array and the
+It is possible by use of the 
 tt(-M) option of the tt(compadd) builtin command to specify how the
 characters in the string to be completed (referred to here as the
 command line) map onto the characters in the list of matches produced by
@@ -842,17 +827,16 @@ specification characters (tt(L) and tt(M)) guarantees that what has
 already been typed on the command line (in particular the prefix
 tt(no)) will not be deleted.
 
-The second example makes completion case insensitive.  By setting the
-tt(compmatchers) array this applies to every
-completion.  This is just the same as in the option example, except
-here we wish to retain the characters in the list of completions:
+The second example makes completion case insensitive.  This is just
+the same as in the option example, except here we wish to retain the
+characters in the list of completions:
 
-example(compmatchers=( 'm:{a-z}={A-Z}' ) )
+example(compadd -M 'm:{a-z}={A-Z}' ... )
 
 This makes lowercase letters match their uppercase counterparts.
 To make uppercase letters match the lowercase forms as well:
 
-example(compmatchers=( 'm:{a-zA-Z}={A-Za-z}' ) )
+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)
@@ -889,37 +873,21 @@ at the end of the trial completion.
 
 More generally, the specification
 
-example(compmatchers=( 'r:|[.,_-]=* r:|=*' ) )
+example(compadd -M 'r:|[.,_-]=* r:|=*' ... )
 
 allows one to complete words with abbreviations before any of the
-characters in the square brackets in any completion.  For example, to
+characters in the square brackets.  For example, to
 complete tt(veryverylongfile.c) rather than tt(veryverylongheader.h)
 with the above in effect, you can just type tt(very.c) before attempting
 completion.
 
-The tt(compmatchers) array that defines global matching can actually 
-contain any number of specification strings, unlike the case where the
-tt(-M) option is used with the tt(compadd) builtin command.  In this case, when
-completion is attempted for any command, the code will try the
-specifications in order until one matches.  This allows one to define
-simple and fast matches to be used first, more powerful matchers as a
-second choice, and so on.
-
-For example, one can make the code match trial completions that contain
-the string on the command line as a substring, not just at the
-beginning.  Since this might produce more matches than we want,
-we arrange for it to be tried only if the matchers described above don't
-produce any matches:
-
-example(compmatchers=( 'r:|[.,_-]=* r:|=*' 'l:|=* r:|=*' ) )
-
-Here, if the string on the command line is tt(foo.bar), the completion 
-code first tries matching tt(foo)var(anything)tt(.bar)var(anything), as
-with the previous example.  If that fails, the two descriptions in the
-second string say that the blanks at the beginning
-and end of the string on the command line can match any set of
-characters at the beginning or end of the trial completion, so it will
-look for var(anything)tt(foo.bar)var(anything).
+When using the completion system (see
+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.
 
 texinode(Examples)()(Matching Control)(Completion Widgets)
 sect(Examples)