22 files changed, 434 insertions, 208 deletions

diff --git a/Doc/Zsh/arith.yo b/Doc/Zsh/arith.yo
index 80c023301..bb91b6fe9 100644
--- a/Doc/Zsh/arith.yo
+++ b/Doc/Zsh/arith.yo
@@ -7,12 +7,11 @@ cindex(arithmetic evaluation)
 cindex(evaluation, arithmetic)
 findex(let, use of)
 The shell can perform integer arithmetic, either using the builtin tt(let),
-or via a substitution of the form tt($((...))).  Usually arithmetic is
-performed with em(long) integers; however, on certain systems where a
-em(long) has 4-byte precision, zsh may be compiled to use 8-byte precision
-instead.  This can be tested, for example, by giving the command
-`tt(print - $(( 12345678901 )))'; if the number appears unchanged, the
-precision is at least 8 bytes.
+or via a substitution of the form tt($((...))).  The shell is usually
+compiled to use 8-byte precision where this is available, otherwise
+precision is 4 bytes.  This can be tested, for example, by giving the
+command `tt(print - $(( 12345678901 )))'; if the number appears unchanged,
+the precision is at least 8 bytes.
 
 The tt(let) builtin command takes arithmetic expressions as arguments; each
 is evaluated separately.  Since many of the arithmetic operators, as well
@@ -85,7 +84,7 @@ Named parameters and subscripted arrays can be referenced by name within an
 arithmetic expression without using the parameter expansion syntax.  For
 example,
 
-example((((val2 = val1 * 2))))
+example(((val2 = val1 * 2)))
 
 assigns twice the value of tt($val1) to the parameter named tt(val2).
 
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index f6e24ab51..2f1f37258 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -39,7 +39,8 @@ cindex(expanding parameters)
 cindex(parameters, expanding)
 cindex(doing nothing)
 item(tt(:) [ var(arg) ... ])(
-This command only expands parameters.  A zero exit code is returned.
+This command does nothing, although normal argument expansions is performed
+which may have effects on shell parameters.  A zero exit code is returned.
 )
 findex(alias)
 cindex(aliases, defining)
@@ -161,8 +162,8 @@ causes tt(disable) to act on aliases.  The tt(-f) option causes
 tt(disable) to act on shell functions.  The tt(-r) options causes
 tt(disable) to act on reserved words.  Without arguments all disabled
 hash table elements from the corresponding hash table are printed.
-With the tt(-m) flag the arguments are taken as patterns (should be
-quoted to preserve them from being taken as glob patterns), and all hash
+With the tt(-m) flag the arguments are taken as patterns (which should be
+quoted to prevent them from undergoing filename expansion), and all hash
 table elements from the corresponding hash table matching these patterns
 are disabled.  Disabled objects can be enabled with the tt(enable)
 command.
