Updated FAQ.yo from latest posting.

1 files changed, 260 insertions, 121 deletions

diff --git a/Etc/FAQ.yo b/Etc/FAQ.yo
index 0e1274300..019c8aa11 100644
--- a/Etc/FAQ.yo
+++ b/Etc/FAQ.yo
@@ -43,20 +43,20 @@ 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)(2001/06/25)
 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:) 2001/06/25
+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)
+mydit(Copyright:) (C) P.W. Stephenson, 1995--2001 (see end of document)
 )
 
-bf(Changes since issue posted December 1999:)
+bf(Changes since last issue posted:)
 description(
-mydit(   )  None.  Suggestions on a postcard.
+  mydit(1.6)  4.0.2 nearly released.
+  mydit(3.1)  typeset splitting incompatibility and tt(KSH_TYPESET) option
 )
 
 This document contains a list of frequently-asked (or otherwise
@@ -120,6 +120,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 +135,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 +149,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 +189,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 +239,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 +262,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.
   )
 
@@ -295,14 +299,23 @@ 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
+  Zsh 4.0.2 is the latest production version.
+
+  Zsh 3.0.8 was the previous production version.  The major number 3.0
+  largely reflected 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.
 
-  The beta version 3.1.6 is also available.  Development of zsh is usually
+  There will not be any further 3.0 releases now that 4.0 has become
+  the stable version.  However, a few patches to 3.0.8 are available from
+  the patch manager at Sourceforge, \
+url(http://sourceforge.net/patch/?group_id=4068)\
+(http://www.sourceforge.net/patch/?group_id=4068)
+  Official patches are posted by Bart Schaefer (user name tt(barts)).
+
+  A beta of the next version is often 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 +329,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 +351,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 +368,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 +408,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 4.0 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 +439,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 +541,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 4.0 (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 +586,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 +606,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 +660,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 +681,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 +860,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 +887,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 4.0 and recent versions of zsh 3.1, you
+  have the following more sophisticated option,
   verb(
     run-fg-editor() {
       zle push-input
@@ -885,6 +910,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?)
 
@@ -997,6 +1036,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 +1083,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 +1172,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 +1237,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 +1248,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 +1310,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 +1340,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 +1428,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 +1448,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 +1457,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 +1616,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 +1625,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 +1688,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 +1769,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 +2064,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 +2084,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 +2104,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 +2210,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 +2230,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 +2249,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 +2312,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 +2323,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 +2356,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/".