9 files changed, 231 insertions, 90 deletions

diff --git a/Doc/Zsh/arith.yo b/Doc/Zsh/arith.yo
index f22b35794..80c023301 100644
--- a/Doc/Zsh/arith.yo
+++ b/Doc/Zsh/arith.yo
@@ -74,11 +74,12 @@ is evaluated.  Note the precedence of the bitwise AND, OR,
 and XOR operators.
 
 An expression of the form `tt(#\)var(x)' where var(x) is any character
-gives the ascii value of this character and an expression of the form
-`tt(#)var(foo)' gives the ascii value of the first character of the value
-of the parameter var(foo).  Note that this is different from the expression
-`tt($#)var(foo)', a standard parameter substitution which gives the length
-of the parameter var(foo).
+sequence such as `tt(a)', `tt(^A)', or `tt(\M-\C-x)' gives the ascii
+value of this character and an expression of the form `tt(#)var(foo)'
+gives the ascii value of the first character of the value of the
+parameter var(foo).  Note that this is different from the expression
+`tt($#)var(foo)', a standard parameter substitution which gives the
+length of the parameter var(foo).
 
 Named parameters and subscripted arrays can be referenced by name within an
 arithmetic expression without using the parameter expansion syntax.  For
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 10202dbce..f6e24ab51 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -44,7 +44,7 @@ This command only expands parameters.  A zero exit code is returned.
 findex(alias)
 cindex(aliases, defining)
 cindex(aliases, listing)
-item(tt(alias) [ tt(-gmrL) ] [ var(name)[tt(=)var(value)] ... ])(
+item(tt(alias) [ {tt(PLUS()|tt(-))}tt(gmrL) ] [ var(name)[tt(=)var(value)] ... ])(
 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,
@@ -58,7 +58,9 @@ are taken as patterns (they should be quoted to preserve them from being
 interpreted as glob patterns), and the aliases matching these patterns
 are printed.  When printing aliases and the tt(-g) or tt(-r) flags
 are present, then restrict the printing to global or regular
-aliases, respectively.
+aliases, respectively.  Using `tt(PLUS())' instead of `tt(-)', or ending
+the option list with a single `tt(PLUS())', prevents the values of the
+aliases from being printed.
 
 If the tt(-L) flag is present, then print each
 alias in a manner suitable for putting in a startup script.  The exit
@@ -550,7 +552,7 @@ If the tt(PUSHD_MINUS) option is set, the meanings of `tt(PLUS())' and
 `tt(-)' in this context are swapped.
 )
 findex(print)
-item(tt(print) [ tt(-nrslzpNDPoOicm) ] [ tt(-u)var(n) ] [ tt(-R) [ tt(-en) ]] [ var(arg) ... ])(
+item(tt(print) [ tt(-bnrslzpNDPoOicm) ] [ tt(-u)var(n) ] [ tt(-R) [ tt(-en) ]] [ var(arg) ... ])(
 With no flags or with flag `tt(-)', the arguments are printed on
 the standard output as described by tt(echo), with the following differences:
 the escape sequence `tt(\M-)var(x)' metafies the character
@@ -570,6 +572,13 @@ unless the tt(-e) flag is given.  The tt(-n) flag suppresses the trailing
 newline.  Only the tt(-e) and tt(-n) flags are recognized after
 tt(-R); all other arguments and options are printed.
 )
+item(tt(-b))(
+Recognize all the escape sequences defined for the tt(bindkey) command,
+see 
+ifzman(zmanref(zshmodules))\
+ifnzman(noderef(The zle Module))\
+.
+)
 item(tt(-m))(
 Take the first argument as a pattern (should be quoted), and remove
 it from the argument list together with subsequent arguments that
@@ -917,15 +926,18 @@ ifzman(`Local Parameters' in zmanref(zshparam))\
 ifnzman(noderef(Local Parameters))\
 .  Local parameters are not exported unless tt(ALL_EXPORT) is set, in
 which case the parameter is exported em(only) when var(name) does not
-already appear in the environment.
+already exist.  The same rules apply to special shell parameters, which
+retain their special attributes when made local.
 
 For each var(name)tt(=)var(value) assignment, the parameter
 var(name) set to var(value).  Note that arrays currently cannot be
 assigned in tt(typeset) expressions; scalars and integers only.
 
-For each remaining var(name) that refers to a parameter that is set,
-the name and value of the parameter are printed in the form of an
-assignment.  Nothing is printed for newly-created parameters.
+For each remaining var(name) that refers to a parameter that is set, the
+name and value of the parameter are printed in the form of an assignment.
+Nothing is printed for newly-created parameters, or if any attribute flags
+listed below are given.  Using `tt(PLUS())' instead of minus to introduce
+an attribute turns it off.
 
 If the tt(-T) option is given, exactly two (or zero) var(name)
 arguments must be present.  They represent a scalar and an array (in
@@ -951,13 +963,16 @@ has no effect when listing existing parameters, nor does the flag tt(+g)
 have any effect.
 
 If no var(name) is present, the names and values of all parameters are
-printed.  In this case the attribute flags restrict the display to
-only those parameters that have the specified attributes.  Using
-`tt(PLUS())' rather than `tt(-)' to introduce the flag causes the
-attribute to be turned off, and suppresses printing of the names and
-values.  If only the tt(-m) flag is given the arguments are taken as
-patterns (should be quoted) and all parameters (or functions with the
-tt(-f) flag) with matching names are printed.
+printed.  In this case the attribute flags restrict the display to only
+those parameters that have the specified attributes, and using `tt(PLUS())'
+rather than `tt(-)' to introduce the flag suppresses printing of the values
+of parameters when there is no parameter name.  Also, if the option list
+ends with `tt(PLUS())', values will not be printed.  If only the tt(-m)
+flag is given the arguments are taken as patterns (should be quoted) and
+all parameters (or functions with the tt(-f) flag) with matching names are
+printed.  If no attribute flags and no tt(-m) flag is present, the
+parameter names will be preceded by a list of any attributes (tt(array),
+tt(association), tt(exported), tt(integer), tt(readonly)).
 
 The following attribute flags may be specified:
 
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 2de4e4bd7..477fbdc77 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -17,6 +17,7 @@ menu(Initialization)
 menu(Control Functions)
 menu(Completion Functions)
 menu(Completion Directories)
+menu(Bindable Commands)
 endmenu()
 
 texinode(Initialization)(Control Functions)()(Completion System)
@@ -248,6 +249,11 @@ of the completer functions to decide if other completers should be
 called. If the return value is zero, no other completers are tried and the
 tt(_main_complete) function returns.
 
+The widget function tt(_main_complete) also uses the configuration key 
+tt(last_prompt). If this is set to tt(always), the cursor is moved up
+to the last prompt after printing a list of matches even if a numeric
+argument was given.
+
 The following completer functions are contained in the distribution (users
 may write their own):
 
@@ -578,7 +584,10 @@ it is set to tt(never), this will not be done (the behaviour without the
 tt(_oldlist) completer).  If it is unset, or any other value, then the
 existing list of completions will be displayed if it is not already;
 otherwise, the standard completion list will be generated:  this is the
-default behaviour of tt(_oldlist).
+default behaviour of tt(_oldlist). However, if there is an old list
+and this key contains the name of the completer function that
+generated the list, then the old list will be used even if it was
+generated by a widget which does not listing.
 
 For example, suppose you type tt(^Xc) to use the tt(_correct_word)
 widget, which generates a list of corrections for the word under the
@@ -586,6 +595,14 @@ cursor.  Usually, typing tt(^D) would generate a standard list of
 completions for the word on the command line, and show that.  With
 tt(_oldlist), it will instead show the list of corrections already
 generated.
+
+As another example consider the tt(_match) completer: with the
+tt(match_insert) key set to tt(unambig) it inserts only an
+unambiguous prefix string if there is any. But since this may remove
+parts of the original pattern, attempting completion again may result
+in more matches than on the first attempt. But by using the
+tt(_oldlist) completer and setting this key to tt(_match), the list of 
+matches generated on the first attempt will be used again.
 )
 item(tt(oldlist_menu))(
 Controls how menu completion behaves when a completion has already been
@@ -769,7 +786,7 @@ on words starting with two hyphens.
 )
 enditem()
 
-texinode(Completion Directories)()(Completion Functions)(Completion System)
+texinode(Completion Directories)(Bindable Commands)(Completion Functions)(Completion System)
 sect(Completion Directories)
 
 In the source distribution, the files are contained in various
@@ -802,3 +819,63 @@ Functions which implement special types of completion to be bound to
 keystrokes rather than called by context.
 )
 enditem()
+
+texinode(Bindable Commands)()(Completion Directories)(Completion System)
+sect(Bindable Commands)
+
+In addition to the context-dependent completions provided, which are
+expected to work in an intuitively obvious way, there are a few widgets
+implementing special behaviour which can be bound separately to keys.  The
+following is a list of these and their default bindings.
+
+startitem()
+item(tt(_correct_filename (^XC)))(
+Correct the filename path at the cursor position.  Allows up to six errors
+in the name.  Can also be correctly called with an argument to correct
+a filepath, independently of zle.
+)
+item(tt(_correct_word) (^Xc))(
+Performs correction of the current argument using the usual contextual
+completions as possible choices.
+)
+item(tt(_expand_word (^Xe)))(
+Performs expansion on the current word:  equivalent to the standard
+tt(expand-word) command, but using all the `tt(expand_*)' configuration
+keys described previously.  In addition, each such key can be overridden by
+a key starting with the string `tt(expandword_)'; for example, the
+tt(expandword_substitute) key if defined overrides the
+tt(expand_substitute) key.
+)
+item(tt(_history_complete_word) (\e/))(
+Complete words from the shell's command history.
+)
+item(tt(_most_recent_file (^Xm)))(
+Complete the name of the most recently modified file matching the pattern
+on the command line (which may be blank).  If given a numeric argument
+var(N), complete the var(N)th most recently modified file.  Note the
+completion, if any, is always unique.
+)
+item(tt(_read_comp (^X^R)))(
+Prompt the user for a string, and use that to perform completion on the
+current word.  There are two possibilities for the string.  First, it can
+be a set of words beginning `tt(_)', for example `tt(_files -/)', in which
+case the function with any arguments will be called to generate the
+completions.  Unambiguous parts of the function name will be completed
+automatically (normal completion is not available at this point) until a
+space is typed.
+
+Otherwise, any other string, for example `tt(-b)', will be passed as
+arguments to tt(compgen) and should hence be a set of flags specifying the
+type of completion.
+
+A very restricted set of editing commands is available when reading the
+string:  `tt(DEL)' and `tt(^H)' delete the last character; `tt(^U)' deletes
+the line, and `tt(^C)' and `tt(^G)' abort the function, while `tt(RET)'
+accepts the completion.  Note the string is used verbatim as a command
+line, so arguments must be quoted in accordance with standard shell rules.
+
+Once a string has been read, the next call to tt(_read_comp) will use the
+existing string instead of reading a new one.  To force a new string to be
+read, call tt(_read_comp) with a numeric argument.
+)
+enditem()
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 644578354..4d439ab30 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -620,7 +620,7 @@ array. If tt(words) contains no word matching var(end-pat), the
 testing and modification is performed as if it were not given.
 )
 item(tt(-q))(
-If the cursor is currently inside single or double quotes, the word
+The word
 currently being completed is split in separate words at the spaces. The 
 resulting words are stored in the tt(words) array, and tt(PREFIX),
 tt(SUFFIX), tt(QIPREFIX), and tt(QISUFFIX) are modified to reflect the 
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 5cc9fe4e3..89f94a507 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -248,6 +248,9 @@ reference on the command line, then they refer to the previous command.
 
 The character sequence `tt(^)var(foo)tt(^)var(bar)'
 repeats the last command, replacing the string var(foo) with var(bar).
+More precisely, the sequence `tt(^)var(foo)tt(^)var(bar)tt(^)' is
+synonymous with `tt(!!:s)tt(^)var(foo)tt(^)var(bar)tt(^)', hence other
+modifiers may follow the final `tt(^)'.
 
 If the shell encounters the character sequence `tt(!")'
 in the input, the history mechanism is temporarily disabled until
@@ -855,10 +858,10 @@ texinode(Command Substitution)(Arithmetic Expansion)(Parameter Expansion)(Expans
 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
-accents, like `tt(`)...tt(`)', is replaced with its standard output, with any
-trailing newlines deleted.
+A command enclosed in parentheses preceded by a dollar sign, like
+`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
 output is broken into words using the tt(IFS) parameter.
 vindex(IFS, use of)
diff --git a/Doc/Zsh/mod_complist.yo b/Doc/Zsh/mod_complist.yo
index 101f4e69c..236896e43 100644
--- a/Doc/Zsh/mod_complist.yo
+++ b/Doc/Zsh/mod_complist.yo
@@ -5,6 +5,12 @@ The tt(complist) module offers two extensions to completion listings:
 the ability to highlight matches in such a list and a different
 style of menu-completion.
 
+Whenever one of the parameters tt(ZLS_COLORS) or tt(ZLS_COLOURS) is set 
+and the tt(complist) module is loaded or linked into the shell,
+completion lists will be colored.  Note, however, that tt(complist) will
+not automatically be loaded if it is not linked in:  on systems with
+dynamic loading, `tt(zmodload complist)' is required.
+
 subsect(Parameters)
 For both extensions one of the parameters tt(ZLS_COLORS) or tt(ZLS_COLOURS)
 must be set, even if the value is empty (which uses all the default values
@@ -12,12 +18,12 @@ given below). These describe how matches are highlighted. The format of the
 value of these parameters is the same as used by the GNU version of the
 tt(ls) command: a colon-separated list of specifications of the form
 `var(name)=var(value)'. The var(name) may be one of the following strings,
-most of which specify file-types for which the var(value) will be used. The
+most of which specify file types for which the var(value) will be used. The
 strings and their default values are:
 
 startitem()
 item(tt(no 0))(
-for normal text (not the string displayed for a match)
+for normal text (i.e. when displaying something other than a matched file)
 )
 item(tt(fi 0))(
 for regular files
@@ -44,7 +50,7 @@ item(tt(ex 35))(
 for executable files
 )
 item(tt(mi) var(none))(
-for names not naming a file (default is the value defined for tt(fi))
+for non-existent file (default is the value defined for tt(fi))
 )
 item(tt(lc \e[))(
 for the left code (see below)
@@ -71,46 +77,51 @@ The default values are ISO 6429 (ANSI) compliant and can be used on
 vt100 compatible terminals such as tt(xterm)s. On monochrome terminals
 the default values will have no visual effect.
 
-Whenever one of the parameters tt(ZLS_COLORS) or tt(ZLS_COLOURS) is set 
-and the tt(complist) module is loaded or linked into the shell,
-completion lists will be colored.
-
 subsect(Menu selection)
-The tt(complist) module also offers a different style of selecting
-matches from a list called menu-selection. It can be invoked directly by
+The tt(complist) module also offers an alternative style of selecting
+matches from a list, called menu-selection. It can be invoked directly by
 the widget tt(menu-select) defined by the module.  Alternatively,
-the parameter tt(SELECTMIN) can be set to an integer giving the minimum
-number of matches which must be present before menu selection is
+the parameter tt(SELECTMIN) can be set to an integer, which give the
+minimum number of matches that must be present before menu selection is
 automatically turned on.  This second method requires that menu completion
 be started, either directly from a widget such as tt(menu-complete), or due
 to one of the options tt(MENU_COMPLETE) or tt(AUTO_MENU) being set.  If
 tt(SELECTMIN) is set, but is 0, 1 or empty, menu selection will always be
-started during menu completion if the completion is ambiguous.
+started during an ambiguous menu completion.
 
 After menu-selection is started, the matches will be listed. The
 matches to insert into the command line can be selected from this
 list. In the list one match is highlighted using the value for tt(ma)
 from the tt(ZLS_COLORS) or tt(ZLS_COLOURS) parameter. The default
 value for this it `tt(7)' which forces the selected match to be
-highlighted using standout mode on a vt100 compatible terminal. If
+highlighted using standout mode on a vt100-compatible terminal. If
 neither tt(ZLS_COLORS) nor tt(ZLS_COLOURS) is set, the same terminal
-control sequence is used as for the `tt(%S)' escape in prompts.
+control sequence as for the `tt(%S)' escape in prompts is used.
 
 Selecting matches is done by moving the mark around using the zle movement
 functions. The zle functions tt(send-break) and tt(accept-line) can be used
 to leave menu-selection, leaving the match currently inserted into the line
-in place. In the case of tt(accept-line), the match currently inserted
-will be accepted and the immediatly trying completion again will
-complete after it. Using tt(send-break) leaves menu-selection and
-continues with normal menu-completion. The functions tt(accept-and-hold) and
+in place.  In the case of tt(accept-line), the match currently inserted
+will be accepted and a new completion may be attempted.
+Using tt(send-break) leaves menu-selection and continues with normal
+menu-completion.  The functions tt(accept-and-hold) and
 tt(accept-and-menu-complete) can be used to accept the match currently
-inserted and continue inserting matches after that. Matches inserted this
-way can be removed by invoking the tt(undo) function. Keys bound to one of
+inserted and continue inserting matches from the same list. The
+function tt(accept-and-infer-next-history) accepts the current match and
+then tries completion with menu-selection again.  In the case of
+files this allows one to select a directory and immediately attempt to
+complete files in it.  Matches inserted in one of these ways can be removed
+by invoking the tt(undo) function.  Keys bound to one of
 the completion functions will cycle to the next (or, in case of
 tt(reverse-menu-complete), the previous) match, and the tt(redisplay) and
 tt(clear-screen) functions work as usual without leaving
-menu-selection. Any other zle function leaves menu-selection and executes
-that function.
+menu-selection.
+
+Any other zle function leaves menu-selection and executes that function.
+It is possible to make widgets in the above list do the same by using the
+form of the widget with a `tt(.)' in front.  For example, the widget
+`tt(.accept-line)' has the effect of leaving menu selection and accepting
+the entire command line.
 
 During this selection the widget uses the keymap tt(menuselect). Any
 key that is not defined in this keymap or that is bound to
@@ -124,6 +135,6 @@ ifnzman(noderef(The zle Module))\
 ). For example, to make the return key leave menu-selection and
 continue with normal menu-completion one can call
 
-indent(tt(bindkey -M menuselect '^J' send-break))
+indent(tt(bindkey -M menuselect '^M' send-break))
 
 after loading the tt(complist) module.
diff --git a/Doc/Zsh/mod_zle.yo b/Doc/Zsh/mod_zle.yo
index cae4eadc2..7d438a5d4 100644
--- a/Doc/Zsh/mod_zle.yo
+++ b/Doc/Zsh/mod_zle.yo
@@ -177,7 +177,8 @@ xitem(tt(zle) tt(-D) var(widget) ...)
 xitem(tt(zle) tt(-A) var(old-widget) var(new-widget))
 xitem(tt(zle) tt(-N) var(widget) [ var(function) ])
 xitem(tt(zle) tt(-C) var(widget) var(completion-widget) var(function))
-xitem(tt(zle) tt(-R) [ var(display-string) ])
+xitem(tt(zle) tt(-R) [ tt(-c) ] [ var(display-string) ] [ var(string) ... ])
+xitem(tt(zle) tt(-U) var(string))
 item(tt(zle) var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)(
 The tt(zle) builtin performs a number of different actions concerning
 ZLE.  Which operation it performs depends on its options:
@@ -227,11 +228,21 @@ ifzman(zmanref(zshcompwid))\
 ifnzman(noderef(Completion Widgets))\
 .
 )
-item(tt(-R) [ var(display-string) ])(
+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
-given, this is shown in the status line (immediately below the line being
-edited).
+given and not empty, this is shown in the status line (immediately
+below the line being edited).
+
+If the optional var(string)s are given they are listed below the
+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.
+)
+item(tt(-U) var(string))(
+This puts the characters in the var(string) in the input queue of
+ZLE. After the widget currently executed finishes ZLE will behave as
+if the characters in the var(string) were typed by the user.
 )
 item(var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)(
 Invoke the specified widget.  This can only be done when ZLE is
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index ecf93864f..05bd24613 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -108,14 +108,15 @@ be a list of flags. The flags currently understood are:
 
 startitem()
 item(tt(e))(
-this option has no effect and retained for backward compatibility only.
+This option has no effect and retained for backward compatibility only.
 )
 item(tt(w))(
-if the parameter subscripted is a scalar than this flag makes
-subscription work on a per-word basis instead of characters.
+If the parameter subscripted is a scalar than this flag makes
+subscripting work on words instead of characters.  The default word
+separator is whitespace.
 )
 item(tt(s:)var(string)tt(:))(
-this gives the var(string) that separates words (for use with the
+This gives the var(string) that separates words (for use with the
 tt(w) flag).
 )
 item(tt(p))(
@@ -123,21 +124,22 @@ Recognize the same escape sequences as the tt(print) builtin in
 the string argument of a subsequent `tt(s)' flag.
 )
 item(tt(f))(
-if the parameter subscripted is a scalar than this flag makes
-subscription work on a per-line basis instead of characters.
-This is a shorthand for `tt(pws:\n:)'.
+If the parameter subscripted is a scalar than this flag makes
+subscripting work on lines instead of characters, i.e. with elements
+separated by newlines.  This is a shorthand for `tt(pws:\n:)'.
 )
 item(tt(r))(
-if this flag is given the var(exp) is taken as a pattern and the
-result is the first matching array element, substring or word (if the
-parameter is an array, if it is a scalar, or if it is a scalar and the
-`tt(w)' flag is given, respectively); note that this is like giving a
-number: `tt($foo[(r))var(??)tt(,3])' and `tt($foo[(r))var(??)tt(,(r)f*])' work.
-If the parameter is an associative array, only the value part of each pair
-is compared to the pattern.
+Reverse subscripting:  if this flag is given, the var(exp) is taken as a
+pattern and the  result is the first matching array element, substring or
+word (if the parameter is an array, if it is a scalar, or if it is a scalar
+and the `tt(w)' flag is given, respectively).  The subscript used is the
+number of the matching element, so that pairs of subscripts such as
+`tt($foo[(r))var(??)tt(,3])' and `tt($foo[(r))var(??)tt(,(r)f*])'
+are possible.  If the parameter is an associative array, only the value part
+of each pair is compared to the pattern.
 )
 item(tt(R))(
-like `tt(r)', but gives the last match.  For associative arrays, gives
+Like `tt(r)', but gives the last match.  For associative arrays, gives
 all possible matches.
 )
 item(tt(i))(
@@ -188,8 +190,7 @@ Shell function executions delimit scopes for shell parameters.
 (Parameters are dynamically scoped.)  The tt(typeset) builtin, and its
 alternative forms tt(declare), tt(integer), tt(local) and tt(readonly)
 (but not tt(export)), can be used to declare a parameter as being local
-to the innermost scope.  Note that em(special) parameters cannot be made
-local.
+to the innermost scope.
 
 When a parameter is read or assigned to, the
 innermost existing parameter of that name is used.  (That is, the
@@ -200,6 +201,23 @@ causes it to be created in the em(outer)most scope.
 Local parameters disappear when their scope ends.
 tt(unset) can be used to delete a parameter while it is still in scope;
 any outer parameter of the same name remains hidden.
+
+Special parameters may also be made local; they retain their special
+attributes.  This may have unexpected effects.  Firstly, there is no
+default value, so if there is no assigment at the point the variable is
+made local, it will be set to an empty value (or zero in the case of
+integers).  Secondly, special parameters which are made local will not be
+exported (as with other parameters), so that the global value of the
+parameter remains present in the environment if it is already there.  This
+should be particularly noted in the case of tt(PATH): the shell will use
+the local version of tt(PATH) for finding programmes, but programmes using
+the shell's environment will inherit the global version.  The following:
+
+example(typeset PATH=/new/directory:$PATH)
+
+is valid for temporarily allowing the shell to find the programs in
+tt(/new/directory) inside a function.
+
 texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Local Parameters)(Parameters)
 sect(Parameters Set By The Shell)
 The following parameters are automatically set by the shell:
@@ -715,12 +733,12 @@ set up the terminal before executing the command. The modes apply only to the
 command, and are reset when it finishes or is suspended. If the command is
 suspended and continued later with the tt(fg) or tt(wait) builtins it will
 see the modes specified by tt(STTY), as if it were not suspended.  This
-(intentionally) does not apply if the command is continued via `tt(kill -CONT)'.
-tt(STTY) is ignored if the command is run in the background, or 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.
+(intentionally) does not apply if the command is continued via `tt(kill
+-CONT)'.  tt(STTY) is ignored if the command is run in the background, or
+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.
 )
 vindex(TERM)
 item(tt(TERM) <S>)(
diff --git a/Doc/Zsh/prompt.yo b/Doc/Zsh/prompt.yo
index 29f1f2c22..a7a220633 100644
--- a/Doc/Zsh/prompt.yo
+++ b/Doc/Zsh/prompt.yo
@@ -42,21 +42,14 @@ A `tt(RPAR())'.
 )
 xitem(tt(%d))
 item(tt(%/))(
-Present working directory (tt($PWD)).
+Present working directory (tt($PWD)).  If an integer follows the `tt(%)',
+it specifies a number of trailing components of tt($PWD) to show; zero
+means the whole path.
 )
 item(tt(%~))(
-tt($PWD).
-If it has a named directory as its prefix, that part is replaced
-by a `tt(~)' followed by the name of the directory.
-If it starts with tt($HOME), that part is
-replaced by a `tt(~)'.
-)
-xitem(tt(%c))
-xitem(tt(%.))
-item(tt(%C))(
-Trailing component of tt($PWD).
-An integer may follow the `tt(%)' to get more than one component.
-Unless `tt(%C)' is used, tilde contraction is performed first.
+As tt(%d) and tt(%/), but if tt($PWD) has a named directory as its prefix,
+that part is replaced by a `tt(~)' followed by the name of the directory.
+If it starts with tt($HOME), that part is replaced by a `tt(~)'.
 )
 xitem(tt(%h))
 item(tt(%!))(
@@ -98,7 +91,9 @@ tt($USERNAME).
 item(tt(%N))(
 The name of the script, sourced file, or shell function that zsh is
 currently executing, whichever was started most recently.  If there is
-none, this is equivalent to the parameter tt($0).
+none, this is equivalent to the parameter tt($0).  An integer may follow
+the `tt(%)' to specify a number of trailing path components to show; zero
+means the full path.
 )
 item(tt(%i))(
 The line number currently being executed in the script, sourced file, or
@@ -235,4 +230,14 @@ current directory, followed by a `tt(%)' or `tt(#)', followed by a
 space.  Without the `tt(%<<)', those two characters would be included
 in the string to be truncated.
 )
+xitem(tt(%c))
+xitem(tt(%.))
+item(tt(%C))(
+Trailing component of tt($PWD).
+An integer may follow the `tt(%)' to get more than one component.
+Unless `tt(%C)' is used, tilde contraction is performed first.  These are
+deprecated as tt(%c) and tt(%C) are equivalent to tt(%1~) and tt(%1/),
+respectively, while explicit positive integers have the same effect as for
+the latter two sequences.
+)
 enditem()