New upstream version 5.8.1.2-test

36 files changed, 1409 insertions, 795 deletions

diff --git a/Doc/Zsh/arith.yo b/Doc/Zsh/arith.yo
index c152bf48d..bc3e35ad5 100644
--- a/Doc/Zsh/arith.yo
+++ b/Doc/Zsh/arith.yo
@@ -20,7 +20,7 @@ The tt(let) builtin command takes arithmetic expressions as arguments; each
 is evaluated separately.  Since many of the arithmetic operators, as well
 as spaces, require quoting, an alternative form is provided: for any
 command which begins with a `tt(LPAR()LPAR())', all the characters until a
-matching `tt(RPAR()RPAR())' are treated as a quoted expression and
+matching `tt(RPAR()RPAR())' are treated as a double-quoted expression and
 arithmetic expansion performed as for an argument of tt(let).  More
 precisely, `tt(LPAR()LPAR())var(...)tt(RPAR()RPAR())' is equivalent to
 `tt(let ")var(...)tt(")'.  The return status is 0 if the arithmetic value
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index ada69c99a..1d74f0c17 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -105,7 +105,13 @@ For each var(name) with a corresponding var(value), define an alias
 with that value.  A trailing space in var(value) causes the next word
 to be checked for alias expansion.  If the tt(-g) flag is present,
 define a global alias; global aliases are expanded even if they do not
-occur in command position.
+occur in command position:
+
+example(% perldoc --help 2>&1 | grep 'built-in functions'
+    -f   Search Perl built-in functions
+% alias -g HG='--help 2>&1 | grep'
+% perldoc HG 'built-in functions'
+    -f   Search Perl built-in functions)
 
 If the tt(-s) flag is present, define a suffix alias: if the command
 word on a command line is in the form `var(text)tt(.)var(name)', where
@@ -730,7 +736,7 @@ findex(fc)
 cindex(history, editing)
 cindex(editing history)
 redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ ))ifnztexi(      )))
-xitem(tt(fc) [ tt(-e) var(ename) ] [ tt(-LI) ] [ tt(-m) var(match) ] [ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ])
+xitem(tt(fc) [ tt(-e) var(ename) ] [ tt(-s) ] [ tt(-LI) ] [ tt(-m) var(match) ] [ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ])
 xitem(tt(fc -l )[ tt(-LI) ] [ tt(-nrdfEiD) ] [ tt(-t) var(timefmt) ] [ tt(-m) var(match) ])
 xitem(SPACES()[ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ])
 xitem(tt(fc -p )[ tt(-a) ] [ var(filename) [ var(histsize) [ var(savehistsize) ] ] ])
@@ -750,15 +756,16 @@ specifies the most recent event beginning with the given string.  All
 substitutions var(old)tt(=)var(new), if any, are then performed on the
 text of the events.
 
-In addition to the number range,
+The range of events selected by numbers can be narrowed further by the
+following flags.
 startsitem()
 sitem(tt(-I))(restricts to only internal events (not from tt($HISTFILE)))
 sitem(tt(-L))(restricts to only local events (not from other shells, see
 tt(SHARE_HISTORY) in ifzman(zmanref(zshoptions))\
 ifnzman(noderef(Description of Options)) -- note that tt($HISTFILE) is
 considered local when read at startup))
