manual/8478

9 files changed, 233 insertions, 224 deletions

diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo
index b55aa91be..b65666d5d 100644
--- a/Doc/Zsh/compctl.yo
+++ b/Doc/Zsh/compctl.yo
@@ -1,4 +1,4 @@
-texinode(Programmable Completion Using compctl)(Completion Widgets)(Zsh Line Editor)(Top)
+texinode(Programmable Completion Using compctl)(Zsh Modules)(Completion Widgets)(Top)
 chapter(Programmable Completion Using compctl)
 cindex(completion, programmable)
 cindex(completion, controlling)
@@ -47,7 +47,6 @@ menu(Command Flags)
 menu(Option Flags)
 menu(Alternative Completion)
 menu(Extended Completion)
-menu(Matching Control)
 menu(Example)
 endmenu()
 
@@ -132,8 +131,10 @@ 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 below in noderef(Matching
-Control).
+matching specifications, as described in 
+ifzman(zshcompwid)\
+ifnzman(noderef(Matching Control))\
+.
 
 texinode(Option Flags)(Alternative Completion)(Command Flags)(Programmable Completion Using compctl)
 sect(Option Flags)
@@ -523,7 +524,10 @@ different name spaces.
 item(tt(-M) var(match-spec))(
 This defines additional matching control specifications that should be used
 only when testing words for the list of flags this flag appears in. The format
-of the var(match-spec) string is described below in noderef(Matching Control).
+of the var(match-spec) string is described in 
+ifzman(zshcompwid)\
+ifnzman(noderef(Matching Control))\
+.
 )
 enditem()
 
@@ -542,7 +546,7 @@ up to that point, default completion is tried.
 If the list of flags contains a tt(-t) with a tt(PLUS()) character, the next
 list of flags is used even if the current list produced matches.
 
