4 files changed, 208 insertions, 93 deletions
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index e9bc2ab16..7cbdb1114 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -318,10 +318,13 @@ cindex(file, history)
 tt(fc -R) reads the history from the given file,
 tt(fc -W) writes the history out to the given file,
 and tt(fc -A) appends the history out to the given file.
-If the tt(-I) option is added, only those
-events that are new since last incremental append (write) to
-the history file are appended (written).
-In any case the file will have no more than tt($SAVEHIST)
+If no filename is specified, the tt($HISTFILE) is assumed.
+If the tt(-I) option is added to tt(-R), only those events that are
+not already contained within the internal history list are added.
+If the tt(-I) option is added to tt(-A) or tt(-W), only those
+events that are new since last incremental append/write to
+the history file are appended/written.
+In any case, the created file will have no more than tt($SAVEHIST)
 entries.
 )
 findex(fg)
@@ -1169,30 +1172,26 @@ Equivalent to tt(whence -c).
 findex(zmodload)
 cindex(modules, loading)
 cindex(loading modules)
-xitem(tt(zmodload) [ tt(-iL) ] [ var(name) ... ])
-xitem(tt(zmodload) tt(-u) [ tt(-i) ] var(name) ...)
-xitem(tt(zmodload) tt(-d) [ tt(-L) ] [ var(name) [ var(dep) ... ] ])
-xitem(tt(zmodload) tt(-du) var(name) [ var(dep) ... ])
-xitem(tt(zmodload) tt(-a) [ tt(-iL) ] [ var(name) [ var(builtin) ... ] ])
-xitem(tt(zmodload) tt(-au) [ tt(-i) ] var(builtin) ...)
-xitem(tt(zmodload) tt(-c) [ tt(-iI) ] var(name) [ var(cond) ... ])
-xitem(tt(zmodload) tt(-cu) [ tt(-iI) ] var(cond) ...)
-xitem(tt(zmodload) tt(-c) [ tt(-IL) ])
-xitem(tt(zmodload) tt(-p) [ tt(-i) ] var(name) [ var(parameter) ... ])
-xitem(tt(zmodload) tt(-pu) [ tt(-i) ] var(parameter) ... ])
-item(tt(zmodload) tt(-p) [ tt(-L) ])(
+xitem(tt(zmodload) [ tt(-dL) ] [ ... ])
+xitem(tt(zmodload) [ tt(-a) [ tt(-bcp) [ tt(-I) ] ] ] [ tt(-iL) ] ...)
+item(tt(zmodload) tt(-u) [ tt(-abcdp) [ tt(-I) ] ] [ tt(-iL) ] ...)(
 tt(zmodload) performs operations relating to zsh's loadable modules.
 This feature is not available on all operating systems,
 or on all installations on a particular operating system.
 
-In the simplest case,
-tt(zmodload) loads a binary module.  The module must be in a file with a
-name consisting of the specified var(name) followed by a standard suffix,
-usually `tt(.so)'.  If this can't be found, the var(name) is tried without
-the suffix.
-If the module to be loaded is already loaded and the tt(-i)
-option is given, the duplicate module is ignored.  Otherwise
-tt(zmodload) prints an error message.
+Without arguments all currently loaded binary modules are printed.
+The tt(-L) option causes this list to be in the form of a series of
+tt(zmodload) commands.  Forms with arguments are:
+
+startitem()
+xitem(tt(zmodload) [ tt(-i) ] var(name) ... )
+item(tt(zmodload) tt(-u) [ tt(-i) ] var(name) ...)(
+In the simplest case, tt(zmodload) loads a binary module.  The module must
+be in a file with a name consisting of the specified var(name) followed by
+a standard suffix, usually `tt(.so)'.  If this can't be found, the
+var(name) is tried without the suffix.  If the module to be loaded is
+already loaded and the tt(-i) option is given, the duplicate module is
+ignored.  Otherwise tt(zmodload) prints an error message.
 
 The var(name)d module is searched for in the same way a command is, using
 tt($module_path) instead of tt($path).  If var(name) contains a `tt(/)',
@@ -1209,55 +1208,66 @@ unloaded (or was never loaded).
 Each module has a boot and a cleanup function.  The module
 will not be loaded if its boot function fails.  Similarly a module
 can only be unloaded if its cleanup function runs successfully.
-
-Without arguments all currently loaded binary modules are printed.
-The tt(-L) option causes this list to be in the form of a series of
-tt(zmodload) commands.
-
-The tt(-d) option can be used to specify module dependencies.
-This operation is idempotent regardless of the tt(-i) option.
-The modules named in the second and subsequent arguments will be
-loaded before the module named in the first argument.
-
-With tt(-d) and one
-argument, all dependencies for that module are listed.  With tt(-d) and no
-arguments, all module dependencies are listed.
-This listing is by default in a Makefile-like format.
-The tt(-L) option changes this format to a list of
-tt(zmodload -d) commands.
-
-If tt(-d) and tt(-u) are both used, dependencies are removed.
-This operation is idempotent regardless of the tt(-i) option.
-If only one argument is given, all dependencies for that module are removed.
-
-The tt(-a) option defines autoloaded builtins.  It defines the
-specified var(builtin)s.  When any of those builtins is called, the module
-specified in the first argument is loaded.  If only one argument is given,
-one builtin is defined, with the same name as the module.
-tt(-i) suppresses the error if the builtin is already defined or
-autoloaded, regardless of which module it came from.
-
-With tt(-a) and no arguments, all
-autoloaded builtins are listed, with the module name (if different)
-shown in parentheses after the builtin name.  The tt(-L) option changes
-this format to a list of tt(zmodload -a) commands.
-
-If tt(-a) is used
-together with the tt(-u) option it removes builtins defined with
-tt(zmodload -a).  This is only possible if the builtin is not yet
-loaded.  tt(-i) suppresses the error if the builtin is already
+)
+xitem(tt(zmodload) tt(-d) [ tt(-L) ] [ var(name) ])
+xitem(tt(zmodload) tt(-d) var(name) var(dep) ...)
+item(tt(zmodload) tt(-ud) var(name) [ var(dep) ... ])(
+The tt(-d) option can be used to specify module dependencies.  The modules
+named in the second and subsequent arguments will be loaded before the
+module named in the first argument.
+
+With tt(-d) and one argument, all dependencies for that module are listed.
+With tt(-d) and no arguments, all module dependencies are listed.  This
+listing is by default in a Makefile-like format.  The tt(-L) option
+changes this format to a list of tt(zmodload -d) commands.
+
+If tt(-d) and tt(-u) are both used, dependencies are removed.  If only one
+argument is given, all dependencies for that module are removed.
+)
+xitem(tt(zmodload) tt(-ab) [ tt(-L) ])
+xitem(tt(zmodload) tt(-ab) [ tt(-i) ] var(name) [ var(builtin) ... ])
+item(tt(zmodload) tt(-ub) [ tt(-i) ] var(builtin) ...)(
+The tt(-ab) option defines autoloaded builtins.  It defines the specified
+var(builtin)s.  When any of those builtins is called, the module specified
+in the first argument is loaded.  If only the var(name) is given, one
+builtin is defined, with the same name as the module.  tt(-i) suppresses
+the error if the builtin is already defined or autoloaded, regardless of
+which module it came from.
+
+With tt(-ab) and no arguments, all autoloaded builtins are listed, with the
+module name (if different) shown in parentheses after the builtin name.
+The tt(-L) option changes this format to a list of tt(zmodload -a)
+commands.
+
+If tt(-b) is used together with the tt(-u) option, it removes builtins
+previously defined with tt(-ab).  This is only possible if the builtin is
+not yet loaded.  tt(-i) suppresses the error if the builtin is already
 removed (or never existed).
-
-The tt(-c) option is used to define autoloaded condition codes. The
+)
+xitem(tt(zmodload) tt(-ac) [ tt(-IL) ])
+xitem(tt(zmodload) tt(-ac) [ tt(-iI) ] var(name) [ var(cond) ... ])
+item(tt(zmodload) tt(-uc) [ tt(-iI) ] var(cond) ...)(
+The tt(-ac) option is used to define autoloaded condition codes. The
 var(cond) strings give the names of the conditions defined by the
 module. The optional tt(-I) option is used to define infix condition
 names. Without this option prefix condition names are defined.
 
-Together with the tt(-u) option definitions for autoloaded conditions
-are removed. If given no condition names all defined names are listed
-(as a series of tt(zmodload) commands if the tt(-L) option is given).
+If given no condition names, all defined names are listed (as a series of
+tt(zmodload) commands if the tt(-L) option is given).
 
-The tt(-p) option is like the tt(-c) option, but makes tt(zmodload)
-work on autoloaded parameters instead of condition codes.
+The tt(-uc) option removes definitions for autoloaded conditions.
+)
+xitem(tt(zmodload) tt(-ap) [ tt(-L) ])
+xitem(tt(zmodload) tt(-ap) [ tt(-i) ] var(name) [ var(parameter) ... ])
+item(tt(zmodload) tt(-up) [ tt(-i) ] var(parameter) ...)(
+The tt(-p) option is like the tt(-b) and tt(-c) options, but makes
+tt(zmodload) work on autoloaded parameters instead.
+)
+xitem(tt(zmodload) tt(-a) [ tt(-L) ])
+xitem(tt(zmodload) tt(-a) [ tt(-i) ] var(name) [ var(builtin) ... ])
+item(tt(zmodload) tt(-ua) [ tt(-i) ] var(builtin) ...)(
+Equivalent to tt(-ab) and tt(-ub).
+)
+enditem()
 )
 enditem()
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index cedc4ec8c..90f6b2910 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -49,14 +49,42 @@ endmenu()
 texinode(Initialisation)(Control Functions)()(Completion System)
 sect(Initialisation)
 
+The script tt(compinstall) can be run by a user to set up the completion
+system for use.  It will usually insert code into tt(.zshrc), although if
+that is not writeable it will save it in another file and tell you that
+file's locations.  Note that it is up to you to make sure that the lines
+added to tt(.zshrc) are actually run; you may, for example, need to move
+them to an earlier place in the file if tt(.zshrc) usually returns early.
+So long as you keep them all together (including the comment lines at the
+start and finish), you can rerun tt(compinstall) and it will correctly
+locate and modify these lines.  Note, however, that any code you add to
+this section by hand is likely to be lost if you rerun tt(compinstall).
+
+You can run it as `tt(source )var(<path>)tt(/compinstall)' or
+`tt(. )var(<path>)tt(/compinstall)', where var(<path>) is where the
+completion functions are stored.  It will ask you various questions about
+how you would like completion set up.  It is in two parts; the basic part
+locates the completion files and decides where to put your personal
+dumpfile, used to speed up initialisation after the first time.  After
+that, you will be asked if you wish to go on to the advanced set-up; if you
+answer tt(n), you can rerun tt(compinstall) later without having to
+re-enter any of the basic settings.
+
+You can abort the installation any time you are being prompted for
+information, and your tt(.zshrc) will not be altered at all.
+
+subsect(Use of compinit)
+
+This section describes the use of tt(compinit) to initialize completion for
+the current session when run directly by the user; if you have run
+tt(compinstall) it will be called automatically from your tt(.zshrc).
+
 To initialise the system, the script tt(compinit) should be sourced with
 `tt(source )var(<path>)tt(/compinit)' or
 `tt(. )var(<path>)tt(/compinit)'. This will define a few utility functions,
 arrange for all the necessary shell functions to be autoloaded, and will
 then re-bind all keys that do completion to use the new system.
 
-subsect(Arguments)
-
 To speed up the running of tt(compinit), it can be made to produce a dumped
 configuration which will be read in on future invocations.  The easiest way
 to do this is by adding the option tt(-d) whenever tt(compinit) is sourced.
@@ -65,6 +93,15 @@ but with tt(.dump) appended to the end; alternatively, an explicit file
 name can be given following the tt(-d).  On the next call to tt(compinit
 -d), the dumped file will be read instead.
 
+The other option accepted by tt(compinit) is tt(-f var(dir)), which gives
+the directory in which tt(compinit) resides.  If you source tt(compinit) by
+its full pathname, and the option tt(FUNCTION_ARGZERO) is set, as it is by
+default unless tt(zsh) is emulating tt(sh) or tt(ksh), this is unnecessary
+as tt(compinit) can deduce the directory for itself.  It is used in two
+ways: to find the program tt(compdump) used by the tt(-d) option, and to
+check if the directory should be added to the function search path to find
+the completion functions (see below).
+
 If the number of completion files changes, tt(compinit) will recognise this
 and produce a new dump file.  However, if the name of a function or the
 arguments in the first line of a tt(#compdef) funcion (as described below)
@@ -80,8 +117,18 @@ subsect(Autoloaded files)
 
 The convention for autoloaded functions used in completion is that they
 start with an underscore; as already mentioned, the tt(fpath/FPATH)
-parameter must contain the directory in which they are stored.  When
-tt(compinit) is sourced, it searches all such files accessible via
+parameter must contain the directory in which they are stored.  If
+tt(compinit) does not find enough files beginning with an underscore (fewer
+than twenty) in the search path, it will try to find more by adding its own
+directory to the search path.  If you keep all the completion files in this
+directory, this means you never have to alter tt(fpath/FPATH) yourself.
+Furthermore, if the directory in question ends in the path segment
+tt(Core), or has a subdirectory named tt(Core), tt(compinit) will add all
+subdirectories of the directory where tt(Core) is to the path: this allows
+the functions to be in the same format as in the tt(zsh) source
+distribution.
+
+When tt(compinit) is sourced, it searches all such files accessible via
 tt(fpath/FPATH) and reads the first line of each of them.  This line should
 contain one of the tags described below. Files whose first line does not
 start with one of these tags are not considered to be part of the
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 0326e646d..5853d792f 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -717,18 +717,24 @@ If multiple nested tt(${...}) forms are present, substitution is
 performed from the inside outwards.  At each level, the substitution takes
 account of whether the current value is a scalar or an array, whether the
 whole substitution is in double quotes, and what flags are supplied to the
-current level of substitution; the flags are not propagated up to enclosing
-substitutions.  The value passed back to an enclosing substitution is
-always an array, which however will consist of one word if the value was
-not itself an array.  All the following steps take place where applicable
-at all levels of substitution.
+current level of substitution, just as if the nested substitution were the
+outermost.  The flags are not propagated up to enclosing
+substitutions; the nested subsitution will return either a scalar or an
+array as determined by the flags, possibly adjusted for quoting.  All the
+following steps take place where applicable at all levels of substitution.
+Note that, unless the tt((P)) flag is present, the flags and any subscripts
+apply directly to the value of the nested substitution; for example, the
+expansion tt(${${foo}}) behaves exactly the same as tt(${foo}).
 )
 item(tt(2.) em(Parameter Subscripting))(
 If the value is a raw parameter reference with a subscript, such as
 tt(${)var(var)tt([3]}), the effect of subscripting is applied directly to
-the parameter.  If the parameter is an array, any second subscript,
-indexing on the character in the word, may appear,
-e.g. tt(${)var(var)tt([1][2]}).
+the parameter.  Subscripts are evaluated left to right; subsequent
+subscripts apply to the scalar or array value yielded by the previous
+subscript.  Thus if tt(var) is an array, tt(${var[1][2]}) is the second
+character of the first word, but tt(${var[2,4][2]}) is the entire third
+word (the second word of the range of words two through four of the
+original array).  Any number of subscripts may appear.
 )
 item(tt(3.) em(Parameter Name Replacement))(
 The effect of any tt((P)) flag, which treats the value so far as a
@@ -746,6 +752,10 @@ item(tt(5.) em(Nested Subscripting))(
 Any remaining subscript (i.e. of a nested substitution) is evaluated at
 this point, based on whether the value is an array or a scalar; if it was
 an array, a second subscript for the character in the word may also appear.
+Note that tt(${foo[2,4][2]}) is thus equivalent to tt(${${foo[2,4]}[2]})
+and also to tt("${${(@)foo[2,4]}[2]}") (the nested substitution returns an
+array in both cases), but not to tt("${${foo[2,4]}[2]}") (the nested
+substitution returns a scalar because of the quotes).
 )
 item(tt(6.) em(Modifiers))(
 Any modifiers, as specified by a trailing tt(#), tt(%), tt(/)
@@ -798,20 +808,17 @@ Suppose that tt($foo) contains the array tt(LPAR()bar baz)tt(RPAR()):
 
 startitem()
 item(tt("${(@)${foo}[1]}"))(
-This produces the result tt(bar baz).  First, the inner substitution
+This produces the result tt(b).  First, the inner substitution
 tt("${foo}"), which has no array (tt(@)) flag, produces a single word
-result.  The outer substitution tt("${(@)...[1]}") acts on this result as
-if it were a one word array, because of the array flag, so the result is
-just that 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. 
 )
 item(tt("${${(@)foo}[1]}"))(
-The produces the result tt(b).  In this case, the inner substitution
+The produces the result tt(bar).  In this case, the inner substitution
 tt("${(@)foo}") produces the array tt(LPAR()bar baz)tt(RPAR()).  The outer
-substitution tt("${...[1]}"), however, has no array flag, so that it joins
-the array it has to a single word and indexes as if it were a string.  Note
-that this is not identical to the case tt("${foo[1]}"), since here the
-expression tt(foo[1]) is recognised immediately as an index into an array,
-so that the result in that case is tt(bar).
+substitution tt("${...[1]}") detects that this is an array and picks the
+first word.  This is similar to the simple case tt("${foo[1]}").
 )
 enditem()
 
diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo
index 92de8c2d8..41c5ce24e 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -302,9 +302,10 @@ always produces named directory expansion.)
 pindex(EXTENDED_HISTORY)
 cindex(history, timestamping)
 item(tt(EXTENDED_HISTORY))(
-Save beginning and ending timestamps to the history file.
-The format of these timestamps is
-`tt(:)var(<beginning time>)tt(:)var(<ending time>)tt(:)var(<command>)'.
+Save each command's beginning timestamp (in seconds since the epoch)
+and the duration (in seconds) to the history file.  The format of
+this prefixed data is
+`tt(:)var(<beginning time>)tt(:)var(<elapsed seconds>)tt(:)var(<command>)'.
 )
 pindex(FLOW_CONTROL)
 cindex(flow control)
@@ -405,6 +406,20 @@ item(tt(HIST_BEEP))(
 Beep when an attempt is made to access a history entry which
 isn't there.
 )
+pindex(HIST_EXPIRE_DUPS_FIRST)
+cindex(history, expiring duplicates)
+item(tt(HIST_EXPIRE_DUPS_FIRST))(
+If the history needs to be trimmed to add a new line, setting this
+option will cause the oldest duplicate history line to be lost before
+losing a unique line from the internal history list.
+)
+pindex(HIST_IGNORE_ALL_DUPS)
+cindex(history, ignoring all duplicates)
+item(tt(HIST_IGNORE_ALL_DUPS) (tt(-h)))(
+If a new command line being added to the history list duplicates an
+older one, the older command is removed from the list (even if it is
+not the previous event).
+)
 pindex(HIST_IGNORE_DUPS)
 cindex(history, ignoring duplicates)
 item(tt(HIST_IGNORE_DUPS) (tt(-h)))(
@@ -426,6 +441,11 @@ item(tt(HIST_NO_STORE))(
 Remove the tt(history) (tt(fc -l)) command from
 the history when invoked.
 )
+pindex(HIST_SAVE_NO_DUPS)
+item(tt(HIST_SAVE_NO_DUPS))(
+When writing out the history file, older commands that duplicate
+newer ones are omitted.
+)
 pindex(HIST_REDUCE_BLANKS)
 item(tt(HIST_REDUCE_BLANKS))(
 Remove superfluous blanks from each command line
@@ -459,6 +479,15 @@ of tt(exit) or tt(logout) instead.
 However, ten consecutive EOFs will cause the shell to exit anyway,
 to avoid the shell hanging if its tty goes away.
 )
+pindex(INCREMENTAL_APPEND_HISTORY)
+cindex(history, incremental appending to a file)
+item(tt(INCREMENTAL_APPEND_HISTORY))(
+This options works like APPEND_HISTORY except that new history lines
+are added to the tt($HISTFILE) when they finish running, rather than
+waiting until the shell is killed. The file is periodically trimmed
+to the number of lines specified by tt($SAVEHIST), but can exceed this
+value between trimmings.
+)
 pindex(INTERACTIVE)
 item(tt(INTERACTIVE) (tt(-i), ksh: tt(-i)))(
 This is an interactive shell.  This option is set upon initialisation if
@@ -798,6 +827,28 @@ This avoids the problem of reflexively answering `yes' to the query
 when one didn't really mean it.  The wait and query can always be
 avoided by expanding the `tt(*)' in ZLE (with tab).
 )
+pindex(SHARE_HISTORY)
+cindex(share history)
+cindex(history, sharing)
+item(tt(SHARE_HISTORY))(
+
+This option both imports new commands from the history file, and also
+causes your typed commands to be appended to the history file (like
+specifiying tt(INCREMENTAL_APPEND_HISTORY)).  The history lines are also
+output with timestamps ala tt(EXTENDED_HISTORY) (which makes it easier to
+find the spot where we left off reading the file after it gets re-written).
+
+By default, history movement commands visit the imported lines as well as
+the local lines, but you can toggle this on and off with the
+set-local-history zle binding.  It is also possible to create a zle
+widget that will make some commands ignore imported commands, and some
+include them.
+
+If you find that you want more control over when commands
+get imported, you may wish to turn tt(SHARE_HISTORY) off,
+tt(INCREMENTAL_APPEND_HISTORY) on, and then manually import
+commands whenever you need them using `fc -RI'.
+)
 pindex(SH_FILE_EXPANSION)
 cindex(sh, expansion style)
 cindex(expansion style, sh)