zsh-3.1.5-pws-25 dot-zsh-199907031715

16 files changed, 243 insertions, 121 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 3b3ba70c0..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,15 +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.
-May be called from a zle widget, in which case it will use zle to retrieve
-a key.
+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.  May be called from a zle widget with no tt(-u)
-or tt(-p) argument, in which case it will use zle to retrieve a key.
+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
@@ -905,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))(
@@ -944,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
@@ -1192,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.
@@ -1287,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 20721dfec..8f7c23f25 100644
--- a/Doc/Zsh/compctl.yo
+++ b/Doc/Zsh/compctl.yo
@@ -13,7 +13,7 @@ tt(compctl) command.
 )\
 ifnzman(\
 sect(Types of completion)
-This version of zsh has two ways of performing completino of words on the
+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
@@ -633,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 f481ee4c0..2de4e4bd7 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -6,51 +6,29 @@ cindex(completion, controlling)
 sect(Description)
 
 This describes the shell code for the new completion system.  It consists
-of two scripts and a few other files that define shell functions.
-The shell functions which implement completion behaviour and which may
-be bound to keystrokes, are referred to as `widgets'.  All are contained
-in the following subdirectories of the tt(Completion) directory of the main
-distribution directory.
-
-startitem()
-item(tt(Core))(
-The core scripts and functions.  You will certainly need these, though will
-probably not need to alter them.  The contents of this directory is
-described in more detail below.
-)
-item(tt(Base))(
-Other functions you will almost certainly want if you are going to use
-any of the standard completion functions.  You may want to edit some of
-these files.
-)
-item(tt(Builtins))(
-Functions for completing arguments of shell builtin commands.
-)
-item(tt(User))(
-Functions for completing arguments of external commands and suites of
-commands.  They may need modifying for your system.
-)
-item(tt(Commands))(
-Functions which implement special types of completion to be bound to
-keystrokes rather than called by context.
-)
-enditem()
-
-You should decide which files you will be using and copy them to a
-directory (or multiple directories) of your own which should appear in your
-tt($fpath) variable so that the functions can be autoloaded.
+of varsious shell functions; those beginning `tt(comp)' are to be called
+directly by the user, while those beginning `tt(_)' are called by the
+completion code.  The shell functions of the second set which implement
+completion behaviour and which may be bound to keystrokes, are referred to
+as `widgets'.
 
 startmenu()
 menu(Initialization)
 menu(Control Functions)
 menu(Completion Functions)
+menu(Completion Directories)
 endmenu()
 
 texinode(Initialization)(Control Functions)()(Completion System)
 sect(Initialization)
 
-The script 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
+The function tt(compinstall) can be run by a user to set up the completion
+system for use, which also provides options for more advanced usage.
+However, if the system was installed completely, it should be enough to
+call the shell function tt(compinit) from your initialization file; see the
+next section.
+
+Usually, tt(compinstall) will 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
 added to tt(.zshrc) are actually run; you may, for example, need to move
@@ -62,10 +40,10 @@ 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 initialization after the first time.  After
 that, you will be asked if you wish to go on to the advanced set-up; if you
@@ -86,30 +64,21 @@ 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 initialize 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).
+configuration which will be read in on future invocations; this is the
+default, although it can be turned off by calling tt(compinit) with the
+option tt(-D).  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 option
+tt(-d).  On the next call to tt(compinit -d), the dumped file will be read
+instead.
 
 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
@@ -117,27 +86,34 @@ 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.
+
+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.
 
 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
@@ -165,7 +141,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
@@ -248,8 +228,8 @@ enditem()
 texinode(Control Functions)(Completion Functions)(Initialization)(Completion System)
 sect(Control Functions)
 
-The initialization script tt(compinit) re-binds all the keys which perform
-completion to newly created widgets that all call the supplied widget
+The initialization script tt(compinit) redefines all the widgets
+which perform completion to call the supplied widget
 function tt(_main_complete). This function acts as a wrapper calling
 the so-called `completer' functions that generate matches. If
 tt(_main_complete) is
@@ -474,6 +454,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
@@ -620,7 +606,7 @@ enditem()
 )
 enditem()
 
-texinode(Completion Functions)()(Control Functions)(Completion System)
+texinode(Completion Functions)(Completion Directories)(Control Functions)(Completion System)
 sect(Utility Functions)
 
 Descriptions follow for utility functions that may be
@@ -707,10 +693,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
@@ -779,3 +768,37 @@ accepts the option `tt(-t)'; if this is given, completion is only done
 on words starting with two hyphens.
 )
 enditem()
+
+texinode(Completion Directories)()(Completion Functions)(Completion System)
+sect(Completion Directories)
+
+In the source distribution, the files are contained in various
+subdirectories of the tt(Completion) directory.  They may have been
+installed in the same structure, or into one single function directory.
+The following is a description of the files found in the original directory
+structure.  If you wish to alter an installed file, you will need to copy
+it to some directory which appears earlier in your tt(fpath) than the
+standard directory where it appears.
+
+startitem()
+item(tt(Core))(
+The core scripts and functions.  You will certainly need these, though will
+probably not need to alter them.  Many of these are docmented above.
+)
+item(tt(Base))(
+Other functions you will almost certainly want if you are going to use
+any of the standard completion functions.  You may want to edit some of
+these files.
+)
+item(tt(Builtins))(
+Functions for completing arguments of shell builtin commands.
+)
+item(tt(User))(
+Functions for completing arguments of external commands and suites of
+commands.  They may need modifying for your system.
+)
+item(tt(Commands))(
+Functions which implement special types of completion to be bound to
+keystrokes rather than called by context.
+)
+enditem()
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 923323aa7..644578354 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -238,7 +238,9 @@ upwards (e.g. `tt(2:4)' specifies the fourth match of the second group).
 Negative numbers count backward from the last match or group (with `tt(-1)'
 selecting the last match or group) and out-of-range values are wrapped
 around, so that a value of zero selects the last match or group and a value
