20 files changed, 441 insertions, 103 deletions

diff --git a/Doc/.distfiles b/Doc/.distfiles
index 4c21f9fb1..7fd1cdcc1 100644
--- a/Doc/.distfiles
+++ b/Doc/.distfiles
@@ -2,13 +2,11 @@ DISTFILES_SRC='
     .cvsignore .distfiles Makefile.in
     META-FAQ.yo intro.ms
     version.yo zmacros.yo zman.yo ztexi.yo
-    zsh.yo zshbuiltins.yo zshcompctl.yo zshcompsys.yo zshcompwid.yo
-    zshexpn.yo zshmisc.yo zshmodules.yo zshoptions.yo zshparam.yo
-    zshzftpsys.yo zshzle.yo
+    zsh.yo zshbuiltins.yo zshcompctl.yo zshexpn.yo zshmisc.yo
+    zshmodules.yo zshoptions.yo zshparam.yo zshzle.yo
     zsh.texi
-    zsh.1 zshbuiltins.1 zshcompctl.1 zshcompsys.1 zshcompwid.1
-    zshexpn.1 zshmisc.1 zshmodules.1 zshoptions.1 zshparam.1
-    zshzftpsys.1 zshzle.1 zshall.1
+    zsh.1 zshbuiltins.1 zshcompctl.1 zshexpn.1 zshmisc.1 zshmodules.1
+    zshoptions.1 zshparam.1 zshzle.1 zshall.1
 '
 
 DISTFILES_DOC='
diff --git a/Doc/Makefile.in b/Doc/Makefile.in
index 83bba17f8..9e70f88b1 100644
--- a/Doc/Makefile.in
+++ b/Doc/Makefile.in
@@ -56,9 +56,9 @@ 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/compwid.yo Zsh/compsys.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_mapfile.yo Zsh/mod_stat.yo \
-Zsh/mod_zle.yo Zsh/options.yo \
+Zsh/mod_clone.yo Zsh/mod_comp1.yo Zsh/mod_compctl.yo Zsh/mod_complist.yo \
+Zsh/mod_deltochar.yo Zsh/mod_example.yo Zsh/mod_files.yo \
+Zsh/mod_mapfile.yo Zsh/mod_stat.yo Zsh/mod_zle.yo Zsh/options.yo \
 Zsh/params.yo Zsh/prompt.yo Zsh/redirect.yo Zsh/restricted.yo \
 Zsh/seealso.yo Zsh/zftpsys.yo Zsh/zle.yo
 
@@ -131,9 +131,10 @@ zshmisc.1: Zsh/grammar.yo Zsh/redirect.yo Zsh/exec.yo Zsh/func.yo \
            Zsh/prompt.yo Zsh/restricted.yo
 
 zshmodules.1: Zsh/modules.yo Zsh/mod_cap.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_mapfile.yo \
-              Zsh/mod_sched.yo Zsh/mod_stat.yo Zsh/mod_zftp.yo Zsh/mod_zle.yo
+              Zsh/mod_comp1.yo Zsh/mod_complist.yo Zsh/mod_compctl.yo \
+              Zsh/mod_deltochar.yo Zsh/mod_example.yo Zsh/mod_files.yo \
+              Zsh/mod_mapfile.yo Zsh/mod_sched.yo Zsh/mod_stat.yo \
+              Zsh/mod_zftp.yo Zsh/mod_zle.yo
 
 zshoptions.1: Zsh/options.yo
 
diff --git a/Doc/Zsh/.distfiles b/Doc/Zsh/.distfiles
index 3fbde5ef1..691cd8749 100644
--- a/Doc/Zsh/.distfiles
+++ b/Doc/Zsh/.distfiles
@@ -3,7 +3,7 @@ DISTFILES_SRC='
     arith.yo builtins.yo compat.yo compctl.yo compsys.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_cap.yo mod_clone.yo mod_comp1.yo mod_complist.yo
     mod_compctl.yo mod_deltochar.yo mod_example.yo mod_files.yo
     mod_mapfile.yo mod_parameter.yo mod_sched.yo mod_stat.yo
     mod_zftp.yo mod_zle.yo
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 49c9dc26c..10202dbce 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -224,10 +224,11 @@ are reset to their default value corresponding to the specified emulation
 mode, except for certain options describing the interactive
 environment; otherwise, only those options likely to cause portability
 problems in scripts and functions are altered.  If the tt(-L) option
-is given, the option tt(LOCAL_OPTIONS) will be set as well, causing
-the effect of the tt(emulate) command to be local to the immediately
-surrounding shell function, if any; normally this is turned off in all
-emulation modes except tt(ksh).
+is given, the options tt(LOCAL_OPTIONS) and tt(LOCAL_TRAPS) will be set as
+well, causing the effects of the tt(emulate) command and any tt(setopt) and
+tt(trap) commands to be local to the immediately surrounding shell
+function, if any; normally these options are turned off in all emulation
+modes except tt(ksh).
 )
 findex(enable)
 cindex(enabling commands)
@@ -263,8 +264,7 @@ findex(export)
 item(tt(export) [ var(name)[tt(=)var(value)] ... ])(
 The specified var(name)s are marked for automatic export
 to the environment of subsequently executed commands.
-Equivalent to tt(typeset -x), except that no parameter will be created
-to hide an existing one in an outer scope.
+Equivalent to tt(typeset -gx).
 If a parameter specified does not
 already exist, it is created in the global scope.
 )
@@ -428,7 +428,7 @@ added by explicit specification.  If has no effect if used with tt(-f).
 )
 alias(history)(fc -l)
 findex(integer)
-item(tt(integer) [ {tt(PLUS())|tt(-)}tt(lrtux) ] [ var(name)[tt(=)var(value)] ... ])(
+item(tt(integer) [ {tt(PLUS())|tt(-)}tt(glrtux) ] [ var(name)[tt(=)var(value)] ... ])(
 Equivalent to tt(typeset -i), except that options irrelevant to
 integers are not permitted.
 )
@@ -522,7 +522,7 @@ endsitem()
 )
 findex(local)
 item(tt(local) [ {tt(PLUS())|tt(-)}tt(ALRUZailrtu) [var(n)]] [ var(name)[tt(=)var(value)] ] ...)(
-Same as tt(typeset), except that the options tt(-x) and
+Same as tt(typeset), except that the options tt(-g), tt(-x) and
 tt(-f) are not permitted.
 )
 findex(log)
