Update files to 4.2.4

4 files changed, 392 insertions, 173 deletions

diff --git a/ChangeLog b/ChangeLog
index c22e0bf45..a397e2748 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2005-02-02  Peter Stephenson  <pws@csr.com>
+
+	* unposted: README, Config/version.mk, Etc/FAQ.yo: update version
+	number to 4.2.4.
+
 2005-02-01  Bart Schaefer  <schaefer@zsh.org>
 
 	* 20774: Src/exec.c: fix e.g. "FOO=BAR BAR=FOO echo" failure to
diff --git a/Config/version.mk b/Config/version.mk
index a7f855515..9a52cc83e 100644
--- a/Config/version.mk
+++ b/Config/version.mk
@@ -27,5 +27,5 @@
 # This must also serve as a shell script, so do not add spaces around the
 # `=' signs.
 
-VERSION=3.1.6-dev-20
-VERSION_DATE='February 23, 2000'
+VERSION=4.2.4
+VERSION_DATE='February 2, 2005'
diff --git a/Etc/FAQ.yo b/Etc/FAQ.yo
index 0e1274300..ebcd0925f 100644
--- a/Etc/FAQ.yo
+++ b/Etc/FAQ.yo
@@ -43,20 +43,14 @@ whenlatex(report(ARG1)(ARG2)(ARG3))\
 whenman(report(ARG1)(ARG2)(ARG3))\
 whenms(report(ARG1)(ARG2)(ARG3))\
 whensgml(report(ARG1)(ARG2)(ARG3)))