-one more than the maximum selects the first.
+one more than the maximum selects the first. Unless the value of this
+key ends in a space, the match is inserted as in a menu-completion,
+i.e. without automatically appending a space.
 )
 item(tt(to_end))(
 Specifies the occasions on which the cursor is moved to the end of a string
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
index 460d4a609..101f4e69c 100644
--- a/Doc/Zsh/mod_complist.yo
+++ b/Doc/Zsh/mod_complist.yo
@@ -92,12 +92,17 @@ 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.
+highlighted using standout mode on a vt100 compatible terminal. If
+neither tt(ZLS_COLORS) nor tt(ZLS_COLOURS) is set, the same terminal
+control sequence is used as for the `tt(%S)' escape in prompts.
 
 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
+in place. In the case of tt(accept-line), the match currently inserted
+will be accepted and the immediatly trying completion again will
+complete after it. Using tt(send-break) leaves menu-selection and
+continues with normal menu-completion. 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
@@ -116,4 +121,9 @@ 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))\
-).
+). For example, to make the return key leave menu-selection and
+continue with normal menu-completion one can call
+
+indent(tt(bindkey -M menuselect '^J' send-break))
+
+after loading the tt(complist) 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 185f5118a..cae4eadc2 100644
--- a/Doc/Zsh/mod_zle.yo
+++ b/Doc/Zsh/mod_zle.yo
@@ -72,6 +72,17 @@ be empty.
 )
 enditem()
 
+To use a newly created keymamp, it should be linked to tt(main).  Hence
+the sequence of commands to create and use a new keymap `tt(mymap)'
+initialized from the tt(emacs) keymap (which remains unchanged) is:
+
+example(bindkey -N mymap emacs
+bindkey -A mymap main)
+
+Note that while `tt(bindkey -A) var(newmap) tt(main)' will work when
+var(newmap) is tt(emacs) or tt(viins), it will not work for tt(vicmd), as
+switching from vi insert to command mode becomes impossible.
+
 The following operations require a keymap to be selected:
 
 startitem()
@@ -161,7 +172,7 @@ 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) ])
@@ -176,7 +187,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.
@@ -234,7 +253,12 @@ 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.
+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 e7029370d..265c5e184 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -557,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)
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index 9f0b34193..ecf93864f 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -299,8 +299,11 @@ The current hostname.
 )
 vindex(LINENO)
 item(tt(LINENO) <S>)(
-The line number of the current line within the current script
-being executed.
+The line number of the current line within the current script, sourced
+file, or shell function being executed, whichever was started most
+recently.  Note that in the case of shell functions the line
+number refers to the function as it appeared in the original definition,
+not necesarily as displayed by the tt(functions) builtin.
 )
 vindex(LOGNAME)
 item(tt(LOGNAME))(
@@ -647,7 +650,9 @@ The default is `tt(?# )'.
 )
 vindex(PS4)
 item(tt(PS4) <S>)(
-The execution trace prompt.  Default is `tt(PLUS() )'.
+The execution trace prompt.  Default is `tt(PLUS()%N:%i> )', which displays
+the name of the current shell structure and the line number within it.
+In sh or ksh emulation, the default is `tt(PLUS() )'.
 )
 vindex(PROMPT)
 xitem(tt(PROMPT) <S> <Z>)
@@ -858,6 +863,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/prompt.yo b/Doc/Zsh/prompt.yo
index 685cca8c4..29f1f2c22 100644
--- a/Doc/Zsh/prompt.yo
+++ b/Doc/Zsh/prompt.yo
@@ -95,6 +95,16 @@ Current time of day in 24-hour format, with seconds.
 item(tt(%n))(
 tt($USERNAME).
 )
+item(tt(%N))(
+The name of the script, sourced file, or shell function that zsh is
+currently executing, whichever was started most recently.  If there is
+none, this is equivalent to the parameter tt($0).
+)
+item(tt(%i))(
+The line number currently being executed in the script, sourced file, or
+shell function given by tt(%N).  This is most useful for debugging as part
+of tt($PS4).
+)
 item(tt(%w))(
 The date in var(day)tt(-)var(dd) format.
 )
@@ -122,7 +132,9 @@ item(tt(%_))(
 The status of the parser, i.e. the shell constructs (like `tt(if)' and
 `tt(for)') that have been started on the command line. If given an integer
 number that many strings will be printed; zero or no integer means
-print as many as there are.
+print as many as there are.  This is most useful in prompts tt(PS2) for
+continuation lines and tt(PS4) for debugging with the tt(XTRACE) option; in
+the latter case it will also work non-interactively.
 )
 item(tt(%E))(
 Clears to end of line.
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index ba197facf..ce1b27fec 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -103,8 +103,7 @@ 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.
 They can use tt(read -k) or tt(read -q) to read characters from standard
-input, which will use the appropriate tt(zle) key input mechanism.
-Finally, they can examine and edit the ZLE buffer being edited by
+input.  Finally, they can examine and edit the ZLE buffer being edited by
 reading and setting the special parameters described below.
 
 cindex(parameters, editor)
@@ -957,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.