@@ -682,12 +682,13 @@ Read only one character from the terminal and set var(name) to
 With this flag set the return value is zero only if the character was
 `tt(y)' or `tt(Y)'.  Note that this always reads from the terminal, even
 if used with the tt(-p) or tt(-u) or tt(-z) flags or with redirected input.
+This option may also be used within zle widgets.
 )
 item(tt(-k) [ var(num) ])(
 Read only one (or var(num)) characters.  All are assigned to the first
 var(name), without word splitting.  This flag is ignored when tt(-q) is
 present.  Input is read from the terminal unless one of tt(-u) or tt(-p)
-is present.
+is present.  This option may also be used within zle widgets.
 )
 item(tt(-z))(
 Read one entry from the editor buffer stack and assign it to the first
@@ -842,7 +843,8 @@ findex(trap)
 cindex(signals, trapping)
 cindex(trapping signals)
 item(tt(trap) [ var(arg) [ var(sig) ... ] ])(
-var(arg) is a command to be read and executed when the shell
+var(arg) is a series of commands (usually quoted to protect it from
+immediate evaluation by the shell) to be read and executed when the shell
 receives var(sig).  Each var(sig) can be given as a number
 or as the name of a signal.
 If var(arg) is `tt(-)', then all traps var(sig) are reset to their
@@ -862,6 +864,20 @@ then the command var(arg) is executed when the shell terminates.
 
 The tt(trap) command with no arguments prints a list of commands
 associated with each signal.
+
+Note that traps defined with the tt(trap) builtin are slightly different
+from those defined as `tt(TRAP)var(NAL) () { ... }', as the latter have
+their own function environment (line numbers, local variables, etc.) while
+the former use the environment of the command in which they were called.
+For example,
+
+example(trap 'print $LINENO' DEBUG)
+
+will print the line number of command executed after it has run, while
+
+example(TRAPDEBUG() { print $LINENO; })
+
+will always print the number zero.
 )
 findex(true)
 cindex(doing nothing, successfully)
@@ -887,7 +903,7 @@ Equivalent to tt(whence -v).
 findex(typeset)
 cindex(parameters, setting)
 cindex(parameters, declaring)
-xitem(tt(typeset) [ {tt(PLUS())|tt(-)}tt(ALRUZafilrtuxm) [var(n)]] [ \
+xitem(tt(typeset) [ {tt(PLUS())|tt(-)}tt(ALRUZafgilrtuxm) [var(n)]] [ \
 var(name)[tt(=)var(value)] ... ])
 item(tt(typeset) -T [ {tt(PLUS()|tt(-))}tt(LRUZrux) ] \
   var(SCALAR)[tt(=)var(value)] var(array))(
@@ -926,6 +942,14 @@ to var(array) sets it to be a single-element array.  Note that
 both tt(typeset -xT ...) and tt(export -T ...) work, but only the
 scalar will be marked for export.
 
+The flag tt(-g) (global) flag is treated specially: it means that any
+resulting parameter will not be restricted to local scope.  Note that this
+does not necessarily mean that the parameter will be global, as the flag
+will apply to any existing parameter (even if unset) from an enclosing
+function.  This flag does not affect the parameter after creation, hence it
+has no effect when listing existing parameters, nor does the flag tt(+g)
+have any effect.
+
 If no var(name) is present, the names and values of all parameters are
 printed.  In this case the attribute flags restrict the display to
 only those parameters that have the specified attributes.  Using
@@ -1174,6 +1198,7 @@ findex(zmodload)
 cindex(modules, loading)
 cindex(loading modules)
 xitem(tt(zmodload) [ tt(-dL) ] [ ... ])
+xitem(tt(zmodload -e) [ ... ])
 xitem(tt(zmodload) [ tt(-a) [ tt(-bcp) [ tt(-I) ] ] ] [ tt(-iL) ] ...)
 item(tt(zmodload) tt(-u) [ tt(-abcdp) [ tt(-I) ] ] [ tt(-iL) ] ...)(
 tt(zmodload) performs operations relating to zsh's loadable modules.
@@ -1269,6 +1294,21 @@ xitem(tt(zmodload) tt(-a) [ tt(-i) ] var(name) [ var(builtin) ... ])
 item(tt(zmodload) tt(-ua) [ tt(-i) ] var(builtin) ...)(
 Equivalent to tt(-ab) and tt(-ub).
 )
+item(tt(zmodload -e) [ var(string) ... ])(
+The tt(-e) option without arguments lists all modules loaded or linked 
+into the shell. With arguments only the return status is set to zero
+if all var(string)s given as arguments are names of modules loaded or
+linked in and to one if at least on var(string) is not the name of a
+module loaded or linked. This can be used to test for the availability 
+of things implemented by modules.
+)
 enditem()
+
+In a shell without dynamic loading only the tt(-e) option is
+supported. In such a shell the return status of tt(zmodload) without
+arguments or options is one whereas in a shell with dynamic loading
+the return status without arguments or options is always zero. This
+can be used to test if the shell supports dynamic loading of modules
+or not.
 )
 enditem()
diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo
index 48c7bf629..8f7c23f25 100644
--- a/Doc/Zsh/compctl.yo
+++ b/Doc/Zsh/compctl.yo
@@ -2,6 +2,24 @@ texinode(Programmable Completion Using compctl)(Completion Widgets)(Zsh Line Edi
 chapter(Programmable Completion Using compctl)
 cindex(completion, programmable)
 cindex(completion, controlling)
+ifzman(\
+sect(Synopsis)
+This version of zsh has two ways of performing completion of words on the
+command line.  New users of the shell may prefer to use the newer
+and more powerful system based on shell functions; this is described in
+zmanref(zshcompsys), and the basic shell mechanisms which support it are
+described in zmanref(zshcompwid).  This manual entry describes the older
+tt(compctl) command.
+)\
+ifnzman(\
+sect(Types of completion)
+This version of zsh has two ways of performing completion of words on the
+command line.  New users of the shell may prefer to use the newer
+and more powerful system based on shell functions; this is described
+in noderef(Completion System), and the basic shell mechanisms which support
+it are described in noderef(Completion Widgets).  This chapter describes
+the older tt(compctl) command.
+)\
 findex(compctl)
 sect(Description)
 startlist()
@@ -615,7 +633,8 @@ var(max) inclusive.
 )
 item(tt(r[)var(str1)tt(,)var(str2)tt(])...)(
 Matches if the cursor is after a word with prefix var(str1).  If there
-is also a word with prefix var(str2) on the command line it matches
+is also a word with prefix var(str2) on the command line after the one 
+matched by var(str1) it matches
 only if the cursor is before this word. If the comma and var(str2) are
 omitted, it matches if the cursor is after a word with prefix var(str1).
 )
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 572660de3..9d6cc10ce 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -41,15 +41,15 @@ directory (or multiple directories) of your own which should appear in your
 tt($fpath) variable so that the functions can be autoloaded.
 
 startmenu()
-menu(Initialisation)
+menu(Initialization)
 menu(Control Functions)
 menu(Completion Functions)
 endmenu()
 
-texinode(Initialisation)(Control Functions)()(Completion System)
-sect(Initialisation)
+texinode(Initialization)(Control Functions)()(Completion System)
+sect(Initialization)
 
-The script tt(compinstall) can be run by a user to set up the completion
+The function tt(compinstall) can be run by a user to set up the completion
 system for use.  It will usually insert code into tt(.zshrc), although if
 that is not writable it will save it in another file and tell you that
 file's locations.  Note that it is up to you to make sure that the lines
@@ -59,13 +59,15 @@ So long as you keep them all together (including the comment lines at the
 start and finish), you can rerun tt(compinstall) and it will correctly
 locate and modify these lines.  Note, however, that any code you add to
 this section by hand is likely to be lost if you rerun tt(compinstall).
+The new code will take effect next time you start the shell, or run
+tt(.zshrc) by hand.
 
-You can run it as `tt(source )var(<path>)tt(/compinstall)' or
-`tt(. )var(<path>)tt(/compinstall)', where var(<path>) is where the
-completion functions are stored.  It will ask you various questions about
-how you would like completion set up.  It is in two parts; the basic part
+To run it, you will need to make sure it is in a directory mentioned in your
+tt($fpath) parameter, and that it is autoloaded (`tt(autoload -U
+compinstall)' is recommended).  It will ask you various questions about how
+you would like completion set up.  It is in two parts; the basic part
 locates the completion files and decides where to put your personal
-dumpfile, used to speed up initialisation after the first time.  After
+dumpfile, used to speed up initialization after the first time.  After
 that, you will be asked if you wish to go on to the advanced set-up; if you
 answer tt(n), you can rerun tt(compinstall) later without having to
 re-enter any of the basic settings.
@@ -73,36 +75,35 @@ re-enter any of the basic settings.
 You can abort the installation any time you are being prompted for
 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)'.
+
 subsect(Use of compinit)
 
 This section describes the use of tt(compinit) to initialize completion for
 the current session when run directly by the user; if you have run
 tt(compinstall) it will be called automatically from your tt(.zshrc).
 
-To initialise the system, the script tt(compinit) should be sourced with
-`tt(source )var(<path>)tt(/compinit)' or
-`tt(. )var(<path>)tt(/compinit)'. This 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.
+To initialize the system, the function tt(compinit) should be in a
+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.
 
 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.  The easiest way
-to do this is by adding the option tt(-d) whenever tt(compinit) is sourced.
-In this case the dumped file will have the same name as the sourced file,
-but with tt(.dump) appended to the end, or, if that is not writable by the
-user, the file tt(.zcompdump) in the same directory as the startup files
-(i.e. tt($ZDOTDIR) or tt($HOME)); alternatively, an explicit file name can
-be given following the tt(-d).  On the next call to tt(compinit -d), the
-dumped file will be read instead.
-
-The other option accepted by tt(compinit) is tt(-f )var(dir), which gives
-the directory in which tt(compinit) resides.  If you source tt(compinit) by
-its full pathname, and the option tt(FUNCTION_ARGZERO) is set, as it is by
-default unless tt(zsh) is emulating tt(sh) or tt(ksh), this is unnecessary
-as tt(compinit) can deduce the directory for itself.  It is used in two
-ways: to find the program tt(compdump) used by the tt(-d) option, and to
-check if the directory should be added to the function search path to find
-the completion functions (see below).
+to do this is by adding the option tt(-d) whenever tt(compinit) is run.
+In this case the dumped file is tt(.zcompdump) in the same directory as the
+startup files (i.e. tt($ZDOTDIR) or tt($HOME)); alternatively, an explicit
+file name can be given following the tt(-d).  On the next call to
+tt(compinit -d), the dumped file will be read instead.
+
+If the parameter tt(_compdir) is set, tt(compinit) uses it has a directory
+where completion functions can be found; this is only necessary if they are
+not already in the function search path.
 
 If the number of completion files changes, tt(compinit) will recognise this
 and produce a new dump file.  However, if the name of a function or the
@@ -110,27 +111,30 @@ arguments in the first line of a tt(#compdef) function (as described below)
 change, it is easiest to delete the dump file by hand so that the next time
 tt(compinit) will re-create it.
 
-The dumping is actually done by another script, tt(compdump), but you will
-only need to source this yourself if you change the configuration
+The dumping is actually done by another function, tt(compdump), but you
+will only need to run this yourself if you change the configuration
 (e.g. using tt(compdef)) and then want to dump the new one.  The name of
-the old dumped file will be remembered for this.
+the old dumped file will be remembered for this purpose.
 
 subsect(Autoloaded files)
 
 The convention for autoloaded functions used in completion is that they
 start with an underscore; as already mentioned, the tt(fpath/FPATH)
-parameter must contain the directory in which they are stored.  If
-tt(compinit) does not find enough files beginning with an underscore (fewer
-than twenty) in the search path, it will try to find more by adding its own
-directory to the search path.  If you keep all the completion files in this
-directory, this means you never have to alter tt(fpath/FPATH) yourself.
+parameter must contain the directory in which they are stored.  If tt(zsh)
+was properly installed on your system, then tt(fpath/FPATH) automatically
+contains the required directories.
+
+For incomplete installations, if tt(compinit) does not find enough files
+beginning with an underscore (fewer than twenty) in the search path, it
+will try to find more by adding the directory tt(_compdir) to the search
+path; if you have run tt(compinstall), this will be set automatically.
 Furthermore, if the directory in question ends in the path segment
 tt(Core), or has a subdirectory named tt(Core), tt(compinit) will add all
 subdirectories of the directory where tt(Core) is to the path: this allows
 the functions to be in the same format as in the tt(zsh) source
 distribution.
 
-When tt(compinit) is sourced, it searches all such files accessible via
+When tt(compinit) is run, it searches all such files accessible via
 tt(fpath/FPATH) and reads the first line of each of them.  This line should
 contain one of the tags described below. Files whose first line does not
 start with one of these tags are not considered to be part of the
@@ -158,7 +162,11 @@ var(key-sequences).  It creates a widget behaving like the builtin widget
 var(style), which must be one of those that perform completion, namely
 tt(complete-word), tt(delete-char-or-list), tt(expand-or-complete),
 tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete),
-tt(menu-expand-or-complete), or tt(reverse-menu-complete).
+tt(menu-expand-or-complete), or tt(reverse-menu-complete). If the
+tt(complist) module is loaded (see
+ifzman(zmanref(zshmodules))\
+ifnzman(noderef(The complist Module))\
+), the tt(menu-select) widget can be used, too.
 
 The widget is then bound to all the var(key-sequences) given, if any: when
 one of the var(key-sequences) is typed, the function in the file will
@@ -238,10 +246,10 @@ function, usable to be put in a setup script.
 )
 enditem()
 
-texinode(Control Functions)(Completion Functions)(Initialisation)(Completion System)
+texinode(Control Functions)(Completion Functions)(Initialization)(Completion System)
 sect(Control Functions)
 
-The initialisation script tt(compinit) re-binds all the keys which perform
+The initialization script tt(compinit) re-binds all the keys which perform
 completion to newly created widgets that all call the supplied widget
 function tt(_main_complete). This function acts as a wrapper calling
 the so-called `completer' functions that generate matches. If
@@ -382,7 +390,7 @@ with a numeric argument of six (as in `tt(ESC-6 TAB)'), up to six
 errors are accepted.  Hence with a value of `tt(0n)', no correcting
 completion will be attempted unless a numeric argument is given.
 
-If the value contains `tt(n)' or `tt(N)' and a exclamation mark
+If the value contains `tt(n)' or `tt(N)' and an exclamation mark
 (`tt(!)'), tt(_approximate) will var(not) try to generate corrected
 completions when given a numeric argument, so in this case the number given
 should be greater than zero.  For example, `tt(2n!)' specifies that
@@ -467,6 +475,12 @@ configuration key tt(match_original) has a value of `tt(only)', no
 `tt(*)' will be inserted. If tt(match_original) has any other non-empty
 string as its value, this completer will first try to generate matches
 without, then with a `tt(*)' inserted at the cursor position.
+
+The generated matches will be offered in a menucompletion unless the
+tt(match_insert) configuration key is set to a string starting with
+`tt(unambig)'. In this case menucompletion will only be started if no
+unambiguous string could be generated that is at least as long as the
+original string.
 )
 item(tt(_expand))(
 This completer function does not really do completion, but instead
@@ -652,7 +666,7 @@ one can write a pattern completion function that keeps other functions
 from being tried simply by setting this parameter to any value.
 )
 item(tt(_multi_parts))(
-This functions gets two arguments: a separator character and an
+This function gets two arguments: a separator character and an
 array.  As usual, the array may be either the
 name of an array parameter or a literal array in the form
 `tt(LPAR()foo bar)tt(RPAR())' (i.e. a list of words separated by white 
@@ -700,10 +714,13 @@ These functions also accept the `tt(-J)', `tt(-V)', `tt(-X)', `tt(-P)',
 `tt(-S)', `tt(-q)', `tt(-r)', and `tt(-R)' options from the
 tt(compadd) builtin.
 
-Finally, the tt(_path_files) function supports one configuration key:
-tt(path_expand). If this is set to any non-empty string, the partially
+Finally, the tt(_path_files) function supports two configuration keys.
+If tt(path_expand) is set to any non-empty string, the partially
 typed path from the line will be expanded as far as possible even if
-trailing pathname components can not be completed.
+trailing pathname components can not be completed. And if
+tt(path_cursor) is set to a non-empty string, the cursor will be left
+after the first ambiguous pathname component even when menucompletion
+is used.
 )
 item(tt(_parameters))(
 This should be used to complete parameter names if you need some of the
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 7f5ffe442..923323aa7 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -26,7 +26,8 @@ of the builtin widgets that handle completions can be given:
 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).
+tt(list-choices), or tt(delete-char-or-list).  Note that this will still
+work even if the widget in question has been rebound.
 
 startmenu()
 menu(Special Parameters)
@@ -346,7 +347,7 @@ 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(-I) var(ignored-suffix) ])
-xitem([ tt(-W) var(file-prefix) ])
+xitem([ tt(-W) var(file-prefix) ] [ tt(-y) 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) ])
@@ -406,6 +407,12 @@ match.
 item(tt(-I) var(ignored-suffix))(
 Like tt(-i), but gives an ignored suffix.
 )
+item(tt(-y) var(array))(
+This gives a number of string to display instead of the matches. This
+is like the tt(-y) option of the tt(compctl) builtin command but the
+var(array) argument may only be the name of an array parameter or a
+literal array in parentheses containing the strings to display.
+)
 item(tt(-J) var(name))(
 As for tt(compctl) and tt(compgen), this gives the name of the group
 of matches the words should be stored in.
diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index 0b32acc4a..aa905b600 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -41,16 +41,16 @@ pindex(KSH_AUTOLOAD, use of)
 If the tt(KSH_AUTOLOAD) option is set, or the file contains only a simple
 definition of the function, the file's contents will be
 executed.  It would normally define the function in question, but may
-also perform initialisation.
+also perform initialization.
 It is executed in the context of the function
 execution, and may therefore define local parameters.
 
 Otherwise, the function is defined such that its body is the
 complete contents of the file.  This form allows the file to be
 used directly as an executable shell script.
-Initialisation code can be executed, but only as part of the first
+Initialization code can be executed, but only as part of the first
 function execution, so the function would have to redefine itself to
-avoid reinitialising on the next execution.
+avoid reinitializing on the next execution.
 
 If this processing of the file results in the function being
 fully defined, the function itself is then executed.
diff --git a/Doc/Zsh/guide.yo b/Doc/Zsh/guide.yo
index d1f3e3aa9..cc8fe0f7d 100644
--- a/Doc/Zsh/guide.yo
+++ b/Doc/Zsh/guide.yo
@@ -146,8 +146,10 @@ then be processed with bf(dvips) and optionally bf(gs) (Ghostscript) to
 produce a nicely formatted printed guide.
 )
 item(The HTML guide)(
-An HTML version of this guide is available at the Zsh web site via
+An HTML version of this guide is available at the Zsh web site via:
+
 tt(http://sunsite.auc.dk/zsh/Doc/index.html).
+
 (The HTML version is produced with bf(texi2html), which may be obtained
 from tt(http://wwwcn.cern.ch/dci/texi2html/). The command is
 `tt(texi2html -split_chapter -expandinfo zsh.texi)'.)
diff --git a/Doc/Zsh/mod_compctl.yo b/Doc/Zsh/mod_compctl.yo
index 91f6112ee..785767e45 100644
--- a/Doc/Zsh/mod_compctl.yo
+++ b/Doc/Zsh/mod_compctl.yo
@@ -1,4 +1,4 @@
-texinode(The compctl Module)(The deltochar Module)(The comp1 Module)(Zsh Modules)
+texinode(The compctl Module)(The complist Module)(The comp1 Module)(Zsh Modules)
 sect(The compctl Module)
 The tt(compctl) module makes available several builtin commands. tt(compctl),
 is the standard way to control completions for ZLE.  See
diff --git a/Doc/Zsh/mod_complist.yo b/Doc/Zsh/mod_complist.yo
new file mode 100644
index 000000000..460d4a609
--- /dev/null
+++ b/Doc/Zsh/mod_complist.yo
@@ -0,0 +1,119 @@
+texinode(The complist Module)(The deltochar Module)(The compctl Module)(Zsh Modules)
+sect(The complist Module)
+cindex(completion, listing)
+The tt(complist) module offers two extensions to completion listings:
+the ability to highlight matches in such a list and a different
+style of menu-completion.
+
+subsect(Parameters)
+For both extensions one of the parameters tt(ZLS_COLORS) or tt(ZLS_COLOURS)
+must be set, even if the value is empty (which uses all the default values
+given below). These describe how matches are highlighted. The format of the
+value of these parameters is the same as used by the GNU version of the
+tt(ls) command: a colon-separated list of specifications of the form
+`var(name)=var(value)'. The var(name) may be one of the following strings,
+most of which specify file-types for which the var(value) will be used. The
+strings and their default values are:
+
+startitem()
+item(tt(no 0))(
+for normal text (not the string displayed for a match)
+)
+item(tt(fi 0))(
+for regular files
+)
+item(tt(di 32))(
+for directories
+)
+item(tt(ln 36))(
+for symbolic links
+)
+item(tt(pi 31))(
+for named pipes (FIFOs)
+)
+item(tt(so 33))(
+for sockets
+)
+item(tt(bd 44;37))(
+for block devices
+)
+item(tt(cd 44;37))(
+for character devices
+)
+item(tt(ex 35))(
+for executable files
+)
+item(tt(mi) var(none))(
+for names not naming a file (default is the value defined for tt(fi))
+)
+item(tt(lc \e[))(
+for the left code (see below)
+)
+item(tt(rc m))(
+for the right code
+)
+item(tt(ec) var(none))(
+for the end code
+)
+enditem()
+
+Apart from these strings, the var(name) may also be an asterisk
+(`tt(*)') followed by any string. The var(value) given for such a
+string will be used for all files whose name ends with the string.
+
+When printing a match, the code prints the value of tt(lc), the value
+for the file-type or the last matching specification with a `tt(*)',
+the value of tt(rc), the string to display for the match itself, and
+then the value of tt(ec) if that is defined or the values of tt(lc),
+tt(no), and tt(rc) if tt(ec) is not defined.
+
+The default values are ISO 6429 (ANSI) compliant and can be used on
+vt100 compatible terminals such as tt(xterm)s. On monochrome terminals
+the default values will have no visual effect.
+
+Whenever one of the parameters tt(ZLS_COLORS) or tt(ZLS_COLOURS) is set 
+and the tt(complist) module is loaded or linked into the shell,
+completion lists will be colored.
+
+subsect(Menu selection)
+The tt(complist) module also offers a different style of selecting
+matches from a list called menu-selection. It can be invoked directly by
+the widget tt(menu-select) defined by the module.  Alternatively,
+the parameter tt(SELECTMIN) can be set to an integer giving the minimum
+number of matches which must be present before menu selection is
+automatically turned on.  This second method requires that menu completion
+be started, either directly from a widget such as tt(menu-complete), or due
+to one of the options tt(MENU_COMPLETE) or tt(AUTO_MENU) being set.  If
+tt(SELECTMIN) is set, but is 0, 1 or empty, menu selection will always be
+started during menu completion if the completion is ambiguous.
+
+After menu-selection is started, the matches will be listed. The
+matches to insert into the command line can be selected from this
+list. In the list one match is highlighted using the value for tt(ma)
+from the tt(ZLS_COLORS) or tt(ZLS_COLOURS) parameter. The default
+value for this it `tt(7)' which forces the selected match to be
+highlighted using standout mode on a vt100 compatible terminal.
+
+Selecting matches is done by moving the mark around using the zle movement
+functions. The zle functions tt(send-break) and tt(accept-line) can be used
+to leave menu-selection, leaving the match currently inserted into the line
+in place. The functions tt(accept-and-hold) and
+tt(accept-and-menu-complete) can be used to accept the match currently
+inserted and continue inserting matches after that. Matches inserted this
+way can be removed by invoking the tt(undo) function. Keys bound to one of
+the completion functions will cycle to the next (or, in case of
+tt(reverse-menu-complete), the previous) match, and the tt(redisplay) and
+tt(clear-screen) functions work as usual without leaving
+menu-selection. Any other zle function leaves menu-selection and executes
+that function.
+
+During this selection the widget uses the keymap tt(menuselect). Any
+key that is not defined in this keymap or that is bound to
+tt(undefined-key) is looked up in the keymap currently selected. This
+is used to ensure that the most important keys used during selection
+have sensible default (namely the cursor keys, return, and TAB). However,
+keys in the the tt(menuselect) keymap can be modified directly using the
+tt(bindkey) builtin command (see
+ifzman(zmanref(zshmodules))\
+ifnzman(noderef(The zle Module))\
+).
diff --git a/Doc/Zsh/mod_deltochar.yo b/Doc/Zsh/mod_deltochar.yo
index f92a3da0d..4c3cf58e6 100644
--- a/Doc/Zsh/mod_deltochar.yo
+++ b/Doc/Zsh/mod_deltochar.yo
@@ -1,4 +1,4 @@
-texinode(The deltochar Module)(The example Module)(The compctl Module)(Zsh Modules)
+texinode(The deltochar Module)(The example Module)(The complist Module)(Zsh Modules)
 sect(The deltochar Module)
 The tt(deltochar) module makes available one ZLE function:
 
diff --git a/Doc/Zsh/mod_zle.yo b/Doc/Zsh/mod_zle.yo
index ad88c94c7..f29ab0fd6 100644
--- a/Doc/Zsh/mod_zle.yo
+++ b/Doc/Zsh/mod_zle.yo
@@ -67,7 +67,7 @@ with the var(new-keymap) name, it is deleted.
 item(tt(-N) var(new-keymap) [ var(old-keymap) ])(
 Create a new keymap, named var(new-keymap).  If a keymap already has that
 name, it is deleted.  If an var(old-keymap) name is given, the new keymap
-is initialised to be a duplicate of it, otherwise the new keymap will
+is initialized to be a duplicate of it, otherwise the new keymap will
 be empty.
 )
 enditem()
@@ -161,12 +161,13 @@ cindex(widgets, calling)
 cindex(calling widgets)
 cindex(widgets, defining)
 cindex(defining widgets)
-xitem(tt(zle) tt(-l) [ tt(-L) ])
+xitem(tt(zle) tt(-l) [ tt(-L) ] [ tt(-a) ] [ var(string) ... ])
 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) var(widget) var(completion-widget) var(function))
-item(tt(zle) var(widget))(
+xitem(tt(zle) tt(-R) [ var(display-string) ])
+item(tt(zle) var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)(
 The tt(zle) builtin performs a number of different actions concerning
 ZLE.  Which operation it performs depends on its options:
 
@@ -175,7 +176,15 @@ item(tt(-l) [ tt(-L) ])(
 List all existing user-defined widgets.  If the tt(-L)
 option is used, list in the form of tt(zle)
 commands to create the widgets.
-Built-in widgets are not listed.
+
+When combined with the tt(-a) option, all widget names are listed,
+including the builtin ones. In this case the tt(-L) option is ignored.
+
+If at least one var(string) is given, nothing will be printed but the
+return status will be zero if all var(string)s are names of existing
+widgets (or of user-defined widgets if the tt(-a) flag is not given)
+and non-zero if at least one var(string) is not a name of an defined
+widget.
 )
 item(tt(-D) var(widget) ...)(
 Delete the named var(widget)s.
@@ -191,7 +200,11 @@ Create a user-defined widget.  If there is already a widget with the
 specified name, it is overwritten.  When the new
 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.
+the same name as the widget.  For further information, see the section
+em(Widgets) in
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor))\
+.
 )
 item(tt(-C) var(widget) var(completion-widget) var(function))(
 Create a user-defined completion widget names var(widget). The 
@@ -203,9 +216,38 @@ ifzman(zmanref(zshcompwid))\
 ifnzman(noderef(Completion Widgets))\
 .
 )
-item(var(widget))(
+item(tt(-R) [ var(display-string) ])(
+Redisplay the command line; this is to be called from within a user-defined
+widget to allow changes to become visible.  If a var(display-string) is
+given, this is shown in the status line (immediately below the line being
+edited).
+)
+item(var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)(
 Invoke the specified widget.  This can only be done when ZLE is
 active; normally this will be within a user-defined widget.
+
+With the options tt(-n) and tt(-N), the current numerical argument will be
+saved and then restored after the call to tt(widget); `tt(-n) var(num)'
+sets the numerical argument temporarily to var(num), while `tt(-N)' sets it
+to the default, i.e. as if there were none.
+
+Any further arguments will be passed to the widget.  If it is a shell
+function, these are passed down as postional parameters; for builtin
+widgets it is up to the widget in question what it does with them.
+Currently arguments are only handled by the incremental-search commands,
+the tt(history-search-forward) and tt(-backward) and the corresponding
+functions prefixed by tt(vi-), and by tt(universal-argument).  No error is
+flagged if the command does not use the arguments, or only uses some of
+them.
+
+The return status reflects the success or failure of the operation carried
+out by the widget, or if it is a user-defined widget the return status of
+the shell function.  
+
+A non-zero return status causes the shell to beep when the widget exits,
+unless the tt(BEEP) options was unset or the widget was called via the
+tt(zle) command.  Thus if a user defined widget requires an immediate beep,
+it should call the tt(beep) widget directly.
 )
 enditem()
 )
diff --git a/Doc/Zsh/modules.yo b/Doc/Zsh/modules.yo
index 0b487f673..12066b773 100644
--- a/Doc/Zsh/modules.yo
+++ b/Doc/Zsh/modules.yo
@@ -22,6 +22,9 @@ item(tt(compctl))(
 The tt(compctl) builtin for controlling completion and the builtins for
 completion widgets.
 )
+item(tt(complist))(
+Completion listing extensions.
+)
 item(tt(deltochar))(
 A ZLE function duplicating EMACS' tt(zap-to-char).
 )
@@ -55,6 +58,7 @@ menu(The cap Module)
 menu(The clone Module)
 menu(The comp1 Module)
 menu(The compctl Module)
+menu(The complist Module)
 menu(The deltochar Module)
 menu(The example Module)
 menu(The files Module)
@@ -69,6 +73,7 @@ includefile(Zsh/mod_cap.yo)

 includefile(Zsh/mod_clone.yo)

 includefile(Zsh/mod_comp1.yo)

 includefile(Zsh/mod_compctl.yo)

+includefile(Zsh/mod_complist.yo)

 includefile(Zsh/mod_deltochar.yo)

 includefile(Zsh/mod_example.yo)

 includefile(Zsh/mod_files.yo)

diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo
index 472364d3e..265c5e184 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -34,6 +34,12 @@ Some of the single letter option names refer to an option being off,
 in which case the inversion of that name refers to the option being on.
 For example, `tt(PLUS()n)' is the short name of `tt(exec)', and
 `tt(-n)' is the short name of its inversion, `tt(noexec)'.
+
+In strings of single letter options supplied to the shell at startup,
+trailing whitespace will be ignored; for example the string `tt(-f    )'
+will be treated just as `tt(-f)', but the string `tt(-f i)' is an error.
+This is because many systems which implement the `tt(#!)' mechanism for
+calling scripts do not strip trailing whitespace.
 texinode(Description of Options)(Option Aliases)(Specifying Options)(Options)
 sect(Description of Options)
 cindex(options, description)
@@ -551,7 +557,10 @@ pindex(LIST_BEEP)
 cindex(beep, ambiguous completion)
 cindex(completion, beep on ambiguous)
 item(tt(LIST_BEEP))(
-Beep on an ambiguous completion.
+Beep on an ambiguous completion.  More accurately, this forces the
+completion widgets to return status 1 on an ambiguous completion, which
+causes the shell to beep if the option tt(BEEP) is also set; this may
+be modified if completion is called from a user-defined widget.
 )
 pindex(LIST_TYPES)
 cindex(marking file types)
@@ -572,6 +581,22 @@ A shell function can also guarantee itself a known shell configuration
 with a formulation like `tt(emulate -L zsh)'; the tt(-L) activates
 tt(LOCAL_OPTIONS).
 )
+pindex(LOCAL_TRAPS)
+item(tt(LOCAL_TRAPS))(
+If this option is set when a signal trap is set inside a function, then the
+previous status of the trap for that signal will be restored when the
+function exits.  Note that this option must be set em(prior) to altering the
+trap behaviour in a function; unlike tt(LOCAL_OPTIONS), the value on exit
+from the function is irrelevant.  However, it does not need to be set
+before any global trap for that to be correctly restored by a function.
+For example,
+
+example(unsetopt localtraps
+trap - INT
+fn() { setopt localtraps; trap '' INT; sleep 3; })
+
+will restore normally handling of tt(SIGINT) after the function exits.
+)
 pindex(LOGIN)
 item(tt(LOGIN) (tt(-l), ksh: tt(-l)))(
 This is a login shell.
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index be820f160..9353ec977 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -26,7 +26,7 @@ In the parameter lists that follow, the mark `<S>' indicates that the
 parameter is special.
 Special parameters cannot have their type changed, and they stay special even
 if unset.  `<Z>' indicates that the parameter does not exist when the shell
-initialises in tt(sh) or tt(ksh) emulation mode.
+initializes in tt(sh) or tt(ksh) emulation mode.
 startmenu()
 menu(Array Parameters)
 menu(Positional Parameters)
@@ -316,7 +316,7 @@ as determined at compile time.
 )
 vindex(OLDPWD)
 item(tt(OLDPWD))(
-The previous working directory.  This is set when the shell initialises
+The previous working directory.  This is set when the shell initializes
 and whenever the directory changes.
 )
 vindex(OPTARG)
@@ -339,7 +339,7 @@ The process ID of the parent of the shell.
 )
 vindex(PWD)
 item(tt(PWD))(
-The present working directory.  This is set when the shell initialises
+The present working directory.  This is set when the shell initializes
 and whenever the directory changes.
 )
 vindex(RANDOM)
@@ -592,7 +592,7 @@ item(tt(module_path) <S> <Z> (tt(MODULE_PATH) <S>))(
 An array (colon-separated list)
 of directories that tt(zmodload)
 searches for dynamically loadable modules.
-This is initialised to a standard pathname,
+This is initialized to a standard pathname,
 usually `tt(/usr/local/lib/zsh/$ZSH_VERSION)'.
 (The `tt(/usr/local/lib)' part varies from installation to installation.)
 For security reasons, any value set in the environment when the shell
@@ -858,6 +858,19 @@ item(tt(WORDCHARS) <S>)(
 A list of non-alphanumeric characters considered part of a word
 by the line editor.
 )
+vindex(ZBEEP)
+item(tt(ZBEEP))(
+If set, this gives a string of characters, which can use all the same codes
+as the tt(bindkey) command as described in
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor))\
+, that will be output to the terminal
+instead of beeping.  This may have a visible instead of an audible effect;
+for example, the string `tt(\e[?5h\e[?5l)' on a vt100 or xterm will have
+the effect of flashing reverse video on and off (if you usually use reverse
+video, you should use the string `tt(\e[?5l\e[?5h)' instead).  This takes
+precedence over the tt(NOBEEP) option.
+)
 vindex(ZDOTDIR)
 item(tt(ZDOTDIR))(
 The directory to search for shell startup files (.zshrc, etc),
diff --git a/Doc/Zsh/zftpsys.yo b/Doc/Zsh/zftpsys.yo
index 60f5be60d..d806a49b5 100644
--- a/Doc/Zsh/zftpsys.yo
+++ b/Doc/Zsh/zftpsys.yo
@@ -47,7 +47,7 @@ two letters `tt(zf)'.  They may already have been installed on your system;
 otherwise, you will need to find them and copy them.  The directory should
 appear as one of the elements of the tt($fpath) array (this should already
 be the case if they were installed), and at least the function tt(zfinit)
-should be autoloaded; it will autoload the rest.  Finally, to initialise
+should be autoloaded; it will autoload the rest.  Finally, to initialize
 the use of the system you need to call the tt(zfinit) function.  The
 following code in your tt(.zshrc) will arrange for this; assume the
 functions are stored in the directory tt(~/myfns):
@@ -59,7 +59,7 @@ zfinit)
 Note that tt(zfinit) assumes you are using the tt(zmodload) method to
 load the tt(zftp) command.  If it is already built into the shell, change
 tt(zfinit) to tt(zfinit -n).  It is helpful (though not essential) if the
-call to tt(zfinit) appears after any code to initialise the new completion
+call to tt(zfinit) appears after any code to initialize the new completion
 system, else unnecessary tt(compctl) commands will be given.
 
 texinode(Zftp Functions)(Miscellaneous Features)(Installation)(Zftp Function System)
@@ -324,7 +324,7 @@ alter tt(zftp_chpwd) and tt(zftp_progress), in particular.
 
 startitem()
 item(tt(zfinit [ -n ]))(
-As described above, this is used to initialise the zftp function system.
+As described above, this is used to initialize the zftp function system.
 The tt(-n) option should be used if the zftp command is already built into
 the shell.
 )
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 743fb7f93..ce1b27fec 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -102,7 +102,8 @@ cindex(widgets, user-defined)
 User-defined widgets, being implemented as shell functions,
 can execute any normal shell command.  They can also run other widgets
 (whether built-in or user-defined) using the tt(zle) builtin command.
-Finally, they can examine and edit the ZLE buffer being edited by
+They can use tt(read -k) or tt(read -q) to read characters from standard
+input.  Finally, they can examine and edit the ZLE buffer being edited by
 reading and setting the special parameters described below.
 
 cindex(parameters, editor)
@@ -162,7 +163,11 @@ and meta-keys are reported with a leading `tt(M-)', as in `tt(M-a)' and
 )
 vindex(NUMERIC)
 item(tt(NUMERIC) (integer))(
-The numeric argument.
+The numeric argument. If no numeric argument was given, this parameter
+is unset. When this is set inside a widget function, builtin widgets
+called with the tt(zle) builtin command will use the value
+assigned. If it is unset inside awidget function, builtin widgets
+called behave as if no numeric argument was given.
 )
 vindex(HISTNO)
 item(tt(HISTNO) (integer))(
@@ -346,6 +351,10 @@ item(tt(down-line-or-search))(
 Move down a line in the buffer, or if already at the bottom line,
 search forward in the history for a line beginning with the first
 word in the buffer.
+
+If called from a function by the tt(zle) command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
 )
 tindex(down-history)
 item(tt(down-history) (unbound) (^N) (unbound))(
@@ -414,6 +423,17 @@ search, leaving the last found line in the buffer. Any single character that
 is not bound to one of the above functions, or tt(self-insert) or
 tt(self-insert-unmeta), will have the same effect but the function will be
 executed.
+
+When called from a widget function by the tt(zle) command, the incremental
+search commands can take a string argument.  This will be treated as a
+string of keys, as for arguments to the tt(bindkey) command, and used as
+initial input for the command.  Any characters in the string which are
+unused by the incremental search will be silently ignored.  For example,
+
+example(zle history-incremental-search-backward forceps)
+
+will search backwards for tt(forceps), leaving the minibuffer containing
+the string `tt(forceps)'.
 )
 tindex(history-incremental-search-forward)
 item(tt(history-incremental-search-forward) (^S ^Xs) (unbound) (unbound))(
@@ -427,6 +447,10 @@ tindex(history-search-backward)
 item(tt(history-search-backward) (ESC-P ESC-p) (unbound) (unbound))(
 Search backward in the history for a line beginning with the first
 word in the buffer.
+
+If called from a function by the tt(zle) command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
 )
 tindex(vi-history-search-backward)
 item(tt(vi-history-search-backward) (unbound) (/) (unbound))(
@@ -454,18 +478,27 @@ tt(magic-space) is treated as a space.
 Any other character that is not bound to self-insert or
 self-insert-unmeta will beep and be ignored. If the function is called from vi
 command mode, the bindings of the current insert mode will be used.
+
+If called from a function by the tt(zle) command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
 )
 tindex(history-search-forward)
 item(tt(history-search-forward) (ESC-N ESC-n) (unbound) (unbound))(
 Search forward in the history for a line beginning with the first
 word in the buffer.
+
+If called from a function by the tt(zle) command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
 )
 tindex(vi-history-search-forward)
 item(tt(vi-history-search-forward) (unbound) (?) (unbound))(
 Search forward in the history for a specified string.
 The string may begin with `tt(^)' to anchor the search to the
 beginning of the line. The functions available in the mini-buffer are the same
-as for tt(vi-history-search-backward).
+as for tt(vi-history-search-backward).  Argument handling is also the same
+as for that command.
 )
 tindex(infer-next-history)
 item(tt(infer-next-history) (^X^N) (unbound) (unbound))(
@@ -504,6 +537,10 @@ item(tt(up-line-or-search))(
 Move up a line in the buffer, or if already at the top line,
 search backward in the history for a line beginning with the
 first word in the buffer.
+
+If called from a function by the tt(zle) command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
 )
 tindex(up-history)
 item(tt(up-history) (unbound) (^P) (unbound))(
@@ -800,7 +837,11 @@ startitem()
 tindex(digit-argument)
 item(tt(digit-argument) (ESC-0..ESC-9) (1-9) (unbound))(
 Start a new numeric argument, or add to the current one.
-See also tt(vi-digit-or-beginning-of-line).
+See also tt(vi-digit-or-beginning-of-line).  This only works if bound to a
+key sequence ending in a decimal digit.
+
+Inside a widget function, a call to this function treats the last key of
+the key sequence which called the widget as the digit.
 )
 tindex(neg-argument)
 item(tt(neg-argument) (ESC--) (unbound) (unbound))(
@@ -815,6 +856,10 @@ repeated using this command.  For example, if this command occurs
 twice, followed immediately by tt(forward-char), move forward sixteen
 spaces; if instead it is followed by tt(-2), then tt(forward-char),
 move backward two spaces.
+
+Inside a widget function, if passed an argument, i.e. `tt(zle
+universal-argument) var(num)', the numerical argument will be set to
+var(num); this is equivalent to `tt(NUMERIC=)var(num)'.
 )
 enditem()
 texinode(Completion)(Miscellaneous)(Arguments)(Zsh Line Editor)
@@ -911,6 +956,10 @@ item(tt(accept-line-and-down-history) (^O) (unbound) (unbound))(
 Execute the current line, and push the next history
 event on the the buffer stack.
 )
+tindex(beep)
+item(tt(beep))(
+Beep, unless the tt(BEEP) option is unset.
+)
 tindex(vi-cmd-mode)
 item(tt(vi-cmd-mode) (^X^V) (unbound) (^[))(
 Enter command mode; that is, select the `tt(vicmd)' keymap.
diff --git a/Doc/zsh.yo b/Doc/zsh.yo
index b9279e660..d59afff7d 100644
--- a/Doc/zsh.yo
+++ b/Doc/zsh.yo
@@ -15,12 +15,10 @@ ifnzman(\
 def(ifzshone)(1)()\
 def(ifzshall)(1)()\
 )\
-ifztexi(\
+ifztexi(
 texinfo(zsh.info)(zsh)
-NOTRANS(@setchapternewpage off
-@iftex
+NOTRANS(@iftex
 @finalout
-@afourpaper
 @end iftex)
 texititlepage()
 texititle(The Z Shell Guide)
diff --git a/Doc/ztexi.yo b/Doc/ztexi.yo
index c3c1928cf..971947ac6 100644
--- a/Doc/ztexi.yo
+++ b/Doc/ztexi.yo
@@ -11,7 +11,6 @@ def(CMT)(0)(NOTRANS(@c))
 
 ATEXIT(\
   NL()\
-  NOTRANS(@setchapternewpage off)NL()\
   NOTRANS(@contents)NL()\
   NOTRANS(@bye)NL()\
 )
@@ -47,6 +46,10 @@ def(texinfo)(2)(\
   STDPAR()\
   NOTRANS(\input texinfo.tex)NL()\
   NOTRANS(@c %**start of header)NL()\
+  NOTRANS(@iftex)NL()\
+  NOTRANS(@afourpaper)NL()\
+  NOTRANS(@setchapternewpage off)NL()\
+  NOTRANS(@end iftex)NL()\
   NOTRANS(@setfilename )ARG1NL()\
   NOTRANS(@settitle )ARG2NL()\
   NOTRANS(@c %**end of header)NL()\