@@ -221,7 +222,16 @@ item(tt(emulate) [ tt(-LR) ] {tt(zsh)|tt(sh)|tt(ksh)|tt(csh)})(
 Set up zsh options to emulate the specified shell as much as possible.
 bf(csh) will never be fully emulated.
 If the argument is not one of the shells listed above, tt(zsh)
-will be used as a default.  If the tt(-R) option is given, all options
+will be used as a default; more precisely, the tests performed on the
+argument are the same as those used to determine the emulation at startup
+based on the shell name, see
+ifzman(\
+the section `Compatibility' in zmanref(zshmisc)
+)\
+ifnzman(\
+noderef(Compatibility)
+)\
+.  If the tt(-R) option is given, all options
 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
@@ -407,7 +417,7 @@ and for the named directory hash table this adds all users' home directories.
 These two options cannot be used with any arguments.
 
 The tt(-m) option causes the arguments to be taken as patterns
-(they should be quoted) and the elements of the hash table
+(which should be quoted) and the elements of the hash table
 matching those patterns are printed.  This is the only way to display
 a limited selection of hash table elements.
 
@@ -603,8 +613,8 @@ item(tt(-O))(
 Print the arguments sorted in descending order.
 )
 item(tt(-i))(
-If given together with tt(-o) or tt(-O), makes them work case
-independently.
+If given together with tt(-o) or tt(-O), sorting is performed
+case-independently.
 )
 item(tt(-c))(
 Print the arguments in columns.
@@ -810,8 +820,8 @@ Set the options for the shell.  All options specified either
 with flags or by name are set.  If no arguments are supplied,
 the names of all options currently set are printed.
 If the tt(-m) flag is given the arguments are taken as patterns
-(which should be quoted to preserve them from being interpreted as glob
-patterns), and all options with names matching these patterns are set.
+(which should be quoted to protect them from filename expansion), and all
+options with names matching these patterns are set.
 )
 findex(shift)
 cindex(parameters, positional)
@@ -882,7 +892,7 @@ For example,
 
 example(trap 'print $LINENO' DEBUG)
 
-will print the line number of command executed after it has run, while
+will print the line number of a command executed after it has run, while
 
 example(TRAPDEBUG() { print $LINENO; })
 
@@ -931,7 +941,7 @@ retain their special attributes when made local.
 
 For each var(name)tt(=)var(value) assignment, the parameter
 var(name) set to var(value).  Note that arrays currently cannot be
-assigned in tt(typeset) expressions; scalars and integers only.
+assigned in tt(typeset) expressions, only scalars and integers.
 
 For each remaining var(name) that refers to a parameter that is set, the
 name and value of the parameter are printed in the form of an assignment.
@@ -968,9 +978,9 @@ those parameters that have the specified attributes, and using `tt(PLUS())'
 rather than `tt(-)' to introduce the flag suppresses printing of the values
 of parameters when there is no parameter name.  Also, if the option list
 ends with `tt(PLUS())', values will not be printed.  If only the tt(-m)
-flag is given the arguments are taken as patterns (should be quoted) and
-all parameters (or functions with the tt(-f) flag) with matching names are
-printed.  If no attribute flags and no tt(-m) flag is present, the
+flag is given the arguments are taken as patterns (which should be quoted)
+and all parameters (or functions with the tt(-f) flag) with matching names
+are printed.  If no attribute flags and no tt(-m) flag is present, the
 parameter names will be preceded by a list of any attributes (tt(array),
 tt(association), tt(exported), tt(integer), tt(readonly)).
 
diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo
index 8f7c23f25..eaf257660 100644
--- a/Doc/Zsh/compctl.yo
+++ b/Doc/Zsh/compctl.yo
@@ -317,7 +317,7 @@ item(tt(-i) var(function))(
 Like tt(-K), but the function is invoked in a context like that for
 completion widgets, see 
 ifzman(zmanref(zshzle))\
-ifnzman(noderef(The zle Module))\
+ifnzman(noderef(The zle Module))
 for more information.
 )
 item(tt(-H) var(num pattern))(
@@ -422,7 +422,7 @@ tt(-K) option) which can examine the word components passed to it
 (or via the tt(read) builtin's tt(-c) and tt(-l) flags) and
 use its own criteria to decide what matches.  If there is no
 completion, the original word is retained.  Since the produced 
-possible completions seldom seldom have interesting common prefixes
+possible completions seldom have interesting common prefixes
 and suffixes, menucompletion is started immediately if tt(AUTO_MENU) is
 set and this flag is used.
 )
@@ -513,7 +513,7 @@ before all variables.
 item(tt(-V) var(name))(
 Like tt(-J), but matches within the group will not be sorted in listings
 nor in menucompletion. These unsorted groups are in a different name
-space than the sorted ones, so groups defined as tt(-J files) and tt(-V
+space from the sorted ones, so groups defined as tt(-J files) and tt(-V
 files) are distinct.
 )
 item(tt(-M) var(match-spec))(
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index cca636cdc..29f83da4a 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -1,6 +1,6 @@
 texinode(Completion System)(Zftp Function System)(Zsh Modules)(Top)
 chapter(Completion System)
-cindex(completion, system)
+cindex(completion system)
 cindex(completion, programmable)
 cindex(completion, controlling)
 sect(Description)
@@ -22,6 +22,8 @@ endmenu()
 
 texinode(Initialization)(Control Functions)()(Completion System)
 sect(Initialization)
+findex(compinstall)
+cindex(completion system, installing)
 
 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.
@@ -60,6 +62,8 @@ 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)
+findex(compinit)
+cindex(completion system, initializing)
 
 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
@@ -77,9 +81,9 @@ 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.
+alternatively, an explicit file name can be given by `tt(compinit -d)
+var(dumpfile)'.  On the next call to tt(compinit), the dumped file will be
+read instead of a full initialization.
 
 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
@@ -97,6 +101,7 @@ where completion functions can be found; this is only necessary if they are
 not already in the function search path.
 
 subsect(Autoloaded files)
+cindex(completion system, autoloaded functions)
 
 The convention for autoloaded functions used in completion is that they
 start with an underscore; as already mentioned, the tt(fpath/FPATH)
@@ -146,7 +151,9 @@ 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 tt(menu-select) widget can be used, too.  If the option tt(-n) is
+also given, the bindings will not be used if the key is already bound (that
+is, is bound to something other than tt(undefined-key)).
 
 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
@@ -172,6 +179,8 @@ subsect(Functions)
 The tt(compinit) file defines the following functions, which may
 also be called directly by the user.
 
+findex(compdef)
+cindex(completion system, adding definitions)
 startitem()
 xitem(tt(compdef) [ tt(-an) ] var(function names...))
 xitem(tt(compdef -d) var(names...))
@@ -195,15 +204,21 @@ and will otherwise behave like the builtin widget whose name is given as
 the var(style) argument. The widgets usable for this are:
 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), and tt(reverse-menu-complete).
+tt(menu-expand-or-complete), and tt(reverse-menu-complete), as well as
+tt(menu-select) if the tt(complist) module is loaded.  The option tt(-n)
+prevents the key being bound if it is already to bound to something other
+than tt(undefined-key).
 
 In each of the forms supporting it the tt(-a) option makes the
 var(function) autoloadable (exactly equivalent to
 tt(autoload )var(function)).
 )
+findex(compconf)
+cindex(completion system, configuring)
 xitem(tt(compconf) var(definitions...))
 xitem(tt(compconf) [ tt(-L) ] )
 item(tt(compconf) [ tt(-l) ] [ tt(-L) ] var(keys...))(
+vindex(compconfig)
 Several aspects of the completion system can be configured by the
 user. The configuration values are stored under the keys described
 below in the associative array `tt(compconfig)'.  After sourcing
@@ -228,6 +243,7 @@ enditem()
 
 texinode(Control Functions)(Completion Functions)(Initialization)(Completion System)
 sect(Control Functions)
+cindex(completion system, choosing completers)
 
 The initialization script tt(compinit) redefines all the widgets
 which perform completion to call the supplied widget
@@ -257,6 +273,7 @@ argument was given.
 The following completer functions are contained in the distribution (users
 may write their own):
 
+cindex(completion system, completers)
 startitem()
 item(tt(_complete))(
 This completer generates all possible completions in a context-sensitive
@@ -587,7 +604,7 @@ otherwise, the standard completion list will be generated:  this is the
 default behaviour of tt(_oldlist). However, if there is an old list
 and this key contains the name of the completer function that
 generated the list, then the old list will be used even if it was
-generated by a widget which does not listing.
+generated by a widget which does not do listing.
 
 For example, suppose you type tt(^Xc) to use the tt(_correct_word)
 widget, which generates a list of corrections for the word under the
@@ -606,7 +623,7 @@ matches generated on the first attempt will be used again.
 )
 item(tt(oldlist_menu))(
 Controls how menu completion behaves when a completion has already been
-inserted and the user types a standard completion key type as tt(TAB).
+inserted and the user types a standard completion key type such as tt(TAB).
 The default behaviour of tt(_oldlist) is that menu completion always
 continues with the existing list of completions.  If this key is set to
 tt(never), however, a new completion is started if the old list was
@@ -625,6 +642,7 @@ enditem()
 
 texinode(Completion Functions)(Completion Directories)(Control Functions)(Completion System)
 sect(Utility Functions)
+cindex(completion system, utility functions)
 
 Descriptions follow for utility functions that may be
 useful when writing completion functions.  Most of these reside in the
@@ -798,6 +816,7 @@ enditem()
 
 texinode(Completion Directories)(Bindable Commands)(Completion Functions)(Completion System)
 sect(Completion Directories)
+cindex(completion system, directory structure)
 
 In the source distribution, the files are contained in various
 subdirectories of the tt(Completion) directory.  They may have been
@@ -832,6 +851,7 @@ enditem()
 
 texinode(Bindable Commands)()(Completion Directories)(Completion System)
 sect(Bindable Commands)
+cindex(completion system, bindable commands)
 
 In addition to the context-dependent completions provided, which are
 expected to work in an intuitively obvious way, there are a few widgets
@@ -841,8 +861,9 @@ following is a list of these and their default bindings.
 startitem()
 item(tt(_correct_filename (^XC)))(
 Correct the filename path at the cursor position.  Allows up to six errors
-in the name.  Can also be correctly called with an argument to correct
-a filepath, independently of zle.
+in the name.  Can also be called with an argument to correct
+a filepath, independently of zle; the correction is printed on standard
+output.
 )
 item(tt(_correct_word) (^Xc))(
 Performs correction of the current argument using the usual contextual
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 62c243740..2497eb768 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -51,20 +51,24 @@ within the completion widget) to the values they had when the function was
 entered.
 
 startitem()
+vindex(words)
 item(tt(words))(
 This array contains the words present on the command line currently being
 edited.
 )
+vindex(CURRENT)
 item(tt(CURRENT))(
 This is the number of the current word, i.e. the word the cursor is
 currently on in the tt(words) array.  Note that this value is only
 correct if the tt(ksharrays) options is not set.
 )
+vindex(PREFIX)
 item(tt(PREFIX))(
 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; it may be altered
 to give a common prefix for all matches.
 )
+vindex(IPREFIX)
 item(tt(IPREFIX))(
 Initially this will be set to the empty string.  It functions like
 tt(PREFIX), and gives a string which precedes the one in tt(PREFIX) and is
@@ -76,8 +80,10 @@ example(IPREFIX=${PREFIX%%\=*}=
 PREFIX=${PREFIX#*=})
 
 causes the part of the prefix up to and including the first equal sign not
-to be treated as part of a matched string.
+to be treated as part of a matched string.  This can be done automatically
+by the tt(compset) builtin, see below.
 )
+vindex(QIPREFIX)
 item(tt(QIPREFIX))(
 This parameter is read-only and contains the quoted string up to the
 word being completed. E.g. when completing `tt("foo)', this parameter
@@ -85,6 +91,7 @@ contains the double quote. If the tt(-q) option of tt(compset) is used
 (see below), and the original string was `tt("foo bar)' with the
 cursor on the `tt(bar)', this parameter contains `tt("foo )'.
 )
+vindex(SUFFIX)
 item(tt(SUFFIX))(
 Initially this will be set to the part of the current word from the
 cursor position to the end; it may be altered to give a common suffix for
@@ -92,14 +99,18 @@ all matches.  It is most useful when the option tt(COMPLETE_IN_WORD) is
 set, as otherwise the whole word on the command line is treated as a
 prefix.
 )
+vindex(ISUFFIX)
 item(tt(ISUFFIX))(
 As tt(IPREFIX), but for a suffix that should not be considered part
 of the matches; note that the tt(ISUFFIX) string follows the tt(SUFFIX)
 string.
 )
+vindex(QISUFFIX)
 item(tt(QISUFFIX))(
 Like tt(QIPREFIX), but containing the suffix.
 )
+vindex(compstate)
+cindex(completion widgets, examining and setting state in)
 item(tt(compstate))(
 This is an associative array with various keys and values that the
 completion code uses to exchange information with the completion widget.
@@ -212,7 +223,7 @@ would normally cause them to be.  It will be set appropriately on entry to
 a completion widget and may be changed there.
 )
 item(tt(force_list))(
-If the value for the tt(list) key is tt(ambiguous), the list will
+If the value for the tt(list) key is tt(autolist) or tt(ambiguous), the list will
 normally be shown only if there are at least two matches in the
 list. Setting tt(force_list) to an non-empty string forces the list to be
 shown even if there is only one match.
@@ -236,7 +247,8 @@ matches is to be inserted; if set to tt(menu) or tt(automenu) the usual
 behaviour of the tt(MENU_COMPLETE) or tt(AUTO_MENU) options, respectively,
 is to be used.
 
-On exit it may be set to any of the values above, or to a number, in which
+On exit it may be set to any of the values above (where setting it to
+the empty string is the same as unsetting it), or to a number, in which
 case the match whose number is given will be inserted into the command line.
 It may also be set to a string of the form `var(group):var(match)' which
 specifies a match from a group of matches to be inserted, counting from 1
@@ -326,6 +338,7 @@ enditem()
 texinode(Builtin Commands)(Condition Codes)(Special Parameters)(Completion Widgets)
 sect(Builtin Commands)
 startitem()
+cindex(completion widgets, generating matches with flags)
 findex(compgen)
 item(tt(compgen) var(flags ...))(
 
@@ -351,6 +364,8 @@ builtin command.
 The return value is zero if at least one match was added and non-zero
 otherwise.
 )
+findex(compadd)
+cindex(completion widgets, adding specified matches)
 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) ])
@@ -556,6 +571,8 @@ hyphens.
 )
 enditem()
 )
+findex(compset)
+cindex(completion widgets, modifying special parameters)
 xitem(tt(compset -p) var(number))
 xitem(tt(compset -P) [ var(number) ] var(pattern))
 xitem(tt(compset -s) var(number))
@@ -662,6 +679,7 @@ enditem()
 
 texinode(Condition Codes)(Examples)(Builtin Commands)(Completion Widgets)
 sect(Condition Codes)
+cindex(completion widgets, condition codes)
 
 The following additional condition codes for use within the tt([[ ... ]])
 construct are available in completion widgets.  These work on the special
@@ -687,6 +705,7 @@ enditem()
 
 texinode(Examples)()(Condition Codes)(Completion Widgets)
 sect(Examples)
+cindex(completion widgets, examples)
 
 The first step is to define the widget:
 
@@ -711,3 +730,4 @@ source code distribution, see
 ifzman(zmanref(zshcompsys))\
 ifnzman(noderef(Completion System))\
 .
+
diff --git a/Doc/Zsh/cond.yo b/Doc/Zsh/cond.yo
index 0ff49b187..b24ebebc8 100644
--- a/Doc/Zsh/cond.yo
+++ b/Doc/Zsh/cond.yo
@@ -149,6 +149,20 @@ true if either var(exp1) or var(exp2) is true.
 )
 enditem()
 
+Normal shell expansion is performed on the var(file), var(string) and
+var(pattern) arguments, but the result of each expansion is constrained to
+be a single word, similar to the effect of double quotes.  However, pattern
+metacharacters are active for the var(pattern) arguments; the patterns
+are the same as those used for filename generation, see
+ifzman(\
+zmanref(zshexpn)
+)\
+ifnzman(\
+noderef(Filename Generation)
+)\
+, but there is no special behaviour
+of `tt(/)' nor initial dots, and no glob qualifiers are allowed.
+
 In each of the above expressions, if
 var(file) is of the form `tt(/dev/fd/)var(n)',
 where var(n) is an integer,
@@ -156,3 +170,14 @@ then the test applied to the open file whose
 descriptor number is var(n),
 even if the underlying system does not support
 the tt(/dev/fd) directory.
+
+In the forms which do numeric comparison, the expressions var(exp)
+undergo arithmetic expansion as if they were enclosed in tt($((...))).
+
+For example, the following:
+
+example([[ ( -f foo || -f bar ) && $report = y* ]] && print File exists.)
+
+tests if either file tt(foo) or file tt(bar) exists, and if so, if the
+value of the parameter tt(report) begins with `tt(y)'; if the complete
+condition is true, the message `tt(File exists.)' is printed.
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index bb75d4865..7eae493e0 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -185,9 +185,10 @@ resulting word doesn't change any more.
 item(tt(F:)var(expr)tt(:))(
 Like tt(f), but repeats only var(n) times if the expression
 var(expr) evaluates to var(n).  Any character can be used instead of
-the `tt(:)', if any of `tt(LPAR())', `tt([)', or `tt({)'
-is used as the opening delimiter
-the second one has to be 'tt(RPAR())', `tt(])', or `tt(})' respectively.
+the `tt(:)'; if `tt(LPAR())', `tt([)', or `tt({)'
+is used as the opening delimiter,
+the closing delimiter should be 'tt(RPAR())', `tt(])', or `tt(})',
+respectively.
 )
 item(tt(w))(
 Makes the immediately following modifier work on each word in the
@@ -246,7 +247,8 @@ will refer to the first and last words respectively, of the last command
 referenced on the current command line.  However, if they are the first history
 reference on the command line, then they refer to the previous command.
 
-The character sequence `tt(^)var(foo)tt(^)var(bar)'
+The character sequence `tt(^)var(foo)tt(^)var(bar)' (where `tt(^)' is
+actually the second charcter of the tt(histchars) parameter)
 repeats the last command, replacing the string var(foo) with var(bar).
 More precisely, the sequence `tt(^)var(foo)tt(^)var(bar)tt(^)' is
 synonymous with `tt(!!:s)tt(^)var(foo)tt(^)var(bar)tt(^)', hence other
@@ -290,7 +292,7 @@ Note that the file, which is passed as an argument to the command,
 is a system pipe, so programs that expect to lseek (see manref(lseek)(2))
 on the file will not work.
 Also note that the previous example can be more compactly and
-efficiently written as:
+efficiently written (provided the tt(MULTIOS) option is set) as:
 
 nofill(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR() > >LPAR())var(process1)tt(RPAR() > >LPAR())var(process2)tt(RPAR()))
 
@@ -320,7 +322,7 @@ and subscript notation to access individual array elements.
 
 In the expansions discussed below that require a pattern, the form of
 the pattern is the same as that used for filename generation;
-see noderef(Filename Generation).  Note that this pattern, along with
+see noderef(Filename Generation).  Note that these patterns, along with
 the replacement text of any substitutions, are themselves subject to
 parameter expansion, command substitution, and arithmetic expansion.
 In addition to the following operations, the file modifiers described in
@@ -340,11 +342,12 @@ modifiers appearing after the name, or any of the characters `tt(^)',
 `tt(=)', `tt(~)', `tt(#)' or `tt(+)' appearing before the name, all of
 which work with or without braces.
 
-If var(name) is an array parameter, then the value of each
-element of var(name) is substituted, one element per word.
-Otherwise, the expansion results in one word only; no field
-splitting is done on the result unless the tt(SH_WORD_SPLIT)
-option is set.
+If var(name) is an array parameter, and the tt(KSH_ARRAYS) option is not
+set, then the value of each
+element of var(name) is substituted, one element per word.  Otherwise, the
+expansion results in one word only; with tt(KSH_ARRAYS), this is the first
+element of an array.  No field splitting is done on the result unless the
+tt(SH_WORD_SPLIT) option is set.
 )
 item(tt(${PLUS())var(name)tt(}))(
 If var(name) is the name of a set parameter `tt(1)' is substituted,
@@ -363,9 +366,9 @@ set var(name) to var(word).  In both forms, the value of
 the parameter is then substituted.
 )
 item(tt(${)var(name)tt(:?)var(word)tt(}))(
-If var(name) is set and is non-null, then substitute
+If var(name) is set and is non-null then substitute
 its value; otherwise, print var(word) and exit from the shell.
-Interactive shells do not exit.
+Interactive shells instead return to the prompt.
 If var(word) is omitted, then a standard message is printed.
 )
 item(tt(${)var(name)tt(:PLUS())var(word)tt(}))(
@@ -413,8 +416,8 @@ remove the non-matched elements).
 )
 xitem(tt(${)var(name)tt(/)var(pattern)tt(/)var(repl)tt(}))
 item(tt(${)var(name)tt(//)var(pattern)tt(/)var(repl)tt(}))(
-Replace by string var(repl), the longest possible match of
-var(pattern) in the expansion of parameter var(name).  The first form
+Replace the longest possible match of var(pattern) in the expansion of
+parameter var(name) by string var(repl).  The first form
 replaces just the first occurrence, the second form all occurrences.
 The var(pattern) may begin with a `tt(#)', in which case the
 var(pattern) must match at the start of the string, or `tt(%)', in
@@ -534,8 +537,8 @@ If this flag is repeated (as in tt(AA)), create an associative
 array parameter.  Assignment is made before sorting or padding.
 The var(name) part may be a subscripted range for ordinary
 arrays; the var(word) part em(must) be converted to an array, for
-example by using tt(${(AA)=)...tt(}) to activate word splitting,
-when creating an associative array.
+example by using tt(${(AA)=)var(name)tt(=)...tt(}) to activate word
+splitting, when creating an associative array.
 )
 item(tt(@))(
 In double quotes, array elements are put into separate words.
@@ -548,13 +551,12 @@ em(arithmetic expansion) on the result. Such expansions can be
 nested but too deep recursion may have unpredictable effects.
 )
 item(tt(P))(
-This makes the value of the parameter var(name) be taken as a
-parameter name on which to work. If it is used with a tt(${)...tt(})
-type parameter expression or a tt($LPAR())...tt(RPAR()) type command
-substitution in place of the parameter name this flag makes the result
-of the expansion be taken as a parameter name which is then
-used. E.g. if you have `tt(foo=bar)' and `tt(bar=baz)', the strings
-tt(${(P)foo}) and tt(${(P)${foo}}) will be expanded to `tt(baz)'.
+This forces the value of the parameter var(name) to be interpreted as a
+further parameter name, whose value will be used where appropriate. If used
+with a nested parameter or command substitution, the result of that will be
+taken as a parameter name in the same way.  For example, if you have
+`tt(foo=bar)' and `tt(bar=baz)', the strings tt(${(P)foo}),
+tt(${(P)${foo}}), and tt${(P)$(echo bar)} will be expanded to `tt(baz)'.
 )
 item(tt(o))(
 Sort the resulting words in ascending order.
@@ -637,41 +639,44 @@ Split the result of the expansion to lines. This is a shorthand
 for `tt(ps:\n:)'.
 )
 item(tt(t))(
-Don't work on the value of the parameter, but on a string describing
-the type of the parameter. This string consists of keywords separated
-by hyphens (`tt(-)'). The first keyword in the string describes the
-main type, it can be one of `tt(scalar)', `tt(array)', `tt(integer)',
+Use a string describing the type of the parameter where the value
+of the parameter would usually appear. This string consists of keywords
+separated by hyphens (`tt(-)'). The first keyword in the string describes
+the main type, it can be one of `tt(scalar)', `tt(array)', `tt(integer)',
 or `tt(association)'. The other keywords describe the type in more
 detail:
 
 startitem()
-item(`tt(left)')(
+item(tt(local))(
+for local parameters
+)
+item(tt(left))(
 for left justified parameters
 )
-item(`tt(right_blanks)')(
+item(tt(right_blanks))(
 for right justified parameters with leading blanks
 )
-item(`tt(right_zeros)')(
+item(tt(right_zeros))(
 for right justified parameters with leading zeros
 )
-item(`tt(lower)')(
+item(tt(lower))(
 for parameters whose value is converted to all lower case when it is
 expanded
 )
-item(`tt(upper)')(
+item(tt(upper))(
 for parameters whose value is converted to all upper case when it is
 expanded
 )
-item(`tt(readonly)')(
+item(tt(readonly))(
 for readonly parameters
 )
-item(`tt(tag)')(
+item(tt(tag))(
 for tagged parameters
 )
-item(`tt(export)')(
+item(tt(export))(
 for exported parameters
 )
-item(`tt(unique)')(
+item(tt(unique))(
 for arrays which keep only the first occurrence of duplicated values
 )
 enditem()
@@ -809,7 +814,7 @@ enditem()
 
 subsect(Examples)
 The flag tt(f) is useful to split a double-quoted substitution line by
-line.  For example, tt("${(f)$LPAR()<)var(file)tt(RPAR()}")
+line.  For example, tt(${(f)"$LPAR()<)var(file)tt(RPAR()"})
 substitutes the contents of var(file) divided so that each line is
 an element of the resulting array.  Compare this with the effect of
 tt($)tt(LPAR()<)var(file)tt(RPAR()) alone, which divides the file
@@ -1077,8 +1082,8 @@ Match anything that matches the pattern var(x) but does not match var(y).
 This has lower precedence than any operator except `tt(|)', so
 `tt(*/*~foo/bar)' will search for all files in all directories in `tt(.)'
 and then exclude `tt(foo/bar)' if there was such a match.
-It groups left-to-right, so multiple patterns can be excluded by
-`var(foo)tt(~)var(bar)tt(~)var(baz)'.
+Multiple patterns can be excluded by
+`var(foo)tt(~LPAR())var(bar)tt(|)var(baz)tt(RPAR())'.
 In the exclusion pattern (var(y)), `tt(/)' and `tt(.)' are not treated
 specially the way they usually are in globbing.
 )
@@ -1124,8 +1129,8 @@ subsect(Globbing Flags)
 There are various flags which affect any text to their right up to the
 end of the enclosing group or to the end of the pattern; they require
 the tt(EXTENDED_GLOB) option. All take the form
-tt(LPAR()#)var(X)tt(RPAR()) where var(X) may be one of the following
-characters:
+tt(LPAR()#)var(X)tt(RPAR()) where var(X) may have one of the following
+forms:
 
 startitem()
 item(i)(
@@ -1194,7 +1199,7 @@ in character ranges: hence tt(LPAR()#a1)tt(RPAR()???)  matches strings of
 length four, by applying rule 4 to an empty part of the pattern, but not
 strings of length two, since all the tt(?) must match.  Other characters
 which must match exactly are initial dots in filenames (unless the
-tt(GLOB_DOTS) option is set), and all slashes in file names, so that
+tt(GLOB_DOTS) option is set), and all slashes in filenames, so that
 tt(a/bc) is two errors from tt(ab/c) (the slash cannot be transposed with
 another character).  Similarly, errors are counted separately for
 non-contiguous strings in the pattern, so that tt(LPAR()ab|cd)tt(RPAR()ef)
@@ -1353,7 +1358,7 @@ Thus, `tt(*(f70?))' gives the files for which the owner has read,
 write, and execute permission, and for which other group members have
 no rights, independent of the permissions for other users. The pattern
 `tt(*(f-100))' gives all files for which the owner does not have
-execute permission, and `tt(*(f:gu+w,o-rx))' gives the files for which 
+execute permission, and `tt(*(f:gu+w,o-rx:))' gives the files for which 
 the owner and the other members of the group have at least write
 permission, and for which other users don't have read or execute
 permission.
@@ -1421,7 +1426,7 @@ sets the tt(MARK_DIRS) option for the current pattern
 pindex(MARK_DIRS, setting in pattern)
 )
 item(tt(T))(
-appends a trailing qualifier mark to the file names, analogous to the
+appends a trailing qualifier mark to the filenames, analogous to the
 tt(LIST_TYPES) option, for the current pattern (overrides tt(M))
 )
 item(tt(N))(
@@ -1434,16 +1439,15 @@ pindex(GLOB_DOTS, setting in pattern)
 )
 item(tt(o)var(c))(
 specifies how the names of the files should be sorted. If var(c) is
-tt(n) they are sorted by name (the default), if var(c) is tt(L) they
-are sorted depending on the size (length) of the files, tt(l) makes
-them be sorted by the number of links, and tt(a), tt(m), and tt(c)
-make them be sorted by the time of the last access, modification, and
+tt(n) they are sorted by name (the default), if it is tt(L) they
+are sorted depending on the size (length) of the files, if tt(l) 
+they are sorted by the number of links, and if tt(a), tt(m), and tt(c)
+they are sorted by the time of the last access, modification, or
 inode change respectively. Note that tt(a), tt(m), and tt(c) compare
-the age to the current time, so the first name in the list is the 
-one of the youngest file. Also note that the modifiers tt(^) and tt(-) are 
+the age against the current time, hence the first name in the list is the 
+the youngest file. Also note that the modifiers tt(^) and tt(-) are 
 used, so `tt(*(^-oL))' gives a list of all files sorted by file size in 
-descending order working not on symbolic links but on the files they
-point to.
+descending order, following any symbolic links.
 )
 item(tt(O)var(c))(
 like `tt(o)', but sorts in descending order; i.e. `tt(*(^oc))' is the
diff --git a/Doc/Zsh/files.yo b/Doc/Zsh/files.yo
index 54fa800dc..df2ae8d35 100644
--- a/Doc/Zsh/files.yo
+++ b/Doc/Zsh/files.yo
@@ -11,9 +11,10 @@ Commands are first read from tt(/etc/zshenv); this cannot be overridden.
 Subsequent behaviour is modified by the tt(RCS) and
 tt(GLOBAL_RCS) options; the former affects all startup files, while the
 second only affects those in the tt(/etc) directory.  If one of the options
-is unset at any point, the corresponding startup file(s) will not be read.
-It is also possible for a file in tt($ZDOTDIR) to re-enable
-tt(GLOBAL_RCS). Both tt(RCS) and tt(GLOBAL_RCS) are set by default.
+is unset at any point, any subsequent startup file(s) of the corresponding
+type will not be read.  It is also possible for a file in tt($ZDOTDIR) to
+re-enable tt(GLOBAL_RCS). Both tt(RCS) and tt(GLOBAL_RCS) are set by
+default.
 
 Commands are then read from tt($ZDOTDIR/.zshenv).
 pindex(LOGIN, use of)
@@ -37,5 +38,11 @@ saved.
 If tt(ZDOTDIR) is unset, tt(HOME) is used instead.
 Those files listed above as being in tt(/etc) may be in another
 directory, depending on the installation.
+
+As tt(/etc/zshenv) is run for all instances of zsh, it is important that
+it be kept as small as possible.  In particular, it is a good idea to
+put code that does not need to be run for every single shell behind
+a test of the form `tt(if [[ -o rcs ]]; then ...)' so that it will not
+be executed when zsh is invoked with the `tt(-f)' option.
 ifnzman(includefile(Zsh/filelist.yo))

 
diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index aa905b600..847381c8d 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -35,25 +35,45 @@ A function can be marked as em(undefined) using the tt(autoload) builtin
 (or `tt(functions -u)' or `tt(typeset -fu)').  Such a function has no
 body.  When the function is first executed, the tt(fpath)
 variable will be searched for a file with the same name as the
-function.
+function.  The usual alias expansion during reading will be suppressed if
+the tt(autoload) builtin or its equivalent is given the option tt(-U);
+this is recommended for the use of functions supplied with the zsh
+distribution.  Thus to define functions for autoloading, a typical sequence
+is:
+
+example(fpath=(~/myfuncs $fpath)
+autoload myfunc1 myfunc2 ...)
 
 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 initialization.
-It is executed in the context of the function
-execution, and may therefore define local parameters.
+executed.  It will normally define the function in question, but may
+also perform initialization:  this
+is executed in the context of the function
+execution, and may therefore define local parameters.  It is an error if
+the function is not defined by loading the file.
+
+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.  If processing of the file results in the function
+being re-defined, the function itself is not re-executed. To force the
+function to perform initialization and be called, the file should contain
+initialization code (which will be discarded) in addition to a complete
+function definition (which will be retained for subsequent calls to the
+function), and a call to the shell function at the end.
+
+For example, suppose the autoload file tt(func) contains
 
-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.
-Initialization code can be executed, but only as part of the first
-function execution, so the function would have to redefine itself to
-avoid reinitializing on the next execution.
+example(func() { print This is func; }
+print func is initialized
+)
+
+then `tt(func; func)' with tt(KSH_AUTOLOAD) set will produce both messages
+on the first call, and just the message `tt(This is func)' on the second
+and any subsequent calls.  Without tt(KSH_AUTOLOAD) set, it will produce
+the initialization message on the first call, and the other message on the
+second and subsequent calls.
 
-If this processing of the file results in the function being
-fully defined, the function itself is then executed.
 sect(Special Functions)
 The following functions, if defined, have special meaning to
 the shell:
@@ -106,3 +126,8 @@ item(tt(TRAPZERR))(
 Executed whenever a command has a non-zero exit status.
 )
 enditem()
+
+The functions beginning `tt(TRAP)' may alternatively be defined with the
+tt(trap) builtin:  this may be preferable for some uses, as they are then
+run in the environment of the calling process, rather than in their own
+function environment.
diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo
index 80c132ab7..5ae28dba1 100644
--- a/Doc/Zsh/grammar.yo
+++ b/Doc/Zsh/grammar.yo
@@ -25,6 +25,11 @@ If a command name is given, the parameter assignments modify
 the environment of the command when it is executed.
 The value of a simple command is its exit status,
 or 128 plus the signal number if terminated by a signal.
+For example,
+
+example(echo foo)
+
+is a simple command with arguments.
 
 cindex(pipeline)
 A em(pipeline) is either a simple command, or a sequence of two or more
@@ -37,6 +42,12 @@ command to the standard input of the next.  The value of a pipeline
 is the value of the last command, unless the pipeline is preceded by
 `tt(!)' in which case the value is the logical inverse of the value of the
 last command.
+For example,
+
+example(echo foo | sed 's/foo/bar/')
+
+is a pipeline, where the output (`tt(foo)' plus a newline) of the first
+command will be passed to the input of the second.
 
 findex(coproc)
 cindex(coprocess)
@@ -45,6 +56,8 @@ a two-way pipe is established between it and the parent shell.  The
 shell can read from or write to the coprocess by means of the `tt(>&p)'
 and `tt(<&p)' redirection operators or with `tt(print -p)' and `tt(read -p)'.
 A pipeline cannot be preceded by both `tt(coproc)' and `tt(!)'.
+If job control is active, the coprocess can be treated in other than input
+and output as an ordinary background job.
 
 cindex(sublist)
 A em(sublist) is either a single pipeline, or a sequence of two or more
@@ -54,6 +67,14 @@ by `tt(&&)', the second pipeline is executed only if the first succeeds
 second is executed only if the first fails (returns a nonzero value).
 Both operators have equal precedence and are left associative.
 The value of the sublist is the value of the last pipeline executed.
+For example,
+
+example(dmesg | grep panic && print yes)
+
+is a sublist consisting of two piplines, the second just a simple command
+which will be executed if and only if the tt(grep) command returns a zero
+value.  If it does not, the value of the sublist is that return value, else
+it is the value returned by the tt(print) (almost certainly zero).
 
 cindex(list)
 A em(list) is a sequence of zero or more sublists, in which each sublist
@@ -65,9 +86,15 @@ or `tt({)...tt(})'.  When a
 sublist is terminated by `tt(;)' or newline, the shell waits for it to
 finish before executing the next sublist.  If a sublist is terminated
 by a `tt(&)', `tt(&|)', or `tt(&!)',
-the shell executes it in the background, and
-does not wait for it to finish.
-A backgrounded sublist returns a status of zero.
+the shell executes the last pipeline in it in the background, and
+does not wait for it to finish (note the difference from other shells
+which execute the whole sublist in the background).
+A backgrounded pipeline returns a status of zero.
+
+More generally, a list can be seen as a set of any shell commands
+whatsoever, including the complex commands below; this is implied wherever
+the word `list' appears in later descriptions.  For example, the commands
+in a shell function form a special sort of list.
 texinode(Precommand Modifiers)(Complex Commands)(Simple Commands & Pipelines)(Shell Grammar)
 sect(Precommand Modifiers)
 cindex(precommand modifiers)
@@ -87,7 +114,9 @@ Filename generation (globbing) is not performed on any of
 the words.
 )
 item(tt(nocorrect))(
-Spelling correction is not done on any of the words.
+Spelling correction is not done on any of the words.  This must appear
+before any other precommand modifier, as it is interpreted immediately,
+before any parsing is done.  It has no effect in non-interactive shells.
 )
 item(tt(exec))(
 The command is executed in the parent shell without forking.
@@ -173,7 +202,7 @@ findex(select)
 cindex(user selection)
 cindex(selection, user)
 item(tt(select) var(name) [ tt(in) var(word) ... var(term) ] tt(do) var(list) tt(done))(
-where var(term) is one ore more newline or tt(;).
+where var(term) is one or more newline or tt(;) to terminate the var(word)s.
 Print the set of var(word)s, each preceded by a number.
 If the tt(in) var(word) is omitted, use the positional parameters.
 The tt(PROMPT3) prompt is printed and a line is read from standard
@@ -333,7 +362,13 @@ string by using the `tt(\')' escape.
 
 All characters enclosed between a pair of single quotes (tt('')) that
 is not preceded by a `tt($)' are quoted.  A single quote cannot appear
-within single quotes.
+within single quotes unless the option tt(RC_QUOTES) is set, in which case
+a pair of single quotes are turned into a single quote.  For example,
+
+example(print '''')
+
+outputs nothing apart from a newline if tt(RC_QUOTES) is not set, but one
+single quote if it is set.
 
 Inside double quotes (tt("")), parameter and
 command substitution occurs, and `tt(\)' quotes the characters
diff --git a/Doc/Zsh/invoke.yo b/Doc/Zsh/invoke.yo
index 40a5513d0..7add05b38 100644
--- a/Doc/Zsh/invoke.yo
+++ b/Doc/Zsh/invoke.yo
@@ -21,3 +21,14 @@ item(tt(-s))(
 Read command from the standard input.
 )
 enditem()
+
+For further options, which are common to invocation and the tt(set)
+builtin, see
+ifzman(zmanref(zshoptions))\
+ifnzman(noderef(Options))\
+.  Flags may be specified by name using the tt(-o) option.  For example,
+
+example(zsh -x -o shwordsplit scr)
+
+runs the script tt(scr), setting the tt(XTRACE) option by the corresponding
+letter `tt(-x)' and the tt(SH_WORD_SPLIT) option by name.
diff --git a/Doc/Zsh/jobs.yo b/Doc/Zsh/jobs.yo
index 62e945f23..2a5ee69d8 100644
--- a/Doc/Zsh/jobs.yo
+++ b/Doc/Zsh/jobs.yo
@@ -20,7 +20,8 @@ does not have a place in the job table, and is not subject
 to the job control features described here.
 
 If you are running a job and wish to do something else you may hit the key
-^Z (control-Z) which sends a tt(TSTP) signal to the current job.
+^Z (control-Z) which sends a tt(TSTP) signal to the current job:  this key
+may be redefined by the tt(susp) option of the external tt(stty) command.
 cindex(jobs, suspending)
 cindex(suspending jobs)
 The shell will then normally indicate that the job has been `suspended',
diff --git a/Doc/Zsh/metafaq.yo b/Doc/Zsh/metafaq.yo
index c8273da47..c27f4f152 100644
--- a/Doc/Zsh/metafaq.yo
+++ b/Doc/Zsh/metafaq.yo
@@ -80,7 +80,6 @@ tt(ftp://sunsite.org.uk/packages/zsh/))
 item(USA)(
 nofill(tt(ftp://ftp.math.gatech.edu/pub/zsh/)
 tt(ftp://uiarchive.uiuc.edu/pub/packages/shells/zsh/)
-tt(ftp://ftp.sterling.com/zsh/)  em((G))  em((H))
 tt(ftp://ftp.rge.com/pub/shells/zsh/)
 tt(ftp://foad.org/pub/zsh/)
 tt(http://foad.org/zsh/))
diff --git a/Doc/Zsh/mod_complist.yo b/Doc/Zsh/mod_complist.yo
index b37252582..23f8bee2e 100644
--- a/Doc/Zsh/mod_complist.yo
+++ b/Doc/Zsh/mod_complist.yo
@@ -1,6 +1,7 @@
 texinode(The complist Module)(The deltochar Module)(The compctl Module)(Zsh Modules)
 sect(The complist Module)
 cindex(completion, listing)
+cindex(completion, coloured listings)
 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.
@@ -12,6 +13,8 @@ not automatically be loaded if it is not linked in:  on systems with
 dynamic loading, `tt(zmodload complist)' is required.
 
 subsect(Parameters)
+vindex(ZLS_COLORS)
+vindex(ZLS_COLOURS)
 The parameters tt(ZLS_COLORS) and tt(ZLS_COLOURS) describe how matches
 are highlighted. To turn on highlighting an empty value suffices, in
 which case all the default values given below will be used. The format of the
@@ -78,6 +81,9 @@ vt100 compatible terminals such as tt(xterm)s. On monochrome terminals
 the default values will have no visual effect.
 
 subsect(Menu selection)
+cindex(completion, selecting by cursor)
+vindex(SELECTMIN)
+tindex(menu-select)
 The tt(complist) module also offers an alternative style of selecting
 matches from a list, called menu-selection, which can be used if the
 shell is set up to return to the last prompt after showing a
diff --git a/Doc/Zsh/mod_stat.yo b/Doc/Zsh/mod_stat.yo
index a8551d8e9..d0c7acfe1 100644
--- a/Doc/Zsh/mod_stat.yo
+++ b/Doc/Zsh/mod_stat.yo
@@ -85,10 +85,10 @@ item(tt(-A) var(array))(
 Instead of displaying the results on standard
 output, assign them to an var(array), one tt(struct stat) element per array
 element for each file in order.  In this case neither the name
-of the element nor the name of the files is provided unless the
-tt(-t) or tt(-n) options are provided, respectively.  In the
-former case the element name appears as a prefix to the
-appropriate array element and in the latter case the file name
+of the element nor the name of the files appears in var(array) unless the
+tt(-t) or tt(-n) options were given, respectively.  If tt(-t) is given,
+the element name appears as a prefix to the
+appropriate array element; if tt(-n) is given, the file name
 appears as a separate array element preceding all the others.
 Other formatting options are respected.
 )
diff --git a/Doc/Zsh/mod_zftp.yo b/Doc/Zsh/mod_zftp.yo
index 7b64882b4..f5d165083 100644
--- a/Doc/Zsh/mod_zftp.yo
+++ b/Doc/Zsh/mod_zftp.yo
@@ -240,6 +240,7 @@ The following shell parameters are used by tt(zftp).  Currently none
 of them are special.
 
 startitem()
+vindex(ZFTP_TMOUT)
 item(tt(ZFTP_TMOUT))(
 Integer.  The time in seconds to wait for a network operation to
 complete before returning an error.  If this is not set when the
@@ -374,14 +375,14 @@ subsect(Functions)
 cindex(zftp, functions)
 
 startitem()
-findex(zftp_chpwd)
+findex(zftp_chpwd, specification)
 item(tt(zftp_chpwd))(
 If this function is set by the user, it is called every time the
 directory changes on the server, including when a user is logged
 in, or when a connection is closed.  In the last case, tt($ZFTP_PWD)
 will be unset; otherwise it will reflect the new directory.
 )
-findex(zftp_progress)
+findex(zftp_progress, specification)
 item(tt(zftp_progress))(
 If this function is set by the user, it will be called during
 a tt(get), tt(put) or tt(append) operation each time sufficient data
diff --git a/Doc/Zsh/mod_zle.yo b/Doc/Zsh/mod_zle.yo
index 7d438a5d4..95aa27535 100644
--- a/Doc/Zsh/mod_zle.yo
+++ b/Doc/Zsh/mod_zle.yo
@@ -41,11 +41,9 @@ and does not otherwise count as an argument.
 )
 enditem()
 
-Some operations do not permit a keymap to be selected.
 If a keymap selection is required and none of the options above are used, the
-`tt(main)' keymap is used.  These operations do not permit a keymap to be
-selected:
-
+`tt(main)' keymap is used.  Some operations do not permit a keymap to be
+selected, namely:
 startitem()
 item(tt(-l))(
 List all existing keymap names.  If the tt(-L)
@@ -137,7 +135,10 @@ sitem(tt(^)var(X))(control character)
 endsitem()
 
 In all other cases, `tt(\)' escapes the following character.  Delete is
-written as `tt(^?)'.  Note that `tt(\M^?)' and `tt(^\M?)' are not the same.
+written as `tt(^?)'.  Note that `tt(\M^?)' and `tt(^\M?)' are not the same,
+and that (unlike emacs), the bindings `tt(\M-)var(X)' and `tt(\e)var(X)'
+are entirely distinct, although they are initialized to the same bindings
+by `tt(bindkey -m)'.
 )
 findex(vared)
 cindex(parameters, editing)
@@ -218,8 +219,9 @@ ifzman(zmanref(zshzle))\
 ifnzman(noderef(Zsh Line Editor))\
 .
 )
+citem(completion widgets, creating)
 item(tt(-C) var(widget) var(completion-widget) var(function))(
-Create a user-defined completion widget names var(widget). The 
+Create a user-defined completion widget named 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.
@@ -254,7 +256,7 @@ 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
+function, these are passed down as positional 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
diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo
index bfd7bc201..c5be29064 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -40,9 +40,18 @@ 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)
+In the following list, options set by default in all emulations are marked
+<D>; those set by default only in csh, ksh, sh, or zsh emulations are marked
+<C>, <K>, <S>, <Z> as appropriate.  When listing options (by `tt(setopt)',
+`tt(unsetopt)', `tt(set -o)' or `tt(set +o)'), those turned on by default
+appear in the list prefixed with `tt(no)'.  Hence (unless
+tt(KSH_OPTION_PRINT) is set), `tt(setopt)' shows all options whose settings
+are changed from the default.
+
 startitem()
 pindex(ALL_EXPORT)
 cindex(export, automatic)
@@ -50,7 +59,7 @@ item(tt(ALL_EXPORT) (tt(-a), ksh: tt(-a)))(
 All parameters subsequently defined are automatically exported.
 )
 pindex(ALWAYS_LAST_PROMPT)
-item(tt(ALWAYS_LAST_PROMPT))(
+item(tt(ALWAYS_LAST_PROMPT) <D>)(
 If unset, key functions that list completions try to return to the last
 prompt if given a numeric argument. If set these functions try to
 return to the last prompt if given em(no) numeric argument.
@@ -64,7 +73,7 @@ a single match is inserted or menu completion is performed.
 )
 pindex(APPEND_HISTORY)
 cindex(history, appending to a file)
-item(tt(APPEND_HISTORY))(
+item(tt(APPEND_HISTORY) <D>)(
 If this is set, zsh sessions will append their history list to
 the history file, rather than overwrite it. Thus, multiple parallel
 zsh sessions will all have their history lists added to the
@@ -79,12 +88,12 @@ command to that directory.
 )
 pindex(AUTO_LIST)
 cindex(completion, listing choices)
-item(tt(AUTO_LIST) (tt(-9)))(
+item(tt(AUTO_LIST) (tt(-9)) <D>)(
 Automatically list choices on an ambiguous completion.
 )
 pindex(AUTO_MENU)
 cindex(completion, menu)
-item(tt(AUTO_MENU))(
+item(tt(AUTO_MENU) <D>)(
 Automatically use menu completion after the second consecutive request for
 completion, for example by pressing the tab key repeatedly. This option
 is overridden by tt(MENU_COMPLETE).
@@ -100,7 +109,7 @@ is performed on a word starting with `tt(~)'.
 (Otherwise, the parameter must be used in the form `tt(~)var(param)' first.)
 )
 pindex(AUTO_PARAM_KEYS)
-item(tt(AUTO_PARAM_KEYS))(
+item(tt(AUTO_PARAM_KEYS) <D>)(
 If a parameter name was completed and a following character
 (normally a space) automatically
 inserted, and the next character typed is one
@@ -111,7 +120,7 @@ Completion in a brace expansion is affected similarly: the added character
 is a `tt(,)', which will be removed if `tt(})' is typed next.
 )
 pindex(AUTO_PARAM_SLASH)
-item(tt(AUTO_PARAM_SLASH))(
+item(tt(AUTO_PARAM_SLASH) <D>)(
 If a parameter is completed whose content is the name of a directory,
 then add a trailing slash instead of a space.
 )
@@ -123,7 +132,7 @@ Make tt(cd) push the old directory onto the directory stack.
 )
 pindex(AUTO_REMOVE_SLASH)
 cindex(slash, removing trailing)
-item(tt(AUTO_REMOVE_SLASH))(
+item(tt(AUTO_REMOVE_SLASH) <D>)(
 When the last character resulting from a completion is a slash and the next
 character typed is a word delimiter, a slash, or a character that ends 
 a command (such as a semicolon or an ampersand), remove the slash.
@@ -138,21 +147,21 @@ as candidates for resumption of an existing job.
 pindex(BAD_PATTERN)
 cindex(globbing, bad pattern)
 cindex(filename generation, bad pattern)
-item(tt(BAD_PATTERN) (tt(PLUS()2)))(
+item(tt(BAD_PATTERN) (tt(PLUS()2)) <C> <Z>)(
 If a pattern for filename generation is badly formed, print an error message.
 (If this option is unset, the pattern will be left unchanged.)
 )
 pindex(BANG_HIST)
 cindex(history, enable substitution)
 cindex(enable history substitution)
-item(tt(BANG_HIST) (tt(PLUS()K)))(
+item(tt(BANG_HIST) (tt(PLUS()K)) <C> <Z>)(
 Perform textual history expansion, bf(csh)-style,
 treating the character `tt(!)' specially.
 )
 pindex(BARE_GLOB_QUAL)
 cindex(globbing qualifiers, enable)
 cindex(enable globbing qualifiers)
-item(tt(BARE_GLOB_QUAL))(
+item(tt(BARE_GLOB_QUAL) <Z>)(
 In a glob pattern, treat a trailing set of parentheses as a qualifier
 list, if it contains no `tt(|)', `tt(LPAR())' or (if special) `tt(~)'
 characters.  See noderef(Filename Generation).
@@ -171,14 +180,14 @@ through the list in that case.
 pindex(BEEP)
 cindex(beep, enabling)
 cindex(enabling the beep)
-item(tt(BEEP) (tt(PLUS()B)))(
+item(tt(BEEP) (tt(PLUS()B)) <D>)(
 Beep on error in ZLE.
 )
 pindex(BG_NICE)
 cindex(jobs, background priority)
 cindex(background jobs, priority of)
 cindex(priority of background jobs)
-item(tt(BG_NICE) (tt(-6)))(
+item(tt(BG_NICE) (tt(-6)) <C> <Z>)(
 Run all background jobs at a lower priority.  This option
 is set by default.
 )
@@ -192,7 +201,7 @@ noderef(Brace Expansion).
 )
 pindex(BSD_ECHO)
 cindex(echo, BSD compatible)
-item(tt(BSD_ECHO))(
+item(tt(BSD_ECHO) <S>)(
 Make the tt(echo) builtin compatible with the BSD manref(echo)(1) command.
 This disables backslashed escape sequences in echo strings unless the
 tt(-e) option is specified.
@@ -233,7 +242,7 @@ path segment is a symbolic link.
 pindex(CLOBBER)
 cindex(clobbering, of files)
 cindex(file clobbering, allowing)
-item(tt(CLOBBER) (tt(PLUS()C), ksh: tt(PLUS()C)))(
+item(tt(CLOBBER) (tt(PLUS()C), ksh: tt(PLUS()C)) <D>)(
 Allows `tt(>)' redirection to truncate existing files,
 and `tt(>>)' to create files.
 Otherwise `tt(>!)' or `tt(>|)' must be used to truncate a file,
@@ -264,7 +273,7 @@ Try to correct the spelling of all arguments in a line.
 pindex(CSH_JUNKIE_HISTORY)
 cindex(csh, history style)
 cindex(history style, csh)
-item(tt(CSH_JUNKIE_HISTORY))(
+item(tt(CSH_JUNKIE_HISTORY) <C>)(
 A history reference without an event specifier will always refer to the
 previous command.  Without this option, such a history reference refers
 to the same event as the previous history reference, defaulting to the
@@ -273,14 +282,14 @@ previous command.
 pindex(CSH_JUNKIE_LOOPS)
 cindex(csh, loop style)
 cindex(loop style, csh)
-item(tt(CSH_JUNKIE_LOOPS))(
+item(tt(CSH_JUNKIE_LOOPS) <C>)(
 Allow loop bodies to take the form `var(list); tt(end)' instead of
 `tt(do) var(list); tt(done)'.
 )
 pindex(CSH_JUNKIE_QUOTES)
 cindex(csh, quoting style)
 cindex(quoting style, csh)
-item(tt(CSH_JUNKIE_QUOTES))(
+item(tt(CSH_JUNKIE_QUOTES) <C>)(
 Changes the rules for single- and double-quoted text to match that of
 bf(csh).  These require that embedded newlines be preceded by a backslash;
 unescaped newlines will cause an error message.
@@ -292,7 +301,7 @@ pindex(CSH_NULL_GLOB)
 cindex(csh, null globbing style)
 cindex(null globbing style, csh)
 cindex(globbing, null, style, csh)
-item(tt(CSH_NULL_GLOB))(
+item(tt(CSH_NULL_GLOB) <C>)(
 If a pattern for filename generation has no matches,
 delete the pattern from the argument list;
 do not report an error unless all the patterns
@@ -301,7 +310,7 @@ Overrides tt(NULL_GLOB).
 )
 pindex(EQUALS)
 cindex(filename expansion, =)
-item(tt(EQUALS))(
+item(tt(EQUALS) <Z>)(
 Perform tt(=) filename expansion.
 (See noderef(Filename Expansion).)
 )
@@ -314,7 +323,7 @@ scripts.
 )
 pindex(EXEC)
 cindex(command execution, enabling)
-item(tt(EXEC) (tt(PLUS()n), ksh: tt(PLUS()n)))(
+item(tt(EXEC) (tt(PLUS()n), ksh: tt(PLUS()n)) <D>)(
 Do execute commands.  Without this option, commands are
 read and checked for syntax errors, but not executed.
 )
@@ -327,7 +336,7 @@ always produces named directory expansion.)
 )
 pindex(EXTENDED_HISTORY)
 cindex(history, timestamping)
-item(tt(EXTENDED_HISTORY))(
+item(tt(EXTENDED_HISTORY) <C>)(
 Save each command's beginning timestamp (in seconds since the epoch)
 and the duration (in seconds) to the history file.  The format of
 this prefixed data is:
@@ -336,35 +345,35 @@ this prefixed data is:
 )
 pindex(FLOW_CONTROL)
 cindex(flow control)
-item(tt(FLOW_CONTROL))(
+item(tt(FLOW_CONTROL) <D>)(
 If this option is unset,
 output flow control via start/stop characters (usually assigned to
 ^S/^Q) is disabled in the shell's editor.
 )
 pindex(FUNCTION_ARGZERO)
 cindex($0, setting)
-item(tt(FUNCTION_ARGZERO))(
+item(tt(FUNCTION_ARGZERO) <C> <Z>)(
 When executing a shell function or sourcing a script, set tt($0)
 temporarily to the name of the function/script.
 )
 pindex(GLOB)
 cindex(globbing, enabling)
 cindex(enabling globbing)
-item(tt(GLOB) (tt(PLUS()F), ksh: tt(PLUS()f)))(
+item(tt(GLOB) (tt(PLUS()F), ksh: tt(PLUS()f)) <D>)(
 Perform filename generation (globbing).
 (See noderef(Filename Generation).)
 )
 pindex(GLOBAL_RCS)
 cindex(startup files, global, inhibiting)
 cindex(files, global startup, inhibiting)
-item(tt(GLOBAL_RCS) (tt(-d)))(
+item(tt(GLOBAL_RCS) (tt(-d)) <D>)(
 If this option is unset, the startup files tt(/etc/zprofile),
 tt(/etc/zshrc), tt(/etc/zlogin) and tt(/etc/zlogout) will not be run.  It
 can be disabled and re-enabled at any time, including inside local startup
 files (tt(.zshrc), etc.).
 )
 pindex(GLOB_ASSIGN)
-item(tt(GLOB_ASSIGN))(
+item(tt(GLOB_ASSIGN) <C>)(
 If this option is set, filename generation (globbing) is
 performed on the right hand side of scalar parameter assignments of
 the form `var(name)tt(=)var(pattern) (e.g. `tt(foo=*)').
@@ -392,7 +401,7 @@ item(tt(GLOB_DOTS) (tt(-4)))(
 Do not require a leading `tt(.)' in a filename to be matched explicitly.
 )
 pindex(GLOB_SUBST)
-item(tt(GLOB_SUBST))(
+item(tt(GLOB_SUBST) <C> <K> <S>)(
 Treat any characters resulting from parameter expansion as being
 eligible for file expansion and filename generation, and any
 characters resulting from command substitution as being eligible for
@@ -401,7 +410,7 @@ filename generation.
 pindex(HASH_CMDS)
 cindex(hashing, of commands)
 cindex(command hashing)
-item(tt(HASH_CMDS))(
+item(tt(HASH_CMDS) <D>)(
 Note the location of each command the first time it is executed.
 Subsequent invocations of the same command will use the
 saved location, avoiding a path search.
@@ -410,13 +419,13 @@ If this option is unset, no path hashing will be done at all.
 pindex(HASH_DIRS)
 cindex(hashing, of directories)
 cindex(directories, hashing)
-item(tt(HASH_DIRS))(
+item(tt(HASH_DIRS) <D>)(
 Whenever a command is executed, hash the directory containing it,
 as well as all directories that occur earlier in the path.
 Has no effect if tt(HASH_CMDS) is unset.
 )
 pindex(HASH_LIST_ALL)
-item(tt(HASH_LIST_ALL))(
+item(tt(HASH_LIST_ALL) <D>)(
 Whenever a command completion is attempted, make sure the entire
 command path is hashed first.  This makes the first completion slower.
 )
@@ -428,7 +437,7 @@ references to clobber files even when tt(CLOBBER) is unset.
 pindex(HIST_BEEP)
 cindex(history beeping)
 cindex(beep, history)
-item(tt(HIST_BEEP))(
+item(tt(HIST_BEEP) <D>)(
 Beep when an attempt is made to access a history entry which
 isn't there.
 )
@@ -490,7 +499,7 @@ history expansion and reload the line into the editing buffer.
 )
 pindex(HUP)
 cindex(jobs, HUP)
-item(tt(HUP))(
+item(tt(HUP) <Z>)(
 Send the tt(HUP) signal to running jobs when the
 shell exits.
 )
@@ -498,7 +507,7 @@ pindex(IGNORE_BRACES)
 cindex(disabling brace expansion)
 cindex(brace expansion, disabling)
 cindex(expansion, brace, disabling)
-item(tt(IGNORE_BRACES) (tt(-I)))(
+item(tt(IGNORE_BRACES) (tt(-I)) <S>)(
 Do not perform brace expansion.
 )
 pindex(IGNORE_EOF)
@@ -529,14 +538,14 @@ The value of this option cannot be changed anywhere other than the command line.
 )
 pindex(INTERACTIVE_COMMENTS)
 cindex(comments, in interactive shells)
-item(tt(INTERACTIVE_COMMENTS) (tt(-k)))(
+item(tt(INTERACTIVE_COMMENTS) (tt(-k)) <K> <S>)(
 Allow comments even in interactive shells.
 )
 pindex(KSH_ARRAYS)
 cindex(arrays, ksh style)
 cindex(array style, ksh)
 cindex(ksh, array style)
-item(tt(KSH_ARRAYS))(
+item(tt(KSH_ARRAYS) <K> <S>)(
 Emulate bf(ksh) array handling as closely as possible.  If this option
 is set, array elements are numbered from zero, an array parameter
 without subscript refers to the first element instead of the whole array,
@@ -544,7 +553,7 @@ and braces are required to delimit a subscript (`tt(${path[2]})' rather
 than just `tt($path[2])').
 )
 pindex(KSH_AUTOLOAD)
-item(tt(KSH_AUTOLOAD))(
+item(tt(KSH_AUTOLOAD) <K> <S>)(
 Emulate bf(ksh) function autoloading.  This means that when a function is
 autoloaded, the corresponding file is merely executed, and must define
 the function itself.  (By default, the function is defined to the contents
@@ -553,7 +562,7 @@ containing only a simple definition of the function - is always handled
 in the bf(ksh)-compatible manner.)
 )
 pindex(KSH_GLOB)
-item(tt(KSH_GLOB))(
+item(tt(KSH_GLOB) <K>)(
 In pattern matching, the interpretation of parentheses is affected by
 a preceding `tt(@)', `tt(*)', `tt(+)', `tt(?)' or `tt(!)'.
 See noderef(Filename Generation).
@@ -562,13 +571,15 @@ pindex(KSH_OPTION_PRINT)
 cindex(option printing, ksh style)
 cindex(option printing style, ksh)
 cindex(ksh, option printing style)
-item(tt(KSH_OPTION_PRINT))(
-Alters the way options settings are printed.
+item(tt(KSH_OPTION_PRINT) <K>)(
+Alters the way options settings are printed: instead of separate lists of
+set and unset options, all options are shown, marked `on' if
+they are in the non-default state, `off' otherwise.
 )
 pindex(LIST_AMBIGUOUS)
 cindex(ambiguous completion)
 cindex(completion, ambiguous)
-item(tt(LIST_AMBIGUOUS))(
+item(tt(LIST_AMBIGUOUS) <D>)(
 This option works when tt(AUTO_LIST) or tt(BASH_AUTO_LIST) is also
 set.  If there is an unambiguous prefix to insert on the command line,
 that is done without a completion list being displayed; in other
@@ -579,7 +590,7 @@ will be delayed to the third call of the function.
 pindex(LIST_BEEP)
 cindex(beep, ambiguous completion)
 cindex(completion, beep on ambiguous)
-item(tt(LIST_BEEP))(
+item(tt(LIST_BEEP) <D>)(
 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
@@ -588,12 +599,12 @@ be modified if completion is called from a user-defined widget.
 pindex(LIST_TYPES)
 cindex(marking file types)
 cindex(files, marking type of)
-item(tt(LIST_TYPES) (tt(-X)))(
+item(tt(LIST_TYPES) (tt(-X)) <D>)(
 When listing files that are possible completions, show the
 type of each file with a trailing identifying mark.
 )
 pindex(LOCAL_OPTIONS)
-item(tt(LOCAL_OPTIONS))(
+item(tt(LOCAL_OPTIONS) <K>)(
 If this option is set at the point of return from a shell function,
 all the options (including this one) which were in force upon entry to
 the function are restored.  Otherwise, only this option and the
@@ -605,7 +616,7 @@ with a formulation like `tt(emulate -L zsh)'; the tt(-L) activates
 tt(LOCAL_OPTIONS).
 )
 pindex(LOCAL_TRAPS)
-item(tt(LOCAL_TRAPS))(
+item(tt(LOCAL_TRAPS) <K>)(
 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
@@ -671,13 +682,13 @@ item(tt(MONITOR) (tt(-m), ksh: tt(-m)))(
 Allow job control.  Set by default in interactive shells.
 )
 pindex(MULTIOS)
-item(tt(MULTIOS))(
+item(tt(MULTIOS) <Z>)(
 Perform implicit bf(tee)s or bf(cat)s when multiple
 redirections are attempted (see noderef(Redirection)).
 )
 pindex(NOMATCH)
 cindex(globbing, no matches)
-item(tt(NOMATCH) (tt(PLUS()3)))(
+item(tt(NOMATCH) (tt(PLUS()3)) <C> <Z>)(
 If a pattern for filename generation has no matches,
 print an error, instead of
 leaving it unchanged in the argument list.
@@ -687,7 +698,7 @@ of an initial `tt(~)' or `tt(=)'.
 pindex(NOTIFY)
 cindex(background jobs, notification)
 cindex(notification of background jobs)
-item(tt(NOTIFY) (tt(-5), ksh: tt(-b)))(
+item(tt(NOTIFY) (tt(-5), ksh: tt(-b)) <Z>)(
 Report the status of background jobs immediately, rather than
 waiting until just before printing a prompt.
 )
@@ -723,7 +734,7 @@ This also applies to the tt(.) builtin,
 and to searches for modules performed by the tt(zmodload) builtin.
 )
 pindex(POSIX_BUILTINS)
-item(tt(POSIX_BUILTINS))(
+item(tt(POSIX_BUILTINS) <K> <S>)(
 When this option is set the tt(command) builtin can be used to execute
 shell builtin commands.  Parameter assignments specified before shell
 functions and special builtins are kept after the command completes unless
@@ -778,25 +789,26 @@ option.
 )
 pindex(PROMPT_BANG)
 cindex(prompt, ! expansion)
-item(tt(PROMPT_BANG))(
+item(tt(PROMPT_BANG) <K>)(
 If set, `tt(!)' is treated specially in prompt expansion.
 See noderef(Prompt Expansion).
 )
 pindex(PROMPT_CR)
 cindex(prompt, with CR)
-item(tt(PROMPT_CR) (tt(PLUS()V)))(
+item(tt(PROMPT_CR) (tt(PLUS()V)) <D>)(
 Print a carriage return just before printing
-a prompt in the line editor.
+a prompt in the line editor.  This is on by default as multi-line editing
+is only possible if the editor knows where the start of the line appears.
 )
 pindex(PROMPT_PERCENT)
 cindex(prompt, % expansion)
-item(tt(PROMPT_PERCENT))(
+item(tt(PROMPT_PERCENT) <C> <Z>)(
 If set, `tt(%)' is treated specially in prompt expansion.
 See noderef(Prompt Expansion).
 )
 pindex(PROMPT_SUBST)
 cindex(prompt, parameter expansion)
-item(tt(PROMPT_SUBST))(
+item(tt(PROMPT_SUBST) <K>)(
 If set, em(parameter expansion), em(command substitution) and
 em(arithmetic expansion) are performed in prompts.
 )
@@ -840,7 +852,7 @@ within singly quoted strings.
 )
 pindex(RCS)
 cindex(startup files, sourcing)
-item(tt(RCS) (tt(PLUS()f)))(
+item(tt(RCS) (tt(PLUS()f)) <D>)(
 After tt(/etc/zshenv) is sourced on startup, source the
 tt(.zshenv), tt(/etc/zprofile), tt(.zprofile),
 tt(/etc/zshrc), tt(.zshrc), tt(/etc/zlogin), tt(.zlogin), and tt(.zlogout)
@@ -867,7 +879,7 @@ noderef(Restricted Shell).
 pindex(RM_STAR_SILENT)
 cindex(rm *, querying before)
 cindex(querying before rm *)
-item(tt(RM_STAR_SILENT) (tt(-H)))(
+item(tt(RM_STAR_SILENT) (tt(-H)) <K> <S>)(
 Do not query the user before executing `tt(rm *)' or `tt(rm path/*)'.
 )
 pindex(RM_STAR_WAIT)
@@ -883,7 +895,7 @@ avoided by expanding the `tt(*)' in ZLE (with tab).
 pindex(SHARE_HISTORY)
 cindex(share history)
 cindex(history, sharing)
-item(tt(SHARE_HISTORY))(
+item(tt(SHARE_HISTORY) <K>)(
 
 This option both imports new commands from the history file, and also
 causes your typed commands to be appended to the history file (the
@@ -906,7 +918,7 @@ commands whenever you need them using `tt(fc -RI)'.
 pindex(SH_FILE_EXPANSION)
 cindex(sh, expansion style)
 cindex(expansion style, sh)
-item(tt(SH_FILE_EXPANSION))(
+item(tt(SH_FILE_EXPANSION) <K> <S>)(
 Perform filename expansion (e.g., ~ expansion) em(before)
 parameter expansion, command substitution, arithmetic expansion
 and brace expansion.
@@ -917,7 +929,7 @@ brace expansion, so things like `tt(~$USERNAME)' and
 pindex(SH_GLOB)
 cindex(sh, globbing style)
 cindex(globbing style, sh)
-item(tt(SH_GLOB))(
+item(tt(SH_GLOB) <K> <S>)(
 Disables the special meaning of `tt(LPAR())', `tt(|)', `tt(RPAR())'
 and 'tt(<)' for globbing the result of parameter and command substitutions,
 and in some other places where
@@ -944,20 +956,20 @@ cindex(sh, single letter options style)
 cindex(ksh, single letter options style)
 cindex(single letter options, ksh style)
 cindex(options, single letter, ksh style)
-item(tt(SH_OPTION_LETTERS))(
+item(tt(SH_OPTION_LETTERS) <K> <S>)(
 If this option is set the shell tries to interpret single letter options
 (which are used with tt(set) and tt(setopt)) like bf(ksh) does.
 This also affects the value of the tt(-) special parameter.
 )
 pindex(SHORT_LOOPS)
-item(tt(SHORT_LOOPS))(
+item(tt(SHORT_LOOPS) <D>)(
 Allow the short forms of tt(for), tt(select),
 tt(if), and tt(function) constructs.
 )
 pindex(SH_WORD_SPLIT)
 cindex(field splitting, sh style)
 cindex(sh, field splitting style)
-item(tt(SH_WORD_SPLIT) (tt(-y)))(
+item(tt(SH_WORD_SPLIT) (tt(-y)) <K> <S>)(
 Causes field splitting to be performed on unquoted parameter expansions.
 Note that this option has nothing to do with word splitting.
 (See noderef(Parameter Expansion).)
@@ -973,7 +985,7 @@ The value of this option cannot be changed anywhere other than the command line.
 )
 pindex(SINGLE_LINE_ZLE)
 cindex(editor, single line mode)
-item(tt(SINGLE_LINE_ZLE) (tt(-M)))(
+item(tt(SINGLE_LINE_ZLE) (tt(-M)) <K>)(
 Use single-line command line editing instead of multi-line.
 )
 pindex(SUN_KEYBOARD_HACK)
@@ -988,7 +1000,7 @@ too small, and the backquote key lies annoyingly close to it.
 pindex(UNSET)
 cindex(parameters, substituting unset)
 cindex(unset parameters, substituting)
-item(tt(UNSET) (tt(PLUS()u), ksh: tt(PLUS()u)))(
+item(tt(UNSET) (tt(PLUS()u), ksh: tt(PLUS()u)) <K> <S> <Z>)(
 Treat unset parameters as if they were empty when substituting.
 Otherwise they are treated as an error.
 )
@@ -1008,7 +1020,8 @@ pindex(ZLE)
 cindex(editor, enabling)
 cindex(enabling the editor)
 item(tt(ZLE) (tt(-Z)))(
-Use the zsh line editor.
+Use the zsh line editor.  Set by default in interactive shells connected to
+a terminal.
 )
 enditem()
 texinode(Option Aliases)(Single Letter Options)(Description of Options)(Options)
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index 2dbff771e..f8089faf8 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -107,9 +107,6 @@ parentheses the string up to the matching closing one is considered to
 be a list of flags. The flags currently understood are:
 
 startitem()
-item(tt(e))(
-This option has no effect and retained for backward compatibility only.
-)
 item(tt(w))(
 If the parameter subscripted is a scalar than this flag makes
 subscripting work on words instead of characters.  The default word
@@ -162,6 +159,9 @@ if combined with `tt(r)', `tt(R)', `tt(i)' or `tt(I)', makes them begin
 at the var(n)th or var(n)th last element, word, or character (if var(expr)
 evaluates to var(n)).  This flag is ignored when the array is associative.
 )
+item(tt(e))(
+This option has no effect and retained for backward compatibility only.
+)
 enditem()
 texinode(Positional Parameters)(Local Parameters)(Array Parameters)(Parameters)
 sect(Positional Parameters)
@@ -431,7 +431,7 @@ The following parameters are used by the shell:
 startitem()
 vindex(ARGV0)
 item(tt(ARGV0))(
-If exported, its value is used as tt(argv[0]) of external commands.
+If exported, its value is used as the tt(argv[0]) of external commands.
 Usually used in constructs like `tt(ARGV0=emacs nethack)'.
 )
 vindex(BAUD)
@@ -888,8 +888,8 @@ 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))\
+ifzman(the zle module entry in zmanref(zshmodules))\
+ifnzman(noderef(The zle Module))\
 , 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
diff --git a/Doc/Zsh/redirect.yo b/Doc/Zsh/redirect.yo
index b44b07e63..3f30b75a1 100644
--- a/Doc/Zsh/redirect.yo
+++ b/Doc/Zsh/redirect.yo
@@ -173,11 +173,23 @@ example(echo foo > bar > baz)
 
 when tt(MULTIOS) is unset will truncate bar, and write `tt(foo)' into baz.
 
+sect(Redirections with no command)
+vindex(NULLCMD, use of)
+vindex(READNULLCMD, use of)
 If a simple command consists of one or more redirection operators
-and zero or more parameter assignments, but no command name,
-the command named in the shell variable tt(READNULLCMD) is assumed.
-(If tt(READNULLCMD) is empty or not set, `tt(cat)' is used.)  Thus
+and zero or more parameter assignments, but no command name, and the
+parameter tt(NULLCMD) is not set, an error is caused.  If the parameter
+tt(NULLCMD) is set, its value will be inserted as a command with the
+given redirections.  If both tt(NULLCMD) and tt(READNULLCMD) are set, then
+the value of the latter will be used instead of that of the former when the
+redirection is an input.  The default for tt(NULLCMD) is `tt(cat)' and for
+tt(READNULLCMD) is `tt(more)'. Thus
 
 example(< file)
 
-copies the contents of tt(file) to the standard output.
+shows the contents of tt(file) on standard output, with paging if that is a
+terminal.  tt(NULLCMD) and tt(READNULLCMD) may refer to shell functions.
+
+The standard Bourne shell behaviour is obtained by setting tt(NULLCMD) and
+tt(READNULLCMD) to `tt(:)'.  This is the default when zsh is emulating bf(sh)
+or bf(ksh).
diff --git a/Doc/Zsh/zftpsys.yo b/Doc/Zsh/zftpsys.yo
index d806a49b5..b99604d44 100644
--- a/Doc/Zsh/zftpsys.yo
+++ b/Doc/Zsh/zftpsys.yo
@@ -1,6 +1,7 @@
 texinode(Zftp Function System)()(Completion System)(Top)
 chapter(Zftp Function System)
-cindex(zftp, function system)
+cindex(zftp function system)
+cindex(FTP, functions for using shell as client)
 sect(Description)
 
 This describes the set of shell functions supplied with the source
@@ -70,6 +71,7 @@ same as that in a standard FTP client.
 
 subsect(Opening a connection)
 startitem()
+findex(zfparams)
 item(tt(zfparams [ var(host) [ var(user) [ var(password) ... ] ] ]))(
 Set or show the parameters for a future tt(zfopen) with no arguments.  If
 no arguments are given, the current parameters are displayed (the password
@@ -80,6 +82,7 @@ parameter given as `tt(?)' will be prompted for.
 As tt(zfopen) calls tt(zfparams) to store the parameters, this usually need
 not be called directly.
 )
+findex(zfopen)
 item(tt(zfopen [ -1 ] [ var(host) [ var(user) [ var(password) [ var(account) ] ] ] ]))(
 If var(host) is present, open a connection to that host under username
 var(user) with password var(password) (and, on the rare occasions when it
@@ -97,6 +100,7 @@ recorded for later re-opening, either by a tt(zfopen) with no arguments, or
 automatically (see below).  With the option `tt(-1)', no information is
 stored.
 )
+findex(zfanon)
 item(tt(zfanon [ -1 ] var(host)))(
 Open a connection var(host) for anonymous FTP.  The username used is
 tt(anonymous).  The password (which will be reported the first time) is
@@ -108,6 +112,7 @@ enditem()
 
 subsect(Directory management)
 startitem()
+findex(zfcd)
 xitem(tt(zfcd [ var(dir) ]))
 xitem(tt(zfcd -))
 item(tt(zfcd var(old) var(new)))(
@@ -137,12 +142,14 @@ tt(~/foo), so that the `tt(~)' will be expanded by the server to the
 correct remote host directory.  Other named directories of the form
 `tt(~name)' are not treated in this fashion.
 )
+findex(zfhere)
 item(tt(zfhere))(
 Change directory on the remote server to the one corresponding to the
 current local directory, with special handling of `tt(~)' as in tt(zfcd).
 For example, if the current local directory is tt(~/foo/bar), then
 tt(zfhere) performs the effect of `tt(zfcd ~/foo/bar)'.
 )
+findex(zfdir)
 item(tt(zfdir [ -rfd ] [ - ] [ var(dir-options) ] [ var(dir) ]))(
 Produce a long directory listing.  The arguments var(dir-options) and
 var(dir) are passed directly to the server and their effect is
@@ -161,6 +168,7 @@ tt(zfdir), the tt(-f) option can be used to force the cache to be flushed.
 Also, the option tt(-d) will delete both caches without showing a directory
 listing.
 )
+findex(zfdir)
 item(tt(zfls) [ var(ls-options) ] [ var(dir) ])(
 List files on the remote server.  With no arguments, this will produce a
 simple list of file names for the current remote directory.  Any arguments
@@ -170,12 +178,14 @@ enditem()
 
 subsect(Status commands)
 startitem()
+findex(zftype)
 item(tt(zftype) [ var(type) ])(
 With no arguments, show the type of data to be transferred, usually ASCII
 or binary.  With an argument, change the type: the types `tt(A)' or
 `tt(ASCII)' for ASCII data and `tt(B)' or `tt(BINARY)', `tt(I)' or
 `tt(IMAGE)' for binary data are understood case-insensitively.
 )
+findex(zfstat)
 item(tt(zfstat) [ -v ])(
 Show the status of the current or last connection, as well as the status of
 some of tt(zftp)'s status variables.  With the tt(-v) option, a more
@@ -193,12 +203,14 @@ this requires version 5 of tt(perl), see the description of the function
 tt(zfrtime) below for more information.
 
 startitem()
+findex(zfget)
 item(tt(zfget [ -Gt ] var(file1) ...))(
 Retrieve all the listed files var(file1) ... one at a time from the remote
 server.  If a file contains a `tt(/)', the full name is passed to the
 remote server, but the file is stored locally under the name given by the
 part after the final `tt(/)'.
 )
+findex(zfuget)
 item(tt(zfuget [ -Gvst ] var(file1) ...))(
 As tt(zfget), but only retrieve files where the version on the remote
 server is newer (has a later modification time), or where the local file
@@ -209,6 +221,7 @@ and will always retrieve the file in either of those two cases.  With the
 option tt(-v), the command prints more information about the files while it
 is working out whether or not to transfer them.
 )
+findex(zfcget)
 item(tt(zfcget [ -Gt ] var(file1) ...))(
 As tt(zfget), but if any of the local files exists, and is shorter than
 the corresponding remote file, the command assumes that it is the result of
@@ -218,6 +231,7 @@ file.  This is useful on a poor connection which keeps failing.
 Note that this requires a commonly implemented, but non-standard, version
 of the FTP protocol, so is not guaranteed to work on all servers.
 )
+findex(zfgcp)
 xitem(tt(zfgcp [ -Gt ] var(remote-file) var(local-file)))
 item(tt(zfgcp [ -Gt ] var(rfile1) ... var(ldir)))(
 This retrieves files from the remote server with arguments behaving
@@ -234,16 +248,19 @@ enditem()
 
 subsect(Sending files)
 startitem()
+findex(zfput)
 item(tt(zfput var(file1) ...))(
 Send all the var(file1) ... given separately to the remote server.  If a
 filename contains a `tt(/)', the full filename is used locally to find the
 file, but only the basename is used for the remote file name.
 )
+findex(zfuput)
 item(tt(zfuput [ -vs ] var(file1) ...))(
 As tt(zfput), but only send files which are newer than their local
 equivalents, or if the remote file does not exist.  The logic is the same
 as for tt(zfuget), but reversed between local and remote files.
 )
+findex(zfcput)
 item(tt(zfcput var(file1) ...))(
 As tt(zfput), but if any remote file already exists and is shorter than the
 local equivalent, assume it is the result of an incomplete transfer and
@@ -251,6 +268,7 @@ send the rest of the file to append to the existing part.  As the FTP
 append command is part of the standard set, this is in principle more
 likely to work than tt(zfcget).
 )
+findex(zfpcp)
 xitem(tt(zfpcp var(local-file) var(remote-file)))
 item(tt(zfpcp var(lfile1) ... var(rdir)))(
 This sends files to the remote server with arguments behaving similarly to
@@ -277,6 +295,7 @@ enditem()
 
 subsect(Closing the connection)
 startitem()
+findex(zfclose)
 item(tt(zfclose))(
 Close the connection.
 )
@@ -291,6 +310,7 @@ functions is called, it will be set to the file tt(.zfbfmarks) in the
 directory where your zsh startup files live (usually tt(~)).
 
 startitem()
+findex(zfmark)
 item(tt(zfmark [ )var(bookmark)tt( ]))(
 If given an argument, mark the current host, user and directory under the
 name var(bookmark) for later use by tt(zfgoto).  If there is no connection
@@ -301,6 +321,7 @@ under the same name will be silently replaced.
 If not given an argument, list the existing bookmarks and the points to
 which they refer in the form var(user)tt(@)var(host)tt(:)var(directory).
 )
+findex(zfgoto)
 item(tt(zfgoto [ -n ] )var(bookmark))(
 Return to the location given by var(bookmark), as previously set by
 tt(zfmark).  If the location has user `tt(ftp)' or `tt(anonymous)', open
@@ -323,11 +344,13 @@ tt(zfinit)), but are described here for completeness.  You may wish to
 alter tt(zftp_chpwd) and tt(zftp_progress), in particular.
 
 startitem()
+findex(zfinit)
 item(tt(zfinit [ -n ]))(
 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.
 )
+findex(zfautocheck)
 item(tt(zfautocheck [ -dn ]))(
 This function is called to implement automatic reopening behaviour, as
 described in more detail below.  The options must appear in the first
@@ -338,6 +361,7 @@ transfer.  The host and directory for the last session are stored in the
 variable tt($zflastsession), but the internal host/user/password parameters
 must also be correctly set.
 )
+findex(zfcd_match)
 item(tt(zfcd_match var(prefix) var(suffix)))(
 This performs matching for completion of remote directory names.  If the
 remote server is UNIX, it will attempt to persuade the server to list the
@@ -346,6 +370,7 @@ guaranteed.  On other hosts it simply calls tt(zfget_match) and hence
 completes all files, not just directories.  On some systems, directories
 may not even look like filenames.
 )
+findex(zfget_match)
 item(tt(zfget_match var(prefix) var(suffix)))(
 This performs matching for completion of remote filenames.  It caches files
 for the current directory (only) in the shell parameter tt($zftp_fcache).
@@ -353,12 +378,14 @@ It is in the form to be called by the tt(-K) option of tt(compctl), but
 also works when called from a widget-style completion function with
 var(prefix) and var(suffix) set appropriately.
 )
+findex(zfrglob)
 item(tt(zfrglob var(varname)))(
 Perform remote globbing, as describes in more detail below.  var(varname)
 is the name of a variable containing the pattern to be expanded; if there
 were any matches, the same variable will be set to the expanded set of
 filenames on return.
 )
+findex(zfrtime)
 item(tt(zfrtime var(lfile) var(rfile) [ var(time) ]))(
 Set the local file var(lfile) to have the same modification time as the
 remote file var(rfile), or the explicit time var(time) in FTP format
@@ -368,6 +395,7 @@ Currently this requires tt(perl) version 5 to perform the conversion from
 GMT to local time.  This is unfortunately difficult to do using shell code
 alone.
 )
+findex(zftp_chpwd, supplied version)
 item(tt(zftp_chpwd))(
 This function is called every time a connection is opened, or closed, or
 the remote directory changes.  This version alters the title bar of an
@@ -385,6 +413,7 @@ example(chpwd() {
 
 fits in well.
 )
+findex(zftp_progress, supplied version)
 item(tt(zftp_progress))(
 This function shows the status of the transfer as the percentage of the
 total so far transferred.  It will not write anything unless the output is
@@ -399,6 +428,7 @@ texinode(Miscellaneous Features)()(Zftp Functions)(Zftp Function System)
 sect(Miscellaneous Features)
 
 subsect(Remote globbing)
+cindex(zftp function system, remote globbing)
 
 The commands for retrieving files usually perform filename expansion
 (globbing) on their arguments; this can be turned off by passing the option
@@ -422,6 +452,7 @@ patterns.  This may in some cases be faster, as it avoids retrieving the
 entire list of directory contents.
 
 subsect(Automatic and temporary reopening)
+cindex(zftp function system, automatic reopening)
 
 As described for the tt(zfopen) command, a subsequent tt(zfopen) with no
 parameters will reopen the connection to the last host (this includes
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 60c003533..e04737da9 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -4,9 +4,9 @@ cindex(line editor)
 cindex(editor, line)
 sect(Description)
 pindex(ZLE, use of)
-If the tt(ZLE) option is set (it is by default)
+If the tt(ZLE) option is set (which it is by default in interactive shells)
 and the shell input is attached to the terminal, the user
-is allowed to edit command lines.
+is able to edit command lines.
 
 There are two display modes.  The first, multiline mode, is the
 default.  It only works if the tt(TERM) parameter is set to a valid
@@ -67,7 +67,8 @@ that is bound to some command and is also a prefix of a longer bound string.
 In this case ZLE will wait a certain time to see if more characters
 are typed, and if not (or they don't match any longer string) it will
 execute the binding.  This timeout is defined by the tt(KEYTIMEOUT) parameter;
-its default is 0.4 sec.  No timeout is done if the prefix string is not bound.
+its default is 0.4 sec.  There is no timeout if the prefix string is not
+itself bound to a command.
 
 As well as ZLE commands, key sequences can be bound to other strings, by using
 `tt(bindkey -s)'.
@@ -83,7 +84,7 @@ simply to perform some small action.  The ZLE commands that key sequences
 in keymaps are bound to are in fact widgets.  Widgets can be user-defined
 or built in.
 
-There are 162 standard widgets built in to ZLE (see Standard Widgets below).
+The standard widgets built in to ZLE are listed in Standard Widgets below.
 Other built-in widgets can be defined by other modules (see
 ifzman(zmanref(zshmodules))\
 ifnzman(noderef(Zsh Modules))\
@@ -163,7 +164,7 @@ item(tt(NUMERIC) (integer))(
 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
+assigned. If it is unset inside a widget function, builtin widgets
 called behave as if no numeric argument was given.
 )
 vindex(HISTNO)
@@ -508,7 +509,10 @@ Insert the last word from the previous history event at the
 cursor position.  If a positive numeric argument is given,
 insert that word from the end of the previous history event.
 If the argument is zero or negative insert that word from the
-left (zero inserts the previous command word).
+left (zero inserts the previous command word).  Repeating this command
+replaces the word just inserted with the last word from the
+history event prior to the one just used; numeric arguments can be used in
+the same way to pick a word from that event.
 )
 tindex(vi-repeat-search)
 item(tt(vi-repeat-search) (unbound) (n) (unbound))(