25 files changed, 419 insertions, 220 deletions
diff --git a/Doc/Zsh/.cvsignore b/Doc/Zsh/.cvsignore
deleted file mode 100644
index 71e99e521..000000000
--- a/Doc/Zsh/.cvsignore
+++ /dev/null
@@ -1,4 +0,0 @@
-modlist.yo
-modmenu.yo
-manmodmenu.yo
-*.swp
diff --git a/Doc/Zsh/arith.yo b/Doc/Zsh/arith.yo
index f8807eb4a..4a0709b27 100644
--- a/Doc/Zsh/arith.yo
+++ b/Doc/Zsh/arith.yo
@@ -122,6 +122,33 @@ taken for a parameter name.  All numeric parts (before and after the
 decimal point and in the exponent) may contain underscores after the
 leading digit for visual guidance; these are ignored in computation.
 
+The special floating point values NaN (not a number) and infinity are
+fully supported in floating point arithmetic.  They may be produced by
+certain operations, such as division by zero, or referenced explicitly in
+arithmetic constructs and float assignments using the case-insensitive
+constants tt(NaN) and tt(Inf).  Expansion syntax must be used to
+reference a parameter with one of these names in these contexts:
+
+example(% nan=123 INF=456
+% print $LPAR()LPAR() nan RPAR()RPAR() $LPAR()LPAR() INF RPAR()RPAR()
+NaN Inf
+% print $LPAR()LPAR() $nan RPAR()RPAR() $LPAR()LPAR() $INF RPAR()RPAR()
+123 456
+% typeset -F f=nan && typeset -p f
+typeset -F f=NaN
+% typeset -F f=$nan && typeset -p f
+typeset -F f=123.0000000000)
+
+To check whether a value is NaN, either use the tt(isnan) function
+provided by the tt(zsh/mathfunc) module
+or compare it to the string tt(NaN):
+
+example(% zmodload zsh/mathfunc
+% LPAR()LPAR() isnan+LPAR()0.0 / 0+RPAR() RPAR()RPAR() && print is nan
+is nan
+% typeset -F f=nan && [[ $f == NaN ]] && print is nan
+is nan)
+
 cindex(arithmetic operators)
 cindex(operators, arithmetic)
 An arithmetic expression uses nearly the same syntax and
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index c322cee77..ca9ba996b 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -464,13 +464,14 @@ enditem()
 )
 findex(disown)
 cindex(jobs, disowning)
-xitem(tt(disown) [ var(job) ... ])
+xitem(tt(disown) [ tt(-a) | var(job) ... ])
 xitem(var(job) ... tt(&|))
 item(var(job) ... tt(&!))(
 Remove the specified var(job)s from the job table; the shell will
 no longer report their status, and will not complain if you
 try to exit an interactive shell with them running or stopped.
 If no var(job) is specified, disown the current job.
+With tt(-a), disown all jobs.
 
 If the var(job)s are currently stopped and the tt(AUTO_CONTINUE) option
 is not set, a warning is printed containing information about how to
@@ -570,8 +571,7 @@ change.
 
 The var(flags) may be any of the invocation-time flags described in
 sectref(Invocation)(zsh),
-except that `tt(-o EMACS)' and `tt(-o VI)' may not be used.  Flags such
-as `tt(+r)'/`tt(+o RESTRICTED)' may be prohibited in some circumstances.
+except that `tt(-o EMACS)' and `tt(-o VI)' may not be used.
 
 If tt(-c) var(arg) appears in var(flags), var(arg) is evaluated while the
 requested emulation is temporarily in effect.  In this case the emulation
@@ -989,16 +989,16 @@ tt(read -zr).
 )
 findex(getopts)
 cindex(options, processing)
-item(tt(getopts) var(optstring) var(name) [ var(arg) ... ])(
+item(tt(getopts) [ tt(-p) ] var(optstring) var(name) [ var(arg) ... ])(
 Checks the var(arg)s for legal options.  If the var(arg)s are omitted,
-use the positional parameters.  A valid option argument
+the positional parameters are used.  A valid option argument
 begins with a `tt(PLUS())' or a `tt(-)'.  An argument not beginning with
 a `tt(PLUS())' or a `tt(-)', or the argument `tt(-)tt(-)', ends the options.
 Note that a single `tt(-)' is not considered a valid option argument.
 var(optstring) contains the letters that tt(getopts)
 recognizes.  If a letter is followed by a `tt(:)', that option
-requires an argument.  The options can be
-separated from the argument by blanks.
+requires an argument.  The argument may appear either immediately
+following the option in the same word, or in the next word.
 
 Each time it is invoked, tt(getopts) places the option letter it finds
 in the shell parameter var(name), prepended with a `tt(PLUS())' when
@@ -1008,15 +1008,17 @@ is stored in tt(OPTARG).
 vindex(OPTIND, use of)
 vindex(OPTARG, use of)
 
+When the terminator `tt(-)tt(-)' is encountered, tt(OPTIND) is
+incremented such that it can be tt(shift)ed away with the options.  This
+is not true of other non-option arguments, including a single `tt(-)'.
+
 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.  (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
-stored.  The option itself is still stored in var(name) in this case.
+upon exit.  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 stored.  The option itself is still stored in var(name) in this case.
 
 A leading `tt(:)' in var(optstring) causes tt(getopts) to store the
 letter of any invalid option in tt(OPTARG), and to set var(name) to
@@ -1024,6 +1026,14 @@ letter of any invalid option in tt(OPTARG), and to set var(name) to
 missing.  Otherwise, tt(getopts) sets var(name) to `tt(?)' and prints
 an error message when an option is invalid.  The exit status is
 nonzero when there are no more options.
+
+When either the tt(POSIX_BUILTINS) option is enabled or the tt(-p)
+option is given to tt(getopts) itself, tt(getopts) behaves in a more
+POSIX-compatible manner.  Specifically, handling of
+`tt(PLUS())'-prefixed options is disabled (they are treated as
+non-options) and the value of tt(OPTIND) is calculated differently.
+Additionally, with tt(POSIX_BUILTINS) (but not with tt(-p)), the value
+of tt(OPTIND) is not kept local to the calling function.
 )
 findex(hash)
 item(tt(hash) [ tt(-Ldfmrv) ] [ var(name)[tt(=)var(value)] ] ...)(
@@ -1735,7 +1745,7 @@ If the tt(-m) flag is given the arguments are taken as patterns
 options with names matching these patterns are set.
 
 Note that a bad option name does not cause execution of subsequent shell
-code to be aborted; this is behaviour is different from that of `tt(set
+code to be aborted; this behaviour is different from that of `tt(set
 -o)'.  This is because tt(set) is regarded as a special builtin by the
 POSIX standard, but tt(setopt) is not.
 )
diff --git a/Doc/Zsh/compat.yo b/Doc/Zsh/compat.yo
index 4d3567d45..df0ace63d 100644
--- a/Doc/Zsh/compat.yo
+++ b/Doc/Zsh/compat.yo
@@ -1,12 +1,11 @@
-texinode(Compatibility)(Restricted Shell)()(Invocation)
+texinode(Compatibility)()()(Invocation)
 sect(Compatibility)
 cindex(compatibility)
 cindex(sh compatibility)
 cindex(ksh compatibility)
 Zsh tries to emulate bf(sh) or bf(ksh) when it is invoked as
 tt(sh) or tt(ksh) respectively; more precisely, it looks at the first