-myreport(Z-Shell Frequently-Asked Questions)(Peter Stephenson)(2000/1/25)
+myreport(Z-Shell Frequently-Asked Questions)(Peter Stephenson)(2005/01/11)
 COMMENT(-- the following are for Usenet and must appear first)\
 description(\
 mydit(Archive-Name:) unix-faq/shell/zsh
-mydit(Last-Modified:) 2000/11/25
-mydit(Submitted-By:) email(pws@ibmth.df.unipi.it (Peter Stephenson))
-mydit(Version:) $Id: FAQ.yo,v 1.1.1.20 2000/02/03 01:21:45 akr Exp $
+mydit(Last-Modified:) 2005/01/11
+mydit(Submitted-By:) email(pws@pwstephenson.fsnet.co.uk (Peter Stephenson))
 mydit(Posting-Frequency:) Monthly
-mydit(Copyright:) (C) P.W. Stephenson, 1995--2000 (see end of document)
-)
-
-bf(Changes since issue posted December 1999:)
-description(
-mydit(   )  None.  Suggestions on a postcard.
+mydit(Copyright:) (C) P.W. Stephenson, 1995--2005 (see end of document)
 )
 
 This document contains a list of frequently-asked (or otherwise
@@ -94,6 +88,7 @@ Chapter 2:  How does zsh differ from...?
 2.4. tcsh?
 2.5. bash?
 2.6. Shouldn't zsh be more/less like ksh/(t)csh?
+2.7. What is zsh's support for Unicode/UTF-8?
 
 Chapter 3:  How to get various things to work
 3.1. Why does `$var' where `var="foo bar"' not do what I expect?
@@ -120,6 +115,8 @@ Chapter 3:  How to get various things to work
 3.22. How do I get a variable's value to be evaluated as another variable?
 3.23. How do I prevent the prompt overwriting output when there is no newline?
 3.24. What's wrong with cut and paste on my xterm?
+3.25. How do I get coloured prompts on my colour xterm?
+3.26. Why is my output duplicated with `tt(foo 2>&1 >foo.out | bar)'?
 
 Chapter 4:  The mysteries of completion
 4.1. What is completion?
@@ -133,7 +130,7 @@ Chapter 5:  The future of zsh
 5.1. What bugs are currently known and unfixed? (Plus recent important changes)
 5.2. Where do I report bugs, get more info / who's working on zsh?
 5.3. What's on the wish-list?
-5.4. Will zsh have problems in the year 2000?
+5.4. Did zsh have problems in the year 2000?
 
 Acknowledgments
 
@@ -147,22 +144,21 @@ sect(Sources of information)
 label(11)
 
   Information on zsh is available via the World Wide Web.  The URL
-  is url(http://sunsite.auc.dk/zsh/)(http://sunsite.auc.dk/zsh/) (note the \
-  change of address from the
-  end of April 1998).  The server provides this FAQ and much else and is
+  is url(http://sunsite.dk/zsh/)(http://sunsite.dk/zsh/) .
+  The server provides this FAQ and much else and is
   now maintained by Karsten Thygesen and others (mail \
-  email(zsh@sunsite.auc.dk)
+  email(zsh@sunsite.dk)
   with any related messages).  The FAQ is at \
-url(http://sunsite.auc.dk/zsh/FAQ/)(http://sunsite.auc.dk/zsh/FAQ/) .
+url(http://sunsite.dk/zsh/FAQ/)(http://sunsite.dk/zsh/FAQ/) .
   The site also contains some contributed zsh scripts and functions;
   we are delighted to add more, or simply links to your own collection.
 
   This document was originally written in YODL, allowing it to be converted
   easily into various other formats.  The master source file lives at
-  url(http://sunsite.auc.dk/zsh/FAQ/zshfaq.yo)
-(http://sunsite.auc.dk/zsh/FAQ/zshfaq.yo) and the plain text version
-  can be found at url(http://sunsite.auc.dk/zsh/FAQ/zshfaq.txt)
-(http://sunsite.auc.dk/zsh/FAQ/zshfaq.txt) .
+  url(http://sunsite.dk/zsh/FAQ/zshfaq.yo)
+(http://sunsite.dk/zsh/FAQ/zshfaq.yo) and the plain text version
+  can be found at url(http://sunsite.dk/zsh/FAQ/zshfaq.txt)
+(http://sunsite.dk/zsh/FAQ/zshfaq.txt) .
 
   Another useful source of information is the collection of FAQ articles
   posted frequently to the Usenet news groups comp.unix.questions,
@@ -188,13 +184,15 @@ email(mail-server@rtfm.mit.edu)
   The latest version of this FAQ is also available directly from any
   of the zsh archive sites listed in question link(1.6)(16).
 
-  There is now a preliminary version of a reference card for
-  zsh 3.0, which you can find (while it's being developed) at
-    url(http://www.ifh.de/~pws/computing/refcard.ps)
-    (http://www.ifh.de/~pws/computing/refcard.ps)
-  This is optimised for A4 paper. The tt(LaTeX) source is in the
-  same place with the extension tt(.tex).  It is not a good place
-  from which to learn zsh for the first time.
+  I have been putting together a user guide to complement the manual by
+  explaining the most useful features of zsh in a more easy to read way.
+  This will be a long project, but a partial version describing how to
+  write startup files and how to use the new, more powerful, form for
+  completion which first appeared in 3.1.6 (and is not described in this
+  FAQ) can be seen by looking at
+    url(http://www.pwstephenson.fsnet.co.uk/computing/)
+(http://www.pwstephenson.fsnet.co.uk/computing/)
+  where it exists in various formats.
 
   (As a method of reading the following in Emacs, you can type tt(\M-2
   \C-x $) to make all the indented text vanish, then tt(\M-0 \C-x $)
@@ -236,16 +234,16 @@ sect(What is it good at?)
   itemize(
   it() Command line editing:
   itemize(
-    it() programmable completion: incorporates the ability to use
-       the full power of zsh globbing (compctl -g),
+    it() programmable completion: incorporates the ability to use the
+       full power of zsh's globbing and shell programming features,
     it() multi-line commands editable as a single buffer (even files!),
     it() variable editing (vared),
     it() command buffer stack,
     it() print text straight into the buffer for immediate editing (print -z),
     it() execution of unbound commands,
-    it() menu completion,
+    it() menu completion in two flavours,
     it() variable, editing function and option name completion,
-    it() inline expansion of variables, history commands.  
+    it() inline expansion of variables and history commands.  
   )
   it() Globbing --- extremely powerful, including:
   itemize(
@@ -259,8 +257,9 @@ sect(What is it good at?)
   it() Adaptable messages for spelling, watch, time as well as prompt
      (including conditional expressions).
   it() Named directories.
-  it() Comprehensive integer arithmetic.
+  it() Comprehensive integer and floating point arithmetic.
   it() Manipulation of arrays (including reverse subscripting).
+  it() Associative arrays (key-to-value hashes)
   it() Spelling correction.
   )
 
@@ -271,7 +270,7 @@ sect(On what machines will it run?)
   mechanism.  This considerably increases flexibility over the old
   `buildzsh' mechanism.  Consequently, zsh should compile and run on
   any modern version of UNIX, and a great many not-so-modern versions
-  too.  The file Etc/MACHINES in the distribution has more details.
+  too.  The file MACHINES in the distribution has more details.
 
   There are also now separate ports for Windows and OS/2, see `Where
   do I get it' below.
@@ -284,7 +283,7 @@ sect(On what machines will it run?)
 
   To get it to work, retrieve the source distribution (see question
   link(1.6)(16)), un-gzip it, un-tar it and read the INSTALL file in the top
-  directory.  Also read the Etc/MACHINES file for up-to-date
+  directory.  Also read the MACHINES file for up-to-date
   information on compilation on certain architectures.
 
   mybf(Note for users of nawk) (The following information comes from Zoltan
@@ -295,14 +294,12 @@ sect(On what machines will it run?)
 
 sect(What's the latest version?)
 
-  Zsh 3.0.7 is the latest production version. The new major number 3.0
-  largely reflects the considerable internal changes in zsh to make it more
-  reliable, consistent and (where possible) compatible.  Those planning on
-  upgrading their zsh installation should take a look at the list of
-  incompatibilities at the end of link(5.1)(51).  This is longer than usual
-  due to enhanced sh, ksh and POSIX compatibility.
+  Zsh 4.2.4 is the latest production version.
+
+  There will not be any further 4.0 releases now that 4.2 has become
+  the stable version.
 
-  The beta version 3.1.6 is also available.  Development of zsh is usually
+  A beta of the next version is sometimes available.  Development of zsh is
   patch by patch, with each intermediate version publicly available.  Note
   that this `open' development system does mean bugs are sometimes
   introduced into the most recent archived version.  These are usually
@@ -316,7 +313,7 @@ sect(What's the latest version?)
   Changes of this kind are almost always forced by an awkward or
   unnecessary feature in the original design (as perceived by current
   users), or to enhance compatibility with other Bourne shell
-  derivatives, or (most recently) to provide POSIX compliancy.
+  derivatives, or (mostly in the 3.0 series) to provide POSIX compliancy.
 
 
 sect(Where do I get it?)
@@ -338,12 +335,12 @@ label(16)
 (http://www.zsh.org/pub/zsh/)
     mydit(Australia) url(ftp://ftp.ips.gov.au/mirror/zsh/)
 (ftp://ftp.ips.gov.au/mirror/zsh/)
-    mydit(Denmark)   url(ftp://sunsite.auc.dk/pub/unix/shells/zsh)
-(ftp://sunsite.auc.dk/pub/unix/shells/zsh)
+    mydit(Denmark)   url(ftp://sunsite.dk/pub/unix/shells/zsh)
+(ftp://sunsite.dk/pub/unix/shells/zsh)
     mydit(Finland)   url(ftp://ftp.funet.fi/pub/unix/shells/zsh/)
 (ftp://ftp.funet.fi/pub/unix/shells/zsh/)
-    mydit(France)    url(ftp://ftp.cenatls.cena.dgac.fr/pub/shells/zsh/)
-(ftp://ftp.cenatls.cena.dgac.fr/pub/shells/zsh/)
+    mydit(France)    url(ftp://ftp.cenatls.cena.dgac.fr/shells/zsh/)
+(ftp://ftp.cenatls.cena.dgac.fr/shells/zsh/)
     mydit(Germany)   url(ftp://ftp.fu-berlin.de/pub/unix/shells/zsh/)
 (ftp://ftp.fu-berlin.de/pub/unix/shells/zsh/)
     mydit()          url(ftp://ftp.uni-trier.de/pub/unix/shell/zsh/)
@@ -355,11 +352,11 @@ label(16)
     mydit()          url(ftp://ftp.kfki.hu/pub/packages/zsh/)
 (ftp://ftp.kfki.hu/pub/packages/zsh/)
     mydit(Israel)    \
-url(ftp://ftp.math.technion.ac.il/mirror/ftp.zsh.org/pub/zsh/)
-(ftp://ftp.math.technion.ac.il/mirror/ftp.zsh.org/pub/zsh/)
+url(ftp://ftp.math.technion.ac.il/pub/zsh/)
+(ftp://ftp.math.technion.ac.il/pub/zsh/)
     mydit()          \
-url(http://www.math.technion.ac.il/mirror/ftp.zsh.org/pub/zsh/)
-(http://www.math.technion.ac.il/mirror/ftp.zsh.org/pub/zsh/)
+url(http://www.math.technion.ac.il/pub/zsh/)
+(http://www.math.technion.ac.il/pub/zsh/)
     mydit(Italy)     url(ftp://ftp.unina.it/pub/Unix/pkgs/shell/zsh/)
 (ftp://ftp.unina.it/pub/Unix/pkgs/shell/zsh/)
     mydit(Japan)     url(ftp://ftp.nisiq.net/pub/shells/zsh/)
@@ -395,14 +392,20 @@ url(http://www.math.technion.ac.il/mirror/ftp.zsh.org/pub/zsh/)
 
   The Windows port mentioned above is maintained separately by email(Amol
   Deshpande <amold@microsoft.com>); please mail Amol directly about any
-  Windows-specific problems.  This is quite new, so don't expect it to
-  be perfect.  You can get it from:
+  Windows-specific problems.  This is based on 3.0.5, and probably will
+  not be developed further.  You can get it from:
 
   description(
     mydit()        url(ftp://ftp.blarg.net/users/amol/zsh)
 (ftp://ftp.blarg.net/users/amol/zsh)  
   )
 
+  There is no port of version 4 for Windows, but newer releases compile under
+  Cygwin, a freely available UNIX-style environment for the Win32 API.  You
+  can find information about this at 
+  url(http://sourceware.cygnus.com/cygwin)\
+(http://sourceware.cygnus.com/cygwin).
+
   Likewise the OS/2 port is available from email(TAMURA Kent
   <kent@tril.ibm.co.jp>) at
 
@@ -420,8 +423,8 @@ url(http://www.math.technion.ac.il/mirror/ftp.zsh.org/pub/zsh/)
   link(1.1)(11)) at:
 
   description(
-    mydit()        url(http://sunsite.auc.dk/zsh/Patches/)
-(http://sunsite.auc.dk/zsh/Patches/)
+    mydit()        url(http://sunsite.dk/zsh/Patches/)
+(http://sunsite.dk/zsh/Patches/)
   )
      
 sect(I don't have root access: how do I make zsh my login shell?)
@@ -522,31 +525,33 @@ label(21)
   myeit() also from 3.0, the command `emulate' is available: `emulate
      ksh' and `emulate sh' set various options as well as changing the
      effect of single-letter option flags as if the shell had been
-     invoked with the appropriate name.  Including the commands
+     invoked with the appropriate name.  Including the command
      `emulate sh; setopt localoptions' in a shell function will
-     turn on sh emulation for that function only.
+     turn on sh emulation for that function only.  In version 4 (and in
+     3.0.6 through 8), this can be abbreviated as `emulate -L sh'.
    )
 
-  The classic difference is word splitting, discussed in link(3.1)(31); this
-  catches out very many beginning zsh users.  As explained there, this
-  is actually a bug in every other shell.  The answer is to set
+  The classic difference is word splitting, discussed in question \
+link(3.1)(31);
+  this catches out very many beginning zsh users.  As explained there,
+  this is actually a bug in every other shell.  The answer is to set
   tt(SH_WORD_SPLIT) for backward compatibility.  The next most classic
-  difference is that unmatched glob patterns cause the command to
-  abort; set tt(NO_NOMATCH) for those.
+  difference is that unmatched glob patterns cause the command to abort;
+  set tt(NO_NOMATCH) for those.
 
   Here is a list of various options which will increase ksh
   compatibility, though maybe decrease zsh's abilities: see the manual
   entries for tt(GLOB_SUBST), tt(IGNORE_BRACES) (though brace expansion occurs
   in some versions of ksh), tt(KSH_ARRAYS), tt(KSH_GLOB), tt(KSH_OPTION_PRINT),
   tt(LOCAL_OPTIONS), tt(NO_BAD_PATTERN), tt(NO_BANG_HIST), tt(NO_EQUALS), \
-tt(NO_HUP,)
+tt(NO_HUP),
   tt(NO_NOMATCH), tt(NO_RCS), tt(NO_SHORT_LOOPS), tt(PROMPT_SUBST), \
 tt(RM_STAR_SILENT),
   tt(POSIX_BUILTINS), tt(SH_FILE_EXPANSION), tt(SH_GLOB), \
 tt(SH_OPTION_LETTERS),
   tt(SH_WORD_SPLIT) (see question link(3.1)(31)) and tt(SINGLE_LINE_ZLE).
   Note that you can also disable any built-in commands which get in
-  your way.  If invoked as `ksh', the shell will try and set suitable
+  your way.  If invoked as `ksh', the shell will try to set suitable
   options.
 
   Here are some differences from ksh which might prove significant for
@@ -565,7 +570,7 @@ tt(SH_OPTION_LETTERS),
         subscripts start at 1, not 0; tt(array[0]) refers to tt(array[1]);
         mytt($array) refers to the whole array, not tt($array[0]);
         braces are unnecessary: tt($a[1] == ${a[1]}), etc.
-        The tt(KSH_ARRAYS) option is now available.
+        Set the tt(KSH_ARRAYS) option for compatibility.
     it()  Coprocesses are established by mytt(coproc); mytt(|&) behaves like
         csh.  Handling of coprocess file descriptors is also different.
     it()  In mytt(cmd1 && cmd2 &), only mytt(cmd2) instead of the whole
@@ -585,8 +590,8 @@ PROMPT_SUBST).
         Equivalents:
   verb(
 ----------------------------------------------------------------------
-      ksh             zsh          Meaning
-      -----           -----        ---------
+      ksh              zsh         Meaning
+     ------           ------       ---------
      !(foo)            ^foo        Anything but foo.
                 or   foo1~foo2     Anything matching foo1 but foo2[1].
 @(foo1|foo2|...)  (foo1|foo2|...)  One of foo1 or foo2 or ...
@@ -639,6 +644,10 @@ link(2.3)(23).
     it()* Options are not local to functions (use LOCAL_OPTIONS; note this
         may always be unset locally to propagate options settings from a
         function to the calling level).
+    it()  Functions defined with `function funcname { body }' behave the
+        same way as those defined with `funcname () { body }'.  In ksh,
+        the former behave as if the body were read from a file with `.',
+        and only the latter behave as true functions.
   )
     it() Traps and signals:
   itemize(
@@ -656,7 +665,7 @@ link(2.3)(23).
     it()  The mytt(keyword) option does not exist and mytt(-k) is instead
         interactivecomments.  (mytt(keyword) will not be in the next ksh
         release either.)
-    it()  Management of histories in multiple shells is different:
+    it()* Management of histories in multiple shells is different:
         the history list is not saved and restored after each command.
         The option tt(SHARE_HISTORY) appeared in 3.1.6 and is set in ksh
         compatibility mode to remedy this.
@@ -835,13 +844,13 @@ sect(Similarities with tcsh)
 
   (The sections on csh apply too, of course.)  Certain features have
   been borrowed from tcsh, including tt($watch), tt(run-help), tt($savehist),
-  tt($histlit), periodic commands etc., extended prompts, tt(sched)
-  and tt(which) built-ins.  Programmable completion was inspired by,
-  but is entirely different to, tcsh's mytt(complete).  (There is a perl
-  script called tt(lete2ctl) in the Misc directory of the source
-  distribution to convert mytt(complete) to mytt(compctl) statements.)
-  This list is not definitive:  some features have gone in the other
-  direction. 
+  periodic commands etc., extended prompts, tt(sched) and tt(which) built-ins.
+  Programmable completion was inspired by, but is entirely different to,
+  tcsh's mytt(complete).  (There is a perl script called tt(lete2ctl) in the
+  Misc directory of the source distribution to convert mytt(complete) to \
+mytt(compctl)
+  statements.)  This list is not definitive: some features have gone in
+  the other direction.
 
   If you're missing the editor function tt(run-fg-editor), try something
   with mytt(bindkey -s) (which binds a string to a keystroke), e.g.
@@ -862,8 +871,8 @@ sect(Similarities with tcsh)
   verb(
     bindkey '\eq' push-input
   )
-  to save the entire buffer.  In recent versions of zsh 3.1, you have
-  the following more sophisticated option,
+  to save the entire buffer.  In version 4 and recent versions of zsh 3.1,
+  you have the following more sophisticated option,
   verb(
     run-fg-editor() {
       zle push-input
@@ -885,6 +894,20 @@ sect(Similarities with bash)
   (i.e. POSIX) for longer, and has so far avoided the more abstruse
   interactive features (programmable completion, etc.) that zsh has.
 
+  In recent years there has been a certain amount of crossover in the
+  extensions, however.  Zsh (as of 3.1.6) has bash's `tt(${var/old/new})'
+  feature for replacing the text tt(old) with the text tt(new) in the
+  parameter tt($var).  Note one difference here:  while both shells
+  implement the syntax `tt(${var/#old/new})' and `tt(${var/%old/new})' for
+  anchoring the match of tt(old) to the start or end of the parameter text,
+  respectively, in zsh you can't put the `tt(#)' or `tt(%)' inside a
+  parameter:  in other words `tt({var/$old/new})' where tt(old) begins with
+  a `tt(#)' treats that as an ordinary character in zsh, unlike bash.  To
+  do this sort of thing in zsh you can use (from 3.1.7) the new syntax
+  for anchors in any pattern, `tt((#s))' to match the start of a string,
+  and `tt((#e))' to match the end.  These require the option
+  tt(EXTENDED_GLOB) to be set.
+
 
 sect(Shouldn't zsh be more/less like ksh/(t)csh?)
 
@@ -913,6 +936,46 @@ sect(Shouldn't zsh be more/less like ksh/(t)csh?)
   help.
 
 
+sect(What is zsh's support for Unicode/UTF-8?)
+
+  `Unicode', or UCS for Universal Character Set, is the modern way
+  of specifying character sets.  It replaces a large number of ad hoc
+  ways of supporting character sets beyond ASCII.  `UTF-8' is an
+  encoding of Unicode that is particularly natural on Unix-like systems.
+
+  Q: Does zsh support UTF-8?
+
+  A: zsh's built-in printf command supports "\u" and "\U" escapes
+  to output arbitrary Unicode characters.  ZLE (the Zsh Line Editor) has
+  no concept of character encodings, and is confused by multi-octet
+  encodings.
+
+  Q: Why doesn't zsh have proper UTF-8 support?
+
+  A: The code has not been written yet.
+
+  Q: What makes UTF-8 support difficult to implement?
+
+  A: In order to handle arbitrary encodings the correct way, significant
+  and intrusive changes must be made to the shell.
+
+  Q: Why can't zsh just use readline?
+
+  A: ZLE is not encapsulated from the rest of the shell.  Isolating it
+  such that it could be replaced by readline would be a significant
+  effort.  Furthermore, using readline would effect a significant loss of
+  features.
+
+  Q: What changes are planned?
+
+  A: Introduction of Unicode support will be gradual, so if you are
+  interested in being involved you should join the zsh-workers mailing
+  list.  As a first step ZLE will be rewritten to use wide characters
+  internally.  Character based widgets can then operate on a single wide
+  character instead of a single byte, and the proper display width can be
+  calculated with wcswidth().
+
+
 chapter(How to get various things to work)
 
 sect(Why does mytt($var) where mytt(var="foo bar") not do what I expect?)
@@ -997,6 +1060,22 @@ label(31)
   or (entirely equivalent) when mytt(emulate ksh) or mytt(emulate sh) is in
   effect.
 
+  There is one other effect of word splitting which differs between ksh
+  and zsh.  In ksh, the builtin commands that declare parameters such
+  as tt(typeset) and tt(export) force word-splitting not to take place
+  after on an assignment argument:
+  verb(
+    typeset param=`echo foo bar`
+  )
+  in ksh will create a parameter with value mytt(foo bar), but in zsh will
+  create a parameter tt(param) with value tt(foo) and a parameter tt(bar)
+  whose value is empty.  Contrast this with a normal assignment (no
+  tt(typeset) or other command in front), which never causes a word split
+  unless you have tt(GLOB_ASSIGN) set.  From zsh version 4.0.2 the option
+  tt(KSH_TYPESET), set automatically in compatibility mode, fixes this
+  problem.  Note that in bash this behaviour occurs with all arguments that
+  look like assignments, whatever the command name; to get this behaviour
+  in zsh you have to set the option tt(MAGIC_EQUAL_SUBST).
 
 sect(In which startup file do I put...?)
 
@@ -1028,7 +1107,7 @@ sect(In which startup file do I put...?)
   you use the tt(-f) option) is tt(.zshenv), so this is a good place to \
   put
   things you want even if the shell is non-interactive: options for
-  changing the the syntax, like tt(EXTENDED_GLOB), any changes to set with
+  changing the syntax, like tt(EXTENDED_GLOB), any changes to set with
   mytt(limit), any more variables you want to make sure are set as for
   example tt($fpath) to find functions.  You almost certainly do not
   want tt(.zshenv) to produce any output.  Some people prefer not to
@@ -1117,7 +1196,10 @@ label(35)
   )
   (disable parity detection, don't strip high bit, use 8-bit characters).
   Make sure this comes myem(before) any bindkey entries in your .zshrc which
-  redefine keys normally defined in the emacs/vi keymap.
+  redefine keys normally defined in the emacs/vi keymap.  You may also
+  need to set the tt(eightBitOutput) resource in your tt(~/.Xdefaults)
+  file, although this is on by default and it's unlikely anybody will
+  have tinkered with it.
 
   You don't need the mytt(bindkey) to be able to define your own sequences
   with the meta key, though you still need the mytt(stty).
@@ -1179,7 +1261,9 @@ sect(Why do the cursor (arrow) keys not work?)
   )
   
   If you use vi mode, use mytt(vi-backward-char) and mytt(vi-forward-char)
-  where appropriate.
+  where appropriate.  As of version 4.0.1, zsh attempts to look up these
+  codes and to set the key bindings for you (both emacs and vi), but in
+  some circumstances this may not work.
 
   Note, however, that up to version 3.0 binding arbitrary multiple key
   sequences can cause problems, so check that this works with your set
@@ -1188,6 +1272,29 @@ sect(Why do the cursor (arrow) keys not work?)
   tt(B), tt(C) or tt(D), as well as the corresponding set beginning
   mytt(<ESC>[), so this may be redundant.
 
+  A particular problem which sometimes occurs is that there are two
+  different modes for arrow keys, normal mode and keypad mode, which
+  send different sequences.  Although this is largely a historical
+  artifact, it sometimes happens that your terminal can be switched from
+  one mode to the other, for example by a rogue programme that sends the
+  sequence to switch one way, but not the sequence to switch back.  Thus
+  you are stuck with the effects.  Luckily in this case the arrow key
+  sequences are likely to be standard, and you can simply bind both sets.
+  The following code does this.
+  verb(
+    bindkey '\e[A'  up-line-or-history
+    bindkey '\e[B'  down-line-or-history
+    bindkey '\e[C'  forward-char
+    bindkey '\e[D'  backward-char
+    bindkey '\eOA'  up-line-or-history
+    bindkey '\eOB'  down-line-or-history
+    bindkey '\eOC'  forward-char
+    bindkey '\eOD'  backward-char
+  )
+  For most even vaguely VT100-compatible terminals, the above eight
+  instructions are a fairly safe bet for your tt(.zshrc).  Of course
+  you can substitute variant functions for the second argument here too.
+
 
 sect(Why does my terminal act funny in some way?)
 
@@ -1227,10 +1334,9 @@ sect(Why does my terminal act funny in some way?)
     ttyctl -u
     STTY='lnext "^-"' commandname
   )
-  (in this example), or just export STTY for all commands to see.  Note
-  that zsh doesn't reset the terminal completely afterwards: just the
-  modes it uses itself and a number of special processing characters
-  (see the tt(stty(1)) manual page).
+  (in this example).  Note that zsh doesn't reset the terminal completely
+  afterwards: just the modes it uses itself and a number of special
+  processing characters (see the tt(stty(1)) manual page).
 
 
 sect(Why does zsh not work in an Emacs shell mode any more?)
@@ -1258,7 +1364,7 @@ sect(Why does zsh not work in an Emacs shell mode any more?)
   into a file ~/bin/eshell, then mytt(chmod +x ~/bin/eshell), and
   tell emacs to use that as the shell by adding
   verb(
-    (setenv "ESHELL" "~/bin/eshell")
+    (setenv "ESHELL" (expand-file-name "~/bin/eshell"))
   )
   to ~/.emacs.
 
@@ -1346,7 +1452,11 @@ sect(How does base arithmetic work?)
   )
   which requests base 10 for output.  You can change the output base of an
   existing variable in this fashion.  Using the mytt($(( ... ))) method will
-  always display in decimal.
+  always display in decimal, except that in 3.1.9 there is a new feature
+  for selecting a base for displaying here:
+  verb(
+    print $(( [#16] 255 ))
+  )
 
 
 sect(How do I get a newline in my prompt?)
@@ -1362,8 +1472,8 @@ label(313)
   mytt(unsetopt cshjunkiequotes) and mytt(setopt cshjunkiequotes), or put it
   in your tt(.zshrc) before the option is set.
 
-  In all recent versions of zsh, there is a form of quoting which will
-  interpret print sequences like `tt(\n)' but otherwise acts like single
+  In recent versions of zsh (not 3.0), there is a form of quoting which
+  interprets print sequences like `tt(\n)' but otherwise acts like single
   quotes: surround the string with tt($'...').  Hence:
   verb(
     PROMPT=$'Hi Joe,\nwhat now?%# '
@@ -1371,6 +1481,7 @@ label(313)
   is a neat way of doing what you want.  Note that it is the quotes, not
   the prompt expansion, which turns the `tt(\n)' into a newline.
 
+
 sect(Why does mytt(bindkey ^a command-name) or mytt(stty intr ^-) do something funny?)
 
   You probably have the extendedglob option set in which case tt(^) and tt(#)
@@ -1529,8 +1640,8 @@ sect(How do I get a variable's value to be evaluated as another variable?)
   Ignore the mytt((e)) for now.  The mytt(:+) means: if the variable
   tt($E) is set, substitute the following, i.e. mytt(\$$E).  This is
   expanded to mytt($EDITOR) by the normal rules.  Finally, the mytt((e)) \
-  means:
-  evaluate the expression you just made.  This gives mytt(emacs).
+  means
+  `evaluate the expression you just made'.  This gives mytt(emacs).
 
   For a standard shell way of doing this, you are stuck with mytt(eval):
   verb(
@@ -1538,7 +1649,7 @@ sect(How do I get a variable's value to be evaluated as another variable?)
   )
   produces the same result.
 
-  Versions 3.1.6 of allows you to do this directly with a new flag;
+  Versions since 3.1.6 allow you to do this directly with a new flag;
   mytt(${(P)E}).
 
   As a slight aside, sometimes people note that the syntax mytt(${${E}})
@@ -1601,6 +1712,68 @@ sect(What's wrong with cut and paste on my xterm?)
      fixes referred to above in order to be reliable).
   )
 
+sect(How do I get coloured prompts on my colour xterm?)
+
+  (Or `color xterm', if you're reading this in black and white.)  You need
+  to find the sequences which generate the various colours from the manual
+  for your terminal emulator; these are ANSI standard on those I know about
+  which support colour.  With a recent (post 3.1.6) distribution of zsh,
+  there is a theme system to handle this for you; even if you don't see that,
+  the installed function `mytt(colors)' (meaning `colours', if you're not
+  reading this in black and white) gives the escape sequences.  You will end
+  up with code looking like this (borrowed from Oliver Kiddle):
+  verb(
+    PS1=$'%{\e[1;31m%}<the rest of your prompt here>%{\e[0m%}'
+  )
+  The mytt($') form of quoting turns the `mytt(\e)' into a real escape
+  character; this only works from about version 3.1.4, so if you're using
+  3.0.x, you need to do something like
+  verb(
+    PS1="$(print '%{\e[1;31m%}<the rest goes here>%{\e[0m%}')"
+  )
+  The `mytt(%{...%})' is used in prompts for strings which will
+  not appear as characters, so that the prompt code doesn't miscalculate the
+  length of the prompt which would have a bad effect on editing.  The
+  resulting `mytt(<ESC>[1;31m)' makes the prompt red, and the
+  `mytt(<ESC>[0m)' puts printing back to normal so that the rest of the line
+  is unchanged.
+
+sect(Why is my output duplicated with `tt(foo 2>&1 >foo.out | bar)'?)
+
+  This is a slightly unexpected effect of the option tt(MULTIOS), which is
+  set by default.  Let's look more closely:
+  verb(
+    foo 2>&1 >foo.out | bar
+  )
+  What you're probably expecting is that the command mytt(foo) sends its
+  standard output to the pipe and so to the input of the command mytt(bar),
+  while it sends its standard error to the file mytt(foo.out).  What you
+  actually see is that the output is going both to the pipe and into the
+  file.  To be more explicit, here's the same example with real commands:
+  verb(
+    % { print output; print error >&2 } 2>&1 >foo.out | sed 's/error/erratic'
+    erratic
+    output
+    % cat foo.out
+    output
+  )
+  and you can see `tt(output)' appears twice.
+
+  It becomes clearer what's going on if we write:
+  verb(
+    % print output >foo1.out >foo2.out
+    % cat foo1.out
+    output
+    % cat foo2.out
+    output
+  )
+  You might recognise this as a standard feature of zsh, called `tt(multios)'
+  and controlled by the option of the same name, whereby output is copied
+  to both files when the redirector appears twice.  What's going on in the
+  first example is exactly the same, however the second redirector is
+  disguised as a pipe.  So if you want to turn this effect off, you need
+  to unset the option mytt(MULTIOS).
+
 
 chapter(The mysteries of completion)
 
@@ -1620,6 +1793,7 @@ you need to do, in principal, is to arrange for this to be loaded.  Putting
 the system is installed properly.  The rest of this section talks about the
 old completion system.
 
+
 sect(What is completion?)
 
   `Completion' is where you hit a particular command key (TAB is the
@@ -1914,7 +2088,9 @@ sect(And if programmable completion isn't good enough?)
   completions via the mytt(reply) array, and this becomes the set of
   possible completions.  The best way to understand this is to look at
   mytt(multicomp) and other functions supplied with the zsh
-  distribution.
+  distribution.  Almost certainly, however, you are better off using
+  the new completion system for anything complicated.  No further
+  upgrades are planned for the old system.
 
 
 chapter(The future of zsh)
@@ -1932,9 +2108,10 @@ this applies
   with more detail.
 
   itemize(
+  it() Parameter expansions using the tt(${param+word}) and tt(${param-word})
+    forms may fail to behave in Bourne-shell-compatible fashion when the
+    tt(SH_WORD_SPLIT) option is set and the word contains spaces.
   it() mytt(time) is ignored with builtins and can't be used with mytt({...}).
-  it() When showing completion lists with exactly 80 columns, some
-       terminals print an extra newline which messes up zsh's logic.  
   it() mytt(set -x) (mytt(setopt xtrace)) still has a few glitches; these
      are mostly fixed in 3.1.6.
   it() Zsh's notion of the current line number (via tt($LINENO)) is
@@ -1951,15 +2128,18 @@ this applies
   verb(
       [[ fofo = (fo#)# ]]
   )
-     were not correctly handled, and there were problems with
-     complicated exclusions using mytt(^) or mytt(~).  These
-     are fixed in version 3.1.3.
+     were once not correctly handled, and there were problems with
+     complicated exclusions using mytt(^) or mytt(~).  These are fixed
+     since version 3.1.3.
   )
+  it() Handling of the mytt(:q) and mytt(:x) with parameter subsitutions is
+    erratic: neither work in any 3.0 release, and tt(:x) doesn't work in
+    any release so far.
 
   Note that a few recent changes introduce incompatibilities (these
   are not bugs):
 
-  Changes after zsh 3.0 (3.1.x is still currently in beta):
+  Changes after zsh 3.0:
   itemize(
   it() The options tt(ALWAYS_LAST_PROMPT) (return to the line you were
      editing after displaying completion lists) and tt(LIST_AMBIGUOUS)
@@ -2054,7 +2234,7 @@ label(52)
   The shell is being maintained by various (entirely self-appointed)
   subscribers to the mailing list,
   verb(
-    zsh-workers@sunsite.auc.dk
+    zsh-workers@sunsite.dk
   )
   so mail on any issues (bug reports, suggestions, complaints...)
   related to the development of the shell should be sent there.  If
@@ -2074,12 +2254,12 @@ label(52)
   Two progressively lower volume lists exist, one with messages
   concerning the use of zsh,
   verb(
-    zsh-users@sunsite.auc.dk
+    zsh-users@sunsite.dk
   )
   and one just containing announcements:  about releases, about major
   changes in the shell, or this FAQ, for example,
   verb(
-    zsh-announce@sunsite.auc.dk
+    zsh-announce@sunsite.dk
   )
   (posting to the last one is currently restricted).
 
@@ -2093,14 +2273,14 @@ label(52)
 
   To join zsh-workers, send email to
   verb(
-    zsh-workers-subscribe@sunsite.auc.dk
+    zsh-workers-subscribe@sunsite.dk
   )
   (the actual content is unimportant).  Replace tt(subscribe) with
   tt(unsubscribe) to unsubscribe.  The mailing software (tt(ezlm)) has
   various bells and whistles: you can retrieve archived messages.
-  Mail email(zsh-workers-help@sunsite.auc.dk) for detailed information.
+  Mail email(zsh-workers-help@sunsite.dk) for detailed information.
   Adminstrative matters are best sent to
-  email(zsh-workers-owner@sunsite.auc.dk).  The list maintainer's
+  email(zsh-workers-owner@sunsite.dk).  The list maintainer's
   real name is email(Karsten Thygesen <karthy@kom.auc.dk>).
   
   An archive of mailings for the last few years can be found at
@@ -2156,6 +2336,10 @@ sect(What's on the wish-list?)
 
   Other future possibilities which have been suggested:
   itemize(
+  it() The parameter code could do with tidying up, maybe with more of the
+     features made available in ksh93.
+  it() Configuration files to enable zsh startup files to be created
+     with the Dotfile Generator.
   it() Further improvements in integrating the line editor with shell
      functions.
   it() Ksh compatibility could be improved.
@@ -2163,33 +2347,12 @@ sect(What's on the wish-list?)
   )
 
 
-sect(Will zsh have problems in the year 2000?)
-
-  (This information was written by Bart Schaefer.  Note it is a
-  description of the state of affairs as seen by the developers, it is
-  not a guarantee!)
-
-  You can confirm the following by looking at the source code yourself
-  if necessary; there's no other definitive reference:
-
-  Zsh uses UNIX/POSIX time_t, timeval, and tm data types for internal
-  date manipulations.  These types either do not store year values at
-  all (for example, time_t is measured in seconds since midnight, Jan
-  1, 1970) or store them as integer types and NOT as pairs of digits.
-  Thus there can be no overflows at year 2000.  On some unix systems,
-  time_t is a 32-bit value and will overflow during the year 2038, but
-  more modern systems use a 64-bit time_t.
-
-  The only input and output of dates that zsh performs for its own use
-  is optional history time-stamping.  This is performed using time_t
-  values converted to long integers, which are either 32 or 64 bits,
-  see above.
+sect(Did zsh have problems in the year 2000?)
 
-  Note, however, that zsh does provide facilities for formatted date
-  output, in particular in prompt escapes such as mytt(%W) and
-  mytt(%D) using mytt(print -P), so it's possible that scripts written
-  for zsh might employ 2-digit years.  Shell scripts should always be
-  considered separate programs and therefore evaluated individually.
+  Not that I heard of; it's up to you to be careful with two-digit dates,
+  though, which are produced by the prompt escapes mytt(%W) and mytt(%D),
+  and also by the command `tt(print -P)'.  Earlier versions of zsh may
+  show problems here.
 
 
 nsect(Acknowledgments:)
@@ -2217,4 +2380,4 @@ notice appears in all copies of this documentation.  Remember,
 however, that this document changes monthly and it may be more useful
 to provide a pointer to it rather than the entire text.  A suitable
 pointer is "information on the Z-shell can be obtained on the World
-Wide Web at URL http://sunsite.auc.dk/zsh/".
+Wide Web at URL http://sunsite.dk/zsh/".
diff --git a/README b/README
index 6b47a99ce..62445aade 100644
--- a/README
+++ b/README
@@ -5,49 +5,97 @@ THE Z SHELL (ZSH)
 Version
 -------
 
-This is zsh version 3.1 (beta)
-
-Note that this is a beta version.  The latest stable version is zsh-3.0.6.
+This is zsh version 4.2.4.  This is a stable version.
 
 Installing Zsh
 --------------
 
 The instructions for compiling zsh are in the file INSTALL.  You should
-also check the file MACHINES in the subdirectory Etc to see if there
+also check the file MACHINES in the top directory to see if there
 are any special instructions for your particular architecture.
 
 Features
 --------
 
-Zsh is a shell with lots of features.  For a list of these, see the
-file Etc/FEATURES, and for the latest changes see Etc/NEWS.  For more
+Zsh is a shell with lots of features.  For a list of some of these, see the
+file FEATURES, and for the latest changes see NEWS.  For more
 details, see the documentation.
 
-Possibile incompatibilities
+Possible incompatibilities
 ---------------------------
 
-If you have been using recent versions of zsh 3.1, the following changes in
-the shell may affect you:
-- The traditional bindings of \M-n (history-search-backward) and
-  \M-p (history-search-forward) in older versions of zsh have returned,
-  as has the traditional behaviour of those functions and the functions
-  up-line-or-search and down-line-or-search.  In 3.1.5, the functions
-  behaved differently and \M-n and \M-p were bound by default to
-  history-beginning-search-backward and history-beginning-search-forward.
-- Prompt truncation behaviour via %<...< and %>...> (or %[<...] etc.) has
-  changed slightly:  the string to be truncated runs to the end of the
-  prompt or to the next truncation sequence; %<< will turn off truncation.
-  Previously it only covered individual prompt escapes.  So for example the
-  prompt `%10<...<%~%% ' will now include the `%% ' in the string to be
-  truncated, and you should change the prompt to `%10<...<%~%<<%% ' to turn
-  off truncation immediately after the `%~'.
-- If for some reason you have `setopt norcs' or `unsetopt rcs' anywhere in
-  your startup files (e.g. to stop .zlogout being run), this will now
-  take effect immediately, preventing later startup files from being
-  run.  It is safe to put `setopt norcs' in .zlogin as this is always
-  the last run.
-
-See the FAQ for a discussion of changes over the longer term.
+Currently the only known incompatibilities between 4.2.0 and later
+versions are minor:
+
+
+Since 4.2.1:
+
+The "test" and "[" builtins now behave more like relevant Unix standards
+suggest they should.  Previously they were a simple front-end to the same
+tests used by zsh's "[[" syntax.  (The documentation was previously cagey
+about what "test" and "[" actually did.)  "[[" has always been the
+recommended way of implementing tests within zsh.
+
+In recent versions of zsh, typing the end-of-file (EOF) character
+(typically ^D, although this can be altered with the "stty" command)
+repeatedly in the line editor printed a warning message, but never exited the
+shell.  This was a departure from the traditional behaviour of zsh and
+other shells where the shell would exit after 10 EOFs.  The traditional
+behaviour has been restored.  Also, binding a user-defined editor command
+to the EOF character now suppresses the EOF behaviour inside the line
+editor; it is possible to emulate it if desired.
+
+
+From 4.2.0 to 4.2.1:
+
+IPv6 addresses must be specified in square brackets in the zftp module and
+the function system built on top of the zftp module.
+
+Special traps for pseudosignals ZERR, DEBUG and EXIT are no longer executed
+inside other traps.  Users may well have assumed this was the case anyway
+since the behaviour was not explicity documented.  See the NEWS file for
+more detail.
+
+By default, a maximum function depth of 4096 is now compiled into the
+shell.  This may be altered during configuration; see `Function depth' in
+INSTALL.
+
+
+Some particular differences you may notice between the 4.0 and 4.2 series
+of releases:
+
+The bash-compatibility zle functions described in the zshcontrib manual
+page have been removed as a more configurable set of editing widgets for
+dealing with words have been added.  The following code in .zshrc will set
+up for bash-style word handling:
+  autoload -U select-word-style
+  select-word-style bash
+
+The `=prog' facility for expanding command paths (provided the EQUALS
+option is enabled, as it is by default) no longer expands aliases.  It was
+felt this feature was underused and confusing.
+
+In 4.0, a literal `/' was quoted in the `src' text of a substitution of the
+form `${foo/src/rep}' or ${foo//src/rep} with two backslashes.  This was
+documented, but inconsistent with normal quoting conventions and poorly
+implemented.  The `/' now requires only one backslash to quote it whether
+or not the expression occurs in double quotes.  For example:
+  % foo=word/bird
+  % print ${foo/\//-} "${foo/\//+}"
+  word-bird word+bird
+Note also the following workaround which is valid in all versions of the
+shell that support this syntax:
+  % slash=/
+  % foo=word/bird
+  % print ${foo/$slash/-} "${foo/$slash/+}"
+
+In 4.0, the -M option to bindkey used the first non-option argument to
+specify the keymap, whereas it now uses an argument to the option.  Hence:
+  bindkey -M -R keymap a-z self-insert
+needs to be rewritten as
+  bindkey -M keymap -R a-z self-insert
+The following form works in both versions:
+  bindkey -R -M keymap a-z self-insert
 
 Documentation
 -------------
@@ -59,7 +107,7 @@ Doc/Zsh/*.yo	The master source for the zsh documentation is written in
 		It is not required by zsh but but it is a nice program so
 		you might want to get it anyway, especially if you are a
 		zsh developer.  It can be downloaded from
-		ftp://ftp.icce.rug.nl/pub/unix/yodl*
+		ftp://ftp.lilypond.org/pub/yodl/
 
 Doc/zsh*.1	Man pages in nroff format.  These will be installed
 		by "make install.man" or "make install".  By default,
@@ -73,7 +121,8 @@ Doc/zsh.texi	Everything the man pages have, but in texinfo format.  These
 		By default, these will be installed in /usr/local/info,
 		although you can change this with the --infodir option to
 		configure or editing the user configuration section of the
-		top level Makefile.
+		top level Makefile.  Version 4.0 or above of the
+		Texinfo tools are recommended for processing this file.
 
 Also include in the distribution are:
 
@@ -84,9 +133,11 @@ Doc/intro.ms	An introduction to zsh in troff format using the ms
 		may not work without changes but it is still a good
 		introduction.
 
+For more information, see the website, as described in the META-FAQ.
+
 If you do not have the necessary tools to process these documents,
 PostScript, ASCII, Info and DVI versions are available in the separate
-file zsh-beta-doc.tar.gz at the archive sites listed in the META-FAQ.
+file zsh-doc.tar.gz at the archive sites listed in the META-FAQ.
 
 The distribution also contains a Perl script in Utils/helpfiles which
 can be used to extract the descriptions of builtin commands from the
@@ -95,7 +146,7 @@ script about its usage.  The files created by this script can be used
 by example function run-help located in the subdirectory Functions/Misc to
 show information about zsh builtins and run `man' on external commands.
 For this the shell variable HELPDIR should point to a directory containing
-the fileles generated by the helpfiles script.  run-help should be
+the files generated by the helpfiles script.  run-help should be
 unaliased before loading the run-help function.  After that this function
 will be executed by the run-help ZLE function which is by default bound
 to ESC-h in emacs mode.
@@ -128,19 +179,19 @@ Zsh Maintenance and Bug Reports
 -------------------------------
 
 Zsh is currently maintained by the members of the zsh-workers mailing list
-and coordinated by Peter Stephenson <pws@zsh.org>.  Please send
-any feedback and bugs reports to <zsh-workers@sunsite.auc.dk>.
+and coordinated by Peter Stephenson <coordinator@zsh.org>.  Please send
+any feedback and bugs reports to <zsh-workers@sunsite.dk>.
 
-There is a script "reporter" in the subdirectory Util which will print
-out your current shell environment/setup.  If you report a bug, please
-use this script and include the output from sourcing this file.  This way,
-the problem you are reporting can be recreated.
-
-You can help even more if you can reproduce the bug starting zsh with
+Reports are most helpful if you can reproduce the bug starting zsh with
 the -f option.  This skips the execution of local startup files except
 /etc/zshenv.  If a bug occurs only when some options set try to locate
 the option which triggers the bug.
 
+There is a script "reporter" in the subdirectory Util which will print out
+your current shell environment/setup.  If you cannot reproduce the bug
+with "zsh -f", use this script and include the output from sourcing this
+file.  This way, the problem you are reporting can be recreated.
+
 The known bugs in zsh are listed in the file Etc/BUGS.  Check this as
 well as the Frequently Asked Questions (FAQ) list before sending a bug
 report.  Note that zsh has some features which are not compatible with