zsh-3.1.5-pws-9 zsh-3.1.5-pws-9

15 files changed, 480 insertions, 32 deletions

diff --git a/Doc/Makefile.in b/Doc/Makefile.in
index e22f3c71d..7bc5d7ada 100644
--- a/Doc/Makefile.in
+++ b/Doc/Makefile.in
@@ -38,7 +38,7 @@ TEXI2HTML = texi2html -expandinfo -split_chapter
 .SUFFIXES: .yo .1
 
 # man pages to install
-MAN = zsh.1 zshbuiltins.1 zshcompctl.1 \
+MAN = zsh.1 zshbuiltins.1 zshcompctl.1 zshcompwid.1 \
 zshexpn.1 zshmisc.1 zshmodules.1 \
 zshoptions.1 zshparam.1 zshzle.1 zshall.1
 
@@ -48,7 +48,7 @@ YODLSRC = zmacros.yo zman.yo ztexi.yo Zsh/arith.yo Zsh/builtins.yo \
 Zsh/compat.yo Zsh/compctl.yo Zsh/cond.yo Zsh/exec.yo Zsh/expn.yo \
 Zsh/filelist.yo Zsh/files.yo Zsh/func.yo Zsh/grammar.yo Zsh/guide.yo \
 Zsh/index.yo Zsh/intro.yo Zsh/invoke.yo Zsh/jobs.yo Zsh/metafaq.yo \
-Zsh/modules.yo Zsh/mod_cap.yo \
+Zsh/modules.yo Zsh/mod_cap.yo Zsh/compwid.yo \
 Zsh/mod_clone.yo Zsh/mod_comp1.yo Zsh/mod_compctl.yo Zsh/mod_deltochar.yo \
 Zsh/mod_example.yo Zsh/mod_files.yo Zsh/mod_stat.yo \
 Zsh/mod_zle.yo Zsh/options.yo \
diff --git a/Doc/Zsh/.distfiles b/Doc/Zsh/.distfiles
index 42517f507..c4a6d8080 100644
--- a/Doc/Zsh/.distfiles
+++ b/Doc/Zsh/.distfiles
@@ -1,9 +1,9 @@
 DISTFILES_SRC='
     .distfiles
-    arith.yo builtins.yo compat.yo compctl.yo cond.yo exec.yo expn.yo
-    filelist.yo files.yo func.yo grammar.yo guide.yo index.yo intro.yo
+    arith.yo builtins.yo compat.yo compctl.yo compwid.yo cond.yo exec.yo
+    expn.yo filelist.yo files.yo func.yo grammar.yo guide.yo index.yo intro.yo
     invoke.yo jobs.yo metafaq.yo mod_cap.yo mod_clone.yo mod_comp1.yo
     mod_compctl.yo mod_deltochar.yo mod_example.yo mod_files.yo mod_sched.yo
-    mod_stat.yo mod_zle.yo modules.yo options.yo params.yo prompt.yo
-    redirect.yo restricted.yo seealso.yo zle.yo
+    mod_stat.yo mod_zftp.yo mod_zle.yo modules.yo options.yo params.yo
+    prompt.yo redirect.yo restricted.yo seealso.yo zle.yo
 '
diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo
index 6a7f19023..124f9e604 100644
--- a/Doc/Zsh/compctl.yo
+++ b/Doc/Zsh/compctl.yo
@@ -1,4 +1,4 @@
-texinode(Programmable Completion)(Zsh Modules)(Zsh Line Editor)(Top)
+texinode(Programmable Completion)(Completion Widgets)(Zsh Line Editor)(Top)
 chapter(Programmable Completion)
 cindex(completion, programmable)
 cindex(completion, controlling)