-sitem(tt(-m))(takes the first argument as a pattern (should be quoted) and
-only the history events matching this pattern are considered)
+sitem(tt(-m))(takes the first argument as a pattern (which should be
+quoted) and only the history events matching this pattern are considered)
 endsitem()
 
 If var(first) is not specified, it will be set to -1 (the most recent
@@ -777,6 +784,7 @@ the parameter tt(EDITOR) is used; if that is not set a builtin default,
 usually `tt(vi)' is used.  If var(ename) is `tt(-)', no editor is invoked.
 When editing is complete, the edited command is executed.
 
+The flag `tt(-s)' is equivalent to `tt(-e -)'.
 The flag tt(-r) reverses the order of the events and the
 flag tt(-n) suppresses event numbers when listing.
 
@@ -886,6 +894,10 @@ without affecting the other.  A typical idiom is that var(oldfn) is the
 name of a library shell function which is then redefined to call
 tt(newfn), thereby installing a modified version of the function.
 
+em(The )tt(-M)em( and )tt(+M)em( flags)
+cindex(defining mathematical functions)
+cindex(functions, defining mathematical)
+
 Use of the tt(-M) option may not be combined with any of the options
 handled by tt(typeset -f).
 
@@ -907,9 +919,55 @@ expressions.  The name of the function in tt($0) is var(mathfn) (not
 var(shellfn) as would usually be the case), provided the option
 tt(FUNCTION_ARGZERO) is in effect.  The positional parameters in the shell
 function correspond to the arguments of the mathematical function call.
-The result of the last arithmetical expression evaluated
-inside the shell function (even if it is a form that normally only returns
-a status) gives the result of the mathematical function.
+
+The result of the last arithmetical expression evaluated inside the shell
+function gives the result of the mathematical function.  This is not limited to
+arithmetic substitutions of the form tt($+LPAR()+LPAR())var(...)tt(+RPAR()+RPAR()),
+but also includes arithmetical expressions evaluated in any other way, including
+by the tt(let) builtin,
+by tt(+LPAR()+LPAR())var(...)tt(+RPAR()+RPAR()) statements,
+and even
+by the tt(return) builtin
+and
+by array subscripts.
+Therefore, care must be taken not to use syntactical constructs that perform
+arithmetic evaluation after evaluating what is to be the result of the function.
+For example:
+
+findex(zmath_cube)
+findex(cube)
+example(# WRONG
+zmath_cube+LPAR()+RPAR() {
+  (( $1 * $1 * $1 ))
+  return 0
+}
+functions -M cube 1 1 zmath_cube
+print $(( cube+LPAR()3+RPAR() )))
+
+This will print `tt(0)' because of the tt(return).
+
+Commenting the tt(return) out would lead to a different problem: the
+tt(+LPAR()+LPAR())var(...)tt(+RPAR()+RPAR()) statement would become
+the last statement in the function, so the em(return status) (tt($?)) of the
+function would be non-zero (indicating failure) whenever the em(arithmetic
+result) of the function would happen to be zero (numerically):
+
+example(# WRONG
+zmath_cube+LPAR()+RPAR() {
+  (( $1 * $1 * $1 ))
+}
+functions -M cube 1 1 zmath_cube
+print $(( cube+LPAR()0+RPAR() )))
+
+Instead, the tt(true) builtin can be used:
+
+example(# RIGHT
+zmath_cube+LPAR()+RPAR() {
+  (( $1 * $1 * $1 ))
+  true
+}
+functions -M cube 1 1 zmath_cube
+print $(( cube+LPAR()3+RPAR() )))
 
 If the additional option tt(-s) is given to tt(functions -M), the
 argument to the function is a single string: anything between the
@@ -917,6 +975,12 @@ opening and matching closing parenthesis is passed to the function as a
 single argument, even if it includes commas or white space.  The minimum
 and maximum argument specifiers must therefore be 1 if given.  An empty
 argument list is passed as a zero-length string.
+Thus, the following string function takes a single argument, including
+the commas, and prints 11:
+
+example(stringfn+LPAR()RPAR() { (( $#1 )); true }
+functions -Ms stringfn
+print $(( stringfn+LPAR()foo,bar,rod+RPAR() )))
 
 tt(functions -M) with no arguments lists all such user-defined functions in
 the same form as a definition.  With the additional option tt(-m) and
@@ -928,19 +992,6 @@ additional option tt(-m) the arguments are treated as patterns and
 all functions whose var(mathfn) matches the pattern are removed.  Note
 that the shell function implementing the behaviour is not removed
 (regardless of whether its name coincides with var(mathfn)).
-
-For example, the following prints the cube of 3:
-
-example(zmath_cube+LPAR()RPAR() { (( $1 * $1 * $1 )) }
-functions -M cube 1 1 zmath_cube
-print $(( cube+LPAR()3+RPAR() )))
-
-The following string function takes a single argument, including
-the commas, so prints 11:
-
-example(stringfn+LPAR()RPAR() { (( $#1 )) }
-functions -Ms stringfn
-print $(( stringfn+LPAR()foo,bar,rod+RPAR() )))
 )
 module(getcap)(zsh/cap)
 findex(getln)
@@ -975,7 +1026,8 @@ vindex(OPTARG, use of)
 The first option to be examined may be changed by explicitly assigning
 to tt(OPTIND).  tt(OPTIND) has an initial value of tt(1), and is
 normally set to tt(1) upon entry to a shell function and restored
-upon exit (this is disabled by the tt(POSIX_BUILTINS) option).  tt(OPTARG)
+upon exit.  (The tt(POSIX_BUILTINS) option disables this, and also changes
+the way the value is calculated to match other shells.)  tt(OPTARG)
 is not reset and retains its value from the most recent call to
 tt(getopts).  If either of tt(OPTIND) or tt(OPTARG) is explicitly
 unset, it remains unset, and the index or option argument is not
@@ -1062,6 +1114,24 @@ The tt(-Z) option replaces the shell's argument and environment space with
 the given string, truncated if necessary to fit.  This will normally be
 visible in tt(ps) (manref(ps)(1)) listings.  This feature is typically
 used by daemons, to indicate their state.
+
+Full job control is only available in the top-level interactive shell,
+not in commands run in the left hand side of pipelines or within
+the tt(LPAR())var(...)tt(RPAR()) construct.  However, a snapshot
+of the job state at that point is taken, so it is still possible
+to use the tt(jobs) builtin, or any parameter providing job information.
+This gives information about the state of jobs at the point the subshell
+was created.  If background processes are created within the subshell,
+then instead information about those processes is provided.
+
+For example,
+
+example(sleep 10 &    # Job in background
+LPAR()             # Shell forks
+jobs          # Shows information about "sleep 10 &"
+sleep 5 &     # Process in background (no job control)
+jobs          # Shows information about "sleep 5 &"
+RPAR())
 )
 findex(kill)
 cindex(killing jobs)
@@ -1184,14 +1254,6 @@ Same as tt(typeset), except that the options tt(-g), and
 tt(-f) are not permitted.  In this case the tt(-x) option does not force
 the use of tt(-g), i.e. exported variables will be local to functions.
 )
-findex(log)
-vindex(watch, use of)
-cindex(watching users)
-cindex(users, watching)
-item(tt(log))(
-List all users currently logged in who are affected by
-the current setting of the tt(watch) parameter.
-)
 findex(logout)
 item(tt(logout) [ var(n) ])(
 Same as tt(exit), except that it only works in a login shell.
@@ -1442,7 +1504,7 @@ findex(read)
 vindex(IFS, use of)
 redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ ))ifnztexi(     )))
 xitem(tt(read )[ tt(-rszpqAclneE) ] [ tt(-t) [ var(num) ] ] [ tt(-k) [ var(num) ] ] [ tt(-d) var(delim) ])
-item(SPACES()[ tt(-u) var(n) ] [ var(name)[tt(?)var(prompt)] ] [ var(name) ...  ])(
+item(SPACES()[ tt(-u) var(n) ] [ [var(name)][tt(?)var(prompt)] ] [ var(name) ...  ])(
 vindex(REPLY, use of)
 vindex(reply, use of)
 Read one line and break it into fields using the characters
@@ -1576,7 +1638,13 @@ cindex(functions, returning from)
 item(tt(return) [ var(n) ])(
 Causes a shell function or `tt(.)' script to return to
 the invoking script with the return status specified by
-an arithmetic expression var(n). If var(n)
+an arithmetic expression var(n).  
+For example, the following prints `tt(42)':
+
+example(() { integer foo=40; return "foo + 2" }
+echo $?)
+
+If var(n)
 is omitted, the return status is that of the last command
 executed.
 
@@ -1587,7 +1655,7 @@ will return to whatever it was previously processing; with a non-zero
 status, the shell will behave as interrupted except that the return
 status of the trap is retained.  Note that the numeric value of the signal
 which caused the trap is passed as the first argument, so the statement
-`tt(return $((128PLUS()$1)))' will return the same status as if the signal
+`tt(return "128PLUS()$1")' will return the same status as if the signal
 had not been trapped.
 )
 module(sched)(zsh/sched)
@@ -1836,7 +1904,8 @@ unfreezing the tty does not guarantee settings made on the
 command line are preserved.  Strings of commands run between
 editing the command line will see a consistent tty state.
 See also the shell variable tt(STTY) for a means of initialising
-the tty before running external commands.
+the tty before running external commands and/or freezing the tty
+around a single command.
 )
 findex(type)
 item(tt(type) [ tt(-wfpamsS) ] var(name) ...)(
@@ -1865,7 +1934,11 @@ ifnzman(noderef(Local Parameters))\
 retain their special attributes when made local.
 
 For each var(name)tt(=)var(value) assignment, the parameter
-var(name) is set to var(value).
+var(name) is set to var(value).  If the assignment is omitted and var(name)
+does em(not) refer to an existing parameter, a new parameter is intialized
+to empty string, zero, or empty array (as appropriate), em(unless) the
+shell option tt(TYPESET_TO_UNSET) is set.  When that option is set,
+the parameter attributes are recorded but the parameter remains unset.
 
 If the shell option tt(TYPESET_SILENT) is not set, for each remaining
 var(name) that refers to a parameter that is already set, the name and
@@ -1933,7 +2006,7 @@ a set of three normal command line arguments to tt(typeset) after
 expansion.  Hence it is not possible to assign to multiple arrays by
 this means.
 
-Note that each interface to any of the commands my be disabled
+Note that each interface to any of the commands may be disabled
 separately.  For example, `tt(disable -r typeset)' disables the reserved
 word interface to tt(typeset), exposing the builtin interface, while
 `tt(disable typeset)' disables the builtin.  Note that disabling the
@@ -2294,7 +2367,7 @@ findex(umask)
 cindex(umask)
 item(tt(umask) [ tt(-S) ] [ var(mask) ])(
 The umask is set to var(mask).  var(mask) can be either
-an octal number or a symbolic value as described in manref(chmod)(1).
+an octal number or a symbolic value as described in the manref(chmod)(1) man page.
 If var(mask) is omitted, the current value is printed.  The tt(-S)
 option causes the mask to be printed as a symbolic value.  Otherwise,
 the mask is printed as an octal number.  Note that in
diff --git a/Doc/Zsh/calsys.yo b/Doc/Zsh/calsys.yo
index c20c87e61..a8fd876a5 100644
--- a/Doc/Zsh/calsys.yo
+++ b/Doc/Zsh/calsys.yo
@@ -478,7 +478,7 @@ item(tt(calendar_add) [ tt(-BL) ] var(event) ...)(
 Adds a single event to the calendar in the appropriate location.
 The event can contain multiple lines, as described in
 ifnzman(noderef(Calendar File and Date Formats))\
-ifzman(the section Calendar File Format above).
+ifzman(the section `Calendar File Format' above).
 Using this function ensures that the calendar file is sorted in date
 and time order.  It also makes special arrangements for locking
 the file while it is altered.  The old calendar is left in a file
diff --git a/Doc/Zsh/compat.yo b/Doc/Zsh/compat.yo
index f1be15fee..4d3567d45 100644
--- a/Doc/Zsh/compat.yo
+++ b/Doc/Zsh/compat.yo
@@ -30,8 +30,7 @@ tt(PROMPT2),
 tt(PROMPT3),
 tt(PROMPT4),
 tt(psvar),
-tt(status),
-tt(watch).
+tt(status).
 
 vindex(ENV, use of)
 The usual zsh startup/shutdown scripts are not executed.  Login shells
@@ -74,3 +73,9 @@ tt(PROMPT_SUBST)
 and
 tt(SINGLE_LINE_ZLE)
 options are set if zsh is invoked as tt(ksh).
+
+Please note that, whilst reasonable efforts are taken to address
+incompatibilities when they arise, zsh does not guarantee complete
+emulation of other shells, nor POSIX compliance. For more information on
+the differences between zsh and other shells, please refer to chapter 2
+of the shell FAQ, uref(https://www.zsh.org/FAQ/).
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index c2d20ca40..584ede441 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -49,7 +49,7 @@ Styles modify various operations of the completion system, such as
 output formatting, but also what kinds of completers are used (and in
 what order), or which tags are examined.  Styles may accept arguments
 and are manipulated using the tt(zstyle) command described in
-ifzman(see zmanref(zshmodules))\
+ifzman(zmanref(zshmodules))\
 ifnzman(noderef(The zsh/zutil Module)).
 
 In summary, tags describe em(what) the completion objects are, and style
@@ -190,7 +190,7 @@ tt(compinit) will ask if the completion system should really be used.  To
 avoid these tests and make all files found be used without asking, use the
 option tt(-u), and to make tt(compinit) silently ignore all insecure files
 and directories use the option tt(-i).  This security check is skipped
-entirely when the tt(-C) option is given.
+entirely when the tt(-C) option is given, provided the dumpfile exists.
 
 findex(compaudit)
 The security check can be retried at any time by running the function
@@ -322,15 +322,15 @@ item(tt(-array-value-))(
 The right hand side of an array-assignment
 (`var(name)tt(=LPAR())var(...)tt(RPAR())')
 )
-kindex(-brace-parameter-, completion context)
-item(tt(-brace-parameter-))(
-The name of a parameter expansion within braces (`tt(${)var(...)tt(})')
-)
 kindex(-assign-parameter-, completion context)
 item(tt(-assign-parameter-))(
 The name of a parameter in an assignment, i.e. on the left hand side of
 an `tt(=)'
 )
+kindex(-brace-parameter-, completion context)
+item(tt(-brace-parameter-))(
+The name of a parameter expansion within braces (`tt(${)var(...)tt(})')
+)
 kindex(-command-, completion context)
 item(tt(-command-))(
 A word in command position
@@ -658,8 +658,8 @@ ifnzman(noderef(Bindable Commands)).
 When looking up styles the completion system uses full context names,
 including the tag.  Looking up the value of a style therefore consists of
 two things: the context, which is matched to the most specific (best
-fitting) style pattern, and the name of the style itself, which must be
-matched exactly.  The following examples demonstrate that style patterns
+fitting) pattern, and the name of the style itself, which must be
+matched exactly.  The following examples demonstrate that patterns
 may be loosely defined for styles that apply broadly, or as tightly
 defined as desired for styles that apply in narrower circumstances.
 
@@ -673,7 +673,7 @@ example(zstyle ':completion:*' verbose yes)
 in a startup file (probably tt(.zshrc)).
 This gives the tt(verbose) style the value tt(yes) in every
 context inside the completion system, unless that context has a more
-specific definition.  It is best to avoid giving the context as `tt(*)'
+specific definition.  It is best to avoid giving the pattern as `tt(*)'
 in case the style has some meaning outside the completion system.
 
 Many such general purpose styles can be configured simply by using the
@@ -710,15 +710,21 @@ as tt(menu) and tt(list-rows-first).
 
 Note that the order in which styles are em(defined) does not matter; the
 style mechanism uses the most specific possible match for a particular
-style to determine the set of values.  More precisely, strings are
+style to determine the set of values.  Strings are
 preferred over patterns (for example, `tt(:completion::complete:::foo)' is
 more specific than `tt(:completion::complete:::*')), and longer patterns are
-preferred over shorter patterns.
-
-A good rule of thumb is that any completion style pattern that needs to
-include more than one wildcard (tt(*)) and that does not end in a tag
-name, should include all six colons (tt(:)), possibly surrounding
-additional wildcards.
+preferred over the pattern `tt(*)'. See 
+ifzman(zmanref(zmodules))ifnzman(noderef(The zsh/zutil Module))
+for details.
+
+Context patterns that use something other than a wildcard (tt(*)) to match the
+middle parts of the context DASH()- the var(completer), var(command), and
+var(argument) in
+tt(:completion:)var(function)tt(:)var(completer)tt(:)var(command)tt(:)var(argument)tt(:)var(tag)
+DASH()- should include all six colons (tt(:)) explicitly. Without this,
+a pattern such as tt(:completion:*:foo:*) could match tt(foo) against a
+component other than the intended one (for example, against var(completer) when
+a match against var(command) was intended).
 
 Style names like those of tags are arbitrary and depend on the completion
 function.  However, the following two sections list some of the most
@@ -885,14 +891,14 @@ kindex(indexes, completion tag)
 item(tt(indexes))(
 for array indexes
 )
-kindex(jobs, completion tag)
-item(tt(jobs))(
-for jobs (as listed by the `tt(jobs)' builtin)
-)
 kindex(interfaces, completion tag)
 item(tt(interfaces))(
 for network interfaces
 )
+kindex(jobs, completion tag)
+item(tt(jobs))(
+for jobs (as listed by the `tt(jobs)' builtin)
+)
 kindex(keymaps, completion tag)
 item(tt(keymaps))(
 for names of zsh keymaps
@@ -916,14 +922,14 @@ directory when completing arguments of tt(cd) and related builtin
 commands (compare tt(path-directories)) DASH()- when the tt(cdpath)
 array is unset, tt(directories) is used instead
 )
-kindex(manuals, completion tag)
-item(tt(manuals))(
-for names of manual pages
-)
 kindex(mailboxes, completion tag)
 item(tt(mailboxes))(
 for e-mail folders
 )
+kindex(manuals, completion tag)
+item(tt(manuals))(
+for names of manual pages
+)
 kindex(maps, completion tag)
 item(tt(maps))(
 for map names (e.g. NIS maps)
@@ -973,11 +979,6 @@ kindex(other-accounts, completion tag)
 item(tt(other-accounts))(
 used to look up the tt(users-hosts) style
 )
-kindex(other-files, completion tag)
-item(tt(other-files))(
-for the names of any non-directory files.  This is used instead
-of tt(all-files) when the tt(list-dirs-first) style is in effect.
-)
 kindex(packages, completion tag)
 item(tt(packages))(
 for packages (e.g. tt(rpm) or installed tt(Debian) packages)
@@ -1388,6 +1389,12 @@ components after the first ambiguous one will also be added.  This means
 that the resulting string is the longest unambiguous string possible.
 However, menu completion can be used to cycle through all matches.
 )
+kindex(extra-verbose, completion style)
+item(tt(extra-verbose))(
+If set, the completion listing is more verbose at the cost of
+a probable decrease in completion speed.  Completion performance
+will suffer if this style is set to `true'.
+)
 kindex(fake, completion style)
 item(tt(fake))(
 This style may be set for any completion context.  It
@@ -1523,9 +1530,10 @@ If no `tt(:)var(tag)' is given the `tt(files)' tag will be used.
 The var(tag) may also be followed by an optional second colon and a
 description, which will be used for the `tt(%d)' in the value of
 the tt(format) style (if that is set) instead of the default
-description supplied by the completion function.  If the description
-given here contains itself a `tt(%d)', that is replaced with the
-description supplied by the completion function.
+description supplied by the completion function.  The inclusion
+of a description also gives precedence to associated options such as
+for completion grouping so it can be used where files should be
+separated.
 
 For example, to make the tt(rm) command first complete only names of
 object files and then the names of all files if there is no matching
@@ -1547,6 +1555,15 @@ all files using the pattern `tt(*)' at the first step and stops when it
 sees this pattern.  Note also it will never try a pattern more than once
 for a single completion attempt.
 
+To separate directories into a separate group from the files but still
+complete them at the first attempt, a description needs to be given.
+Note that directories need to be explicitly excluded from the
+globbed-files because `tt(*)' will match directories. For grouping, it
+is also necessary to set the tt(group-name) style.
+
+example(zstyle ':completion:*' file-patterns \ 
+    '%p+LPAR()^-/RPAR():globbed-files *(-/):directories:location')
+
 During the execution of completion functions, the tt(EXTENDED_GLOB)
 option is in effect, so the characters `tt(#)', `tt(~)' and `tt(^)' have
 special meanings in the patterns.
@@ -1641,6 +1658,15 @@ ifzman(zmanref(zshmodules))\
 ifnzman(noderef(The zsh/zutil Module))\
 .
 )
+kindex(gain-privileges, completion style)
+item(tt(gain-privileges))(
+If set to tt(true), this style enables the use of commands like tt(sudo)
+or tt(doas) to gain extra privileges when retrieving information for
+completion. This is only done when a command such as tt(sudo) appears on
+the command-line. To force the use of, e.g. tt(sudo) or to override any
+prefix that might be added due to tt(gain-privileges), the tt(command)
+style can be used with a value that begins with a hyphen.
+)
 kindex(glob, completion style)
 item(tt(glob))(
 This is used by the tt(_expand) completer.  If
@@ -1679,6 +1705,9 @@ example(zstyle ':completion:*' group-name '')
 
 All matches for which no group name is defined will be put in a group
 named tt(-default-).
+
+To display the group name in the output, see the tt(format) style (q.v.)
+under the tt(descriptions) tag.
 )
 kindex(group-order, completion style)
 item(tt(group-order))(
@@ -1784,12 +1813,6 @@ Excluded values act in a similar fashion to values of the
 tt(ignored-patterns) style, so they can be restored to consideration by
 the tt(_ignored) completer.
 )
-kindex(extra-verbose, completion style)
-item(tt(extra-verbose))(
-If set, the completion listing is more verbose at the cost of
-a probable decrease in completion speed.  Completion performance
-will suffer if this style is set to `true'.
-)
 kindex(ignored-patterns, completion style)
 item(tt(ignored-patterns))(
 A list of patterns; any trial completion matching one of the patterns
@@ -1826,6 +1849,28 @@ be unsuccessful until that point.  If the value is any other
 string, menu completion will be started when the string typed by the
 user is longer than the common prefix to the corresponding IDs.
 )
+kindex(insert-sections, completion style)
+item(tt(insert-sections))(
+This style is used with tags of the form `tt(manuals.)var(X)' when
+completing names of manual pages. If set and the var(X) in the tag name matches
+the section number of the page being completed, the section number is inserted
+along with the page name. For example, given
+
+example(zstyle ':completion:*:manuals.*' insert-sections true)
+
+tt(man ssh_<TAB>) may be completed to tt(man 5 ssh_config).
+
+The value may also be set to one of `tt(prepend)', or `tt(suffix)'.
+`tt(prepend)' behaves the same as `true' as in the above example, while
+`tt(suffix)' would complete tt(man ssh_<TAB>) as tt(man ssh_config.5).
+
+This is especially useful in conjunction with tt(separate-sections), as
+it ensures that the page requested of tt(man) corresponds to the one
+displayed in the completion listing when there are multiple pages with the
+same name (e.g., tt(printf+LPAR()1+RPAR()) and tt(printf+LPAR()3+RPAR())).
+
+The default for this style is `false'.
+)
 kindex(insert-tab, completion style)
 item(tt(insert-tab))(
 If this is set to `true', the completion system will
@@ -1864,15 +1909,6 @@ In the case of the tt(_match) completer, the style may also be set to
 the string `tt(pattern)'.  Then the pattern on the line is left
 unchanged if it does not match unambiguously.
 )
-kindex(gain-privileges, completion style)
-item(tt(gain-privileges))(
-If set to tt(true), this style enables the use of commands like tt(sudo)
-or tt(doas) to gain extra privileges when retrieving information for
-completion. This is only done when a command such as tt(sudo) appears on
-the command-line. To force the use of, e.g. tt(sudo) or to override any
-prefix that might be added due to tt(gain-privileges), the tt(command)
-style can be used with a value that begins with a hyphen.
-)
 kindex(keep-prefix, completion style)
 item(tt(keep-prefix))(
 This style is used by the tt(_expand) completer.  If it is `true', the
@@ -1888,6 +1924,13 @@ The behaviour of tt(_expand) when this style is `true' is to cause tt(_expand)
 to give up when a single expansion with the restored prefix is the same
 as the original; hence any remaining completers may be called.
 )
+kindex(known-hosts-files)
+item(tt(known-hosts-files))(
+This style should contain a list of files to search for host names and
+(if the tt(use-ip) style is set) IP addresses in a format compatible with
+ssh tt(known_hosts) files.  If it is not set, the files
+tt(/etc/ssh/ssh_known_hosts) and tt(~/.ssh/known_hosts) are used.
+)
 kindex(last-prompt, completion style)
 item(tt(last-prompt))(
 This is a more flexible form of the tt(ALWAYS_LAST_PROMPT) option.
@@ -1899,13 +1942,6 @@ previous line if this style is `true' for all types of match.  Note
 that unlike the tt(ALWAYS_LAST_PROMPT) option this is independent of the
 numeric argument.
 )
-kindex(known-hosts-files)
-item(tt(known-hosts-files))(
-This style should contain a list of files to search for host names and
-(if the tt(use-ip) style is set) IP addresses in a format compatible with
-ssh tt(known_hosts) files.  If it is not set, the files
-tt(/etc/ssh/ssh_known_hosts) and tt(~/.ssh/known_hosts) are used.
-)
 kindex(list, completion style)
 item(tt(list))(
 This style is used by the tt(_history_complete_word) bindable command.
@@ -1945,11 +1981,10 @@ obtained by setting the style to an empty string (i.e. tt('')).
 )
 kindex(list-dirs-first, completion style)
 item(tt(list-dirs-first))(
-This is used by file completion.  If set, directories to be completed
-are listed separately from and before completion for other files,
-regardless of tag ordering.  In addition, the tag tt(other-files)
-is used in place of tt(all-files) for the remaining files, to indicate
-that no directories are presented with that tag.
+This is used by file completion and corresponds to a particular
+setting of the tt(file-patterns) style.
+If set, the default directories to be completed
+are listed separately from and before completion for other files.
 )
 kindex(list-grouped, completion style)
 item(tt(list-grouped))(
@@ -2004,6 +2039,12 @@ This style is tested in the same way as the tt(list-packed) style and
 determines whether matches are to be listed in a rows-first fashion as
 if the tt(LIST_ROWS_FIRST) option were set.
 )
+kindex(list-separator, completion style)
+item(tt(list-separator))(
+The value of this style is used in completion listing to separate the
+string to complete from a description when possible (e.g. when
+completing options).  It defaults to `tt(-)tt(-)' (two hyphens).
+)
 kindex(list-suffixes, completion style)
 item(tt(list-suffixes))(
 This style is used by the function that completes filenames.  If it is
@@ -2011,12 +2052,6 @@ This style is used by the function that completes filenames.  If it is
 typed pathname components, all ambiguous components will be shown.
 Otherwise, completion stops at the first ambiguous component.
 )
-kindex(list-separator, completion style)
-item(tt(list-separator))(
-The value of this style is used in completion listing to separate the
-string to complete from a description when possible (e.g. when
-completing options).  It defaults to `tt(-)tt(-)' (two hyphens).
-)
 kindex(local, completion style)
 item(tt(local))(
 This is for use with functions that complete URLs for which the
@@ -2445,7 +2480,7 @@ For example,
 example(zstyle ':completion:*' recursive-files '*/zsh/*')
 
 If the current directory is tt(/home/pws/zsh/Src), then
-tt(zle_tr)em(TAB) can be completed to tt(Zle/zle_tricky.c).
+tt(zle_tr<TAB>) can be completed to tt(Zle/zle_tricky.c).
 )
 kindex(regular, completion style)
 item(tt(regular))(
@@ -2502,12 +2537,13 @@ kindex(separate-sections, completion style)
 item(tt(separate-sections))(
 This style is used with the tt(manuals) tag when completing names of
 manual pages.  If it is `true', entries for different sections are
-added separately using tag names of the form `tt(manual.)var(X)',
+added separately using tag names of the form `tt(manuals.)var(X)',
 where var(X) is the section number.  When the tt(group-name) style is
 also in effect, pages from different sections will appear separately.
 This style is also used similarly with the tt(words) style when
 completing words for the dict command. It allows words from different
-dictionary databases to be added separately.
+dictionary databases to be added separately. See also tt(insert-sections).
+
 The default for this style is `false'.
 )
 kindex(show-ambiguity, completion style)
@@ -3584,8 +3620,18 @@ described using the var(spec)s which are of the form:
 `var(tag)tt(:)var(descr)tt(:)var(action)'.  The var(tag)s are offered using
 tt(_tags) and if the tag is requested, the var(action) is executed with the
 given description var(descr).  The var(action)s are those accepted
-by the tt(_arguments) function (described below), excluding the
-`tt(->)var(state)' and `tt(=)var(...)' forms.
+by the tt(_arguments) function (described below), with the following
+exceptions:
+startitemize()
+itemiz(\
+The `tt(->)var(state)' and `tt(=)var(...)' forms are not supported.
+)
+itemiz(\
+The `tt(LPAR()LPAR()a\:bar b\:baz)tt(RPAR()RPAR())' form does not need
+the colon to be escaped, since the var(spec)s have no colon-separated fields
+after the var(action).
+)
+enditemize()
 
 For example, the var(action) may be a simple function call:
 
@@ -3715,6 +3761,12 @@ The default var(matchspec) allows partial word completion after `tt(_)' and
 var(matchspec) is:
 example(tt(r:|[_-]=* r:|=*))
 )
+item(tt(-0))(
+When populating values of the `tt(opt_args)' associative array, don't
+backslash-escape colons and backslashes and use NUL rather than colon for
+joining multiple values. This option is described in more detail below, under
+the heading em(var(spec)s: actions).
+)
 enditem()
 
 em(var(spec)s: overview)
@@ -3887,6 +3939,7 @@ specific contexts: on the first call `tt(_arguments $global_options)' is
 used, and on subsequent calls `tt(_arguments !$^global_options)'.
 
 em(var(spec)s: actions)
+COMMENT(If you change this section title, change the references to it in running text.)
 
 In each of the forms above the var(action) determines how
 completions should be generated.  Except for the `tt(->)var(string)'
@@ -4008,9 +4061,21 @@ the normal arguments from the command line, i.e. the words from the
 command line after the command name excluding all options and their
 arguments.  Options are stored in the associative array
 `tt(opt_args)' with option names as keys and their arguments as
-the values.  For options that have more than one argument these are
-given as one string, separated by colons.  All colons and backslashes
-in the original arguments are preceded with backslashes.
+the values.  By default, all colons and backslashes in the value are escaped
+with backslashes, and if an option has multiple arguments (for example, when
+using an var(optspec) of the form `tt(*)var(optspec)'), they are joined with
+(unescaped) colons.  However, if the tt(-0) option was passed, no backslash
+escaping is performed, and multiple values are joined with NUL bytes.  For
+example, after `tt(zsh -o foo:foo -o bar:bar -o <TAB>)', the contents of
+`tt(opt_args)' would be
+
+example(typeset -A opt_args=( [-o]='foo\:foo:bar\:bar:' ))
+
+by default, and
+
+example(typeset -A opt_args=( [-o]=$'foo:foo\x00bar:bar\x00' ))
+
+if tt(_arguments) had been called with the tt(-0) option.
 
 The parameter `tt(context)' is set when returning to the calling function
 to perform an action of the form `tt(->)var(string)'.  It is set to an
@@ -4223,7 +4288,7 @@ The last two descriptions say what should be completed as
 arguments.  The first describes the first argument as a
 `var(postscript file)' and makes files ending in `tt(ps)' or `tt(eps)' 
 be completed.  The last description gives all other arguments the
-description `var(page numbers)' but does not offer completions.
+description `var(page number)' but does not offer completions.
 )
 findex(_cache_invalid)
 item(tt(_cache_invalid) var(cache_identifier))(
@@ -4349,6 +4414,15 @@ Include the leading underscore (`tt(_)') in the matches.
 )
 enditem()
 )
+findex(_default)
+item(tt(_default))(
+This function corresponds to the tt(-default-) special context which is
+applied where no completion is defined.  It is useful to call it under
+certain error conditions such as completion after an unrecognised
+subcommand.  This applies the concept of graceful degradation to the
+completion system, allowing it to fallback on basic completion of
+commonly useful things like filenames.
+)
 findex(_describe)
 redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ @ ))ifnztexi(          )))
 xitem(tt(_describe )[tt(-12JVx)] [ tt(-oO) | tt(-t) var(tag) ] var(descr) var(name1) [ var(name2) ] [ var(opt) ... ])
@@ -4422,8 +4496,22 @@ not contain an explanation string to be displayed above the matches.
 If tt(_description) is called with more than three arguments,
 the additional var(spec)s should be of the form `var(char)tt(:)var(str)'.
 These supply escape sequence replacements for the tt(format) style:
-every appearance of `tt(%)var(char)' will be
-replaced by var(string).
+every appearance of `tt(%)var(char)' will be replaced by var(string).
+If no additional var(spec)s are given but the description in var(descr)
+conforms to a common form then further escape sequences are set for
+elements of that description.  These elements correspond to a default
+value (`tt(%o)'), the units (`tt(%m)') range of acceptable values
+(`tt(%r)') and the remaining initial part of the description (`tt(%h)').
+The form the description takes consists of specifying the units and
+range in parentheses and the default value in square brackets, for
+example:
+
+example(_description times expl 'timeout (seconds) (0-60) [20]')
+
+It is possible to use tt(zformat) conditional expressions when styling
+these elements. So, for example, to add `tt(default:)' as a tag but only
+when there is a default value to show, the tt(format) style might
+include `tt(%(o.default: %o.))'.
 
 If the tt(-x) option is given, the description will be passed to
 tt(compadd) using the tt(-x) option instead of the default tt(-X).  This
@@ -4699,6 +4787,69 @@ checked.  If it is set completion is terminated at that point even if
 no matches have been found.  This is the same effect as in the
 tt(-first-) context.
 )
+findex(_numbers)
+item(tt(_numbers) [ var(option) ... ] [ var(description) ] [ var(suffix) ... ])(
+This can be used where a number is followed by a suffix to indicate the units.
+The unit suffixes are completed and can also be included in the description
+used when completion is invoked for the preceding number.
+
+In addition to common tt(compadd) options, tt(_numbers) accepts the following
+options:
+
+startitem()
+item(tt(-t) var(tag))(
+Specify a tag to use instead of the default of tt(numbers).
+)
+item(tt(-u) var(units))(
+Indicate the default units for the number, e.g. tt(bytes).
+)
+item(tt(-l) var(min))(
+Specify the lowest possible value for the number.
+)
+item(tt(-m) var(max))(
+Specify the highest possible value for the number.
+)
+item(tt(-d) var(default))(
+Specify the default value.
+)
+item(tt(-N))(
+Allow negative numbers.  This is implied if the range includes a negative.
+)
+item(tt(-f))(
+Allow decimal numbers.
+)
+enditem()
+
+Where a particular suffix represents the default units for a number, it
+should be prefixed with a colon.  Additionally, suffixes can be followed
+by a colon and a description.  So for example, the following allows the
+age of something to be specified, either in seconds or with an optional
+suffix with a longer unit of time:
+
+example(_numbers -u seconds age :s:seconds m:minutes h:hours d:days)
+
+It is typically helpful for units to be presented in order of magnitude
+when completed.  To facilitate this, the order in which they are given
+is preserved.
+
+When the tt(format) style is looked up with the tt(descriptions) tag or
+the tag specified with tt(-t), the list of suffixes is available as a
+`tt(%x)' escape sequence. This is in addition to the usual sequences
+documented under the tt(format) style. The form this list takes can also
+be configured. To this end, the tt(format) style is first looked up with
+the tag tt(unit-suffixes). The retrieved format is applied to each
+suffix in turn and the results are then concatenated to form the
+completed list. For the tt(unit-suffixes) format, `tt(%x)' expands to
+the individual suffix and `tt(%X)' to its description. tt(%d)' indicates
+a default suffix and can be used in a condition. The index and reverse
+index are set in `tt(%i)' and `tt(%r)' respectively and are useful for
+text included only with the first and last suffixes in the list. So for
+example, the following joins the suffixes together as a comma-separated
+list:
+
+example(zstyle ':completion:*:unit-suffixes' format '%x%(r::,)')
+)
+
 findex(_options)
 item(tt(_options))(
 This can be used to complete the names of shell options.  It provides a
@@ -5244,7 +5395,11 @@ matches with the given description:
 
 example(local expl
 _wanted tag expl 'description' \ 
-    compadd matches...)
+    compadd -- var(match1) var(match2)...)
+
+See also the use of tt(_wanted) in the example function in
+ifzman(the subsection `Dynamic named directories' in zmanref(zshexpn))\
+ifnzman(noderef(Dynamic named directories)).
 
 Note that, as for tt(_requested), the var(command) must be able to
 accept options to be passed down to tt(compadd).
@@ -5284,7 +5439,6 @@ in the tt(_comp_caller_options) associative array. Option names, spelled
 in lowercase without underscores, are mapped to one or other of the
 strings `tt(on)' and `tt(off)'.
 )
-
 item(tt(_comp_priv_prefix))(
 Completion functions such as tt(_sudo) can set the tt(_comp_priv_prefix)
 array to a command prefix that may then be used by tt(_call_program) to
@@ -5292,6 +5446,8 @@ match the privileges when calling programs to generate matches.
 )
 enditem()
 
+vindex(compprefuncs, use of)
+vindex(comppostfuncs, use of)
 Two more features are offered by the tt(_main_complete) function.  The
 arrays tt(compprefuncs) and tt(comppostfuncs) may contain
 names of functions that are to be called immediately before or after
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 0b98d07b2..d32a0702f 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -39,7 +39,7 @@ using the tt(bindkey) builtin command defined in the tt(zsh/zle) module
 ifzman(see zmanref(zshzle))\
 ifnzman(noderef(Zsh Line Editor))\
 ), typing that key will call the shell function `tt(completer)'. This
-function is responsible for generating the possible matches using the
+function is responsible for generating completion matches using the
 builtins described below.  As with other ZLE widgets, the function is
 called with its standard input closed.
 
@@ -213,7 +213,7 @@ The string of an exact match if one was found, otherwise unset.
 )
 vindex(ignored, compstate)
 item(tt(ignored))(
-The number of words that were ignored because they matched one of the
+The number of completions that were ignored because they matched one of the
 patterns given with the tt(-F) option to the tt(compadd) builtin
 command.
 )
@@ -309,8 +309,7 @@ will be used in the same way as the value of tt(LISTMAX).
 )
 vindex(nmatches, compstate)
 item(tt(nmatches))(
-The number of matches generated and accepted by the completion code so
-far.
+The number of matches added by the completion code so far.
 )
 vindex(old_insert, compstate)
 item(tt(old_insert))(
@@ -346,7 +345,8 @@ value of a parameter assignment.
 vindex(pattern_insert, compstate)
 item(tt(pattern_insert))(
 Normally this is set to tt(menu), which specifies that menu completion will
-be used whenever a set of matches was generated using pattern matching.  If
+be used whenever a set of matches was generated using tt(pattern_match)
+(see below).  If
 it is set to any other non-empty string by the user and menu completion is
 not selected by other option settings, the code will instead insert any
 common prefix for the generated matches as with normal completion.
@@ -362,7 +362,7 @@ command line will be treated as patterns; if it is `tt(*)', then
 additionally a wildcard `tt(*)' is assumed at the cursor position; if
 it is empty or unset, metacharacters will be treated literally.
 
-Note that the matcher specifications given to the tt(compadd) builtin
+Note that the match specifications given to the tt(compadd) builtin
 command are not used if this is set to a non-empty string.
 )
 vindex(quote, compstate)
@@ -456,17 +456,16 @@ xitem(SPACES()[tt(-V) var(group-name) ] [ tt(-o) [ var(order) ] ])
 xitem(SPACES()[tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ])
 xitem(SPACES()[tt(-D) var(array) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ])
 xitem(SPACES()[tt(-E) var(number) ])
-item(SPACES()[tt(-M) var(match-spec) ] [ tt(-)tt(-) ] [ var(words) ... ])(
+item(SPACES()[tt(-M) var(match-spec) ] [ tt(-)tt(-) ] [ var(completions) ... ])(
 
 This builtin command can be used to add matches directly and control
 all the information the completion code stores with each possible
-match. The return status is zero if at least one match was added and
+completion. The return status is zero if at least one match was added and
 non-zero if no matches were added.
 
-The completion code breaks the string to complete into seven fields in
-the order: 
+The completion code breaks each match into seven fields in the order:
 
-indent(var(<ipre><apre><hpre><word><hsuf><asuf><isuf>))
+indent(var(<ipre><apre><hpre><body><hsuf><asuf><isuf>))
 
 The first field
 is an ignored prefix taken from the command line, the contents of the
@@ -474,12 +473,12 @@ tt(IPREFIX) parameter plus the string given with the tt(-i)
 option. With the tt(-U) option, only the string from the tt(-i)
 option is used. The field var(<apre>) is an optional prefix string
 given with the tt(-P) option.  The var(<hpre>) field is a string
-that is considered part of the match but that should not be shown when 
+that is considered part of the match but that should not be shown when
 listing completions, given with the tt(-p) option; for example,
 functions that do filename generation might specify
-a common path prefix this way.  var(<word>) is the part of the match that
-should appear in the list of completions, i.e. one of the var(words) given
-at the end of the tt(compadd) command line. The suffixes var(<hsuf>),
+a common path prefix this way.  var(<body>) is the part of the match that
+should appear in the list of matches shown to the user.
+The suffixes var(<hsuf>),
 var(<asuf>) and var(<isuf>) correspond to the prefixes var(<hpre>),
 var(<apre>) and var(<ipre>) and are given by the options tt(-s), tt(-S) and
 tt(-I), respectively.
@@ -488,52 +487,52 @@ The supported flags are:
 
 startitem()
 item(tt(-P) var(prefix))(
-This gives a string to be inserted before the given var(words).  The
+This gives a string to be inserted before each match.  The
 string given is not considered as part of the match and any shell
 metacharacters in it will not be quoted when the string is inserted.
 )
 item(tt(-S) var(suffix))(
-Like tt(-P), but gives a string to be inserted after the match.
+Like tt(-P), but gives a string to be inserted after each match.
 )
 item(tt(-p) var(hidden-prefix))(
-This gives a string that should be inserted into the command line before the
+This gives a string that should be inserted before each
 match but that should not appear in the list of matches. Unless the
 tt(-U) option is given, this string must be matched as part of the string
 on the command line.
 )
 item(tt(-s) var(hidden-suffix))(
-Like `tt(-p)', but gives a string to insert after the match.
+Like `tt(-p)', but gives a string to insert after each match.
 )
 item(tt(-i) var(ignored-prefix))(
-This gives a string to insert into the command line just before any
+This gives a string to insert just before any
 string given with the `tt(-P)' option.  Without `tt(-P)' the string is
-inserted before the string given with `tt(-p)' or directly before the
+inserted before the string given with `tt(-p)' or directly before each
 match.
 )
 item(tt(-I) var(ignored-suffix))(
 Like tt(-i), but gives an ignored suffix.
 )
 item(tt(-a))(
-With this flag the var(words) are taken as names of arrays and the
-possible matches are their values.  If only some elements of the
-arrays are needed, the var(words) may also contain subscripts, as in
+With this flag the var(completions) are taken as names of arrays and the
+actual completions are their values.  If only some elements of the
+arrays are needed, the var(completions) may also contain subscripts, as in
 `tt(foo[2,-1])'.
 )
 item(tt(-k))(
-With this flag the var(words) are taken as names of associative arrays
-and the possible matches are their keys.  As for tt(-a), the
+With this flag the var(completions) are taken as names of associative arrays
+and the actual completions are their keys.  As for tt(-a), the
 var(words) may also contain subscripts, as in `tt(foo[(R)*bar*])'.
 )
 item(tt(-d) var(array))(
-This adds per-match display strings. The var(array) should contain one 
-element per var(word) given. The completion code will then display the 
-first element instead of the first var(word), and so on. The
+This adds per-completion display strings. The var(array) should contain one
+element per var(completion) given. The completion code will then display the
+first element instead of the first var(completion), and so on. The
 var(array) may be given as the name of an array parameter or directly
 as a space-separated list of words in parentheses.
 
-If there are fewer display strings than var(words), the leftover
-var(words) will be displayed unchanged and if there are more display
-strings than var(words), the leftover display strings will be silently
+If there are fewer display strings than var(completions), the leftover
+var(completions) will be displayed unchanged and if there are more display
+strings than var(completions), the leftover display strings will be silently
 ignored.
 )
 item(tt(-l))(
@@ -556,7 +555,8 @@ by the tt(-d) option). This is the default if `tt(-o)' is specified but
 the var(order) argument is omitted.
 )
 item(tt(nosort))(
-This specifies that the matches are pre-sorted and their order should be
+This specifies that the var(completions)
+are pre-sorted and their order should be
 preserved.  This value only makes sense alone and cannot be combined with any
 others.
 )
@@ -570,7 +570,7 @@ Arrange the matches backwards by reversing the sort ordering.
 enditem()
 )
 item(tt(-J) var(group-name))(
-Gives the name of the group of matches the words should be stored in.
+Gives the name of the group that the matches should be stored in.
 )
 item(tt(-V) var(group-name))(
 Like tt(-J) but naming an unsorted group. This option is identical to
@@ -616,13 +616,13 @@ produce unexpected results. If arbitrary text is to be passed in a
 description, it can be escaped using e.g. tt(${my_str//\%/%%}).
 )
 item(tt(-x) var(message))(
-Like tt(-X), but the var(message) will be printed even if there are no 
+Like tt(-X), but the var(message) will be printed even if there are no
 matches in the group.
 )
 item(tt(-q))(
-The suffix given with tt(-S) will be automatically removed if 
+The suffix given with tt(-S) will be automatically removed if
 the next character typed is a blank or does not insert anything, or if
-the suffix consists of only one character and the next character typed 
+the suffix consists of only one character and the next character typed
 is the same character.
 )
 item(tt(-r) var(remove-chars))(
@@ -644,8 +644,8 @@ automatically added space will be removed when one of the characters in the
 list is typed.
 )
 item(tt(-R) var(remove-func))(
-This is another form of the tt(-r) option. When a suffix 
-has been inserted and the completion accepted, the function
+This is another form of the tt(-r) option. When a match
+has been accepted and a suffix has been inserted, the function
 var(remove-func) will be called after the next character typed.  It is
 passed the length of the suffix as an argument and can use the special
 parameters available in ordinary (non-completion) zle widgets (see
@@ -654,7 +654,7 @@ ifnzman(noderef(Zsh Line Editor))\
 ) to analyse and modify the command line.
 )
 item(tt(-f))(
-If this flag is given, all of the matches built from var(words) are
+If this flag is given, all of the matches built from the var(completions) are
 marked as being the names of files.  They are not required to be actual
 filenames, but if they are, and the option tt(LIST_TYPES) is set, the
 characters describing the types of the files in the completion lists will
@@ -668,15 +668,14 @@ the tt(AUTO_PARAM_SLASH) and tt(AUTO_PARAM_KEYS) options be used for
 the matches.
 )
 item(tt(-W) var(file-prefix))(
-This string is a pathname that will be
-prepended to each of the matches formed by the given var(words) together 
+This string is a pathname that will be prepended to each match together
 with any prefix specified by the tt(-p) option to form a complete filename
 for testing.  Hence it is only useful if combined with the tt(-f) flag, as
 the tests will not otherwise be performed.
 )
 item(tt(-F) var(array))(
-Specifies an array containing patterns. Words matching one of these
-patterns are ignored, i.e. not considered to be possible matches.
+Specifies an array containing patterns.  var(completions) that match one of
+these patterns are ignored, that is, not considered to be matches.
 
 The var(array) may be the name of an array parameter or a list of
 literal patterns enclosed in parentheses and quoted, as in `tt(-F "(*?.o
@@ -684,8 +683,8 @@ literal patterns enclosed in parentheses and quoted, as in `tt(-F "(*?.o
 taken as the patterns.
 )
 item(tt(-Q))(
-This flag instructs the completion 
-code not to quote any metacharacters in the words when inserting them
+This flag instructs the completion
+code not to quote any metacharacters in the matches when inserting them
 into the command line.
 )
 item(tt(-M) var(match-spec))(
@@ -696,47 +695,50 @@ between them to form the specification string to use.
 Note that they will only be used if the tt(-U) option is not given.
 )
 item(tt(-n))(
-Specifies that the words added are to be used as possible
-matches, but are not to appear in the completion listing.
+Specifies that matching var(completions) are to be added to the set of
+matches, but are not to be listed to the user.
 )
 item(tt(-U))(
-If this flag is given, all words given will be accepted and no matching
+If this flag is given, all var(completions) are added
+to the set of matches and no matching
 will be done by the completion code. Normally this is used in
 functions that do the matching themselves.
 )
 item(tt(-O) var(array))(
-If this option is given, the var(words) are em(not) added to the set of
-possible completions.  Instead, matching is done as usual and all of the
-var(words) given as arguments that match the string on the command line
+If this option is given, the var(completions) are em(not) added to the set of
+matches.  Instead, matching is done as usual and all of the
+var(completions) that match
 will be stored in the array parameter whose name is given as var(array).
 )
 item(tt(-A) var(array))(
-As the tt(-O) option, except that instead of those of the var(words) which
+As the tt(-O) option, except that instead of those of the var(completions)
+which
 match being stored in var(array), the strings generated internally by the
-completion code are stored. For example,
-with a matching specification of `tt(-M "L:|no=")', the string `tt(nof)'
-on the command line and the string `tt(foo)' as one of the var(words), this
+completion code are stored.  For example,
+with a match specification of `tt(-M "L:|no=")', a current word of `tt(nof)'
+and var(completions) of `tt(foo)', this
 option stores the string `tt(nofoo)' in the array, whereas the tt(-O)
 option stores the `tt(foo)' originally given.
 )
 item(tt(-D) var(array))(
-As with tt(-O), the var(words) are not added to the set of possible
-completions.  Instead, the completion code tests whether each var(word) 
-in turn matches what is on the line.  If the var(n)th var(word) does not
+As with tt(-O), the var(completions) are not added to the set of matches.
+Instead, whenever the var(n)th var(completion) does not
 match, the var(n)th element of the var(array) is removed.  Elements
-for which the corresponding var(word) is matched are retained.
+for which the corresponding var(completion) matches are retained.
+This option can be used more than once to remove elements from multiple
+arrays.
 )
 item(tt(-C))(
 This option adds a special match which expands to all other matches
 when inserted into the line, even those that are added after this
 option is used.  Together with the tt(-d) option it is possible to
-specify a string that should be displayed in the list for this special 
-match.  If no string is given, it will be shown as a string containing 
-the strings that would be inserted for the other matches, truncated to 
+specify a string that should be displayed in the list for this special
+match.  If no string is given, it will be shown as a string containing
+the strings that would be inserted for the other matches, truncated to
 the width of the screen.
 )
 item(tt(-E) var(number))(
-This option adds var(number) empty matches after the var(words) have
+This option adds var(number) empty matches after matching var(completions) have
 been added.  An empty match takes up space in completion listings but
 will never be inserted in the line and can't be selected with menu
 completion or menu selection.  This makes empty matches only useful to
@@ -751,7 +753,7 @@ added.
 xitem(tt(-))
 item(tt(-)tt(-))(
 This flag ends the list of flags and options. All arguments after it
-will be taken as the words to use as matches even if they begin with
+will be taken as the var(completions) even if they begin with
 hyphens.
 )
 enditem()
@@ -788,7 +790,7 @@ Without the optional var(number), the longest match is taken, but
 if var(number) is given, anything up to the var(number)th match is
 moved.  If the var(number) is negative, the var(number)th longest
 match is moved. For example, if tt(PREFIX) contains the string
-`tt(a=b=c)', then tt(compset -P '*\=') will move the string `tt(a=b=)' 
+`tt(a=b=c)', then tt(compset -P '*\=') will move the string `tt(a=b=)'
 into the tt(IPREFIX) parameter, but tt(compset -P 1 '*\=') will move only
 the string `tt(a=)'.
 )
@@ -801,7 +803,7 @@ As tt(-P), but match the last portion of tt(SUFFIX) and transfer the
 matched portion to the front of the value of tt(ISUFFIX).
 )
 item(tt(-n) var(begin) [ var(end) ])(
-If the current word position as specified by the parameter tt(CURRENT) 
+If the current word position as specified by the parameter tt(CURRENT)
 is greater than or equal to var(begin), anything up to the
 var(begin)th word is removed from the tt(words) array and the value
 of the parameter tt(CURRENT) is decremented by var(begin).
@@ -824,7 +826,7 @@ point to the same word in the changed array.
 If the optional pattern var(end-pat) is also given, and there is an
 element in the tt(words) array matching this pattern, the parameters
 are modified only if the index of this word is higher than the one
-given by the tt(CURRENT) parameter (so that the matching word has 
+given by the tt(CURRENT) parameter (so that the matching word has
 to be after the cursor). In this case, the words starting with the one
 matching tt(end-pat) are also removed from the tt(words)
 array. If tt(words) contains no word matching var(end-pat), the
@@ -833,7 +835,7 @@ testing and modification is performed as if it were not given.
 item(tt(-q))(
 The word
 currently being completed is split on spaces into separate words,
-respecting the usual shell quoting conventions.  The 
+respecting the usual shell quoting conventions.  The
 resulting words are stored in the tt(words) array, and tt(CURRENT),
 tt(PREFIX), tt(SUFFIX), tt(QIPREFIX), and tt(QISUFFIX) are modified to
 reflect the word part that is completed.
@@ -885,7 +887,7 @@ item(tt(-suffix) [ var(number) ] var(pattern))(
 true if the test for the tt(-S) option of tt(compset) would succeed.
 )
 item(tt(-after) var(beg-pat))(
-true if the test of the tt(-N) option with only the var(beg-pat) given 
+true if the test of the tt(-N) option with only the var(beg-pat) given
 would succeed.
 )
 item(tt(-between) var(beg-pat end-pat))(
@@ -896,270 +898,286 @@ enditem()
 texinode(Completion Matching Control)(Completion Widget Example)(Completion Condition Codes)(Completion Widgets)
 sect(Completion Matching Control)
 
-It is possible by use of the
-tt(-M) option of the tt(compadd) builtin command to specify how the
-characters in the string to be completed (referred to here as the
-command line) map onto the characters in the list of matches produced by
-the completion code (referred to here as the trial completions). Note
-that this is not used if the command line contains a glob pattern and
-the tt(GLOB_COMPLETE) option is set or the tt(pattern_match) of the
-tt(compstate) special association is set to a non-empty string.
+When the user invokes completion, the current em(word) on the command line
+(that is, the word the cursor is currently on) is used to generate a em(match
+pattern).  Only those em(completions) that match the pattern are offered to the
+user as em(matches).
 
-The var(match-spec) given as the argument to the tt(-M) option (see
+The default match pattern is generated from the current word by either
+
+startitemize()
+itemiz(\
+appending a `tt(*)' (matching any number of characters in a completion)
+em(or,)\
+)
+itemiz(\
+if the shell option tt(COMPLETE_IN_WORD) is set, inserting a `tt(*)' at the
+cursor position.\
+)
+enditemize()
+
+This narrow pattern can be broadened selectively by passing a em(match
+specification) to the tt(compadd) builtin command through its tt(-M) option
+(see
 ifzman(`Completion Builtin Commands' above)\
 ifnzman(noderef(Completion Builtin Commands))\
-) consists of one or more matching descriptions separated by
-whitespace.  Each description consists of a letter followed by a colon
-and then the patterns describing which character sequences on the line match
-which character sequences in the trial completion.  Any sequence of
-characters not handled in this fashion must match exactly, as usual.
-
-The forms of var(match-spec) understood are as follows. In each case, the
-form with an upper case initial character retains the string already
-typed on the command line as the final result of completion, while with
-a lower case initial character the string on the command line is changed
-into the corresponding part of the trial completion.
+).  A match specification consists of one or more var(matchers) separated by
+whitespace.  Matchers in a match specification are applied one at a time, from
+left to right.  Once all matchers have been applied, completions are compared
+to the final match pattern and non-matching ones are discarded.
+
+startitemize()
+itemiz(\
+Note that the tt(-M) option is ignored if the current word contains a glob
+pattern and the shell option tt(GLOB_COMPLETE) is set or if the
+tt(pattern_match) key of the special associative array tt(compstate) is set to
+a non-empty value (see
+ifzman(`Completion Special Parameters' above)\
+ifnzman(noderef(Completion Special Parameters))\
+).\
+)
+itemiz(\
+Users of the \
+ifzman(completion system (see zmanref(zshcompsys))) \
+ifnzman(noderef(Completion System)) \
+should generally not use the tt(-M) option directly, but rather use the
+tt(matcher-list) and tt(matcher) styles (see the subsection em(Standard Styles)
+in
+ifzman(\
+the documentation for COMPLETION SYSTEM CONFIGURATION in zmanref(zshcompsys))\
+ifnzman(noderef(Completion System Configuration))\
+).\
+)
+enditemize()
+
+Each matcher consists of
+
+startitemize()
+itemiz(a case-sensitive letter)
+itemiz(a `tt(:)',)
+itemiz(one or more patterns separated by pipes (`tt(|)'),)
+itemiz(an equals sign (`tt(=)'), and)
+itemiz(another pattern.)
+enditemize()
+
+The patterns before the `tt(=)' are used to match substrings of the current
+word.  For each matched substring, the corresponding part of the match pattern
+is broadened with the pattern after the `tt(=)', by means of a logical tt(OR).
+
+Each pattern in a matcher cosists of either
+
+startitemize()
+itemiz(the empty string or)
+itemiz(a sequence of
+
+startitemize()
+itemiz(literal characters (which may be quoted with a `tt(\)'),)
+itemiz(question marks (`tt(?)'),)
+itemiz(\
+bracket expressions (`tt([...])'; see the subsection em(Glob Operators) in
+ifnzman(noderef(Filename Generation))\
+ifzman(the documentation for GLOB OPERATORS in zmanref(zshexpn))\
+), and/or\
+)
+itemiz(brace expressions (see below).)
+enditemize()
+)
+enditemize()
+
+Other shell patterns are not allowed.
+
+A brace expression, like a bracket expression, consists of a list of
+
+startitemize()
+itemiz(literal characters,)
+itemiz(ranges (`tt(0-9)'), and/or)
+itemiz(character classes (`tt([:)var(name)tt(:])').)
+enditemize()
+
+However, they differ from each other as follows:
+
+startitemize()
+itemiz(\
+A brace expression is delimited by a pair of braces (`tt({...})').\
+)
+itemiz(\
+Brace expressions do not support negations.  That is, an initial
+`tt(!)' or `tt(^)' has no special meaning and will be interpreted as a literal
+character.\
+)
+itemiz(\
+When a character in the current word matches the var(n)th pattern in a brace
+expression, the corresponding part of the match pattern is broadened only with
+the var(n)th pattern of the brace expression on the other side of the `tt(=)',
+if there is one; if there is no brace expression on the other side, then this
+pattern is the empty string.  However, if either brace expression has more
+elements than the other, then the excess entries are simply ignored.  When
+comparing indexes, each literal character or character class counts as one
+element, but each range is instead expanded to the full list of literal
+characters it represents.  Additionally, if on em(both) sides of the
+`tt(=)', the var(n)th pattern is `tt([:upper:])' or `tt([:lower:])', then these
+are expanded as ranges, too.\
+)
+enditemize()
+
+Note that, although the matching system does not yet handle multibyte
+characters, this is likely to be a future extension.  Hence, using
+`tt([:upper:])' and `tt([:lower:])' is recommended over
+`tt(A-Z)' and `tt(a-z)'.
+
+Below are the different forms of matchers supported.  Each em(uppercase) form
+behaves exactly like its lowercase counterpart, but adds an additional step
+em(after) the match pattern has filtered out non-matching completions:  Each of
+a match's substrings that was matched by a subpattern from an uppercase matcher
+is replaced with the corresponding substring of the current word.  However,
+patterns from em(lowercase) matchers have higher weight:  If a substring of the
+current word was matched by patterns from both a lowercase and an uppercase
+matcher, then the lowercase matcher's pattern wins and the corresponding part
+of the match is not modified.
+
+Unless indicated otherwise, each example listed assumes tt(COMPLETE_IN_WORD) to
+be unset (as it is by default).
 
 startitem()
-xitem(tt(m:)var(lpat)tt(=)var(tpat))
-item(tt(M:)var(lpat)tt(=)var(tpat))(
-Here, var(lpat) is a pattern that matches on the command line,
-corresponding to var(tpat) which matches in the trial completion.
-)
-xitem(tt(l:)var(lanchor)tt(|)var(lpat)tt(=)var(tpat))
-xitem(tt(L:)var(lanchor)tt(|)var(lpat)tt(=)var(tpat))
-xitem(tt(l:)var(lanchor)tt(||)var(ranchor)tt(=)var(tpat))
-xitem(tt(L:)var(lanchor)tt(||)var(ranchor)tt(=)var(tpat))
-xitem(tt(b:)var(lpat)tt(=)var(tpat))
-item(tt(B:)var(lpat)tt(=)var(tpat))(
-These letters are for patterns that are anchored by another pattern on
-the left side. Matching for var(lpat) and var(tpat) is as for tt(m) and
-tt(M), but the pattern var(lpat) matched on the command line must be
-preceded by the pattern var(lanchor).  The var(lanchor) can be blank to
-anchor the match to the start of the command line string; otherwise the
-anchor can occur anywhere, but must match in both the command line and
-trial completion strings.
-
-If no var(lpat) is given but a var(ranchor) is, this matches the gap
-between substrings matched by var(lanchor) and var(ranchor). Unlike
-var(lanchor), the var(ranchor) only needs to match the trial
-completion string.
-
-The tt(b) and tt(B) forms are similar to tt(l) and tt(L) with an empty 
-anchor, but need to match only the beginning of the word on the command line
-or trial completion, respectively.
-)
-xitem(tt(r:)var(lpat)tt(|)var(ranchor)tt(=)var(tpat))
-xitem(tt(R:)var(lpat)tt(|)var(ranchor)tt(=)var(tpat))
-xitem(tt(r:)var(lanchor)tt(||)var(ranchor)tt(=)var(tpat))
-xitem(tt(R:)var(lanchor)tt(||)var(ranchor)tt(=)var(tpat))
-xitem(tt(e:)var(lpat)tt(=)var(tpat))
-item(tt(E:)var(lpat)tt(=)var(tpat))(
-As tt(l), tt(L), tt(b) and tt(B), with the difference that the command
-line and trial completion patterns are anchored on the right side.
-Here an empty var(ranchor) and the tt(e) and tt(E) forms force the
-match to the end of the command line or trial completion string.
+xitem(tt(m:)var(word-pat)tt(=)var(match-pat))
+item(tt(M:)var(word-pat)tt(=)var(match-pat))(
+
+For each substring of the current word that matches var(word-pat), broaden the
+corresponding part of the match pattern to additionally match var(match-pat).
+
+startitem()
+item(Examples:)(
+
+tt(m:{[:lower:]}={[:upper:]}) lets any lower case character in the current word
+be completed to itself or its uppercase counterpart.  So, the completions
+`tt(foo)', `tt(FOO)' and `tt(Foo)' will are be considered matches for the word
+`tt(fo)'.
+
+tt(M:_=) inserts every underscore from the current word into each match, in the
+same relative position, determined by matching the substrings around it.  So,
+given a completion `tt(foo)', the word `tt(f_o)' will be completed to the match
+`tt(f_oo)', even though the latter was not present as a completion.
 )
-item(tt(x:))(
-This form is used to mark the end of matching specifications:
-subsequent specifications are ignored. In a single standalone list
-of specifications this has no use but where matching specifications
-are accumulated, such as from nested function calls, it can allow one
-function to override another.
+enditem()
+)
+xitem(tt(b:)var(word-pat)tt(=)var(match-pat))
+xitem(tt(B:)var(word-pat)tt(=)var(match-pat))
+xitem(tt(e:)var(word-pat)tt(=)var(match-pat))
+item(tt(E:)var(word-pat)tt(=)var(match-pat))(
+
+For each consecutive substring at the tt(b:)eginning or tt(e:)nd of the current
+word that matches var(word-pat), broaden the corresponding part of the match
+pattern to additionally match var(match-pat).
+
+startitem()
+item(Examples:)(
+
+`tt(b:-=+)' lets any number of minuses at the start of the current word be
+completed to a minus or a plus.
+
+`tt(B:0=)' adds all zeroes at the beginning of the current word to the
+beginning of each match.
 )
 enditem()
+)
+xitem(tt(l:)tt(|)var(word-pat)tt(=)var(match-pat))
+xitem(tt(L:)tt(|)var(word-pat)tt(=)var(match-pat))
+xitem(tt(R:)var(word-pat)tt(|)tt(=)var(match-pat))
+item(tt(r:)var(word-pat)tt(|)tt(=)var(match-pat))(
 
-Each var(lpat), var(tpat) or var(anchor) is either an empty string or
-consists of a sequence of literal characters (which may be quoted with a
-backslash), question marks, character classes, and correspondence
-classes; ordinary shell patterns are not used.  Literal characters match
-only themselves, question marks match any character, and character
-classes are formed as for globbing and match any character in the given
-set.
-
-Correspondence classes are defined like character classes, but with two
-differences: they are delimited by a pair of braces, and negated classes
-are not allowed, so the characters tt(!) and tt(^) have no special
-meaning directly after the opening brace.  They indicate that a range of
-characters on the line match a range of characters in the trial
-completion, but (unlike ordinary character classes) paired according to
-the corresponding position in the sequence.  For example, to make any
-ASCII lower case letter on the line match the corresponding upper case
-letter in the trial completion, you can use `tt(m:{a-z}={A-Z})'
-(however, see below for the recommended form for this).  More
-than one pair of classes can occur, in which case the first class before
-the tt(=) corresponds to the first after it, and so on.  If one side has
-more such classes than the other side, the superfluous classes behave
-like normal character classes.  In anchor patterns correspondence classes
-also behave like normal character classes.
-
-The standard `tt([:)var(name)tt(:])' forms described for standard shell
-patterns (see
-ifnzman(noderef(Filename Generation))\
-ifzman(the section FILENAME GENERATION in zmanref(zshexpn)))
-may appear in correspondence classes as well as normal character
-classes.  The only special behaviour in correspondence classes is if
-the form on the left and the form on the right are each one of
-tt([:upper:]), tt([:lower:]).  In these cases the
-character in the word and the character on the line must be the same up
-to a difference in case.  Hence to make any lower case character on the
-line match the corresponding upper case character in the trial
-completion you can use `tt(m:{[:lower:]}={[:upper:]})'.  Although the
-matching system does not yet handle multibyte characters, this is likely
-to be a future extension, at which point this syntax will handle
-arbitrary alphabets; hence this form, rather than the use of explicit
-ranges, is the recommended form.  In other cases
-`tt([:)var(name)tt(:])' forms are allowed.  If the two forms on the left
-and right are the same, the characters must match exactly.  In remaining
-cases, the corresponding tests are applied to both characters, but they
-are not otherwise constrained; any matching character in one set goes
-with any matching character in the other set:  this is equivalent to the
-behaviour of ordinary character classes.
-
-The pattern var(tpat) may also be one or two stars, `tt(*)' or
-`tt(**)'. This means that the pattern on the command line can match
-any number of characters in the trial completion. In this case the
-pattern must be anchored (on either side); in the case of a single
-star, the var(anchor) then determines how much of the trial completion
-is to be included DASH()- only the characters up to the next appearance of
-the anchor will be matched. With two stars, substrings matched by the
-anchor can be matched, too.
-
-Examples:
-
-The keys of the tt(options) association defined by the tt(parameter)
-module are the option names in all-lower-case form, without
-underscores, and without the optional tt(no) at the beginning even
-though the builtins tt(setopt) and tt(unsetopt) understand option names
-with upper case letters, underscores, and the optional tt(no).  The
-following alters the matching rules so that the prefix tt(no) and any
-underscore are ignored when trying to match the trial completions
-generated and upper case letters on the line match the corresponding
-lower case letters in the words:
-
-example(compadd -M 'L:|[nN][oO]= M:_= M:{[:upper:]}={[:lower:]}' - \ 
-  ${(k)options} )
-
-The first part says that the pattern `tt([nN][oO])' at the beginning
-(the empty anchor before the pipe symbol) of the string on the
-line matches the empty string in the list of words generated by
-completion, so it will be ignored if present. The second part does the
-same for an underscore anywhere in the command line string, and the
-third part uses correspondence classes so that any
-upper case letter on the line matches the corresponding lower case
-letter in the word. The use of the upper case forms of the
-specification characters (tt(L) and tt(M)) guarantees that what has
-already been typed on the command line (in particular the prefix
-tt(no)) will not be deleted.
-
-Note that the use of tt(L) in the first part means that it matches
-only when at the beginning of both the command line string and the
-trial completion. I.e., the string `tt(_NO_f)' would not be
-completed to `tt(_NO_foo)', nor would `tt(NONO_f)' be completed to
-`tt(NONO_foo)' because of the leading underscore or the second
-`tt(NO)' on the line which makes the pattern fail even though they are 
-otherwise ignored. To fix this, one would use `tt(B:[nN][oO]=)'
-instead of the first part. As described above, this matches at the
-beginning of the trial completion, independent of other characters or
-substrings at the beginning of the command line word which are ignored
-by the same or other var(match-spec)s.
-
-The second example makes completion case insensitive.  This is just
-the same as in the option example, except here we wish to retain the
-characters in the list of completions:
-
-example(compadd -M 'm:{[:lower:]}={[:upper:]}' ... )
-
-This makes lower case letters match their upper case counterparts.
-To make upper case letters match the lower case forms as well:
-
-example(compadd -M 'm:{[:lower:][:upper:]}={[:upper:][:lower:]}' ... )
-
-A nice example for the use of tt(*) patterns is partial word
-completion. Sometimes you would like to make strings like `tt(c.s.u)'
-complete to strings like `tt(comp.source.unix)', i.e. the word on the
-command line consists of multiple parts, separated by a dot in this
-example, where each part should be completed separately DASH()- note,
-however, that the case where each part of the word, i.e. `tt(comp)',
-`tt(source)' and `tt(unix)' in this example, is to be completed from
-separate sets of matches
-is a different problem to be solved by the implementation of the
-completion widget.  The example can be handled by:
-
-example(compadd -M 'r:|.=* r:|=*' \ 
-  - comp.sources.unix comp.sources.misc ...)
-
-The first specification says that var(lpat) is the empty string, while
-var(anchor) is a dot; var(tpat) is tt(*), so this can match anything
-except for the `tt(.)' from the anchor in
-the trial completion word.  So in `tt(c.s.u)', the matcher sees `tt(c)',
-followed by the empty string, followed by the anchor `tt(.)', and
-likewise for the second dot, and replaces the empty strings before the
-anchors, giving `tt(c)[tt(omp)]tt(.s)[tt(ources)]tt(.u)[tt(nix)]', where
-the last part of the completion is just as normal.
-
-With the pattern shown above, the string `tt(c.u)' could not be
-completed to `tt(comp.sources.unix)' because the single star means
-that no dot (matched by the anchor) can be skipped. By using two stars 
-as in `tt(r:|.=**)', however, `tt(c.u)' could be completed to
-`tt(comp.sources.unix)'. This also shows that in some cases,
-especially if the anchor is a real pattern, like a character class,
-the form with two stars may result in more matches than one would like.
-
-The second specification is needed to make this work when the cursor is
-in the middle of the string on the command line and the option
-tt(COMPLETE_IN_WORD) is set. In this case the completion code would
-normally try to match trial completions that end with the string as
-typed so far, i.e. it will only insert new characters at the cursor
-position rather than at the end.  However in our example we would like
-the code to recognise matches which contain extra characters after the
-string on the line (the `tt(nix)' in the example).  Hence we say that the
-empty string at the end of the string on the line matches any characters
-at the end of the trial completion.
-
-More generally, the specification
-
-example(compadd -M 'r:|[.,_-]=* r:|=*' ... )
-
-allows one to complete words with abbreviations before any of the
-characters in the square brackets.  For example, to
-complete tt(veryverylongfile.c) rather than tt(veryverylongheader.h)
-with the above in effect, you can just type tt(very.c) before attempting
-completion.
-
-The specifications with both a left and a right anchor are useful to
-complete partial words whose parts are not separated by some
-special character. For example, in some places strings have to be
-completed that are formed `tt(LikeThis)' (i.e. the separate parts are
-determined by a leading upper case letter) or maybe one has to
-complete strings with trailing numbers. Here one could use the simple
-form with only one anchor as in:
-
-example(compadd -M 'r:|[[:upper:]0-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234)
-
-But with this, the string `tt(H)' would neither complete to `tt(FooHoo)'
-nor to `tt(LikeTHIS)' because in each case there is an upper case
-letter before the `tt(H)' and that is matched by the anchor. Likewise, 
-a `tt(2)' would not be completed. In both cases this could be changed
-by using `tt(r:|[[:upper:]0-9]=**)', but then `tt(H)' completes to both
-`tt(LikeTHIS)' and `tt(FooHoo)' and a `tt(2)' matches the other
-strings because characters can be inserted before every upper case
-letter and digit. To avoid this one would use:
-
-example(compadd -M 'r:[^[:upper:]0-9]||[[:upper:]0-9]=** r:|=*' \ 
-    LikeTHIS FooHoo foo123 bar234)
-
-By using these two anchors, a `tt(H)' matches only upper case `tt(H)'s that 
-are immediately preceded by something matching the left anchor
-`tt([^[:upper:]0-9])'. The effect is, of course, that `tt(H)' matches only
-the string `tt(FooHoo)', a `tt(2)' matches only `tt(bar234)' and so on.
-
-When using the completion system (see
-ifzman(zmanref(zshcompsys))\
+If there is a substring at the tt(l:)eft or tt(r:)ight edge of the current word
+that matches var(word-pat), then broaden the corresponding part of the match
+pattern to additionally match var(match-pat).
+
+For each tt(l:), tt(L:), tt(r:) and tt(R:) matcher (including the ones below),
+the pattern var(match-pat) may also be a `tt(*)'.  This matches any number of
+characters in a completion.
+
+startitem()
+item(Examples:)(
+
+`tt(r:|=*)' appends a `tt(*)' to the match pattern, even when
+tt(COMPLETE_IN_WORD) is set and the cursor is not at the end of the current
+word.
+
+If the current word starts with a minus, then `tt(L:|-=)' will prepend it to
+each match.
+)
+enditem()
+)
+xitem(tt(l:)var(anchor)tt(|)var(word-pat)tt(=)var(match-pat))
+xitem(tt(L:)var(anchor)tt(|)var(word-pat)tt(=)var(match-pat))
+xitem(tt(r:)var(word-pat)tt(|)var(anchor)tt(=)var(match-pat))
+item(tt(R:)var(word-pat)tt(|)var(anchor)tt(=)var(match-pat))(
+
+For each substring of the current word that matches var(word-pat) and has on
+its tt(l:)eft or tt(r:)ight another substring matching var(anchor), broaden the
+corresponding part of the match pattern to additionally match var(match-pat).
+
+Note that these matchers (and the ones below) modify only what is matched by
+var(word-pat); they do not change the matching behavior of what is matched by
+var(anchor) (or var(coanchor); see the matchers below).  Thus, unless its
+corresponding part of the match pattern has been modified, the anchor in the
+current word has to match literally in each completion, just like any other
+substring of the current word.
+
+If a matcher includes at least one anchor (which includes the matchers with two
+anchors, below), then var(match-pat) may also be `tt(*)' or `tt(**)'.  `tt(*)'
+can match any part of a completion that does not contain any substrings
+matching var(anchor), whereas a `tt(**)' can match any part of a completion,
+period.  (Note that this is different from the behavior of `tt(*)' in the
+anchorless forms of `tt(l:)' and `tt(r:)' and and also different from `tt(*)'
+and `tt(**)' in glob expressions.)
+
+startitem()
+item(Examples:)(
+
+`tt(r:|.=*)' makes the completion `tt(comp.sources.unix)' a match for the word
+`tt(..u)' DASH()- but em(not) for the word `tt(.u)'.
+
+Given a completion `tt(-)tt(-foo)', the matcher `tt(L:--|no-=)' will complete
+the word `tt(-)tt(-no-)' to the match `tt(-)tt(-no-foo)'.
+)
+enditem()
+)
+xitem(tt(l:)var(anchor)tt(||)var(coanchor)tt(=)var(match-pat))
+xitem(tt(L:)var(anchor)tt(||)var(coanchor)tt(=)var(match-pat))
+xitem(tt(r:)var(coanchor)tt(||)var(anchor)tt(=)var(match-pat))
+item(tt(R:)var(coanchor)tt(||)var(anchor)tt(=)var(match-pat))(
+
+For any two consecutive substrings of the current word that match var(anchor)
+and var(coanchor), in the order given, insert the pattern var(match-pat)
+between their corresponding parts in the match pattern.
+
+Note that, unlike var(anchor), the pattern var(coanchor) does not change what
+`tt(*)' can match.
+
+startitem()
+item(Examples:)(
+
+`tt(r:?||[[:upper:]]=*)' will complete the current word `tt(fB)' to
+`tt(fooBar)', but it will not complete it to `tt(fooHooBar)' (because `tt(*)'
+here cannot match anything that includes a match for `tt([[:upper:]])), nor
+will it complete `tt(B)' to `tt(fooBar)' (because there is no character in the
+current word to match var(coanchor)).
+
+Given the current word `tt(pass.n)' and a completion `tt(pass.byname)', the
+matcher `tt(L:.||[[:alpha:]]=by)' will produce the match `tt(pass.name)'.
+)
+enditem()
+)
+item(tt(x:))(
+
+Ignore this matcher and all matchers to its right.
+
+This matcher is used to mark the end of a match specification.  In a single
+standalone list of matchers, this has no use, but where match specifications
+are concatenated, as is often the case when using the
+ifzman(completion system (see zmanref(zshcompsys)))\
 ifnzman(noderef(Completion System))\
-), users can define match specifications that are to be used for
-specific contexts by using the tt(matcher) and tt(matcher-list)
-styles. The values for the latter will be used everywhere.
+, it can allow one match specification to override another.
+)
+enditem()
 
 texinode(Completion Widget Example)()(Completion Matching Control)(Completion Widgets)
 sect(Completion Widget Example)
@@ -1180,5 +1198,5 @@ matches, e.g.:
 
 example(complete-files LPAR()RPAR() { compadd - * })
 
-This function will complete files in the current directory matching the 
+This function will complete files in the current directory matching the
 current word.
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index c6bf745b7..0ef59dbc9 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -347,7 +347,7 @@ as the var(hook) argument.
 var(widgetname) is the name of a ZLE widget.  If no options are given this
 is added to the array of widgets to be invoked in the given hook context.
 Widgets are invoked in the order they were added, with
-example(tt(zle )var(widgetname)tt( -Nw -- "$@"))
+example(tt(zle )var(widgetname)tt( -Nw -f "nolast" -- "$@"))
 
 vindex(WIDGET, in hooks)
 Note that this means that the `tt(WIDGET)' special parameter tracks the
@@ -465,7 +465,7 @@ allows you to edit the list of directories, one per line.  The
 list can be edited to any extent you like; no sanity checking is
 performed.  Completion is available.  No quoting is necessary (except for
 newlines, where I have in any case no sympathy); directories are in
-unabbreviated from and contain an absolute path, i.e. they start with tt(/).
+unabbreviated form and contain an absolute path, i.e. they start with tt(/).
 Usually the first entry should be left as the current directory.
 )
 item(tt(-p ')var(pattern)tt('))(
@@ -598,7 +598,7 @@ changes to descendant directories; earlier directories on the
 list are not pruned.  For example, changing from ~pws/yet/another
 to ~pws/some/other/dir does not cause ~pws to be pruned.
 )
-item(tt(pattern:var(pattern)))(
+item(tt(pattern:)var(pattern))(
 Gives a zsh pattern for directories that should not be
 added to the recent list (if not already there).  This element
 can be repeated to add different patterns.  For example,
@@ -660,7 +660,7 @@ sect(Abbreviated dynamic references to directories)
 
 The dynamic directory naming system is described in the subsection
 em(Dynamic named directories) of
-ifzman(the section em(Filename Expansion) in zmanref(expn))\
+ifzman(the section em(Filename Expansion) in zmanref(zshexpn))\
 ifnzman(noderef(Filename Expansion)).  In this, a reference to
 tt(~[)var(...)tt(]) is expanded by a function found by the hooks
 mechanism.
@@ -708,7 +708,7 @@ that the wrapper function gets.  This configuration is described below.
 
 Then arrange for the wrapper to be run as a zsh_directory_name hook:
 
-example(autoload -Uz add-zsh-hook zsh_diretory_name_generic zdn_mywrapper
+example(autoload -Uz add-zsh-hook zsh_directory_name_generic zdn_mywrapper
 add-zsh-hook -U zsh_directory_name zdn_mywrapper)
 
 subsect(Configuration)
@@ -1159,7 +1159,7 @@ This is used by the Perforce backend (tt(p4)) to decide if it should
 contact the Perforce server to find out if a directory is managed
 by Perforce.  This is the only reliable way of doing this, but runs
 the risk of a delay if the server name cannot be found.  If the
-server (more specifically, the tt(host)tt(:)tt(port) pair describing the
+server (more specifically, the var(host)tt(:)var(port) pair describing the
 server) cannot be contacted, its name is put into the associative array
 tt(vcs_info_p4_dead_servers) and is not contacted again during the session
 until it is removed by hand.  If you do not set this style, the tt(p4)
@@ -1177,7 +1177,7 @@ If there are two different ways of gathering
 information, you can select the simpler one by setting this style to true;
 the default is to use the not-that-simple code, which is potentially a lot
 slower but might be more accurate in all possible cases. This style is
-used by the tt(bzr) and tt(hg) backends. In the case of tt(hg) it will invoke
+used by the tt(bzr), tt(hg), and tt(git) backends. In the case of tt(hg) it will invoke
 the external hexdump program to parse the binary dirstate cache file; this
 method will not return the local revision number.
 )
@@ -1236,7 +1236,7 @@ item(tt(get-unapplied))(
 This boolean style controls whether a backend should attempt to gather a list
 of unapplied patches (for example with Mercurial Queue patches).
 
-Used by the tt(quilt) and tt(hg) backends.
+Used by the tt(quilt), tt(hg), and tt(git) backends.
 )
 enditem()
 
@@ -1318,7 +1318,7 @@ tt(%Q) expando.
 item(tt(%Q))(
 Quilt series information.
 When quilt is used (either in `addon' mode or as a `standalone' backend),
-this expando is set to quilt series' tt(patch-format) string.
+this expando is set to the quilt series' tt(patch-format) string.
 The tt(set-patch-format) hook and tt(nopatch-format) style are honoured.
 
 See ifzman(tt(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) below for details.
@@ -1328,7 +1328,8 @@ enditem()
 In tt(branchformat) these replacements are done:
 
 startsitem()
-sitem(tt(%b))(The branch name.)
+sitem(tt(%b))(The branch name. For tt(hg), the branch name can include a
+topic name.)
 sitem(tt(%r))(The current revision number or the tt(hgrevformat) style for
 tt(hg).)
 endsitem()
@@ -1403,7 +1404,7 @@ a directory that holds quilt's patches needs to be found. That directory is
 configurable via the `tt(QUILT_PATCHES)' environment variable. If that
 variable exists its value is used, otherwise the value `tt(patches)' is
 assumed. The value from tt($QUILT_PATCHES) can be overwritten using the
-`tt(quilt-patches)' style. (Note: you can use tt(vcs_info) to keep the value
+`tt(quilt-patch-dir)' style. (Note: you can use tt(vcs_info) to keep the value
 of tt($QUILT_PATCHES) correct all the time via the tt(post-quilt) hook).
 
 When the directory in question is found, quilt is assumed to be active. To
@@ -1509,7 +1510,7 @@ below for details.
 )
 findex(vcs_info_lastmsg)
 item(tt(vcs_info_lastmsg))(
-Outputs the last tt(${vcs_info_msg_*_}) value.
+Outputs the current values of tt(${vcs_info_msg_*_}).
 Takes into account the value of the tt(use-prompt-escapes) style in
 tt(':vcs_info:formats:command:-all-'). It also only prints tt(max-exports)
 values.
@@ -1651,16 +1652,28 @@ Called in the tt(git) (with tt(stgit) or during rebase or merge), and tt(hg)
 is generated; the tt(use-quilt) zstyle must be true for tt(quilt) (the tt(mq)
 and tt(stgit) backends are active by default).
 
-This hook gets the names of all applied patches which tt(vcs_info) collected
-so far in the opposite order, which means that the first argument is the
+The arguments to this hook describe applied patches 
+in the opposite order, which means that the first argument is the
 top-most patch and so forth.
 
+When the patches' log messages can be extracted, those are embedded
+within each argument after a space, so each argument is of the form
+`var(patch-name) var(first line of the log message)', where var(patch-name)
+contains no whitespace. The tt(mq) backend passes arguments of
+the form `var(patch name)', with possible embedded spaces, but without
+extracting the patch's log message.
+
 When setting tt(ret) to non-zero, the string in
 tt(${hook_com[applied-string]}) will be
 available as tt(%p) in the tt(patch-format) and tt(nopatch-format) styles.
 This hook is, in concert with tt(set-patch-format), responsible for
 tt(%)-escaping that value for use in the prompt.
 (See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).)
+
+COMMENT(This paragraph is repeated above/below)\
+The tt(quilt) backend passes to this hook the inputs
+tt(${hook_com[quilt-patches-dir]}) and, if it has been
+determined, tt(${hook_com[quilt-pc-dir]}).
 )
 item(tt(gen-unapplied-string))(
 Called in the tt(git) (with tt(stgit) or during rebase), and tt(hg) (with
@@ -1668,15 +1681,22 @@ tt(mq)) backend and in tt(quilt) support when the tt(unapplied-string) is
 generated; the tt(get-unapplied) style must be true.
 
 This hook gets the names of all unapplied patches which tt(vcs_info)
-collected so far in order, which means that the first argument is
+in order, which means that the first argument is
 the patch next-in-line to be applied and so forth.
 
+The format of each argument is as for tt(gen-applied-string), above.
+
 When setting tt(ret) to non-zero, the string in
 tt(${hook_com[unapplied-string]}) will be available as tt(%u) in the
 tt(patch-format) and tt(nopatch-format) styles.
 This hook is, in concert with tt(set-patch-format), responsible for
 tt(%)-escaping that value for use in the prompt.
 (See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).)
+
+COMMENT(This paragraph is repeated above/below)\
+The tt(quilt) backend passes to this hook the inputs
+tt(${hook_com[quilt-patches-dir]}) and, if it has been
+determined, tt(${hook_com[quilt-pc-dir]}).
 )
 item(tt(gen-mqguards-string))(
 Called in the tt(hg) backend when tt(guards-string) is generated; the
@@ -1759,6 +1779,11 @@ This hook is, in concert with the tt(gen-applied-string) or
 tt(gen-unapplied-string) hooks if they are defined, responsible for
 tt(%)-escaping the final tt(patch-format) value for use in the prompt.
 (See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).)
+
+COMMENT(This paragraph is repeated above/below)\
+The tt(quilt) backend passes to this hook the inputs
+tt(${hook_com[quilt-patches-dir]}) and, if it has been
+determined, tt(${hook_com[quilt-pc-dir]}).
 )
 item(tt(set-message))(
 Called each time before a `tt(vcs_info_msg_)var(N)tt(_)' message is set.
@@ -1826,16 +1851,28 @@ If you do use tt(use-simple), please report if it does `the-right-thing[tm]'.
 
 Display the revision number in yellow for tt(bzr) and tt(svn):
 example(zstyle ':vcs_info:(svn|bzr):*' \ 
+       branchformat '%b%%F{yellow}:%r')
+
+The doubled percent sign is explained in
+ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).
+
+Alternatively, one can use the raw colour codes directly:
+
+example(zstyle ':vcs_info:(svn|bzr):*' \ 
        branchformat '%b%{'${fg[yellow]}'%}:%r')
 
-If you want colors, make sure you enclose the color codes in tt(%{)var(...)tt(%})
+Normally when a variable is interpolated into a format string, the variable
+needs to be tt(%)-escaped. In this example we skipped that because we assume
+the value of tt(${fg[yellow]}) doesn't contain any tt(%) signs.
+
+Make sure you enclose the color codes in tt(%{)var(...)tt(%})
 if you want to use the string provided by tt(vcs_info) in prompts.
 
 Here is how to print the VCS information as a command (not in a prompt):
-example(alias vcsi='vcs_info command; vcs_info_lastmsg')
+example(vcsi+LPAR()+RPAR() { vcs_info interactive; vcs_info_lastmsg })
 
 This way, you can even define different formats for output via
-tt(vcs_info_lastmsg) in the 'tt(:vcs_info:*:command:*)' namespace.
+tt(vcs_info_lastmsg) in the 'tt(:vcs_info:*:interactive:*)' namespace.
 
 Now as promised, some code that uses hooks:
 say, you'd like to replace the string `svn' by `subversion' in
@@ -1919,7 +1956,7 @@ subsect(Installation)
 
 You should make sure all the functions from the tt(Functions/Prompts)
 directory of the source distribution are available; they all begin with
-the string `tt(prompt_)' except for the special function`tt(promptinit)'.
+the string `tt(prompt_)' except for the special function `tt(promptinit)'.
 You also need the `tt(colors)' and `tt(add-zsh-hook)' functions from
 tt(Functions/Misc).
 All these functions may already be installed on your system; if not,
@@ -2019,27 +2056,30 @@ setopts (tt(promptbang), etc.) are turned on, all other prompt-related
 options are turned off.  The tt(prompt_opts) array preserves setopts even
 beyond the scope of tt(localoptions), should your function need that.
 )
-item(Modify precmd and preexec)(
-Use of tt(add-zsh-hook) is recommended.  The tt(precmd) and tt(preexec)
-hooks are automatically adjusted if the prompt theme changes or is
-disabled.
+item(Modify hooks)(
+Use of tt(add-zsh-hook) and tt(add-zle-hook-widget) is recommended (see
+the bf(Manipulating Hook Functions) section above).
+All hooks that follow the naming pattern tt(prompt_)var(theme)tt(_)var(hook)
+are automatically removed when the prompt theme changes or is disabled.
 )
 item(Declare cleanup)(
 If your function makes any other changes that should be undone when the
 theme is disabled, your setup function may call
+
 example(prompt_cleanup var(command))
+
 where var(command) should be suitably quoted.  If your theme is ever
 disabled or replaced by another, var(command) is executed with tt(eval).
 You may declare more than one such cleanup hook.
 )
 item(Define preview)(
-Define or autoload a function tt(prompt_var(name)_preview) to display
+Define or autoload a function tt(prompt_)var(name)tt(_preview) to display
 a simulated version of your prompt.  A simple default previewer is
 defined by tt(promptinit) for themes that do not define their own.
 This preview function is called by `tt(prompt -p)'.
 )
 item(Provide help)(
-Define or autoload a function tt(prompt_var(name)_help) to display
+Define or autoload a function tt(prompt_)var(name)tt(_help) to display
 documentation or help text for your theme.
 This help function is called by `tt(prompt -h)'.
 )
@@ -2316,8 +2356,8 @@ directly.
 )
 tindex(bracketed-paste-magic)
 item(tt(bracketed-paste-magic))(
-The tt(bracketed-paste) widget (see ifzman(subsection Miscellaneous in
-zmanref(zshzle))ifnzman(noderef(Miscellaneous) in noderef(Zle Widgets)))
+The tt(bracketed-paste) widget (see ifzman(the subsection `Miscellaneous' in
+zmanref(zshzle))ifnzman(noderef(Miscellaneous) in noderef(Standard Widgets)))
 inserts pasted text literally into the editor buffer rather than interpret
 it as keystrokes.  This disables some common usages where the self-insert
 widget is replaced in order to accomplish some extra processing.  An
@@ -2471,6 +2511,12 @@ item(tt(edit-command-line))(
 Edit the command line using your visual editor, as in tt(ksh).
 
 example(bindkey -M vicmd v edit-command-line)
+
+The editor to be used can also be specified using the tt(editor) style in
+the context of the widget. It is specified as an array of command and
+arguments:
+
+example(zstyle :zle:edit-command-line editor gvim -f)
 )
 tindex(expand-absolute-path)
 item(tt(expand-absolute-path))(
@@ -3159,7 +3205,7 @@ investigate the command word found.  The default is tt(whence -c).
 tindex(zcalc-auto-insert)
 item(tt(zcalc-auto-insert))(
 This function is useful together with the tt(zcalc) function described in
-ifzman(the section Mathematical Functions)\
+ifzman(the section `Mathematical Functions')\
 ifnzman(noderef(Mathematical Functions)).
 It should be bound to a key representing a binary operator such
 as `tt(PLUS())', `tt(-)', `tt(*)' or `tt(/)'.  When running in zcalc,
@@ -3559,7 +3605,8 @@ Calling tt(zsh-mime-setup) with the option
 tt(-v) causes verbose output to be shown during the setup operation.
 
 The system respects the tt(mailcap) flags tt(needsterminal) and
-tt(copiousoutput), see manref(mailcap)(4).
+tt(copiousoutput); see manref(mailcap)(4) or manref(mailcap)(5)
+(the man page's name varies across platforms).
 
 The functions use the following styles, which are defined with the
 tt(zstyle) builtin command (\
@@ -3632,7 +3679,7 @@ types even if they are executable.  As this example shows, the complete
 file name is matched against the pattern, regardless of how the file
 was passed to the handler.  The file is resolved to a full path using
 the tt(:P) modifier described in
-ifzman(the subsection Modifiers in zmanref(zshexpn))\
+ifzman(the subsection `Modifiers' in zmanref(zshexpn))\
 ifnzman(noderef(Modifiers));
 this means that symbolic links are resolved where possible, so that
 links into other file systems behave in the correct fashion.
@@ -4264,6 +4311,12 @@ Same as tt(zed -f).  This function does not appear in the zsh
 distribution, but can be created by linking tt(zed) to the name tt(fned)
 in some directory in your tt(fpath).
 )
+findex(histed)
+item(tt(histed) [ [ var(name) ] var(size) ])(
+Same as tt(zed -h).  This function does not appear in the zsh
+distribution, but can be created by linking tt(zed) to the name tt(histed)
+in some directory in your tt(fpath).
+)
 findex(is-at-least)
 item(tt(is-at-least) var(needed) [ var(present) ])(
 Perform a greater-than-or-equal-to comparison of two strings having the
@@ -4297,7 +4350,7 @@ See also the tt(pager), tt(prompt) and tt(rprompt) styles below.
 findex(regexp-replace)
 item(tt(regexp-replace) var(var) var(regexp) var(replace))(
 Use regular expressions to perform a global search and replace operation
-on a variable.  POSIX extended regular expressions are used,
+on a variable.  POSIX extended regular expressions (ERE) are used,
 unless the option tt(RE_MATCH_PCRE) has been set, in which case
 Perl-compatible regular expressions are used
 (this requires the shell to be linked against the tt(pcre)
@@ -4315,6 +4368,9 @@ and arithmetic expressions which will be replaced:  in particular, a
 reference to tt($MATCH) will be replaced by the text matched by the pattern.
 
 The return status is 0 if at least one match was performed, else 1.
+
+Note that if using POSIX EREs, the tt(^) or word boundary operators
+(where available) may not work properly.
 )
 findex(run-help)
 item(tt(run-help) var(cmd))(
@@ -4355,6 +4411,7 @@ directory.  These must be autoloaded, or placed as executable scripts in
 your search path, in order to be found and used by tt(run-help).
 
 startitem()
+findex(run-help-btrfs)
 findex(run-help-git)
 findex(run-help-ip)
 findex(run-help-openssl)
@@ -4362,14 +4419,16 @@ findex(run-help-p4)
 findex(run-help-sudo)
 findex(run-help-svk)
 findex(run-help-svn)
-xitem(run-help-git)
-xitem(run-help-ip)
-xitem(run-help-openssl)
-xitem(run-help-p4)
-xitem(run-help-sudo)
-xitem(run-help-svk)
+xitem(tt(run-help-btrfs))
+xitem(tt(run-help-git))
+xitem(tt(run-help-ip))
+xitem(tt(run-help-openssl))
+xitem(tt(run-help-p4))
+xitem(tt(run-help-sudo))
+xitem(tt(run-help-svk))
 item(tt(run-help-svn))(
 Assistant functions for the
+tt(btrfs),
 tt(git),
 tt(ip),
 tt(openssl),
@@ -4464,12 +4523,13 @@ counts the number of arguments passed to each execution of var(command),
 em(including) any var(arg) list.  Also, any time tt(-i) or tt(-I) is used,
 each var(input) is processed separately as if by `tt(-L) tt(1)'.
 
-For details of the other tt(zargs) options, see zmanref(xargs) (but note
+For details of the other tt(zargs) options, see the manref(xargs)(1) man page (but note
 the difference in function between tt(zargs) and tt(xargs)) or run
 tt(zargs) with the tt(-)tt(-help) option.
 )
 findex(zed)
 xitem(tt(zed) [ tt(-f) [ tt(-x) var(num) ] ] var(name))
+xitem(tt(zed) [ tt(-h) [ var(name) ] var(size) ])
 item(tt(zed -b))(
 This function uses the ZLE editor to edit a file or function.
 
@@ -4484,7 +4544,14 @@ the given number of spaces; `tt(-x 2)' is consistent with the layout
 of functions distributed with the shell.
 
 Without tt(-f), var(name) is the path name of the file to edit, which need
-not exist; it is created on write, if necessary.
+not exist; it is created on write, if necessary.  With tt(-h), the file is
+presumed to contain history events.
+
+When no file name is provided for tt(-h) the current shell history is edited
+in place.  The history is renumbered when zed exits successfully.
+
+When editing history, multi-line events must have a trailing backslash on
+every line before the last.
 
 While editing, the function sets the main keymap to tt(zed) and the
 vi command keymap to tt(zed-vicmd).  These will be copied from the existing
@@ -4500,16 +4567,20 @@ suitable for putting into a startup file.  Note that, if rerun,
 this will overwrite the existing tt(zed) and tt(zed-vicmd) keymaps.
 
 Completion is available, and styles may be set with the context prefix
-`tt(:completion:zed)'.
-
-A zle widget tt(zed-set-file-name) is available.  This can be called by
-name from within zed using `tt(\ex zed-set-file-name)' (note, however, that
-because of zed's rebindings you will have to type tt(^j) at the end instead
-of the return key), or can be bound to a key in either of the tt(zed) or
-tt(zed-vicmd) keymaps after `tt(zed -b)' has been run.  When the widget is
-called, it prompts for a new name for the file being edited.  When zed
-exits the file will be written under that name and the original file will
-be left alone.  The widget has no effect with `tt(zed -f)'.
+`tt(:completion:zed:)'.
+
+findex(zed-set-file-name)
+A zle widget tt(zed-set-file-name) is available.  This can be called
+by name from within zed using `tt(\ex zed-set-file-name)' or can be
+bound to a key in either of the tt(zed) or tt(zed-vicmd) keymaps after
+`tt(zed -b)' has been run.  When the widget is called, it prompts for
+a new name for the file being edited.  When zed exits the file will be
+written under that name and the original file will be left alone.  The
+widget has no effect when invoked from `tt(zed -f)'.  The completion
+context is changed to `tt(:completion:zed-set-file-name:)'.  When editing
+the current history with `tt(zed -h)', the history is first updated and
+then the file is written, but the global setting of tt(HISTFILE) is not
+altered.
 
 While tt(zed-set-file-name) is running, zed uses the keymap
 tt(zed-normal-keymap), which is linked from the main keymap in effect
@@ -4551,7 +4622,7 @@ the same result, the destination was an existing regular file and tt(-f)
 was not given) causes the entire function to abort without doing
 anything.
 
-In addition to pattern replacement, the variable tt($f) can be referrred
+In addition to pattern replacement, the variable tt($f) can be referred
 to in the second (replacement) argument.  This makes it possible to
 use variable substitution to alter the argument; see examples below.
 
diff --git a/Doc/Zsh/exec.yo b/Doc/Zsh/exec.yo
index 5f79967de..2b3d29500 100644
--- a/Doc/Zsh/exec.yo
+++ b/Doc/Zsh/exec.yo
@@ -14,9 +14,20 @@ a shell builtin by that name, the builtin is invoked.
 
 vindex(path, use of)
 Otherwise, the shell searches each element of tt($path) for a
-directory containing an executable file by that name.  If the
-search is unsuccessful, the shell prints an error message and returns
-a nonzero exit status.
+directory containing an executable file by that name.
+
+If execution fails: an error message is printed, and one of the
+following values is returned.
+
+startsitem()
+sitem(127)(The search was unsuccessful.  The error message is
+`tt(command not found:) var(cmd)'.)
+sitem(126)(The executable file has insufficient permissions, is a
+directory or special file, or is not a script and is in a format
+unrecognized by the operating system.  The exact conditions and error
+message are operating system-dependent; see
+manref(execve)(2).)
+endsitem()
 
 If execution fails because the file is not in executable format,
 and the file is not a directory, it is assumed to be a shell
@@ -29,10 +40,6 @@ not handle this executable format in the kernel.
 If no external command is found but a function tt(command_not_found_handler)
 exists the shell executes this function with all
 command line arguments.  The return status of the function becomes the
-status of the command.  If the function wishes to mimic the
-behaviour of the shell when the command is not found, it should
-print the message `tt(command not found:) var(cmd)' to standard error
-and return status 127.  Note that the handler is executed in a
+status of the command.  Note that the handler is executed in a
 subshell forked to execute an external command, hence changes to
 directories, shell parameters, etc. have no effect on the main shell.
-
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index c129b4228..bbacc6ae4 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -84,7 +84,7 @@ vindex(histchars, use of)
 A history expansion begins with the first character of the tt(histchars)
 parameter, which is `tt(!)' by default, and may occur anywhere on the
 command line, including inside double quotes (but not inside single quotes
-tt('...') or C-style quotes tt($'...') nor when escaped with a backslash).  
+tt('...') or C-style quotes tt($'...') nor when escaped with a backslash).
 
 The first character is followed by an optional event designator
 (ifzman(see )noderef(Event Designators)) and then an optional word
@@ -287,8 +287,10 @@ expansion.
 )
 item(tt(P))(
 Turn a file name into an absolute path, like tt(realpath+LPAR()3+RPAR()).
-The resulting path will be absolute, have neither `tt(.)' nor `tt(..)' components,
-and refer to the same directory entry as the input filename.
+The resulting path will be absolute,
+will refer to the same directory entry as the input filename,
+and none of its components will be symbolic links or equal to
+`tt(.)' or `tt(..)'.
 
 Unlike tt(realpath+LPAR()3+RPAR()), non-existent trailing components are
 permitted and preserved.
@@ -494,7 +496,7 @@ which treats var(arg) as a file name and replaces it with the file's
 contents.
 
 The tt(=) form is useful as both the tt(/dev/fd) and the named pipe
-implementation of tt(<LPAR())var(...)tt(RPAR()) have drawbacks.  In 
+implementation of tt(<LPAR())var(...)tt(RPAR()) have drawbacks.  In
 the former case, some programmes may automatically close the file
 descriptor in question before examining the file on the command line,
 particularly if this is necessary for security reasons such as when the
@@ -509,7 +511,7 @@ information using a pipe, so that programmes that expect to lseek
 Also note that the previous example can be more compactly and
 efficiently written (provided the tt(MULTIOS) option is set) as:
 
-example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) ifzman(\ 
+example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) ifzman(\
 )tt(> >LPAR())var(process1)tt(RPAR() > >LPAR())var(process2)tt(RPAR()))
 
 The shell uses pipes instead of FIFOs to implement the latter
@@ -870,7 +872,8 @@ of the string tt($-) and the array tt($*) respectively.  If
 tt(POSIX_IDENTIFIERS) is set, then braces are required for
 the tt(#) to be treated in this fashion.
 )
-item(tt(${^)var(spec)tt(}))(
+xitem(tt(${^)var(spec)tt(}))
+item(tt(${^^)var(spec)tt(}))(
 pindex(RC_EXPAND_PARAM, toggle)
 cindex(array expansion style, rc)
 cindex(rc, array expansion style)
@@ -893,7 +896,8 @@ happening later.  If word splitting is also in effect the
 tt($var[)var(N)tt(]) may themselves be split into different list
 elements.
 )
-item(tt(${=)var(spec)tt(}))(
+xitem(tt(${=)var(spec)tt(}))
+item(tt(${==)var(spec)tt(}))(
 pindex(SH_WORD_SPLIT, toggle)
 cindex(field splitting, sh style, parameter)
 cindex(sh, field splitting style, parameter)
@@ -909,7 +913,8 @@ Note that splitting is applied to var(word) in the assignment forms
 of var(spec) em(before) the assignment to var(name) is performed.
 This affects the result of array assignments with the tt(A) flag.
 )
-item(tt(${~)var(spec)tt(}))(
+xitem(tt(${~)var(spec)tt(}))
+item(tt(${~~)var(spec)tt(}))(
 pindex(GLOB_SUBST, toggle)
 Turn on the tt(GLOB_SUBST) option for the evaluation of
 var(spec); if the `tt(~)' is doubled, turn it off.  When this option is
@@ -963,16 +968,17 @@ following flags are supported:
 
 startitem()
 item(tt(#))(
-Evaluate the resulting words as numeric expressions and output the
-characters corresponding to the resulting integer.  Note that this form is
-entirely distinct from use of the tt(#) without parentheses.
+Evaluate the resulting words as numeric expressions and interpret
+these as character codes.  Output the corresponding characters.  Note
+that this form is entirely distinct from use of the tt(#) without
+parentheses.
 
 If the tt(MULTIBYTE) option is set and the number is greater than 127
 (i.e. not an ASCII character) it is treated as a Unicode character.
 )
 item(tt(%))(
 Expand all tt(%) escapes in the resulting words in the same way as in
-prompts (see 
+prompts (see
 ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\
 ifnzman(noderef(Prompt Expansion))). If this flag is given twice,
 full prompt expansion is done on the resulting words, depending on the
@@ -1092,22 +1098,31 @@ Convert all letters in the result to lower case.
 item(tt(n))(
 Sort decimal integers numerically; if the first differing
 characters of two test strings are not digits, sorting
-is lexical.   Integers with more initial zeroes
-are sorted before those with fewer or none.  Hence the array `tt(foo1 foo02
+is lexical.  `tt(+)' and `tt(-)' are not treated specially; they are treated as
+any other non-digit.  Integers with more initial zeroes
+are sorted before those with fewer or none.  Hence the array `tt(foo+24 foo1 foo02
 foo2 foo3 foo20 foo23)' is sorted into the order shown.
 May be combined with `tt(i)' or `tt(O)'.
 )
+item(tt(-))(
+As tt(n), but a leading minus sign indicates a negative decimal
+integer.  A leading minus sign not followed by an integer does not trigger
+numeric sorting.
+Note that `tt(+)' signs are not handled specially (this may change in the
+future).
+)
 item(tt(o))(
 Sort the resulting words in ascending order; if this appears on its
 own the sorting is lexical and case-sensitive (unless the locale
 renders it case-insensitive).  Sorting in ascending order is the
 default for other forms of sorting, so this is ignored if combined
-with `tt(a)', `tt(i)' or `tt(n)'.
+with `tt(a)', `tt(i)', `tt(n)' or `tt(-)'.
 )
 item(tt(O))(
 Sort the resulting words in descending order; `tt(O)' without `tt(a)',
-`tt(i)' or `tt(n)' sorts in reverse lexical order.  May be combined
-with `tt(a)', `tt(i)' or `tt(n)' to reverse the order of sorting.
+`tt(i)', `tt(n)' or `tt(-)' sorts in reverse lexical order.  May be
+combined with `tt(a)', `tt(i)', `tt(n)' or `tt(-)' to reverse the
+order of sorting.
 )
 item(tt(P))(
 This forces the value of the parameter var(name) to be interpreted as a
@@ -1191,6 +1206,11 @@ for readonly parameters
 item(tt(tag))(
 for tagged parameters
 )
+item(tt(tied))(
+for parameters tied to another parameter in the manner of tt(PATH)
+(colon-separated list) and tt(path) (array), whether these are
+special parameters or user-defined with `tt(typeset -T)'
+)
 item(tt(export))(
 for exported parameters
 )
@@ -1377,16 +1397,29 @@ i.e.  tt("${(@s.:.)line}").
 item(tt(Z:)var(opts)tt(:))(
 As tt(z) but takes a combination of option letters between a following
 pair of delimiter characters.  With no options the effect is identical
-to tt(z).  tt(LPAR()Z+PLUS()c+PLUS()RPAR())
+to tt(z).  The following options are available:
+
+startitem()
+item(tt(LPAR()Z+PLUS()c+PLUS()RPAR()))(
 causes comments to be parsed as a string and retained; any field in the
 resulting array beginning with an unquoted comment character is a
-comment.  tt(LPAR()Z+PLUS()C+PLUS()RPAR()) causes comments to be parsed
+comment.
+)
+item(tt(LPAR()Z+PLUS()C+PLUS()RPAR()))(
+causes comments to be parsed
 and removed.  The rule for comments is standard: anything between a word
 starting with the third character of tt($HISTCHARS), default tt(#), up to
-the next newline is a comment.  tt(LPAR()Z+PLUS()n+PLUS()RPAR()) causes
+the next newline is a comment.
+)
+item(tt(LPAR()Z+PLUS()n+PLUS()RPAR()))(
+causes
 unquoted newlines to be treated as ordinary whitespace, else they are
 treated as if they are shell code delimiters and converted to
-semicolons.  Options are combined within the same set of delimiters,
+semicolons.
+)
+enditem()
+
+Options are combined within the same set of delimiters,
 e.g. tt(LPAR()Z+PLUS()Cn+PLUS()RPAR()).
 )
 item(tt(_:)var(flags)tt(:))(
@@ -1398,7 +1431,7 @@ error, and the flag itself has no effect.
 enditem()
 
 The following flags are meaningful with the tt(${)...tt(#)...tt(}) or
-tt(${)...tt(%)...tt(}) forms.  The tt(S) and tt(I) flags may also be
+tt(${)...tt(%)...tt(}) forms.  The tt(S), tt(I), and tt(*) flags may also be
 used with the tt(${)...tt(/)...tt(}) forms.
 
 startitem()
@@ -1464,6 +1497,10 @@ will remove the same matches as for `tt(#)', but in reverse order, and the
 form using `tt(%%)' will remove the same matches as for `tt(##)' in reverse
 order.
 )
+item(tt(*))(
+Enable tt(EXTENDED_GLOB) for substitution via tt(${)...tt(/)...tt(}) or
+tt(${)...tt(//)...tt(}).
+)
 item(tt(B))(
 Include the index of the beginning of the match in the result.
 )
@@ -1483,7 +1520,9 @@ Include the unmatched portion in the result (the em(R)est).
 enditem()
 
 subsect(Rules)
-
+cindex(parameter expansion rules)
+cindex(rules, parameter expansion)
+cindex(substitution, parameter, rules)
 Here is a summary of the rules for substitution; this assumes that braces
 are present around the substitution, i.e. tt(${)var(...)tt(}).  Some particular
 examples are given below.  Note that the Zsh Development Group accepts
@@ -1681,6 +1720,7 @@ expression) and replaced with the corresponding value, with internal flags
 enditem()
 
 subsect(Examples)
+cindex(parameter expansion, 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()"})
 substitutes the contents of var(file) divided so that each line is
@@ -1698,7 +1738,7 @@ This produces the result tt(b).  First, the inner substitution
 tt("${foo}"), which has no array (tt(@)) flag, produces a single word
 result tt("bar baz").  The outer substitution tt("${(@)...[1]}") detects
 that this is a scalar, so that (despite the `tt((@))' flag) the subscript
-picks the first character. 
+picks the first character.
 )
 item(tt("${${(@)foo}[1]}"))(
 This produces the result `tt(bar)'.  In this case, the inner substitution
@@ -1732,7 +1772,7 @@ sect(Command Substitution)
 cindex(command substitution)
 cindex(substitution, command)
 A command enclosed in parentheses preceded by a dollar sign, like
-`tt($LPAR())...tt(RPAR())', or quoted with grave 
+`tt($LPAR())...tt(RPAR())', or quoted with grave
 accents, like `tt(`)...tt(`)', is replaced with its standard output, with
 any trailing newlines deleted.
 If the substitution is not enclosed in double quotes, the
@@ -1823,7 +1863,7 @@ has similar effects.
 
 To combine brace expansion with array expansion, see the
 tt(${^)var(spec)tt(}) form described
-ifzman(in the section Parameter Expansion)\
+ifzman(in the section `Parameter Expansion')\
 ifnzman(in noderef(Parameter Expansion))
 above.
 
@@ -1858,11 +1898,18 @@ The tt(PUSHD_MINUS)
 option exchanges the effects of `tt(~PLUS())' and `tt(~-)' where they are
 followed by a number.
 
+startmenu()
+menu(Dynamic named directories)
+menu(Static named directories)
+menu(`=' expansion)
+menu(Notes)
+endmenu()
+
+texinode(Dynamic named directories)(Static named directories)()(Filename Expansion)
 subsect(Dynamic named directories)
 cindex(directories, named, dynamic)
 cindex(named directories, dynamic)
 cindex(dynamic named directories)
-
 If the function tt(zsh_directory_name) exists, or the shell variable
 tt(zsh_directory_name_functions) exists and contains an array of
 function names, then the functions are used to implement dynamic
@@ -1952,6 +1999,7 @@ example(zsh_directory_name+LPAR()RPAR() {
   return 0
 })
 
+texinode(Static named directories)(`=' expansion)(Dynamic named directories)(Filename Expansion)
 subsect(Static named directories)
 cindex(directories, named, static)
 cindex(named directories, static)
@@ -1978,6 +2026,7 @@ i.e. either the directory name or the full path; the name is used
 if they are the same length.
 The parameters tt($PWD) and tt($OLDPWD) are never abbreviated in this fashion.
 
+texinode(`=' expansion)(Notes)(Static named directories)(Filename Expansion)
 subsect(`=' expansion)
 
 If a word begins with an unquoted `tt(=)'
@@ -1987,8 +2036,9 @@ name of a command.  If a command
 exists by that name, the word is replaced
 by the full pathname of the command.
 
+texinode(Notes)()(`=' expansion)(Filename Expansion)
 subsect(Notes)
-
+cindex(filename expansion, notes)
 Filename expansion is performed on the right hand side of a parameter
 assignment, including those appearing after commands of the
 tt(typeset) family.  In this case, the right hand side will be treated
@@ -2033,6 +2083,7 @@ No filename generation pattern
 matches the files `tt(.)' or `tt(..)'.  In other instances of pattern
 matching, the `tt(/)' and `tt(.)' are not treated specially.
 subsect(Glob Operators)
+cindex(glob operators)
 startitem()
 item(tt(*))(
 Matches any string, including the null string.
@@ -2103,7 +2154,8 @@ is not sensitive to the locale:
 startitem()
 item(tt([:IDENT:]))(
 The character is allowed to form part of a shell identifier, such
-as a parameter name
+as a parameter name; this test respects the tt(POSIX_IDENTIFIERS)
+option
 )
 item(tt([:IFS:]))(
 The character is used as an input field separator, i.e. is contained in the
@@ -2263,6 +2315,8 @@ within `tt([[)...tt(]])'), a `tt(/)' is not special; and `tt(/)' is also
 not special after a `tt(~)' appearing outside parentheses in a filename
 pattern.
 subsect(Globbing Flags)
+cindex(globbing flags)
+cindex(glob 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
@@ -2427,7 +2481,7 @@ qualifiers are also not applied in ordinary pattern matching.
 )
 item(tt(u))(
 Respect the current locale in determining the presence of multibyte
-characters in a pattern, provided the shell was compiled with 
+characters in a pattern, provided the shell was compiled with
 tt(MULTIBYTE_SUPPORT).  This overrides the tt(MULTIBYTE)
 option; the default behaviour is taken from the option.  Compare tt(U).
 (Mnemonic: typically multibyte characters are from Unicode in the UTF-8
@@ -2457,6 +2511,8 @@ searched for all files which match, so that a pattern of the form
 tt(LPAR()#i)tt(RPAR()/foo/bar/...) is potentially slow.
 
 subsect(Approximate Matching)
+cindex(approximate matching)
+cindex(matching, approximate)
 When matching approximately, the shell keeps a count of the errors found,
 which cannot exceed the number specified in the
 tt(LPAR()#a)var(num)tt(RPAR()) flags.  Four types of error are recognised:
@@ -2522,6 +2578,8 @@ approximate match.  It is best to place the tt((#a1)) after any path
 segments which are known to be correct.
 
 subsect(Recursive Globbing)
+cindex(recursive globbing)
+cindex(globbing, recursive)
 A pathname component of the form `tt(LPAR())var(foo)tt(/RPAR()#)'
 matches a path consisting of zero or more directories
 matching the pattern var(foo).
@@ -2674,18 +2732,18 @@ expected, if combined with a `tt(=)', the value given must match the
 file-modes exactly, with a `tt(PLUS())', at least the bits in the
 given number must be set in the file-modes, and with a `tt(-)', the
 bits in the number must not be set. Giving a `tt(?)' instead of a
-octal digit anywhere in the number ensures that the corresponding bits 
+octal digit anywhere in the number ensures that the corresponding bits
 in the file-modes are not checked, this is only useful in combination
 with `tt(=)'.
 
 If the qualifier `tt(f)' is followed by any other character anything
-up to the next matching character (`tt([)', `tt({)', and `tt(<)' match 
+up to the next matching character (`tt([)', `tt({)', and `tt(<)' match
 `tt(])', `tt(})', and `tt(>)' respectively, any other character
 matches itself) is taken as a list of comma-separated
 var(sub-spec)s. Each var(sub-spec) may be either an octal number as
 described above or a list of any of the characters `tt(u)', `tt(g)',
 `tt(o)', and `tt(a)', followed by a `tt(=)', a `tt(PLUS())', or a
-`tt(-)', followed by a list of any of the characters `tt(r)', `tt(w)', 
+`tt(-)', followed by a list of any of the characters `tt(r)', `tt(w)',
 `tt(x)', `tt(s)', and `tt(t)', or an octal digit. The first list of
 characters specify which access rights are to be checked. If a `tt(u)'
 is given, those for the owner of the file are used, if a `tt(g)' is
@@ -2694,7 +2752,7 @@ of other users, and the `tt(a)' says to test all three groups. The
 `tt(=)', `tt(PLUS())', and `tt(-)' again says how the modes are to be
 checked and have the same meaning as described for the first form
 above. The second list of characters finally says which access rights
-are to be expected: `tt(r)' for read access, `tt(w)' for write access, 
+are to be expected: `tt(r)' for read access, `tt(w)' for write access,
 `tt(x)' for the right to execute the file (or to search a directory),
 `tt(s)' for the setuid and setgid bits, and `tt(t)' for the sticky
 bit.
@@ -2703,7 +2761,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.
@@ -2824,7 +2882,9 @@ negates all qualifiers following it
 )
 item(tt(-))(
 toggles between making the qualifiers work on symbolic links (the
-default) and the files they point to
+default) and the files they point to, if any; any symbolic link for
+whose target the `tt(stat)' system call fails (whatever the cause of the
+failure) is treated as a file in its own right
 )
 item(tt(M))(
 sets the tt(MARK_DIRS) option for the current pattern
@@ -2854,18 +2914,26 @@ matches in directory traversal order will be considered.
 Implies tt(oN) when no tt(o)var(c) qualifier is used.
 )
 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; 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; if tt(a), tt(m), or tt(c)
-they are sorted by the time of the last access, modification, or
-inode change respectively; if tt(d), files in subdirectories appear before
+specifies how the names of the files should be sorted. The following values
+of var(c) sort in the following ways:
+
+startsitem()
+sitem(tt(n))(By name.)
+sitem(tt(L))(By the size (length) of the files.)
+sitem(tt(l))(By number of links.)
+sitem(tt(a))(By time of last access, youngest first.)
+sitem(tt(m))(By time of last modification, youngest first.)
+sitem(tt(c))(By time of last inode change, youngest first.)
+sitem(tt(d))(By directories: files in subdirectories appear before
 those in the current directory at each level of the search DASH()- this is best
 combined with other criteria, for example `tt(odon)' to sort on names for
-files within the same directory; if tt(N), no sorting is performed.
-Note that tt(a), tt(m), and tt(c) compare
-the age against the current time, hence the first name in the list is the
-youngest file. Also note that the modifiers tt(^) and tt(-) are used,
+files within the same directory.)
+sitem(tt(N))(No sorting is performed.)
+xitem(tt(e)var(string))
+sitem(tt(+)var(cmd))(Sort by shell code (see below).)
+endsitem()
+
+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, following any symbolic links.  Unless tt(oN) is used, multiple order
 specifiers may occur to resolve ties.
@@ -2885,8 +2953,8 @@ repeated, but note that the maximum number of sort operators of any kind
 that may appear in any glob expression is 12.
 )
 item(tt(O)var(c))(
-like `tt(o)', but sorts in descending order; i.e. `tt(*(^oc))' is the
-same as `tt(*(Oc))' and `tt(*(^Oc))' is the same as `tt(*(oc))'; `tt(Od)'
+like `tt(o)', but sorts in descending order; i.e. `tt(*+LPAR()^o)var(c)tt(+RPAR())' is the
+same as `tt(*+LPAR()O)var(c)tt(+RPAR())' and `tt(*+LPAR()^O)var(c)tt(+RPAR())' is the same as `tt(*+LPAR()o)var(c)tt(+RPAR())'; `tt(Od)'
 puts files in the current directory before those in subdirectories at each
 level of the search.
 )
@@ -2894,7 +2962,7 @@ item(tt([)var(beg)[tt(,)var(end)]tt(]))(
 specifies which of the matched filenames should be included in the
 returned list. The syntax is the same as for array
 subscripts. var(beg) and the optional var(end) may be mathematical
-expressions. As in parameter subscripting they may be negative to make 
+expressions. As in parameter subscripting they may be negative to make
 them count from the last match backward. E.g.: `tt(*(-OL[1,3]))'
 gives a list of the names of the three largest files.
 )
diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index d500a78ae..12db3f56a 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -206,13 +206,14 @@ findex(hook functions)
 For the functions below, it is possible to define an array that has the
 same name as the function with `tt(_functions)' appended.  Any element in
 such an array is taken as the name of a function to execute; it is executed
-in the same context and with the same arguments as the basic function.  For
+in the same context and with the same arguments and same initial value of tt($?)
+as the basic function.  For
 example, if tt($chpwd_functions) is an array containing the values
 `tt(mychpwd)', `tt(chpwd_save_dirstack)', then the shell attempts to
 execute the functions `tt(chpwd)', `tt(mychpwd)' and
 `tt(chpwd_save_dirstack)', in that order.  Any function that does not exist
 is silently ignored.  A function found by this mechanism is referred to
-elsewhere as a `hook function'.  An error in any function causes subsequent
+elsewhere as a em(hook function).  An error in any function causes subsequent
 functions not to be run.  Note further that an error in a tt(precmd) hook
 causes an immediately following tt(periodic) function not to run (though
 it may run at the next opportunity).
@@ -275,7 +276,7 @@ the history file.  In case of a conflict, the first non-zero status
 value is taken.
 
 A hook function may call `tt(fc -p) var(...)' to switch the history
-context so that the history is saved in a different file from the
+context so that the history is saved in a different file from
 that in the global tt(HISTFILE) parameter.  This is handled specially:
 the history context is automatically restored after the processing
 of the history line is finished.
diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo
index e028c8512..f8f4ada86 100644
--- a/Doc/Zsh/grammar.yo
+++ b/Doc/Zsh/grammar.yo
@@ -288,7 +288,9 @@ for each selection until a break or end-of-file is encountered.
 cindex(subshell)
 item(tt(LPAR()) var(list) tt(RPAR()))(
 Execute var(list) in a subshell.  Traps set by the tt(trap) builtin
-are reset to their default values while executing var(list).
+are reset to their default values while executing var(list); an
+exception is that ignored signals will continue to be ignored
+if the option tt(POSIXTRAPS) is set.
 )
 item(tt({) var(list) tt(}))(
 Execute var(list).
@@ -357,7 +359,7 @@ deliberately left unspecified, because historically there was a mismatch between
 the documented and implemented behaviours.  Cf. 20076, 21734/21735, 45075.)
 )
 findex(function)
-xitem(tt(function) var(word) ... [ tt(()) ] [ var(term) ] tt({) var(list) tt(}))
+xitem(tt(function) [ tt(-T) ] var(word) ... [ tt(()) ] [ var(term) ] tt({) var(list) tt(}))
 xitem(var(word) ... tt(()) [ var(term) ] tt({) var(list) tt(}))
 item(var(word) ... tt(()) [ var(term) ] var(command))(
 where var(term) is one or more newline or tt(;).
@@ -367,6 +369,17 @@ are usually only useful for setting traps.
 The body of the function is the var(list) between
 the tt({) and tt(}).  See noderef(Functions).
 
+The options of tt(function) have the following meanings:
+
+startitem()
+item(-T)(
+Enable tracing for this function, as though with tt(functions -T).  See the
+documentation of the tt(-f) option to the tt(typeset) builtin, in
+ifzman(zmanref(zshbuiltins))\
+ifnzman(noderef(Shell Builtin Commands)).
+)
+enditem()
+
 If the option tt(SH_GLOB) is set for compatibility with other shells, then
 whitespace may appear between the left and right parentheses when
 there is a single var(word);  otherwise, the parentheses will be treated as
@@ -417,6 +430,8 @@ else the end of the test will not be recognized.  For the
 tt(for), tt(repeat), tt(case) and tt(select) commands no such special form
 for the arguments is necessary, but the other condition (the special form
 of var(sublist) or use of the tt(SHORT_LOOPS) option) still applies.
+The tt(SHORT_REPEAT) option is available to enable the short version only
+for the tt(repeat) command.
 
 startitem()
 item(tt(if) var(list) tt({) var(list) tt(}) [ tt(elif) var(list) tt({) var(list) tt(}) ] ... [ tt(else {) var(list) tt(}) ])(
@@ -558,6 +573,11 @@ position (if it could be the first word of a simple command),
 or if the alias is global.
 If the replacement text ends with a space, the next word in the shell input
 is always eligible for purposes of alias expansion.
+
+It is an error for the function name, var(word), in the sh-compatible function
+definition syntax `var(word) tt(+LPAR()+RPAR()) ...' to be a word that resulted
+from alias expansion, unless the tt(ALIAS_FUNC_DEF) option is set.
+
 findex(alias, use of)
 cindex(aliases, global)
 An alias is defined using the tt(alias) builtin; global aliases
@@ -584,6 +604,15 @@ word, e.g. tt(\foo).  Any form of quoting works, although there is
 nothing to prevent an alias being defined for the quoted form such as
 tt(\foo) as well.
 
+In particular, note that quoting must be used when using tt(unalias) to remove
+global aliases:
+
+example(% alias -g foo=bar
+% unalias foo
+unalias: no such hash table element: bar
+% unalias \foo
+% )
+
 When tt(POSIX_ALIASES) is set, only plain unquoted strings are eligible
 for aliasing.  The tt(alias) builtin does not reject ineligible aliases,
 but they are not expanded.
@@ -634,26 +663,6 @@ a problem in shell scripts, functions, and code executed with `tt(source)'
 or `tt(.)'.  Consequently, use of functions rather than aliases is
 recommended in non-interactive code.
 
-Note also the unhelpful interaction of aliases and function definitions:
-
-example(alias func='noglob func'
-func+LPAR()RPAR() {
-    echo Do something with $*
-})
-
-Because aliases are expanded in function definitions, this causes the
-following command to be executed:
-
-example(noglob func+LPAR()RPAR() {
-    echo Do something with $*
-})
-
-which defines tt(noglob) as well as tt(func) as functions with the
-body given.  To avoid this, either quote the name tt(func) or use the
-alternative function definition form `tt(function func)'.  Ensuring the
-alias is defined after the function works but is problematic if the
-code fragment might be re-executed.
-
 texinode(Quoting)()(Aliasing)(Shell Grammar)
 sect(Quoting)
 cindex(quoting)
diff --git a/Doc/Zsh/intro.yo b/Doc/Zsh/intro.yo
index 75d25ce27..474e537c2 100644
--- a/Doc/Zsh/intro.yo
+++ b/Doc/Zsh/intro.yo
@@ -45,7 +45,7 @@ zsh most closely resembles bf(ksh) but includes many enhancements.  It
 does not provide compatibility with POSIX or other shells in its
 default operating mode:  see
 ifnzman(the section noderef(Compatibility))\
-ifzman(the section Compatibility below).
+ifzman(the section `Compatibility' below).
 
 Zsh has command line editing, builtin spelling correction, programmable
 command completion, shell functions (with autoloading), a history
diff --git a/Doc/Zsh/jobs.yo b/Doc/Zsh/jobs.yo
index 70559f2d8..3ab0698ae 100644
--- a/Doc/Zsh/jobs.yo
+++ b/Doc/Zsh/jobs.yo
@@ -111,7 +111,7 @@ cindex(jobs, disowning)
 cindex(disowning jobs)
 findex(disown, use of)
 To avoid having the shell terminate the running jobs, either
-use the bf(nohup) command (see manref(nohup)(1))
+use the manref(nohup)(1) command
 or the tt(disown) builtin.
 sect(Signals)
 The tt(INT) and tt(QUIT) signals for an invoked
@@ -135,4 +135,4 @@ ifzman(the section PROCESS SUBSTITUTION in the zmanref(zshexpn) manual page)\
 ifnzman(noderef(Process Substitution)), and the handler processes for
 multios, see
 ifzman(the section MULTIOS in the zmanref(zshmisc) manual page)\
-ifnzman(the section Multios in noderef(Redirection)).
+ifnzman(the section em(Multios) in noderef(Redirection)).
diff --git a/Doc/Zsh/manmodmenu.yo b/Doc/Zsh/manmodmenu.yo
index 53c0e01c9..e91a5ce3d 100644
--- a/Doc/Zsh/manmodmenu.yo
+++ b/Doc/Zsh/manmodmenu.yo
@@ -27,6 +27,7 @@ menu(The zsh/system Module)
 menu(The zsh/net/tcp Module)
 menu(The zsh/termcap Module)
 menu(The zsh/terminfo Module)
+menu(The zsh/watch Module)
 menu(The zsh/zftp Module)
 menu(The zsh/zle Module)
 menu(The zsh/zleparameter Module)
diff --git a/Doc/Zsh/manual.yo b/Doc/Zsh/manual.yo
index 119849e4c..dc4d6ed07 100644
--- a/Doc/Zsh/manual.yo
+++ b/Doc/Zsh/manual.yo
@@ -108,6 +108,8 @@ Zsh Line Editor
 menu(Keymaps)
 menu(Zle Builtins)
 menu(Zle Widgets)
+menu(User-Defined Widgets)
+menu(Standard Widgets)
 menu(Character Highlighting)
 
 Completion Widgets
@@ -196,7 +198,7 @@ produce a nicely formatted printed manual.
 item(The HTML manual)(
 An HTML version of this manual is available at the Zsh web site via:
 
-uref(http://zsh.sourceforge.net/Doc/).
+uref(https://zsh.sourceforge.io/Doc/).
 
 (The HTML version is produced with bf(texi2html), which may be obtained
 from uref(http://www.nongnu.org/texi2html/). The command is
diff --git a/Doc/Zsh/metafaq.yo b/Doc/Zsh/metafaq.yo
index c123a7cea..c780808e3 100644
--- a/Doc/Zsh/metafaq.yo
+++ b/Doc/Zsh/metafaq.yo
@@ -10,12 +10,12 @@ endmenu()
 texinode(Author)(Availability)()(Introduction)
 sect(Author)
 cindex(author)
-Zsh was originally written by Paul Falstad tt(<pf@zsh.org>).
-Zsh is now maintained by the members of the zsh-workers mailing
-list tt(<zsh-workers@zsh.org>).  The development is currently
-coordinated by Peter Stephenson tt(<pws@zsh.org>).  The coordinator
-can be contacted at tt(<coordinator@zsh.org>), but matters relating to
-the code should generally go to the mailing list.
+Zsh was originally written by Paul Falstad.  Zsh is now maintained by
+the members of the zsh-workers mailing list tt(<zsh-workers@zsh.org>).
+The development is currently coordinated by Peter Stephenson
+tt(<pws@zsh.org>).  The coordinator can be contacted at
+tt(<coordinator@zsh.org>), but matters relating to the code should
+generally go to the mailing list.
 texinode(Availability)(Mailing Lists)(Author)(Introduction)
 sect(Availability)
 Zsh is available from the following HTTP and anonymous FTP site.
@@ -25,17 +25,16 @@ cindex(acquiring zsh by FTP)
 cindex(availability of zsh)
 nofill(uref(ftp://ftp.zsh.org/pub/)
 uref(https://www.zsh.org/pub/))
-)
 
 The up-to-date source code is available via Git from Sourceforge.  See
 uref(https://sourceforge.net/projects/zsh/) for details.  A summary of
 instructions for the archive can be found at
-uref(http://zsh.sourceforge.net/).
+uref(https://zsh.sourceforge.io/).
 
 texinode(Mailing Lists)(The Zsh FAQ)(Availability)(Introduction)
 sect(Mailing Lists)
 cindex(mailing lists)
-Zsh has 3 mailing lists:
+Zsh has several mailing lists:
 
 startitem()
 item(tt(<zsh-announce@zsh.org>))(
@@ -48,6 +47,12 @@ User discussions.
 item(tt(<zsh-workers@zsh.org>))(
 Hacking, development, bug reports and patches.
 )
+item(tt(<zsh-security@zsh.org>))(
+Private mailing list (the general public cannot subscribe to it) for discussing
+bug reports with security implications, i.e., potential vulnerabilities.
+
+If you find a security problem in zsh itself, please mail this address.
+)
 enditem()
 
 To subscribe or unsubscribe, send mail
@@ -69,12 +74,11 @@ bf(zsh-users).  All submissions to bf(zsh-users) are automatically
 forwarded to bf(zsh-workers).
 
 If you have problems subscribing/unsubscribing to any of the mailing
-lists, send mail to tt(<listmaster@zsh.org>).  The mailing lists are
-maintained by Karsten Thygesen tt(<karthy@kom.auc.dk>).
+lists, send mail to tt(<listmaster@zsh.org>).
 
 The mailing lists are archived; the archives can be accessed via the
 administrative addresses listed above.  There is also a hypertext
-archive, maintained by Geoff Wing tt(<gcw@zsh.org>), available at
+archive available at
 uref(https://www.zsh.org/mla/).
 texinode(The Zsh FAQ)(The Zsh Web Page)(Mailing Lists)(Introduction)
 sect(The Zsh FAQ)
@@ -82,12 +86,11 @@ Zsh has a list of Frequently Asked Questions (FAQ), maintained by
 Peter Stephenson tt(<pws@zsh.org>).  It is regularly posted to the
 newsgroup bf(comp.unix.shell) and the bf(zsh-announce) mailing list.
 The latest version can be found at any of the Zsh FTP sites, or at
-uref(http://www.zsh.org/FAQ/).  The contact address for FAQ-related matters
+uref(https://www.zsh.org/FAQ/).  The contact address for FAQ-related matters
 is tt(<faqmaster@zsh.org>).
 texinode(The Zsh Web Page)(The Zsh Userguide)(The Zsh FAQ)(Introduction)
 sect(The Zsh Web Page)
-Zsh has a web page which is located at uref(https://www.zsh.org/).  This is
-maintained by Karsten Thygesen tt(<karthy@zsh.org>), of SunSITE Denmark.
+Zsh has a web page which is located at uref(https://www.zsh.org/).
 The contact address for web-related matters is tt(<webmaster@zsh.org>).
 texinode(The Zsh Userguide)(See Also)(The Zsh Web Page)(Introduction)
 sect(The Zsh Userguide)
@@ -95,6 +98,6 @@ A userguide is currently in preparation.  It is intended to complement the
 manual, with explanations and hints on issues where the manual can be
 cabbalistic, hierographic, or downright mystifying (for example, the word
 `hierographic' does not exist).  It can be viewed in its current state at
-uref(http://zsh.sourceforge.net/Guide/).  At the time of writing, chapters
+uref(https://zsh.sourceforge.io/Guide/).  At the time of writing, chapters
 dealing with startup files and their contents and the new completion system
 were essentially complete.
diff --git a/Doc/Zsh/mod_curses.yo b/Doc/Zsh/mod_curses.yo
index 6e4831abe..e2d5690e2 100644
--- a/Doc/Zsh/mod_curses.yo
+++ b/Doc/Zsh/mod_curses.yo
@@ -157,7 +157,7 @@ input.  This is only available with the ncurses library; mouse handling
 can be detected by checking for the exit status of `tt(zcurses mouse)' with
 no arguments.  If a mouse
 button is clicked (or double- or triple-clicked, or pressed or released with
-a configurable delay from being clicked) then tt(kparam) is set to the string
+a configurable delay from being clicked) then var(kparam) is set to the string
 tt(MOUSE), and var(mparam) is set to an array consisting of the
 following elements:
 startitem()
diff --git a/Doc/Zsh/mod_datetime.yo b/Doc/Zsh/mod_datetime.yo
index da65a9bbd..853656128 100644
--- a/Doc/Zsh/mod_datetime.yo
+++ b/Doc/Zsh/mod_datetime.yo
@@ -6,8 +6,8 @@ The tt(zsh/datetime) module makes available one builtin command:
 startitem()
 findex(strftime)
 cindex(date string, printing)
-xitem(tt(strftime) [ tt(-s) var(scalar) ] var(format) [ var(epochtime) [ var(nanoseconds) ] ] )
-item(tt(strftime) tt(-r) [ tt(-q) ] [ tt(-s) var(scalar) ] var(format) var(timestring) )(
+xitem(tt(strftime) [ tt(-s) var(scalar) | tt(-n) ] var(format) [ var(epochtime) [ var(nanoseconds) ] ] )
+item(tt(strftime) tt(-r) [ tt(-q) ] [ tt(-s) var(scalar) | tt(-n) ] var(format) var(timestring) )(
 Output the date in the var(format) specified.  With no var(epochtime), the
 current system date/time is used; optionally, var(epochtime) may be used to
 specify the number of seconds since the epoch, and var(nanoseconds) may
@@ -18,6 +18,9 @@ ifzman(the section EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\
 ifnzman(noderef(Prompt Expansion)) are also available.
 
 startitem()
+item(tt(-n))(
+Suppress printing a newline after the formatted string.
+)
 item(tt(-q))(
 Run quietly; suppress printing of all error messages described below.
 Errors for invalid var(epochtime) values are always printed.
diff --git a/Doc/Zsh/mod_mapfile.yo b/Doc/Zsh/mod_mapfile.yo
index 640beeb12..9d8f07214 100644
--- a/Doc/Zsh/mod_mapfile.yo
+++ b/Doc/Zsh/mod_mapfile.yo
@@ -13,7 +13,7 @@ value is the content of the file.  The value is treated identically to any
 other text coming from a parameter.  The value may also be assigned to, in
 which case the file in question is written (whether or not it originally
 existed); or an element may be unset, which will delete the file in
-question.  For example, `tt(vared mapfile[myfile])' works as expected,
+question.  For example, `tt(vared 'mapfile[myfile]')' works as expected,
 editing the file `tt(myfile)'.
 
 When the array is accessed as a whole, the keys are the names of files in
diff --git a/Doc/Zsh/mod_newuser.yo b/Doc/Zsh/mod_newuser.yo
index 92a64a013..7937e43c3 100644
--- a/Doc/Zsh/mod_newuser.yo
+++ b/Doc/Zsh/mod_newuser.yo
@@ -44,4 +44,4 @@ even if the tt(zsh/newuser) module is disabled.  Note, however, that
 if the module is not installed the function will not be installed either.
 The function is documented in
 ifnzman(noderef(User Configuration Functions))\
-ifzman(the section User Configuration Functions in zmanref(zshcontrib)).
+ifzman(the section `User Configuration Functions' in zmanref(zshcontrib)).
diff --git a/Doc/Zsh/mod_parameter.yo b/Doc/Zsh/mod_parameter.yo
index 2e3011e44..f3bcd7957 100644
--- a/Doc/Zsh/mod_parameter.yo
+++ b/Doc/Zsh/mod_parameter.yo
@@ -165,6 +165,8 @@ The keys of the associative arrays are usually valid job numbers,
 and these are the values output with, for example, tt(${(k)jobdirs}).
 Non-numeric job references may be used when looking up a value;
 for example, tt(${jobdirs[%+]}) refers to the current job.
+
+See the tt(jobs) builtin for how job information is provided in a subshell.
 )
 vindex(jobtexts)
 item(tt(jobtexts))(
@@ -173,6 +175,8 @@ that were used to start the jobs.
 
 Handling of the keys of the associative array is as described for
 tt(jobdirs) above.
+
+See the tt(jobs) builtin for how job information is provided in a subshell.
 )
 vindex(jobstates)
 item(tt(jobstates))(
@@ -189,6 +193,8 @@ the var(state) describes the state of that process.
 
 Handling of the keys of the associative array is as described for
 tt(jobdirs) above.
+
+See the tt(jobs) builtin for how job information is provided in a subshell.
 )
 vindex(nameddirs)
 item(tt(nameddirs))(
diff --git a/Doc/Zsh/mod_private.yo b/Doc/Zsh/mod_private.yo
index 78aee0acf..184fa2be8 100644
--- a/Doc/Zsh/mod_private.yo
+++ b/Doc/Zsh/mod_private.yo
@@ -10,12 +10,16 @@ ifnzman()
 startitem()
 findex(private)
 cindex(private parameter, creating)
-item(tt(private) [ {tt(PLUS())|tt(-)}tt(AHUahlprtux) ] \
+item(tt(private) [ {tt(PLUS())|tt(-)}tt(AHUahlmrtux) ] \
 [ {tt(PLUS())|tt(-)}tt(EFLRZi) [ var(n) ] ] [ var(name)[tt(=)var(value)] ... ])(
 The tt(private) builtin accepts all the same options and arguments as tt(local)
 (ifzman(zmanref(zshbuiltins))ifnzman(noderef(Shell Builtin Commands))) except
 for the `tt(-)tt(T)' option.  Tied parameters may not be made private.
 
+The `tt(-)tt(p)' option is presently a no-op because the state of
+private parameters cannot reliably be reloaded.  This also applies
+to printing private parameters with `tt(typeset -p)'.
+
 If used at the top level (outside a function scope), tt(private) creates a
 normal parameter in the same manner as tt(declare) or tt(typeset).  A
 warning about this is printed if tt(WARN_CREATE_GLOBAL) is set
@@ -75,7 +79,8 @@ itemiz(Within any other function called by the declaring function, the
 private parameter does em(NOT) hide other parameters of the same name, so
 for example a global parameter of the same name is visible and may be
 assigned or unset.  This includes calls to anonymous functions, although
-that may also change in the future.)
+that may also change in the future.  However, the private name may not be
+created outside the local scope when it was not previously declared.)
 itemiz(An exported private remains in the environment of inner scopes but
 appears unset for the current shell in those scopes.  Generally, exporting
 private parameters should be avoided.)
diff --git a/Doc/Zsh/mod_regex.yo b/Doc/Zsh/mod_regex.yo
index f20451664..40ee92785 100644
--- a/Doc/Zsh/mod_regex.yo
+++ b/Doc/Zsh/mod_regex.yo
@@ -26,5 +26,17 @@ tt(-regex-match) operator.
 
 If tt(BASH_REMATCH) is set, then the array tt(BASH_REMATCH) will be set
 instead of tt(MATCH) and tt(match).
+
+Note that the tt(zsh/regex) module logic relies on the host system. The 
+same var(expr) and var(regex) pair could produce different results on different
+platforms if a var(regex) with non-standard syntax is given.
+
+For example, no syntax for matching a word boundary is defined in the POSIX
+extended regular expression standard. GNU tt(libc) and BSD tt(libc) both provide 
+such syntaxes as extensions (tt(\b) and tt([[:<:]])/tt([[:>:]]) respectively), 
+but neither of these syntaxes is supported by both of these implementations.
+
+Refer to the manref(regcomp)(3) and manref(re_format)(7) manual pages on your
+system for locally-supported syntax.
 )
 enditem()
diff --git a/Doc/Zsh/mod_stat.yo b/Doc/Zsh/mod_stat.yo
index 9caed1e45..b591d4003 100644
--- a/Doc/Zsh/mod_stat.yo
+++ b/Doc/Zsh/mod_stat.yo
@@ -118,6 +118,8 @@ formatting of the time elements.  The format string supports all of the
 zsh extensions described in
 ifzman(the section EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\
 ifnzman(noderef(Prompt Expansion)).
+In particular, tt(-F %s.%N) can be used to show timestamps with nanosecond
+precision if supported by the system.
 The tt(-s) option is implied.
 )
 item(tt(-g))(
diff --git a/Doc/Zsh/mod_system.yo b/Doc/Zsh/mod_system.yo
index 6292af071..884c3e753 100644
--- a/Doc/Zsh/mod_system.yo
+++ b/Doc/Zsh/mod_system.yo
@@ -62,6 +62,9 @@ suppress updating of the file atime
 item(tt(nofollow))(
 fail if var(file) is a symbolic link
 )
+item(tt(nonblock))(
+the file is opened in nonblocking mode
+)
 item(tt(sync))(
 request that writes wait until data has been physically written
 )
@@ -166,7 +169,7 @@ to the command, or 2 for an error on the write; no error message is
 printed in the last case, but the parameter tt(ERRNO) will reflect
 the error that occurred.
 )
-xitem(tt(zsystem flock) [ tt(-t) var(timeout) ] [ tt(-f) var(var) ] [tt(-er)] var(file))
+xitem(tt(zsystem flock) [ tt(-t) var(timeout) ] [ tt(-i) var(interval) ] [ tt(-f) var(var) ] [tt(-er)] var(file))
 item(tt(zsystem flock -u) var(fd_expr))(
 The builtin tt(zsystem)'s subcommand tt(flock) performs advisory file
 locking (via the manref(fcntl)(2) system call) over the entire contents
@@ -196,9 +199,16 @@ a safety check that the file descriptor is in use for file locking.
 
 By default the shell waits indefinitely for the lock to succeed.
 The option tt(-t) var(timeout) specifies a timeout for the lock in
-seconds; currently this must be an integer.  The shell will attempt
-to lock the file once a second during this period.  If the attempt
-times out, status 2 is returned.
+seconds; fractional seconds are allowed.  During this period, the
+shell will attempt to lock the file every var(interval) seconds
+if the tt(-i) var(interval) option is given, otherwise once a second.
+(This var(interval) is shortened before the last attempt if needed,
+so that the shell waits only until the var(timeout) and not longer.)
+If the attempt times out, status 2 is returned.
+
+(Note: var(timeout) is limited to 2^30-1 seconds (about 34 years), and
+var(interval) to 0.999 * LONG_MAX microseconds (only about 35 minutes
+on 32-bit systems).)
 
 If the option tt(-e) is given, the file descriptor for the lock is
 preserved when the shell uses tt(exec) to start a new process;
@@ -256,9 +266,9 @@ tt($$), which returns the process ID of the main shell process.
 )
 item(tt(ppid))(
 vindex(ppid, sysparams)
-Returns the process ID of the parent of the current process, even in
-subshells.  Compare tt($PPID), which returns the process ID of the parent
-of the main shell process.
+Returns the current process ID of the parent of the current process, even
+in subshells.  Compare tt($PPID), which returns the process ID of the
+initial parent of the main shell process.
 )
 item(tt(procsubstpid))(
 Returns the process ID of the last process started for process
diff --git a/Doc/Zsh/mod_watch.yo b/Doc/Zsh/mod_watch.yo
new file mode 100644
index 000000000..d97a41d13
--- /dev/null
+++ b/Doc/Zsh/mod_watch.yo
@@ -0,0 +1,146 @@
+COMMENT(!MOD!zsh/watch
+Reporting of login and logout events.
+!MOD!)
+The tt(zsh/watch) module can be used to report when specific users log in or
+out. This is controlled via the following parameters.
+
+startitem()
+vindex(LOGCHECK)
+item(tt(LOGCHECK))(
+The interval in seconds between checks for login/logout activity
+using the tt(watch) parameter.
+)
+vindex(watch)
+vindex(WATCH)
+item(tt(watch) <S> <Z> (tt(WATCH) <S>))(
+An array (colon-separated list) of login/logout events to report.
+
+If it contains the single word `tt(all)', then all login/logout events
+are reported.  If it contains the single word `tt(notme)', then all
+events are reported as with `tt(all)' except tt($USERNAME).
+
+An entry in this list may consist of a username,
+an `tt(@)' followed by a remote hostname,
+and a `tt(%)' followed by a line (tty).  Any of these may
+be a pattern (be sure to quote this during the assignment to
+tt(watch) so that it does not immediately perform file generation);
+the setting of the tt(EXTENDED_GLOB) option is respected.
+Any or all of these components may be present in an entry;
+if a login/logout event matches all of them,
+it is reported.
+
+For example, with the tt(EXTENDED_GLOB) option set, the following:
+
+example(watch=('^(pws|barts)'))
+
+causes reports for activity associated with any user other than tt(pws)
+or tt(barts).
+)
+vindex(WATCHFMT)
+item(tt(WATCHFMT))(
+The format of login/logout reports if the tt(watch) parameter is set.
+Default is `tt(%n has %a %l from %m)'.
+Recognizes the following escape sequences:
+
+startitem()
+item(tt(%n))(
+The name of the user that logged in/out.
+)
+item(tt(%a))(
+The observed action, i.e. "logged on" or "logged off".
+)
+item(tt(%l))(
+The line (tty) the user is logged in on.
+)
+item(tt(%M))(
+The full hostname of the remote host.
+)
+item(tt(%m))(
+The hostname up to the first `tt(.)'.  If only the
+IP address is available or the utmp field contains
+the name of an X-windows display, the whole name is printed.
+
+em(NOTE:)
+The `tt(%m)' and `tt(%M)' escapes will work only if there is a host name
+field in the utmp on your machine.  Otherwise they are
+treated as ordinary strings.
+)
+item(tt(%F{)var(color)tt(}) LPAR()tt(%f)RPAR())(
+Start (stop) using a different foreground color.
+)
+item(tt(%K{)var(color)tt(}) LPAR()tt(%k)RPAR())(
+Start (stop) using a different background color.
+)
+item(tt(%S) LPAR()tt(%s)RPAR())(
+Start (stop) standout mode.
+)
+item(tt(%U) LPAR()tt(%u)RPAR())(
+Start (stop) underline mode.
+)
+item(tt(%B) LPAR()tt(%b)RPAR())(
+Start (stop) boldface mode.
+)
+xitem(tt(%t))
+item(tt(%@))(
+The time, in 12-hour, am/pm format.
+)
+item(tt(%T))(
+The time, in 24-hour format.
+)
+item(tt(%w))(
+The date in `var(day)tt(-)var(dd)' format.
+)
+item(tt(%W))(
+The date in `var(mm)tt(/)var(dd)tt(/)var(yy)' format.
+)
+item(tt(%D))(
+The date in `var(yy)tt(-)var(mm)tt(-)var(dd)' format.
+)
+item(tt(%D{)var(string)tt(}))(
+The date formatted as var(string) using the tt(strftime) function, with
+zsh extensions as described by
+ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\
+ifnzman(noderef(Prompt Expansion)).
+)
+item(tt(%LPAR())var(x)tt(:)var(true-text)tt(:)var(false-text)tt(RPAR()))(
+Specifies a ternary expression.
+The character following the var(x) is
+arbitrary; the same character is used to separate the text
+for the "true" result from that for the "false" result.
+Both the separator and the right parenthesis may be escaped
+with a backslash.
+Ternary expressions may be nested.
+
+The test character var(x) may be any one of `tt(l)', `tt(n)', `tt(m)'
+or `tt(M)', which indicate a `true' result if the corresponding
+escape sequence would return a non-empty value; or it may be `tt(a)',
+which indicates a `true' result if the watched user has logged in,
+or `false' if he has logged out.
+Other characters evaluate to neither true nor false; the entire
+expression is omitted in this case.
+
+If the result is `true', then the var(true-text)
+is formatted according to the rules above and printed,
+and the var(false-text) is skipped.
+If `false', the var(true-text) is skipped and the var(false-text)
+is formatted and printed.
+Either or both of the branches may be empty, but
+both separators must be present in any case.
+)
+enditem()
+)
+enditem()
+
+Furthermore, the tt(zsh/watch) module makes available one builtin
+command:
+
+startitem()
+findex(log)
+vindex(watch, use of)
+cindex(watching users)
+cindex(users, watching)
+item(tt(log))(
+List all users currently logged in who are affected by
+the current setting of the tt(watch) parameter.
+)
+enditem()
diff --git a/Doc/Zsh/mod_zselect.yo b/Doc/Zsh/mod_zselect.yo
index e0651571e..faf59c165 100644
--- a/Doc/Zsh/mod_zselect.yo
+++ b/Doc/Zsh/mod_zselect.yo
@@ -12,7 +12,7 @@ The tt(zselect) builtin is a front-end to the `select' system call, which
 blocks until a file descriptor is ready for reading or writing, or has an
 error condition, with an optional timeout.  If this is not available on
 your system, the command prints an error message and returns status 2
-(normal errors return status 1).  For more information, see your systems
+(normal errors return status 1).  For more information, see your system's
 documentation for manref(select)(3).  Note there is no connection with the
 shell builtin of the same name.
 
diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
index 24aebdfaf..3cf9e5028 100644
--- a/Doc/Zsh/mod_zutil.yo
+++ b/Doc/Zsh/mod_zutil.yo
@@ -32,20 +32,27 @@ If two patterns are equally specific, the tie is broken in favour of
 the pattern that was defined first.
 
 em(Example)
+kindex(preferred-precipitation, example style)
+findex(weather, example function)
 
-For example, to define your preferred form of precipitation depending on which
-city you're in, you might set the following in your tt(zshrc):
+For example, a fictional `tt(weather)' plugin might state in its documentation
+that it looks up the tt(preferred-precipitation) style under the
+`tt(:weather:)var(continent)tt(:)var(day-of-the-week)tt(:)var(phase-of-the-moon)' context.
+According to this, you might set the following in your tt(zshrc):
 
 example(zstyle ':weather:europe:*' preferred-precipitation rain
-zstyle ':weather:europe:germany:* preferred-precipitation none
-zstyle ':weather:europe:germany:*:munich' preferred-precipitation snow)
+zstyle ':weather:*:Sunday:*' preferred-precipitation snow)
 
-Then, the fictional `tt(weather)' plugin might run under the hood a command
-such as
+Then the plugin would run under the hood a command such as
 
-example(zstyle -s ":weather:${continent}:${country}:${county}:${city}" preferred-precipitation REPLY)
+example(zstyle -s ":weather:${continent}:${day_of_week}:${moon_phase}" preferred-precipitation REPLY)
 
 in order to retrieve your preference into the scalar variable tt($REPLY).
+On Sundays tt($REPLY) would be set to `tt(snow)'; in Europe it would be set
+to `tt(rain)'; and on Sundays in Europe it would be set to `tt(snow)' again,
+because the patterns `tt(:weather:europe:*)' and `tt(:weather:*:Sunday:*)' both
+match the var(context) argument to tt(zstyle -s), are equally specific, and the
+latter is more specific (because it has more colon-separated components).
 
 em(Usage)
 
@@ -143,8 +150,9 @@ enditem()
 )
 findex(zformat)
 xitem(tt(zformat -f) var(param) var(format) var(spec) ...)
+xitem(tt(zformat -F) var(param) var(format) var(spec) ...)
 item(tt(zformat -a) var(array) var(sep) var(spec) ...)(
-This builtin provides two different forms of formatting. The first form 
+This builtin provides different forms of formatting. The first form
 is selected with the tt(-f) option. In this case the var(format)
 string will be modified by replacing sequences starting with a percent 
 sign in it with strings from the var(spec)s.  Each var(spec) should be
@@ -188,7 +196,13 @@ outputs "The answer is 'yes'." to tt(REPLY) since the value for the format
 specifier tt(c) is 3, agreeing with the digit argument to the ternary
 expression.
 
-The second form, using the tt(-a) option, can be used for aligning
+With tt(-F) instead of tt(-f), ternary expressions choose between the
+`true' or `false' text on the basis of whether the format specifier is
+present and non-empty.  A test number indicates a minimum width for the
+value given in the format specifier. Negative numbers reverse this,
+so the test is for whether the value exceeds a maximum width.
+
+The form, using the tt(-a) option, can be used for aligning
 strings.  Here, the var(spec)s are of the form
 `var(left)tt(:)var(right)' where `var(left)' and `var(right)' are
 arbitrary strings.  These strings are modified by replacing the colons
diff --git a/Doc/Zsh/modlist.yo b/Doc/Zsh/modlist.yo
index 484321e69..d066879a9 100644
--- a/Doc/Zsh/modlist.yo
+++ b/Doc/Zsh/modlist.yo
@@ -87,6 +87,9 @@ Interface to the termcap database.
 item(tt(zsh/terminfo))(
 Interface to the terminfo database.
 )
+item(tt(zsh/watch))(
+Reporting of login and logout events.
+)
 item(tt(zsh/zftp))(
 A builtin FTP client.
 )
@@ -195,10 +198,13 @@ includefile(Zsh/mod_tcp.yo)

 texinode(The zsh/termcap Module)(The zsh/terminfo Module)(The zsh/net/tcp Module)(Zsh Modules)
 sect(The zsh/termcap Module)
 includefile(Zsh/mod_termcap.yo)

-texinode(The zsh/terminfo Module)(The zsh/zftp Module)(The zsh/termcap Module)(Zsh Modules)
+texinode(The zsh/terminfo Module)(The zsh/watch Module)(The zsh/termcap Module)(Zsh Modules)
 sect(The zsh/terminfo Module)
 includefile(Zsh/mod_terminfo.yo)

-texinode(The zsh/zftp Module)(The zsh/zle Module)(The zsh/terminfo Module)(Zsh Modules)
+texinode(The zsh/watch Module)(The zsh/zftp Module)(The zsh/terminfo Module)(Zsh Modules)
+sect(The zsh/watch Module)
+includefile(Zsh/mod_watch.yo)

+texinode(The zsh/zftp Module)(The zsh/zle Module)(The zsh/watch Module)(Zsh Modules)
 sect(The zsh/zftp Module)
 includefile(Zsh/mod_zftp.yo)

 texinode(The zsh/zle Module)(The zsh/zleparameter Module)(The zsh/zftp Module)(Zsh Modules)
diff --git a/Doc/Zsh/modmenu.yo b/Doc/Zsh/modmenu.yo
index 2d29b6e96..c922390a4 100644
--- a/Doc/Zsh/modmenu.yo
+++ b/Doc/Zsh/modmenu.yo
@@ -28,6 +28,7 @@ menu(The zsh/system Module)
 menu(The zsh/net/tcp Module)
 menu(The zsh/termcap Module)
 menu(The zsh/terminfo Module)
+menu(The zsh/watch Module)
 menu(The zsh/zftp Module)
 menu(The zsh/zle Module)
 menu(The zsh/zleparameter Module)
diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo
index fdea51412..443676b78 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -41,6 +41,9 @@ 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.
 
+It is possible for options to be set within a function scope.  See the
+description of the option tt(LOCAL_OPTIONS) below.
+
 texinode(Description of Options)(Option Aliases)(Specifying Options)(Options)
 sect(Description of Options)
 cindex(options, description)
@@ -474,6 +477,22 @@ item(tt(CASE_MATCH) <D>)(
 Make regular expressions using the tt(zsh/regex) module (including
 matches with tt(=~)) sensitive to case.
 )
+pindex(CASE_PATHS)
+pindex(NO_CASE_PATHS)
+pindex(CASEPATHS)
+pindex(NOCASEPATHS)
+cindex(case-sensitive globbing, option)
+item(tt(CASE_PATHS))(
+If tt(CASE_PATHS) is not set (the default), tt(CASE_GLOB) affects the
+interpretation of em(every) path component, whenever a special
+character appears in em(any) component.  When tt(CASE_PATHS) is set,
+file path components that do em(not) contain special filename
+generation characters are always sensitive to case, thus restricting
+tt(NO_CASE_GLOB) to components that contain globbing characters.
+
+Note that if the filesystem itself is not sensitive to case, then
+tt(CASE_PATHS) has no effect.
+)
 pindex(CSH_NULL_GLOB)
 pindex(NO_CSH_NULL_GLOB)
 pindex(CSHNULLGLOB)
@@ -586,7 +605,7 @@ Substitutions using the tt(:s) and tt(:&) history modifiers are performed
 with pattern matching instead of string matching.  This occurs wherever
 history modifiers are valid, including glob qualifiers and parameters.
 See
-ifzman(the section Modifiers in zmanref(zshexpn))\
+ifzman(the section `Modifiers' in zmanref(zshexpn))\
 ifnzman(noderef(Modifiers)).
 )
 pindex(IGNORE_BRACES)
@@ -1124,7 +1143,7 @@ pindex(GLOBALRCS)
 pindex(NOGLOBALRCS)
 cindex(startup files, global, inhibiting)
 cindex(files, global startup, inhibiting)
-item(tt(GLOBAL_RCS) (tt(-d)) <D>)(
+item(tt(GLOBAL_RCS) (tt(+d)) <D>)(
 If this option is unset, the startup files tt(zprofile()),
 tt(zshrc()), tt(zlogin()) and tt(zlogout()) will not be run.  It
 can be disabled and re-enabled at any time, including inside local startup
@@ -1168,6 +1187,22 @@ If the option is not set, and the option tt(APPEND_CREATE) is also
 not set, `tt(>>!)' or `tt(>>|)' must be used to create a file.
 If either option is set, `tt(>>)' may be used.
 )
+pindex(CLOBBER_EMPTY)
+pindex(NO_CLOBBER_EMPTY)
+pindex(CLOBBEREMPTY)
+pindex(NOCLOBBEREMPTY)
+cindex(clobbering, of empty files)
+cindex(file clobbering, of empty files)
+item(tt(CLOBBER_EMPTY))(
+This option is only used if the option tt(CLOBBER) is not set: note that
+it is set by default.
+
+If this option is set, then regular files of zero length may be
+ovewritten (`clobbered').  Note that it is possible another process
+has written to the file between this test and use of the file by
+the current process.  This option should therefore not be used in
+cases where files to be clobbered may be written to asynchronously.
+)
 pindex(CORRECT)
 pindex(NO_CORRECT)
 pindex(NOCORRECT)
@@ -1377,6 +1412,14 @@ item(tt(SHORT_LOOPS) <C> <Z>)(
 Allow the short forms of tt(for), tt(repeat), tt(select),
 tt(if), and tt(function) constructs.
 )
+pindex(SHORT_REPEAT)
+pindex(NO_SHORT_REPEAT)
+pindex(SHORTREPEAT)
+pindex(NOSHORTREPEAT)
+item(tt(SHORT_REPEAT))(
+Allow the short form tt(repeat) as tt(SHORT_LOOPS) but without enabling
+it for the other constructs.
+)
 pindex(SUN_KEYBOARD_HACK)
 pindex(NO_SUN_KEYBOARD_HACK)
 pindex(SUNKEYBOARDHACK)
@@ -1443,7 +1486,7 @@ The check is omitted if the commands run from the previous command line
 included a `tt(jobs)' command, since it is assumed the user is aware that
 there are background or suspended jobs.  A `tt(jobs)' command run from one
 of the hook functions defined in
-ifnzman(the section Special Functions in noderef(Functions))\
+ifnzman(the section `Special Functions' in noderef(Functions))\
 ifzman(the section SPECIAL FUNCTIONS in zmanref(zshmisc))
 is not counted for this purpose.
 )
@@ -1902,6 +1945,16 @@ If the option is set, they will only be shown when parameters are selected
 with the `tt(-m)' option.  The option `tt(-p)' is available whether or not
 the option is set.
 )
+pindex(TYPESET_TO_UNSET)
+pindex(NO_TYPESET_TO_UNSET)
+pindex(TYPESETTOUNSET)
+pindex(NOTYPESETTOUNSET)
+item(tt(TYPESET_TO_UNSET) <K> <S>)(
+When declaring a new parameter with any of the `tt(typeset)' family of
+related commands, the parameter remains unset unless and until a
+value is explicity assigned to it, either in the `tt(typeset)' command
+itself or as a later assignment statement.
+)
 pindex(VERBOSE)
 pindex(NO_VERBOSE)
 pindex(NOVERBOSE)
@@ -2199,7 +2252,8 @@ command found in the path.
 
 Furthermore, the tt(getopts) builtin behaves in a POSIX-compatible
 fashion in that the associated variable tt(OPTIND) is not made
-local to functions.
+local to functions, and its value is calculated differently to match
+other shells.
 
 Moreover, the warning and special exit code from
 tt([[ -o )var(non_existent_option)tt( ]]) are suppressed.
@@ -2279,10 +2333,15 @@ When this option is set, the usual zsh behaviour of executing
 traps for tt(EXIT) on exit from shell functions is suppressed.
 In that case, manipulating tt(EXIT) traps always alters the global
 trap for exiting the shell; the tt(LOCAL_TRAPS) option is
-ignored for the tt(EXIT) trap.  Furthermore, a tt(return) statement
-executed in a trap with no argument passes back from the function the
-value from the surrounding context, not from code executed within the
-trap.
+ignored for the tt(EXIT) trap.
+
+Also, a tt(return) statement executed in a trap with no argument passes
+back from the function the value from the surrounding context, not from
+code executed within the trap.
+
+Furthermore, if a trap is set to be ignored, this state persists when
+a subshell is entered.  Without the option, the trap would be reset to
+its default state at this point.
 )
 pindex(SH_FILE_EXPANSION)
 pindex(NO_SH_FILE_EXPANSION)
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index 8daf33d5e..6d2d41b7a 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -106,7 +106,7 @@ may be in any order.  Note that this syntax is strict: tt([) and tt(]=) must
 not be quoted, and var(key) may not consist of the unquoted string
 tt(]=), but is otherwise treated as a simple string.  The enhanced forms
 of subscript expression that may be used when directly subscripting a
-variable name, described in the section Array Subscripts below, are not
+variable name, described in the section `Array Subscripts' below, are not
 available.
 
 The syntaxes with and without the explicit key may be mixed.  An implicit
@@ -393,12 +393,21 @@ is compared to the pattern, and the first matching key found is the
 result.  On failure substitutes the length of the array plus one, as
 discussed under the description of `tt(r)', or the empty string for an
 associative array.
+
+Note: Although `tt(i)' may be applied to a scalar substitution to find
+the offset of a substring, the results are likely to be misleading when
+searching within substitutions that yield an empty string, or when
+searching for the empty substring.
 )
 item(tt(I))(
 Like `tt(i)', but gives the index of the last match, or all possible
 matching keys in an associative array.  On failure substitutes 0, or
 the empty string for an associative array.  This flag is best when
 testing for values or keys that do not exist.
+
+Note: If the option tt(KSH_ARRAYS) is in effect and no match is found, the
+result is indistinguishable from the case when the first element of the array
+matches.
 )
 item(tt(k))(
 If used in a subscript on an associative array, this flag causes the keys
@@ -623,6 +632,14 @@ In the parameter lists that follow, the mark `<S>' indicates that the
 parameter is special.  `<Z>' indicates that the parameter does not exist
 when the shell initializes in tt(sh) or tt(ksh) emulation mode.
 
+The parameters `tt(!)', `tt(#)', `tt(*)', `tt(-)', `tt(?)', `tt(@)',
+`tt($)', `tt(ARGC)', `tt(HISTCMD)', `tt(LINENO)', `tt(PPID)',
+`tt(status)', `tt(TTYIDLE)', `tt(zsh_eval_context)',
+`tt(ZSH_EVAL_CONTEXT)', and `tt(ZSH_SUBSHELL)' are read-only and thus
+cannot be restored by the user, so they are not output by
+`tt(typeset -p)'.  This also applies to many read-only parameters loaded
+from modules.
+
 The following parameters are automatically set by the shell:
 
 startitem()
@@ -645,10 +662,11 @@ Same as tt(#).
 )
 vindex($)
 item(tt($) <S>)(
-The process ID of this shell.  Note that this indicates the original
-shell started by invoking tt(zsh); all processes forked from the shells
-without executing a new program, such as subshells started by
-tt(LPAR())var(...)tt(RPAR()), substitute the same value.
+The process ID of this shell, set when the shell initializes.  Processes
+forked from the shell without executing a new program, such as command
+substitutions and commands grouped with tt(LPAR())var(...)tt(RPAR()),
+are subshells that duplicate the current shell, and thus substitute the
+same value for tt($$) as their parent shell.
 )
 vindex(-)
 item(tt(-) <S>)(
@@ -727,7 +745,7 @@ explicitly set locally.
 )
 vindex(ERRNO)
 item(tt(ERRNO) <S>)(
-The value of errno (see manref(errno)(3))
+The value of tt(errno) (see manref(errno)(3))
 as set by the most recently failed system call.
 This value is system dependent and is intended for debugging
 purposes.  It is also useful with the tt(zsh/system) module which
@@ -808,9 +826,9 @@ The operating system, as determined at compile time.
 )
 vindex(PPID)
 item(tt(PPID) <S>)(
-The process ID of the parent of the shell.  As for tt($$), the
-value indicates the parent of the original shell and does not
-change in subshells.
+The process ID of the parent of the shell, set when the shell initializes.
+As with tt($$), the value does not change in subshells created as a
+duplicate of the current shell.
 )
 vindex(PWD)
 item(tt(PWD))(
@@ -836,8 +854,9 @@ will be the value that was assigned plus the number of seconds
 since the assignment.
 
 Unlike other special parameters, the type of the tt(SECONDS) parameter can
-be changed using the tt(typeset) command.  Only integer and one of the
-floating point types are allowed.  For example, `tt(typeset -F SECONDS)'
+be changed using the tt(typeset) command.  The type may be changed only
+to one of the floating point types or back to integer.  For example,
+`tt(typeset -F SECONDS)'
 causes the value to be reported as a floating point number.  The
 value is available to microsecond accuracy, although the shell may
 show more or fewer digits depending on the use of tt(typeset).  See
@@ -1313,11 +1332,6 @@ most as many lines as given by the absolute value.
 If set to zero, the shell asks only if the top of the listing would scroll
 off the screen.
 )
-vindex(LOGCHECK)
-item(tt(LOGCHECK))(
-The interval in seconds between checks for login/logout activity
-using the tt(watch) parameter.
-)
 vindex(MAIL)
 item(tt(MAIL))(
 If this parameter is set and tt(mailpath) is not set,
@@ -1556,6 +1570,11 @@ if it is in the environment of the shell but not explicitly assigned to in
 the input line. This avoids running stty at every external command by
 accidentally exporting it. Also note that tt(STTY) should not be used for
 window size specifications; these will not be local to the command.
+
+If the parameter is set and empty, all of the above applies except
+that tt(stty) is not run. This can be useful as a way to freeze the tty
+around a single command, blocking its changes to tty settings,
+similar to the tt(ttyctl) builtin.
 )
 vindex(TERM)
 item(tt(TERM) <S>)(
@@ -1651,119 +1670,6 @@ to be interpreted as a file extension.  The default is not to append
 any suffix, thus this parameter should be assigned only when needed
 and then unset again.
 )
-vindex(watch)
-vindex(WATCH)
-item(tt(watch) <S> <Z> (tt(WATCH) <S>))(
-An array (colon-separated list) of login/logout events to report.
-
-If it contains the single word `tt(all)', then all login/logout events
-are reported.  If it contains the single word `tt(notme)', then all
-events are reported as with `tt(all)' except tt($USERNAME).
-
-An entry in this list may consist of a username,
-an `tt(@)' followed by a remote hostname,
-and a `tt(%)' followed by a line (tty).  Any of these may
-be a pattern (be sure to quote this during the assignment to
-tt(watch) so that it does not immediately perform file generation);
-the setting of the tt(EXTENDED_GLOB) option is respected.
-Any or all of these components may be present in an entry;
-if a login/logout event matches all of them,
-it is reported.
-
-For example, with the tt(EXTENDED_GLOB) option set, the following:
-
-example(watch=('^(pws|barts)'))
-
-causes reports for activity associated with any user other than tt(pws)
-or tt(barts).
-)
-vindex(WATCHFMT)
-item(tt(WATCHFMT))(
-The format of login/logout reports if the tt(watch) parameter is set.
-Default is `tt(%n has %a %l from %m)'.
-Recognizes the following escape sequences:
-
-startitem()
-item(tt(%n))(
-The name of the user that logged in/out.
-)
-item(tt(%a))(
-The observed action, i.e. "logged on" or "logged off".
-)
-item(tt(%l))(
-The line (tty) the user is logged in on.
-)
-item(tt(%M))(
-The full hostname of the remote host.
-)
-item(tt(%m))(
-The hostname up to the first `tt(.)'.  If only the
-IP address is available or the utmp field contains
-the name of an X-windows display, the whole name is printed.
-
-em(NOTE:)
-The `tt(%m)' and `tt(%M)' escapes will work only if there is a host name
-field in the utmp on your machine.  Otherwise they are
-treated as ordinary strings.
-)
-item(tt(%S) LPAR()tt(%s)RPAR())(
-Start (stop) standout mode.
-)
-item(tt(%U) LPAR()tt(%u)RPAR())(
-Start (stop) underline mode.
-)
-item(tt(%B) LPAR()tt(%b)RPAR())(
-Start (stop) boldface mode.
-)
-xitem(tt(%t))
-item(tt(%@))(
-The time, in 12-hour, am/pm format.
-)
-item(tt(%T))(
-The time, in 24-hour format.
-)
-item(tt(%w))(
-The date in `var(day)tt(-)var(dd)' format.
-)
-item(tt(%W))(
-The date in `var(mm)tt(/)var(dd)tt(/)var(yy)' format.
-)
-item(tt(%D))(
-The date in `var(yy)tt(-)var(mm)tt(-)var(dd)' format.
-)
-item(tt(%D{)var(string)tt(}))(
-The date formatted as var(string) using the tt(strftime) function, with
-zsh extensions as described by
-ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\
-ifnzman(noderef(Prompt Expansion)).
-)
-item(tt(%LPAR())var(x)tt(:)var(true-text)tt(:)var(false-text)tt(RPAR()))(
-Specifies a ternary expression.
-The character following the var(x) is
-arbitrary; the same character is used to separate the text
-for the "true" result from that for the "false" result.
-Both the separator and the right parenthesis may be escaped
-with a backslash.
-Ternary expressions may be nested.
-
-The test character var(x) may be any one of `tt(l)', `tt(n)', `tt(m)'
-or `tt(M)', which indicate a `true' result if the corresponding
-escape sequence would return a non-empty value; or it may be `tt(a)',
-which indicates a `true' result if the watched user has logged in,
-or `false' if he has logged out.
-Other characters evaluate to neither true nor false; the entire
-expression is omitted in this case.
-
-If the result is `true', then the var(true-text)
-is formatted according to the rules above and printed,
-and the var(false-text) is skipped.
-If `false', the var(true-text) is skipped and the var(false-text)
-is formatted and printed.
-Either or both of the branches may be empty, but
-both separators must be present in any case.
-)
-enditem()
-)
 vindex(WORDCHARS)
 item(tt(WORDCHARS) <S>)(
 A list of non-alphanumeric characters considered part of a word
diff --git a/Doc/Zsh/redirect.yo b/Doc/Zsh/redirect.yo
index 2b48974b4..fd40ab5a4 100644
--- a/Doc/Zsh/redirect.yo
+++ b/Doc/Zsh/redirect.yo
@@ -86,7 +86,8 @@ item(tt(<<<) var(word))(
 Perform shell expansion on var(word) and pass the result
 to standard input.  This is known as a em(here-string).
 Compare the use of var(word) in here-documents above, where var(word)
-does not undergo shell expansion.
+does not undergo shell expansion.  The result will have a trailing newline
+after it.
 )
 xitem(tt(<&) var(number))
 item(tt(>&) var(number))(
diff --git a/Doc/Zsh/roadmap.yo b/Doc/Zsh/roadmap.yo
index 94ef74d1f..2db90889b 100644
--- a/Doc/Zsh/roadmap.yo
+++ b/Doc/Zsh/roadmap.yo
@@ -20,7 +20,7 @@ The function is designed to be self-explanatory.  You can run it by hand
 with `tt(autoload -Uz zsh-newuser-install; zsh-newuser-install -f)'.
 See also
 ifnzman(noderef(User Configuration Functions))\
-ifzman(the section User Configuration Functions in zmanref(zshcontrib)).
+ifzman(the section `User Configuration Functions' in zmanref(zshcontrib)).
 
 
 sect(Interactive Use)
@@ -49,7 +49,7 @@ The shell now supports the UTF-8 character set (and also others if
 supported by the operating system).  This is (mostly) handled transparently
 by the shell, but the degree of support in terminal emulators is variable.
 There is some discussion of this in the shell FAQ,
-uref(http://www.zsh.org/FAQ/).  Note in particular that for combining
+uref(https://www.zsh.org/FAQ/).  Note in particular that for combining
 characters to be handled the option tt(COMBINING_CHARS) needs to be set.
 Because the shell is now more sensitive to the definition of the
 character set, note that if you are upgrading from an older version of
diff --git a/Doc/Zsh/zftpsys.yo b/Doc/Zsh/zftpsys.yo
index 349039edc..c2fbdd23f 100644
--- a/Doc/Zsh/zftpsys.yo
+++ b/Doc/Zsh/zftpsys.yo
@@ -518,13 +518,11 @@ command `tt(zstyle ':zftp:*') var(style) var(value) ...'.
 defines the var(style) to have value var(value); more than one value may be
 given, although that is not useful in the cases described here.  These
 values will then be used throughout the zftp function system.  For more
-precise control, the first argument, which gives a context in which the
+precise control, the first argument, which gives a pattern that matches em(contexts) in which the
 style applies, can be modified to include a particular function, as for
 example `tt(:zftp:zfget)': the style will then have the given value only
-in the tt(zfget) function.  Values for the same style in different contexts
-may be set; the most specific function will be used, where
-strings are held to be more specific than patterns, and longer patterns and
-shorter patterns.  Note that only the top level function name, as called by
+in the tt(zfget) function, and will override styles set under `tt(:zftp:*)'.
+Note that only the top level function name, as called by
 the user, is used; calling of lower level functions is transparent to the
 user.  Hence modifications to the title bar in tt(zftp_chpwd) use the
 contexts tt(:zftp:zfopen), tt(:zftp:zfcd), etc., depending where it was
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index c928b8ca2..2d033a0a1 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -50,13 +50,15 @@ argument causes the next command entered to be repeated the specified
 number of times, unless otherwise noted below; this is implemented
 by the tt(digit-argument) widget. See also
 ifzman(the em(Arguments) subsection of the em(Widgets) section )\
-ifnzman(noderef(Arguments) )\
+ifnzman(noderef(Arguments))\
 for some other ways the numeric argument can be modified.
 
 startmenu()
 menu(Keymaps)
 menu(Zle Builtins)
 menu(Zle Widgets)
+menu(User-Defined Widgets)
+menu(Standard Widgets)
 menu(Character Highlighting)
 endmenu()
 
@@ -107,6 +109,7 @@ In the `tt(.safe)' keymap, each single key is bound to tt(self-insert),
 except for ^J (line feed) and ^M (return) which are bound to tt(accept-line).
 This is deliberately not pleasant to use; if you are using it, it
 means you deleted the main keymap, and you should put it back.
+
 subsect(Reading Commands)
 When ZLE is reading a command from the terminal, it may read a sequence
 that is bound to some command and is also a prefix of a longer bound string.
@@ -137,6 +140,7 @@ in user-defined widgets with the tt(read-command) widget, described in
 ifzman(the subsection `Miscellaneous' of the section `Standard Widgets' below)\
 ifnzman(noderef(Miscellaneous) below)\
 .
+
 subsect(Local Keymaps)
 cindex(local keymaps)
 While for normal editing a single keymap is used exclusively, in many
@@ -415,7 +419,7 @@ xitem(tt(zle) tt(-K) var(keymap))
 xitem(tt(zle) tt(-F) [ tt(-L) | tt(-w) ] [ var(fd) [ var(handler) ] ])
 xitem(tt(zle) tt(-I))
 xitem(tt(zle) tt(-T) [ tt(tc) var(function) | tt(-r) tt(tc) | tt(-L) ] )
-item(tt(zle) var(widget) [ tt(-n) var(num) ] [ tt(-Nw) ] [ tt(-K) var(keymap) ] var(args) ...)(
+item(tt(zle) var(widget) [ tt(-n) var(num) ] [ tt(-f) var(flag) ] [ tt(-Nw) ] [ tt(-K) var(keymap) ] var(args) ...)(
 The tt(zle) builtin performs a number of different actions concerning
 ZLE.
 
@@ -501,8 +505,7 @@ ifnzman(noderef(Completion Widgets))\
 .
 )
 item(tt(-R) [ tt(-c) ] [ var(display-string) ] [ var(string) ... ])(
-Redisplay the command line; this is to be called from within a user-defined
-widget to allow changes to become visible.  If a var(display-string) is
+Redisplay the command line.  If a var(display-string) is
 given and not empty, this is shown in the status line (immediately
 below the line being edited).
 
@@ -511,9 +514,9 @@ prompt in the same way as completion lists are printed. If no
 var(string)s are given but the tt(-c) option is used such a list is
 cleared.
 
-Note that this option is only useful for widgets that do not exit
-immediately after using it because the strings displayed will be erased 
-immediately after return from the widget.
+Note that immediately after returning from running widgets, the command line
+will be redisplayed and the strings displayed will be erased.  Therefore, this
+option is only useful for widgets that do not exit immediately after using it.
 
 This command can safely be called outside user defined widgets; if zle is
 active, the display will be refreshed, while if zle is not active, the
@@ -683,7 +686,7 @@ optional argument for debugging or testing.  Note that this
 transformation is not applied to other non-printing characters such as
 carriage returns and newlines.
 )
-item(var(widget) [ tt(-n) var(num) ] [ tt(-Nw) ] [ tt(-K) var(keymap) ] var(args) ...)(
+item(var(widget) [ tt(-n) var(num) ] [ tt(-f) var(flag) ] [ tt(-Nw) ] [ tt(-K) var(keymap) ] var(args) ...)(
 Invoke the specified var(widget).  This can only be done when ZLE is
 active; normally this will be within a user-defined widget.
 
@@ -702,6 +705,9 @@ appears as if the top-level widget called by the user were still
 active.  With the option tt(-w), tt(WIDGET) and related parameters are set
 to reflect the widget being executed by the tt(zle) call.
 
+Normally, when var(widget) returns the special parameter tt(LASTWIDGET) will
+point to it.  This can be inhibited by passing the option tt(-f nolast).
+
 Any further arguments will be passed to the widget; note that as
 standard argument handling is performed, any general argument list
 should be preceded by tt(-)tt(-).  If it is a shell
@@ -726,15 +732,17 @@ enditem()
 )
 enditem()
 
-texinode(Zle Widgets)(Character Highlighting)(Zle Builtins)(Zsh Line Editor)
-sect(Widgets)
+texinode(Zle Widgets)(User-Defined Widgets)(Zle Builtins)(Zsh Line Editor)
+sect(Zle Widgets)
 cindex(widgets)
 All actions in the editor are performed by `widgets'.  A widget's job is
 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.
 
-The standard widgets built into ZLE are listed in Standard Widgets below.
+The standard widgets built into ZLE are listed in
+ifzman(the section `Standard Widgets' below)\
+ifnzman(noderef(Standard Widgets)).
 Other built-in widgets can be defined by other modules (see
 ifzman(zmanref(zshmodules))\
 ifnzman(noderef(Zsh Modules))\
@@ -748,6 +756,8 @@ as shell functions.  When the widget is executed, the corresponding
 shell function is executed, and can perform editing (or other) actions.
 It is recommended that user-defined widgets should not have names
 starting with `tt(.)'.
+
+texinode(User-Defined Widgets)(Standard Widgets)(Zle Widgets)(Zsh Line Editor)
 sect(User-Defined Widgets)
 cindex(widgets, user-defined)
 User-defined widgets, being implemented as shell functions,
@@ -974,27 +984,39 @@ of the non-editable parts of the command line in tt(PREDISPLAY)
 and tt(POSTDISPLAY) are possible, but note that the tt(P) flag
 is needed for character indexing to include tt(PREDISPLAY).
 
-Each string consists of the following parts:
+Each string consists of the following whitespace-separated parts:
 
 startitemize()
 itemiz(Optionally, a `tt(P)' to signify that the start and end offset that
 follow include any string set by the tt(PREDISPLAY) special parameter;
 this is needed if the predisplay string itself is to be highlighted.
-Whitespace may follow the `tt(P)'.)
-itemiz(A start offset in the same units as tt(CURSOR), terminated by
-whitespace.)
-itemiz(An end offset in the same units as tt(CURSOR), terminated by
-whitespace.)
+Whitespace between the `tt(P)' and the start offset is optional.)
+itemiz(A start offset in the same units as tt(CURSOR).)
+itemiz(An end offset in the same units as tt(CURSOR).)
 itemiz(A highlight specification in the same format as
 used for contexts in the parameter tt(zle_highlight), see
 ifnzman(noderef(Character Highlighting))\
 ifzman(the section `Character Highlighting' below);
-for example, tt(standout) or tt(fg=red,bold)).
+for example, tt(standout) or tt(fg=red,bold).)
+itemiz(Optionally, a string of the form `tt(memo=)var(token)'.
+The var(token) consists of everything between the `tt(=)' and the next
+whitespace, comma, NUL, or the end of the string.
+The var(token) is preserved verbatim but not parsed in any way.
+
+Plugins may use this to identify array elements they have added: for example,
+a plugin might set var(token) to its (the plugin's) name and then use
+`tt(region_highlight=+LPAR() ${region_highlight:#*memo=)var(token)tt(} +RPAR())'
+in order to remove array elements it have added.
+
+(This example uses the `tt(${)var(name)tt(:#)var(pattern)tt(})' array-grepping
+syntax described in
+ifzman(the section `Parameter Expansion' in zmanref(zshexpn))\
+ifnzman(noderef(Parameter Expansion)).))
 enditemize()
 
 For example, 
 
-example(region_highlight=("P0 20 bold"))
+example(region_highlight=("P0 20 bold memo=foobar"))
 
 specifies that the first twenty characters of the text including
 any predisplay string should be highlighted in bold.
@@ -1002,6 +1024,14 @@ any predisplay string should be highlighted in bold.
 Note that the effect of tt(region_highlight) is not saved and disappears
 as soon as the line is accepted.
 
+Note that zsh 5.8 and older do not support the `tt(memo=)var(token)' field
+and may misparse the third (highlight specification) field when a memo
+is given.
+COMMENT(The syntax `tt(0 20 bold, memo=foobar)' (with an auxiliary comma)
+happens to work on both zsh <=5.8 and zsh 5.9-to-be, but that seems to be more of
+an accident of implementation than something we should make a first-class-citizen
+API promise.  It's mentioned in the "Incompatibilities" section of README.)
+
 The final highlighting on the command line depends on both tt(region_highlight)
 and tt(zle_highlight); see
 ifzman(the section CHARACTER HIGHLIGHTING below)\
@@ -1184,6 +1214,7 @@ This can be used for detecting switches between the vi command
 )
 enditem()
 
+texinode(Standard Widgets)(Character Highlighting)(User-Defined Widgets)(Zsh Line Editor)
 sect(Standard Widgets)
 cindex(widgets, standard)
 The following is a list of all the standard widgets,
@@ -1209,7 +1240,7 @@ menu(Completion)
 menu(Miscellaneous)
 menu(Text Objects)
 endmenu()
-texinode(Movement)(History Control)()(Zle Widgets)
+texinode(Movement)(History Control)()(Standard Widgets)
 subsect(Movement)
 startitem()
 tindex(vi-backward-blank-word)
@@ -1356,7 +1387,7 @@ item(tt(up-line) (unbound) (unbound) (unbound))(
 Move up a line in the buffer.
 )
 enditem()
-texinode(History Control)(Modifying Text)(Movement)(Zle Widgets)
+texinode(History Control)(Modifying Text)(Movement)(Standard Widgets)
 subsect(History Control)
 startitem()
 tindex(beginning-of-buffer-or-history)
@@ -1704,7 +1735,7 @@ the numeric argument. Zero for both local and imported lines and nonzero for
 only local lines.
 )
 enditem()
-texinode(Modifying Text)(Arguments)(History Control)(Zle Widgets)
+texinode(Modifying Text)(Arguments)(History Control)(Standard Widgets)
 subsect(Modifying Text)
 startitem()
 tindex(vi-add-eol)
@@ -2030,7 +2061,7 @@ into the kill buffer.
 Arguably, this is what Y should do in vi, but it isn't what it actually does.
 )
 enditem()
-texinode(Arguments)(Completion)(Modifying Text)(Zle Widgets)
+texinode(Arguments)(Completion)(Modifying Text)(Standard Widgets)
 subsect(Arguments)
 startitem()
 tindex(digit-argument)
@@ -2078,7 +2109,7 @@ example(zle argument-base 16
 zle universal-argument)
 )
 enditem()
-texinode(Completion)(Miscellaneous)(Arguments)(Zle Widgets)
+texinode(Completion)(Miscellaneous)(Arguments)(Standard Widgets)
 subsect(Completion)
 startitem()
 tindex(accept-and-menu-complete)
@@ -2153,7 +2184,7 @@ When a previous completion displayed a list below the prompt, this
 widget can be used to move the prompt below the list.
 )
 enditem()
-texinode(Miscellaneous)(Text Objects)(Completion)(Zle Widgets)
+texinode(Miscellaneous)(Text Objects)(Completion)(Standard Widgets)
 subsect(Miscellaneous)
 startitem()
 tindex(accept-and-hold)
@@ -2200,7 +2231,7 @@ item(tt(beep))(
 Beep, unless the tt(BEEP) option is unset.
 )
 tindex(bracketed-paste)
-item(tt(bracketed-paste))(
+item(tt(bracketed-paste) (tt(^[[200~)) (tt(^[[200~)) (tt(^[[200~)))(
 This widget is invoked when text is pasted to the terminal emulator. It
 is not intended to be bound to actual keys but instead to the special
 sequence generated by the terminal emulator when text is pasted.
@@ -2551,7 +2582,7 @@ If the last command executed was a digit as part of an argument,
 continue the argument.  Otherwise, execute vi-beginning-of-line.
 )
 enditem()
-texinode(Text Objects)()(Miscellaneous)(Zle Widgets)
+texinode(Text Objects)()(Miscellaneous)(Standard Widgets)
 subsect(Text Objects)
 cindex(text objects)
 Text objects are commands that can be used to select a block of text
@@ -2596,7 +2627,7 @@ argument, multiple words will be selected.
 )
 enditem()
 
-texinode(Character Highlighting)()(Zle Widgets)(Zsh Line Editor)
+texinode(Character Highlighting)()(Standard Widgets)(Zsh Line Editor)
 sect(Character Highlighting)
 
 vindex(zle_highlight, setting)