-letter of the name by which it was invoked, excluding any initial `tt(r)'
-(assumed to stand for `restricted'), and if that is `tt(b)', `tt(s)' or `tt(k)' it
+letter of the name by which it was invoked, and if that is `tt(b)', `tt(s)' or `tt(k)' it
 will emulate bf(sh) or bf(ksh).  Furthermore, if invoked as tt(su) (which
 happens on certain systems when the shell is executed by the tt(su)
 command), the shell will try to find an alternative name from the tt(SHELL)
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index fbfccf82e..3aca78998 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -32,7 +32,7 @@ enditemize()
 
 A full context specification contains other elements, as we shall describe.
 
-Besides commands names and contexts, the system employs two more
+Besides command names and contexts, the system employs two more
 concepts, em(styles) and em(tags).  These provide ways for the user
 to configure the system's behaviour.
 
@@ -167,7 +167,8 @@ change, it is easiest to delete the dump file by hand so that
 tt(compinit) will re-create it the next time it is run.  The check
 performed to see if there are new functions can be omitted by giving
 the option tt(-C).  In this case the dump file will only be created if
-there isn't one already.
+there isn't one already.  Use option tt(-w) to explain why a dump file
+isn't loaded and/or why it's regenerated.
 
 The dumping is actually done by another function, tt(compdump), but you
 will only need to run this yourself if you change the configuration
@@ -774,7 +775,7 @@ for color names
 kindex(commands, completion tag)
 item(tt(commands))(
 for names of external commands.  Also used by complex commands such as
-tt(cvs) when completing names subcommands.
+tt(cvs) when completing names of subcommands.
 )
 kindex(contexts, completion tag)
 item(tt(contexts))(
@@ -1208,7 +1209,7 @@ generated.  Its value is a list of names of completers.  If any of
 these is the name of the completer that generated the matches in this
 completion, the string will not be added.
 
-The default value for this style is `tt(_expand _old_list _correct
+The default value for this style is `tt(_expand _oldlist _correct
 _approximate)', i.e. it contains the completers for which a string
 with all matches will almost never be wanted.
 )
@@ -3701,6 +3702,10 @@ example(foobar -x -- -y)
 
 the `tt(-x)' is considered an option, the `tt(-y)' is considered an
 argument, and the `tt(-)tt(-)' is considered to be neither.
+
+If this option is given twice (as tt(-S -S)), a single `tt(-)' is also
+treated this way.  This is useful for completing zsh's own builtins as
+well as functions that use tt(zparseopts) for option parsing.
 )
 item(tt(-A) var(pat))(
 Do not complete options after the first non-option
@@ -3979,10 +3984,9 @@ typeset -A opt_args)
 to prevent tt(_arguments) from altering the global environment.
 )
 item(tt({)var(eval-string)tt(}))(
-vindex(expl, use of)
-A string in braces is evaluated as shell code to generate matches.  If the
-var(eval-string) itself does not begin with an opening parenthesis or
-brace it is split into separate words before execution.
+A string in braces is evaluated as shell code to generate matches.
+This is similar to the `tt(SP())var(word) var(...)' action described
+below, but isn't limited to a single command.
 )
 item(tt(= )var(action))(
 If the var(action) starts with `tt(= )' (an equals sign followed by a
@@ -4000,8 +4004,9 @@ causes tt(_arguments) on a restricted range; it is necessary to use this
 trick to insert an appropriate command name into the range for the second
 call to tt(_arguments) to be able to parse the line.
 )