@@ -89,7 +89,7 @@ to the user database is too slow and/or it contains too many users (so
 that completion after `tt(~)' is too slow to be usable), you can use
 
 indent(
-tt(compctl -T -x 'C[0,*/*]' -f - 's[~]' -k friends -S/ -tn)
+tt(compctl -T -x 's[~] C[0,[^/]#]' -k friends -S/ -tn)
 )
 
 to complete the strings in the array tt(friends) after a `tt(~)'.
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
new file mode 100644
index 000000000..2cb12e2c2
--- /dev/null
+++ b/Doc/Zsh/compwid.yo
@@ -0,0 +1,428 @@
+texinode(Completion Widgets)(Zsh Modules)(Programmable Completion)(Top)
+chapter(Completion Widgets)
+cindex(completion, widgets)
+cindex(completion, programmable)
+cindex(completion, controlling)
+sect(Description)
+Completion widgets are defined using the tt(-C) option to the tt(zle)
+builtin command provided by the tt(zle) module (see
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(The zle Module))\
+). For example, the invocation:
+
+indent(nofill(
+tt(zle -C complete expand-or-complete completer)))
+
+defines a widget named tt(complete). If this widget is bound to a key
+using the tt(bindkey) builtin command defined in the tt(zle) module
+(see 
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor))\
+) typing that key will make the completion code call the shell
+function tt(completer). This function is responsible for generating
+the possible matches using the builtins described below. Once the
+function returns, the completion code takes over control again and
+treats the matches the way the builtin widget tt(expand-or-complete)
+would do it. For this second argument, the name of any of the builtin
+widgets that handle completions can be given, i.e. it may be any of
+tt(complete-word), tt(expand-or-complete),
+tt(expand-or-complete-prefix), tt(menu-complete),
+tt(menu-expand-or-complete), tt(reverse-menu-complete),
+tt(list-choices), or tt(delete-char-or-list).
+
+startmenu()
+menu(Special Parameters)
+menu(Builtin Commands)
+menu(Condition Codes)
+menu(Examples)
+endmenu()
+
+texinode(Special Parameters)(Builtin Commands)()(Completion Widgets)
+sect(Special Parameters)
+
+Inside completion widgets some parameters have special meaning. They
+will be used inside the widget function and other shell functions
+called from it. Outside of these function they are not special to the
+shell in any way.
+
+The parameters are used to give information about the internal state
+from the completion code to the completion widget and can be set to
+give information to the completion code from the completion
+widget. Some of the builtin commands and the condition codes use or
+change the current values of these parameters. While the completion
+widget is active, these parameters are reseton each function exit to
+the values they had when the function was entered.
+
+startitem()
+item(tt(argv))(
+The positional parameters are set to the arguments on the command line
+when the widget function is invoked from the completion code.
+)
+item(tt(CURRENT))(
+This is the number of the current word, i.e. the word the cursor is
+currently on in the tt(argv) array.
+)
+item(tt(CONTEXT))(
+This will be set by the completion code to the overall context
+completion is attempted in. Possible values are:
+
+startitem()
+item(tt(command))(
+when completing in a command position, e.g. in the first word on the
+command line
+)
+item(tt(argument))(
+when completing an argument for a command
+)
+item(tt(redirect))(
+when completing after a redirection operator; in this case the
+positional parameters contain not only the arguments but also the
+command name itself as the first element
+)
+item(tt(condition))(
+when completing inside a `tt([[)...tt(]])' conditional expressing; in
+this case the positional parameters are set to the words inside the
+conditional expressions
+)
+item(tt(math))(
+when completing in a mathematical environment such as a
+`tt(LPAR()LPAR())...tt(RPAR()RPAR())' construct
+)
+item(tt(value))(
+when completing the value of a parameter assignment; in case of an
+array value the positional parameters are set to the words in
+parentheses
+)
+item(tt(subscript))(
+when completing inside a parameter expansion subscript
+)
+enditem()
+)
+item(tt(COMMAND))(
+In most cases this is set to name of the command for which completion
+is tried. When completing after a redirection operator it contains the 
+string forming that operator. Also, when completing in the value of a
+parameter assignment or in a parameter subscript it is set to the name
+of the parameter.
+)
+item(tt(PREFIX))(
+This should be set to that part of the current word that should be
+taken as the string every possible match has to begin with. Initially
+this will be set to the part of the current word from the beginning of
+the word up to the position of the cursor. When 
+)
+item(tt(IPREFIX))(
+When a part of the current word should not be considered part of the
+matches, this part should be taken from the tt(PREFIX) parameter and
+appended to this parameter. This will initially be set to the empty
+string when called from the completion code.
+)
+item(tt(SUFFIX))(
+This should be set to that part of the current word that should be
+taken as the string every possible match has to end with. The
+completion code sets this to the part of the current word from the
+cursor position to the end.
+)
+item(tt(NMATCHES))(
+This is always set to the number of matches generated and accepted by
+the completion code so far.
+)
+item(tt(MATCHER))(
+When completion is used with a global match specification (i.e. a
+tt(compctl) with only a tt(-M) option), this parameter is set to the
+number of the specification string which is currently used.
+)
+enditem()
+
+texinode(Builtin Commands)(Condition Codes)(Special Parameters)(Completion Widgets)
+sect(Builtin Commands)
+startitem()
+findex(complist)
+item(tt(complist) var(flags ...))(
+
+Generate matches according to the given var(flags) which can be any of 
+the option flags supported by the tt(compctl) builtin command (see
+ifzman(zmanref(zshcompctl))\
+ifnzman(noderef(Programmable Completion))\
+) except for the tt(-t) and tt(-l) flags. Also, when using the tt(-K)
+flag, the function given as argument to it can not access the command
+line with the tt(read) builtin command.
+
+The matches will be generated in the same way as if the completion code
+generated them directly from a tt(compctl)-definition with the same
+flags. The completion code will consider only those matches as
+possible completions that match the prefix and suffix from the special 
+parameters desribed above. These strings will be compared with the
+generated matches using the normal matching rules and any matching
+specifications given with the tt(-M) flag to tt(complist) and the
+global matching specifications given to the tt(compctl) builtin
+command.
+)
+xitem(tt(compadd) [ tt(-qQfnUam) ] [ 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(-W) var(file-prefix) ])
+xitem([ tt(-J) var(name) ] [ tt(-V) var(name) ])
+xitem([ tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ])
+item([ tt(-M) var(match-spec) ] [ tt(--) ] [ var(words) ... ])(
+
+This builtin command can be used to add matches and directly control
+all the information the completion code stores with each possible
+match.
+
+The supported flags are:
+
+startitem()
+item(tt(-P) var(prefix))(
+The same as for tt(compctl) and tt(complist), it gives a string that
+should be inserted before the given words when they are completed. The
+string given is not considered to be part of the match.
+)
+item(tt(-S) var(suffix))(
+Like tt(-P) but gives a string that has to be inserted after the match.
+)
+item(tt(-p) var(hidden-prefix))(
+This gives a string that should be 
+...
+)
+item(tt(-s) var(hidden-suffix))(
+...
+)
+item(tt(-i) var(ignored-prefix))(
+...
+)
+item(tt(-J) var(name))(
+As for tt(compctl) and tt(complist) this gives the name of the group
+of matches the words should be stored in.
+)
+item(tt(-V) var(name))(
+Like tt(-J) but naming a unsorted group.
+)
+item(tt(-q))(
+This flag has the same meaning as for tt(compctl) and tt(complist),
+too. It makes the suffix given with tt(-S) be automatically removed if 
+the next character typed is a blank or does not insert anything or if
+the suffix consists of only one character and the next character typed 
+is the same character.
+)
+item(tt(-r) var(remove-chars))(
+This makes the suffix given with tt(-S) be automatically removed if
+the next character typed inserts one of the characters given in the
+var(remove-chars). This string is parsed as a characters class with
+the usual backslash-sequences understood, e.g. using `tt(-r "a-z\t")'
+removes the suffix if the next character typed inserts one of the
+lower case letters or a TAB, and `tt(-r "^0-9")' removes the suffix if 
+the next character typed inserts anything but a digit. One extra
+backslash sequence is understood in this string: `tt(\-)' stands for
+all characters that insert nothing. Thus `tt(-S "=" -q)' is the same
+as `tt(-S "=" -r "= \t\n\-")'.
+)
+item(tt(-R) var(remove-func))(
+For the cases where one wants to remove suffix and the tt(-r) option
+does not give enough control, this option can be used. It stores the
+name of the shell function var(remove-func) in the matches. If one of
+the matches is finally accepted and the tt(-S)-suffix inserted, this
+function will be called after the next character typed. It gets the
+length of the suffix as its argument and can use the special
+parameters available in zle widgets (see
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor))\
+) to analyse and modify the command line.
+)
+item(tt(-f))(
+If this flag is given, the matches build are marked as being the names 
+of files. They need not be actual filenames, though. But if they are
+and the option tt(LIST_TYPES) is set, the characters describing the
+types of the files in the completion lists will be shown. This also
+makes a slash automatically be added when the name of a directory is
+completed.
+)
+item(tt(-W) var(file-prefix))(
+This option has the same meaning as for the tt(compctl) and
+tt(complist) builtin commands. Here, however, only one string may be
+given, not an array. This string is used as a pathname that will be
+prepended to the given words and the prefix given with the tt(-p)
+option to perform the file-tests when showing completion
+listings. Hence it is only useful if combined with the tt(-f) flag,
+since the tests will only be performed if that flag is given.
+)
+item(tt(-a))(
+When used by tt(compctl) or tt(complist) the completion code normally
+builds two sets of matches: the normal one where words with one of the 
+suffixes in the array parameter tt(fignore) are not considered
+possible matches, and the alternate set where the words excluded
+from the first set are stored. Normally only the matches in the first
+set are used. But if this set is empty, the words from the alternate
+set are used.
+
+The tt(compadd) builtin does not use tt(fignore) parameter and
+normally stores all words in the first set. With the tt(-a)-flag
+given, however, they are all stored in the alternate set unless this
+flag is overridden by the tt(-F) option.
+)
+item(tt(-F) var(array))(
+This can be used to give an array containing suffixes like the
+tt(fignore) parameter. Words with one of these suffixes are stored in
+the alternate set of matches and words without one of these suffixes
+are stored in the normal set.
+
+The var(array) may be the name of an array parameter or a list of
+literal suffixes enclosed in parentheses as in `tt(-F "(.o .h)")'. If
+the name of an array is given, the elements of the array are taken as
+the suffixes.
+)
+item(tt(-Q))(
+As for tt(compctl) and tt(complist) this flag instructs the completion 
+code not to quote any metacharacters in the words when inserting them
+in the command line.
+)
+item(tt(-m))(
+Normally the matches added by tt(compadd) will not be compared with
+what is already on the line. If this flag is given, this comparison is 
+performed as usual and the match specifications given with the tt(-M)
+option to tt(compadd) and the global match specifications defined with 
+tt(compctl) will be used. This means that probably not all the word
+given will be stored as matches since some of them may not match the
+string on the line.
+)
+item(tt(-M) var(match-spec))(
+This option allows one to give local match specifications with the
+same meaning and format as for the tt(compctl) and tt(complist)
+builtin commands. Note that they will only be used if the tt(-m) is
+given, too.
+)
+item(tt(-n))(
+Words added with tt(compadd) with this flag will be used as possible
+matches as usual but they not appear in the completion listing.
+)
+item(tt(-U))(
+If this flag is given to one of the calls to tt(compadd) and the
+option tt(AUTO_MENU) is set, the completion code will immediatly
+switch to menucompletion.
+)
+item(tt(-), tt(--))(
+This flag ends the list of flags and options. All arguments after it
+will be taken as the words to use as matches even if they begin with
+hyphens.
+)
+enditem()
+)
+item(tt(compcall) [ tt(-TD) ])(
+
+This allows one to use completion definitions given with the
+tt(compctl) builtin from within completion widgets. It makes
+completion code complete the current word according to the
+tt(compctl)s defined. Normally only tt(compctl)s given for specific
+commands are used. To make the code use the completion flags given to
+the tt(-T) option of tt(compctl), one can give the tt(-T) flag to
+tt(compctl). Likewise, the tt(-D) flag to tt(compcall) makes the
+default completion flags given to tt(compctl) with the tt(-D) option
+be used.
+)
+enditem()
+
+texinode(Condition Codes)(Examples)(Builtin Commands)(Completion Widgets)
+sect(Condition Codes)
+
+Inside completion widgets not only the builtin commands described
+above can be used, but also some additional condition codes. These
+work on the special parameters and can be used to easily build
+completion functions that generate different matches depending on the
+strings on the line.
+
+The following condition codes are made available inside completion
+widgets:
+
+startitem()
+item(tt(-prefix) var(string))(
+true if the content of tt(PREFIX) starts with var(string)
+)
+item(tt(-iprefix) var(string))(
+like tt(-prefix), but the var(string) is removed from tt(PREFIX) and
+added to tt(IPREFIX)
+)
+item(tt(-position) var(beg) [ var(end) ])(
+true if tt(CURRENT) is equal to var(beg) or, if var(end) is given,
+equal to or greater than var(beg) and equal to or less than var(end);
+both of var(beg) and var(end) may be arithmetic expressions, if they
+are less than zero the number of words in tt(argv) are added to them
+before comparing them to tt(CURRENT); thus, tt(-1) is the last word,
+tt(-2) is the word before that and so on
+)
+item(tt(-word) var(index) var(string))(
+true if the word number var(index) in tt(argv) is equal to
+var(string); again, var(index) may be negative, counting backwards
+)
+item(tt(-mword) var(index) var(pattern))(
+like tt(-word) but using pattern matching
+)
+item(tt(-current) var(offset) var(string))(
+like tt(-word) but var(offset) is relative to the value of
+tt(CURRENT)
+)
+item(tt(-mcurrent) var(offset) var(pattern))(
+like tt(-current) but using pattern matching
+)
+item(tt(-string) [ var(number) ] var(string))(
+true if the current word contains var(string); anything up to the last 
+occurrence of this string will be ingnored by removing it from
+tt(PREFIX) and adding it to tt(IPREFIX); if var(number) is given,
+anything up to the var(number)'th occurrence of the var(string) will
+be ignored; again, var(nmuber) may be any arithmetic expression and
+negative values count backward
+)
+item(tt(-class) [ var(number) ] var(class))(
+like tt(-string) but the var(class) is used as a character class so
+that anything up to and including the last or the var(number)'th
+occurrence of any character from the string var(class) is ignored
+)
+item(tt(-words) var(min) [ var(max) ])(
+true if the number of words is equal to var(min); if var(max) is
+given, it is true if the number of words is equal to or greater than
+var(min) and equal to or less than var(max)
+)
+item(tt(-after) var(string))(
+true if the cursor is after a word that is equal to var(string)
+)
+item(tt(-mafter) var(pattern))(
+like tt(-after) but using pattern matching
+)
+item(tt(-between) var(string1) var(string2))(
+true if the cursor is after a word that is equal to var(string1), if
+there is also a word that is equal to va(string2), this is true only
+if the cursor is before it
+)
+item(tt(-mbetween) var(pattern1) var(pattern2))(
+like tt(-between) but using pattern matching
+)
+item(tt(-nmatches) var(number))(
+true if the the value of tt(NMATCHES) is equal to var(number)
+)
+item(tt(-matcher) var(number))(
+true if the value of tt(MATCHER) is equal to var(number)
+)
+enditem()
+
+texinode(Examples)()(Condition Codes)(Completion Widgets)
+sect(Examples)
+
+The first step is to define the widget:
+
+indent(nofill(
+tt(zle -C complete complete-word complete-history)))
+
+Then the widget can be bound to a key using the tt(bindkey) builtin
+command:
+
+indent(nofill(
+tt(bindkey '^X\t' complete)))
+
+After that the shell function tt(complete-history) will be invoked
+after typing control-X and TAB. The function should then generte the
+matches, e.g.:
+
+indent(nofill(
+tt(complete-history LPAR()RPAR() { complist -H 0 '' })))
+
+In this the function will complete words from the history matching the 
+current word.
diff --git a/Doc/Zsh/guide.yo b/Doc/Zsh/guide.yo
index 0fb954e26..e0005e339 100644
--- a/Doc/Zsh/guide.yo
+++ b/Doc/Zsh/guide.yo
@@ -29,6 +29,7 @@ menu(Options)
 menu(Shell Builtin Commands)
 menu(Zsh Line Editor)
 menu(Programmable Completion)