-texinode(Extended Completion)(Matching Control)(Alternative Completion)(Programmable Completion Using compctl)
+texinode(Extended Completion)(Example)(Alternative Completion)(Programmable Completion Using compctl)
 sect(Extended Completion)
 startlist()
 list(nofill(tt(compctl) [ tt(-CDT) ] var(options) \
@@ -653,190 +657,7 @@ completion is done in backticks and var(str) starts with a `b'.
 )
 enditem()
 
-texinode(Matching Control)(Example)(Extended Completion)(Programmable Completion Using compctl)
-sect(Matching Control)
-
-It is possible by use of the tt(-M) var(spec) flag 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
-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 var(spec) 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
-handled in this fashion must match exactly, as usual.
-
-The forms of var(spec) understood are as follows. In each case, the
-form with an uppercase initial character retains the string already
-typed on the command line as the final result of completion, while with
-a lowercase initial character the string on the command line is changed
-into the corresponding part of the trial completion.
-
-startitem()
-xitem(tt(m:)var(lpat)tt(=)var(tpat))
-item(tt(M:)var(lpat)tt(=)var(tpat))(
-Here, var(lpat) is a pattern that matches on the command line,
-corresponding to var(tpat) which matches in the trial completion.
-)
-xitem(tt(l:)var(anchor)tt(|)var(lpat)tt(=)var(tpat))
-item(tt(L:)var(anchor)tt(|)var(lpat)tt(=)var(tpat))(
-These letters are for patterns that are anchored by another pattern on
-the left side. Matching for var(lpat) and var(tpat) is as for tt(m) and
-tt(M), but the pattern var(lpat) matched on the command line must be
-preceeded by the pattern var(anchor).  The var(anchor) can be blank to
-anchor the match to the start of the command line string; otherwise the
-anchor can occur anywhere, but must match in both the command line and
-trial completion strings.
-)
-xitem(tt(r:)var(lpat)tt(|)var(anchor)tt(=)var(tpat))
-item(tt(R:)var(lpat)tt(|)var(anchor)tt(=)var(tpat))(
-As tt(l) and tt(L) with the difference that the command line and trial
-completion patterns are anchored on the right side.  Here an empty
-var(anchor) forces the match to the end of the command line string.
-)
-enditem()
-
-Each var(lpat), var(tpat) or var(anchor) is either an empty string or
-consists of a sequence of literal characters (which may be quoted with a
-backslash), question marks, character classes, and correspondence
-classes; ordinary shell patterns are not used.  Literal characters match
-only themselves, question marks match any character, and character
-classes are formed as for globbing and match any character in the given
-set.
-
-Correspondence classes are defined like character classes, but with two
-differences: they are delimited by a pair of braces, and negated classes
-are not allowed, so the characters tt(!) and tt(^) have no special
-meaning directly after the opening brace.  They indicate that a range of
-characters on the line match a range of characters in the trial
-completion, but (unlike ordinary character classes) paired according to
-the corresponding position in the sequence. For example, to make any
-lowercase letter on the line match the corresponding uppercase letter in
-the trial completion, you can use `tt(m:{a-z}={A-Z})'.  More than one
-pair of classes can occur, in which case the first class before the
-tt(=) corresponds to the first after it, and so on.  If one side has
-more such classes than the other side, the superfluous classes behave
-like normal character classes. In anchor patterns correspondence classes
-also behave like normal character classes.
-
-The pattern var(tpat) may also be a single star, `tt(*)'. This means
-that the pattern on the command line can match any number of characters
-in the trial completion. In this case the pattern must be anchored (on
-either side); the var(anchor) then determines how much of the trial
-completion is to be included --- only the characters up to the next
-appearance of the anchor will be matched.
-
-Examples:
-
-The option tt(-o) produces option names in all-lowercase form, without
-underscores, and without the optional tt(no) at the beginning even
-though the builtins tt(setopt) and tt(unsetopt) understand option names
-with uppercase letters, underscores, and the optional tt(no).  The
-following alters the matching rules so that the prefix tt(no) and any
-underscore are ignored when trying to match the trial completions
-generated and uppercase letters on the line match the corresponding
-lowercase letters in the words:
-
-example(compctl -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' \ 
-  -o setopt unsetopt)
-
-The first part says that the pattern `tt([nN][oO])' at the beginning
-(the empty anchor before the pipe symbol) of the string on the
-line matches the empty string in the list of words generated by
-completion, so it will be ignored if present. The second part does the
-same for an underscore anywhere in the command line string, and the
-third part uses correspondence classes so that any
-uppercase letter on the line matches the corresponding lowercase
-letter in the word. The use of the uppercase forms of the
-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 using
-tt(compctl) with the tt(-M) option alone this applies to every
-completion.  This is just the same as in the tt(setopt) example, except
-here we wish to retain the characters in the list of completions:
-
-example(compctl -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(compctl -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
-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:
-
-example(compctl -M 'r:|.=* r:|=*' \ 
-  -k '(comp.sources.unix comp.sources.misc ...)' ngroups)
-
-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
-except for the `tt(.)' from the anchor in
-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
-the last part of the completion is just as normal.
-
-The second specification is needed to make this work when the cursor is
-in the middle of the string on the command line and the option
-tt(COMPLETE_IN_WORD) is set. In this case the completion code would
-normally try to match trial completions that end with the string as
-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
-empty string at the end of the string on the line matches any characters
-at the end of the trial completion.
-
-More generally, the specification
-
-example(compctl -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
-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 form tt(compctl -M) that defines global matching actually accepts
-any number of specification strings, unlike the case where the tt(-M)
-option applies only to a particular 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. These global matchers can also be defined by 
-setting the tt(compmatchers) special array to the strings that would
-otherwise be given to tt(compctl -M) as arguments.
-
-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(compctl -M 'r:|[.,_-]=* r:|=*' 'l:|=* r:|=*')
-
-Here, if the string on the command line is tt(foo.bar), tt(compctl)
-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 after the tt(-M) 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).
-
-texinode(Example)()(Matching Control)(Programmable Completion Using compctl)
+texinode(Example)()(Extended Completion)(Programmable Completion Using compctl)
 sect(Example)
 
 example(compctl -u -x 's[tt(PLUS())] c[-1,-f],s[-f+PLUS()]' \ 
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index a6ebeef6b..d741ee9c0 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -19,7 +19,7 @@ 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(zshcompctl))\
+ifzman(the section `Matching Control' in zmanref(zshcompwid))\
 ifnzman(noderef(Matching Control))
 for further details.
 
@@ -383,7 +383,7 @@ for completing the name of a parameter expansion within braces
 )
 item(tt(-first-))(
 for adding completions before any other other completion functions are
-tried (similar to the `tt(-T)' flag of tt(compctl)); if this
+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 `tt(patterns)', no pattern completion functions will be
@@ -392,12 +392,10 @@ function for the `tt(-default-)' context will not be called, but
 functions defined for commands will.
 )
 item(tt(-default-))(
-for generating completions when no special completion function is used 
-(similar to the `tt(-D)' option of tt(compctl)).
+for generating completions when no special completion function is used.
 )
 item(tt(-command-))(
-for completing in a command position (as with the `tt(-C)' option of
-tt(compctl)).
+for completing in a command position.
 )
 enditem()
 
@@ -696,15 +694,21 @@ to the tt(compadd) builtin used to add the matches.
 )
 item(tt(_path_files) and tt(_files))(
 The function tt(_path_files) is used throughout the shell code
-to complete filenames. The advantage over the builtin
-completion functions is that it allows completion of partial paths. For
+to complete filenames. It allows completion of partial paths. For
 example, the string `tt(/u/i/s/sig)' may be completed to
-`tt(/usr/include/sys/signal.h)'.  The options `tt(-/)', `tt(-f)', `tt(-g)',
-and `tt(-W)' are available as for the tt(compctl)
-and builtin command; tt(-f) is the default. Additionally, the `tt(-F)'
+`tt(/usr/include/sys/signal.h)'.  The option `tt(-/)' specifies that
+only directories should be completed. The option `tt(-g) var(pattern)' 
+says that only files matching the var(pattern) should be completed,
+and the `tt(-f)' option, which is the default, completes all
+filenames. The option `tt(-W) var(paths)' may be used to specify path
+prefixes that are to be prepended to the string from the line to
+generate the filenames but that should not be inserted in the line or
+shown in a completion listing. The var(paths) may be the name of an
+array parameter or a literal list of paths enclosed in parentheses.
+Additionally, the `tt(-F)'
 option from the tt(compadd) builtin is supported, giving direct control
-over which filenames should be ignored as done by the tt(fignore)
-parameter in normal completion.
+over which filenames should be ignored. If no such option is given,
+the tt(fignore) parameter is used.
 
 The function tt(_files) calls tt(_path_files) with all the arguments
 it was passed and, if that generated no matches, calls tt(_path_files) again
@@ -1488,7 +1492,7 @@ item(tt(approximate_prompt))(
 This can be set to a string to be displayed on top of the
 corrected strings generated when cycling through them. This string
 may contain the control sequences `tt(%n)', `tt(%B)', etc. known from
-the `tt(-X)' option of tt(compctl). Also, the sequence `tt(%e)' will
+the `tt(-X)' option of tt(compadd). Also, the sequence `tt(%e)' will
 be replaced by the number of errors accepted to generate the corrected 
 strings.
 )
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index c22a7bb14..fc2285e40 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -1,4 +1,4 @@
-texinode(Completion Widgets)(Zsh Modules)(Programmable Completion Using compctl)(Top)
+texinode(Completion Widgets)(Programmable Completion Using compctl)(Zsh Line Editor)(Top)
 chapter(Completion Widgets)
 cindex(completion, widgets)
 cindex(completion, programmable)
@@ -33,6 +33,7 @@ startmenu()
 menu(Special Parameters)
 menu(Builtin Commands)
 menu(Condition Codes)
+menu(Matching Control)
 menu(Examples)
 endmenu()
 
@@ -364,7 +365,7 @@ xitem(tt(compadd) [ tt(-qQfenUaml12) ] [ tt(-F) var(array) ])
 xitem([ tt(-P) var(prefix) ] [ tt(-S) var(suffix) ])
 xitem([ tt(-p) var(hidden-prefix) ] [ tt(-s) var(hidden-suffix) ])
 xitem([ tt(-i) var(ignored-prefix) ] [ tt(-I) var(ignored-suffix) ])
-xitem([ tt(-W) var(file-prefix) ] [ tt(-y) var(array) ] [ tt(-d) var(array) ])
+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) ])
@@ -541,7 +542,8 @@ code not to quote any metacharacters in the words when inserting them
 into the command line.
 )
 item(tt(-M) var(match-spec))(
-This gives local match specifications.
+This gives local match specifications as described below in
+noderef(Matching Control).
 Note that they will only be used if the tt(-U) option is not given.
 )
 item(tt(-n))(
@@ -552,10 +554,6 @@ item(tt(-U))(
 If this flag is given, all words given will be accepted and no matching
 will be done by the completion code. Normally this is used in
 functions that do the matching themselves.
-
-Note that with tt(compadd) this option does not automatically turn on
-menu completion if tt(AUTO_LIST) is set, unlike the corresponding option of
-tt(compctl).
 )
 item(tt(-O) var(array))(
 If this option is given, the var(words) are em(not) added to the set of
@@ -693,7 +691,7 @@ Note that this builtin is defined by the tt(compctl) module.
 )
 enditem()
 
-texinode(Condition Codes)(Examples)(Builtin Commands)(Completion Widgets)
+texinode(Condition Codes)(Matching Control)(Builtin Commands)(Completion Widgets)
 sect(Condition Codes)
 cindex(completion widgets, condition codes)
 
@@ -719,26 +717,209 @@ true if the test for the tt(-N) option with both patterns would succeed.
 )
 enditem()
 
-texinode(Examples)()(Condition Codes)(Completion Widgets)
+texinode(Matching Control)(Examples)(Condition Codes)(Completion Widgets)
+sect(Matching Control)
+
+It is possible by use of the tt(compmatchers) special array and 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
+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 var(spec) 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
+handled in this fashion must match exactly, as usual.
+
+The forms of var(spec) understood are as follows. In each case, the
+form with an uppercase initial character retains the string already
+typed on the command line as the final result of completion, while with
+a lowercase initial character the string on the command line is changed
+into the corresponding part of the trial completion.
+
+startitem()
+xitem(tt(m:)var(lpat)tt(=)var(tpat))
+item(tt(M:)var(lpat)tt(=)var(tpat))(
+Here, var(lpat) is a pattern that matches on the command line,
+corresponding to var(tpat) which matches in the trial completion.
+)
+xitem(tt(l:)var(anchor)tt(|)var(lpat)tt(=)var(tpat))
+item(tt(L:)var(anchor)tt(|)var(lpat)tt(=)var(tpat))(
+These letters are for patterns that are anchored by another pattern on
+the left side. Matching for var(lpat) and var(tpat) is as for tt(m) and
+tt(M), but the pattern var(lpat) matched on the command line must be
+preceeded by the pattern var(anchor).  The var(anchor) can be blank to
+anchor the match to the start of the command line string; otherwise the
+anchor can occur anywhere, but must match in both the command line and
+trial completion strings.
+)
+xitem(tt(r:)var(lpat)tt(|)var(anchor)tt(=)var(tpat))
+item(tt(R:)var(lpat)tt(|)var(anchor)tt(=)var(tpat))(
+As tt(l) and tt(L) with the difference that the command line and trial
+completion patterns are anchored on the right side.  Here an empty
+var(anchor) forces the match to the end of the command line string.
+)
+enditem()
+
+Each var(lpat), var(tpat) or var(anchor) is either an empty string or
+consists of a sequence of literal characters (which may be quoted with a
+backslash), question marks, character classes, and correspondence
+classes; ordinary shell patterns are not used.  Literal characters match
+only themselves, question marks match any character, and character
+classes are formed as for globbing and match any character in the given
+set.
+
+Correspondence classes are defined like character classes, but with two
+differences: they are delimited by a pair of braces, and negated classes
+are not allowed, so the characters tt(!) and tt(^) have no special
+meaning directly after the opening brace.  They indicate that a range of
+characters on the line match a range of characters in the trial
+completion, but (unlike ordinary character classes) paired according to
+the corresponding position in the sequence. For example, to make any
+lowercase letter on the line match the corresponding uppercase letter in
+the trial completion, you can use `tt(m:{a-z}={A-Z})'.  More than one
+pair of classes can occur, in which case the first class before the
+tt(=) corresponds to the first after it, and so on.  If one side has
+more such classes than the other side, the superfluous classes behave
+like normal character classes. In anchor patterns correspondence classes
+also behave like normal character classes.
+
+The pattern var(tpat) may also be a single star, `tt(*)'. This means
+that the pattern on the command line can match any number of characters
+in the trial completion. In this case the pattern must be anchored (on
+either side); the var(anchor) then determines how much of the trial
+completion is to be included --- only the characters up to the next
+appearance of the anchor will be matched.
+
+Examples:
+
+The keys of the tt(options) association defined by the tt(parameter)
+module are the option names in all-lowercase form, without
+underscores, and without the optional tt(no) at the beginning even
+though the builtins tt(setopt) and tt(unsetopt) understand option names
+with uppercase letters, underscores, and the optional tt(no).  The
+following alters the matching rules so that the prefix tt(no) and any
+underscore are ignored when trying to match the trial completions
+generated and uppercase letters on the line match the corresponding
+lowercase letters in the words:
+
+example(compadd -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' - \ 
+  ${(k)options} )
+
+The first part says that the pattern `tt([nN][oO])' at the beginning
+(the empty anchor before the pipe symbol) of the string on the
+line matches the empty string in the list of words generated by
+completion, so it will be ignored if present. The second part does the
+same for an underscore anywhere in the command line string, and the
+third part uses correspondence classes so that any
+uppercase letter on the line matches the corresponding lowercase
+letter in the word. The use of the uppercase forms of the
+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:
+
+example(compmatchers=( '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}' ) )
+
+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
+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:
+
+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
+except for the `tt(.)' from the anchor in
+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
+the last part of the completion is just as normal.
+
+The second specification is needed to make this work when the cursor is
+in the middle of the string on the command line and the option
+tt(COMPLETE_IN_WORD) is set. In this case the completion code would
+normally try to match trial completions that end with the string as
+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
+empty string at the end of the string on the line matches any characters
+at the end of the trial completion.
+
+More generally, the specification
+
+example(compmatchers=( 'r:|[.,_-]=* r:|=*' ) )
+
+allows one to complete words with abbreviations before any of the
+characters in the square brackets in any completion.  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).
+
+texinode(Examples)()(Matching Control)(Completion Widgets)
 sect(Examples)
 cindex(completion widgets, examples)
 
 The first step is to define the widget:
 
-example(zle -C complete complete-word complete-history)
+example(zle -C complete complete-word complete-files)
 
 Then the widget can be bound to a key using the tt(bindkey) builtin
 command:
 
 example(bindkey '^X\t' complete)
 
-After that the shell function tt(complete-history) will be invoked
+After that the shell function tt(complete-files) will be invoked
 after typing control-X and TAB. The function should then generate the
 matches, e.g.:
 
-example(complete-history LPAR()RPAR() { compadd - $historywords })
+example(complete-filles LPAR()RPAR() { compadd - * })
 
-This function will complete words from the history matching the 
+This function will complete files in the current directory matching the 
 current word.
 
 For a description of the widget-based completion system provided with the
diff --git a/Doc/Zsh/intro.yo b/Doc/Zsh/intro.yo
index 0e4e1048f..fa593b76d 100644
--- a/Doc/Zsh/intro.yo
+++ b/Doc/Zsh/intro.yo
@@ -20,8 +20,8 @@ list(em(zshparam)     Zsh parameters)
 list(em(zshoptions)   Zsh options)
 list(em(zshbuiltins)  Zsh built-in functions)
 list(em(zshzle)       Zsh command line editing)
-list(em(zshcompctl)   Zsh completion control)
 list(em(zshcompwid)   Zsh completion widgets)
+list(em(zshcompctl)   Zsh completion control)
 list(em(zshmodules)   Zsh loadable modules)
 list(em(zshcompsys)   Zsh completion system)
 ifzshone(\
diff --git a/Doc/Zsh/manual.yo b/Doc/Zsh/manual.yo
index 16a1bdec6..30c8a0345 100644
--- a/Doc/Zsh/manual.yo
+++ b/Doc/Zsh/manual.yo
@@ -28,8 +28,8 @@ menu(Parameters)
 menu(Options)
 menu(Shell Builtin Commands)
 menu(Zsh Line Editor)
-menu(Programmable Completion Using compctl)
 menu(Completion Widgets)
+menu(Programmable Completion Using compctl)
 menu(Zsh Modules)
 menu(Completion System)
 menu(Zftp Function System)
diff --git a/Doc/Zsh/mod_complete.yo b/Doc/Zsh/mod_complete.yo
index 558bbc4ae..0443fcde8 100644
--- a/Doc/Zsh/mod_complete.yo
+++ b/Doc/Zsh/mod_complete.yo
@@ -1,6 +1,6 @@
 texinode(The complete Module)(The compctl Module)(The clone Module)(Zsh Modules)
 sect(The complete Module)
-The tt(compctl) module makes available several builtin commands which
+The tt(complete) module makes available several builtin commands which
 can be used in user-defined completion widgets, see
 ifzman(zmanref(zshcompwid))\
 ifnzman(noderef(Completion Widgets))\
diff --git a/Doc/Zsh/modules.yo b/Doc/Zsh/modules.yo
index 9ce81c264..827f68b4c 100644
--- a/Doc/Zsh/modules.yo
+++ b/Doc/Zsh/modules.yo
@@ -1,4 +1,4 @@
-texinode(Zsh Modules)(Completion System)(Completion Widgets)(Top)
+texinode(Zsh Modules)(Completion System)(Programmable Completion Using compctl)(Top)
 chapter(Zsh Modules)
 cindex(modules)
 sect(Description)
@@ -15,6 +15,9 @@ Builtins for manipulating POSIX.1e (POSIX.6) capability (privilege) sets.
 item(tt(clone))(
 A builtin that can clone a running shell onto another terminal.
 )
+item(tt(complete))(
+The basic completion code.
+)
 item(tt(compctl))(
 The tt(compctl) builtin for controlling completion and the builtins for
 completion widgets.
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 17fe7b345..baca81e62 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -1,4 +1,4 @@
-texinode(Zsh Line Editor)(Programmable Completion Using compctl)(Shell Builtin Commands)(Top)
+texinode(Zsh Line Editor)(Completion Widgets)(Shell Builtin Commands)(Top)
 chapter(Zsh Line Editor)
 cindex(line editor)
 cindex(editor, line)
diff --git a/Doc/zsh.yo b/Doc/zsh.yo
index dad958b80..c38313b4e 100644
--- a/Doc/zsh.yo
+++ b/Doc/zsh.yo
@@ -61,8 +61,8 @@ ifnzman(includefile(Zsh/params.yo))

 ifnzman(includefile(Zsh/options.yo))

 ifnzman(includefile(Zsh/builtins.yo))

 ifnzman(includefile(Zsh/zle.yo))

-ifnzman(includefile(Zsh/compctl.yo))

 ifnzman(includefile(Zsh/compwid.yo))

+ifnzman(includefile(Zsh/compctl.yo))

 ifnzman(includefile(Zsh/modules.yo))

 ifnzman(includefile(Zsh/compsys.yo))

 ifnzman(includefile(Zsh/zftpsys.yo))

@@ -75,8 +75,8 @@ source(zshparam)
 source(zshoptions)
 source(zshbuiltins)
 source(zshzle)
-source(zshcompctl)
 source(zshcompwid)
+source(zshcompctl)
 source(zshmodules)
 source(zshcompsys)
 source(zshzftpsys)