-xitem(var(tt(SP())word...))
-item(var(word...))(
+xitem(tt(SP())var(word) var(...))
+item(var(word) var(...))(
+vindex(expl, use of)
 This covers all forms other than those above.  If the var(action)
 starts with a space, the remaining list of words will be invoked unchanged.
 
@@ -4020,7 +4025,11 @@ enditem()
 During the performance of the action the array `tt(line)' will be set to
 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
+arguments.  Also excluded are any words appearing after the current
+word, the parsing terminator `tt(-)tt(-)' or `tt(-)' if tt(_arguments)
+was called with tt(-S), and any words ignored by the tt(-A) pattern.
+
+Options are stored in the associative array
 `tt(opt_args)' with option names as keys and their arguments as
 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
@@ -4287,7 +4296,7 @@ The return status of tt(_call_function) itself is zero if the function
 var(name) exists and was called and non-zero otherwise.
 )
 findex(_call_program)
-item(tt(_call_program) [ tt(-l) ] [ tt(-p) ] var(tag) var(string) ...)(
+item(tt(_call_program) [ tt(-lpqQ) ] var(tag) var(string) ...)(
 This function provides a mechanism for the user to override the use of an
 external command.  It looks up the tt(command) style with the supplied
 var(tag).  If the style is set, its value is used as the command to
@@ -4309,6 +4318,15 @@ match the permissions to whatever the final command is likely to run
 under. When looking up the tt(gain-privileges) and tt(command) styles,
 the command component of the zstyle context will end with a slash
 (`tt(/)') followed by the command that would be used to gain privileges.
+
+By default, the var(string)s are passed directly to tt(eval), which may
+require double-quoting in some cases. The options tt(-q) and tt(-Q) can
+help with this: with tt(-q), all var(string)s are quoted, whereas with
+tt(-Q) all var(string)s except the first one (usually the name of the
+command to run) are quoted. tt(-Q) is useful when the first var(string)
+is tt($words[1]), which may already be quoted since it is taken directly
+from the typed command line. These options do not affect the quoting of
+arguments derived from the tt(command) style.
 )
 findex(_combination)
 item(tt(_combination) [ tt(-s) var(pattern) ] var(tag) var(style) var(spec) ... var(field) var(opts) ...)(
@@ -4403,16 +4421,22 @@ Multiple groups separated by tt(-)tt(-) can be supplied, potentially with
 different completion options var(opt)s.
 
 The var(descr) is taken as a string to display above the matches if the
-tt(format) style for the tt(descriptions) tag is set.  This is followed by
-one or two names of arrays followed by options to pass to tt(compadd).  The
-array var(name1) contains the possible completions with their descriptions in
-the form `var(completion)tt(:)var(description)'.  Any literal colons in
-var(completion) must be quoted with a backslash.  If a var(name2) is
+tt(format) style for the tt(descriptions) tag is set.
+
+This is followed by one or two names of arrays.  Alternatively, the arrays
+may be given inline, following the rules described below, using the syntax
+tt(LPAR())var(item) var(...)tt(RPAR()).  (There is no separate
+tt(LPAR()LPAR())var(...)tt(RPAR()RPAR()) form as with tt(_arguments).)
+
+The array var(name1) contains the possible completions with their (optional)
+descriptions in the form `var(completion)tt(:)var(description)'.  Any literal
+colons in var(completion) must be quoted with a backslash.  If a var(name2) is
 given, it should have the same number of elements as var(name1); in this
 case the corresponding elements are added as possible completions instead
 of the var(completion) strings from var(name1).  The completion list
-will retain the descriptions from var(name1).  Finally, a set of
-completion options can appear.
+will retain the descriptions from var(name1).
+
+Finally, a set of options to pass to tt(compadd) can appear.
 
 If the option `tt(-o)' appears before the first argument, the matches added
 will be treated as names of command options (N.B. not shell options),
@@ -4439,6 +4463,7 @@ it does not need to appear inside a loop over tag labels.
 )
 findex(_description)
 item(tt(_description) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(spec) ... ])(
+vindex(expl, use of)
 This function is not to be confused with the previous one; it is used as
 a helper function for creating options to tt(compadd).  It is buried
 inside many of the higher level completion functions and so often does
@@ -4900,6 +4925,24 @@ Finally, the tt(_path_files) function  uses the styles tt(expand),
 tt(ambiguous), tt(special-dirs), tt(list-suffixes) and tt(file-sort)
 described above.
 )
+findex(_phony)
+item(tt(_phony) ... [ var(word) ... ] [ [ tt(--) ] var(function) [ tt(-) ] ... ])(
+This function allows extra matches to be mixed in with the matches
+generated by a function.  Sometimes a command accepts special values like
+`tt(any)', `tt(all)', or `tt(none)' to be specified but the applicable
+completion function only generates real values.
+
+tt(_phony) takes all the same arguments as tt(compadd).  With the exception
+of `tt(-a)', `tt(-d)', `tt(-k)' and `tt(-l)', these are passed on to the
+following function.  Unless there is only one word, a `tt(--)' separator is
+needed to indicate where the words finish and the function begins.  You can
+also omit the function in which case an empty input won't match the phony
+values, allowing descriptions to be displayed. This is useful where real
+values can't be generated and tt(_message -e) would otherwise be used.
+
+To ensure that real and phony matches are grouped together, any options
+defining the match group should be passed to tt(_phony).
+)
 findex(_pick_variant)
 redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ @ @ @ @ @ ))ifnztexi(              )))
 xitem(tt(_pick_variant )[ tt(-b) var(builtin-label) ] [ tt(-c) var(command) ] [ tt(-r) var(name) ])
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index cff46fb29..3e8e9f446 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -520,8 +520,12 @@ item(tt(-d) var(array))(
 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.
+var(array) may be given as the name of an array parameter, or directly
+as a literal array enclosed in parentheses. A literal array is a space or
+comma separated list of words; quotes have no special meaning and
+backslashes can be used for escaping (for example, `tt((foo\ bar))' produces
+one element, tt(foo bar), while `tt((foo bar))' produces two elements,
+tt(foo) and tt(bar)).
 
 If there are fewer display strings than var(completions), the leftover
 var(completions) will be displayed unchanged and if there are more display
@@ -869,16 +873,20 @@ builtin, but in the case of the condition codes the contents of the special
 parameters are not modified.
 
 startitem()
+findex(-prefix, within [[)
 item(tt(-prefix) [ var(number) ] var(pattern))(
 true if the test for the tt(-P) option of tt(compset) would succeed.
 )
+findex(-suffix, within [[)
 item(tt(-suffix) [ var(number) ] var(pattern))(
 true if the test for the tt(-S) option of tt(compset) would succeed.
 )
+findex(-after, within [[)
 item(tt(-after) var(beg-pat))(
 true if the test of the tt(-N) option with only the var(beg-pat) given
 would succeed.
 )
+findex(-between, within [[)
 item(tt(-between) var(beg-pat end-pat))(
 true if the test for the tt(-N) option with both patterns would succeed.
 )
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 03572bf45..aeb47851c 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -190,9 +190,11 @@ ordinary, such as a Delete key that sends neither tt(^H) nor tt(^?).
 
 The keystrokes read by tt(zkbd) are recorded as a definition for an
 associative array named tt(key), written to a file in the subdirectory
-tt(.zkbd) within either your tt(HOME) or tt(ZDOTDIR) directory.  The name
-of the file is composed from the tt(TERM), tt(VENDOR) and tt(OSTYPE)
-parameters, joined by hyphens.
+tt(.zkbd) within either your tt(HOME) or, if specified, tt(ZDOTDIR) directory.
+Alternatively, you can tell tt(zkbd) the directory to write new files into
+with the tt(-d) option, e.g. tt(zkbd -d $ZCACHEDIR/zkbd). In either case, the
+directory is created if it did not exist. The name of the file is composed from
+the tt(TERM), tt(VENDOR) and tt(OSTYPE) parameters, joined by hyphens.
 
 You may read this file into your tt(.zshrc) or another startup file with
 the `tt(source)' or `tt(.)' commands, then reference the tt(key) parameter
@@ -4404,7 +4406,7 @@ the context prefix `tt(:completion:nslookup)'.
 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))(
+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 (ERE) are used,
 unless the option tt(RE_MATCH_PCRE) has been set, in which case
@@ -4414,7 +4416,8 @@ library).
 
 var(var) is the name of the variable containing the string to be matched.
 The variable will be modified directly by the function.  The
-variables tt(MATCH), tt(MBEGIN), tt(MEND), tt(match), tt(mbegin), tt(mend)
+variables tt(MATCH), tt(MBEGIN), tt(MEND), tt(match), tt(mbegin), tt(mend),
+as well as any variables starting with tt(_regexp_replace)
 should be avoided as these are used by the regular expression code.
 
 var(regexp) is the regular expression to match against the string.
@@ -4422,6 +4425,7 @@ var(regexp) is the regular expression to match against the string.
 var(replace) is the replacement text.  This can contain parameter, command
 and arithmetic expressions which will be replaced:  in particular, a
 reference to tt($MATCH) will be replaced by the text matched by the pattern.
+If not given, matches are replaced with nothing.
 
 The return status is 0 if at least one match was performed, else 1.
 
@@ -4651,6 +4655,79 @@ Same as tt(zmv -C) and tt(zmv -L), respectively.  These functions do not
 appear in the zsh distribution, but can be created by linking tt(zmv) to
 the names tt(zcp) and tt(zln) in some directory in your tt(fpath).
 )
+findex(zgetopt)
+item(tt(zgetopt) [ tt(-A) var(array) ] [ tt(-l) var(spec) ] [ tt(-n) var(name) ] [ tt(-o) var(spec) ] tt(--) [ var(arg) ... ])(
+This is a wrapper around tt(zparseopts) (from tt(zsh/zutil)) which
+provides an interface similar to the util-linux implementation of
+tt(getopt+LPAR()1+RPAR()) (sometimes called `GNU tt(getopt)'). It
+simplifies GNU-style argument parsing (including permutation) and
+can make it easier to write functions and scripts with complex APIs,
+particularly ones where the order of options is significant.
+
+The typical usage pattern is as follows:
+
+example(zgetopt -o abc: -l aaa,bbb,ccc: -- "$@" || return
+while (( $# )); do
+  case $1 in
+    -a|--aaa+RPAR() ...; shift ;;        # handle -a
+    -b|--bbb+RPAR() ...; shift ;;        # handle -b
+    -c|--ccc+RPAR() ...; shift 2 ;;      # handle -c and arg
+    --+RPAR()       ...; shift; break ;; # end of options
+  esac
+done
+# handle operands)
+
+It can also be called as a stand-alone script from other shells
+using the more traditional print-and-eval pattern:
+
+example(args=$( zgetopt -n myscript -o abc: -l aaa,bbb,ccc: -- "$@" ) || return
+eval set -- "$args"
+while [ $# -ne 0 ]; do ...; done)
+
+Options:
+
+startsitem()
+sitem(tt(-A var(array)))(When called as a function, assign the parsed
+arguments to the named array var(array). Defaults to tt(argv), which
+overwrites the caller's positional parameters. Has no meaning when
+called as a script, in which case the parsed and quoted arguments are
+always printed to standard output. An empty string forces the
+printing behaviour in either mode.)
+sitem(tt(-l var(spec)))(Specify long options to recognise when
+parsing. These should be given using just the option name (no
+dashes), suffixed by `tt(:)' or `tt(::)' if it takes a mandatory or
+optional argument respectively. Multiple options can be defined
+either by separating them by commas or by supplying -l again.
+Example: tt(-l foo,bar: -l baz))
+sitem(tt(-n var(name)))(Specify the name to use in the error message
+if argument parsing fails. Defaults to the name of the nearest
+calling function or the base name of tt($ZSH_ARGZERO). Note that
+errors related to the usage of tt(zgetopt) itself are always reported
+as coming from tt(zgetopt).)
+sitem(tt(-o var(spec)))(Specify short options to recognise when
+parsing. These should be given as a single string, in the same format
+used by the tt(getopts) built-in or the tt(getopt+LPAR()3+RPAR())
+library function, again using `tt(:)' or `tt(::)' to indicate a
+mandatory or optional argument. The spec may be prefixed with `tt(+)'
+to indicate that option parsing should stop at the first non-option
+argument (equivalent to setting the environment variable
+tt(POSIXLY_CORRECT)). Example: tt(-o ab:cd::))
+endsitem()
+
+At least one of tt(-o) or tt(-l) must be given. The function's own
+options should be followed by zero or more arguments to parse. It is
+critical that these be separated explicitly by `tt(--)', as in the
+above examples, to ensure that the function can accurately
+distinguish the arguments it's meant to parse from its own.
+
+Refer to the manual for util-linux's tt(getopt+LPAR()1+RPAR()) for
+more information about the way arguments are parsed and results are
+returned. Note however that this function is not intended to be a
+complete re-implementation. In particular: it omits all
+portability/compatibility features, it doesn't support the
+tt(--alternative) option, and it doesn't support abbreviating long
+options.
+)
 item(tt(zkbd))(
 See subref(Keyboard Definition)(above).
 )
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 0cefaf7d1..cbdaddead 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -663,7 +663,7 @@ item(tt(${)var(name)tt(::=)var(word)tt(}))(
 In the first form, if var(name) is unset then set it to var(word); in the
 second form, if var(name) is unset or null then set it to var(word); and
 in the third form, unconditionally set var(name) to var(word).  In all
-forms, the value of the parameter is then substituted.
+forms, the value of var(name) is then substituted.
 )
 xitem(tt(${)var(name)tt(?)var(word)tt(}))
 item(tt(${)var(name)tt(:?)var(word)tt(}))(
@@ -1699,7 +1699,7 @@ are not the same as the flags used within parameter substitutions.
 At the outermost level of substitution, the `tt((P))' flag (rule tt(4.))
 ignores these transformations and uses the unmodified value of the
 parameter as the name to be replaced.  This is usually the desired
-behavior because padding may make the value syntactically illegal as a
+behavior because padding may make the value syntactically invalid as a
 parameter name, but if capitalization changes are desired, use the
 tt(${${(P)foo}}) form (rule tt(25.)).
 )
diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo
index e75e66a6c..8dbfd1164 100644
--- a/Doc/Zsh/grammar.yo
+++ b/Doc/Zsh/grammar.yo
@@ -531,7 +531,6 @@ itemiz(Execution of incorrectly positioned loop control structures
 (tt(continue), tt(break)))
 itemiz(Attempts to use regular expression with no regular expression
 module available)
-itemiz(Disallowed operations when the tt(RESTRICTED) options is set)
 itemiz(Failure to create a pipe needed for a pipeline)
 itemiz(Failure to create a multio)
 itemiz(Failure to autoload a module needed for a declared shell feature)
diff --git a/Doc/Zsh/invoke.yo b/Doc/Zsh/invoke.yo
index 9c589b278..b6ed73fe5 100644
--- a/Doc/Zsh/invoke.yo
+++ b/Doc/Zsh/invoke.yo
@@ -105,8 +105,6 @@ can be stacked after the `tt(-b)' and will take effect as normal.
 
 startmenu()
 menu(Compatibility)
-menu(Restricted Shell)
 endmenu()
 
 includefile(Zsh/compat.yo)
-includefile(Zsh/restricted.yo)
diff --git a/Doc/Zsh/manual.yo b/Doc/Zsh/manual.yo
index 8cbe2cfd2..6dcec0063 100644
--- a/Doc/Zsh/manual.yo
+++ b/Doc/Zsh/manual.yo
@@ -49,6 +49,7 @@ menu(Functions Index)
 menu(Editor Functions Index)
 menu(Style and Tag Index)
 
+startdetailmenu()
  --- The Detailed Node Listing ---
 
 Introduction
@@ -64,7 +65,6 @@ menu(See Also)
 Invocation
 
 menu(Compatibility)
-menu(Restricted Shell)
 
 Shell Grammar
 
@@ -111,6 +111,7 @@ menu(Zle Widgets)
 menu(User-Defined Widgets)
 menu(Standard Widgets)
 menu(Character Highlighting)
+menu(Cursor Shape and Color)
 
 Completion Widgets
 
@@ -177,6 +178,7 @@ menu(Mathematical Functions)
 menu(User Configuration Functions)
 menu(Other Functions)
 
+enddetailmenu()
 endmenu()
 texinode(The Z Shell Manual)(Introduction)(Top)(Top)
 chapter(The Z Shell Manual)
diff --git a/Doc/Zsh/mod_ksh93.yo b/Doc/Zsh/mod_ksh93.yo
index 9e995caac..a99592c8e 100644
--- a/Doc/Zsh/mod_ksh93.yo
+++ b/Doc/Zsh/mod_ksh93.yo
@@ -16,9 +16,7 @@ item(tt(nameref) [ tt(-gpur) ] var(pname)[tt(=)var(rname)])(
 Equivalent to tt(typeset -n )var(pname)tt(=)var(rname)
 
 However, tt(nameref) is a builtin command rather than a reserved word,
-so when var(rname) uses subscript syntax it must be quoted against
-globbing.  Subscripts in referenced parameters are not supported in
-ksh93, so this is not a significant compatibility issue.
+so handling of assigments in the argument list may differ.
 )
 enditem()
 
diff --git a/Doc/Zsh/mod_mathfunc.yo b/Doc/Zsh/mod_mathfunc.yo
index 61aa3decf..b7223e2cf 100644
--- a/Doc/Zsh/mod_mathfunc.yo
+++ b/Doc/Zsh/mod_mathfunc.yo
@@ -27,8 +27,8 @@ tt(floor), tt(gamma), tt(j0), tt(j1), tt(lgamma), tt(log), tt(log10),
 tt(log1p), tt(log2), tt(logb), tt(sin), tt(sinh), tt(sqrt), tt(tan),
 tt(tanh), tt(y0), tt(y1).  The tt(atan) function can optionally take a
 second argument, in which case it behaves like the C function tt(atan2).
-The tt(ilogb) function takes a single floating point argument, but
-returns an integer.
+The tt(ilogb), tt(isinf), and tt(isnan) functions take a single floating
+point argument, but return an integer.
 
 The function tt(signgam) takes no arguments, and returns an integer, which
 is the C variable of the same name, as described in manref(gamma)(3).  Note
diff --git a/Doc/Zsh/mod_nearcolor.yo b/Doc/Zsh/mod_nearcolor.yo
index df7771397..ef565fff3 100644
--- a/Doc/Zsh/mod_nearcolor.yo
+++ b/Doc/Zsh/mod_nearcolor.yo
@@ -23,10 +23,14 @@ it will be compared against each of the available colours and the
 closest will be selected. The first sixteen colours are never matched in
 this process due to being unpredictable.
 
-It isn't possible to reliably detect support for true colour in the
-terminal emulator. It is therefore recommended to be selective in
-loading the tt(zsh/nearcolor) module. For example, the following
-checks the tt(COLORTERM) environment variable:
+The use of a hex triplet will automatically load the tt(zsh/nearcolor)
+module if the terminal doesn't support 24-bit colour. This behaviour can
+be modified via the tt(.term.extensions) parameter DASH()- see
+sectref(Terminal Extensions)(zshzle).
+
+The module can also be loaded manually. It is recommended to be
+selective in doing so. For example, the following checks the
+tt(COLORTERM) environment variable:
 
 example([[ $COLORTERM = *LPAR()24bit|truecolor+RPAR()* ]] || \
     zmodload zsh/nearcolor)
diff --git a/Doc/Zsh/mod_pcre.yo b/Doc/Zsh/mod_pcre.yo
index 41fab4475..8458145dd 100644
--- a/Doc/Zsh/mod_pcre.yo
+++ b/Doc/Zsh/mod_pcre.yo
@@ -66,18 +66,26 @@ while [[ $? -eq 0 ]] do
     pcre_match -b -n $b[2] -- $string
 done
 print -l $accum)
-)
-enditem()
-
-If the regular expression contains callouts, these are executed as shell code.
-During the execution of the callout, the string the regular expression is
-matching against is available in the parameter tt(.pcre.subject). If there is a
-non-zero return status from the shell code, the callout does not match.
 
 The option tt(-d) uses the alternative breadth-first DFA search algorithm of
 pcre. This sets tt(match), or the array given with tt(-a), to all the matches
 found from the same start point in the subject.
 
+If the regular expression contains string callouts, these are executed as
+shell code, while numerical callouts are ignored. During the execution of the
+callout, the string the regular expression is matching against is available
+in the parameter tt(.pcre.subject). The parameter tt(.pcre.pos) contains the
+position in that string that is currently being matched against. If there is
+a non-zero return status from the shell code, the callout does not match. Note
+that callouts are not available in the below -pcre-match test condition. It is
+also likely not a good idea to call any pcre related builtins from a callout. As
+an example, the following will print out `tt(bar)':
+
+example(pcre_compile 'foo+LPAR()?C"echo ${.pcre.subject[${.pcre.pos},-1]}"+RPAR()'
+pcre_match foobar)
+)
+enditem()
+
 The tt(zsh/pcre) module makes available the following test condition:
 
 startitem()
diff --git a/Doc/Zsh/mod_random.yo b/Doc/Zsh/mod_random.yo
index d797ca381..3bd904d42 100644
--- a/Doc/Zsh/mod_random.yo
+++ b/Doc/Zsh/mod_random.yo
@@ -24,22 +24,24 @@ Returns a random floating point number between 0 and 1 inclusive.
 enditem()
 
 startitem()
-item(tt(zrand_int)+LPAR()tt(upper), tt(lower), tt(inclusive)RPAR()) (
-Returns a random integer between tt(lower) and tt(upper). All parameters are
-optional.  If none are specified it is equivalent to
-tt(SRANDOM).
+item(tt(zrand_int)+LPAR()var(upper), var(lower), var(inclusive)RPAR()) (
+Returns a random integer between var(lower) and var(upper). All parameters
+are optional.  If none are specified it is equivalent to tt(SRANDOM). Note
+that this is equivalent to passing the default values except that it
+is inclusive.
 
-tt(upper) is the upper bound on the resultant number and defaults to
-4,294,967,295.
+var(upper) is the upper bound on the resultant number and defaults to
+4,294,967,295. It is exclusive by default, unless var(inclusive) is passed.
 
-tt(lower) is the lower bound and defaults to 0.
+var(lower) is the lower bound and defaults to 0.
 
 The defaults of these two arguments are also the maximum and minimum to which
 either can be set.
 
-tt(inclusive) is a flag that controls whether the result is ever equal to
-tt(upper).  By default it is not. If this argument is set to a non-zero value
-then it may be.
+var(inclusive) is a flag that controls whether the var(upper) bound is
+exclusive or inclusive. Passing any non-zero value makes it inclusive,
+otherwise it is exclusive when the var(upper) bound is specified. The
+var(lower) bound is always inclusive.
 
 This is to facilitate a construct like tt($a[zrand_int+LPAR()$#a+RPAR()+1]) rather
 than tt($a[zrand_int+LPAR()$#a-1+RPAR()+1]).
@@ -50,7 +52,7 @@ be an array index range error for it to also potentially return 16 ($#a). You
 could, however, use the construct tt(zrand_int+LPAR()16,1,1+RPAR()) instead of
 adding 1 to achieve the same result, but it is more verbose.
 
-Most statistics algorithms seem to also expect 0 to tt(upper)-1, so this was
+Most statistics algorithms seem to also expect 0 to var(upper)-1, so this was
 deemed the most commonly desired case and chosen as the default.
 )
 enditem()
diff --git a/Doc/Zsh/mod_socket.yo b/Doc/Zsh/mod_socket.yo
index 78d9254e8..2c699b1d1 100644
--- a/Doc/Zsh/mod_socket.yo
+++ b/Doc/Zsh/mod_socket.yo
@@ -7,7 +7,7 @@ startitem()
 findex(zsocket)
 cindex(sockets)
 cindex(sockets, Unix domain)
-item(tt(zsocket) [ tt(-altv) ] [ tt(-d) var(fd) ] [ var(args) ])(
+item(tt(zsocket) [ tt(-alstv) ] [ tt(-d) var(fd) ] [ var(args) ])(
 tt(zsocket) is implemented as a builtin to allow full use of shell
 command line editing, file I/O, and job control mechanisms.
 )
@@ -33,6 +33,11 @@ File descriptors can be closed with normal shell syntax when no longer
 needed, for example:
 
 example(exec {REPLY}>&-)
+
+The tt(zsocket -s var(fd)) command may also be used to shut down a
+socket fd before closing it. This will send an EOF to the other side,
+while this side can still read their subsequent response before closing
+the connection fully, for example.
 )
 enditem()
 
diff --git a/Doc/Zsh/mod_tcp.yo b/Doc/Zsh/mod_tcp.yo
index d19e8cc92..5dd1d5da1 100644
--- a/Doc/Zsh/mod_tcp.yo
+++ b/Doc/Zsh/mod_tcp.yo
@@ -7,7 +7,7 @@ startitem()
 findex(ztcp)
 cindex(TCP)
 cindex(sockets, TCP)
-item(tt(ztcp) [ tt(-acflLtv) ] [ tt(-d) var(fd) ] [ var(args) ])(
+item(tt(ztcp) [ tt(-acflLstv) ] [ tt(-d) var(fd) ] [ var(args) ])(
 tt(ztcp) is implemented as a builtin to allow full use of shell
 command line editing, file I/O, and job control mechanisms.
 
@@ -24,7 +24,7 @@ startitem()
 item(File descriptor)(
 The file descriptor in use for the connection.  For normal inbound (tt(I))
 and outbound (tt(O)) connections this may be read and written by the usual
-shell mechanisms.  However, it should only be close with `tt(ztcp -c)'.
+shell mechanisms.  However, it should only be closed with `tt(ztcp -c)'.
 )
 item(Connection type)(
 A letter indicating how the session was created:
@@ -42,6 +42,9 @@ An inbound connection accepted with `tt(ztcp -a)'.
 item(tt(O))(
 An outbound connection created with `tt(ztcp) var(host) var(...)'.
 )
+item(tt(S))(
+A connection that has been shut down with `tt(ztcp -s)'.
+)
 enditem()
 
 )
@@ -122,6 +125,24 @@ subsect(Closing Connections)
 cindex(sockets, closing TCP)
 
 startitem()
+item(tt(ztcp) tt(-s) var(fd))(
+tt(ztcp -s) will shut down the socket associated
+with var(fd). This means a graceful termination
+of the connection is initiated, flushing unsent
+data (due to Nagle's algorithm, for example). To
+complete it, you should also drain any remaining
+data on the fd by reading it. Afterwards you should
+use tt(ztcp -c) to close the fd. If you close it
+without first using tt(ztcp -s) and draining the
+data, the kernel may reset the connection, causing
+data you sent to not be received by the other end.
+
+Note that this is only useful for inbound and
+outbound connections, not for listening sockets.
+)
+enditem()
+
+startitem()
 xitem(tt(ztcp) tt(-cf) [ tt(-v) ] [ var(fd) ])
 item(tt(ztcp) tt(-c) [ tt(-v) ] [ var(fd) ])(
 tt(ztcp -c) will close the socket associated
@@ -129,6 +150,8 @@ with var(fd).  The socket will be removed from the
 session table.  If var(fd) is not specified,
 tt(ztcp) will close everything in the session table.
 
+See also the previous tt(ztcp -s) entry.
+
 Normally, sockets registered by zftp (see
 sectref(The zsh/zftp Module)(zshmodules))
 cannot be closed this way.  In order
@@ -166,6 +189,8 @@ prints `tt(This is a message)'.
 
 To tidy up, on tt(host1):
 example(ztcp -c $listenfd
+ztcp -s $fd
 ztcp -c $fd)
 and on tt(host2)
-example(ztcp -c $fd)
+example(ztcp -s $fd
+ztcp -c $fd)
diff --git a/Doc/Zsh/mod_watch.yo b/Doc/Zsh/mod_watch.yo
index 06ab3cbea..df477a770 100644
--- a/Doc/Zsh/mod_watch.yo
+++ b/Doc/Zsh/mod_watch.yo
@@ -40,7 +40,8 @@ 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:
+Recognizes the following escape sequences, many of which are described
+further in sectref(Simple Prompt Escapes)(zshmisc):
 
 startitem()
 item(tt(%n))(
@@ -71,6 +72,10 @@ 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(%H{)var(group)tt(}))(
+Change all character visual attributes using a highlighting
+specification from the tt(.zle.hlgroups) associative array.
+)
 item(tt(%S) LPAR()tt(%s)RPAR())(
 Start (stop) standout mode.
 )
diff --git a/Doc/Zsh/mod_zpty.yo b/Doc/Zsh/mod_zpty.yo
index 599b9e6d2..b0b5fdf20 100644
--- a/Doc/Zsh/mod_zpty.yo
+++ b/Doc/Zsh/mod_zpty.yo
@@ -30,10 +30,13 @@ and tt(syswrite) is em(not) recommended; use tt(zpty -r) and tt(zpty -w)
 unless you know exactly what you are doing.
 )
 item(tt(zpty) tt(-d) [ var(name) ... ])(
-The second form, with the tt(-d) option, is used to delete commands
-previously started, by supplying a list of their var(name)s.  If no
-var(name) is given, all commands are deleted.  Deleting a command causes
-the HUP signal to be sent to the corresponding process.
+The tt(-d) option is used to delete commands previously started, by
+supplying a list of their var(name)s.  If no var(name) is given, all
+commands are deleted.  Deleting a command causes the HUP signal to be sent
+to the corresponding process.  It is not a good idea to use this form in a
+subshell, as it will kill the command but leave the parent shell confused
+about the state, and it may try to kill another process that re-used the
+process ID.
 )
 item(tt(zpty) tt(-w) [ tt(-n) ] var(name) [ var(string) ... ])(
 The tt(-w) option can be used to send the to command var(name) the given
@@ -82,9 +85,10 @@ when the command has exited:  the return value is zero if at least
 one character could still be read even if the pattern failed to match.
 )
 item(tt(zpty) tt(-t) var(name))(
-The tt(-t) option without the tt(-r) option can be used to test
-whether the command var(name) is still running.  It returns a zero
-status if the command is running and a non-zero value otherwise.
+The tt(-t) option without the tt(-r) option can be used to test whether the
+command var(name) is still running.  It returns a zero status if the command
+is running and a non-zero value otherwise.  Note that this does not indicate
+whether or not any output is available to read.
 )
 item(tt(zpty) [ tt(-L) ])(
 The last form, without any arguments, is used to list the commands
diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
index 06b953f69..11fe8a073 100644
--- a/Doc/Zsh/mod_zutil.yo
+++ b/Doc/Zsh/mod_zutil.yo
@@ -158,11 +158,13 @@ var(pattern) matches at least one of the strings in the value.
 enditem()
 )
 findex(zformat)
-xitem(tt(zformat -f) var(param) var(format) var(spec) ...)
-xitem(tt(zformat -F) var(param) var(format) var(spec) ...)
+xitem(tt(zformat -f) [ tt(-qQ) ] ] var(param) var(format) var(spec) ...)
+xitem(tt(zformat -F) [ tt(-qQ) ] ] var(param) var(format) var(spec) ...)
 item(tt(zformat -a) var(array) var(sep) var(spec) ...)(
-This builtin provides different forms of formatting. The first form
-is selected with the tt(-f) option. In this case the var(format)
+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
 of the form `var(char)tt(:)var(string)' which will cause every
@@ -176,9 +178,21 @@ width makes the result be padded with spaces to the right if the
 var(string) is shorter than the requested width.  Padding to the left
 can be achieved by giving a negative minimum field width.  If a maximum 
 field width is specified, the var(string) will be truncated after that
-many characters.  After all `tt(%)' sequences for the given var(spec)s
-have been processed, the resulting string is stored in the parameter
-var(param).
+many characters.
+
+The var(char) in each var(spec) may optionally be preceded by an
+escaping indicator, either `tt(%)' to explicitly enable the
+var(spec)-escaping behaviour of tt(-q) described below, or `tt(%%)' to
+explicitly disable it.  The default behaviour is to em(not) escape specs.
+
+Any `tt(%)' sequence in tt(format) that does not match a given var(spec)
+(or one of the special sequences described below) is output as-is.  If
+desired, these sequences may be processed by a second round of
+formatting, by prompt expansion, etc. DASH()- see also tt(-q).
+
+The sequence `tt(%%)' can be used to produce a literal tt(%).
+After all `tt(%)' sequences have been processed, the resulting string is
+stored in the parameter var(param).
 
 The tt(%)-escapes also understand ternary expressions in the form used by
 prompts.  The tt(%) is followed by a `tt(LPAR())' and then an ordinary
@@ -207,11 +221,42 @@ expression.
 
 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.
+present and non-empty.  If a test number is provided, it tests the width
+of the value given in the format specifier DASH()- with a positive
+number the condition is true when the width is em(greater than) that
+number, and with a negative number the condition is true when the width
+is em(less than or equal to) the absolute value of that number.
+
+With tt(-q), `tt(%)' characters in the var(spec)s are escaped by default
+as they are inserted into the formatted string, and pre-escaped `tt(%)' and
+`tt(RPAR())` characters in the format string are left as they are.  For
+example:
+
+example(zformat -qF REPLY '%%foo%% %B%d%b' d:%bar%)
+
+outputs `tt(%%foo%% %B%%bar%%%b)' to tt(REPLY).  This is useful when the
+formatted string will undergo further expansion DASH()- in this example
+the tt(%B)...tt(%b) sequences could be used with prompt expansion to
+produce bold text.  One notable use case is formatting a description to
+be passed to tt(compadd -x) in a completion function.
+
+Since the output with tt(-q) is expected to be subject to further
+processing, width specifiers don't count the extra escape characters,
+ensuring that the widths are correct em(after) that processing.
+Additionally, with tt(-F), ternary-expression test numbers are compared
+against the em(pre-escaped) spec lengths.
+
+tt(-Q) is like tt(-q) except that it interprets pre-escaped `tt(%)' and
+`tt(RPAR())` characters in the format string as normal.
 
-The form, using the tt(-a) option, can be used for aligning
+The optional escaping indicator can be used to exempt individual
+var(spec)s from escaping as described above.  For example:
+
+example(zformat -qF REPLY '%d %D' d:%foo% %%D:%bar%)
+
+outputs `tt(%%foo%% %bar%)' to tt(REPLY).
+
+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
@@ -230,7 +275,7 @@ item(tt(zregexparse))(
 This implements some internals of the tt(_regex_arguments) function.
 )
 findex(zparseopts)
-item(tt(zparseopts) [ tt(-D) tt(-E) tt(-F) tt(-G) tt(-K) tt(-M) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] [ tt(-v) var(argv) ] [ tt(-) ] var(spec) ...)(
+item(tt(zparseopts) [ tt(-DEFGKM) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] [ tt(-n) var(name) ] [ tt(-v) var(argv) ] [ tt(-) ] var(spec) ...)(
 This builtin simplifies the parsing of options in positional parameters,
 i.e. the set of arguments given by tt($*).  Each var(spec) describes one
 option and must be of the form `var(opt)[tt(=)var(array)]'.  If an option
@@ -239,7 +284,11 @@ into the var(array) specified with the tt(-a) option; if the optional
 `tt(=)var(array)' is given, it is instead copied into that array, which
 should be declared as a normal array and never as an associative array.
 
-Note that it is an error to give any var(spec) without an
+At least one var(spec) must be given.  If a single spec is given which
+is either an empty string or a single hyphen (as in
+tt(zparseopts -DF '')), it signifies that no options are recognised.
+(This is useful for future-proofing functions that might gain options
+later.)  Otherwise, it is an error to give any var(spec) without an
 `tt(=)var(array)' unless one of the tt(-a) or tt(-A) options is used.
 
 Unless the tt(-E) option is given, parsing stops at the first string
@@ -298,10 +347,11 @@ ambiguities may arise when at least one overlapping var(spec) takes an
 argument, as in `tt(-foo: -foobar)'. In that case, the last matching
 var(spec) wins. (This is not an issue with GNU-style parsing.)
 
-The options of tt(zparseopts) itself cannot be stacked because, for
-example, the stack `tt(-DEK)' is indistinguishable from a var(spec) for
-the GNU-style long option `tt(-)tt(-DEK)'.  The options of tt(zparseopts)
-itself are:
+In order to distinguish GNU-style long option var(spec)s from
+tt(zparseopts)'s own options, they em(must) be preceded by a `tt(-)',
+`tt(--)', or short option tt(spec), as in tt(zparseopts -Ga opts - -foo).
+
+The options of tt(zparseopts) itself are:
 
 startitem()
 item(tt(-a) var(array))(
@@ -386,11 +436,20 @@ item(tt(-M))(
 This changes the assignment rules to implement a map among equivalent
 option names.  If any var(spec) uses the `tt(=)var(array)' form, the
 string var(array) is interpreted as the name of another var(spec),
-which is used to choose where to store the values.  If no other var(spec)
+which is used to choose where to store the values.
+Values stored in an associative array (tt(-A)) use the name of the
+mapped-to option, whereas values stored in an array use the last
+as-given option name.  If no other var(spec)
 is found, the values are stored as usual.  This changes only the way the
 values are stored, not the way tt($*) is parsed, so results may be
 unpredictable if the `var(name)tt(+)' specifier is used inconsistently.
 )
+item(tt(-n) var(name))(
+If this option is given, var(name) is used when printing usage errors
+intended for the end user.  Otherwise, the name of the calling function
+or script is used.  Error messages arising from misusage of tt(zparseopts)
+itself are not affected by this option.
+)
 item(tt(-v) var(argv))(
 With this option, the elements of the named array var(argv) are used as the
 positional parameters to parse, rather than those given by tt($*).  The
@@ -433,4 +492,12 @@ to have the effect of
 example(foo=(-a)
 bar=(-a '' -b xyz))
 )
+
+The following is a useful general-purpose pattern:
+
+example(local -A opts
+zparseopts -DFGA opts - x -long: || return
+(( $+opts[-x] )) && ... # handle -x
+(( $+opts[--long] )) && ... # handle --long, optarg in $opts[--long]
+)
 enditem()
diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo
index a7e862c70..6f3bef189 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -240,7 +240,7 @@ pindex(AUTONAMEDIRS)
 pindex(NOAUTONAMEDIRS)
 cindex(directories, named)
 item(tt(AUTO_NAME_DIRS))(
-Any parameter that is set to the absolute name of a directory
+Any global parameter that is set to the absolute name of a directory
 immediately becomes a name for that directory, that will be used
 by the `tt(%~)'
 and related prompt sequences, and will be available when completion
@@ -1194,7 +1194,7 @@ 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
+overwritten (`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.
@@ -1837,8 +1837,8 @@ pindex(NOLOCALOPTIONS)
 item(tt(LOCAL_OPTIONS) <K>)(
 If this option is set at the point of return from a shell function,
 most options (including this one) which were in force upon entry to
-the function are restored; options that are not restored are
-tt(PRIVILEGED) and tt(RESTRICTED).  Otherwise, only this option,
+the function are restored; the tt(PRIVILEGED) option is not restored.
+Otherwise, only this option,
 and the tt(LOCAL_LOOPS), tt(XTRACE) and tt(PRINT_EXIT_VALUE) options are
 restored.  Hence if this is explicitly unset by a shell function the
 other options in force at the point of return will remain so.
@@ -2255,13 +2255,12 @@ Furthermore, functions and shell builtins are not executed after
 an tt(exec) prefix; the command to be executed must be an external
 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, 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.
+
+Other builtins may be affected as described in
+ifzman(zmanref(zshbuiltins))\
+ifnzman(noderef(Shell Builtin Commands)).
 )
 pindex(POSIX_IDENTIFIERS)
 pindex(NO_POSIX_IDENTIFIERS)
@@ -2466,16 +2465,6 @@ tt(-m) option of tt(setopt) and tt(unsetopt), and changing it inside a
 function always changes it globally regardless of the tt(LOCAL_OPTIONS)
 option.
 )
-pindex(RESTRICTED)
-pindex(NO_RESTRICTED)
-pindex(NORESTRICTED)
-cindex(restricted shell)
-item(tt(RESTRICTED) (tt(-r)))(
-Enables restricted mode.  This option cannot be changed using
-tt(unsetopt), and setting it inside a function always changes it
-globally regardless of the tt(LOCAL_OPTIONS) option.  See
-sectref(Restricted Shell)(zsh).
-)
 pindex(SHIN_STDIN)
 pindex(NO_SHIN_STDIN)
 pindex(SHINSTDIN)
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index ecedc3862..a4dd1a2ca 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -1082,7 +1082,7 @@ Code specified by the tt(-c) option to the command line that invoked
 the shell.
 )
 item(tt(cmdsubst))(
-Command substitution using of the tt(`)var(...)tt(`),
+Command substitution using the tt(`)var(...)tt(`),
 tt($+LPAR())var(...)tt(RPAR()), tt(${{)var(name)tt(}) var(...)tt(}),
 tt(${|)var(...)tt(}), or tt(${ )var(...)tt( }) constructs.
 )
@@ -1115,13 +1115,19 @@ item(tt(globsort))(
 Code executed to order files by the tt(o) glob qualifier.
 )
 item(tt(insubst))(
-The tt(<LPAR())var(...)tt(RPAR()) form of process substitution.
+The tt(>LPAR())var(...)tt(RPAR()) form of process substitution.
 )
 item(tt(loadautofunc))(
 Code read directly from a file to define an autoloaded function.
 )
+item(tt(math))(
+Code executed in the tt($+LPAR()LPAR())var(...)tt(RPAR()RPAR()) or
+tt(LPAR()LPAR())var(...)tt(RPAR()RPAR()) constructs,
+by the tt(let) builtin, in an array subscript, or in
+another arithmetic context.
+)
 item(tt(outsubst))(
-The tt(>LPAR())var(...)tt(RPAR()) form of process substitution.
+The tt(<LPAR())var(...)tt(RPAR()) form of process substitution.
 )
 item(tt(sched))(
 Code executed by the tt(sched) builtin.
@@ -1175,6 +1181,9 @@ the argument passed to the option.  Otherwise it is not set.
 vindex(ZSH_EXEPATH)
 item(tt(ZSH_EXEPATH))(
 Full pathname of the executable file of the current zsh process.
+This value should be accurate on Linux, macOS, FreeBSD, DragonflyBSD,
+NetBSD, Solaris, Cygwin, and their derivatives.  On other systems, it is
+determined from tt(argv[0]), which is not always accurate.
 )
 vindex(ZSH_NAME)
 item(tt(ZSH_NAME))(
@@ -1256,6 +1265,12 @@ vindex(COLUMNS)
 item(tt(COLUMNS) <S>)(
 The number of columns for this terminal session.
 Used for printing select lists and for the line editor.
+If the shell is non-interactive and a legal value is imported from the
+environment, it is preserved.  Otherwise, the value is reset on start-up
+and in response to certain events such as the receipt of a tt(SIGWINCH)
+signal.  Explicitly setting it to an illegal value such as tt(0) also
+resets it.  (Unsetting the parameter does not have this effect; it
+simply `hides' the value that the shell is tracking internally.)
 )
 vindex(CORRECT_IGNORE)
 item(tt(CORRECT_IGNORE))(
@@ -1462,6 +1477,7 @@ vindex(LINES)
 item(tt(LINES) <S>)(
 The number of lines for this terminal session.
 Used for printing select lists and for the line editor.
+See tt(COLUMNS).
 )
 vindex(LISTMAX)
 item(tt(LISTMAX))(
diff --git a/Doc/Zsh/restricted.yo b/Doc/Zsh/restricted.yo
deleted file mode 100644
index a84fd28ea..000000000
--- a/Doc/Zsh/restricted.yo
+++ /dev/null
@@ -1,84 +0,0 @@
-texinode(Restricted Shell)()(Compatibility)(Invocation)
-sect(Restricted Shell)
-cindex(restricted shell)
-pindex(RESTRICTED)
-When the basename of the command used to invoke zsh starts with the letter
-`tt(r)' or the `tt(-r)' command line option is supplied at invocation, the
-shell becomes restricted.  Emulation mode is determined after stripping the
-letter `tt(r)' from the invocation name.  The following are disabled in
-restricted mode:
-
-startitemize()
-itemiz(changing directories with the tt(cd) builtin)
-itemiz(changing or unsetting the tt(EGID), tt(EUID), tt(GID),
-tt(HISTFILE), tt(HISTSIZE), tt(IFS), tt(LD_AOUT_LIBRARY_PATH),
-tt(LD_AOUT_PRELOAD), tt(LD_LIBRARY_PATH), tt(LD_PRELOAD),
-tt(MODULE_PATH), tt(module_path), tt(PATH), tt(path), tt(SHELL),
-tt(UID) and tt(USERNAME) parameters)
-itemiz(specifying command names containing tt(/))
-itemiz(specifying command pathnames using tt(hash))
-itemiz(redirecting output to files)
-itemiz(using the tt(exec) builtin command to replace the shell with another
-command)
-itemiz(using tt(jobs -Z) to overwrite the shell process' argument and
-environment space)
-itemiz(using the tt(ARGV0) parameter to override tt(argv[0]) for external
-commands)
-itemiz(turning off restricted mode with tt(set +r) or tt(unsetopt
-RESTRICTED))
-enditemize()
-
-These restrictions are enforced after processing the startup files.  The
-startup files should set up tt(PATH) to point to a directory of commands
-which can be safely invoked in the restricted environment.  They may also
-add further restrictions by disabling selected builtins.
-
-Restricted mode can also be activated any time by setting the
-tt(RESTRICTED) option.  This immediately enables all the restrictions
-described above even if the shell still has not processed all startup
-files.
-
-A shell em(Restricted Mode) is an outdated way to restrict what users may
-do:  modern systems have better, safer and more reliable ways to
-confine user actions, such as em(chroot jails), em(containers) and
-em(zones).
-
-A restricted shell is very difficult to implement safely.  The feature
-may be removed in a future version of zsh.
-
-It is important to realise that the restrictions only apply to the shell,
-not to the commands it runs (except for some shell builtins).  While a
-restricted shell can only run the restricted list of commands accessible
-via the predefined `tt(PATH)' variable, it does not prevent those
-commands from running any other command.
-
-As an example, if `tt(env)' is among the list of em(allowed) commands,
-then it allows the user to run any command as `tt(env)' is not a shell
-builtin command and can run arbitrary executables.
-
-So when implementing a restricted shell framework it is important to be
-fully aware of what actions each of the em(allowed) commands or features
-(which may be regarded as em(modules)) can perform.
-
-Many commands can have their behaviour affected by environment
-variables.  Except for the few listed above, zsh does not restrict
-the setting of environment variables.
-
-If a `tt(perl)', `tt(python)', `tt(bash)', or other general purpose
-interpreted script is treated as a restricted
-command, the user can work around the restriction by
-setting specially crafted `tt(PERL5LIB)', `tt(PYTHONPATH)',
-`tt(BASH_ENV)' (etc.) environment variables. On GNU systems, any
-command can be made to run arbitrary code when performing character set
-conversion (including zsh itself) by setting a `tt(GCONV_PATH)'
-environment variable.  Those are only a few examples.
-
-Bear in mind that, contrary to some other shells, `tt(readonly)' is not a
-security feature in zsh as it can be undone and so cannot be used to
-mitigate the above.
-
-A restricted shell only works if the allowed commands are few
-and carefully written so as not to grant more access to users than
-intended.  It is also important to restrict what zsh module the user may
-load as some of them, such as `tt(zsh/system)', `tt(zsh/mapfile)' and
-`tt(zsh/files)', allow bypassing most of the restrictions.
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 8c1cd078d..761bd5bc4 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -56,6 +56,7 @@ menu(User-Defined Widgets)
 menu(Standard Widgets)
 menu(Terminal Extensions)
 menu(Character Highlighting)
+menu(Cursor Shape and Color)
 endmenu()
 
 texinode(Keymaps)(Zle Builtins)()(Zsh Line Editor)
@@ -2636,7 +2637,7 @@ as by adding `tt(-cursor)' to disable cursor shape and color changing.
 
 When ZLE starts, it will add entries for features that were auto-detected.  This
 auto-detection uses extensions itself, all named with a `tt(query)' prefix.  As
-this happens when ZLE starts disabling them needs to be done early in the
+this happens when ZLE starts, disabling them needs to be done early in the
 startup files.  A value of `tt(-query)' will disable all terminal queries on
 startup, including those that query terminal properties such as colors rather
 than detecting features.  Populating the array with the status of auto-detected
@@ -2712,7 +2713,7 @@ termcap and the tt(COLORTERM) environment variable.
 )
 enditem()
 
-texinode(Character Highlighting)()(Terminal Extensions)(Zsh Line Editor)
+texinode(Character Highlighting)(Cursor Shape and Color)(Terminal Extensions)(Zsh Line Editor)
 sect(Character Highlighting)
 
 vindex(zle_highlight, setting)
@@ -2977,8 +2978,8 @@ special array parameter tt(region_highlight); see
 ifnzman(noderef(Zle Widgets))\
 ifzman(above).
 
-texinode(Cursor Shape and Color)()()(Character Highlighting)
-subsect(Cursor Shape and Color)
+texinode(Cursor Shape and Color)()(Character Highlighting)(Zsh Line Editor)
+sect(Cursor Shape and Color)
 cindex(cursor shape)
 cindex(cursor color)