+menu(Completion Widgets)
 menu(Zsh Modules)
 
  --- Indices ---
@@ -103,6 +104,13 @@ menu(Alternative Completion)
 menu(Extended Completion)
 menu(Example)
 
+Completion Widgets
+
+menu(Special Parameters)
+menu(Builtin Commands)
+menu(Condition Codes)
+menu(Examples)
+
 Zsh Modules
 
 menu(The cap Module)
diff --git a/Doc/Zsh/intro.yo b/Doc/Zsh/intro.yo
index ebb678f70..f619f82fe 100644
--- a/Doc/Zsh/intro.yo
+++ b/Doc/Zsh/intro.yo
@@ -21,6 +21,7 @@ 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(zshmodules)   Zsh loadable modules)
 ifzshone(\
 list(em(zshall)       Meta-man page containing all of the above)
diff --git a/Doc/Zsh/metafaq.yo b/Doc/Zsh/metafaq.yo
index cad82ee65..1d1636942 100644
--- a/Doc/Zsh/metafaq.yo
+++ b/Doc/Zsh/metafaq.yo
@@ -11,7 +11,7 @@ sect(Author)
 cindex(author)
 Zsh was originally written by Paul Falstad tt(<pf@zsh.org>).
 Zsh is now maintained by the members of the zsh-workers mailing
-list tt(<zsh-workers@math.gatech.edu>).  The development is currently
+list tt(<zsh-workers@sunsite.auc.dk>).  The development is currently
 coordinated by Andrew Main (Zefram) tt(<zefram@zsh.org>).  The coordinator
 can be contacted at tt(<coordinator@zsh.org>), but matters relating to
 the code should generally go to the mailing list.
diff --git a/Doc/Zsh/mod_compctl.yo b/Doc/Zsh/mod_compctl.yo
index b7adf8fa6..cfd615b2d 100644
--- a/Doc/Zsh/mod_compctl.yo
+++ b/Doc/Zsh/mod_compctl.yo
@@ -1,7 +1,12 @@
 texinode(The compctl Module)(The deltochar Module)(The comp1 Module)(Zsh Modules)
 sect(The compctl Module)
-The tt(compctl) module makes available one builtin command, tt(compctl),
-which is the standard way to control completions for ZLE.  See
+The tt(compctl) module makes available several builtin commands. tt(compctl),
+is the standard way to control completions for ZLE.  See
 ifzman(zmanref(zshcompctl))\
 ifnzman(noderef(Programmable Completion))\
 .
+The other builtin commands can be used in user-defined completion widgets,
+see
+ifzman(zmanref(zshcompwid))\
+ifnzman(noderef(Completion Widgets))\
+.
diff --git a/Doc/Zsh/mod_zftp.yo b/Doc/Zsh/mod_zftp.yo
index c08130bf5..395bf26de 100644
--- a/Doc/Zsh/mod_zftp.yo
+++ b/Doc/Zsh/mod_zftp.yo
@@ -439,4 +439,8 @@ until the next call to tt(zftp).  Other status changes in subshells
 will not be reflected by changes to the variables (but should
 be otherwise harmless).
 
+On some operatings systems, the control connection is not valid after a
+fork(), so that operations in subshells or on the left hand side of a
+pipeline are not possible.
+
 enditem()
diff --git a/Doc/Zsh/mod_zle.yo b/Doc/Zsh/mod_zle.yo
index 86d145636..ad88c94c7 100644
--- a/Doc/Zsh/mod_zle.yo
+++ b/Doc/Zsh/mod_zle.yo
@@ -165,7 +165,7 @@ xitem(tt(zle) tt(-l) [ tt(-L) ])
 xitem(tt(zle) tt(-D) var(widget) ...)
 xitem(tt(zle) tt(-A) var(old-widget) var(new-widget))
 xitem(tt(zle) tt(-N) var(widget) [ var(function) ])
-xitem(tt(zle) tt(-C) [ tt(-mMgG) ] var(widget) [ var(compctl-options) ])
+xitem(tt(zle) tt(-C) var(widget) var(completion-widget) var(function))
 item(tt(zle) var(widget))(
 The tt(zle) builtin performs a number of different actions concerning
 ZLE.  Which operation it performs depends on its options:
@@ -193,22 +193,15 @@ widget is invoked from within the editor, the specified shell var(function)
 is called.  If no function name is specified, it defaults to
 the same name as the widget.
 )
-item(tt(-C) [ tt(-mMgG) ] var(widget) [ var(compctl-options) ])(
-Create a user-defined widget which will perform completion according
-to var(compctl-options).  These are passed directly to the
-tt(compctl) command, see
-ifzman(zmanref(zshcompctl))\
-ifnzman(noderef(Programmable Completion))\
-; no command names or special options (tt(-LDCT)) may be used.  If the
-var(compctl-options) are missing the widget will have normal
-completion behaviour as modified by the tt(zle) options.
-
-There are four additional tt(zle) options, which must precede the
-widget name: tt(-m) and tt(-M) force the widget to use or not to use
-menu completion, respectively, while tt(-g) and tt(-G) likewise force
-the widget to use or not to use glob completion.  The defaults are to
-use the current settings of tt(MENU_COMPLETE) and tt(GLOB_COMPLETE)
-as with normal completion.
+item(tt(-C) var(widget) var(completion-widget) var(function))(
+Create a user-defined completion widget names var(widget). The 
+completion widget will behave like the built-in completion-widget
+whose name is given as var(completion-widget). To generate the
+completions, the shell function var(function) will be called.
+For further information, see
+ifzman(zmanref(zshcompwid))\
+ifnzman(noderef(Completion Widgets))\
+.
 )
 item(var(widget))(
 Invoke the specified widget.  This can only be done when ZLE is
diff --git a/Doc/Zsh/modules.yo b/Doc/Zsh/modules.yo
index 300553845..97c420eed 100644
--- a/Doc/Zsh/modules.yo
+++ b/Doc/Zsh/modules.yo
@@ -1,4 +1,4 @@
-texinode(Zsh Modules)()(Programmable Completion)(Top)
+texinode(Zsh Modules)()(Completion Widgets)(Top)
 chapter(Zsh Modules)
 cindex(modules)
 sect(Description)
@@ -19,7 +19,8 @@ item(tt(comp1))(
 Base of the completion system.  Used by the tt(compctl) and tt(zle) modules.
 )
 item(tt(compctl))(
-The tt(compctl) builtin for controlling completion.
+The tt(compctl) builtin for controlling completion and the builtins for
+completion widgets.
 )
 item(tt(deltochar))(
 A ZLE function duplicating EMACS' tt(zap-to-char).
diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo
index b9455f578..b59fa624a 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -544,12 +544,14 @@ List jobs in the long format by default.
 )
 pindex(MAGIC_EQUAL_SUBST)
 item(tt(MAGIC_EQUAL_SUBST))(
-All unquoted arguments of the form `var(identifier)tt(=)var(expression)'
+All unquoted arguments of the form `var(anything)tt(=)var(expression)'
 appearing after the command name have filename expansion (that is,
 where var(expression) has a leading `tt(~)' or `tt(=)') performed on
 var(expression) as if it were a parameter assignment.  The argument is
 not otherwise treated specially; it is passed to the command as a single
-argument, and not used as an actual parameter assignment.
+argument, and not used as an actual parameter assignment.  For example, in
+tt(echo foo=~/bar:~/rod), both occurrences of tt(~) would be replaced.
+Note that this happens anyway with tt(typeset) and similar statements.
 )
 pindex(MAIL_WARNING)
 cindex(mail, warning of reading)
diff --git a/Doc/Zsh/seealso.yo b/Doc/Zsh/seealso.yo
index 8289e6628..5231e8828 100644
--- a/Doc/Zsh/seealso.yo
+++ b/Doc/Zsh/seealso.yo
@@ -10,6 +10,7 @@ ifzshone(\
 ,
 zmanref(zshbuiltins),
 zmanref(zshcompctl),
+zmanref(zshcompwid),
 zmanref(zshexpn),
 zmanref(zshmisc),
 zmanref(zshmodules),
diff --git a/Doc/zsh.yo b/Doc/zsh.yo
index a97f023e7..e6cef6a32 100644
--- a/Doc/zsh.yo
+++ b/Doc/zsh.yo
@@ -64,6 +64,7 @@ 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/modules.yo))

 ifzshall(\
 def(source)(1)(NOTRANS(.so )man1/ARG1NOTRANS(.)1)\
@@ -75,6 +76,7 @@ source(zshoptions)
 source(zshbuiltins)
 source(zshzle)
 source(zshcompctl)
+source(zshcompwid)
 source(zshmodules)
 manpage(ZSHALL)(1)(date())(zsh version())
 )\
diff --git a/Doc/zshcompwid.yo b/Doc/zshcompwid.yo
new file mode 100644
index 000000000..d876e422d
--- /dev/null
+++ b/Doc/zshcompwid.yo
@@ -0,0 +1,3 @@
+manpage(ZSHCOMPWID)(1)(date())(zsh version())
+manpagename(zshcompwid)(zsh completion widgets)
+includefile(Zsh/compwid.yo)