--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/Zsh/modlist.yo
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/Zsh/modlist.yo
@@ -0,0 +1,173 @@
+startitem()
+item(tt(zsh/cap))(
+Builtins for manipulating POSIX.1e (POSIX.6) capability (privilege) sets.
+)
+item(tt(zsh/clone))(
+A builtin that can clone a running shell onto another terminal.
+)
+item(tt(zsh/compctl))(
+The tt(compctl) builtin for controlling completion.
+)
+item(tt(zsh/complete))(
+The basic completion code.
+)
+item(tt(zsh/complist))(
+Completion listing extensions.
+)
+item(tt(zsh/computil))(
+A module with utility builtins needed for the shell function based
+completion system.
+)
+item(tt(zsh/datetime))(
+Some date/time commands and parameters.
+)
+item(tt(zsh/deltochar))(
+A ZLE function duplicating EMACS' tt(zap-to-char).
+)
+item(tt(zsh/example))(
+An example of how to write a module.
+)
+item(tt(zsh/files))(
+Some basic file manipulation commands as builtins.
+)
+item(tt(zsh/mapfile))(
+Access to external files via a special associative array.
+)
+item(tt(zsh/mathfunc))(
+Standard scientific functions for use in mathematical evaluations.
+)
+item(tt(zsh/parameter))(
+Access to internal hash tables via special associative arrays.
+)
+item(tt(zsh/pcre))(
+Interface to the PCRE library.
+)
+item(tt(zsh/sched))(
+A builtin that provides a timed execution facility within the shell.
+)
+item(tt(zsh/net/socket))(
+Manipulation of Unix domain sockets
+)
+item(tt(zsh/stat))(
+A builtin command interface to the tt(stat) system call.
+)
+item(tt(zsh/system))(
+A builtin interface to various low-level system features.
+)
+item(tt(zsh/net/tcp))(
+Manipulation of TCP sockets
+)
+item(tt(zsh/termcap))(
+Interface to the termcap database.
+)
+item(tt(zsh/terminfo))(
+Interface to the terminfo database.
+)
+item(tt(zsh/zftp))(
+A builtin FTP client.
+)
+item(tt(zsh/zle))(
+The Zsh Line Editor, including the tt(bindkey) and tt(vared) builtins.
+)
+item(tt(zsh/zleparameter))(
+Access to internals of the Zsh Line Editor via parameters.
+)
+item(tt(zsh/zprof))(
+A module allowing profiling for shell functions.
+)
+item(tt(zsh/zpty))(
+A builtin for starting a command in a pseudo-terminal.
+)
+item(tt(zsh/zselect))(
+Block and return when file descriptors are ready.
+)
+item(tt(zsh/zutil))(
+Some utility builtins, e.g. the one for supporting configuration via 
+styles.
+)
+enditem()
+includefile(Zsh/modmenu.yo)
+texinode(The zsh/cap Module)(The zsh/clone Module)()(Zsh Modules)
+sect(The zsh/cap Module)
+includefile(Zsh/mod_cap.yo)
+texinode(The zsh/clone Module)(The zsh/compctl Module)(The zsh/cap Module)(Zsh Modules)
+sect(The zsh/clone Module)
+includefile(Zsh/mod_clone.yo)
+texinode(The zsh/compctl Module)(The zsh/complete Module)(The zsh/clone Module)(Zsh Modules)
+sect(The zsh/compctl Module)
+includefile(Zsh/mod_compctl.yo)
+texinode(The zsh/complete Module)(The zsh/complist Module)(The zsh/compctl Module)(Zsh Modules)
+sect(The zsh/complete Module)
+includefile(Zsh/mod_complete.yo)
+texinode(The zsh/complist Module)(The zsh/computil Module)(The zsh/complete Module)(Zsh Modules)
+sect(The zsh/complist Module)
+includefile(Zsh/mod_complist.yo)
+texinode(The zsh/computil Module)(The zsh/datetime Module)(The zsh/complist Module)(Zsh Modules)
+sect(The zsh/computil Module)
+includefile(Zsh/mod_computil.yo)
+texinode(The zsh/datetime Module)(The zsh/deltochar Module)(The zsh/computil Module)(Zsh Modules)
+sect(The zsh/datetime Module)
+includefile(Zsh/mod_datetime.yo)
+texinode(The zsh/deltochar Module)(The zsh/example Module)(The zsh/datetime Module)(Zsh Modules)
+sect(The zsh/deltochar Module)
+includefile(Zsh/mod_deltochar.yo)
+texinode(The zsh/example Module)(The zsh/files Module)(The zsh/deltochar Module)(Zsh Modules)
+sect(The zsh/example Module)
+includefile(Zsh/mod_example.yo)
+texinode(The zsh/files Module)(The zsh/mapfile Module)(The zsh/example Module)(Zsh Modules)
+sect(The zsh/files Module)
+includefile(Zsh/mod_files.yo)
+texinode(The zsh/mapfile Module)(The zsh/mathfunc Module)(The zsh/files Module)(Zsh Modules)
+sect(The zsh/mapfile Module)
+includefile(Zsh/mod_mapfile.yo)
+texinode(The zsh/mathfunc Module)(The zsh/parameter Module)(The zsh/mapfile Module)(Zsh Modules)
+sect(The zsh/mathfunc Module)
+includefile(Zsh/mod_mathfunc.yo)
+texinode(The zsh/parameter Module)(The zsh/pcre Module)(The zsh/mathfunc Module)(Zsh Modules)
+sect(The zsh/parameter Module)
+includefile(Zsh/mod_parameter.yo)
+texinode(The zsh/pcre Module)(The zsh/sched Module)(The zsh/parameter Module)(Zsh Modules)
+sect(The zsh/pcre Module)
+includefile(Zsh/mod_pcre.yo)
+texinode(The zsh/sched Module)(The zsh/net/socket Module)(The zsh/pcre Module)(Zsh Modules)
+sect(The zsh/sched Module)
+includefile(Zsh/mod_sched.yo)
+texinode(The zsh/net/socket Module)(The zsh/stat Module)(The zsh/sched Module)(Zsh Modules)
+sect(The zsh/net/socket Module)
+includefile(Zsh/mod_socket.yo)
+texinode(The zsh/stat Module)(The zsh/system Module)(The zsh/net/socket Module)(Zsh Modules)
+sect(The zsh/stat Module)
+includefile(Zsh/mod_stat.yo)
+texinode(The zsh/system Module)(The zsh/net/tcp Module)(The zsh/stat Module)(Zsh Modules)
+sect(The zsh/system Module)
+includefile(Zsh/mod_system.yo)
+texinode(The zsh/net/tcp Module)(The zsh/termcap Module)(The zsh/system Module)(Zsh Modules)
+sect(The zsh/net/tcp Module)
+includefile(Zsh/mod_tcp.yo)
+texinode(The zsh/termcap Module)(The zsh/terminfo Module)(The zsh/net/tcp Module)(Zsh Modules)
+sect(The zsh/termcap Module)
+includefile(Zsh/mod_termcap.yo)
+texinode(The zsh/terminfo Module)(The zsh/zftp Module)(The zsh/termcap Module)(Zsh Modules)
+sect(The zsh/terminfo Module)
+includefile(Zsh/mod_terminfo.yo)
+texinode(The zsh/zftp Module)(The zsh/zle Module)(The zsh/terminfo Module)(Zsh Modules)
+sect(The zsh/zftp Module)
+includefile(Zsh/mod_zftp.yo)
+texinode(The zsh/zle Module)(The zsh/zleparameter Module)(The zsh/zftp Module)(Zsh Modules)
+sect(The zsh/zle Module)
+includefile(Zsh/mod_zle.yo)
+texinode(The zsh/zleparameter Module)(The zsh/zprof Module)(The zsh/zle Module)(Zsh Modules)
+sect(The zsh/zleparameter Module)
+includefile(Zsh/mod_zleparameter.yo)
+texinode(The zsh/zprof Module)(The zsh/zpty Module)(The zsh/zleparameter Module)(Zsh Modules)
+sect(The zsh/zprof Module)
+includefile(Zsh/mod_zprof.yo)
+texinode(The zsh/zpty Module)(The zsh/zselect Module)(The zsh/zprof Module)(Zsh Modules)
+sect(The zsh/zpty Module)
+includefile(Zsh/mod_zpty.yo)
+texinode(The zsh/zselect Module)(The zsh/zutil Module)(The zsh/zpty Module)(Zsh Modules)
+sect(The zsh/zselect Module)
+includefile(Zsh/mod_zselect.yo)
+texinode(The zsh/zutil Module)()(The zsh/zselect Module)(Zsh Modules)
+sect(The zsh/zutil Module)
+includefile(Zsh/mod_zutil.yo)
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/Zsh/modmenu.yo
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/Zsh/modmenu.yo
@@ -0,0 +1,30 @@
+startmenu()
+menu(The zsh/cap Module)
+menu(The zsh/clone Module)
+menu(The zsh/compctl Module)
+menu(The zsh/complete Module)
+menu(The zsh/complist Module)
+menu(The zsh/computil Module)
+menu(The zsh/datetime Module)
+menu(The zsh/deltochar Module)
+menu(The zsh/example Module)
+menu(The zsh/files Module)
+menu(The zsh/mapfile Module)
+menu(The zsh/mathfunc Module)
+menu(The zsh/parameter Module)
+menu(The zsh/pcre Module)
+menu(The zsh/sched Module)
+menu(The zsh/net/socket Module)
+menu(The zsh/stat Module)
+menu(The zsh/system Module)
+menu(The zsh/net/tcp Module)
+menu(The zsh/termcap Module)
+menu(The zsh/terminfo Module)
+menu(The zsh/zftp Module)
+menu(The zsh/zle Module)
+menu(The zsh/zleparameter Module)
+menu(The zsh/zprof Module)
+menu(The zsh/zpty Module)
+menu(The zsh/zselect Module)
+menu(The zsh/zutil Module)
+endmenu()
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/Zsh/manmodmenu.yo
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/Zsh/manmodmenu.yo
@@ -0,0 +1,28 @@
+menu(The zsh/cap Module)
+menu(The zsh/clone Module)
+menu(The zsh/compctl Module)
+menu(The zsh/complete Module)
+menu(The zsh/complist Module)
+menu(The zsh/computil Module)
+menu(The zsh/datetime Module)
+menu(The zsh/deltochar Module)
+menu(The zsh/example Module)
+menu(The zsh/files Module)
+menu(The zsh/mapfile Module)
+menu(The zsh/mathfunc Module)
+menu(The zsh/parameter Module)
+menu(The zsh/pcre Module)
+menu(The zsh/sched Module)
+menu(The zsh/net/socket Module)
+menu(The zsh/stat Module)
+menu(The zsh/system Module)
+menu(The zsh/net/tcp Module)
+menu(The zsh/termcap Module)
+menu(The zsh/terminfo Module)
+menu(The zsh/zftp Module)
+menu(The zsh/zle Module)
+menu(The zsh/zleparameter Module)
+menu(The zsh/zprof Module)
+menu(The zsh/zpty Module)
+menu(The zsh/zselect Module)
+menu(The zsh/zutil Module)
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/version.yo
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/version.yo
@@ -0,0 +1,4 @@
+STARTDEF()
+def(version)(0)(4.2.1-dev-1)
+def(date)(0)(August 16, 2004)
+ENDDEF()\
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zsh.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zsh.1
@@ -0,0 +1,529 @@
+.TH "ZSH" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zsh \- the Z shell
+.\" Yodl file: Zsh/intro.yo
+.SH "OVERVIEW"
+Because zsh contains many features, the zsh manual has been split into
+a number of sections:
+.PP
+.PD 0
+.TP
+\fIzsh\fP          Zsh overview (this section)
+.TP
+\fIzshmisc\fP      Anything not fitting into the other sections
+.TP
+\fIzshexpn\fP      Zsh command and parameter expansion
+.TP
+\fIzshparam\fP     Zsh parameters
+.TP
+\fIzshoptions\fP   Zsh options
+.TP
+\fIzshbuiltins\fP  Zsh built\-in functions
+.TP
+\fIzshzle\fP       Zsh command line editing
+.TP
+\fIzshcompwid\fP   Zsh completion widgets
+.TP
+\fIzshcompsys\fP   Zsh completion system
+.TP
+\fIzshcompctl\fP   Zsh completion control
+.TP
+\fIzshmodules\fP   Zsh loadable modules
+.TP
+\fIzshzftpsys\fP   Zsh built\-in FTP client
+.TP
+\fIzshall\fP       Meta\-man page containing all of the above
+.PD
+.SH "DESCRIPTION"
+Zsh is a UNIX command interpreter (shell) usable as an interactive
+login shell and as a shell script command processor\&.  Of the standard shells,
+zsh most closely resembles \fBksh\fP but includes many enhancements\&.  Zsh
+has command line editing, builtin spelling correction, programmable
+command completion, shell functions (with autoloading), a history
+mechanism, and a host of other features\&.
+.\" Yodl file: Zsh/metafaq.yo
+.SH "AUTHOR"
+Zsh was originally written by Paul Falstad \fB<pf@zsh\&.org>\fP\&.
+Zsh is now maintained by the members of the zsh\-workers mailing
+list \fB<zsh\-workers@sunsite\&.dk>\fP\&.  The development is currently
+coordinated by Peter Stephenson \fB<pws@zsh\&.org>\fP\&.  The coordinator
+can be contacted at \fB<coordinator@zsh\&.org>\fP, but matters relating to
+the code should generally go to the mailing list\&.
+.SH "AVAILABILITY"
+Zsh is available from the following anonymous FTP sites\&.  These mirror
+sites are kept frequently up to date\&.  The sites marked with \fI(H)\fP may be
+mirroring \fBftp\&.cs\&.elte\&.hu\fP instead of the primary site\&.
+.PP
+.PD 0
+.TP
+.PD
+Primary site
+.nf
+\fBftp://ftp\&.zsh\&.org/pub/zsh/\fP
+\fBhttp://www\&.zsh\&.org/pub/zsh/\fP
+.fi
+.TP
+Australia
+.nf
+\fBftp://ftp\&.zsh\&.org/pub/zsh/\fP
+\fBhttp://www\&.zsh\&.org/pub/zsh/\fP
+.fi
+.TP
+Denmark
+.nf
+\fBftp://sunsite\&.dk/pub/unix/shells/zsh/\fP
+.fi
+.TP
+Finland
+.nf
+\fBftp://ftp\&.funet\&.fi/pub/unix/shells/zsh/\fP
+.fi
+.TP
+Germany
+.nf
+\fBftp://ftp\&.fu\-berlin\&.de/pub/unix/shells/zsh/\fP  \fI(H)\fP
+\fBftp://ftp\&.gmd\&.de/packages/zsh/\fP
+\fBftp://ftp\&.uni\-trier\&.de/pub/unix/shell/zsh/\fP
+.fi
+.TP
+Hungary
+.nf
+\fBftp://ftp\&.cs\&.elte\&.hu/pub/zsh/\fP
+\fBhttp://www\&.cs\&.elte\&.hu/pub/zsh/\fP
+\fBftp://ftp\&.kfki\&.hu/pub/packages/zsh/\fP
+.fi
+.TP
+Israel
+.nf
+\fBftp://ftp\&.math\&.technion\&.ac\&.il/pub/zsh/\fP
+\fBhttp://www\&.math\&.technion\&.ac\&.il/pub/zsh/\fP
+.fi
+.TP
+Japan
+.nf
+\fBftp://ftp\&.win\&.ne\&.jp/pub/shell/zsh/\fP
+\fBftp://ftp\&.ayamura\&.org/pub/zsh/\fP
+.fi
+.TP
+Korea
+.nf
+\fBftp://linux\&.sarang\&.net/mirror/system/shell/zsh/\fP
+.fi
+.TP
+Netherlands
+.nf
+\fBftp://ftp\&.demon\&.nl/pub/mirrors/zsh/\fP
+.fi
+.TP
+Norway
+.nf
+\fBftp://ftp\&.uit\&.no/pub/unix/shells/zsh/\fP
+.fi
+.TP
+Poland
+.nf
+\fBftp://sunsite\&.icm\&.edu\&.pl/pub/unix/shells/zsh/\fP
+.fi
+.TP
+Romania
+.nf
+\fBftp://ftp\&.roedu\&.net/pub/mirrors/ftp\&.zsh\&.org/pub/zsh/\fP
+\fBftp://ftp\&.kappa\&.ro/pub/mirrors/ftp\&.zsh\&.org/pub/zsh/\fP
+.fi
+.TP
+Slovenia
+.nf
+\fBftp://ftp\&.siol\&.net/mirrors/zsh/\fP
+.fi
+.TP
+Sweden
+.nf
+\fBftp://ftp\&.lysator\&.liu\&.se/pub/unix/zsh/\fP
+.fi
+.TP
+UK
+.nf
+\fBftp://ftp\&.net\&.lut\&.ac\&.uk/zsh/\fP
+\fBftp://sunsite\&.org\&.uk/packages/zsh/\fP
+.fi
+.TP
+USA
+.nf
+\fBftp://uiarchive\&.uiuc\&.edu/mirrors/ftp/ftp\&.zsh\&.org/pub/\fP
+\fBftp://ftp\&.rge\&.com/pub/shells/zsh/\fP
+\fBhttp://zsh\&.disillusion\&.org/\fP
+\fBhttp://foad\&.org/zsh/\fP
+.fi
+.PP
+The up\-to\-date source code is available via anonymous CVS from Sourceforge\&.
+See \fBhttp://sourceforge\&.net/projects/zsh/\fP for details\&.
+.PP
+.SH "MAILING LISTS"
+Zsh has 3 mailing lists:
+.PP
+.PD 0
+.TP
+.PD
+\fB<zsh\-announce@sunsite\&.dk>\fP
+Announcements about releases, major changes in the shell and the
+monthly posting of the Zsh FAQ\&.  (moderated)
+.TP
+\fB<zsh\-users@sunsite\&.dk>\fP
+User discussions\&.
+.TP
+\fB<zsh\-workers@sunsite\&.dk>\fP
+Hacking, development, bug reports and patches\&.
+.PP
+To subscribe or unsubscribe, send mail
+to the associated administrative address for the mailing list\&.
+.PP
+.PD 0
+.TP
+\fB<zsh\-announce\-subscribe@sunsite\&.dk>\fP
+.TP
+\fB<zsh\-users\-subscribe@sunsite\&.dk>\fP
+.TP
+\fB<zsh\-workers\-subscribe@sunsite\&.dk>\fP
+.PP
+.TP
+\fB<zsh\-announce\-unsubscribe@sunsite\&.dk>\fP
+.TP
+\fB<zsh\-users\-unsubscribe@sunsite\&.dk>\fP
+.TP
+\fB<zsh\-workers\-unsubscribe@sunsite\&.dk>\fP
+.PD
+.PP
+YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED\&.
+All submissions to \fBzsh\-announce\fP are automatically forwarded to
+\fBzsh\-users\fP\&.  All submissions to \fBzsh\-users\fP are automatically
+forwarded to \fBzsh\-workers\fP\&.
+.PP
+If you have problems subscribing/unsubscribing to any of the mailing
+lists, send mail to \fB<listmaster@zsh\&.org>\fP\&.  The mailing lists are
+maintained by Karsten Thygesen \fB<karthy@kom\&.auc\&.dk>\fP\&.
+.PP
+The mailing lists are archived; the archives can be accessed via the
+administrative addresses listed above\&.  There is also a hypertext
+archive, maintained by Geoff Wing \fB<gcw@zsh\&.org>\fP, available at
+\fBhttp://www\&.zsh\&.org/mla/\fP\&.
+.SH "THE ZSH FAQ"
+Zsh has a list of Frequently Asked Questions (FAQ), maintained by
+Peter Stephenson \fB<pws@zsh\&.org>\fP\&.  It is regularly posted to the
+newsgroup \fBcomp\&.unix\&.shell\fP and the \fBzsh\-announce\fP mailing list\&.
+The latest version can be found at any of the Zsh FTP sites, or at
+\fBhttp://www\&.zsh\&.org/FAQ/\fP\&.  The contact address for FAQ\-related matters
+is \fB<faqmaster@zsh\&.org>\fP\&.
+.SH "THE ZSH WEB PAGE"
+Zsh has a web page which is located at \fBhttp://www\&.zsh\&.org/\fP\&.  This is
+maintained by Karsten Thygesen \fB<karthy@zsh\&.org>\fP, of SunSITE Denmark\&.
+The contact address for web\-related matters is \fB<webmaster@zsh\&.org>\fP\&.
+.SH "THE ZSH USERGUIDE"
+A userguide is currently in preparation\&.  It is intended to complement the
+manual, with explanations and hints on issues where the manual can be
+cabbalistic, hierographic, or downright mystifying (for example, the word
+`hierographic' does not exist)\&.  It can be viewed in its current state at
+\fBhttp://zsh\&.sunsite\&.dk/Guide/\fP\&.  At the time of writing, chapters
+dealing with startup files and their contents and the new completion system
+were essentially complete\&.
+.SH "THE ZSH WIKI"
+A `wiki' website for zsh has been created at \fBhttp://www\&.zshwiki\&.org/\fP\&.
+This is a site which can be added to and modified directly by users without
+any special permission\&.  You can add your own zsh tips and configurations\&.
+.\" Yodl file: Zsh/invoke.yo
+.SH "INVOCATION OPTIONS"
+The following flags are interpreted by the shell when invoked to determine
+where the shell will read commands from:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-c\fP
+Take the first argument as a command to execute, rather than reading commands
+from a script or standard input\&.  If any further arguments are given, the
+first one is assigned to \fB$0\fP, rather than being used as a positional
+parameter\&.
+.TP
+\fB\-i\fP
+Force shell to be interactive\&.
+.TP
+\fB\-s\fP
+Force shell to read commands from the standard input\&.
+If the \fB\-s\fP flag is not present and an argument is given,
+the first argument is taken to be the pathname of a script to
+execute\&.
+.PP
+After the first one or two arguments have been appropriated as described above,
+the remaining arguments are assigned to the positional parameters\&.
+.PP
+For further options, which are common to invocation and the \fBset\fP
+builtin, see
+\fIzshoptions\fP(1)\&.
+.PP
+Options may be specified by name using the \fB\-o\fP option\&.  \fB\-o\fP acts like
+a single\-letter option, but takes a following string as the option name\&.
+For example,
+.PP
+.RS
+.nf
+\fBzsh \-x \-o shwordsplit scr\fP
+.fi
+.RE
+.PP
+runs the script \fBscr\fP, setting the \fBXTRACE\fP option by the corresponding
+letter `\fB\-x\fP' and the \fBSH_WORD_SPLIT\fP option by name\&.
+Options may be turned \fIoff\fP by name by using \fB+o\fP instead of \fB\-o\fP\&.
+\fB\-o\fP can be stacked up with preceding single\-letter options, so for example
+`\fB\-xo shwordsplit\fP' or `\fB\-xoshwordsplit\fP' is equivalent to
+`\fB\-x \-o shwordsplit\fP'\&.
+.PP
+Options may also be specified by name in GNU long option style,
+`\fB\-\-\fP\fIoption\-name\fP'\&.  When this is done, `\fB\-\fP' characters in the
+option name are permitted: they are translated into `\fB_\fP', and thus ignored\&.
+So, for example, `\fBzsh \-\-sh\-word\-split\fP' invokes zsh with the
+\fBSH_WORD_SPLIT\fP option turned on\&.  Like other option syntaxes, options can
+be turned off by replacing the initial `\fB\-\fP' with a `\fB+\fP'; thus
+`\fB+\-sh\-word\-split\fP' is equivalent to `\fB\-\-no\-sh\-word\-split\fP'\&.
+Unlike other option syntaxes, GNU\-style long options cannot be stacked with
+any other options, so for example `\fB\-x\-shwordsplit\fP' is an error,
+rather than being treated like `\fB\-x \-\-shwordsplit\fP'\&.
+.PP
+The special GNU\-style option `\fB\-\-version\fP' is handled; it sends to standard
+output the shell's version information, then exits successfully\&.
+`\fB\-\-help\fP' is also handled; it sends to standard output a list of options
+that can be used when invoking the shell, then exits successfully\&.
+.PP
+Option processing may be finished, allowing following arguments that start with
+`\fB\-\fP' or `\fB+\fP' to be treated as normal arguments, in two ways\&.
+Firstly, a lone `\fB\-\fP' (or `\fB+\fP') as an argument by itself ends option
+processing\&.  Secondly, a special option `\fB\-\-\fP' (or `\fB+\-\fP'), which may
+be specified on its own (which is the standard POSIX usage) or may be stacked
+with preceding options (so `\fB\-x\-\fP' is equivalent to `\fB\-x \-\-\fP')\&.  Options
+are not permitted to be stacked after `\fB\-\-\fP' (so `\fB\-x\-f\fP' is an error),
+but note the GNU\-style option form discussed above, where `\fB\-\-shwordsplit\fP'
+is permitted and does not end option processing\&.
+.PP
+Except when the \fBsh\fP/\fBksh\fP emulation single\-letter options are in effect,
+the option `\fB\-b\fP' (or `\fB+b\fP') ends option processing\&.
+`\fB\-b\fP' is like `\fB\-\fP\fB\-\fP', except that further single\-letter options
+can be stacked after the `\fB\-b\fP' and will take effect as normal\&.
+.PP
+.PP
+.\" Yodl file: Zsh/compat.yo
+.SH "COMPATIBILITY"
+Zsh tries to emulate \fBsh\fP or \fBksh\fP when it is invoked as
+\fBsh\fP or \fBksh\fP respectively; more precisely, it looks at the first
+letter of the name by which it was invoked, excluding any initial `\fBr\fP'
+(assumed to stand for `restricted'), and if that is `\fBs\fP' or `\fBk\fP' it
+will emulate \fBsh\fP or \fBksh\fP\&.  Furthermore, if invoked as \fBsu\fP (which
+happens on certain systems when the shell is executed by the \fBsu\fP
+command), the shell will try to find an alternative name from the \fBSHELL\fP
+environment variable and perform emulation based on that\&.
+.PP
+In \fBsh\fP and \fBksh\fP compatibility modes the following
+parameters are not special and not initialized by the shell:
+\fBARGC\fP,
+\fBargv\fP,
+\fBcdpath\fP,
+\fBfignore\fP,
+\fBfpath\fP,
+\fBHISTCHARS\fP,
+\fBmailpath\fP,
+\fBMANPATH\fP,
+\fBmanpath\fP,
+\fBpath\fP,
+\fBprompt\fP,
+\fBPROMPT\fP,
+\fBPROMPT2\fP,
+\fBPROMPT3\fP,
+\fBPROMPT4\fP,
+\fBpsvar\fP,
+\fBstatus\fP,
+\fBwatch\fP\&.
+.PP
+The usual zsh startup/shutdown scripts are not executed\&.  Login shells
+source \fB/etc/profile\fP followed by \fB$HOME/\&.profile\fP\&.  If the
+\fBENV\fP environment variable is set on invocation, \fB$ENV\fP is sourced
+after the profile scripts\&.  The value of \fBENV\fP is subjected to
+parameter expansion, command substitution, and arithmetic expansion
+before being interpreted as a pathname\&.  Note that the \fBPRIVILEGED\fP
+option also affects the execution of startup files\&.
+.PP
+The following options are set if the shell is invoked as \fBsh\fP or
+\fBksh\fP:
+\fBNO_BAD_PATTERN\fP,
+\fBNO_BANG_HIST\fP,
+\fBNO_BG_NICE\fP,
+\fBNO_EQUALS\fP,
+\fBNO_FUNCTION_ARGZERO\fP,
+\fBGLOB_SUBST\fP,
+\fBNO_GLOBAL_EXPORT\fP,
+\fBNO_HUP\fP,
+\fBINTERACTIVE_COMMENTS\fP,
+\fBKSH_ARRAYS\fP,
+\fBNO_MULTIOS\fP,
+\fBNO_NOMATCH\fP,
+\fBNO_NOTIFY\fP,
+\fBPOSIX_BUILTINS\fP,
+\fBNO_PROMPT_PERCENT\fP,
+\fBRM_STAR_SILENT\fP,
+\fBSH_FILE_EXPANSION\fP,
+\fBSH_GLOB\fP,
+\fBSH_OPTION_LETTERS\fP,
+\fBSH_WORD_SPLIT\fP\&.
+Additionally the \fBBSD_ECHO\fP and \fBIGNORE_BRACES\fP
+options are set if zsh is invoked as \fBsh\fP\&.
+Also, the
+\fBKSH_OPTION_PRINT\fP,
+\fBLOCAL_OPTIONS\fP,
+\fBPROMPT_BANG\fP,
+\fBPROMPT_SUBST\fP
+and
+\fBSINGLE_LINE_ZLE\fP
+options are set if zsh is invoked as \fBksh\fP\&.
+.\" Yodl file: Zsh/restricted.yo
+.SH "RESTRICTED SHELL"
+When the basename of the command used to invoke zsh starts with the letter
+`\fBr\fP' or the `\fB\-r\fP' command line option is supplied at invocation, the
+shell becomes restricted\&.  Emulation mode is determined after stripping the
+letter `\fBr\fP' from the invocation name\&.  The following are disabled in
+restricted mode:
+.PP
+.PD 0
+.TP
+.PD
+\(bu
+changing directories with the \fBcd\fP builtin
+.TP
+\(bu
+changing or unsetting the \fBPATH\fP, \fBpath\fP, \fBMODULE_PATH\fP,
+\fBmodule_path\fP, \fBSHELL\fP, \fBHISTFILE\fP, \fBHISTSIZE\fP, \fBGID\fP, \fBEGID\fP,
+\fBUID\fP, \fBEUID\fP, \fBUSERNAME\fP, \fBLD_LIBRARY_PATH\fP,
+\fBLD_AOUT_LIBRARY_PATH\fP, \fBLD_PRELOAD\fP and  \fBLD_AOUT_PRELOAD\fP
+parameters
+.TP
+\(bu
+specifying command names containing \fB/\fP
+.TP
+\(bu
+specifying command pathnames using \fBhash\fP
+.TP
+\(bu
+redirecting output to files
+.TP
+\(bu
+using the \fBexec\fP builtin command to replace the shell with another
+command
+.TP
+\(bu
+using \fBjobs \-Z\fP to overwrite the shell process' argument and
+environment space
+.TP
+\(bu
+using the \fBARGV0\fP parameter to override \fBargv[0]\fP for external
+commands
+.TP
+\(bu
+turning off restricted mode with \fBset +r\fP or \fBunsetopt
+RESTRICTED\fP
+.PP
+These restrictions are enforced after processing the startup files\&.  The
+startup files should set up \fBPATH\fP to point to a directory of commands
+which can be safely invoked in the restricted environment\&.  They may also
+add further restrictions by disabling selected builtins\&.
+.PP
+Restricted mode can also be activated any time by setting the
+\fBRESTRICTED\fP option\&.  This immediately enables all the restrictions
+described above even if the shell still has not processed all startup
+files\&.
+.\" Yodl file: Zsh/files.yo
+.SH "STARTUP/SHUTDOWN FILES"
+Commands are first read from \fB/etc/zshenv\fP; this cannot be overridden\&.
+Subsequent behaviour is modified by the \fBRCS\fP and
+\fBGLOBAL_RCS\fP options; the former affects all startup files, while the
+second only affects those in the \fB/etc\fP directory\&.  If one of the options
+is unset at any point, any subsequent startup file(s) of the corresponding
+type will not be read\&.  It is also possible for a file in \fB$ZDOTDIR\fP to
+re\-enable \fBGLOBAL_RCS\fP\&. Both \fBRCS\fP and \fBGLOBAL_RCS\fP are set by
+default\&.
+.PP
+Commands are then read from \fB$ZDOTDIR/\&.zshenv\fP\&.
+If the shell is a login shell, commands
+are read from \fB/etc/zprofile\fP and then \fB$ZDOTDIR/\&.zprofile\fP\&.
+Then, if the shell is interactive,
+commands are read from \fB/etc/zshrc\fP and then \fB$ZDOTDIR/\&.zshrc\fP\&.
+Finally, if the shell is a login shell, \fB/etc/zlogin\fP and
+\fB$ZDOTDIR/\&.zlogin\fP are read\&.
+.PP
+When a login shell exits, the files \fB$ZDOTDIR/\&.zlogout\fP and then
+\fB/etc/zlogout\fP are read\&.  This happens with either an explicit exit
+via the \fBexit\fP or \fBlogout\fP commands, or an implicit exit by reading
+end\-of\-file from the terminal\&.  However, if the shell terminates due
+to \fBexec\fP'ing another process, the logout files are not read\&.
+These are also affected by the \fBRCS\fP and \fBGLOBAL_RCS\fP options\&.
+Note also that the \fBRCS\fP option affects the saving of history files,
+i\&.e\&. if \fBRCS\fP is unset when the shell exits, no history file will be
+saved\&.
+.PP
+If \fBZDOTDIR\fP is unset, \fBHOME\fP is used instead\&.
+Those files listed above as being in \fB/etc\fP may be in another
+directory, depending on the installation\&.
+.PP
+As \fB/etc/zshenv\fP is run for all instances of zsh, it is important that
+it be kept as small as possible\&.  In particular, it is a good idea to
+put code that does not need to be run for every single shell behind
+a test of the form `\fBif [[ \-o rcs ]]; then \&.\&.\&.\fP' so that it will not
+be executed when zsh is invoked with the `\fB\-f\fP' option\&.
+.PP
+Any of these files may be pre\-compiled with the \fBzcompile\fP builtin
+command (see \fIzshbuiltins\fP(1))\&.  If a compiled file exists (named for the original file plus the
+\fB\&.zwc\fP extension) and it is newer than the original file, the compiled
+file will be used instead\&.
+.\" Yodl file: Zsh/filelist.yo
+.SH "FILES"
+.PD 0
+.TP
+\fB$ZDOTDIR/\&.zshenv\fP
+.TP
+\fB$ZDOTDIR/\&.zprofile\fP
+.TP
+\fB$ZDOTDIR/\&.zshrc\fP
+.TP
+\fB$ZDOTDIR/\&.zlogin\fP
+.TP
+\fB$ZDOTDIR/\&.zlogout\fP
+.TP
+\fB${TMPPREFIX}*\fP   (default is /tmp/zsh*)
+.TP
+\fB/etc/zshenv\fP
+.TP
+\fB/etc/zprofile\fP
+.TP
+\fB/etc/zshrc\fP
+.TP
+\fB/etc/zlogin\fP
+.TP
+\fB/etc/zlogout\fP    (installation\-specific \- \fB/etc\fP is the default)
+.PD
+.\" Yodl file: Zsh/seealso.yo
+.SH "SEE ALSO"
+\fIsh\fP(1),
+\fIcsh\fP(1),
+\fItcsh\fP(1),
+\fIrc\fP(1),
+\fIbash\fP(1),
+\fIksh\fP(1),
+\fIzshbuiltins\fP(1),
+\fIzshcompwid\fP(1),
+\fIzshcompsys\fP(1),
+\fIzshcompctl\fP(1),
+\fIzshexpn\fP(1),
+\fIzshmisc\fP(1),
+\fIzshmodules\fP(1),
+\fIzshoptions\fP(1),
+\fIzshparam\fP(1),
+\fIzshzle\fP(1)
+.PP
+\fBIEEE Standard for information Technology \-
+Portable Operating System Interface (POSIX) \-
+Part 2: Shell and Utilities\fP,
+IEEE Inc, 1993, ISBN 1\-55937\-255\-9\&.
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshbuiltins.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshbuiltins.1
@@ -0,0 +1,2042 @@
+.TH "ZSHBUILTINS" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshbuiltins \- zsh built\-in commands
+.\" Yodl file: Zsh/builtins.yo
+.SH "SHELL BUILTIN COMMANDS"
+.PD 0
+.TP
+.PD
+\fB\-\fP \fIsimple command\fP
+See the section `Precommand Modifiers'\&.
+.TP
+\fB\&.\fP \fIfile\fP [ \fIarg\fP \&.\&.\&. ]
+Read commands from \fIfile\fP and execute them in the current shell
+environment\&.
+.RS
+.PP
+If \fIfile\fP does not contain a slash, or if \fBPATH_DIRS\fP is set,
+the shell looks in the components of \fB$path\fP to find the directory
+containing \fIfile\fP\&.  Files in the current directory are not read
+unless `\fB\&.\fP' appears somewhere in \fB$path\fP\&.  If a file named
+`\fIfile\fP\fB\&.zwc\fP' is found, is newer than \fIfile\fP, and is the
+compiled form (created with the \fBzcompile\fP builtin) of \fIfile\fP,
+then commands are read from that file instead of \fIfile\fP\&.
+.PP
+If any arguments \fIarg\fP are given,
+they become the positional parameters; the old positional
+parameters are restored when the \fIfile\fP is done executing\&.
+The exit status is the exit status of the last command executed\&.
+.RE
+.TP
+\fB:\fP [ \fIarg\fP \&.\&.\&. ]
+This command does nothing, although normal argument expansions is performed
+which may have effects on shell parameters\&.  A zero exit code is returned\&.
+.TP
+\fBalias\fP [ {\fB+|\fB\-\fP\fP}\fBgmrsL\fP ] [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ]
+For each \fIname\fP with a corresponding \fIvalue\fP, define an alias
+with that value\&.  A trailing space in \fIvalue\fP causes the next word
+to be checked for alias expansion\&.  If the \fB\-g\fP flag is present,
+define a global alias; global aliases are expanded even if they do not
+occur in command position\&.
+.RS
+.PP
+If the \fB\-s\fP flags is present, define a suffix alias: if the command
+word on a command line is in the form `\fItext\fP\fB\&.\fP\fIname\fP', where
+\fItext\fP is any non\-empty string, it is replaced by the text
+`\fIvalue\fP \fItext\fP\fB\&.\fP\fIname\fP'\&.  Note that \fIname\fP is treated as
+a literal string, not a pattern\&.  A trailing space in \fIvalue\fP is not
+special in this case\&.  For example,
+.PP
+.RS
+.nf
+\fBalias \-s ps=gv\fP
+.fi
+.RE
+.PP
+will cause the command `\fB*\&.ps\fP' to be expanded to `\fBgv *\&.ps\fP'\&.  As
+alias expansion is carried out earlier than globbing, the `\fB*\&.ps\fP' will
+then be expanded\&.  Suffix aliases constitute a different name space from
+other aliases (so in the above example it is still possible
+to create an alias for the command \fBps\fP) and the two sets are never
+listed together\&.
+.PP
+For each \fIname\fP with no \fIvalue\fP,
+print the value of \fIname\fP, if any\&.  With no arguments, print all
+currently defined aliases other than suffix aliases\&.  If the \fB\-m\fP flag
+is given the arguments are taken as patterns (they should be quoted to
+preserve them from being interpreted as glob patterns), and the aliases
+matching these patterns are printed\&.  When printing aliases and one of
+the \fB\-g\fP, \fB\-r\fP or \fB\-s\fP flags is present, restrict the printing to
+global, regular or suffix aliases, respectively; a regular alias is one
+which is neither a global nor a suffix alias\&.   Using `\fB+\fP'
+instead of `\fB\-\fP', or ending the option list with a single
+`\fB+\fP', prevents the values of the aliases from being printed\&.
+.PP
+If the \fB\-L\fP flag is present, then print each
+alias in a manner suitable for putting in a startup script\&.  The exit
+status is nonzero if a \fIname\fP (with no \fIvalue\fP) is given for
+which no alias has been defined\&.
+.RE
+.TP
+\fBautoload\fP [ {\fB+\fP|\fB\-\fP}\fBUXktz\fP ] [ \fB\-w\fP ] [ \fIname\fP \&.\&.\&. ]
+Equivalent to \fBfunctions \-u\fP, with the exception of \fB\-X\fP/\fB+X\fP and
+\fB\-w\fP\&.
+.RS
+.PP
+The flag \fB\-X\fP may be used only inside a shell function, and may not be
+followed by a \fIname\fP\&.  It causes the calling function to be marked for
+autoloading and then immediately loaded and executed, with the current
+array of positional parameters as arguments\&.  This replaces the previous
+definition of the function\&.  If no function definition is found, an error
+is printed and the function remains undefined and marked for autoloading\&.
+.PP
+The flag \fB+X\fP attempts to load each \fIname\fP as an autoloaded function,
+but does \fInot\fP execute it\&.  The exit status is zero (success) if the
+function was not previously defined \fIand\fP a definition for it was found\&.
+This does \fInot\fP replace any existing definition of the function\&.  The
+exit status is nonzero (failure) if the function was already defined or
+when no definition was found\&.  In the latter case the function remains
+undefined and marked for autoloading\&.  If ksh\-style autoloading is
+enabled, the function created will contain the contents of the file
+plus a call to the function itself appended to it, thus giving normal
+ksh autoloading behaviour on the first call to the function\&.
+.PP
+With the \fB\-w\fP flag, the \fIname\fPs are taken as names of files compiled
+with the \fBzcompile\fP builtin, and all functions defined in them are
+marked for autoloading\&.
+.RE
+.TP
+.PD 0
+\fBbg\fP [ \fIjob\fP \&.\&.\&. ]
+.TP
+.PD
+\fIjob\fP \&.\&.\&. \fB&\fP
+Put each specified \fIjob\fP in the background,
+or the current job if none is specified\&.
+.TP
+\fBbindkey\fP
+See the section `Zle Builtins' in \fIzshzle\fP(1)\&.
+.TP
+\fBbreak\fP [ \fIn\fP ]
+Exit from an enclosing \fBfor\fP, \fBwhile\fP,
+\fBuntil\fP, \fBselect\fP or \fBrepeat\fP loop\&.  If \fIn\fP
+is specified, then break \fIn\fP levels instead of just one\&.
+.TP
+\fBbuiltin\fP \fIname\fP [ \fIargs\fP \&.\&.\&. ]
+Executes the builtin \fIname\fP, with the given \fIargs\fP\&.
+.TP
+\fBbye\fP
+Same as \fBexit\fP\&.
+.TP
+\fBcap\fP
+See the section `The zsh/cap Module' in \fIzshmodules\fP(1)\&.
+.TP
+.PD 0
+\fBcd\fP [ \fB\-sLP\fP ] [ \fIarg\fP ]
+.TP
+.PD 0
+\fBcd\fP [ \fB\-sLP\fP ] \fIold\fP \fInew\fP
+.TP
+.PD
+\fBcd\fP [ \fB\-sLP\fP ] {\fB+\fP|\fB\-\fP}\fIn\fP
+Change the current directory\&.  In the first form, change the
+current directory to \fIarg\fP, or to the value of \fB$HOME\fP if
+\fIarg\fP is not specified\&.  If \fIarg\fP is `\fB\-\fP', change to the
+value of \fB$OLDPWD\fP, the previous directory\&.
+Otherwise, if a directory named \fIarg\fP is not found in the current
+directory and \fIarg\fP does not begin with a slash, search each
+component of the shell parameter \fBcdpath\fP\&.  If no directory is found
+and the option \fBCDABLE_VARS\fP is set, and a parameter named \fIarg\fP
+exists whose value begins with a slash, treat its value as the
+directory\&.  In that case, the parameter is added to the named
+directory hash table\&.
+.RS
+.PP
+The second form of \fBcd\fP substitutes the string \fInew\fP
+for the string \fIold\fP in the name of the current directory,
+and tries to change to this new directory\&.
+.PP
+The third form of \fBcd\fP extracts an entry from the directory
+stack, and changes to that directory\&.  An argument of the form
+`\fB+\fP\fIn\fP' identifies a stack entry by counting from the left
+of the list shown by the \fBdirs\fP command, starting with zero\&.
+An argument of the form `\fB\-\fP\fIn\fP' counts from the right\&.
+If the \fBPUSHD_MINUS\fP option is set, the meanings of `\fB+\fP'
+and `\fB\-\fP' in this context are swapped\&.
+.PP
+If the \fB\-s\fP option is specified, \fBcd\fP refuses to change the current
+directory if the given pathname contains symlinks\&.  If the \fB\-P\fP option
+is given or the \fBCHASE_LINKS\fP option is set, symbolic links are resolved
+to their true values\&.  If the \fB\-L\fP option is given symbolic links are
+followed regardless of the state of the \fBCHASE_LINKS\fP option\&.
+.RE
+.TP
+\fBchdir\fP
+Same as \fBcd\fP\&.
+.TP
+\fBclone\fP
+See the section `The zsh/clone Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBcommand\fP [ \fB\-pvV\fP ] \fIsimple command\fP
+The simple command argument is taken as an external command instead of
+a function or builtin and is executed\&. If the \fBPOSIX_BUILTINS\fP option
+is set, builtins will also be executed but certain special properties
+of them are suppressed\&. The \fB\-p\fP flag causes a default path to be
+searched instead of that in \fB$path\fP\&. With the \fB\-v\fP flag, \fBcommand\fP
+is similar to \fBwhence\fP and with \fB\-V\fP, it is equivalent to \fBwhence
+\-v\fP\&.
+.RS
+.PP
+See also the section `Precommand Modifiers'\&.
+.RE
+.TP
+\fBcomparguments\fP
+See the section `The zsh/computil Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBcompcall\fP
+See the section `The zsh/compctl Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBcompctl\fP
+See the section `The zsh/compctl Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBcompdescribe\fP
+See the section `The zsh/computil Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBcompfiles\fP
+See the section `The zsh/computil Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBcompgroups\fP
+See the section `The zsh/computil Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBcompquote\fP
+See the section `The zsh/computil Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBcomptags\fP
+See the section `The zsh/computil Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBcomptry\fP
+See the section `The zsh/computil Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBcompvalues\fP
+See the section `The zsh/computil Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBcontinue\fP [ \fIn\fP ]
+Resume the next iteration of the enclosing
+\fBfor\fP, \fBwhile\fP, \fBuntil\fP, \fBselect\fP or
+\fBrepeat\fP loop\&.  If \fIn\fP is specified, break out of
+\fIn\fP\-1 loops and resume at the \fIn\fPth enclosing loop\&.
+.TP
+\fBdeclare\fP
+Same as \fBtypeset\fP\&.
+.TP
+.PD 0
+\fBdirs\fP [ \fB\-c\fP ] [ \fIarg\fP \&.\&.\&. ]
+.TP
+.PD
+\fBdirs\fP [ \fB\-lpv\fP ]
+With no arguments, print the contents of the directory stack\&.
+Directories are added to this stack with the \fBpushd\fP command,
+and removed with the \fBcd\fP or \fBpopd\fP commands\&.
+If arguments are specified, load them onto the directory stack,
+replacing anything that was there, and push the current directory
+onto the stack\&.
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fB\-c\fP
+clear the directory stack\&.
+.TP
+\fB\-l\fP
+print directory names in full instead of using of using \fB~\fP expressions\&.
+.TP
+\fB\-p\fP
+print directory entries one per line\&.
+.TP
+\fB\-v\fP
+number the directories in the stack when printing\&.
+.PP
+.RE
+.TP
+\fBdisable\fP [ \fB\-afmrs\fP ] \fIname\fP \&.\&.\&.
+Temporarily disable the \fIname\fPd hash table elements\&.  The default
+is to disable builtin commands\&.  This allows you to use an external
+command with the same name as a builtin command\&.  The \fB\-a\fP option
+causes \fBdisable\fP to act on regular or global aliases\&.  The \fB\-s\fP
+option causes \fBdisable\fP to act on suffix aliases\&.  The \fB\-f\fP option causes
+\fBdisable\fP to act on shell functions\&.  The \fB\-r\fP options causes
+\fBdisable\fP to act on reserved words\&.  Without arguments all disabled
+hash table elements from the corresponding hash table are printed\&.
+With the \fB\-m\fP flag the arguments are taken as patterns (which should be
+quoted to prevent them from undergoing filename expansion), and all hash
+table elements from the corresponding hash table matching these patterns
+are disabled\&.  Disabled objects can be enabled with the \fBenable\fP
+command\&.
+.TP
+.PD 0
+\fBdisown\fP [ \fIjob\fP \&.\&.\&. ]
+.TP
+.PD 0
+\fIjob\fP \&.\&.\&. \fB&|\fP
+.TP
+.PD
+\fIjob\fP \&.\&.\&. \fB&!\fP
+Remove the specified \fIjob\fPs from the job table; the shell will
+no longer report their status, and will not complain if you
+try to exit an interactive shell with them running or stopped\&.
+If no \fIjob\fP is specified, disown the current job\&.
+.RS
+.PP
+If the \fIjob\fPs are currently stopped and the \fBAUTO_CONTINUE\fP option
+is not set, a warning is printed containing information about how to
+make them running after they have been disowned\&.  If one of the latter
+two forms is used, the \fIjob\fPs will automatically be made running,
+independent of the setting of the \fBAUTO_CONTINUE\fP option\&.
+.RE
+.TP
+\fBecho\fP [ \fB\-neE\fP ] [ \fIarg\fP \&.\&.\&. ]
+Write each \fIarg\fP on the standard output, with a space separating
+each one\&.
+If the \fB\-n\fP flag is not present, print a newline at the end\&.
+\fBecho\fP recognizes the following escape sequences:
+.RS
+.PP
+.PD 0
+.TP
+\fB\ea\fP
+bell character
+.TP
+\fB\eb\fP
+backspace
+.TP
+\fB\ec\fP
+suppress final newline
+.TP
+\fB\ee\fP
+escape
+.TP
+\fB\ef\fP
+form feed
+.TP
+\fB\en\fP
+linefeed (newline)
+.TP
+\fB\er\fP
+carriage return
+.TP
+\fB\et\fP
+horizontal tab
+.TP
+\fB\ev\fP
+vertical tab
+.TP
+\fB\e\e\fP
+backslash
+.TP
+\fB\e0\fP\fINNN\fP
+character code in octal
+.TP
+\fB\ex\fP\fINN\fP
+character code in hexadecimal
+.TP
+\fB\eu\fP\fINNNN\fP
+unicode character code in hexadecimal
+.TP
+\fB\eU\fP\fINNNNNNNN\fP
+unicode character code in hexadecimal
+.PD
+.PP
+The \fB\-E\fP flag, or the \fBBSD_ECHO\fP option, can be used to disable
+these escape sequences\&.  In the latter case, \fB\-e\fP flag can be used to
+enable them\&.
+.RE
+.TP
+\fBechotc\fP
+See the section `The zsh/termcap Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBechoti\fP
+See the section `The zsh/terminfo Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBemulate\fP [ \fB\-LR\fP ] {\fBzsh\fP|\fBsh\fP|\fBksh\fP|\fBcsh\fP}
+Set up zsh options to emulate the specified shell as much as possible\&.
+\fBcsh\fP will never be fully emulated\&.
+If the argument is not one of the shells listed above, \fBzsh\fP
+will be used as a default; more precisely, the tests performed on the
+argument are the same as those used to determine the emulation at startup
+based on the shell name, see
+the section `Compatibility' in \fIzshmisc\fP(1)
+\&.  If the \fB\-R\fP option is given, all options
+are reset to their default value corresponding to the specified emulation
+mode, except for certain options describing the interactive
+environment; otherwise, only those options likely to cause portability
+problems in scripts and functions are altered\&.  If the \fB\-L\fP option
+is given, the options \fBLOCAL_OPTIONS\fP and \fBLOCAL_TRAPS\fP will be set as
+well, causing the effects of the \fBemulate\fP command and any \fBsetopt\fP and
+\fBtrap\fP commands to be local to the immediately surrounding shell
+function, if any; normally these options are turned off in all emulation
+modes except \fBksh\fP\&.
+.TP
+\fBenable\fP [ \fB\-afmrs\fP ] \fIname\fP \&.\&.\&.
+Enable the \fIname\fPd hash table elements, presumably disabled
+earlier with \fBdisable\fP\&.  The default is to enable builtin commands\&.
+The \fB\-a\fP option causes \fBenable\fP to act on regular or global aliases\&.
+The \fB\-s\fP option causes \fBenable\fP to act on suffix aliases\&.
+The \fB\-f\fP option causes \fBenable\fP to act on shell functions\&.  The \fB\-r\fP
+option causes \fBenable\fP to act on reserved words\&.  Without arguments
+all enabled hash table elements from the corresponding hash table are
+printed\&.  With the \fB\-m\fP flag the arguments are taken as patterns
+(should be quoted) and all hash table elements from the corresponding
+hash table matching these patterns are enabled\&.  Enabled objects can be
+disabled with the \fBdisable\fP builtin command\&.
+.TP
+\fBeval\fP [ \fIarg\fP \&.\&.\&. ]
+Read the arguments as input to the shell and execute the resulting
+command in the current shell process\&.
+.TP
+\fBexec\fP \fIsimple command\fP
+See the section `Precommand Modifiers'\&.
+.TP
+\fBexit\fP [ \fIn\fP ]
+Exit the shell with the exit code specified by \fIn\fP; if none
+is specified, use the exit code from the last command executed\&.
+An EOF condition will also cause the shell to exit, unless
+the \fBIGNORE_EOF\fP option is set\&.
+.TP
+\fBexport\fP [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ]
+The specified \fIname\fPs are marked for automatic export
+to the environment of subsequently executed commands\&.
+Equivalent to \fBtypeset \-gx\fP\&.
+If a parameter specified does not
+already exist, it is created in the global scope\&.
+.TP
+\fBfalse\fP [ \fIarg\fP \&.\&.\&. ]
+Do nothing and return an exit code of 1\&.
+.TP
+.PD 0
+\fBfc\fP [ \fB\-e\fP \fIename\fP ] [ \fB\-nlrdDfEim\fP ] [ \fIold\fP\fB=\fP\fInew\fP \&.\&.\&. ] [ \fIfirst\fP [ \fIlast\fP ] ]
+.TP
+.PD 0
+\fBfc\fP \fB\-p\fP [ \fB\-a\fP ] [ \fIfilename\fP [ \fIhistsize\fP [ \fIsavehistsize\fP ] ] ]
+.TP
+.PD 0
+\fBfc\fP \fB\-P\fP
+.TP
+.PD
+\fBfc\fP \fB\-ARWI\fP [ \fIfilename\fP ]
+Select a range of commands from \fIfirst\fP to \fIlast\fP from the
+history list\&.
+The arguments \fIfirst\fP and \fIlast\fP may be specified as a
+number or as a string\&.  A negative number is used as an offset
+to the current history event number\&.
+A string specifies the most recent event beginning with the given string\&.
+All substitutions \fIold\fP\fB=\fP\fInew\fP, if any, are then performed
+on the commands\&.
+.RS
+.PP
+If the \fB\-l\fP flag is given, the resulting commands are listed on
+standard output\&.
+If the \fB\-m\fP flag is also given the first argument is taken as a
+pattern (should be quoted) and only the history events matching this
+pattern will be shown\&.
+Otherwise the editor program \fIename\fP is invoked on a file containing
+these history events\&.  If \fIename\fP is not given, the value
+of the parameter \fBFCEDIT\fP is used\&.  If \fIename\fP is `\fB\-\fP',
+no editor is invoked\&.  When editing is complete, the edited
+command is executed\&.
+.PP
+If \fIfirst\fP is not specified, it will be set to \-1 (the most recent
+event), or to \-16 if the \fB\-l\fP flag is given\&.
+If \fIlast\fP is not specified, it will be set to \fIfirst\fP,
+or to \-1 if the \fB\-l\fP flag is given\&.
+.PP
+The flag \fB\-r\fP reverses the order of the commands and the
+flag \fB\-n\fP suppresses command numbers when listing\&.
+Also when listing, \fB\-d\fP prints timestamps for each command, and
+\fB\-f\fP prints full time\-date stamps\&.  Adding the \fB\-E\fP flag
+causes the dates to be printed as `\fIdd\fP\fB\&.\fP\fImm\fP\fB\&.\fP\fIyyyy\fP',
+instead of the default `\fImm\fP\fB/\fP\fIdd\fP\fB/\fP\fIyyyy\fP'\&.
+Adding the \fB\-i\fP flag causes the dates to be printed in ISO8601
+`\fIyyyy\fP\fB\-\fP\fImm\fP\fB\-\fP\fIdd\fP' format\&.
+With the \fB\-D\fP flag, \fBfc\fP prints elapsed times\&.
+.PP
+.PP
+`\fBfc \-p\fP' pushes the current history list onto a stack and switches to a
+new history list\&.  If the \fB\-a\fP option is also specified, this history list
+will be automatically popped when the current function scope is exited, which
+is a much better solution than creating a trap function to call `\fBfc \-P\fP'
+manually\&.  If no arguments are specified, the history list is left empty,
+\fB$HISTFILE\fP is unset, and \fB$HISTSIZE\fP & \fB$SAVEHIST\fP are set to their
+default values\&.  If one argument is given, \fB$HISTFILE\fP is set to that
+filename, \fB$HISTSIZE\fP & \fB$SAVEHIST\fP are left unchanged, and the history
+file is read in (if it exists) to initialize the new list\&.  If a second
+argument is specified, \fB$HISTSIZE\fP & \fB$SAVEHIST\fP are instead set to the
+single specified numeric value\&.  Finally, if a third argument is specified,
+\fB$SAVEHIST\fP is set to a separate value from \fB$HISTSIZE\fP\&.  You are free to
+change these environment values for the new history list however you desire
+in order to manipulate the new history list\&.
+.PP
+`\fBfc \-P\fP' pops the history list back to an older list saved by `\fBfc \-p\fP'\&.
+The current list is saved to its \fB$HISTFILE\fP before it is destroyed
+(assuming that \fB$HISTFILE\fP and \fB$SAVEHIST\fP are set appropriately, of
+course)\&.  The values of \fB$HISTFILE\fP, \fB$HISTSIZE\fP, and \fB$SAVEHIST\fP are
+restored to the values they had when `\fBfc \-p\fP' was called\&.  Note that this
+restoration can conflict with making these variables "local", so your best
+bet is to avoid local declarations for these variables in functions that use
+`\fBfc \-p\fP'\&.  The one other guaranteed\-safe combination is declaring these
+variables to be local at the top of your function and using the automatic
+option (\fB\-a\fP) with `\fBfc \-p\fP'\&.  Finally, note that it is legal to manually
+pop a push marked for automatic popping if you need to do so before the
+function exits\&.
+.PP
+`\fBfc \-R\fP' reads the history from the given file,
+`\fBfc \-W\fP' writes the history out to the given file,
+and `\fBfc \-A\fP' appends the history out to the given file\&.
+If no filename is specified, the \fB$HISTFILE\fP is assumed\&.
+If the \fB\-I\fP option is added to \fB\-R\fP, only those events that are
+not already contained within the internal history list are added\&.
+If the \fB\-I\fP option is added to \fB\-A\fP or \fB\-W\fP, 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 \fB$SAVEHIST\fP
+entries\&.
+.RE
+.TP
+.PD 0
+\fBfg\fP [ \fIjob\fP \&.\&.\&. ]
+.TP
+.PD
+\fIjob\fP \&.\&.\&.
+Bring each specified \fIjob\fP in turn to the foreground\&.
+If no \fIjob\fP is specified, resume the current job\&.
+.TP
+\fBfloat\fP [ {\fB+\fP|\fB\-\fP}\fBEFHghlprtux\fP ] [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ]
+Equivalent to \fBtypeset \-E\fP, except that options irrelevant to floating
+point numbers are not permitted\&.
+.TP
+\fBfunctions\fP [ {\fB+\fP|\fB\-\fP}\fBUXkmtuz\fP ] [ \fIname\fP \&.\&.\&. ]
+Equivalent to \fBtypeset \-f\fP\&.
+.TP
+\fBgetcap\fP
+See the section `The zsh/cap Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBgetln\fP [ \fB\-AclneE\fP ] \fIname\fP \&.\&.\&.
+Read the top value from the buffer stack and put it in
+the shell parameter \fBname\fP\&.  Equivalent to
+\fBread \-zr\fP\&.
+.TP
+\fBgetopts\fP \fIoptstring\fP \fIname\fP [ \fIarg\fP \&.\&.\&. ]
+Checks the \fIarg\fPs for legal options\&.  If the \fIarg\fPs are omitted,
+use the positional parameters\&.  A valid option argument
+begins with a `\fB+\fP' or a `\fB\-\fP'\&.  An argument not beginning with
+a `\fB+\fP' or a `\fB\-\fP', or the argument `\fB\-\-\fP', ends the options\&.
+Note that a single `\fB\-\fP' is not considered a valid option argument\&.
+\fIoptstring\fP contains the letters that \fBgetopts\fP
+recognizes\&.  If a letter is followed by a `\fB:\fP', that option
+is expected to have an argument\&.  The options can be
+separated from the argument by blanks\&.
+.RS
+.PP
+Each time it is invoked, \fBgetopts\fP places the option letter it finds
+in the shell parameter \fIname\fP, prepended with a `\fB+\fP' when
+\fIarg\fP begins with a `\fB+\fP'\&.  The index of the next \fIarg\fP
+is stored in \fBOPTIND\fP\&.  The option argument, if any,
+is stored in \fBOPTARG\fP\&.
+.PP
+The first option to be examined may be changed by explicitly assigning
+to \fBOPTIND\fP\&.  \fBOPTIND\fP has an initial value of \fB1\fP, and is
+normally reset to \fB1\fP upon exit from a shell function\&.  \fBOPTARG\fP
+is not reset and retains its value from the most recent call to
+\fBgetopts\fP\&.  If either of \fBOPTIND\fP or \fBOPTARG\fP is explicitly
+unset, it remains unset, and the index or option argument is not
+stored\&.  The option itself is still stored in \fIname\fP in this case\&.
+.PP
+A leading `\fB:\fP' in \fIoptstring\fP causes \fBgetopts\fP to store the
+letter of any invalid option in \fBOPTARG\fP, and to set \fIname\fP to
+`\fB?\fP' for an unknown option and to `\fB:\fP' when a required option is
+missing\&.  Otherwise, \fBgetopts\fP sets \fIname\fP to `\fB?\fP' and prints
+an error message when an option is invalid\&.  The exit status is
+nonzero when there are no more options\&.
+.RE
+.TP
+\fBhash\fP [ \fB\-Ldfmrv\fP ] [ \fIname\fP[\fB=\fP\fIvalue\fP] ] \&.\&.\&.
+\fBhash\fP can be used to directly modify the contents of the command
+hash table, and the named directory hash table\&.  Normally one would
+modify these tables by modifying one's \fBPATH\fP
+(for the command hash table) or by creating appropriate shell parameters
+(for the named directory hash table)\&.
+The choice of hash table to work on is determined by the \fB\-d\fP option;
+without the option the command hash table is used, and with the option the
+named directory hash table is used\&.
+.RS
+.PP
+Given no arguments, and neither the \fB\-r\fP or \fB\-f\fP options,
+the selected hash table will be listed in full\&.
+.PP
+The \fB\-r\fP option causes the selected hash table to be emptied\&.
+It will be subsequently rebuilt in the normal fashion\&.
+The \fB\-f\fP option causes the selected hash table to be fully
+rebuilt immediately\&.  For the command hash table this hashes
+all the absolute directories in the \fBPATH\fP,
+and for the named directory hash table this adds all users' home directories\&.
+These two options cannot be used with any arguments\&.
+.PP
+The \fB\-m\fP option causes the arguments to be taken as patterns
+(which should be quoted) and the elements of the hash table
+matching those patterns are printed\&.  This is the only way to display
+a limited selection of hash table elements\&.
+.PP
+For each \fIname\fP with a corresponding \fIvalue\fP, put `\fIname\fP' in
+the selected hash table, associating it with the pathname `\fIvalue\fP'\&.
+In the command hash table, this means that
+whenever `\fIname\fP' is used as a command argument, the shell will try
+to execute the file given by `\fIvalue\fP'\&.
+In the named directory hash table, this means
+that `\fIvalue\fP' may be referred to as `\fB~\fP\fIname\fP'\&.
+.PP
+For each \fIname\fP with no
+corresponding \fIvalue\fP, attempt to add \fIname\fP to the hash table,
+checking what the appropriate \fBvalue\fP is in the normal manner for
+that hash table\&.  If an appropriate \fBvalue\fP can't be found, then
+the hash table will be unchanged\&.
+.PP
+The \fB\-v\fP option causes hash table entries to be listed as they are
+added by explicit specification\&.  If has no effect if used with \fB\-f\fP\&.
+.PP
+If the \fB\-L\fP flag is present, then each hash table entry is printed in
+the form of a call to hash\&.
+.RE
+.TP
+\fBhistory\fP
+Same as \fBfc \-l\fP\&.
+.TP
+\fBinteger\fP [ {\fB+\fP|\fB\-\fP}\fBHghilprtux\fP ] [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ]
+Equivalent to \fBtypeset \-i\fP, except that options irrelevant to
+integers are not permitted\&.
+.TP
+.PD 0
+\fBjobs\fP [ \fB\-dlprs\fP ] [ \fIjob\fP \&.\&.\&. ]
+.TP
+.PD
+\fBjobs \-Z\fP \fIstring\fP
+Lists information about each given job, or all jobs
+if \fIjob\fP is omitted\&.  The \fB\-l\fP flag lists process
+IDs, and the \fB\-p\fP flag lists process groups\&.
+If the \fB\-r\fP flag is specified only running jobs will be listed
+and if the \fB\-s\fP flag is given only stopped jobs are shown\&.
+If the \fB\-d\fP flag is given, the directory from which the job was
+started (which may not be the current directory of the job) will also
+be shown\&.
+.RS
+.PP
+The \fB\-Z\fP option replaces the shell's argument and environment space with
+the given string, truncated if necessary to fit\&.  This will normally be
+visible in \fBps\fP (\fIps\fP(1)) listings\&.  This feature is typically
+used by daemons, to indicate their state\&.
+.RE
+.TP
+.PD 0
+\fBkill\fP [ \fB\-s\fP \fIsignal_name\fP | \fB\-n\fP \fIsignal_number\fP | \fB\-\fP\fIsig\fP ] \fIjob\fP \&.\&.\&.
+.TP
+.PD
+\fBkill\fP \fB\-l\fP [ \fIsig\fP \&.\&.\&. ]
+Sends either \fBSIGTERM\fP or the specified signal to the given
+jobs or processes\&.
+Signals are given by number or by names, with or without the `\fBSIG\fP'
+prefix\&.
+If the signal being sent is not `\fBKILL\fP' or `\fBCONT\fP', then the job
+will be sent a `\fBCONT\fP' signal if it is stopped\&.
+The argument \fIjob\fP can be the process ID of a job
+not in the job list\&.
+In the second form, \fBkill \-l\fP, if \fIsig\fP is not
+specified the signal names are listed\&.  Otherwise, for each
+\fIsig\fP that is a name, the corresponding signal number is
+listed\&.  For each \fIsig\fP that is a signal number or a number
+representing the exit status of a process which was terminated or
+stopped by a signal the name of the signal is printed\&.
+.TP
+\fBlet\fP \fIarg\fP \&.\&.\&.
+Evaluate each \fIarg\fP as an arithmetic expression\&.
+See the section `Arithmetic Evaluation' for a description
+of arithmetic expressions\&.  The exit status is 0 if the
+value of the last expression is nonzero, and 1 otherwise\&.
+.TP
+\fBlimit\fP [ \fB\-hs\fP ] [ \fIresource\fP [ \fIlimit\fP ] ] \&.\&.\&.
+Set or display resource limits\&.  Unless the \fB\-s\fP flag is given,
+the limit applies only the children of the shell\&.  If \fB\-s\fP is
+given without other arguments, the resource limits of the current
+shell is set to the previously set resource limits of the children\&.
+.RS
+.PP
+If \fIlimit\fP is not specified, print the current limit placed
+on \fIresource\fP, otherwise
+set the limit to the specified value\&.  If the \fB\-h\fP flag
+is given, use hard limits instead of soft limits\&.
+If no \fIresource\fP is given, print all limits\&.
+.PP
+When looping over multiple resources, the shell will abort immediately if
+it detects a badly formed argument\&.  However, if it fails to set a limit
+for some other reason it will continue trying to set the remaining limits\&.
+.PP
+\fIresource\fP can be one of:
+.PP
+.PD 0
+.TP
+\fBaddressspace\fP
+Maximum amount of address space used\&.
+.TP
+\fBaiomemorylocked\fP
+Maximum amount of memory locked in RAM for AIO operations\&.
+.TP
+\fBaiooperations\fP
+Maximum number of AIO operations\&.
+.TP
+\fBcachedthreads\fP
+Maximum number of cached threads\&.
+.TP
+\fBcoredumpsize\fP
+Maximum size of a core dump\&.
+.TP
+\fBcputime\fP
+Maximum CPU seconds per process\&.
+.TP
+\fBdatasize\fP
+Maximum data size (including stack) for each process\&.
+.TP
+\fBdescriptors\fP
+Maximum value for a file descriptor\&.
+.TP
+\fBfilesize\fP
+Largest single file allowed\&.
+.TP
+\fBmaxproc\fP
+Maximum number of processes\&.
+.TP
+\fBmaxpthreads\fP
+Maximum number of threads per process\&.
+.TP
+\fBmemorylocked\fP
+Maximum amount of memory locked in RAM\&.
+.TP
+\fBmemoryuse\fP
+Maximum resident set size\&.
+.TP
+\fBresident\fP
+Maximum resident set size\&.
+.TP
+\fBsockbufsize\fP
+Maximum size of all socket buffers\&.
+.TP
+\fBstacksize\fP
+Maximum stack size for each process\&.
+.TP
+\fBvmemorysize\fP
+Maximum amount of virtual memory\&.
+.PD
+.PP
+Which of these resource limits are available depends on the system\&.
+\fIresource\fP can be abbreviated to any unambiguous prefix\&.  It
+can also be an integer, which corresponds to the integer defined
+for the resource by the operating system\&.
+.PP
+If argument corresponds to a number which is out of the range of the
+resources configured into the shell, the shell will try to read or write
+the limit anyway, and will report an error if this fails\&.  As the shell
+does not store such resources internally, an attempt to set the limit will
+fail unless the \fB\-s\fP option is present\&.
+.PP
+\fIlimit\fP is a number, with an optional scaling factor, as follows:
+.PP
+.PD 0
+.TP
+\fIn\fP\fBh\fP
+hours
+.TP
+\fIn\fP\fBk\fP
+kilobytes (default)
+.TP
+\fIn\fP\fBm\fP
+megabytes or minutes
+.TP
+[\fImm\fP\fB:\fP]\fIss\fP
+minutes and seconds
+.PD
+.RE
+.TP
+\fBlocal\fP [ {\fB+\fP|\fB\-\fP}\fBAEFHLRUZahilprtux\fP [\fIn\fP]] [ \fIname\fP[\fB=\fP\fIvalue\fP] ] \&.\&.\&.
+Same as \fBtypeset\fP, except that the options \fB\-g\fP, and
+\fB\-f\fP are not permitted\&.  In this case the \fB\-x\fP option does not force
+the use of \fB\-g\fP, i\&.e\&. exported variables will be local to functions\&.
+.TP
+\fBlog\fP
+List all users currently logged in who are affected by
+the current setting of the \fBwatch\fP parameter\&.
+.TP
+\fBlogout\fP [ \fIn\fP ]
+Same as \fBexit\fP, except that it only works in a login shell\&.
+.TP
+\fBnoglob\fP \fIsimple command\fP
+See the section `Precommand Modifiers'\&.
+.TP
+\fBpopd\fP [ {\fB+\fP|\fB\-\fP}\fIn\fP ]
+Remove an entry from the directory stack, and perform a \fBcd\fP to
+the new top directory\&.  With no argument, the current top entry is
+removed\&.  An argument of the form `\fB+\fP\fIn\fP' identifies a stack
+entry by counting from the left of the list shown by the \fBdirs\fP command,
+starting with zero\&.  An argument of the form \fB\-n\fP counts from the right\&.
+If the \fBPUSHD_MINUS\fP option is set, the meanings of `\fB+\fP' and
+`\fB\-\fP' in this context are swapped\&.
+.TP
+.PD 0
+\fBprint\fP [ \fB\-abcDilmnNoOpPrsz\fP ] [ \fB\-u\fP \fIn\fP ] [ \fB\-f\fP \fIformat\fP ] [ \fB\-C\fP \fIcols\fP ]
+.TP
+.PD
+  [ \fB\-R\fP [ \fB\-en\fP ]] [ \fIarg\fP \&.\&.\&. ]
+With the `\fB\-f\fP' option the arguments are printed as described by \fBprintf\fP\&.
+With no flags or with the flag `\fB\-\fP', the arguments are printed on
+the standard output as described by \fBecho\fP, with the following differences:
+the escape sequence `\fB\eM\-\fP\fIx\fP' metafies the character
+\fIx\fP (sets the highest bit),
+`\fB\eC\-\fP\fIx\fP' produces a control character (`\fB\eC\-@\fP' and `\fB\eC\-?\fP' give the
+characters NUL and delete), and `\fB\eE\fP' is a synonym for `\fB\ee\fP'\&.
+Finally, if not in an escape
+sequence, `\fB\e\fP' escapes the following character and is not printed\&.
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fB\-a\fP
+Print arguments with the column incrementing first\&.  Only useful with the
+\fB\-c\fP and \fB\-C\fP options\&.
+.TP
+\fB\-b\fP
+Recognize all the escape sequences defined for the \fBbindkey\fP command,
+see 
+\fIzshzle\fP(1)\&.
+.TP
+\fB\-c\fP
+Print the arguments in columns\&.  Unless \fB\-a\fP is also given, arguments are
+printed with the row incrementing first\&.
+.TP
+\fB\-C\fP \fIcols\fP
+Print the arguments in \fIcols\fP columns\&.  Unless \fB\-a\fP is also given,
+arguments are printed with the row incrementing first\&.
+.TP
+\fB\-D\fP
+Treat the arguments as directory names, replacing prefixes with \fB~\fP
+expressions, as appropriate\&.
+.TP
+\fB\-i\fP
+If given together with \fB\-o\fP or \fB\-O\fP, sorting is performed
+case\-independently\&.
+.TP
+\fB\-l\fP
+Print the arguments separated by newlines instead of spaces\&.
+.TP
+\fB\-m\fP
+Take the first argument as a pattern (should be quoted), and remove
+it from the argument list together with subsequent arguments that
+do not match this pattern\&.
+.TP
+\fB\-n\fP
+Do not add a newline to the output\&.
+.TP
+\fB\-N\fP
+Print the arguments separated and terminated by nulls\&.
+.TP
+\fB\-o\fP
+Print the arguments sorted in ascending order\&.
+.TP
+\fB\-O\fP
+Print the arguments sorted in descending order\&.
+.TP
+\fB\-p\fP
+Print the arguments to the input of the coprocess\&.
+.TP
+\fB\-P\fP
+Perform prompt expansion (see
+\fIzshmisc\fP(1))\&.
+.TP
+\fB\-r\fP
+Ignore the escape conventions of \fBecho\fP\&.
+.TP
+\fB\-R\fP
+Emulate the BSD \fBecho\fP command, which does not process escape sequences
+unless the \fB\-e\fP flag is given\&.  The \fB\-n\fP flag suppresses the trailing
+newline\&.  Only the \fB\-e\fP and \fB\-n\fP flags are recognized after
+\fB\-R\fP; all other arguments and options are printed\&.
+.TP
+\fB\-s\fP
+Place the results in the history list instead of on the standard output\&.
+.TP
+\fB\-u\fP \fIn\fP
+Print the arguments to file descriptor \fIn\fP\&.
+.TP
+\fB\-z\fP
+Push the arguments onto the editing buffer stack, separated by spaces\&.
+.PP
+If any of `\fB\-m\fP', `\fB\-o\fP' or `\fB\-O\fP' are used in combination with
+`\fB\-f\fP' and there are no arguments (after the removal process in the
+case of `\fB\-m\fP') then nothing is printed\&.
+.RE
+.TP
+\fBprintf\fP \fIformat\fP [ \fIarg\fP \&.\&.\&. ]
+Print the arguments according to the format specification\&. Formatting
+rules are the same as used in C\&. The same escape sequences as for \fBecho\fP
+are recognised in the format\&. All C conversion specifications ending in
+one of csdiouxXeEfgGn are handled\&. In addition to this, `\fB%b\fP' can be
+used instead of `\fB%s\fP' to cause escape sequences in the argument to be
+recognised and `\fB%q\fP' can be used to quote the argument in such a way
+that allows it to be reused as shell input\&. With the numeric format
+specifiers, if the corresponding argument starts with a quote character,
+the numeric value of the following character is used as the number to
+print otherwise the argument is evaluated as an arithmetic expression\&. See
+the section `Arithmetic Evaluation' for a description of arithmetic
+expressions\&. With `\fB%n\fP', the corresponding argument is taken as an
+identifier which is created as an integer parameter\&.
+.RS
+.PP
+Normally, conversion specifications are applied to each argument in order
+but they can explicitly specify the \fIn\fPth argument is to be used by
+replacing `\fB%\fP' by `\fB%\fP\fIn\fP\fB$\fP' and `\fB*\fP' by `\fB*\fP\fIn\fP\fB$\fP'\&.
+It is recommended that you do not mix references of this explicit style
+with the normal style and the handling of such mixed styles may be subject
+to future change\&.
+.PP
+If arguments remain unused after formatting, the format string is reused
+until all arguments have been consumed\&. With the \fBprint\fP builtin, this
+can be suppressed by using the \fB\-r\fP option\&. If more arguments are
+required by the format than have been specified, the behaviour is as if
+zero or an empty string had been specified as the argument\&.
+.RE
+.TP
+.PD 0
+\fBpushd\fP [ \fB\-sLP\fP ] [ \fIarg\fP ]
+.TP
+.PD 0
+\fBpushd\fP [ \fB\-sLP\fP ] \fIold\fP \fInew\fP
+.TP
+.PD
+\fBpushd\fP [ \fB\-sLP\fP ] {\fB+\fP|\fB\-\fP}\fIn\fP
+Change the current directory, and push the old current directory
+onto the directory stack\&.  In the first form, change the
+current directory to \fIarg\fP\&.
+If \fIarg\fP is not specified, change to the second directory
+on the stack (that is, exchange the top two entries), or
+change to \fB$HOME\fP if the \fBPUSHD_TO_HOME\fP
+option is set or if there is only one entry on the stack\&.
+Otherwise, \fIarg\fP is interpreted as it would be by \fBcd\fP\&.
+The meaning of \fIold\fP and \fInew\fP in the second form is also
+the same as for \fBcd\fP\&.
+.RS
+.PP
+The third form of \fBpushd\fP changes directory by rotating the
+directory list\&.  An argument of the form `\fB+\fP\fIn\fP' identifies a stack
+entry by counting from the left of the list shown by the \fBdirs\fP
+command, starting with zero\&.  An argument of the form `\fB\-\fP\fIn\fP' counts
+from the right\&.  If the \fBPUSHD_MINUS\fP option is set, the meanings
+of `\fB+\fP' and `\fB\-\fP' in this context are swapped\&.
+.PP
+If the option \fBPUSHD_SILENT\fP is not set, the directory
+stack will be printed after a \fBpushd\fP is performed\&.
+.PP
+The options \fB\-s\fP, \fB\-L\fP and \fB\-P\fP have the same meanings as for the
+\fBcd\fP builtin\&.
+.RE
+.TP
+\fBpushln\fP [ \fIarg\fP \&.\&.\&. ]
+Equivalent to \fBprint \-nz\fP\&.
+.TP
+\fBpwd\fP [ \fB\-rLP\fP ]
+Print the absolute pathname of the current working directory\&.
+If the \fB\-r\fP or the \fB\-P\fP flag is specified, or the \fBCHASE_LINKS\fP
+option is set and the \fB\-L\fP flag is not given, the printed path will not
+contain symbolic links\&.
+.TP
+\fBr\fP
+Same as \fBfc \-e \-\fP\&.
+.TP
+.PD 0
+\fBread\fP [ \fB\-rszpqAclneE\fP ] [ \fB\-t\fP [ \fInum\fP ] ] [ \fB\-k\fP [ \fInum\fP ] ] [ \fB\-d\fP \fIdelim\fP ]
+.TP
+.PD
+ [ \fB\-u\fP \fIn\fP ] [ \fIname\fP[\fB?\fP\fIprompt\fP] ] [ \fIname\fP \&.\&.\&.  ]
+Read one line and break it into fields using the characters
+in \fB$IFS\fP as separators, except as noted below\&.
+The first field is assigned to the first \fIname\fP, the second field
+to the second \fIname\fP, etc\&., with leftover
+fields assigned to the last \fIname\fP\&.
+If \fIname\fP is omitted then
+\fBREPLY\fP is used for scalars and \fBreply\fP for arrays\&.
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fB\-r\fP
+Raw mode: a `\fB\e\fP' at the end of a line does not signify line
+continuation and backslashes in the line don't quote the following
+character and are not removed\&.
+.TP
+\fB\-s\fP
+Don't echo back characters if reading from the terminal\&.  Currently does
+not work with the \fB\-q\fP option\&.
+.TP
+\fB\-q\fP
+Read only one character from the terminal and set \fIname\fP to
+`\fBy\fP' if this character was `\fBy\fP' or `\fBY\fP' and to `\fBn\fP' otherwise\&.
+With this flag set the return value is zero only if the character was
+`\fBy\fP' or `\fBY\fP'\&.  Note that this always reads from the terminal, even
+if used with the \fB\-p\fP or \fB\-u\fP or \fB\-z\fP flags or with redirected input\&.
+This option may also be used within zle widgets\&.
+.TP
+\fB\-k\fP [ \fInum\fP ]
+Read only one (or \fInum\fP) characters\&.  All are assigned to the first
+\fIname\fP, without word splitting\&.  This flag is ignored when \fB\-q\fP is
+present\&.  Input is read from the terminal unless one of \fB\-u\fP or \fB\-p\fP
+is present\&.  This option may also be used within zle widgets\&.
+.TP
+\fB\-z\fP
+Read one entry from the editor buffer stack and assign it to the first
+\fIname\fP, without word splitting\&.  Text is pushed onto the stack with
+`\fBprint \-z\fP' or with \fBpush\-line\fP from the line editor (see
+\fIzshzle\fP(1))\&.  This flag is ignored when the \fB\-k\fP or \fB\-q\fP flags are present\&.
+.TP
+.PD 0
+\fB\-e\fP
+.TP
+.PD
+\fB\-E\fP
+The input read is printed (echoed) to the standard output\&.  If the \fB\-e\fP
+flag is used, no input is assigned to the parameters\&.
+.TP
+\fB\-A\fP
+The first \fIname\fP is taken as the name of an array and all words are
+assigned to it\&.
+.TP
+.PD 0
+\fB\-c\fP
+.TP
+.PD
+\fB\-l\fP
+These flags are allowed only if called inside a
+function used for completion (specified with the \fB\-K\fP flag to
+\fBcompctl\fP)\&.  If the \fB\-c\fP flag is given, the words of the
+current command are read\&. If the \fB\-l\fP flag is given, the whole
+line is assigned as a scalar\&.  If both flags are present, \fB\-l\fP
+is used and \fB\-c\fP is ignored\&.
+.TP
+\fB\-n\fP
+Together with \fB\-c\fP, the number of the word the cursor is on is
+read\&.  With \fB\-l\fP, the index of the character the cursor is on is
+read\&.  Note that the command name is word number 1, not word 0,
+and that when the cursor is at the end of the line, its character
+index is the length of the line plus one\&.
+.TP
+\fB\-u\fP \fIn\fP
+Input is read from file descriptor \fIn\fP\&.
+.TP
+\fB\-p\fP
+Input is read from the coprocess\&.
+.TP
+\fB\-d\fP \fIdelim\fP
+Input is terminated by the first character of \fIdelim\fP instead of
+by newline\&.
+.TP
+\fB\-t\fP [ \fInum\fP ]
+Test if input is available before attempting to read\&.  If \fInum\fP
+is present, it must begin with a digit and will be evaluated
+to give a number of seconds, which may be a floating point number;
+in this case the read times out if input is not available within this
+time\&.  If \fInum\fP is not present, it is taken to be zero, so that
+\fBread\fP returns immediately if no input is available\&.
+If no input is available, return status 1 and do not set any variables\&.
+ 
+This option is not available when reading from the editor buffer with
+\fB\-z\fP, when called from within completion with \fB\-c\fP or \fB\-l\fP, with
+\fB\-q\fP which clears the input queue before reading, or within zle where
+other mechanisms should be used to test for input\&.
+ 
+Note that read does not attempt to alter the input processing mode\&.  The
+default mode is canonical input, in which an entire line is read at a time,
+so usually `\fBread \-t\fP' will not read anything until an entire line has
+been typed\&.  However, when reading from the terminal with \fB\-k\fP
+input is processed one key at a time; in this case, only availability of
+the first character is tested, so that e\&.g\&. `\fBread \-t \-k 2\fP' can still
+block on the second character\&.  Use two instances of `\fBread \-t \-k\fP' if
+this is not what is wanted\&.
+If the first argument contains a `\fB?\fP', the remainder of this
+word is used as a \fIprompt\fP on standard error when the shell
+is interactive\&.
+.PP
+The value (exit status) of \fBread\fP is 1 when an end\-of\-file is
+encountered, or when \fB\-c\fP or \fB\-l\fP is present and the command is
+not called from a \fBcompctl\fP function, or as described for \fB\-q\fP\&.
+Otherwise the value is 0\&.
+.PP
+The behavior of some combinations of the \fB\-k\fP, \fB\-p\fP, \fB\-q\fP, \fB\-u\fP
+and \fB\-z\fP flags is undefined\&.  Presently \fB\-q\fP cancels all the others,
+\fB\-p\fP cancels \fB\-u\fP, \fB\-k\fP cancels \fB\-z\fP, and otherwise \fB\-z\fP
+cancels both \fB\-p\fP and \fB\-u\fP\&.
+.PP
+The \fB\-c\fP or \fB\-l\fP flags cancel any and all of \fB\-kpquz\fP\&.
+.RE
+.TP
+\fBreadonly\fP
+Same as \fBtypeset \-r\fP\&.
+.TP
+\fBrehash\fP
+Same as \fBhash \-r\fP\&.
+.TP
+\fBreturn\fP [ \fIn\fP ]
+Causes a shell function or \fB\&.\fP script to return to
+the invoking script with the return status specified by \fIn\fP\&.  If \fIn\fP
+is omitted, the return status is that of the last command
+executed\&.
+.RS
+.PP
+If \fBreturn\fP was executed from a trap in a \fBTRAP\fP\fINAL\fP function,
+the effect is different for zero and non\-zero return status\&.  With zero
+status (or after an implicit return at the end of the trap), the shell
+will return to whatever it was previously processing; with a non\-zero
+status, the shell will behave as interrupted except that the return
+status of the trap is retained\&.  Note that the numeric value of the signal
+which caused the trap is passed as the first argument, so the statement
+`\fBreturn $((128+$1))\fP' will return the same status as if the signal
+had not been trapped\&.
+.RE
+.TP
+\fBsched\fP
+See the section `The zsh/sched Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBset\fP [ {\fB+\fP|\fB\-\fP}\fIoptions\fP | {\fB+\fP|\fB\-\fP}\fBo\fP [ \fIoption_name\fP ] ] \&.\&.\&. [ {\fB+\fP|\fB\-\fP}\fBA\fP [ \fIname\fP ] ] [ \fIarg\fP \&.\&.\&. ]
+Set the options for the shell and/or set the positional parameters, or
+declare and set an array\&.  If the \fB\-s\fP option is given, it causes the
+specified arguments to be sorted before assigning them to the positional
+parameters (or to the array \fIname\fP if \fB\-A\fP is used)\&.  With \fB+s\fP
+sort arguments in descending order\&.  For the meaning of the other flags, see
+\fIzshoptions\fP(1)\&.  Flags may be specified by name using the \fB\-o\fP option\&. If no option
+name is supplied with \fB\-o\fP, the current option states are printed\&.
+With \fB+o\fP they are printed in a form that can be used as input
+to the shell\&.
+.RS
+.PP
+If the \fB\-A\fP flag is specified, \fIname\fP is set to an array containing
+the given \fIarg\fPs; if no \fIname\fP is specified, all arrays are printed
+together with their values\&.
+.PP
+If \fB+A\fP is used and \fIname\fP is an array, the
+given arguments will replace the initial elements of that array; if no
+\fIname\fP is specified, all arrays are printed without their values\&.
+.PP
+The behaviour of arguments after \fB\-A\fP \fIname\fP or \fB+A\fP \fIname\fP
+depends on whether the option \fBKSH_ARRAYS\fP is set\&.  If it is not set, all
+arguments following \fIname\fP are treated as values for the array,
+regardless of their form\&.  If the option is set, normal option processing
+continues at that point; only regular arguments are treated as values for
+the array\&.  This means that
+.PP
+.RS
+.nf
+\fBset \-A array \-x \-\- foo\fP
+.fi
+.RE
+.PP
+sets \fBarray\fP to `\fB\-x \-\- foo\fP' if \fBKSH_ARRAYS\fP is not set, but sets
+the array to \fBfoo\fP and turns on the option `\fB\-x\fP' if it is set\&.
+.PP
+If the \fB\-A\fP flag is not present, but there are arguments beyond the
+options, the positional parameters are set\&.  If the option list (if any)
+is terminated by `\fB\-\fP\fB\-\fP', and there are no further arguments, the
+positional parameters will be unset\&.
+.PP
+If no arguments and no `\fB\-\fP\fB\-\fP' are given, then the names and values of
+all parameters are printed on the standard output\&.  If the only argument is
+`\fB+\fP', the names of all parameters are printed\&.
+.RE
+.TP
+\fBsetcap\fP
+See the section `The zsh/cap Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBsetopt\fP [ {\fB+\fP|\fB\-\fP}\fIoptions\fP | {\fB+\fP|\fB\-\fP}\fBo\fP \fIoption_name\fP ] [ \fIname\fP \&.\&.\&. ]
+Set the options for the shell\&.  All options specified either
+with flags or by name are set\&.  If no arguments are supplied,
+the names of all options currently set are printed\&.
+If the \fB\-m\fP flag is given the arguments are taken as patterns
+(which should be quoted to protect them from filename expansion), and all
+options with names matching these patterns are set\&.
+.TP
+\fBshift\fP [ \fIn\fP ] [ \fIname\fP \&.\&.\&. ]
+The positional parameters \fB${\fP\fIn\fP+1\fB}\fP \&.\&.\&. are renamed
+to \fB$1\fP \&.\&.\&., where \fIn\fP is an arithmetic expression that
+defaults to 1\&.
+If any \fIname\fPs are given then the arrays with these names are
+shifted instead of the positional parameters\&.
+.TP
+\fBsource\fP \fIfile\fP [ \fIarg\fP \&.\&.\&. ]
+Same as \fB\&.\fP, except that the current directory is always searched and
+is always searched first, before directories in \fB$path\fP\&.
+.TP
+\fBstat\fP
+See the section `The zsh/stat Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBsuspend\fP [ \fB\-f\fP ]
+Suspend the execution of the shell (send it a \fBSIGTSTP\fP)
+until it receives a \fBSIGCONT\fP\&.
+Unless the \fB\-f\fP option is given, this will refuse to suspend a login shell\&.
+.TP
+.PD 0
+\fBtest\fP [ \fIarg\fP \&.\&.\&. ]
+.TP
+.PD
+\fB[\fP [ \fIarg\fP \&.\&.\&. ] \fB]\fP
+Like the system version of \fBtest\fP\&.  Added for compatibility;
+use conditional expressions instead (see the section `Conditional Expressions')\&.
+The main differences between the conditional expression syntax and the
+\fBtest\fP and \fB[\fP builtins are:  these commands are not handled
+syntactically, so for example an empty variable expansion may cause an
+argument to be omitted; syntax errors cause status 2 to be returned instead
+of a shell error; and arithmetic operators expect integer arguments rather
+than arithemetic expressions\&.
+.TP
+\fBtimes\fP
+Print the accumulated user and system times for the shell
+and for processes run from the shell\&.
+.TP
+\fBtrap\fP [ \fIarg\fP [ \fIsig\fP \&.\&.\&. ] ]
+\fIarg\fP is a series of commands (usually quoted to protect it from
+immediate evaluation by the shell) to be read and executed when the shell
+receives \fIsig\fP\&.  Each \fIsig\fP can be given as a number
+or as the name of a signal\&.
+If \fIarg\fP is `\fB\-\fP', then all traps \fIsig\fP are reset to their
+default values\&.  If \fIarg\fP is the empty string, then this signal
+is ignored by the shell and by the commands it invokes\&.
+.RS
+.PP
+If \fIsig\fP is \fBZERR\fP then \fIarg\fP will be executed
+after each command with a nonzero exit status\&.
+If \fIsig\fP is \fBDEBUG\fP then \fIarg\fP will be executed
+after each command\&.
+If \fIsig\fP is \fB0\fP or \fBEXIT\fP
+and the \fBtrap\fP statement is executed inside the body of a function,
+then the command \fIarg\fP is executed after the function completes\&.
+If \fIsig\fP is \fB0\fP or \fBEXIT\fP
+and the \fBtrap\fP statement is not executed inside the body of a function,
+then the command \fIarg\fP is executed when the shell terminates\&.
+.PP
+\fBZERR\fP, \fBDEBUG\fP and \fBEXIT\fP traps are not executed inside other traps\&.
+.PP
+The \fBtrap\fP command with no arguments prints a list of commands
+associated with each signal\&.
+.PP
+Note that traps defined with the \fBtrap\fP builtin are slightly different
+from those defined as `\fBTRAP\fP\fINAL\fP () { \&.\&.\&. }', as the latter have
+their own function environment (line numbers, local variables, etc\&.) while
+the former use the environment of the command in which they were called\&.
+For example,
+.PP
+.RS
+.nf
+\fBtrap 'print $LINENO' DEBUG\fP
+.fi
+.RE
+.PP
+will print the line number of a command executed after it has run, while
+.PP
+.RS
+.nf
+\fBTRAPDEBUG() { print $LINENO; }\fP
+.fi
+.RE
+.PP
+will always print the number zero\&.
+.RE
+.TP
+\fBtrue\fP [ \fIarg\fP \&.\&.\&. ]
+Do nothing and return an exit code of 0\&.
+.TP
+\fBttyctl\fP \fB\-fu\fP
+The \fB\-f\fP option freezes the tty, and \fB\-u\fP unfreezes it\&.
+When the tty is frozen, no changes made to the tty settings by
+external programs will be honored by the shell, except for changes in the
+size of the screen; the shell will
+simply reset the settings to their previous values as soon as each
+command exits or is suspended\&.  Thus, \fBstty\fP and similar programs have
+no effect when the tty is frozen\&.  Without options it reports whether the
+terminal is frozen or not\&.
+.TP
+\fBtype\fP [ \fB\-wfpams\fP ] \fIname\fP \&.\&.\&.
+Equivalent to \fBwhence \-v\fP\&.
+.TP
+.PD 0
+\fBtypeset\fP [ {\fB+\fP|\fB\-\fP}\fBAEFHLRUZafghiklprtuxmz\fP [\fIn\fP]] [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ]
+.TP
+.PD
+\fBtypeset\fP \-T [ {\fB+|\fB\-\fP\fP}\fBLRUZrux\fP ] \fISCALAR\fP[\fB=\fP\fIvalue\fP] \fIarray\fP \fB[\fP \fIsep\fP \fB]\fP
+Set or display attributes and values for shell parameters\&.
+.RS
+.PP
+A parameter is created for each \fIname\fP that does not already refer
+to one\&.  When inside a function, a new parameter is created for every
+\fIname\fP (even those that already exist), and is unset again when the
+function completes\&.  See
+`Local Parameters' in \fIzshparam\fP(1)\&.  The same rules apply to special shell parameters, which
+retain their special attributes when made local\&.
+.PP
+For each \fIname\fP\fB=\fP\fIvalue\fP assignment, the parameter
+\fIname\fP is set to \fIvalue\fP\&.  Note that arrays currently cannot be
+assigned in \fBtypeset\fP expressions, only scalars and integers\&.
+.PP
+If the shell option \fBTYPESET_SILENT\fP is not set, for each remaining
+\fIname\fP that refers to a parameter that is set, the name and value of the
+parameter are printed in the form of an assignment\&.  Nothing is printed for
+newly\-created parameters, or when any attribute flags listed below are
+given along with the \fIname\fP\&.  Using `\fB+\fP' instead of minus to
+introduce an attribute turns it off\&.
+.PP
+If the \fB\-p\fP option is given, parameters and values are printed in the
+form of a typeset comand and an assignment (which will be printed
+separately for arrays and associative arrays), regardless of other flags
+and options\&.  Note that the \fB\-h\fP flag on parameters is respected; no
+value will be shown for these parameters\&.
+.PP
+If the \fB\-T\fP option is given, two or three arguments must be present (an
+exception is that zero arguments are allowed to show the list of parameters
+created in this fashion)\&.  The first two are the name of a scalar and an
+array parameter (in that order) that will be tied together in the manner of
+\fB$PATH\fP and \fB$path\fP\&.  The optional third argument is a single\-character
+separator which will be used to join the elements of the array to form the
+scalar; if absent, a colon is used, as with \fB$PATH\fP\&.  Only the first
+character of the separator is significant; any remaining characters are
+ignored\&.  Only the scalar parameter may be assigned an initial value\&.  Both
+the scalar and the array may otherwise be manipulated as normal\&.  If one is
+unset, the other will automatically be unset too\&.  There is no way of
+untying the variables without unsetting them, or converting the type of one
+of them with another \fBtypeset\fP command; \fB+T\fP does not work, assigning
+an array to \fISCALAR\fP is an error, and assigning a scalar to \fIarray\fP
+sets it to be a single\-element array\&.  Note that both `\fBtypeset \-xT \&.\&.\&.\fP'
+and `\fBexport \-T \&.\&.\&.\fP' work, but only the scalar will be marked for
+export\&.  Setting the value using the scalar version causes a split on all
+separators (which cannot be quoted)\&.
+.PP
+The \fB\-g\fP (global) flag is treated specially: it means that any
+resulting parameter will not be restricted to local scope\&.  Note that this
+does not necessarily mean that the parameter will be global, as the flag
+will apply to any existing parameter (even if unset) from an enclosing
+function\&.  This flag does not affect the parameter after creation, hence it
+has no effect when listing existing parameters, nor does the flag \fB+g\fP
+have any effect except in combination with \fB\-m\fP (see below)\&.
+.PP
+If no \fIname\fP is present, the names and values of all parameters are
+printed\&.  In this case the attribute flags restrict the display to only
+those parameters that have the specified attributes, and using `\fB+\fP'
+rather than `\fB\-\fP' to introduce the flag suppresses printing of the values
+of parameters when there is no parameter name\&.  Also, if the last option
+is the word `\fB+\fP', then names are printed but values are not\&.
+.PP
+If the \fB\-m\fP flag is given the \fIname\fP arguments are taken as patterns
+(which should be quoted)\&.  With no attribute flags, all parameters (or
+functions with the \fB\-f\fP flag) with matching names are printed (the shell
+option \fBTYPESET_SILENT\fP is not used in this case)\&.  Note that \fB\-m\fP is
+ignored if no patterns are given\&.  If the \fB+g\fP flag is combined with
+\fB\-m\fP, a new local parameter is created for every matching parameter that
+is not already local\&.  Otherwise \fB\-m\fP applies all other flags or
+assignments to the existing parameters\&.  Except when assignments are made
+with \fIname\fP\fB=\fP\fIvalue\fP, using \fB+m\fP forces the matching parameters
+to be printed, even inside a function\&.
+.PP
+If no attribute flags are given and either no \fB\-m\fP flag is present or
+the \fB+m\fP form was used, each parameter name printed is preceded by a
+list of the attributes of that parameter (\fBarray\fP, \fBassociation\fP,
+\fBexported\fP, \fBinteger\fP, \fBreadonly\fP)\&.  If \fB+m\fP is used with attribute
+flags, and all those flags are introduced with \fB+\fP, the matching
+parameter names are printed but their values are not\&.
+.PP
+The following attribute flags may be specified:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-A\fP
+The names refer to associative array parameters; see
+`Array Parameters' in \fIzshparam\fP(1)\&.
+.TP
+\fB\-L\fP
+Left justify and remove leading blanks from \fIvalue\fP\&.
+If \fIn\fP is nonzero, it defines the width of the field;
+otherwise it is determined by the width of the value of the first
+assignment\&.
+When the parameter is expanded, it is filled on the right with
+blanks or truncated if necessary to fit the field\&.
+Leading zeros are removed if the \fB\-Z\fP flag is also set\&.
+.TP
+\fB\-R\fP
+Right justify and fill with leading blanks\&.  If \fIn\fP is nonzero
+if defines the width of the field;
+otherwise it is determined by the width of the value of the first
+assignment\&.
+When the parameter is expanded, the field is left filled with
+blanks or truncated from the end\&.
+.TP
+\fB\-U\fP
+For arrays (but not for associative arrays), keep only the first
+occurrence of each duplicated value\&.  This may also be set for
+colon\-separated special parameters like \fBPATH\fP or \fBFIGNORE\fP, etc\&.
+This flag has a different meaning when used with \fB\-f\fP; see below\&.
+.TP
+\fB\-Z\fP
+Right justify and fill with leading zeros if the first non\-blank
+character is a digit and the \fB\-L\fP flag has not been set\&.
+If \fIn\fP is nonzero it defines the width of the field;
+otherwise it is determined by the width of the value of the
+first assignment\&.
+.TP
+\fB\-a\fP
+The names refer to array parameters\&.  An array parameter may be
+created this way, but it may not be assigned to in the \fBtypeset\fP
+statement\&.  When displaying, both normal and associative arrays are
+shown\&.
+.TP
+\fB\-f\fP
+The names refer to functions rather than parameters\&.  No assignments
+can be made, and the only other valid flags are \fB\-t\fP, \fB\-k\fP, \fB\-u\fP,
+\fB\-U\fP and \fB\-z\fP\&.  The flag \fB\-t\fP turns on execution tracing for this
+function\&.  The \fB\-u\fP and \fB\-U\fP flags cause the function to be
+marked for autoloading; \fB\-U\fP also causes alias expansion to be
+suppressed when the function is loaded\&.  The \fBfpath\fP parameter
+will be searched to find the function definition when the function
+is first referenced; see the section `Functions'\&. The \fB\-k\fP and \fB\-z\fP flags
+make the function be loaded using ksh\-style or zsh\-style autoloading
+respectively\&. If neither is given, the setting of the KSH_AUTOLOAD option
+determines how the function is loaded\&.
+.TP
+\fB\-h\fP
+Hide: only useful for special parameters (those marked `<S>' in the table in
+\fIzshparams\fP(1)), and for local parameters with the same name as a special parameter,
+though harmless for others\&.  A special parameter with this attribute will
+not retain its special effect when made local\&.  Thus after `\fBtypeset \-h
+PATH\fP', a function containing `\fBtypeset PATH\fP' will create an ordinary
+local parameter without the usual behaviour of \fBPATH\fP\&.  Alternatively,
+the local parameter may itself be given this attribute; hence inside a
+function `\fBtypeset \-h PATH\fP' creates an ordinary local parameter and the
+special \fBPATH\fP parameter is not altered in any way\&.  It is also possible
+to create a local parameter using `\fBtypeset +h \fP\fIspecial\fP', where the
+local copy of \fIspecial\fP will retain its special properties regardless of
+having the \fB\-h\fP attribute\&.  Global special parameters loaded from shell
+modules (currently those in \fBzsh/mapfile\fP and \fBzsh/parameter\fP) are
+automatically given the \fB\-h\fP attribute to avoid name clashes\&.
+.TP
+\fB\-H\fP
+Hide value: specifies that \fBtypeset\fP will not display the value of the
+parameter when listing parameters; the display for such parameters is
+always as if the `\fB+\fP' flag had been given\&.  Use of the parameter is
+in other respects normal, and the option does not apply if the parameter is
+specified by name, or by pattern with the \fB\-m\fP option\&.  This is on by
+default for the parameters in the \fBzsh/parameter\fP and \fBzsh/mapfile\fP
+modules\&.  Note, however, that unlike the \fB\-h\fP flag this is also useful
+for non\-special parameters\&.
+.TP
+\fB\-i\fP
+Use an internal integer representation\&.  If \fIn\fP is nonzero it
+defines the output arithmetic base, otherwise it is determined by the
+first assignment\&.
+.TP
+\fB\-E\fP
+Use an internal double\-precision floating point representation\&.  On output
+the variable will be converted to scientific notation\&.  If \fIn\fP is
+nonzero it defines the number of significant figures to display; the
+default is ten\&.
+.TP
+\fB\-F\fP
+Use an internal double\-precision floating point representation\&.  On output
+the variable will be converted to fixed\-point decimal notation\&.  If \fIn\fP
+is nonzero it defines the number of digits to display after the decimal
+point; the default is ten\&.
+.TP
+\fB\-l\fP
+Convert the result to lower case whenever the parameter is expanded\&.
+The value is \fInot\fP converted when assigned\&.
+.TP
+\fB\-r\fP
+The given \fIname\fPs are marked readonly\&.  Note that if \fIname\fP is a
+special parameter, the readonly attribute can be turned on, but cannot then
+be turned off\&.
+.TP
+\fB\-t\fP
+Tags the named parameters\&.  Tags have no special meaning to the shell\&.
+This flag has a different meaning when used with \fB\-f\fP; see above\&.
+.TP
+\fB\-u\fP
+Convert the result to upper case whenever the parameter is expanded\&.
+The value is \fInot\fP converted when assigned\&.
+This flag has a different meaning when used with \fB\-f\fP; see above\&.
+.TP
+\fB\-x\fP
+Mark for automatic export to the environment of subsequently
+executed commands\&.  If the option \fBGLOBAL_EXPORT\fP is set, this implies
+the option \fB\-g\fP, unless \fB+g\fP is also explicitly given; in other words
+the parameter is not made local to the enclosing function\&.  This is for
+compatibility with previous versions of zsh\&.
+.RE
+.TP
+\fBulimit\fP [ [ \fB\-SHacdflmnpstv\fP | \fB\-N\fP \fIresource\fP [ \fIlimit\fP ] \&.\&.\&. ]
+Set or display resource limits of the shell and the processes started by
+the shell\&.  The value of \fIlimit\fP can be a number in the unit specified
+below or the value `\fBunlimited\fP'\&.  By default, only soft limits are
+manipulated\&. If the \fB\-H\fP flag is given use
+hard limits instead of soft limits\&.  If the \fB\-S\fP flag is given
+together with the \fB\-H\fP flag set both hard and soft limits\&.  If no
+options are used, the file size limit (\fB\-f\fP) is assumed\&.  If
+\fIlimit\fP is omitted the current value of the specified resources are
+printed\&.  When more than one resource values are printed the limit name and
+unit is printed before each value\&.
+.RS
+.PP
+When looping over multiple resources, the shell will abort immediately if
+it detects a badly formed argument\&.  However, if it fails to set a limit
+for some other reson it will continue trying to set the remaining limits\&.
+.PP
+.PD 0
+.TP
+\fB\-a\fP
+Lists all of the current resource limits\&.
+.TP
+\fB\-c\fP
+512\-byte blocks on the size of core dumps\&.
+.TP
+\fB\-d\fP
+K\-bytes on the size of the data segment\&.
+.TP
+\fB\-f\fP
+512\-byte blocks on the size of files written\&.
+.TP
+\fB\-l\fP
+K\-bytes on the size of locked\-in memory\&.
+.TP
+\fB\-m\fP
+K\-bytes on the size of physical memory\&.
+.TP
+\fB\-n\fP
+open file descriptors\&.
+.TP
+\fB\-s\fP
+K\-bytes on the size of the stack\&.
+.TP
+\fB\-t\fP
+CPU seconds to be used\&.
+.TP
+\fB\-u\fP
+processes available to the user\&.
+.TP
+\fB\-v\fP
+K\-bytes on the size of virtual memory\&.  On some systems this
+refers to the limit called `address space'\&.
+.PD
+.PP
+A resource may also be specified by integer in the form `\fB\-N\fP
+\fIresource\fP', where \fIresource\fP corresponds to the integer defined for
+the resource by the operating system\&.  This may be used to set the limits
+for resources known to the shell which do not correspond to option letters\&.
+Such limits will be shown by number in the output of `\fBulimit \-a\fP'\&.
+.PP
+The number may alternatively be out of the range of limits compiled into
+the shell\&.  The shell will try to read or write the limit anyway, and
+will report an error if this fails\&.
+.RE
+.TP
+\fBumask\fP [ \fB\-S\fP ] [ \fImask\fP ]
+The umask is set to \fImask\fP\&.  \fImask\fP can be either
+an octal number or a symbolic value as described in \fIchmod\fP(1)\&.
+If \fImask\fP is omitted, the current value is printed\&.  The \fB\-S\fP
+option causes the mask to be printed as a symbolic value\&.  Otherwise,
+the mask is printed as an octal number\&.  Note that in
+the symbolic form the permissions you specify are those which are to be
+allowed (not denied) to the users specified\&.
+.TP
+\fBunalias\fP
+Same as \fBunhash \-a\fP\&.
+.TP
+\fBunfunction\fP
+Same as \fBunhash \-f\fP\&.
+.TP
+\fBunhash\fP [ \fB\-adfms\fP ] \fIname\fP \&.\&.\&.
+Remove the element named \fIname\fP from an internal hash table\&.  The
+default is remove elements from the command hash table\&.  The \fB\-a\fP
+option causes \fBunhash\fP to remove regular or global aliases\&.
+The \fB\-s\fP option causes \fBunhash\fP to remove suffix aliases\&.
+The \fB\-f\fP option causes
+\fBunhash\fP to remove shell functions\&.  The \fB\-d\fP options causes
+\fBunhash\fP to remove named directories\&.  If the \fB\-m\fP flag is given
+the arguments are taken as patterns (should be quoted) and all elements
+of the corresponding hash table with matching names will be removed\&.
+.TP
+\fBunlimit\fP [ \fB\-hs\fP ] \fIresource\fP \&.\&.\&.
+The resource limit for each \fIresource\fP is set to the hard limit\&.
+If the \fB\-h\fP flag is given and the shell has appropriate privileges,
+the hard resource limit for each \fIresource\fP is removed\&.
+The resources of the shell process are only changed if the \fB\-s\fP
+flag is given\&.
+.TP
+\fBunset\fP [ \fB\-fmv\fP ] \fIname\fP \&.\&.\&.
+Each named parameter is unset\&.
+Local parameters remain local even if unset; they appear unset within scope,
+but the previous value will still reappear when the scope ends\&.
+.RS
+.PP
+Individual elements of associative array parameters may be unset by using
+subscript syntax on \fIname\fP, which should be quoted (or the entire command
+prefixed with \fBnoglob\fP) to protect the subscript from filename generation\&.
+.PP
+If the \fB\-m\fP flag is specified the arguments are taken as patterns (should
+be quoted) and all parameters with matching names are unset\&.  Note that this
+cannot be used when unsetting associative array elements, as the subscript
+will be treated as part of the pattern\&.
+.PP
+The \fB\-v\fP flag specifies that \fIname\fP refers to parameters\&. This is the
+default behaviour\&.
+.PP
+\fBunset \-f\fP is equivalent to \fBunfunction\fP\&.
+.RE
+.TP
+\fBunsetopt\fP [ {\fB+\fP|\fB\-\fP}\fIoptions\fP | {\fB+\fP|\fB\-\fP}\fBo\fP \fIoption_name\fP ] [ \fIname\fP \&.\&.\&. ]
+Unset the options for the shell\&.  All options specified either
+with flags or by name are unset\&.  If no arguments are supplied,
+the names of all options currently unset are printed\&.
+If the \fB\-m\fP flag is given the arguments are taken as patterns
+(which should be quoted to preserve them from being interpreted as glob
+patterns), and all options with names matching these patterns are unset\&.
+.TP
+\fBvared\fP
+See the section `Zle Builtins' in \fIzshzle\fP(1)\&.
+.TP
+\fBwait\fP [ \fIjob\fP \&.\&.\&. ]
+Wait for the specified jobs or processes\&.  If \fIjob\fP is not given
+then all currently active child processes are waited for\&.
+Each \fIjob\fP can be either a job specification or the process ID
+of a job in the job table\&.
+The exit status from this command is that of the job waited for\&.
+.TP
+\fBwhence\fP [ \fB\-vcwfpams\fP ] \fIname\fP \&.\&.\&.
+For each name, indicate how it would be interpreted if used as a
+command name\&.
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fB\-v\fP
+Produce a more verbose report\&.
+.TP
+\fB\-c\fP
+Print the results in a \fBcsh\fP\-like format\&.
+This takes precedence over \fB\-v\fP\&.
+.TP
+\fB\-w\fP
+For each \fIname\fP, print `\fIname\fP\fB:\fP \fIword\fP' where \fIword\fP
+is one of \fBalias\fP, \fBbuiltin\fP, \fBcommand\fP, \fBfunction\fP,
+\fBhashed\fP, \fBreserved\fP or \fBnone\fP, according as \fIname\fP
+corresponds to an alias, a built\-in command, an external command, a
+shell function, a command defined with the \fBhash\fP builtin, a
+reserved word, or is not recognised\&.  This takes precedence over
+\fB\-v\fP and \fB\-c\fP\&.
+.TP
+\fB\-f\fP
+Causes the contents of a shell function to be
+displayed, which would otherwise not happen unless the \fB\-c\fP
+flag were used\&.
+.TP
+\fB\-p\fP
+Do a path search for \fIname\fP
+even if it is an alias, reserved word, shell function or builtin\&.
+.TP
+\fB\-a\fP
+Do a search for all occurrences of \fIname\fP
+throughout the command path\&.
+Normally only the first occurrence is printed\&.
+.TP
+\fB\-m\fP
+The arguments are taken as patterns (should be
+quoted), and the information is displayed for each command matching one
+of these patterns\&.
+.TP
+\fB\-s\fP
+If a pathname contains symlinks, print the symlink\-free pathname as well\&.
+.RE
+.TP
+\fBwhere\fP [ \fB\-wpms\fP ] \fIname\fP \&.\&.\&.
+Equivalent to \fBwhence \-ca\fP\&.
+.TP
+\fBwhich\fP [ \fB\-wpams\fP ] \fIname\fP \&.\&.\&.
+Equivalent to \fBwhence \-c\fP\&.
+.TP
+.PD 0
+\fBzcompile\fP [ \fB\-U\fP ] [ \fB\-z\fP | \fB\-k\fP ] [ \fB\-R\fP | \fB\-M\fP ] \fIfile\fP [ \fIname\fP \&.\&.\&. ]
+.TP
+.PD 0
+\fBzcompile\fP \fB\-ca\fP [ \fB\-m\fP ] [ \fB\-R\fP | \fB\-M\fP ] \fIfile\fP [ \fIname\fP \&.\&.\&. ]
+.TP
+.PD
+\fBzcompile \-t\fP \fIfile\fP [ \fIname\fP \&.\&.\&. ]
+This builtin command can be used to compile functions or scripts,
+storing the compiled form in a file, and to examine files containing
+the compiled form\&.  This allows faster autoloading of functions and
+execution of scripts by avoiding parsing of the text when the files
+are read\&.
+.RS
+.PP
+The first form (without the \fB\-c\fP, \fB\-a\fP or \fB\-t\fP options) creates a
+compiled file\&.  If only the \fIfile\fP argument is given, the
+output file has the name `\fIfile\fP\fB\&.zwc\fP' and will be placed in
+the same directory as the \fIfile\fP\&.  The shell will load the compiled
+file instead of the normal function file when the function
+is autoloaded; see
+the section `Autoloading Functions' in \fIzshfunc\fP(1)
+for a description of how autoloaded functions are searched\&.  The
+extension \fB\&.zwc\fP stands for `zsh word code'\&.
+.PP
+If there is at least one \fIname\fP argument, all the named files
+are compiled into the output \fIfile\fP given as the first argument\&.  If
+\fIfile\fP does not end in \fB\&.zwc\fP, this extension is automatically
+appended\&.  Files containing multiple compiled functions are called `digest'
+files, and are intended to be used as elements of the \fBFPATH\fP/\fBfpath\fP
+special array\&.
+.PP
+The second form, with the \fB\-c\fP or \fB\-a\fP options, writes the compiled
+definitions for all the named functions into \fIfile\fP\&.  For \fB\-c\fP, the
+names must be functions currently defined in the shell, not those marked
+for autoloading\&.  Undefined functions that are marked for autoloading
+may be written by using the \fB\-a\fP option, in which case the \fBfpath\fP
+is searched and the contents of the definition files for those
+functions, if found, are compiled into \fIfile\fP\&.  If both \fB\-c\fP and
+\fB\-a\fP are given, names of both defined functions and functions marked
+for autoloading may be given\&.  In either case, the functions in files
+written with the \fB\-c\fP or \fB\-a\fP option will be autoloaded as if the
+\fBKSH_AUTOLOAD\fP option were unset\&.
+.PP
+The reason for handling loaded and not\-yet\-loaded functions with
+different options is that some definition files for autoloading define
+multiple functions, including the function with the same name as the
+file, and, at the end, call that function\&.  In such cases the output of
+`\fBzcompile \-c\fP' does not include the additional functions defined in
+the file, and any other initialization code in the file is lost\&.  Using
+`\fBzcompile \-a\fP' captures all this extra information\&.
+.PP
+If the \fB\-m\fP option is combined with \fB\-c\fP or \fB\-a\fP,
+the \fIname\fPs are used as patterns and all functions whose names
+match one of these patterns will be written\&. If no \fIname\fP is given,
+the definitions of all functions currently defined or marked as
+autoloaded will be written\&.
+.PP
+The third form, with the \fB\-t\fP option, examines an existing
+compiled file\&.  Without further arguments, the names of the original
+files compiled into it are listed\&.  The first line of output shows
+the version of the shell which compiled the file and how the file
+will be used (i\&.e\&. by reading it directly or by mapping it into memory)\&.
+With arguments, nothing is output and the return value is set to zero if
+definitions for \fIall\fP \fIname\fPs were found in the compiled
+file, and non\-zero if the definition for at least one \fIname\fP was not
+found\&.
+.PP
+Other options:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-U\fP
+Aliases are not expanded when compiling the \fIname\fPd files\&.
+.TP
+\fB\-R\fP
+When the compiled file is read, its contents are copied into the
+shell's memory, rather than memory\-mapped (see \fB\-M\fP)\&.  This
+happens automatically on systems that do not support memory mapping\&.
+.RS
+.PP
+When compiling scripts instead of autoloadable functions, it is
+often desirable to use this option; otherwise the whole file, including the
+code to define functions which have already been defined, will
+remain mapped, consequently wasting memory\&.
+.RE
+.TP
+\fB\-M\fP
+The compiled file is mapped into the shell's memory when read\&. This
+is done in such a way that multiple instances of the shell running
+on the same host will share this mapped file\&.  If neither \fB\-R\fP nor
+\fB\-M\fP is given, the \fBzcompile\fP builtin decides what to do based
+on the size of the compiled file\&.
+.TP
+.PD 0
+\fB\-k\fP
+.TP
+.PD
+\fB\-z\fP
+These options are used when the compiled file contains functions which
+are to be autoloaded\&. If \fB\-z\fP is given, the
+function will be autoloaded as if the \fBKSH_AUTOLOAD\fP option is
+\fInot\fP set, even if it is set at the time the compiled file is
+read, while if the \fB\-k\fP is given, the function will be loaded as if
+\fBKSH_AUTOLOAD\fP \fIis\fP set\&.  These options also take precedence over
+any \fB\-k\fP or \fB\-z\fP options specified to the \fBautoload\fP builtin\&. If
+neither of these options is given, the function will be loaded as
+determined by the setting of the \fBKSH_AUTOLOAD\fP option at the time
+the compiled file is read\&.
+ 
+These options may also appear as many times as necessary between the listed
+\fIname\fPs to specify the loading style of all following functions, up to
+the next \fB\-k\fP or \fB\-z\fP\&.
+
+The created file always contains two versions of the compiled
+format, one for big\-endian machines and one for small\-endian
+machines\&.  The upshot of this is that the compiled file is machine
+independent and if it is read or mapped, only one half of the file
+is actually used (and mapped)\&.
+.RE
+.TP
+\fBzformat\fP
+See the section `The zsh/zutil Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBzftp\fP
+See the section `The zsh/zftp Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBzle\fP
+See the section `Zle Builtins' in \fIzshzle\fP(1)\&.
+.TP
+.PD 0
+\fBzmodload\fP [ \fB\-dL\fP ] [ \&.\&.\&. ]
+.TP
+.PD 0
+\fBzmodload \-e\fP [ \fB\-A\fP ] [ \&.\&.\&. ]
+.TP
+.PD 0
+\fBzmodload\fP [ \fB\-a\fP [ \fB\-bcpf\fP [ \fB\-I\fP ] ] ] [ \fB\-iL\fP ] \&.\&.\&.
+.TP
+.PD 0
+\fBzmodload\fP \fB\-u\fP [ \fB\-abcdpf\fP [ \fB\-I\fP ] ] [ \fB\-iL\fP ] \&.\&.\&.
+.TP
+.PD 0
+\fBzmodload\fP \fB\-A\fP [ \fB\-L\fP ] [ \fImodalias\fP[\fB=\fP\fImodule\fP] \&.\&.\&. ]
+.TP
+.PD
+\fBzmodload\fP \fB\-R\fP \fImodalias\fP \&.\&.\&. 
+Performs operations relating to zsh's loadable modules\&.
+Loading of modules while the shell is running (`dynamical loading') is not
+available on all operating systems, or on all installations on a particular
+operating system, although the \fBzmodload\fP command itself is always
+available and can be used to manipulate modules built into versions of the
+shell executable without dynamical loading\&.
+.RS
+.PP
+Without arguments the names of all currently loaded binary modules are
+printed\&.  The \fB\-L\fP option causes this list to be in the form of a
+series of \fBzmodload\fP commands\&.  Forms with arguments are:
+.PP
+.PD 0
+.TP
+.PD 0
+\fBzmodload\fP [ \fB\-i\fP ] \fIname\fP \&.\&.\&. 
+.TP
+.PD
+\fBzmodload\fP \fB\-u\fP [ \fB\-i\fP ] \fIname\fP \&.\&.\&.
+In the simplest case, \fBzmodload\fP loads a binary module\&.  The module must
+be in a file with a name consisting of the specified \fIname\fP followed by
+a standard suffix, usually `\fB\&.so\fP' (`\fB\&.sl\fP' on HPUX)\&.
+If the module to be loaded is
+already loaded and the \fB\-i\fP option is given, the duplicate module is
+ignored\&.  Otherwise \fBzmodload\fP prints an error message\&.
+.RS
+.PP
+The \fIname\fPd module is searched for in the same way a command is, using
+\fB$module_path\fP instead of \fB$path\fP\&.  However, the path search is
+performed even when the module name contains a `\fB/\fP', which it usually does\&.
+There is no way to prevent the path search\&.
+.PP
+With \fB\-u\fP, \fBzmodload\fP unloads modules\&.  The same \fIname\fP
+must be given that was given when the module was loaded, but it is not
+necessary for the module to exist in the filesystem\&.
+The \fB\-i\fP option suppresses the error if the module is already
+unloaded (or was never loaded)\&.
+.PP
+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\&.
+.RE
+.TP
+.PD 0
+\fBzmodload\fP \fB\-d\fP [ \fB\-L\fP ] [ \fIname\fP ]
+.TP
+.PD 0
+\fBzmodload\fP \fB\-d\fP \fIname\fP \fIdep\fP \&.\&.\&.
+.TP
+.PD
+\fBzmodload\fP \fB\-ud\fP \fIname\fP [ \fIdep\fP \&.\&.\&. ]
+The \fB\-d\fP 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\&.
+.RS
+.PP
+With \fB\-d\fP and one argument, all dependencies for that module are listed\&.
+With \fB\-d\fP and no arguments, all module dependencies are listed\&.  This
+listing is by default in a Makefile\-like format\&.  The \fB\-L\fP option
+changes this format to a list of \fBzmodload \-d\fP commands\&.
+.PP
+If \fB\-d\fP and \fB\-u\fP are both used, dependencies are removed\&.  If only one
+argument is given, all dependencies for that module are removed\&.
+.RE
+.TP
+.PD 0
+\fBzmodload\fP \fB\-ab\fP [ \fB\-L\fP ]
+.TP
+.PD 0
+\fBzmodload\fP \fB\-ab\fP [ \fB\-i\fP ] \fIname\fP [ \fIbuiltin\fP \&.\&.\&. ]
+.TP
+.PD
+\fBzmodload\fP \fB\-ub\fP [ \fB\-i\fP ] \fIbuiltin\fP \&.\&.\&.
+The \fB\-ab\fP option defines autoloaded builtins\&.  It defines the specified
+\fIbuiltin\fPs\&.  When any of those builtins is called, the module specified
+in the first argument is loaded\&.  If only the \fIname\fP is given, one
+builtin is defined, with the same name as the module\&.  \fB\-i\fP suppresses
+the error if the builtin is already defined or autoloaded, regardless of
+which module it came from\&.
+.RS
+.PP
+With \fB\-ab\fP and no arguments, all autoloaded builtins are listed, with the
+module name (if different) shown in parentheses after the builtin name\&.
+The \fB\-L\fP option changes this format to a list of \fBzmodload \-a\fP
+commands\&.
+.PP
+If \fB\-b\fP is used together with the \fB\-u\fP option, it removes builtins
+previously defined with \fB\-ab\fP\&.  This is only possible if the builtin is
+not yet loaded\&.  \fB\-i\fP suppresses the error if the builtin is already
+removed (or never existed)\&.
+.RE
+.TP
+.PD 0
+\fBzmodload\fP \fB\-ac\fP [ \fB\-IL\fP ]
+.TP
+.PD 0
+\fBzmodload\fP \fB\-ac\fP [ \fB\-iI\fP ] \fIname\fP [ \fIcond\fP \&.\&.\&. ]
+.TP
+.PD
+\fBzmodload\fP \fB\-uc\fP [ \fB\-iI\fP ] \fIcond\fP \&.\&.\&.
+The \fB\-ac\fP option is used to define autoloaded condition codes\&. The
+\fIcond\fP strings give the names of the conditions defined by the
+module\&. The optional \fB\-I\fP option is used to define infix condition
+names\&. Without this option prefix condition names are defined\&.
+.RS
+.PP
+If given no condition names, all defined names are listed (as a series of
+\fBzmodload\fP commands if the \fB\-L\fP option is given)\&.
+.PP
+The \fB\-uc\fP option removes definitions for autoloaded conditions\&.
+.RE
+.TP
+.PD 0
+\fBzmodload\fP \fB\-ap\fP [ \fB\-L\fP ]
+.TP
+.PD 0
+\fBzmodload\fP \fB\-ap\fP [ \fB\-i\fP ] \fIname\fP [ \fIparameter\fP \&.\&.\&. ]
+.TP
+.PD
+\fBzmodload\fP \fB\-up\fP [ \fB\-i\fP ] \fIparameter\fP \&.\&.\&.
+The \fB\-p\fP option is like the \fB\-b\fP and \fB\-c\fP options, but makes
+\fBzmodload\fP work on autoloaded parameters instead\&.
+.TP
+.PD 0
+\fBzmodload\fP \fB\-af\fP [ \fB\-L\fP ]
+.TP
+.PD 0
+\fBzmodload\fP \fB\-af\fP [ \fB\-i\fP ] \fIname\fP [ \fIfunction\fP \&.\&.\&. ]
+.TP
+.PD
+\fBzmodload\fP \fB\-uf\fP [ \fB\-i\fP ] \fIfunction\fP \&.\&.\&.
+The \fB\-f\fP option is like the \fB\-b\fP, \fB\-p\fP, and \fB\-c\fP options, but
+makes \fBzmodload\fP work on autoloaded math functions instead\&. 
+.TP
+.PD 0
+\fBzmodload\fP \fB\-a\fP [ \fB\-L\fP ]
+.TP
+.PD 0
+\fBzmodload\fP \fB\-a\fP [ \fB\-i\fP ] \fIname\fP [ \fIbuiltin\fP \&.\&.\&. ]
+.TP
+.PD
+\fBzmodload\fP \fB\-ua\fP [ \fB\-i\fP ] \fIbuiltin\fP \&.\&.\&.
+Equivalent to \fB\-ab\fP and \fB\-ub\fP\&.
+.TP
+\fBzmodload \-e\fP [ \fB\-A\fP ] [ \fIstring\fP \&.\&.\&. ]
+The \fB\-e\fP option without arguments lists all loaded modules; if the \fB\-A\fP
+option is also given, module aliases corresponding to loaded modules are
+also shown\&.  With arguments only the return status is set to zero
+if all \fIstring\fPs given as arguments are names of loaded modules
+and to one if at least on \fIstring\fP is not the name of a
+loaded module\&.  This can be used to test for the availability 
+of things implemented by modules\&.  In this case, any aliases are
+automatically resolved and the \fB\-A\fP flag is not used\&.
+.TP
+\fBzmodload\fP \fB\-A\fP [ \fB\-L\fP ] [ \fImodalias\fP[\fB=\fP\fImodule\fP] \&.\&.\&. ]
+For each argument, if both \fImodalias\fP and \fImodule\fP are given,
+define \fImodalias\fP to be an alias for the module \fImodule\fP\&.
+If the module \fImodalias\fP is ever subsequently requested, either via a
+call to \fBzmodload\fP or implicitly, the shell will attempt to load
+\fImodule\fP instead\&.  If \fImodule\fP is not given, show the definition of
+\fImodalias\fP\&.  If no arguments are given, list all defined module aliases\&.
+When listing, if the \fB\-L\fP flag was also given, list the definition as a
+\fBzmodload\fP command to recreate the alias\&.
+.RS
+.PP
+The existence of aliases for modules is completely independent of whether
+the name resolved is actually loaded as a module: while the alias exists,
+loading and unloading the module under any alias has exactly the same
+effect as using the resolved name, and does not affect the connection
+between the alias and the resolved name which can be removed either by
+\fBzmodload \-R\fP or by redefining the alias\&.  Chains of aliases (i\&.e\&. where
+the first resolved name is itself an alias) are valid so long as these are
+not circular\&.  As the aliases take the same format as module names, they
+may include path separators:  in this case, there is no requirement for any
+part of the path named to exist as the alias will be resolved first\&.  For
+example, `\fBany/old/alias\fP' is always a valid alias\&.
+.PP
+Dependencies added to aliased modules are actually added to the resolved
+module; these remain if the alias is removed\&.  It is valid to create an
+alias whose name is one of the standard shell modules and which resolves to
+a different module\&.  However, if a module has dependencies, it
+will not be possible to use the module name as an alias as the module will
+already be marked as a loadable module in its own right\&.
+.PP
+Apart from the above, aliases can be used in the \fBzmodload\fP command
+anywhere module names are required\&.  However, aliases will not be
+shown in lists of loaded modules with a bare `\fBzmodload\fP'\&.
+.RE
+.TP
+\fBzmodload\fP \fB\-R\fP \fImodalias\fP \&.\&.\&. 
+For each \fImodalias\fP argument that was previously defined as a module
+alias via \fBzmodload \-A\fP, delete the alias\&.  If any was not defined, an
+error is caused and the remainder of the line is ignored\&.
+.PP
+Note that \fBzsh\fP makes no distinction between modules that were linked 
+into the shell and modules that are loaded dynamically\&. In both cases
+this builtin command has to be used to make available the builtins and
+other things defined by modules (unless the module is autoloaded on
+these definitions)\&. This is true even for systems that don't support
+dynamic loading of modules\&.
+.RE
+.TP
+\fBzparseopts\fP
+See the section `The zsh/zutil Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBzprof\fP
+See the section `The zsh/zprof Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBzpty\fP
+See the section `The zsh/zpty Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBzregexparse\fP
+See the section `The zsh/zutil Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBzsocket\fP
+See the section `The zsh/net/socket Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBzstyle\fP
+See the section `The zsh/zutil Module' in \fIzshmodules\fP(1)\&.
+.TP
+\fBztcp\fP
+See the section `The zsh/net/tcp Module' in \fIzshmodules\fP(1)\&.
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshcompctl.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshcompctl.1
@@ -0,0 +1,736 @@
+.TH "ZSHCOMPCTL" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshcompctl \- zsh programmable completion
+.\" Yodl file: Zsh/compctl.yo
+.SH "DESCRIPTION"
+This version of zsh has two ways of performing completion of words on the
+command line\&.  New users of the shell may prefer to use the newer
+and more powerful system based on shell functions; this is described in
+\fIzshcompsys\fP(1), and the basic shell mechanisms which support it are
+described in \fIzshcompwid\fP(1)\&.  This manual entry describes the older
+\fBcompctl\fP command\&.
+.PD 0
+.TP
+\fBcompctl\fP [ \fB\-CDT\fP ] \fIoptions\fP [ \fIcommand\fP \&.\&.\&. ]
+.TP
+\fBcompctl\fP [ \fB\-CDT\fP ] \fIoptions\fP [ \fB\-x\fP \fIpattern\fP \fIoptions\fP \fB\-\fP \&.\&.\&. \fB\-\-\fP ] [ \fB+\fP \fIoptions\fP [ \fB\-x\fP \&.\&.\&. \fB\-\-\fP ] \&.\&.\&. [\fB+\fP] ] [ \fIcommand\fP \&.\&.\&. ]
+.TP
+\fBcompctl\fP \fB\-M\fP \fImatch\-specs\fP \&.\&.\&.
+.TP
+\fBcompctl\fP \fB\-L\fP [ \fB\-CDTM\fP ] [ \fIcommand\fP \&.\&.\&. ]
+.TP
+\fBcompctl\fP \fB+\fP \fIcommand\fP \&.\&.\&.
+.PD
+.PP
+Control the editor's completion behavior according to the supplied set
+of \fIoptions\fP\&.  Various editing commands, notably
+\fBexpand\-or\-complete\-word\fP, usually bound to tab, will
+attempt to complete a word typed by the user, while others, notably
+\fBdelete\-char\-or\-list\fP, usually bound to ^D in EMACS editing
+mode, list the possibilities; \fBcompctl\fP controls what those
+possibilities are\&.  They may for example be filenames (the most common
+case, and hence the default), shell variables, or words from a
+user\-specified list\&.
+.PP
+.SH "COMMAND FLAGS"
+Completion of the arguments of a command may be different for each
+command or may use the default\&.  The behavior when completing the
+command word itself may also be separately specified\&.  These
+correspond to the following flags and arguments, all of which (except
+for \fB\-L\fP) may be combined with any combination of the
+\fIoptions\fP described subsequently in the section `Option Flags':
+.PP
+.PD 0
+.TP
+.PD
+\fIcommand\fP \&.\&.\&.
+controls completion for the named commands, which must be listed last
+on the command line\&.  If completion is attempted for a command with a
+pathname containing slashes and no completion definition is found, the
+search is retried with the last pathname component\&. If the command starts
+with a \fB=\fP, completion is tried with the pathname of the command\&.
+.RS
+.PP
+Any of the \fIcommand\fP strings may be patterns of the form normally
+used for filename generation\&.  These should be be quoted to protect them
+from immediate expansion; for example the command string \fB'foo*'\fP
+arranges for completion of the words of any command beginning with
+\fBfoo\fP\&.  When completion is attempted, all pattern completions are
+tried in the reverse order of their definition until one matches\&.  By
+default, completion then proceeds as normal, i\&.e\&. the shell will try to
+generate more matches for the specific command on the command line; this
+can be overridden by including \fB\-tn\fP in the flags for the pattern
+completion\&.
+.PP
+Note that aliases
+are expanded before the command name is determined unless the
+\fBCOMPLETE_ALIASES\fP option is set\&.  Commands may not be combined
+with the \fB\-C\fP, \fB\-D\fP or \fB\-T\fP flags\&.
+.RE
+.TP
+\fB\-C\fP
+controls completion when the command word itself is being completed\&.
+If no \fBcompctl \-C\fP command has been issued,  the names of any
+executable command (whether in the path or specific to the shell, such
+as aliases or functions) are completed\&.
+.TP
+\fB\-D\fP
+controls default completion behavior for the arguments of commands not
+assigned any special behavior\&.  If no \fBcompctl \-D\fP command has
+been issued, filenames are completed\&.
+.TP
+\fB\-T\fP
+supplies completion flags to be used before any other processing is
+done, even before processing for \fBcompctl\fPs defined for specific
+commands\&.  This is especially useful when combined with extended
+completion (the \fB\-x\fP flag, see the section `Extended Completion' below)\&.
+Using this flag you can define default behavior
+which will apply to all commands without exception, or you can alter
+the standard behavior for all commands\&.  For example, if your access
+to the user database is too slow and/or it contains too many users (so
+that completion after `\fB~\fP' is too slow to be usable), you can use
+.RS
+.PP
+.RS
+.nf
+\fBcompctl \-T \-x 's[~] C[0,[^/]#]' \-k friends \-S/ \-tn\fP
+.fi
+.RE
+.PP
+to complete the strings in the array \fBfriends\fP after a `\fB~\fP'\&.
+The \fBC[\&.\&.\&.]\fP argument is necessary so that this form of ~\-completion is
+not tried after the directory name is finished\&.
+.RE
+.TP
+\fB\-L\fP
+lists the existing completion behavior in a manner suitable for
+putting into a start\-up script; the existing behavior is not changed\&.
+Any combination of the above forms, or the \fB\-M\fP flag (which must
+follow the \fB\-L\fP flag), may be specified, otherwise all defined
+completions are listed\&.  Any other flags supplied are ignored\&.
+.TP
+\fIno argument\fP
+If no argument is given, \fBcompctl\fP lists all defined completions
+in an abbreviated form;  with a list of \fIoptions\fP, all completions
+with those flags set (not counting extended completion) are listed\&.
+.PP
+If the \fB+\fP flag is alone and followed immediately by the \fIcommand\fP
+list, the completion behavior for all the commands in the list is reset to
+the default\&.  In other words, completion will subsequently use the
+options specified by the \fB\-D\fP flag\&.
+.PP
+The form with \fB\-M\fP as the first and only option defines global
+matching specifications (see
+zshcompwid)\&. The match specifications given will be used for every completion
+attempt (only when using \fBcompctl\fP, not with the new completion
+system) and are tried in the order in which they are defined until one 
+generates at least one match\&. E\&.g\&.:
+.PP
+.RS
+.nf
+\fBcompctl \-M '' 'm:{a\-zA\-Z}={A\-Za\-z}'\fP
+.fi
+.RE
+.PP
+This will first try completion without any global match specifications 
+(the empty string) and, if that generates no matches, will try case
+insensitive completion\&.
+.PP
+.SH "OPTION FLAGS"
+.PD 0
+.TP
+[ \fB\-fcFBdeaRGovNAIOPZEnbjrzu/12\fP ]
+.TP
+[ \fB\-k\fP \fIarray\fP ] [ \fB\-g\fP \fIglobstring\fP ] [ \fB\-s\fP \fIsubststring\fP ]
+.TP
+[ \fB\-K\fP \fIfunction\fP ]
+.TP
+[ \fB\-Q\fP ] [ \fB\-P\fP \fIprefix\fP ] [ \fB\-S\fP \fIsuffix\fP ]
+.TP
+[ \fB\-W\fP \fIfile\-prefix\fP ] [ \fB\-H\fP \fInum pattern\fP ]
+.TP
+[ \fB\-q\fP ] [ \fB\-X\fP \fIexplanation\fP ] [ \fB\-Y\fP \fIexplanation\fP ]
+.TP
+[ \fB\-y\fP \fIfunc\-or\-var\fP ] [ \fB\-l\fP \fIcmd\fP ] [ \fB\-h\fP \fIcmd\fP ] [ \fB\-U\fP ]
+.TP
+[ \fB\-t\fP \fIcontinue\fP ] [ \fB\-J\fP \fIname\fP ] [ \fB\-V\fP \fIname\fP ]
+.TP
+[ \fB\-M\fP \fImatch\-spec\fP ]
+.PD
+.PP
+The remaining \fIoptions\fP specify the type of command arguments
+to look for during completion\&.  Any combination of these flags may be
+specified; the result is a sorted list of all the possibilities\&.  The
+options are as follows\&.
+.PP
+.SS "Simple Flags"
+These produce completion lists made up by the shell itself:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-f\fP
+Filenames and filesystem paths\&.
+.TP
+\fB\-/\fP
+Just filesystem paths\&.
+.TP
+\fB\-c\fP
+Command names, including aliases, shell functions, builtins
+and reserved words\&.
+.TP
+\fB\-F\fP
+Function names\&.
+.TP
+\fB\-B\fP
+Names of builtin commands\&.
+.TP
+\fB\-m\fP
+Names of external commands\&.
+.TP
+\fB\-w\fP
+Reserved words\&.
+.TP
+\fB\-a\fP
+Alias names\&.
+.TP
+\fB\-R\fP
+Names of regular (non\-global) aliases\&.
+.TP
+\fB\-G\fP
+Names of global aliases\&.
+.TP
+\fB\-d\fP
+This can be combined with \fB\-F\fP, \fB\-B\fP, \fB\-w\fP,
+\fB\-a\fP, \fB\-R\fP and \fB\-G\fP to get names of disabled
+functions, builtins, reserved words or aliases\&.
+.TP
+\fB\-e\fP
+This option (to show enabled commands) is in effect by default, but
+may be combined with \fB\-d\fP; \fB\-de\fP in combination with
+\fB\-F\fP, \fB\-B\fP, \fB\-w\fP, \fB\-a\fP, \fB\-R\fP and \fB\-G\fP
+will complete names of functions, builtins, reserved words or aliases
+whether or not they are disabled\&.
+.TP
+\fB\-o\fP
+Names of shell options (see
+\fIzshoptions\fP(1))\&.
+.TP
+\fB\-v\fP
+Names of any variable defined in the shell\&.
+.TP
+\fB\-N\fP
+Names of scalar (non\-array) parameters\&.
+.TP
+\fB\-A\fP
+Array names\&.
+.TP
+\fB\-I\fP
+Names of integer variables\&.
+.TP
+\fB\-O\fP
+Names of read\-only variables\&.
+.TP
+\fB\-p\fP
+Names of parameters used by the shell (including special parameters)\&.
+.TP
+\fB\-Z\fP
+Names of shell special parameters\&.
+.TP
+\fB\-E\fP
+Names of environment variables\&.
+.TP
+\fB\-n\fP
+Named directories\&.
+.TP
+\fB\-b\fP
+Key binding names\&.
+.TP
+\fB\-j\fP
+Job names:  the first word of the job leader's command line\&.  This is useful
+with the \fBkill\fP builtin\&.
+.TP
+\fB\-r\fP
+Names of running jobs\&.
+.TP
+\fB\-z\fP
+Names of suspended jobs\&.
+.TP
+\fB\-u\fP
+User names\&.
+.PP
+.SS "Flags with Arguments"
+These have user supplied arguments to determine how the list of
+completions is to be made up:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-k\fP \fIarray\fP
+Names taken from the elements of \fB$\fP\fIarray\fP (note that the `\fB$\fP'
+does not appear on the command line)\&.
+Alternatively, the argument \fIarray\fP itself may be a set
+of space\- or comma\-separated values in parentheses, in which any
+delimiter may be escaped with a backslash; in this case the argument
+should be quoted\&.  For example,
+.RS
+.PP
+.RS
+.nf
+\fBcompctl \-k "(cputime filesize datasize stacksize
+	       coredumpsize resident descriptors)" limit\fP
+.fi
+.RE
+.RE
+.TP
+\fB\-g\fP \fIglobstring\fP
+The \fIglobstring\fP is expanded using filename globbing; it should be
+quoted to protect it from immediate expansion\&. The resulting
+filenames are taken as the possible completions\&.  Use `\fB*(/)\fP' instead of
+`\fB*/\fP' for directories\&.  The \fBfignore\fP special parameter is not
+applied to the resulting files\&.  More than one pattern may be given
+separated by blanks\&. (Note that brace expansion is \fInot\fP part of
+globbing\&.  Use the syntax `\fB(either|or)\fP' to match alternatives\&.)
+.TP
+\fB\-s\fP \fIsubststring\fP
+The \fIsubststring\fP is split into words and these words are than
+expanded using all shell expansion mechanisms (see
+\fIzshexpn\fP(1))\&.  The resulting words are taken as possible
+completions\&.  The \fBfignore\fP special parameter is not applied to the
+resulting files\&.  Note that \fB\-g\fP is faster for filenames\&.
+.TP
+\fB\-K\fP \fIfunction\fP
+Call the given function to get the completions\&.  Unless the name
+starts with an underscore, the function is
+passed two arguments: the prefix and the suffix of the word on which
+completion is to be attempted, in other words those characters before
+the cursor position, and those from the cursor position onwards\&.  The
+whole command line can be accessed with the \fB\-c\fP and \fB\-l\fP flags
+of the \fBread\fP builtin\&. The
+function should set the variable \fBreply\fP to an array containing
+the completions (one completion per element); note that \fBreply\fP
+should not be made local to the function\&.  From such a function the
+command line can be accessed with the \fB\-c\fP and \fB\-l\fP flags to
+the \fBread\fP builtin\&.  For example,
+.RS
+.PP
+.RS
+.nf
+\fBfunction whoson { reply=(`users`); }
+compctl \-K whoson talk\fP
+.fi
+.RE
+.PP
+completes only logged\-on users after `\fBtalk\fP'\&.  Note that `\fBwhoson\fP' must
+return an array, so `\fBreply=`users`\fP' would be incorrect\&.
+.RE
+.TP
+\fB\-H\fP \fInum pattern\fP
+The possible completions are taken from the last \fInum\fP history
+lines\&.  Only words matching \fIpattern\fP are taken\&.  If \fInum\fP is
+zero or negative the whole history is searched and if \fIpattern\fP is
+the empty string all words are taken (as with `\fB*\fP')\&.  A typical
+use is
+.RS
+.PP
+.RS
+.nf
+\fBcompctl \-D \-f + \-H 0 ''\fP
+.fi
+.RE
+.PP
+which forces completion to look back in the history list for a word if
+no filename matches\&.
+.RE
+.RE
+.PP
+.SS "Control Flags"
+These do not directly specify types of name to be completed, but
+manipulate the options that do:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-Q\fP
+This instructs the shell not to quote any metacharacters in the possible
+completions\&.  Normally the results of a completion are inserted into
+the command line with any metacharacters quoted so that they are
+interpreted as normal characters\&.  This is appropriate for filenames
+and ordinary strings\&.  However, for special effects, such as inserting
+a backquoted expression from a completion array (\fB\-k\fP) so that
+the expression will not be evaluated until the complete line is
+executed, this option must be used\&.
+.TP
+\fB\-P\fP \fIprefix\fP
+The \fIprefix\fP is inserted just before the completed string; any
+initial part already typed will be completed and the whole \fIprefix\fP
+ignored for completion purposes\&.  For example,
+.RS
+.PP
+.RS
+.nf
+\fBcompctl \-j \-P "%" kill\fP
+.fi
+.RE
+.PP
+inserts a `%' after the kill command and then completes job names\&.
+.RE
+.TP
+\fB\-S\fP \fIsuffix\fP
+When a completion is found the \fIsuffix\fP is inserted after
+the completed string\&.  In the case of menu completion the suffix is
+inserted immediately, but it is still possible to cycle through the
+list of completions by repeatedly hitting the same key\&.
+.TP
+\fB\-W\fP \fIfile\-prefix\fP
+With directory \fIfile\-prefix\fP:  for command, file, directory and
+globbing completion (options \fB\-c\fP, \fB\-f\fP, \fB\-/\fP, \fB\-g\fP), the file
+prefix is implicitly added in front of the completion\&.  For example,
+.RS
+.PP
+.RS
+.nf
+\fBcompctl \-/ \-W ~/Mail maildirs\fP
+.fi
+.RE
+.PP
+completes any subdirectories to any depth beneath the directory
+\fB~/Mail\fP, although that prefix does not appear on the command line\&.
+The \fIfile\-prefix\fP may also be of the form accepted by the \fB\-k\fP
+flag, i\&.e\&. the name of an array or a literal list in parenthesis\&. In
+this case all the directories in the list will be searched for
+possible completions\&.
+.RE
+.TP
+\fB\-q\fP
+If used with a suffix as specified by the \fB\-S\fP option, this
+causes the suffix to be removed if the next character typed is a blank
+or does not insert anything or if the suffix consists of only one character
+and the next character typed is the same character; this the same rule used
+for the \fBAUTO_REMOVE_SLASH\fP option\&.  The option is most useful for list
+separators (comma, colon, etc\&.)\&.
+.TP
+\fB\-l\fP \fIcmd\fP
+This option restricts the range
+of command line words that are considered to be arguments\&.  If
+combined with one of the extended completion patterns `\fBp[\fP\&.\&.\&.\fB]\fP',
+`\fBr[\fP\&.\&.\&.\fB]\fP', or `\fBR[\fP\&.\&.\&.\fB]\fP'  (see the section `Extended Completion'
+below) the range is restricted to the range of arguments
+specified in the brackets\&.  Completion is then performed as if these
+had been given as arguments to the \fIcmd\fP supplied with the
+option\&. If the \fIcmd\fP string is empty the first word in the range
+is instead taken as the command name, and command name completion
+performed on the first word in the range\&.  For example,
+.RS
+.PP
+.RS
+.nf
+\fBcompctl \-x 'r[\-exec,;]' \-l '' \-\- find\fP
+.fi
+.RE
+.PP
+completes arguments between `\fB\-exec\fP' and the following `\fB;\fP' (or the end
+of the command line if there is no such string) as if they were
+a separate command line\&.
+.RE
+.TP
+\fB\-h\fP \fIcmd\fP
+Normally zsh completes quoted strings as a whole\&. With this option,
+completion can be done separately on different parts of such
+strings\&. It works like the \fB\-l\fP option but makes the completion code 
+work on the parts of the current word that are separated by
+spaces\&. These parts are completed as if they were arguments to the
+given \fIcmd\fP\&. If \fIcmd\fP is the empty string, the first part is
+completed as a command name, as with \fB\-l\fP\&.
+.TP
+\fB\-U\fP
+Use the whole list of possible completions, whether or not they
+actually match the word on the command line\&.  The word typed so far
+will be deleted\&.  This is most useful with a function (given by the
+\fB\-K\fP option) which can examine the word components passed to it
+(or via the \fBread\fP builtin's \fB\-c\fP and \fB\-l\fP flags) and
+use its own criteria to decide what matches\&.  If there is no
+completion, the original word is retained\&.  Since the produced 
+possible completions seldom have interesting common prefixes
+and suffixes, menu completion is started immediately if \fBAUTO_MENU\fP is
+set and this flag is used\&.
+.TP
+\fB\-y\fP \fIfunc\-or\-var\fP
+The list provided by \fIfunc\-or\-var\fP is displayed instead of the list
+of completions whenever a listing is required; the actual completions
+to be inserted are not affected\&.  It can be provided in two
+ways\&. Firstly, if \fIfunc\-or\-var\fP begins with a \fB$\fP it defines a
+variable, or if it begins with a left parenthesis a literal
+array, which contains the list\&.  A variable may have been set by a
+call to a function using the \fB\-K\fP option\&.  Otherwise it contains the
+name of a function which will be executed to create the list\&.  The
+function will be passed as an argument list all matching completions,
+including prefixes and suffixes expanded in full, and should set the
+array \fBreply\fP to the result\&.  In both cases, the display list will
+only be retrieved after a complete list of matches has been created\&.
+.RS
+.PP
+Note that the returned list does not have to correspond, even in
+length, to the original set of matches, and may be passed as a scalar
+instead of an array\&.  No special formatting of characters is
+performed on the output in this case; in particular, newlines are
+printed literally and if they appear output in columns is suppressed\&.
+.RE
+.TP
+\fB\-X\fP \fIexplanation\fP
+Print \fIexplanation\fP when trying completion on the current set of
+options\&. A `\fB%n\fP' in this string is replaced by the number of
+matches that were added for this explanation string\&.
+The explanation only appears if completion was tried and there was
+no unique match, or when listing completions\&. Explanation strings 
+will be listed together with the matches of the group specified
+together with the \fB\-X\fP option (using the \fB\-J\fP or \fB\-V\fP
+option)\&. If the same explanation string is given to multiple \fB\-X\fP
+options, the string appears only once (for each group) and the number
+of matches shown for the `\fB%n\fP' is the total number of all matches
+for each of these uses\&. In any case, the explanation string will only
+be shown if there was at least one match added for the explanation
+string\&.
+.RS
+.PP
+The sequences \fB%B\fP, \fB%b\fP, \fB%S\fP, \fB%s\fP, \fB%U\fP, and \fB%u\fP specify
+output attributes (bold, standout, and underline) and \fB%{\&.\&.\&.%}\fP can
+be used to include literal escape sequences as in prompts\&.
+.RE
+.TP
+\fB\-Y\fP \fIexplanation\fP
+Identical to \fB\-X\fP, except that the \fIexplanation\fP first undergoes
+expansion following the usual rules for strings in double quotes\&.
+The expansion will be carried out after any functions are called for
+the \fB\-K\fP or \fB\-y\fP options, allowing them to set variables\&.
+.TP
+\fB\-t\fP \fIcontinue\fP
+The \fIcontinue\fP\-string contains a character that specifies which set
+of completion flags should be used next\&.  It is useful:
+.RS
+.PP
+(i) With \fB\-T\fP, or when trying a list of pattern completions, when
+\fBcompctl\fP would usually continue with ordinary processing after
+finding matches; this can be suppressed with `\fB\-tn\fP'\&.
+.PP
+(ii) With a list of alternatives separated by \fB+\fP, when \fBcompctl\fP
+would normally stop when one of the alternatives generates matches\&.  It
+can be forced to consider the next set of completions by adding `\fB\-t+\fP'
+to the flags of the alternative before the `\fB+\fP'\&.
+.PP
+(iii) In an extended completion list (see below), when \fBcompctl\fP would
+normally continue until a set of conditions succeeded, then use only
+the immediately following flags\&.  With `\fB\-t\-\fP', \fBcompctl\fP will
+continue trying extended completions after the next `\fB\-\fP'; with
+`\fB\-tx\fP' it will attempt completion with the default flags, in other
+words those before the `\fB\-x\fP'\&.
+.RE
+.TP
+\fB\-J\fP \fIname\fP
+This gives the name of the group the matches should be placed in\&. Groups
+are listed and sorted separately; likewise, menu completion will offer
+the matches in the groups in the order in which the groups were
+defined\&. If no group name is explicitly given, the matches are stored in
+a group named \fIdefault\fP\&. The first time a group name is encountered,
+a group with that name is created\&. After that all matches with the same
+group name are stored in that group\&.
+.RS
+.PP
+This can be useful with non\-exclusive alternative completions\&.  For
+example, in
+.PP
+.RS
+.nf
+\fBcompctl \-f \-J files \-t+ + \-v \-J variables foo\fP
+.fi
+.RE
+.PP
+both files and variables are possible completions, as the \fB\-t+\fP forces
+both sets of alternatives before and after the \fB+\fP to be considered at
+once\&.  Because of the \fB\-J\fP options, however, all files are listed
+before all variables\&.
+.RE
+.TP
+\fB\-V\fP \fIname\fP
+Like \fB\-J\fP, but matches within the group will not be sorted in listings
+nor in menu completion\&. These unsorted groups are in a different name
+space from the sorted ones, so groups defined as \fB\-J files\fP and \fB\-V
+files\fP are distinct\&.
+.TP
+\fB\-1\fP
+If given together with the \fB\-V\fP option, makes
+only consecutive duplicates in the group be removed\&. Note that groups
+with and without this flag are in different name spaces\&.
+.TP
+\fB\-2\fP
+If given together with the \fB\-J\fP or \fB\-V\fP option, makes all
+duplicates be kept\&. Again, groups with and without this flag are in
+different name spaces\&.
+.TP
+\fB\-M\fP \fImatch\-spec\fP
+This defines additional matching control specifications that should be used
+only when testing words for the list of flags this flag appears in\&. The format
+of the \fImatch\-spec\fP string is described in 
+zshcompwid\&.
+.PP
+.SH "ALTERNATIVE COMPLETION"
+.PD 0
+.TP
+\fBcompctl\fP [ \fB\-CDT\fP ] \fIoptions\fP \fB+\fP \fIoptions\fP [ \fB+\fP \&.\&.\&. ] [ \fB+\fP ] \fIcommand\fP \&.\&.\&.
+.PD
+.PP
+The form with `\fB+\fP' specifies alternative options\&. Completion is
+tried with the options before the first `\fB+\fP'\&. If this produces no
+matches completion is tried with the flags after the `\fB+\fP' and so on\&. If
+there are no flags after the last `\fB+\fP' and a match has not been found
+up to that point, default completion is tried\&.
+If the list of flags contains a \fB\-t\fP with a \fB+\fP character, the next
+list of flags is used even if the current list produced matches\&.
+.PP
+.SH "EXTENDED COMPLETION"
+.PD 0
+.TP
+.nf
+\fBcompctl\fP [ \fB\-CDT\fP ] \fIoptions\fP \fB\-x\fP \fIpattern\fP \fIoptions\fP \fB\-\fP \&.\&.\&. \fB\-\-\fP
+  [ \fIcommand\fP \&.\&.\&. ]
+.fi
+.TP
+.nf
+\fBcompctl\fP [ \fB\-CDT\fP ] \fIoptions\fP [ \fB\-x\fP \fIpattern\fP \fIoptions\fP \fB\-\fP \&.\&.\&. \fB\-\-\fP ]
+  [ \fB+\fP \fIoptions\fP [ \fB\-x\fP \&.\&.\&. \fB\-\-\fP ] \&.\&.\&. [\fB+\fP] ] [ \fIcommand\fP \&.\&.\&. ]
+.fi
+.PD
+.PP
+The form with `\fB\-x\fP' specifies extended completion for the
+commands given; as shown, it may be combined with alternative
+completion using `\fB+\fP'\&.  Each \fIpattern\fP is examined in turn; when a
+match is found, the corresponding \fIoptions\fP, as described in
+the section `Option Flags' above, are used to generate possible
+completions\&.  If no \fIpattern\fP matches, the \fIoptions\fP given
+before the \fB\-x\fP are used\&.
+.PP
+Note that each pattern should be supplied as a single argument and
+should be quoted to prevent expansion of metacharacters by the
+shell\&.
+.PP
+A \fIpattern\fP is built of sub\-patterns separated by commas; it
+matches if at least one of these sub\-patterns matches (they are
+`or'ed)\&. These sub\-patterns are in turn composed of other
+sub\-patterns separated by white spaces which match if all of the
+sub\-patterns match (they are `and'ed)\&.  An element of the
+sub\-patterns is of the form `\fIc\fP\fB[\fP\&.\&.\&.\fB][\fP\&.\&.\&.\fB]\fP', where the pairs of
+brackets may be repeated as often as necessary, and matches if any of
+the sets of brackets match (an `or')\&.  The example below makes this
+clearer\&.
+.PP
+The elements may be any of the following:
+.PP
+.PD 0
+.TP
+.PD
+\fBs[\fP\fIstring\fP\fB]\fP\&.\&.\&.
+Matches if the current word on the command line starts with
+one of the strings given in brackets\&.  The \fIstring\fP is not removed
+and is not part of the completion\&.
+.TP
+\fBS[\fP\fIstring\fP\fB]\fP\&.\&.\&.
+Like \fBs[\fP\fIstring\fP\fB]\fP except that the \fIstring\fP is part of the
+completion\&.
+.TP
+\fBp[\fP\fIfrom\fP\fB,\fP\fIto\fP\fB]\fP\&.\&.\&.
+Matches if the number of the current word is between one of
+the \fIfrom\fP and \fIto\fP pairs inclusive\&. The comma and \fIto\fP
+are optional; \fIto\fP defaults to the same value as \fIfrom\fP\&.  The
+numbers may be negative: \fB\-\fP\fIn\fP refers to the \fIn\fP'th last word
+on the line\&.
+.TP
+\fBc[\fP\fIoffset\fP\fB,\fP\fIstring\fP\fB]\fP\&.\&.\&.
+Matches if the \fIstring\fP matches the word offset by
+\fIoffset\fP from the current word position\&.  Usually \fIoffset\fP
+will be negative\&.
+.TP
+\fBC[\fP\fIoffset\fP\fB,\fP\fIpattern\fP\fB]\fP\&.\&.\&.
+Like \fBc\fP but using pattern matching instead\&.
+.TP
+\fBw[\fP\fIindex\fP\fB,\fP\fIstring\fP\fB]\fP\&.\&.\&.
+Matches if the word in position \fIindex\fP is equal
+to the corresponding \fIstring\fP\&.  Note that the word count is made
+after any alias expansion\&.
+.TP
+\fBW[\fP\fIindex\fP\fB,\fP\fIpattern\fP\fB]\fP\&.\&.\&.
+Like \fBw\fP but using pattern matching instead\&.
+.TP
+\fBn[\fP\fIindex\fP\fB,\fP\fIstring\fP\fB]\fP\&.\&.\&.
+Matches if the current word contains \fIstring\fP\&.  Anything up to and
+including the \fIindex\fPth occurrence of this string will not be
+considered part of the completion, but the rest will\&.  \fIindex\fP may
+be negative to count from the end: in most cases, \fIindex\fP will be
+1 or \-1\&.  For example,
+.RS
+.PP
+.RS
+.nf
+\fBcompctl \-s '`users`' \-x 'n[1,@]' \-k hosts \-\- talk\fP
+.fi
+.RE
+.PP
+will usually complete usernames, but if you insert an \fB@\fP after the
+name, names from the array \fIhosts\fP (assumed to contain hostnames,
+though you must make the array yourself) will be completed\&.  Other
+commands such as \fBrcp\fP can be handled similarly\&.
+.RE
+.TP
+\fBN[\fP\fIindex\fP\fB,\fP\fIstring\fP\fB]\fP\&.\&.\&.
+Like \fBn\fP except that the string will be
+taken as a character class\&.  Anything up to and including the
+\fIindex\fPth occurrence of any of the characters in \fIstring\fP
+will not be considered part of the completion\&.
+.TP
+\fBm[\fP\fImin\fP\fB,\fP\fImax\fP\fB]\fP\&.\&.\&.
+Matches if the total number of words lies between \fImin\fP and
+\fImax\fP inclusive\&.
+.TP
+\fBr[\fP\fIstr1\fP\fB,\fP\fIstr2\fP\fB]\fP\&.\&.\&.
+Matches if the cursor is after a word with prefix \fIstr1\fP\&.  If there
+is also a word with prefix \fIstr2\fP on the command line after the one 
+matched by \fIstr1\fP it matches
+only if the cursor is before this word\&. If the comma and \fIstr2\fP are
+omitted, it matches if the cursor is after a word with prefix \fIstr1\fP\&.
+.TP
+\fBR[\fP\fIstr1\fP\fB,\fP\fIstr2\fP\fB]\fP\&.\&.\&.
+Like \fBr\fP but using pattern matching instead\&.
+.TP
+\fBq[\fP\fIstr\fP\fB]\fP\&.\&.\&.
+Matches the word currently being completed is in single quotes and the 
+\fIstr\fP begins with the letter `s', or if completion is done in
+double quotes and \fIstr\fP starts with the letter `d', or if
+completion is done in backticks and \fIstr\fP starts with a `b'\&.
+.PP
+.SH "EXAMPLE"
+.PP
+.RS
+.nf
+\fBcompctl \-u \-x 's[\fB+\fP] c[\-1,\-f],s[\-f+]' \e 
+  \-g '~/Mail/*(:t)' \- 's[\-f],c[\-1,\-f]' \-f \-\- mail\fP
+.fi
+.RE
+.PP
+This is to be interpreted as follows:
+.PP
+If the current command is \fBmail\fP, then
+.PP
+.RS
+.nf
+.PP
+if ((the current word begins with \fB+\fP and the previous word is \fB\-f\fP)
+or (the current word begins with \fB\-f+\fP)), then complete the
+non\-directory part (the `\fB:t\fP' glob modifier) of files in the directory
+\fB~/Mail\fP; else
+.PP
+if the current word begins with \fB\-f\fP or the previous word was \fB\-f\fP, then
+complete any file; else
+.PP
+complete user names\&.
+
+.fi
+.RE
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshcompwid.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshcompwid.1
@@ -0,0 +1,1175 @@
+.TH "ZSHCOMPWID" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshcompwid \- zsh completion widgets
+.\" Yodl file: Zsh/compwid.yo
+.SH "DESCRIPTION"
+The shell's programmable completion mechanism can be manipulated in two
+ways; here the low\-level features supporting the newer, function\-based
+mechanism are defined\&.  A complete set of shell functions based on these
+features is described in
+\fIzshcompsys\fP(1),
+and users with no interest in adding to that system (or, potentially,
+writing their own \-\-\- see dictionary entry for `hubris') should skip this
+section\&.  The older system based on the \fBcompctl\fP builtin command is
+described in
+\fIzshcompctl\fP(1)\&.
+.PP
+Completion widgets are defined by the \fB\-C\fP option to the \fBzle\fP
+builtin command provided by the \fBzsh/zle\fP module (see
+\fIzshzle\fP(1))\&. For example,
+.PP
+.RS
+.nf
+\fBzle \-C complete expand\-or\-complete completer\fP
+.fi
+.RE
+.PP
+defines a widget named `\fBcomplete\fP'\&.  The second argument is the name
+of any of the builtin widgets that handle completions:
+\fBcomplete\-word\fP, \fBexpand\-or\-complete\fP,
+\fBexpand\-or\-complete\-prefix\fP, \fBmenu\-complete\fP,
+\fBmenu\-expand\-or\-complete\fP, \fBreverse\-menu\-complete\fP,
+\fBlist\-choices\fP, or \fBdelete\-char\-or\-list\fP\&.  Note that this will still
+work even if the widget in question has been re\-bound\&.
+.PP
+When this newly defined widget is bound to a key
+using the \fBbindkey\fP builtin command defined in the \fBzsh/zle\fP module
+(see \fIzshzle\fP(1)), typing that key will call the shell function `\fBcompleter\fP'\&. This
+function is responsible for generating the possible matches using the
+builtins described below\&.  As with other ZLE widgets, the function is
+called with its standard input closed\&.
+.PP
+Once the function returns, the completion code takes over control again
+and treats the matches in the same manner as the specified builtin
+widget, in this case \fBexpand\-or\-complete\fP\&.
+.PP
+.PP
+.SH "SPECIAL PARAMETERS"
+.PP
+Inside completion widgets, and any functions called from them, some
+parameters have special meaning; outside these functions they are not
+special to the shell in any way\&.  These parameters are used to pass
+information between the completion code and the completion widget\&. Some of
+the builtin commands and the condition codes use or change the current
+values of these parameters\&.  Any existing values will be hidden during
+execution of completion widgets; except for \fBcompstate\fP, the parameters
+are reset on each function exit (including nested function calls from
+within the completion widget) to the values they had when the function was
+entered\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBCURRENT\fP
+This is the number of the current word, i\&.e\&. the word the cursor is
+currently on in the \fBwords\fP array\&.  Note that this value is only
+correct if the \fBksharrays\fP option is not set\&.
+.TP
+\fBIPREFIX\fP
+Initially this will be set to the empty string\&.  This parameter functions
+like \fBPREFIX\fP; it contains a string which precedes the one in \fBPREFIX\fP
+and is not considered part of the list of matches\&.  Typically, a string is
+transferred from the beginning of \fBPREFIX\fP to the end of \fBIPREFIX\fP, for
+example:
+.RS
+.PP
+.RS
+.nf
+\fBIPREFIX=${PREFIX%%\e=*}=
+PREFIX=${PREFIX#*=}\fP
+.fi
+.RE
+.PP
+causes the part of the prefix up to and including the first equal sign not
+to be treated as part of a matched string\&.  This can be done automatically
+by the \fBcompset\fP builtin, see below\&.
+.RE
+.TP
+\fBISUFFIX\fP
+As \fBIPREFIX\fP, but for a suffix that should not be considered part
+of the matches; note that the \fBISUFFIX\fP string follows the \fBSUFFIX\fP
+string\&.
+.TP
+\fBPREFIX\fP
+Initially this will be set to the part of the current word from the
+beginning of the word up to the position of the cursor; it may be altered
+to give a common prefix for all matches\&.
+.TP
+\fBQIPREFIX\fP
+This parameter is read\-only and contains the quoted string up to the
+word being completed\&. E\&.g\&. when completing `\fB"foo\fP', this parameter
+contains the double quote\&. If the \fB\-q\fP option of \fBcompset\fP is used 
+(see below), and the original string was `\fB"foo bar\fP' with the
+cursor on the `\fBbar\fP', this parameter contains `\fB"foo \fP'\&.
+.TP
+\fBQISUFFIX\fP
+Like \fBQIPREFIX\fP, but containing the suffix\&.
+.TP
+\fBSUFFIX\fP
+Initially this will be set to the part of the current word from the
+cursor position to the end; it may be altered to give a common suffix for
+all matches\&.  It is most useful when the option \fBCOMPLETE_IN_WORD\fP is
+set, as otherwise the whole word on the command line is treated as a
+prefix\&.
+.TP
+\fBcompstate\fP
+This is an associative array with various keys and values that the
+completion code uses to exchange information with the completion widget\&.
+The keys are:
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fBall_quotes\fP
+The \fB\-q\fP option of the \fBcompset\fP builtin command (see below)
+allows a quoted string to be broken into separate words; if the cursor is
+on one of those words, that word will be completed, possibly invoking
+`\fBcompset \-q\fP' recursively\&.  With this key it is possible to test the
+types of quoted strings which are currently broken into parts in this
+fashion\&.  Its value contains one character for each quoting level\&.  The
+characters are a single quote or a double quote for strings quoted with
+these characters and a backslash for strings not starting with a quote
+character\&.  The first character in the value always corresponds to the
+innermost quoting level\&.
+.TP
+\fBcontext\fP
+This will be set by the completion code to the overall context
+in which completion is attempted\&. Possible values are:
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fBarray_value\fP
+when completing inside the value of an array parameter assignment; in
+this case the \fBwords\fP array contains the words inside the parentheses\&.
+.TP
+\fBbrace_parameter\fP
+when completing the name of a parameter in a parameter expansion beginning
+with \fB${\fP\&.
+.TP
+\fBassign_parameter\fP
+when completing the name of a parameter in a parameter assignment\&.
+.TP
+\fBcommand\fP
+when completing for a normal command (either in command position or for
+an argument of the command)\&.
+.TP
+\fBcondition\fP
+when completing inside a `\fB[[\fP\&.\&.\&.\fB]]\fP' conditional expression; in
+this case the \fBwords\fP array contains only the words inside the
+conditional expression\&.
+.TP
+\fBmath\fP
+when completing in a mathematical environment such as a
+`\fB((\fP\&.\&.\&.\fB))\fP' construct\&.
+.TP
+\fBparameter\fP
+when completing the name of a parameter in a parameter expansion beginning
+with \fB$\fP but not \fB${\fP\&.
+.TP
+\fBredirect\fP
+when completing after a redirection operator\&.
+.TP
+\fBsubscript\fP
+when completing inside a parameter subscript\&.
+.TP
+\fBvalue\fP
+when completing the value of a parameter assignment\&.
+.RE
+.TP
+\fBexact\fP
+Controls the behaviour when the \fBREC_EXACT\fP option is set\&.  It will be
+set to \fBaccept\fP if an exact match would be accepted, and will be unset
+otherwise\&.
+.RS
+.PP
+If it was set when at least one match equal to the string on the line
+was generated, the match is accepted\&.
+.RE
+.TP
+\fBexact_string\fP
+The string of an exact match if one was found, otherwise unset\&.
+.TP
+\fBignored\fP
+The number of words that were ignored because they matched one of the
+patterns given with the \fB\-F\fP option to the \fBcompadd\fP builtin
+command\&.
+.TP
+\fBinsert\fP
+This controls the manner in which a match is inserted into the command
+line\&.  On entry to the widget function, if it is unset the command line is
+not to be changed; if set to \fBunambiguous\fP, any prefix common to all
+matches is to be inserted; if set to \fBautomenu\-unambiguous\fP, the
+common prefix is to be inserted and the next invocation of the
+completion code may start menu completion (due to the \fBAUTO_MENU\fP
+option being set); if set to \fBmenu\fP or \fBautomenu\fP menu completion
+will be started for the matches currently generated (in the
+latter case this will happen because the \fBAUTO_MENU\fP is set)\&. The
+value may also contain the string `\fBtab\fP' when the completion code
+would normally not really do completion, but only insert the TAB
+character\&.
+.RS
+.PP
+On exit it may be set to any of the values above (where setting it to
+the empty string is the same as unsetting it), or to a number, in which
+case the match whose number is given will be inserted into the command line\&.
+Negative numbers count backward from the last match (with `\fB\-1\fP'
+selecting the last match) and out\-of\-range values are wrapped
+around, so that a value of zero selects the last match and a value
+one more than the maximum selects the first\&. Unless the value of this
+key ends in a space, the match is inserted as in a menu completion,
+i\&.e\&. without automatically appending a space\&.
+.PP
+Both \fBmenu\fP and \fBautomenu\fP may also specify the the number of the
+match to insert, given after a colon\&.  For example, `\fBmenu:2\fP' says
+to start menu completion, beginning with the second match\&.
+.PP
+Note that a value containing the substring `\fBtab\fP' makes the
+matches generated be ignored and only the TAB be inserted\&.
+.PP
+Finally, it may also be set to \fBall\fP, which makes all matches
+generated be inserted into the line\&.
+.RE
+.TP
+\fBinsert_positions\fP
+When the completion system inserts an unambiguous string into the
+line, there may be multiple places where characters are missing or
+where the character inserted differs from at least one match\&.  The
+value of this key contains a colon separated list of all these
+positions, as indexes into the command line\&.
+.TP
+\fBlast_prompt\fP
+If this is set to a non\-empty string for every match added, the
+completion code will move the cursor back to the previous prompt after
+the list of completions has been displayed\&.  Initially this is set or
+unset according to the \fBALWAYS_LAST_PROMPT\fP option\&.
+.TP
+\fBlist\fP
+This controls whether or how the list of matches will be displayed\&.  If it
+is unset or empty they will never be listed; if its value begins with
+\fBlist\fP, they will always be listed; if it begins with \fBautolist\fP
+or \fBambiguous\fP, they will be listed when the \fBAUTO_LIST\fP or
+\fBLIST_AMBIGUOUS\fP options respectively would normally cause them to
+be\&.
+.RS
+.PP
+If the substring \fBforce\fP appears in the value, this makes the
+list be shown even if there is only one match\&. Normally, the list
+would be shown only if there are at least two matches\&.
+.PP
+The value contains the substring \fBpacked\fP if the \fBLIST_PACKED\fP
+option is set\&. If this substring is given for all matches added to a
+group, this group will show the \fBLIST_PACKED\fP behavior\&. The same is
+done for the \fBLIST_ROWS_FIRST\fP option with the substring \fBrows\fP\&.
+.PP
+Finally, if the value contains the string \fBexplanations\fP, only the
+explanation strings, if any, will be listed and if it contains
+\fBmessages\fP, only the messages (added with the \fB\-x\fP option of
+\fBcompadd\fP) will be listed\&.  If it contains both \fBexplanations\fP and 
+\fBmessages\fP both kinds of explanation strings will be listed\&.  It
+will be set appropriately on entry to a completion widget and may be
+changed there\&.
+.RE
+.TP
+\fBlist_lines\fP
+This gives the number of lines that are needed to display the full
+list of completions\&.  Note that to calculate the total number of lines
+to display you need to add the number of lines needed for the command
+line to this value, this is available as the value of the \fBBUFFERLINES\fP
+special parameter\&.
+.TP
+\fBlist_max\fP
+Initially this is set to the value of the \fBLISTMAX\fP parameter\&.
+It may be set to any other value; when the widget exits this value
+will be used in the same way as the value of \fBLISTMAX\fP\&.
+.TP
+\fBnmatches\fP
+The number of matches generated and accepted by the completion code so
+far\&.
+.TP
+\fBold_insert\fP
+On entry to the widget this will be set to the number of the match of
+an old list of completions that is currently inserted into the command
+line\&. If no match has been inserted, this is unset\&.
+.RS
+.PP
+As with \fBold_list\fP, the value of this key will only be used if it is the
+string \fBkeep\fP\&. If it was set to this value by the widget and there was an
+old match inserted into the command line, this match will be kept and if
+the value of the \fBinsert\fP key specifies that another match should be
+inserted, this will be inserted after the old one\&.
+.RE
+.TP
+\fBold_list\fP
+This is set to \fByes\fP if there is still a valid list of completions
+from a previous completion at the time the widget is invoked\&.  This will
+usually be the case if and only if the previous editing operation was a
+completion widget or one of the builtin completion functions\&.  If there is a
+valid list and it is also currently shown on the screen, the value of this
+key is \fBshown\fP\&.
+.RS
+.PP
+After the widget has exited the value of this key is only used if it
+was set to \fBkeep\fP\&.  In this case the completion code will continue
+to use this old list\&.  If the widget generated new matches, they will
+not be used\&.
+.RE
+.TP
+\fBparameter\fP
+The name of the parameter when completing in a subscript or in the
+value of a parameter assignment\&.
+.TP
+\fBpattern_insert\fP
+Normally this is set to \fBmenu\fP, which specifies that menu completion will
+be used whenever a set of matches was generated using pattern matching\&.  If
+it is set to any other non\-empty string by the user and menu completion is
+not selected by other option settings, the code will instead insert any
+common prefix for the generated matches as with normal completion\&.
+.TP
+\fBpattern_match\fP
+Locally controls the behaviour given by the \fBGLOB_COMPLETE\fP option\&.
+Initially it is set to `\fB*\fP' if and only if the option is set\&.
+The completion widget may set it to this value, to an empty string
+(which has the same effect as unsetting it), or to any
+other non\-empty string\&.  If it is non\-empty, unquoted metacharacters on the
+command line will be treated as patterns; if it is `\fB*\fP', then
+additionally a wildcard `\fB*\fP' is assumed at the cursor position; if
+it is empty or unset, metacharacters will be treated literally\&.
+.RS
+.PP
+Note that the matcher specifications given to the \fBcompadd\fP builtin
+command are not used if this is set to a non\-empty string\&.
+.RE
+.TP
+\fBquote\fP
+When completing inside quotes, this contains the quotation character
+(i\&.e\&. either a single quote, a double quote, or a backtick)\&.  Otherwise it
+is unset\&.
+.TP
+\fBquoting\fP
+When completing inside single quotes, this is set to the string
+\fBsingle\fP; inside double quotes, the string
+\fBdouble\fP; inside backticks, the string \fBbacktick\fP\&.
+Otherwise it is unset\&.
+.TP
+\fBredirect\fP
+The redirection operator when completing in a redirection position,
+i\&.e\&. one of \fB<\fP, \fB>\fP, etc\&.
+.TP
+\fBrestore\fP
+This is set to \fBauto\fP before a function is entered, which forces the
+special parameters mentioned above (\fBwords\fP, \fBCURRENT\fP, \fBPREFIX\fP,
+\fBIPREFIX\fP, \fBSUFFIX\fP, and \fBISUFFIX\fP) to be restored to their
+previous values when the function exits\&.   If a function unsets it or
+sets it to any other string, they will not be restored\&.
+.TP
+\fBto_end\fP
+Specifies the occasions on which the cursor is moved to the end of a string
+when a match is inserted\&.  On entry to a widget function, it may be
+\fBsingle\fP if this will happen when a single unambiguous match was inserted
+or \fBmatch\fP if it will happen any time a match is inserted (for example,
+by menu completion; this is likely to be the effect of the \fBALWAYS_TO_END\fP
+option)\&.
+.RS
+.PP
+On exit, it may be set to \fBsingle\fP as above\&.  It may also be set to
+\fBalways\fP, or to the empty string or unset; in those cases the cursor will
+be moved to the end of the string always or never respectively\&.  Any
+other string is treated as \fBmatch\fP\&.
+.RE
+.TP
+\fBunambiguous\fP
+This key is read\-only and will always be set to the common (unambiguous)
+prefix the completion code has generated for all matches added so far\&.
+.TP
+\fBunambiguous_cursor\fP
+This gives the position the cursor would be placed at if the
+common prefix in the \fBunambiguous\fP key were inserted, relative to
+the value of that key\&. The cursor would be placed before the character
+whose index is given by this key\&.
+.TP
+\fBunambiguous_positions\fP
+This contains all positions where characters in the unambiguous string
+are missing or where the character inserted differs from at least one
+of the matches\&.  The positions are given as indexes into the string
+given by the value of the \fBunambiguous\fP key\&.
+.TP
+\fBvared\fP
+If completion is called while editing a line using the \fBvared\fP
+builtin, the value of this key is set to the name of the parameter
+given as an argument to \fBvared\fP\&.  This key is only set while a \fBvared\fP
+command is active\&.
+.RE
+.TP
+\fBwords\fP
+This array contains the words present on the command line currently being
+edited\&.
+.PP
+.SH "BUILTIN COMMANDS"
+.PD 0
+.TP
+.PD 0
+\fBcompadd\fP [ \fB\-akqQfenUl12C\fP ] [ \fB\-F\fP \fIarray\fP ]
+.TP
+.PD 0
+[ \fB\-P\fP \fIprefix\fP ] [ \fB\-S\fP \fIsuffix\fP ]
+.TP
+.PD 0
+[ \fB\-p\fP \fIhidden\-prefix\fP ] [ \fB\-s\fP \fIhidden\-suffix\fP ]
+.TP
+.PD 0
+[ \fB\-i\fP \fIignored\-prefix\fP ] [ \fB\-I\fP \fIignored\-suffix\fP ]
+.TP
+.PD 0
+[ \fB\-W\fP \fIfile\-prefix\fP ] [ \fB\-d\fP \fIarray\fP ]
+.TP
+.PD 0
+[ \fB\-J\fP \fIname\fP ] [ \fB\-V\fP \fIname\fP ] [ \fB\-X\fP \fIexplanation\fP ] [ \fB\-x\fP \fImessage\fP ]
+.TP
+.PD 0
+[ \fB\-r\fP \fIremove\-chars\fP ] [ \fB\-R\fP \fIremove\-func\fP ]
+.TP
+.PD 0
+[ \fB\-D\fP \fIarray\fP ] [ \fB\-O\fP \fIarray\fP ] [ \fB\-A\fP \fIarray\fP ]
+.TP
+.PD 0
+[ \fB\-E\fP \fInumber\fP ]
+.TP
+.PD
+[ \fB\-M\fP \fImatch\-spec\fP ] [ \fB\-\-\fP ] [ \fIwords\fP \&.\&.\&. ]
+.RS
+.PP
+This builtin command can be used to add matches directly and control
+all the information the completion code stores with each possible
+match\&. The return value is zero if at least one match was added and
+non\-zero if no matches were added\&.
+.PP
+The completion code breaks the string to complete into seven fields in
+the order: 
+.PP
+.RS
+.nf
+\fI<ipre><apre><hpre><word><hsuf><asuf><isuf>\fP
+.fi
+.RE
+.PP
+The first field
+is an ignored prefix taken from the command line, the contents of the
+\fBIPREFIX\fP parameter plus the string given with the \fB\-i\fP
+option\&. With the \fB\-U\fP option, only the string from the \fB\-i\fP
+option is used\&. The field \fI<apre>\fP is an optional prefix string
+given with the \fB\-P\fP option\&.  The \fI<hpre>\fP field is a string
+that is considered part of the match but that should not be shown when 
+listing completions, given with the \fB\-p\fP option; for example,
+functions that do filename generation might specify
+a common path prefix this way\&.  \fI<word>\fP is the part of the match that
+should appear in the list of completions, i\&.e\&. one of the \fIwords\fP given
+at the end of the \fBcompadd\fP command line\&. The suffixes \fI<hsuf>\fP,
+\fI<asuf>\fP and \fI<isuf>\fP correspond to the prefixes \fI<hpre>\fP,
+\fI<apre>\fP and \fI<ipre>\fP and are given by the options \fB\-s\fP, \fB\-S\fP and
+\fB\-I\fP, respectively\&.
+.PP
+The supported flags are:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-P\fP \fIprefix\fP
+This gives a string to be inserted before the given \fIwords\fP\&.  The
+string given is not considered as part of the match and any shell
+metacharacters in it will not be quoted when the string is inserted\&.
+.TP
+\fB\-S\fP \fIsuffix\fP
+Like \fB\-P\fP, but gives a string to be inserted after the match\&.
+.TP
+\fB\-p\fP \fIhidden\-prefix\fP
+This gives a string that should be inserted into the command line before the
+match but that should not appear in the list of matches\&. Unless the
+\fB\-U\fP option is given, this string must be matched as part of the string
+on the command line\&.
+.TP
+\fB\-s\fP \fIhidden\-suffix\fP
+Like `\fB\-p\fP', but gives a string to insert after the match\&.
+.TP
+\fB\-i\fP \fIignored\-prefix\fP
+This gives a string to insert into the command line just before any
+string given with the `\fB\-P\fP' option\&.  Without `\fB\-P\fP' the string is
+inserted before the string given with `\fB\-p\fP' or directly before the
+match\&.
+.TP
+\fB\-I\fP \fIignored\-suffix\fP
+Like \fB\-i\fP, but gives an ignored suffix\&.
+.TP
+\fB\-a\fP
+With this flag the \fIwords\fP are taken as names of arrays and the
+possible matches are their values\&.  If only some elements of the
+arrays are needed, the \fIwords\fP may also contain subscripts, as in
+`\fBfoo[2,\-1]\fP'\&.
+.TP
+\fB\-k\fP
+With this flag the \fIwords\fP are taken as names of associative arrays
+and the possible matches are their keys\&.  As for \fB\-a\fP, the
+\fIwords\fP may also contain subscripts, as in `\fBfoo[(R)*bar*]\fP'\&.
+.TP
+\fB\-d\fP \fIarray\fP
+This adds per\-match display strings\&. The \fIarray\fP should contain one 
+element per \fIword\fP given\&. The completion code will then display the 
+first element instead of the first \fIword\fP, and so on\&. The
+\fIarray\fP may be given as the name of an array parameter or directly
+as a space\-separated list of words in parentheses\&.
+.RS
+.PP
+If there are fewer display strings than \fIwords\fP, the leftover
+\fIwords\fP will be displayed unchanged and if there are more display
+strings than \fIwords\fP, the leftover display strings will be silently
+ignored\&.
+.RE
+.TP
+\fB\-l\fP
+This option only has an effect if used together with the \fB\-d\fP
+option\&. If it is given, the display strings are listed one per line,
+not arrayed in columns\&.
+.TP
+\fB\-J\fP \fIname\fP
+Gives the name of the group of matches the words should be stored in\&.
+.TP
+\fB\-V\fP \fIname\fP
+Like \fB\-J\fP but naming a unsorted group\&. These are in a different name 
+space than groups created with the \fB\-J\fP flag\&.
+.TP
+\fB\-1\fP
+If given together with the \fB\-V\fP option, makes
+only consecutive duplicates in the group be removed\&. If combined with
+the \fB\-J\fP option, this has no visible effect\&. Note that groups
+with and without this flag are in different name spaces\&.
+.TP
+\fB\-2\fP
+If given together with the \fB\-J\fP or \fB\-V\fP option, makes all
+duplicates be kept\&. Again, groups with and without this flag are in
+different name spaces\&.
+.TP
+\fB\-X\fP \fIexplanation\fP
+The \fIexplanation\fP string will be printed with the list of matches,
+above the group currently selected\&.
+.TP
+\fB\-x\fP \fImessage\fP
+Like \fB\-X\fP, but the \fImessage\fP will be printed even if there are no 
+matches in the group\&.
+.TP
+\fB\-q\fP
+The suffix given with \fB\-S\fP will be automatically removed if 
+the next character typed is a blank or does not insert anything, or if
+the suffix consists of only one character and the next character typed 
+is the same character\&.
+.TP
+\fB\-r\fP \fIremove\-chars\fP
+This is a more versatile form of the \fB\-q\fP option\&.
+The suffix given with \fB\-S\fP or the slash automatically added after
+completing directories will be automatically removed if
+the next character typed inserts one of the characters given in the
+\fIremove\-chars\fP\&.  This string is parsed as a characters class and
+understands the backslash sequences used by the \fBprint\fP command\&.  For
+example, `\fB\-r "a\-z\et"\fP' removes the suffix if the next character typed
+inserts a lowercase character or a TAB, and `\fB\-r "^0\-9"\fP' removes the
+suffix if the next character typed inserts anything but a digit\&. One extra
+backslash sequence is understood in this string: `\fB\e\-\fP' stands for
+all characters that insert nothing\&. Thus `\fB\-S "=" \-q\fP' is the same
+as `\fB\-S "=" \-r "= \et\en\e\-"\fP'\&.
+.RS
+.PP
+This option may also be used without the \fB\-S\fP option; then any
+automatically added space will be removed when one of the characters in the
+list is typed\&.
+.RE
+.TP
+\fB\-R\fP \fIremove\-func\fP
+This is another form of the \fB\-r\fP option\&. When a suffix 
+has been inserted and the completion accepted, the function
+\fIremove\-func\fP will be called after the next character typed\&.  It is
+passed the length of the suffix as an argument and can use the special
+parameters available in ordinary (non\-completion) zle widgets (see
+\fIzshzle\fP(1)) to analyse and modify the command line\&.
+.TP
+\fB\-f\fP
+If this flag is given, all of the matches built from \fIwords\fP are
+marked as being the names of files\&.  They are not required to be actual
+filenames, but if they are, and the option \fBLIST_TYPES\fP is set, the
+characters describing the types of the files in the completion lists will
+be shown\&. This also forces a slash to be added when the name of a
+directory is completed\&.
+.TP
+\fB\-e\fP
+This flag can be used to tell the completion code that the matches
+added are parameter names for a parameter expansion\&. This will make
+the \fBAUTO_PARAM_SLASH\fP and \fBAUTO_PARAM_KEYS\fP options be used for
+the matches\&.
+.TP
+\fB\-W\fP \fIfile\-prefix\fP
+This string is a pathname that will be
+prepended to each of the matches formed by the given \fIwords\fP together 
+with any prefix specified by the \fB\-p\fP option to form a complete filename
+for testing\&.  Hence it is only useful if combined with the \fB\-f\fP flag, as
+the tests will not otherwise be performed\&.
+.TP
+\fB\-F\fP \fIarray\fP
+Specifies an array containing patterns\&. Words matching one of these
+patterns are ignored, i\&.e\&. not considered to be possible matches\&.
+.RS
+.PP
+The \fIarray\fP may be the name of an array parameter or a list of
+literal patterns enclosed in parentheses and quoted, as in `\fB\-F "(*?\&.o
+*?\&.h)"\fP'\&. If the name of an array is given, the elements of the array are
+taken as the patterns\&.
+.RE
+.TP
+\fB\-Q\fP
+This flag instructs the completion 
+code not to quote any metacharacters in the words when inserting them
+into the command line\&.
+.TP
+\fB\-M\fP \fImatch\-spec\fP
+This gives local match specifications as described below in
+the section `Matching Control'\&. This option may be given more than once\&. In 
+this case all \fImatch\-spec\fPs given are concatenated with spaces
+between them to form the specification string to use\&.
+Note that they will only be used if the \fB\-U\fP option is not given\&.
+.TP
+\fB\-n\fP
+Specifies that the words added are to be used as possible
+matches, but are not to appear in the completion listing\&.
+.TP
+\fB\-U\fP
+If this flag is given, all words given will be accepted and no matching
+will be done by the completion code\&. Normally this is used in
+functions that do the matching themselves\&.
+.TP
+\fB\-O\fP \fIarray\fP
+If this option is given, the \fIwords\fP are \fInot\fP added to the set of
+possible completions\&.  Instead, matching is done as usual and all of the
+\fIwords\fP given as arguments that match the string on the command line
+will be stored in the array parameter whose name is given as \fIarray\fP\&.
+.TP
+\fB\-A\fP \fIarray\fP
+As the \fB\-O\fP option, except that instead of those of the \fIwords\fP which
+match being stored in \fIarray\fP, the strings generated internally by the
+completion code are stored\&. For example,
+with a matching specification of `\fB\-M "L:|no="\fP', the string `\fBnof\fP'
+on the command line and the string `\fBfoo\fP' as one of the \fIwords\fP, this
+option stores the string `\fBnofoo\fP' in the array, whereas the \fB\-O\fP
+option stores the `\fBfoo\fP' originally given\&.
+.TP
+\fB\-D\fP \fIarray\fP
+As with \fB\-O\fP, the \fIwords\fP are not added to the set of possible
+completions\&.  Instead, the completion code tests whether each \fIword\fP 
+in turn matches what is on the line\&.  If the \fIn\fP'th \fIword\fP does not
+match, the \fIn\fP'th element of the \fIarray\fP is removed\&.  Elements
+for which the corresponding \fIword\fP is matched are retained\&.
+.TP
+\fB\-C\fP
+This option adds a special match which expands to all other matches
+when inserted into the line, even those that are added after this
+option is used\&.  Together with the \fB\-d\fP option it is possible to
+specify a string that should be displayed in the list for this special 
+match\&.  If no string is given, it will be shown as a string containing 
+the strings that would be inserted for the other matches, truncated to 
+the width of the screen\&.
+.TP
+\fB\-E\fP
+This option adds \fInumber\fP empty matches after the \fIwords\fP have
+been added\&.  An empty match takes up space in completion listings but
+will never be inserted in the line and can't be selected with menu
+completion or menu selection\&.  This makes empty matches only useful to
+format completion lists and to make explanatory string be shown in
+completion lists (since empty matches can be given display strings
+with the \fB\-d\fP option)\&.  And because all but one empty string would
+otherwise be removed, this option implies the \fB\-V\fP and \fB\-2\fP
+options (even if an explicit \fB\-J\fP option is given)\&.
+.TP
+.PD 0
+\fB\-\fP
+.TP
+.PD
+\fB\-\fP\fB\-\fP
+This flag ends the list of flags and options\&. All arguments after it
+will be taken as the words to use as matches even if they begin with
+hyphens\&.
+.PP
+Except for the \fB\-M\fP flag, if any of these flags is given more than
+once, the first one (and its argument) will be used\&.
+.RE
+.TP
+.PD 0
+\fBcompset \-p\fP \fInumber\fP
+.TP
+.PD 0
+\fBcompset \-P\fP [ \fInumber\fP ] \fIpattern\fP
+.TP
+.PD 0
+\fBcompset \-s\fP \fInumber\fP
+.TP
+.PD 0
+\fBcompset \-S\fP [ \fInumber\fP ] \fIpattern\fP
+.TP
+.PD 0
+\fBcompset \-n\fP \fIbegin\fP [ \fIend\fP ]
+.TP
+.PD 0
+\fBcompset \-N\fP \fIbeg\-pat\fP [ \fIend\-pat\fP ]
+.TP
+.PD
+\fBcompset \-q\fP
+This command simplifies modification of the special parameters,
+while its return value allows tests on them to be carried out\&.
+.RS
+.PP
+The options are:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-p\fP \fInumber\fP
+If the contents of the \fBPREFIX\fP parameter is longer than \fInumber\fP
+characters, the first \fInumber\fP characters are removed from it and
+appended to the contents of the \fBIPREFIX\fP parameter\&.
+.TP
+\fB\-P\fP [ \fInumber\fP ] \fIpattern\fP
+If the value of the \fBPREFIX\fP parameter begins with anything that
+matches the \fIpattern\fP, the matched portion is removed from
+\fBPREFIX\fP and appended to \fBIPREFIX\fP\&.
+.RS
+.PP
+Without the optional \fInumber\fP, the longest match is taken, but
+if \fInumber\fP is given, anything up to the \fInumber\fP'th match is
+moved\&.  If the \fInumber\fP is negative, the \fInumber\fP'th longest
+match is moved\&. For example, if \fBPREFIX\fP contains the string
+`\fBa=b=c\fP', then \fBcompset \-P '*\e='\fP will move the string `\fBa=b=\fP' 
+into the \fBIPREFIX\fP parameter, but \fBcompset \-P 1 '*\e='\fP will move only
+the string `\fBa=\fP'\&.
+.RE
+.TP
+\fB\-s\fP \fInumber\fP
+As \fB\-p\fP, but transfer the last \fInumber\fP characters from the
+value of \fBSUFFIX\fP to the front of the value of \fBISUFFIX\fP\&.
+.TP
+\fB\-S\fP [ \fInumber\fP ] \fIpattern\fP
+As \fB\-P\fP, but match the last portion of \fBSUFFIX\fP and transfer the
+matched portion to the front of the value of \fBISUFFIX\fP\&.
+.TP
+\fB\-n\fP \fIbegin\fP [ \fIend\fP ]
+If the current word position as specified by the parameter \fBCURRENT\fP 
+is greater than or equal to \fIbegin\fP, anything up to the
+\fIbegin\fP'th word is removed from the \fBwords\fP array and the value
+of the parameter \fBCURRENT\fP is decremented by \fIbegin\fP\&.
+.RS
+.PP
+If the optional \fIend\fP is given, the modification is done only if
+the current word position is also less than or equal to \fIend\fP\&. In
+this case, the words from position \fIend\fP onwards are also removed from
+the \fBwords\fP array\&.
+.PP
+Both \fIbegin\fP and \fIend\fP may be negative to count backwards
+from the last element of the \fBwords\fP array\&.
+.RE
+.TP
+\fB\-N\fP \fIbeg\-pat\fP [ \fIend\-pat\fP ]
+If one of the elements of the \fBwords\fP array before the one at the
+index given by the value of the parameter \fBCURRENT\fP matches the
+pattern \fIbeg\-pat\fP, all elements up to and including the matching one are
+removed from the \fBwords\fP array and the value of \fBCURRENT\fP is changed to
+point to the same word in the changed array\&.
+.RS
+.PP
+If the optional pattern \fIend\-pat\fP is also given, and there is an
+element in the \fBwords\fP array matching this pattern, the parameters
+are modified only if the index of this word is higher than the one
+given by the \fBCURRENT\fP parameter (so that the matching word has 
+to be after the cursor)\&. In this case, the words starting with the one
+matching \fBend\-pat\fP are also removed from the \fBwords\fP
+array\&. If \fBwords\fP contains no word matching \fIend\-pat\fP, the
+testing and modification is performed as if it were not given\&.
+.RE
+.TP
+\fB\-q\fP
+The word
+currently being completed is split on spaces into separate words,
+respecting the usual shell quoting conventions\&.  The 
+resulting words are stored in the \fBwords\fP array, and \fBCURRENT\fP,
+\fBPREFIX\fP, \fBSUFFIX\fP, \fBQIPREFIX\fP, and \fBQISUFFIX\fP are modified to
+reflect the word part that is completed\&.
+.PP
+In all the above cases the return value is zero if the test succeeded
+and the parameters were modified and non\-zero otherwise\&. This allows
+one to use this builtin in tests such as:
+.PP
+.RS
+.nf
+\fBif compset \-P '*\e='; then \&.\&.\&.\fP
+.fi
+.RE
+.PP
+This forces anything up to and including the last equal sign to be
+ignored by the completion code\&.
+.RE
+.TP
+\fBcompcall\fP [ \fB\-TD\fP ]
+This allows the use of completions defined with the \fBcompctl\fP builtin
+from within completion widgets\&.  The list of matches will be generated as
+if one of the non\-widget completion function (\fBcomplete\-word\fP, etc\&.)
+had been called, except that only \fBcompctl\fPs given for specific commands
+are used\&. To force the code to try completions defined with the \fB\-T\fP
+option of \fBcompctl\fP and/or the default completion (whether defined by
+\fBcompctl \-D\fP or the builtin default) in the appropriate places, the
+\fB\-T\fP and/or \fB\-D\fP flags can be passed to \fBcompcall\fP\&.
+.RS
+.PP
+The return value can be used to test if a matching \fBcompctl\fP
+definition was found\&. It is non\-zero if a \fBcompctl\fP was found and
+zero otherwise\&.
+.PP
+Note that this builtin is defined by the \fBzsh/compctl\fP module\&.
+.RE
+.RE
+.PP
+.SH "CONDITION CODES"
+.PP
+The following additional condition codes for use within the \fB[[ \&.\&.\&. ]]\fP
+construct are available in completion widgets\&.  These work on the special
+parameters\&.  All of these tests can also be performed by the \fBcompset\fP
+builtin, but in the case of the condition codes the contents of the special
+parameters are not modified\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB\-prefix\fP [ \fInumber\fP ] \fIpattern\fP
+true if the test for the \fB\-P\fP option of \fBcompset\fP would succeed\&.
+.TP
+\fB\-suffix\fP [ \fInumber\fP ] \fIpattern\fP
+true if the test for the \fB\-S\fP option of \fBcompset\fP would succeed\&.
+.TP
+\fB\-after\fP \fIbeg\-pat\fP
+true if the test of the \fB\-N\fP option with only the \fIbeg\-pat\fP given 
+would succeed\&.
+.TP
+\fB\-between\fP \fIbeg\-pat end\-pat\fP
+true if the test for the \fB\-N\fP option with both patterns would succeed\&.
+.PP
+.SH "MATCHING CONTROL"
+.PP
+It is possible by use of the
+\fB\-M\fP option of the \fBcompadd\fP builtin command to specify how the
+characters in the string to be completed (referred to here as the
+command line) map onto the characters in the list of matches produced by
+the completion code (referred to here as the trial completions)\&. Note
+that this is not used if the command line contains a glob pattern and
+the \fBGLOB_COMPLETE\fP option is set or the \fBpattern_match\fP of the
+\fBcompstate\fP special association is set to a non\-empty string\&.
+.PP
+The \fImatch\-spec\fP given as the argument to the \fB\-M\fP option (see
+`Builtin Commands' above) consists of one or more matching descriptions separated by
+whitespace\&.  Each description consists of a letter followed by a colon
+and then the patterns describing which character sequences on the line match
+which character sequences in the trial completion\&.  Any sequence of
+characters not handled in this fashion must match exactly, as usual\&.
+.PP
+The forms of \fImatch\-spec\fP understood are as follows\&. In each case, the
+form with an uppercase initial character retains the string already
+typed on the command line as the final result of completion, while with
+a lowercase initial character the string on the command line is changed
+into the corresponding part of the trial completion\&.
+.PP
+.PD 0
+.TP
+.PD 0
+\fBm:\fP\fIlpat\fP\fB=\fP\fItpat\fP
+.TP
+.PD
+\fBM:\fP\fIlpat\fP\fB=\fP\fItpat\fP
+Here, \fIlpat\fP is a pattern that matches on the command line,
+corresponding to \fItpat\fP which matches in the trial completion\&.
+.TP
+.PD 0
+\fBl:\fP\fIlanchor\fP\fB|\fP\fIlpat\fP\fB=\fP\fItpat\fP
+.TP
+.PD 0
+\fBL:\fP\fIlanchor\fP\fB|\fP\fIlpat\fP\fB=\fP\fItpat\fP
+.TP
+.PD 0
+\fBl:\fP\fIlanchor\fP\fB||\fP\fIranchor\fP\fB=\fP\fItpat\fP
+.TP
+.PD 0
+\fBL:\fP\fIlanchor\fP\fB||\fP\fIranchor\fP\fB=\fP\fItpat\fP
+.TP
+.PD 0
+\fBb:\fP\fIlpat\fP\fB=\fP\fItpat\fP
+.TP
+.PD
+\fBB:\fP\fIlpat\fP\fB=\fP\fItpat\fP
+These letters are for patterns that are anchored by another pattern on
+the left side\&. Matching for \fIlpat\fP and \fItpat\fP is as for \fBm\fP and
+\fBM\fP, but the pattern \fIlpat\fP matched on the command line must be
+preceded by the pattern \fIlanchor\fP\&.  The \fIlanchor\fP can be blank to
+anchor the match to the start of the command line string; otherwise the
+anchor can occur anywhere, but must match in both the command line and
+trial completion strings\&.
+.RS
+.PP
+If no \fIlpat\fP is given but a \fIranchor\fP is, this matches the gap
+between substrings matched by \fIlanchor\fP and \fIranchor\fP\&. Unlike
+\fIlanchor\fP, the \fIranchor\fP only needs to match the trial
+completion string\&.
+.PP
+The \fBb\fP and \fBB\fP forms are similar to \fBl\fP and \fBL\fP with an empty 
+anchor, but need to match only the beginning of the trial completion
+or the word on the command line, respectively\&.
+.RE
+.TP
+.PD 0
+\fBr:\fP\fIlpat\fP\fB|\fP\fIranchor\fP\fB=\fP\fItpat\fP
+.TP
+.PD 0
+\fBR:\fP\fIlpat\fP\fB|\fP\fIranchor\fP\fB=\fP\fItpat\fP
+.TP
+.PD 0
+\fBr:\fP\fIlanchor\fP\fB||\fP\fIranchor\fP\fB=\fP\fItpat\fP
+.TP
+.PD 0
+\fBR:\fP\fIlanchor\fP\fB||\fP\fIranchor\fP\fB=\fP\fItpat\fP
+.TP
+.PD 0
+\fBe:\fP\fIlpat\fP\fB=\fP\fItpat\fP
+.TP
+.PD
+\fBE:\fP\fIlpat\fP\fB=\fP\fItpat\fP
+As \fBl\fP, \fBL\fP, \fBb\fP and \fBB\fP, with the difference that the command
+line and trial completion patterns are anchored on the right side\&.
+Here an empty \fIranchor\fP and the \fBe\fP and \fBE\fP forms force the
+match to the end of the trial completion or command line string\&.
+.PP
+Each \fIlpat\fP, \fItpat\fP or \fIanchor\fP is either an empty string or
+consists of a sequence of literal characters (which may be quoted with a
+backslash), question marks, character classes, and correspondence
+classes; ordinary shell patterns are not used\&.  Literal characters match
+only themselves, question marks match any character, and character
+classes are formed as for globbing and match any character in the given
+set\&.
+.PP
+Correspondence classes are defined like character classes, but with two
+differences: they are delimited by a pair of braces, and negated classes
+are not allowed, so the characters \fB!\fP and \fB^\fP have no special
+meaning directly after the opening brace\&.  They indicate that a range of
+characters on the line match a range of characters in the trial
+completion, but (unlike ordinary character classes) paired according to
+the corresponding position in the sequence\&. For example, to make any
+lowercase letter on the line match the corresponding uppercase letter in
+the trial completion, you can use `\fBm:{a\-z}={A\-Z}\fP'\&.  More than one
+pair of classes can occur, in which case the first class before the
+\fB=\fP corresponds to the first after it, and so on\&.  If one side has
+more such classes than the other side, the superfluous classes behave
+like normal character classes\&.  In anchor patterns correspondence classes
+also behave like normal character classes\&.
+.PP
+The pattern \fItpat\fP may also be one or two stars, `\fB*\fP' or
+`\fB**\fP'\&. This means that the pattern on the command line can match
+any number of characters in the trial completion\&. In this case the
+pattern must be anchored (on either side); in the case of a single
+star, the \fIanchor\fP then determines how much of the trial completion
+is to be included \-\-\- only the characters up to the next appearance of
+the anchor will be matched\&. With two stars, substrings matched by the
+anchor can be matched, too\&.
+.PP
+Examples:
+.PP
+The keys of the \fBoptions\fP association defined by the \fBparameter\fP
+module are the option names in all\-lowercase form, without
+underscores, and without the optional \fBno\fP at the beginning even
+though the builtins \fBsetopt\fP and \fBunsetopt\fP understand option names
+with uppercase letters, underscores, and the optional \fBno\fP\&.  The
+following alters the matching rules so that the prefix \fBno\fP and any
+underscore are ignored when trying to match the trial completions
+generated and uppercase letters on the line match the corresponding
+lowercase letters in the words:
+.PP
+.RS
+.nf
+\fBcompadd \-M 'L:|[nN][oO]= M:_= M:{A\-Z}={a\-z}' \- \e 
+  ${(k)options} \fP
+.fi
+.RE
+.PP
+The first part says that the pattern `\fB[nN][oO]\fP' at the beginning
+(the empty anchor before the pipe symbol) of the string on the
+line matches the empty string in the list of words generated by
+completion, so it will be ignored if present\&. The second part does the
+same for an underscore anywhere in the command line string, and the
+third part uses correspondence classes so that any
+uppercase letter on the line matches the corresponding lowercase
+letter in the word\&. The use of the uppercase forms of the
+specification characters (\fBL\fP and \fBM\fP) guarantees that what has
+already been typed on the command line (in particular the prefix
+\fBno\fP) will not be deleted\&.
+.PP
+Note that the use of \fBL\fP in the first part means that it matches
+only when at the beginning of both the command line string and the
+trial completion\&. I\&.e\&., the string `\fB_NO_f\fP' would not be
+completed to `\fB_NO_foo\fP', nor would `\fBNONO_f\fP' be completed to
+`\fBNONO_foo\fP' because of the leading underscore or the second
+`\fBNO\fP' on the line which makes the pattern fail even though they are 
+otherwise ignored\&. To fix this, one would use `\fBB:[nN][oO]=\fP'
+instead of the first part\&. As described above, this matches at the
+beginning of the trial completion, independent of other characters or
+substrings at the beginning of the command line word which are ignored
+by the same or other \fImatch\-spec\fPs\&.
+.PP
+The second example makes completion case insensitive\&.  This is just
+the same as in the option example, except here we wish to retain the
+characters in the list of completions:
+.PP
+.RS
+.nf
+\fBcompadd \-M 'm:{a\-z}={A\-Z}' \&.\&.\&. \fP
+.fi
+.RE
+.PP
+This makes lowercase letters match their uppercase counterparts\&.
+To make uppercase letters match the lowercase forms as well:
+.PP
+.RS
+.nf
+\fBcompadd \-M 'm:{a\-zA\-Z}={A\-Za\-z}' \&.\&.\&. \fP
+.fi
+.RE
+.PP
+A nice example for the use of \fB*\fP patterns is partial word
+completion\&. Sometimes you would like to make strings like `\fBc\&.s\&.u\fP'
+complete to strings like `\fBcomp\&.source\&.unix\fP', i\&.e\&. the word on the
+command line consists of multiple parts, separated by a dot in this
+example, where each part should be completed separately \-\-\- note,
+however, that the case where each part of the word, i\&.e\&. `\fBcomp\fP',
+`\fBsource\fP' and `\fBunix\fP' in this example, is to be completed from
+separate sets of matches
+is a different problem to be solved by the implementation of the
+completion widget\&.  The example can be handled by:
+.PP
+.RS
+.nf
+\fBcompadd \-M 'r:|\&.=* r:|=*' \e 
+  \- comp\&.sources\&.unix comp\&.sources\&.misc \&.\&.\&.\fP
+.fi
+.RE
+.PP
+The first specification says that \fIlpat\fP is the empty string, while
+\fIanchor\fP is a dot; \fItpat\fP is \fB*\fP, so this can match anything
+except for the `\fB\&.\fP' from the anchor in
+the trial completion word\&.  So in `\fBc\&.s\&.u\fP', the matcher sees `\fBc\fP',
+followed by the empty string, followed by the anchor `\fB\&.\fP', and
+likewise for the second dot, and replaces the empty strings before the
+anchors, giving `\fBc\fP[\fBomp\fP]\fB\&.s\fP[\fBources\fP]\fB\&.u\fP[\fBnix\fP]', where
+the last part of the completion is just as normal\&.
+.PP
+With the pattern shown above, the string `\fBc\&.u\fP' could not be
+completed to `\fBcomp\&.sources\&.unix\fP' because the single star means
+that no dot (matched by the anchor) can be skipped\&. By using two stars 
+as in `\fBr:|\&.=**\fP', however, `\fBc\&.u\fP' could be completed to
+`\fBcomp\&.sources\&.unix\fP'\&. This also shows that in some cases,
+especially if the anchor is a real pattern, like a character class,
+the form with two stars may result in more matches than one would like\&.
+.PP
+The second specification is needed to make this work when the cursor is
+in the middle of the string on the command line and the option
+\fBCOMPLETE_IN_WORD\fP is set\&. In this case the completion code would
+normally try to match trial completions that end with the string as
+typed so far, i\&.e\&. it will only insert new characters at the cursor
+position rather then at the end\&.  However in our example we would like
+the code to recognise matches which contain extra characters after the
+string on the line (the `\fBnix\fP' in the example)\&.  Hence we say that the
+empty string at the end of the string on the line matches any characters
+at the end of the trial completion\&.
+.PP
+More generally, the specification
+.PP
+.RS
+.nf
+\fBcompadd \-M 'r:|[\&.,_\-]=* r:|=*' \&.\&.\&. \fP
+.fi
+.RE
+.PP
+allows one to complete words with abbreviations before any of the
+characters in the square brackets\&.  For example, to
+complete \fBveryverylongfile\&.c\fP rather than \fBveryverylongheader\&.h\fP
+with the above in effect, you can just type \fBvery\&.c\fP before attempting
+completion\&.
+.PP
+The specifications with both a left and a right anchor are useful to
+complete partial words whose parts are not separated by some
+special character\&. For example, in some places strings have to be
+completed that are formed `\fBLikeThis\fP' (i\&.e\&. the separate parts are
+determined by a leading uppercase letter) or maybe one has to
+complete strings with trailing numbers\&. Here one could use the simple
+form with only one anchor as in:
+.PP
+.RS
+.nf
+\fBcompadd \-M 'r:|[A\-Z0\-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234\fP
+.fi
+.RE
+.PP
+But with this, the string `\fBH\fP' would neither complete to `\fBFooHoo\fP'
+nor to `\fBLikeTHIS\fP' because in each case there is an uppercase
+letter before the `\fBH\fP' and that is matched by the anchor\&. Likewise, 
+a `\fB2\fP' would not be completed\&. In both cases this could be changed
+by using `\fBr:|[A\-Z0\-9]=**\fP', but then `\fBH\fP' completes to both
+`\fBLikeTHIS\fP' and `\fBFooHoo\fP' and a `\fB2\fP' matches the other
+strings because characters can be inserted before every uppercase
+letter and digit\&. To avoid this one would use:
+.PP
+.RS
+.nf
+\fBcompadd \-M 'r:[^A\-Z0\-9]||[A\-Z0\-9]=** r:|=*' \e 
+    LikeTHIS FooHoo foo123 bar234\fP
+.fi
+.RE
+.PP
+By using these two anchors, a `\fBH\fP' matches only uppercase `\fBH\fP's that 
+are immediately preceded by something matching the left anchor
+`\fB[^A\-Z0\-9]\fP'\&. The effect is, of course, that `\fBH\fP' matches only
+the string `\fBFooHoo\fP', a `\fB2\fP' matches only `\fBbar234\fP' and so on\&.
+.PP
+When using the completion system (see
+\fIzshcompsys\fP(1)), users can define match specifications that are to be used for
+specific contexts by using the \fBmatcher\fP and \fBmatcher\-list\fP
+styles\&. The values for the latter will be used everywhere\&.
+.PP
+.SH "COMPLETION WIDGET EXAMPLE"
+.PP
+The first step is to define the widget:
+.PP
+.RS
+.nf
+\fBzle \-C complete complete\-word complete\-files\fP
+.fi
+.RE
+.PP
+Then the widget can be bound to a key using the \fBbindkey\fP builtin
+command:
+.PP
+.RS
+.nf
+\fBbindkey '^X\et' complete\fP
+.fi
+.RE
+.PP
+After that the shell function \fBcomplete\-files\fP will be invoked
+after typing control\-X and TAB\&. The function should then generate the
+matches, e\&.g\&.:
+.PP
+.RS
+.nf
+\fBcomplete\-files () { compadd \- * }\fP
+.fi
+.RE
+.PP
+This function will complete files in the current directory matching the 
+current word\&.
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshcompsys.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshcompsys.1
@@ -0,0 +1,4612 @@
+.TH "ZSHCOMPSYS" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshcompsys \- zsh completion system
+.\" Yodl file: Zsh/compsys.yo
+.SH "DESCRIPTION"
+.PP
+This describes the shell code for the new completion system\&.  It consists
+of various shell functions; those beginning `\fBcomp\fP' are to be called
+directly, while those beginning `\fB_\fP' are called by the
+completion code\&.  The shell functions of the second set, which implement
+completion behaviour and may be bound to keystrokes, are referred to
+as `widgets'\&.
+.PP
+.PP
+.SH "INITIALIZATION"
+.PP
+If the system was installed completely, it should be enough to
+call the shell function \fBcompinit\fP from your initialization file; see the
+next section\&.  However, the function \fBcompinstall\fP can be run by a user
+to configure various aspects of the completion system\&.
+.PP
+Usually, \fBcompinstall\fP will insert code into \fB\&.zshrc\fP, although if
+that is not writable it will save it in another file and tell you that
+file's location\&.  Note that it is up to you to make sure that the lines
+added to \fB\&.zshrc\fP are actually run; you may, for example, need to move
+them to an earlier place in the file if \fB\&.zshrc\fP usually returns early\&.
+So long as you keep them all together (including the comment lines at the
+start and finish), you can rerun \fBcompinstall\fP 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 \fBcompinstall\fP,
+although lines using the command `\fBzstyle\fP' should be gracefully handled\&.
+.PP
+The new code will take effect next time you start the shell, or run
+\fB\&.zshrc\fP by hand; there is also an option to make them take effect
+immediately\&.  However, if \fBcompinstall\fP has removed definitions, you will
+need to restart the shell to see the changes\&.
+.PP
+To run \fBcompinstall\fP you will need to make sure it is in a directory
+mentioned in your \fBfpath\fP parameter, which should already be the case if
+zsh was properly configured as long as your startup files do not remove the
+appropriate directories from \fBfpath\fP\&.  Then it must be autoloaded
+(`\fBautoload \-U compinstall\fP' is recommended)\&.  You can abort the
+installation any time you are being prompted for information, and your
+\fB\&.zshrc\fP will not be altered at all; changes only take place right at the
+end, where you are specifically asked for confirmation\&.
+.PP
+.SS "Use of compinit"
+.PP
+This section describes the use of \fBcompinit\fP to initialize completion for
+the current session when called directly; if you have run
+\fBcompinstall\fP it will be called automatically from your \fB\&.zshrc\fP\&.
+.PP
+To initialize the system, the function \fBcompinit\fP should be in a
+directory mentioned in the \fBfpath\fP parameter, and should be autoloaded
+(`\fBautoload \-U compinit\fP' is recommended), and then run simply as
+`\fBcompinit\fP'\&.  This will define a
+few utility functions, arrange for all the necessary shell functions to be
+autoloaded, and will then re\-define all widgets that do completion to use the
+new system\&.  If you use the \fBmenu\-select\fP widget, which is part of the
+\fBzsh/complist\fP module, you should make sure that that module is loaded
+before the call to \fBcompinit\fP so that that widget is also
+re\-defined\&.  If completion styles (see below) are set up to perform
+expansion as well as completion by default, and the TAB key is bound to
+\fBexpand\-or\-complete\fP, \fBcompinit\fP will rebind it to \fBcomplete\-word\fP;
+this is necessary to use the correct form of expansion\&.
+.PP
+Should you need to use the original completion commands, you can still
+bind keys to the old widgets by putting a `\fB\&.\fP' in front of the
+widget name, e\&.g\&. `\fB\&.expand\-or\-complete\fP'\&.
+.PP
+To speed up the running of \fBcompinit\fP, it can be made to produce a dumped
+configuration that will be read in on future invocations; this is the
+default, but can be turned off by calling \fBcompinit\fP with the
+option \fB\-D\fP\&.  The dumped file is \fB\&.zcompdump\fP in the same
+directory as the startup files (i\&.e\&. \fB$ZDOTDIR\fP or \fB$HOME\fP);
+alternatively, an explicit file name can be given by `\fBcompinit \-d\fP
+\fIdumpfile\fP'\&.  The next invocation of \fBcompinit\fP will read the dumped
+file instead of performing a full initialization\&.
+.PP
+If the number of completion files changes, \fBcompinit\fP 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 \fB#compdef\fP function (as described below)
+change, it is easiest to delete the dump file by hand so that
+\fBcompinit\fP will re\-create it the next time it is run\&.  The check
+performed to see if there are new functions can be omitted by giving
+the option \fB\-C\fP\&.  In this case the dump file will only be created if
+there isn't one already\&.
+.PP
+The dumping is actually done by another function, \fBcompdump\fP, but you
+will only need to run this yourself if you change the configuration
+(e\&.g\&. using \fBcompdef\fP) and then want to dump the new one\&.  The name of
+the old dumped file will be remembered for this purpose\&.
+.PP
+If the parameter \fB_compdir\fP is set, \fBcompinit\fP uses it as a directory
+where completion functions can be found; this is only necessary if they are
+not already in the function search path\&.
+.PP
+For security reasons \fBcompinit\fP also checks if the completion system
+would use files not owned by root or by the current user, or files in
+directories that are world\- or group\-writable or that are not owned by 
+root or by the current user\&.  If such files or directories are found,
+\fBcompinit\fP will ask if the completion system should really be used\&.  To
+avoid these tests and make all files found be used without asking, use the
+option \fB\-u\fP, and to make \fBcompinit\fP silently ignore all insecure files
+and directories use the option \fB\-i\fP\&.  This security check is skipped
+entirely when the \fB\-C\fP option is given\&.
+.PP
+The security check can be retried at any time by running the function
+\fBcompaudit\fP\&.  This is the same check used by \fBcompinit\fP, but when it
+is executed directly any changes to \fBfpath\fP are made local to the
+function so they do not persist\&.  The directories to be checked may be
+passed as arguments; if none are given, \fBcompaudit\fP uses \fBfpath\fP and
+\fB_compdir\fP to find completion system directories, adding missing ones
+to \fBfpath\fP as necessary\&.  To force a check of exactly the directories
+currently named in \fBfpath\fP, set \fB_compdir\fP to an empty string before
+calling \fBcompaudit\fP or \fBcompinit\fP\&.
+.PP
+.SS "Autoloaded files"
+.PP
+The convention for autoloaded functions used in completion is that they
+start with an underscore; as already mentioned, the \fBfpath/FPATH\fP
+parameter must contain the directory in which they are stored\&.  If \fBzsh\fP
+was properly installed on your system, then \fBfpath/FPATH\fP automatically
+contains the required directories for the standard functions\&.
+.PP
+For incomplete installations, if \fBcompinit\fP does not find enough files
+beginning with an underscore (fewer than twenty) in the search path, it
+will try to find more by adding the directory \fB_compdir\fP to the search
+path\&.  If that directory has a subdirectory named \fBBase\fP, all
+subdirectories will be added to the path\&.  Furthermore, if the subdirectory
+\fBBase\fP has a subdirectory named \fBCore\fP, \fBcompinit\fP will add all
+subdirectories of the subdirectories is to the path: this allows
+the functions to be in the same format as in the \fBzsh\fP source
+distribution\&.
+.PP
+When \fBcompinit\fP is run, it searches all such files accessible via
+\fBfpath/FPATH\fP 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
+completion system and will not be treated specially\&.
+.PP
+The tags are:
+.PP
+.PD 0
+.TP
+.PD
+\fB#compdef\fP \fInames\&.\&.\&.\fP [ \fB\-[pP]\fP \fIpatterns\&.\&.\&.\fP [ \fB\-N\fP \fInames\&.\&.\&.\fP ] ]
+The file will be made autoloadable and the function defined 
+in it will be called when completing \fInames\fP, each of which is
+either the name of a command whose arguments are to be completed or one of
+a number of special contexts in the form \fB\-\fP\fIcontext\fP\fB\-\fP described
+below\&.
+.RS
+.PP
+Each \fIname\fP may also be of the form `\fIcmd\fP\fB=\fP\fIservice\fP'\&.
+When completing the command \fIcmd\fP, the function typically behaves as
+if the command (or special context) \fIservice\fP was being completed
+instead\&.  This provides a way of altering the behaviour of functions
+that can perform many different completions\&.  It is implemented
+by setting the parameter \fB$service\fP when calling the function;
+the function may choose to interpret this how it wishes, and simpler
+functions will probably ignore it\&.
+.PP
+If the \fB#compdef\fP line contains one of the options \fB\-p\fP or \fB\-P\fP,
+the words following are taken to be patterns\&.  The function will be
+called when completion is attempted for a command or context that matches
+one of the patterns\&.  The options \fB\-p\fP and \fB\-P\fP are used to specify
+patterns to be tried before or after other completions respectively\&.
+Hence \fB\-P\fP may be used to specify default actions\&.
+.PP
+The option \fB\-N\fP is used after a list following \fB\-p\fP or \fB\-P\fP; it
+specifies that remaining words no longer define patterns\&.  It is
+possible to toggle between the three options as many times as necessary\&.
+.RE
+.TP
+\fB#compdef \-k\fP \fIstyle key\-sequences\&.\&.\&.\fP
+This option creates a widget behaving like the
+builtin widget \fIstyle\fP and binds it to the given \fIkey\-sequences\fP,
+if any\&.  The \fIstyle\fP must be one of the builtin widgets that perform
+completion, namely \fBcomplete\-word\fP, \fBdelete\-char\-or\-list\fP,
+\fBexpand\-or\-complete\fP, \fBexpand\-or\-complete\-prefix\fP, \fBlist\-choices\fP,
+\fBmenu\-complete\fP, \fBmenu\-expand\-or\-complete\fP, or
+\fBreverse\-menu\-complete\fP\&.  If the \fBzsh/complist\fP module is loaded (see
+\fIzshmodules\fP(1)) the widget \fBmenu\-select\fP is also available\&.
+.RS
+.PP
+When one of the \fIkey\-sequences\fP is typed, the function in the file will
+be invoked to generate the matches\&.  Note that a key will not be re\-bound
+if if it already was (that is, was bound to something other than
+\fBundefined\-key\fP)\&.  The widget created has the same name as the file and
+can be bound to any other keys using \fBbindkey\fP as usual\&.
+.RE
+.TP
+\fB#compdef \-K\fP \fIwidget\-name\fP \fIstyle\fP \fIkey\-sequences\fP \&.\&.\&.
+This is similar to \fB\-k\fP except that only one \fIkey\-sequences\fP
+argument may be given for each \fIwidget\-name\fP \fIstyle\fP pair\&.
+However, the entire set of three arguments may be repeated with a
+different set of arguments\&.  Note in particular that the
+\fIwidget\-name\fP must be distinct in each set\&.  If it does not begin with
+`\fB_\fP' this will be added\&.  The \fIwidget\-name\fP should not clash with
+the name of any existing widget: names based on the name of the function
+are most useful\&.  For example,
+.RS
+.PP
+.RS
+.nf
+\fB#compdef \-K _foo_complete complete\-word "^X^C" \e 
+  _foo_list list\-choices "^X^D"\fP
+.fi
+.RE
+.PP
+(all on one line) defines a widget \fB_foo_complete\fP for completion, bound
+to `\fB^X^C\fP', and a widget \fB_foo_list\fP for listing, bound to `\fB^X^D\fP'\&.
+.RE
+.TP
+\fB#autoload\fP [ \fIoptions\fP ]
+Functions with the \fB#autoload\fP tag are marked for autoloading but
+are not otherwise treated specially\&.  Typically they are to be called
+from within one of the completion functions\&.  Any \fIoptions\fP supplied
+will be passed to the \fBautoload\fP builtin; a typical use is \fB+X\fP to
+force the function to be loaded immediately\&.  Note that the \fB\-U\fP and
+\fB\-z\fP flags are always added implicitly\&.
+.PP
+The \fB#\fP is part of the tag name and no white space is allowed after it\&.
+The \fB#compdef\fP tags use the \fBcompdef\fP function described below; the
+main difference is that the name of the function is supplied implicitly\&.
+.PP
+The special contexts for which completion functions can be defined are:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-array\-value\-\fP
+The right hand side of an array\-assignment
+(`\fBfoo=(\&.\&.\&.)\fP')
+.TP
+\fB\-brace\-parameter\-\fP
+The name of a parameter expansion within braces (`\fB${\&.\&.\&.}\fP')
+.TP
+\fB\-assign\-parameter\-\fP
+The name of a parameter in an assignment, i\&.e\&. on the left hand side of
+an `\fB=\fP'
+.TP
+\fB\-command\-\fP
+A word in command position
+.TP
+\fB\-condition\-\fP
+A word inside a condition (`\fB[[\&.\&.\&.]]\fP')
+.TP
+\fB\-default\-\fP
+Any word for which no other completion is defined
+.TP
+\fB\-equal\-\fP
+A word beginning with an equals sign
+.TP
+\fB\-first\-\fP
+This is tried before any other completion function\&.  The function called
+may set the \fB_compskip\fP parameter to one of various values: 
+\fBall\fP: no further completion is attempted; a string
+containing the substring \fBpatterns\fP: no pattern completion functions
+will be called; a string containing \fBdefault\fP: the
+function for the `\fB\-default\-\fP' context will not be called, but
+functions defined for commands will
+.TP
+\fB\-math\-\fP
+Inside mathematical contexts, such as
+`\fB((\fP\&.\&.\&.\fB))\fP'
+.TP
+\fB\-parameter\-\fP
+The name of a parameter expansion (`\fB$\&.\&.\&.\fP')
+.TP
+\fB\-redirect\-\fP
+The word after a redirection operator\&.
+.TP
+\fB\-subscript\-\fP
+The contents of a parameter subscript\&.
+.TP
+\fB\-tilde\-\fP
+After an initial tilde (`\fB~\fP'), but before the first slash
+in the word\&.
+.TP
+\fB\-value\-\fP
+On the right hand side of an assignment\&.
+.PP
+Default implementations are supplied for each of these
+contexts\&.  In most cases the context \fB\-\fP\fIcontext\fP\fB\-\fP is
+implemented by a corresponding function \fB_\fP\fIcontext\fP, for example
+the context `\fB\-tilde\-\fP' and the function `\fB_tilde\fP')\&.
+.PP
+The contexts \fB\-redirect\-\fP and \fB\-value\-\fP allow extra context\-specific
+information\&.  (Internally, this is handled by the functions for each
+context calling the function \fB_dispatch\fP\&.)  The extra
+information is added separated by commas\&.
+.PP
+For the \fB\-redirect\-\fP context, the extra information is in the form
+`\fB\-redirect\-,\fP\fIop\fP\fB,\fP\fIcommand\fP', where \fIop\fP is the
+redirection operator and \fIcommand\fP is the name of the command on
+the line\&.  If there is no command on the line yet, the \fIcommand\fP
+field will be empty\&.
+.PP
+For the \fB\-value\-\fP context, the form is
+`\fB\-value\-,\fP\fIname\fP\fB,\fP\fIcommand\fP', where \fIname\fP is the name of
+the parameter\&.  In the case of elements of an associative array, for
+example `\fBassoc=(key <TAB>\fP', \fIname\fP is expanded to
+`\fIname\fP\fB\-\fP\fIkey\fP'\&.  In certain special contexts, such as
+completing after `\fBmake CFLAGS=\fP', the \fIcommand\fP part gives the
+name of the command, here \fBmake\fP; otherwise it is empty\&.
+.PP
+It is not necessary to define fully specific completions as the
+functions provided will try to generate completions by progressively
+replacing the elements with `\fB\-default\-\fP'\&.  For example, when
+completing after `\fBfoo=<TAB>\fP', \fB_value\fP will try the names
+`\fB\-value\-,foo,\fP' (note the empty \fIcommand\fP part),
+`\fB\-value\-,foo,\-default\-\fP' and`\fB\-value\-,\-default\-,\-default\-\fP', in
+that order, until it finds a function to handle the context\&.
+.PP
+As an example:
+.PP
+.RS
+.nf
+\fBcompdef '_files \-g "*\&.log"' '\-redirect\-,2>,\-default\-'\fP
+.fi
+.RE
+.PP
+completes files matching `\fB*\&.log\fP' after `\fB2> <TAB>\fP' for any
+command with no more specific handler defined\&.
+.PP
+Also:
+.PP
+.RS
+.nf
+\fBcompdef _foo \-value\-,\-default\-,\-default\-\fP
+.fi
+.RE
+.PP
+specifies that \fB_foo\fP provides completions for the values of
+parameters for which no special function has been defined\&.  This is
+usually handled by the function \fB_value\fP itself\&.
+.PP
+The same lookup rules are used when looking up styles (as described
+below); for example
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*:*:\-redirect\-,2>,*:*' file\-patterns '*\&.log'\fP
+.fi
+.RE
+.PP
+is another way to make completion after `\fB2> <TAB>\fP' complete files
+matching `\fB*\&.log\fP'\&.
+.PP
+.SS "Functions"
+.PP
+The following function is defined by \fBcompinit\fP and may be called
+directly\&.
+.PP
+.PD 0
+.TP
+.PD 0
+\fBcompdef\fP [ \fB\-an\fP ] \fIfunction names\&.\&.\&.\fP [ \fB\-[pP]\fP \fIpatterns\&.\&.\&.\fP [ \fB\-N\fP \fInames\&.\&.\&.\fP ] ]
+.TP
+.PD 0
+\fBcompdef \-d\fP \fInames\&.\&.\&.\fP
+.TP
+.PD 0
+\fBcompdef \-k\fP [ \fB\-an\fP ] \fIfunction style key\-sequences\&.\&.\&.\fP
+.TP
+.PD
+\fBcompdef \-K\fP [ \fB\-an\fP ] \fIfunction name style key\-sequences \&.\&.\&.\fP
+The first form defines the \fIfunction\fP to call for completion in the
+given contexts as described for the \fB#compdef\fP tag above\&.
+.RS
+.PP
+Alternatively, all the arguments may have the form
+`\fIcmd\fP\fB=\fP\fIservice\fP'\&.  Here \fIservice\fP should already have been
+defined by `\fIcmd1\fP\fB=\fP\fIservice\fP' lines in \fB#compdef\fP files, as
+described above\&.  The argument for \fIcmd\fP will be completed in the
+same way as \fIservice\fP\&.
+.PP
+The \fIfunction\fP argument may alternatively be a string containing any
+shell code\&.  The string will be executed using the \fBeval\fP builtin
+command to generate completions\&.  This provides a way of avoiding having
+to define a new completion function\&.  For example, to complete
+files ending in `\fB\&.h\fP' as arguments to the command \fBfoo\fP:
+.PP
+.RS
+.nf
+\fBcompdef '_files \-g "*\&.h"' foo\fP
+.fi
+.RE
+.PP
+The option \fB\-n\fP prevents any completions already defined for the
+command or context from being overwritten\&.
+.PP
+The option \fB\-d\fP deletes any completion defined for the command or
+contexts listed\&.
+.PP
+The \fInames\fP may also contain \fB\-p\fP, \fB\-P\fP and \fB\-N\fP options as
+described for the \fB#compdef\fP tag\&.  The effect on the argument list is
+identical, switching between definitions of patterns tried initially,
+patterns tried finally, and normal commands and contexts\&.
+.PP
+The parameter \fB$_compskip\fP may be set by any function defined for a
+pattern context\&.  If it is set to a value containing the substring
+`\fBpatterns\fP' none of the pattern\-functions will be called; if it is
+set to a value containing the substring `\fBall\fP', no other function
+will be called\&.
+.PP
+The form with \fB\-k\fP defines a widget with the same name as the \fIfunction\fP
+that will be called for each of the \fIkey\-sequences\fP; this is like the
+\fB#compdef \-k\fP tag\&.  The function should generate the completions needed
+and will otherwise behave like the builtin widget whose name is given as
+the \fIstyle\fP argument\&.  The widgets usable for this are:
+\fBcomplete\-word\fP, \fBdelete\-char\-or\-list\fP, \fBexpand\-or\-complete\fP,
+\fBexpand\-or\-complete\-prefix\fP, \fBlist\-choices\fP, \fBmenu\-complete\fP,
+\fBmenu\-expand\-or\-complete\fP, and \fBreverse\-menu\-complete\fP, as well as
+\fBmenu\-select\fP if the \fBzsh/complist\fP module is loaded\&.  The option \fB\-n\fP
+prevents the key being bound if it is already to bound to something other
+than \fBundefined\-key\fP\&.
+.PP
+The form with \fB\-K\fP is similar and defines multiple widgets based on the
+same \fIfunction\fP, each of which requires the set of three arguments
+\fIname\fP, \fIstyle\fP and \fIkey\-sequences\fP, where the latter two are as
+for \fB\-k\fP and the first must be a unique widget name beginning with an
+underscore\&.
+.PP
+Wherever applicable, the \fB\-a\fP option makes the \fIfunction\fP
+autoloadable, equivalent to \fBautoload \-U \fP\fIfunction\fP\&.
+.RE
+.RE
+.PP
+The function \fBcompdef\fP can be used to associate existing completion
+functions with new commands\&.  For example,
+.PP
+.RS
+.nf
+\fBcompdef _pids foo\fP
+.fi
+.RE
+.PP
+uses the function \fB_pids\fP to complete process IDs for the command \fBfoo\fP\&.
+.PP
+Note also the \fB_gnu_generic\fP function described below, which can be
+used to complete options for commands that understand the
+`\fB\-\fP\fB\-help\fP' option\&.
+.PP
+.SH "COMPLETION SYSTEM CONFIGURATION"
+.PP
+This section gives a short overview of how the completion system works,
+and then more detail on how users can configure how and when matches are
+generated\&.
+.PP
+.SS "Overview"
+.PP
+When completion is attempted somewhere on the command line the
+completion system first works out the context\&.  This takes account of a
+number of things including the command word (such as `\fBgrep\fP' or
+`\fBzsh\fP') and options to which the current word may be an argument
+(such as the `\fB\-o\fP' option to \fBzsh\fP which takes a shell option as an
+argument)\&.
+.PP
+This context information is condensed into a string consisting of
+multiple fields separated by colons, referred to simply as `the context'
+in the remainder of the documentation\&.  This is used to look up
+\fIstyles\fP, context\-sensitive options that can be used to configure the
+completion system\&.  The context used for lookup may vary during the same
+call to the completion system\&.
+.PP
+The context string always consists of the following fields, separated
+by colons and with a leading colon before the first:
+.PP
+.PD 0
+.TP
+.PD
+\(bu
+The literal string \fBcompletion\fP, saying that this style is used by
+the completion system\&.  This distinguishes the context from those used
+by, for example, zle widgets and ZFTP functions\&.
+
+.TP
+\(bu
+The \fIfunction\fP, if completion is called from a named widget rather
+than through the normal completion system\&.  Typically this is blank, but
+it is set by special widgets such as \fBpredict\-on\fP and the various
+functions in the \fBWidget\fP directory of the distribution to the name of
+that function, often in an abbreviated form\&.
+
+.TP
+\(bu
+The \fIcompleter\fP currently active, the name of the function
+without the leading underscore\&.  A `completer' is in
+overall control of how completion is to be performed; `\fBcomplete\fP'
+is the simplest, but other completers exist to perform
+related tasks such as correction, or to modify the behaviour of a
+later completer\&.  See
+the section `Control Functions' below 
+for more information\&.  
+
+.TP
+\(bu
+The \fIcommand\fP or a special \fB\-\fP\fIcontext\fP\fB\-\fP, just at it appears
+following the \fB#compdef\fP tag or the \fBcompdef\fP function\&.  Completion
+functions for commands that have sub\-commands usually modify this field
+to contain the name of the command followed by a minus sign and the
+sub\-command\&.  For example, the completion function for the \fBcvs\fP
+command sets this field to \fBcvs\-add\fP when completing arguments to
+the \fBadd\fP subcommand\&.
+
+.TP
+\(bu
+The \fIargument\fP; this indicates which command line or option argument
+we are completing\&.  For command arguments this generally takes the form
+\fBargument\-\fP\fIn\fP, where \fIn\fP is the number of the argument,
+and for arguments to options the form \fBoption\-\fP\fIopt\fP\fB\-\fP\fIn\fP
+where \fIn\fP is the number of the argument to option \fIopt\fP\&.  However,
+this is only the case if the command line is parsed with standard
+UNIX\-style options and arguments, so many completions do not set this\&.
+
+.TP
+\(bu
+The \fItag\fP\&.  Tags are used to discriminate between the types
+of matches a completion function can generate in a certain context and
+are described further below\&.
+
+.PP
+As an example, the context name
+.PP
+.RS
+.nf
+\fB\fB:completion::complete:dvips:option\-o\-1:files\fP\fP
+.fi
+.RE
+.PP
+says that normal completion was attempted as the first argument to the
+option \fB\-o\fP of the command \fBdvips\fP:
+.PP
+.RS
+.nf
+\fB\fBdvips \-o \&.\&.\&.\fP\fP
+.fi
+.RE
+.PP
+and the completion function will generate filenames\&.
+.PP
+Each type of completion the system can perform in a given context is
+described by a `tag', a short descriptive string such as \fBfiles\fP in
+the example above\&.  Any completion function may use any tag name it
+likes, but a list of the more common ones is given below\&.
+.PP
+Usually completion will be tried by all possible tags in an order given
+by the completion function\&.  However, this can be altered by using the
+\fBtag\-order\fP style\&.  Completion is then restricted to the list of given
+tags in the given order\&.
+.PP
+The \fB_complete_help\fP bindable command shows all the contexts and tags
+available for completion at a particular point\&.  This provides an easy
+way of finding information for \fBtag\-order\fP and other styles\&.  It is
+described in
+the section `Bindable Commands' below\&.
+.PP
+Styles determine such things as how the matches are generated, similarly
+to shell options but with much more control\&.  They can have any number
+of strings as their value\&.  They are defined with the \fBzstyle\fP builtin
+command (see \fIzshmodules\fP(1))\&.
+.PP
+When looking up styles the completion system uses full context names,
+including the tag\&.  Looking up the value of a style therefore consists
+of two things:  the context, which may be matched as a pattern, and the
+name of the style itself, which must be given exactly\&.
+.PP
+For example, many completion functions can generate matches in a
+simple and a verbose form and use the \fBverbose\fP style to decide
+which form should be used\&.  To make all such functions use the verbose form,
+put
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' verbose yes\fP
+.fi
+.RE
+.PP
+in a startup file (probably \fB\&.zshrc\fP)\&.
+This gives the \fBverbose\fP style the value \fByes\fP in every
+context inside the completion system, unless that context has a more
+specific definition\&.  It is best to avoid giving the context as `\fB*\fP'
+in case the style has some meaning outside the completion system\&.
+.PP
+Many such general purpose styles can be configured simply by using the
+\fBcompinstall\fP function\&.
+.PP
+A more specific example of the use of the \fBverbose\fP style is by the
+completion for the \fBkill\fP builtin\&.  If the style is set, the builtin
+lists full job texts and process command lines; otherwise it shows the
+bare job numbers and PIDs\&.  To turn the style off for this use only:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*:*:kill:*' verbose no\fP
+.fi
+.RE
+.PP
+For even more control, the style can use one of the tags `\fBjobs\fP' or
+`\fBprocesses\fP'\&.  To turn off verbose display only for jobs:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*:*:kill:*:jobs' verbose no\fP
+.fi
+.RE
+.PP
+The \fB\-e\fP option to \fBzstyle\fP even allows completion function code to
+appear as the argument to a style; this requires some understanding of
+the internals of completion functions (see
+see \fIzshcompwid\fP(1)))\&.  For example:
+.PP
+.RS
+.nf
+\fBzstyle \-e ':completion:*' completer '
+    if [[ $words[1] = cvs ]]; then
+      reply=(_complete)
+    else
+      reply=(_complete _approximate)
+    fi'\fP
+.fi
+.RE
+.PP
+uses the value `\fB_complete\fP' for the \fBcompleter\fP style in most
+contexts, but the value `\fB_complete _approximate\fP' when the first word
+on the command line is `\fBcvs\fP'\&.  This is probably more conveniently done
+by specifying the style for two different contexts\&.  This form can be
+slow and should be avoided for commonly examined styles such
+as \fBmenu\fP and \fBlist\-rows\-first\fP\&.
+.PP
+Note that the order in which styles are \fIdefined\fP does not matter; the
+style mechanism uses the most specific possible match for a particular
+style to determine the set of values\&.  More precisely, strings are
+preferred over patterns (for example, `\fB:completion::complete:foo\fP' is
+more specific than `\fB:completion::complete:*'\fP), and longer patterns are
+preferred over shorter patterns\&.
+.PP
+Style names like those of tags are arbitrary and depend on the completion
+function\&.  However, the following two sections list some of the most
+common tags and styles\&.
+.PP
+.SS "Standard Tags"
+.PP
+Some of the following are only used when looking up particular styles
+and do not refer to a type of match\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBaccounts\fP
+used to look up the \fBusers\-hosts\fP style
+.TP
+\fBall\-expansions\fP
+used by the \fB_expand\fP completer when adding the single string containing
+all possible expansions
+.TP
+\fBall\-files\fP
+for the names of all files (as distinct from a particular subset, see the
+\fBglobbed\-files\fP tag)\&.
+.TP
+\fBarguments\fP
+for arguments to a command
+.TP
+\fBarrays\fP
+for names of array parameters
+.TP
+\fBassociation\-keys\fP
+for keys of associative arrays; used when completing inside a
+subscript to a parameter of this type
+.TP
+\fBbookmarks\fP
+when completing bookmarks (e\&.g\&. for URLs and the \fBzftp\fP function suite)
+.TP
+\fBbuiltins\fP
+for names of builtin commands
+.TP
+\fBcharacters\fP
+for single characters in arguments of commands such as \fBstty\fP\&.   Also used
+when completing character classes after an opening bracket
+.TP
+\fBcolormapids\fP
+for X colormap ids
+.TP
+\fBcolors\fP
+for color names
+.TP
+\fBcommands\fP
+for names of external commands\&.  Also used by complex commands such as
+\fBcvs\fP when completing names subcommands\&.
+.TP
+\fBcontexts\fP
+for contexts in arguments to the \fBzstyle\fP builtin command
+.TP
+\fBcorrections\fP
+used by the \fB_approximate\fP and \fB_correct\fP completers for possible
+corrections
+.TP
+\fBcursors\fP
+for cursor names used by X programs
+.TP
+\fBdefault\fP
+used in some contexts to provide a way of supplying a default when more
+specific tags are also valid\&.  Note that this tag is
+used when only the \fIfunction\fP field of the context name is set
+.TP
+\fBdescriptions\fP
+used when looking up the value of the \fBformat\fP style to generate
+descriptions for types of matches
+.TP
+\fBdevices\fP
+for names of device special files
+.TP
+\fBdirectories\fP
+for names of directories
+.TP
+\fBdirectory\-stack\fP
+for entries in the directory stack
+.TP
+\fBdisplays\fP
+for X display names
+.TP
+\fBdomains\fP
+for network domains
+.TP
+\fBexpansions\fP
+used by the \fB_expand\fP completer for individual words (as opposed to
+the complete set of expansions) resulting from the expansion of a word
+on the command line
+.TP
+\fBextensions\fP
+for X server extensions
+.TP
+\fBfile\-descriptors\fP
+for numbers of open file descriptors
+.TP
+\fBfiles\fP
+the generic file\-matching tag used by functions completing filenames
+.TP
+\fBfonts\fP
+for X font names
+.TP
+\fBfstypes\fP
+for file system types (e\&.g\&. for the \fBmount\fP command)
+.TP
+\fBfunctions\fP
+names of functions \-\-\- normally shell functions, although certain
+commands may understand other kinds of function
+.TP
+\fBglobbed\-files\fP
+for filenames when the name has been generated by pattern matching
+.TP
+\fBgroups\fP
+for names of user groups
+.TP
+\fBhistory\-words\fP
+for words from the history
+.TP
+\fBhosts\fP
+for hostnames
+.TP
+\fBindexes\fP
+for array indexes
+.TP
+\fBjobs\fP
+for jobs (as listed by the `\fBjobs\fP' builtin)
+.TP
+\fBinterfaces\fP
+for network interfaces
+.TP
+\fBkeymaps\fP
+for names of zsh keymaps
+.TP
+\fBkeysyms\fP
+for names of X keysyms
+.TP
+\fBlibraries\fP
+for names of system libraries
+.TP
+\fBlimits\fP
+for system limits
+.TP
+\fBlocal\-directories\fP
+for names of directories that are subdirectories of the current working
+directory when completing arguments of \fBcd\fP and related builtin
+commands (compare \fBpath\-directories\fP)
+.TP
+\fBmanuals\fP
+for names of manual pages
+.TP
+\fBmailboxes\fP
+for e\-mail folders
+.TP
+\fBmaps\fP
+for map names (e\&.g\&. NIS maps)
+.TP
+\fBmessages\fP
+used to look up the \fBformat\fP style for messages
+.TP
+\fBmodifiers\fP
+for names of X modifiers
+.TP
+\fBmodules\fP
+for modules (e\&.g\&. \fBzsh\fP modules)
+.TP
+\fBmy\-accounts\fP
+used to look up the \fBusers\-hosts\fP style
+.TP
+\fBnamed\-directories\fP
+for named directories (you wouldn't have guessed that, would you?)
+.TP
+\fBnames\fP
+for all kinds of names
+.TP
+\fBnewsgroups\fP
+for USENET groups
+.TP
+\fBnicknames\fP
+for nicknames of NIS maps
+.TP
+\fBoptions\fP
+for command options
+.TP
+\fBoriginal\fP
+used by the \fB_approximate\fP, \fB_correct\fP and \fB_expand\fP completers when
+offering the original string as a match
+.TP
+\fBother\-accounts\fP
+used to look up the \fBusers\-hosts\fP style
+.TP
+\fBpackages\fP
+for packages (e\&.g\&. \fBrpm\fP or installed \fBDebian\fP packages)
+.TP
+\fBparameters\fP
+for names of parameters
+.TP
+\fBpath\-directories\fP
+for names of directories found by searching the \fBcdpath\fP array when
+completing arguments of \fBcd\fP and related builtin commands (compare
+\fBlocal\-directories\fP)
+.TP
+\fBpaths\fP
+used to look up the values of the \fBexpand\fP, \fBambiguous\fP and
+\fBspecial\-dirs\fP styles
+.TP
+\fBpods\fP
+for perl pods (documentation files)
+.TP
+\fBports\fP
+for communication ports
+.TP
+\fBprefixes\fP
+for prefixes (like those of a URL)
+.TP
+\fBprinters\fP
+for print queue names
+.TP
+\fBprocesses\fP
+for process identifiers
+.TP
+\fBprocesses\-names\fP
+used to look up the \fBcommand\fP style when generating the names of
+processes for \fBkillall\fP
+.TP
+\fBsequences\fP
+for sequences (e\&.g\&. \fBmh\fP sequences)
+.TP
+\fBsessions\fP
+for sessions in the \fBzftp\fP function suite
+.TP
+\fBsignals\fP
+for signal names
+.TP
+\fBstrings\fP
+for strings (e\&.g\&. the replacement strings for the \fBcd\fP builtin
+command)
+.TP
+\fBstyles\fP
+for styles used by the zstyle builtin command
+.TP
+\fBsuffixes\fP
+for filename extensions
+.TP
+\fBtags\fP
+for tags (e\&.g\&. \fBrpm\fP tags)
+.TP
+\fBtargets\fP
+for makefile targets
+.TP
+\fBtime\-zones\fP
+for time zones (e\&.g\&. when setting the \fBTZ\fP parameter)
+.TP
+\fBtypes\fP
+for types of whatever (e\&.g\&. address types for the \fBxhost\fP command)
+.TP
+\fBurls\fP
+used to look up the \fBurls\fP and \fBlocal\fP styles when completing URLs
+.TP
+\fBusers\fP
+for usernames
+.TP
+\fBvalues\fP
+for one of a set of values in certain lists
+.TP
+\fBvariant\fP
+used by \fB_pick_variant\fP to look up the command to run when determining
+what program is installed for a particular command name\&.
+.TP
+\fBvisuals\fP
+for X visuals
+.TP
+\fBwarnings\fP
+used to look up the \fBformat\fP style for warnings
+.TP
+\fBwidgets\fP
+for zsh widget names
+.TP
+\fBwindows\fP
+for IDs of X windows
+.TP
+\fBzsh\-options\fP
+for shell options
+.PP
+.SS "Standard Styles"
+.PP
+Note that the values of several of these styles represent boolean
+values\&.  Any of the strings `\fBtrue\fP', `\fBon\fP',
+`\fByes\fP', and `\fB1\fP' can be used for the value `true' and
+any of the strings `\fBfalse\fP', `\fBoff\fP', `\fBno\fP', and `\fB0\fP' for
+the value `false'\&.  The behavior for any other value is undefined 
+except where explicitly mentioned\&.  The default value may
+be either true or false if the style is not set\&.
+.PP
+Some of these styles are tested first for every possible tag
+corresponding to a type of match, and if no style was found, for the
+\fBdefault\fP tag\&.  The most notable styles of this type are \fBmenu\fP, 
+\fBlist\-colors\fP and styles controlling completion listing such as 
+\fBlist\-packed\fP and \fBlast\-prompt\fP)\&.  When tested for the \fBdefault\fP
+tag, only the \fIfunction\fP field of the context will be set so that
+a style using the default tag will normally be defined along the lines of:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*:default' menu \&.\&.\&.\fP
+.fi
+.RE
+.PP
+.PD 0
+.TP
+.PD
+\fBaccept\-exact\fP
+This is tested for the default tag in addition to the tags valid for
+the current context\&.  If it is set to `true' and any of the trial
+matches is the same as the string on the command line, this match will
+immediately be accepted (even if it would otherwise be considered
+ambiguous)\&.
+.RS
+.PP
+When completing pathnames (where the tag used is `\fBpaths\fP')
+this style accepts any number of patterns as the value in addition to
+the boolean values\&.  Pathnames matching one of these
+patterns will be accepted immediately even if the command line contains
+some more partially typed pathname components and these match no file
+under the directory accepted\&.
+.PP
+This style is also used by the \fB_expand\fP completer to decide if
+words beginning with a tilde or parameter expansion should be
+expanded\&.  For example, if there are parameters
+\fBfoo\fP and \fBfoobar\fP, the string `\fB$foo\fP' will only be expanded if 
+\fBaccept\-exact\fP is set to `true'; otherwise the completion system will
+be allowed to complete \fB$foo\fP to \fB$foobar\fP\&. If the style is set to
+`continue', _expand will add the expansion as a match and the completion
+system will also be allowed to continue\&.
+.RE
+.TP
+\fBadd\-space\fP
+This style is used by the \fB_expand\fP completer\&.  If it is true (the
+default), a space will be inserted after all words resulting from the 
+expansion, or a slash in the case of directory names\&.  If the value
+is `\fBfile\fP', the completer will only add a space
+to names of existing files\&.  Either a boolean true or the value
+`\fBfile\fP' may be combined with `\fBsubst\fP', in which case the completer
+will not add a space to words generated from the expansion of a
+substitution of the form `\fB$(\&.\&.\&.)\fP' or `\fB${\&.\&.\&.}\fP'\&.
+.RS
+.PP
+The \fB_prefix\fP completer uses this style as a simple boolean value
+to decide if a space should be inserted before the suffix\&.
+.RE
+.TP
+\fBambiguous\fP
+This applies when completing non\-final components of filename paths, in
+other words those with a trailing slash\&.  If it is set, the cursor is
+left after the first ambiguous component, even if menu completion is in
+use\&.  The style is always tested with the \fBpaths\fP tag\&.
+.TP
+\fBassign\-list\fP
+When completing after an equals sign that is being treated as an
+assignment, the completion system normally completes only one filename\&.
+In some cases the value  may be a list of filenames separated by colons,
+as with \fBPATH\fP and similar parameters\&.  This style can be set to a
+list of patterns matching the names of such parameters\&.
+.RS
+.PP
+The default is to complete lists when the word on the line already
+contains a colon\&.
+.RE
+.TP
+\fBauto\-description\fP
+If set, this style's value will be used as the description for options that
+are not described by the completion functions, but that have exactly
+one argument\&.  The sequence `\fB%d\fP' in the value will be replaced by
+the description for this argument\&.  Depending on personal preferences,
+it may be useful to set this style to something like `\fBspecify: %d\fP'\&. 
+Note that this may not work for some commands\&.
+.TP
+\fBavoid\-completer\fP
+This is used by the \fB_all_matches\fP completer to decide if the string 
+consisting of all matches should be added to the list currently being
+generated\&.  Its value is a list of names of completers\&.  If any of
+these is the name of the completer that generated the matches in this
+completion, the string will not be added\&.
+.RS
+.PP
+The default value for this style is `\fB_expand _old_list _correct
+_approximate\fP', i\&.e\&. it contains the completers for which a string
+with all matches will almost never be wanted\&.
+.RE
+.TP
+\fBcache\-path\fP
+This style defines the path where any cache files containing dumped
+completion data are stored\&.  It defaults to `\fB$ZDOTDIR/\&.zcompcache\fP', or
+`\fB$HOME/\&.zcompcache\fP' if \fB$ZDOTDIR\fP is not defined\&.  The completion
+cache will not be used unless the \fBuse\-cache\fP style is set\&.
+.TP
+\fBcache\-policy\fP
+This style defines the function that will be used to determine whether
+a cache needs rebuilding\&.  See the section on the \fB_cache_invalid\fP
+function below\&.
+.TP
+\fBcall\-command\fP
+This style is used in the function for commands such as \fBmake\fP and
+\fBant\fP where calling the command directly to generate matches suffers
+problems such as being slow or, as in the case of \fBmake\fP can
+potentially causes actions in the makefile to be executed\&. If it is set
+to `true' the command is called to generate matches\&. The default value
+of this style is `false'\&.
+.TP
+\fBcommand\fP
+In many places, completion functions need to call external commands to
+generate the list of completions\&.  This style can be used to override the
+command that is called in some such cases\&.  The elements of the value are
+joined with spaces to form a command line to execute\&.  The value can also
+start with a hyphen, in which case the usual command will be added to the
+end; this is most useful for putting `\fBbuiltin\fP' or `\fBcommand\fP' in
+front to make sure the appropriate version of a command is called, for
+example to avoid calling a shell function with the same name as an external
+command\&.
+.RS
+.PP
+As an example, the completion function for process IDs uses this
+style with the \fBprocesses\fP tag to generate the IDs to complete and
+the list of processes to display (if the \fBverbose\fP style is `true')\&.
+The list produced by the command should look like the output of the
+\fBps\fP command\&.  The first line is not displayed, but is searched for
+the string `\fBPID\fP' (or `\fBpid\fP') to find the position of the
+process IDs in the following lines\&.  If the line does not contain
+`\fBPID\fP', the first numbers in each of the other lines are taken as the 
+process IDs to complete\&.
+.PP
+Note that the completion function generally has to call the specified
+command for each attempt to generate the completion list\&.  Hence
+care should be taken to specify only commands that take a short
+time to run, and in particular to avoid any that may never terminate\&.
+.RE
+.TP
+\fBcommand\-path\fP
+This is a list of directories to search for commands to complete\&.  The
+default for this style is the value of the special parameter \fBpath\fP\&.
+.TP
+\fBcommands\fP
+This is used by the function completing sub\-commands for the system
+initialisation scripts (residing in \fB/etc/init\&.d\fP or somewhere not
+too far away from that)\&.  Its values give the default commands to
+complete for those commands for which the completion function isn't
+able to find them out automatically\&.  The default for this style are
+the two strings `\fBstart\fP' and `\fBstop\fP'\&.
+.TP
+\fBcomplete\fP
+This is used by the \fB_expand_alias\fP function when invoked as a
+bindable command\&.  If it set to `true' and the word on the command
+line is not the name of an alias, matching alias names will be
+completed\&.
+.TP
+\fBcompleter\fP
+The strings given as the value of this style provide the names of the
+completer functions to use\&. The available completer functions are
+described in
+the section `Control Functions' below\&.
+.RS
+.PP
+Each string may be either the name of a completer function or a string
+of the form `\fIfunction\fP\fB:\fP\fIname\fP'\&.  In the first case the
+\fIcompleter\fP field of the context will contain the name of the
+completer without the leading underscore and with all other
+underscores replaced by hyphens\&.  In the second case the
+\fIfunction\fP is the name of the completer to call, but the context
+will contain the user\-defined \fIname\fP in the \fIcompleter\fP field of
+the context\&.  If the \fIname\fP starts with a hyphen, the string for the
+context will be build from the name of the completer function as in
+the first case with the \fIname\fP appended to it\&.  For example: 
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' completer _complete _complete:\-foo\fP
+.fi
+.RE
+.PP
+Here, completion will call the \fB_complete\fP completer twice, once
+using `\fBcomplete\fP' and once using `\fBcomplete\-foo\fP' in the
+\fIcompleter\fP field of the context\&.  Normally, using the same
+completer more than once only makes sense when used with the
+`\fIfunctions\fP\fB:\fP\fIname\fP' form, because otherwise the context
+name will be the same in all calls to the completer; possible
+exceptions to this rule are the \fB_ignored\fP and \fB_prefix\fP
+completers\&.
+.PP
+The default value for this style is `\fB_complete _ignored\fP':
+only completion will be done, first using the \fBignored\-patterns\fP style
+and the \fB$fignore\fP array and then without ignoring matches\&.
+.RE
+.TP
+\fBcondition\fP
+This style is used by the \fB_list\fP completer function to decide if
+insertion of matches should be delayed unconditionally\&. The default is 
+`true'\&.
+.TP
+\fBdisabled\fP
+If this is set to `true', the \fB_expand_alias\fP completer and bindable 
+command will try to expand disabled aliases, too\&.  The default is
+`\fBfalse\fP'\&.
+.TP
+\fBdisable\-stat\fP
+This is used with an empty tag by the \fB_cvs\fP function
+to decide whether the \fBzsh/stat\fP module should be used to
+generate names of modified files in the appropriate places (this is its
+only use)\&.  If the style is set, completion will use the \fBls\fP command\&.
+.TP
+\fBdomains\fP
+A list of names of network domains for completion\&.
+If this is not set, domain names will be taken from
+the file \fB/etc/resolv\&.conf\fP\&.
+.TP
+\fBexpand\fP
+This style is used when completing strings consisting of multiple
+parts, such as path names\&.
+.RS
+.PP
+If one of its values is the string `\fBprefix\fP', the partially typed
+word from the line will be expanded as far as possible even if trailing
+parts cannot be completed\&.
+.PP
+If one of its values is the string `\fBsuffix\fP', matching names for
+components after the first ambiguous one will also be added\&.  This means
+that the resulting string is the longest unambiguous string possible\&.
+However, menu completion can be used to cycle through all matches\&.
+.RE
+.TP
+\fBfake\fP
+This style may be set for any completion context\&.  It
+specifies additional strings that will always be completed in that
+context\&.  The form of each string is `\fIvalue\fP\fB:\fP\fIdescription\fP'; 
+the colon and description may be omitted, but any literal colons in
+\fIvalue\fP must be quoted with a backslash\&.  Any \fIdescription\fP
+provided is shown alongside the value in completion listings\&.
+.RS
+.PP
+It is important to use a sufficiently restrictive context when specifying
+fake strings\&.  Note that the styles \fBfake\-files\fP and \fBfake\-parameters\fP
+provide additional features when completing files or parameters\&.
+.RE
+.TP
+\fBfake\-files\fP
+This style is used when completing files and looked up 
+without a tag\&.  Its values are of the form
+`\fIdir\fP\fB:\fP\fInames\&.\&.\&.\fP'\&.  This will add the \fInames\fP (strings
+separated by spaces) as
+possible matches when completing in the directory \fIdir\fP, even if no 
+such files really exist\&.
+.RS
+.PP
+This can be useful on systems that support special filesystems whose
+top\-level pathnames can not be listed or generated with glob patterns\&.
+It can also be used for directories for which one does not have read
+permission\&.
+.RE
+.TP
+\fBfake\-parameters\fP
+This is used by the completion function for parameter names\&.
+Its values are names of parameters that might not yet be
+set but should be completed nonetheless\&.  Each name may also be 
+followed by a colon and a string specifying the type of the parameter
+(like `\fBscalar\fP', `\fBarray\fP' or `\fBinteger\fP')\&.  If the type is
+given, the name will only be completed if parameters of that type are
+required in the particular context\&.  Names for which no type is
+specified will always be completed\&.
+.TP
+\fBfile\-patterns\fP
+This is used by the standard function for completing filenames,
+\fB_files\fP\&.  If the style is unset up to three tags are offered,
+`\fBglobbed\-files\fP',`\fBdirectories\fP' and `\fBall\-files\fP', depending on
+the types of files  expected by the caller of \fB_files\fP\&.  The first two
+(`\fBglobbed\-files\fP' and `\fBdirectories\fP') are normally offered
+together to make it easier to complete files in sub\-directories\&.
+.RS
+.PP
+The \fBfile\-patterns\fP style provides alternatives to the default tags,
+which are not used\&.  Its value consists of elements of the form
+`\fIpattern\fP\fB:\fP\fItag\fP'; each string may contain any number of
+such specifications separated by spaces\&.
+.PP
+The \fIpattern\fP is a pattern that is to be used to generate filenames\&.
+Any occurrence of the sequence `\fB%p\fP' is replaced by any pattern(s)
+passed by the function calling \fB_files\fP\&.  Colons in the pattern must
+be preceded by a backslash to make them distinguishable from the colon
+before the \fItag\fP\&.  If more than one pattern is needed, the patterns
+can be given inside braces, separated by commas\&.
+.PP
+The \fItag\fPs of all strings in the value will be offered by \fB_files\fP
+and used when looking up other styles\&.  Any \fItag\fPs in the same
+word will be offered at the same time and before later words\&.
+If no `\fB:\fP\fItag\fP' is given the `\fBfiles\fP' tag will be used\&.
+.PP
+The \fItag\fP may also be followed by an optional second colon and a
+description, which will be used for the `\fB%d\fP' in the value of
+the \fBformat\fP style (if that is set) instead of the default
+description supplied by the completion function\&.  If the description
+given here contains itself a `\fB%d\fP', that is replaced with the
+description supplied by the completion function\&.
+.PP
+For example, to make the \fBrm\fP command first complete only names of
+object files and then the names of all files if there is no matching
+object file:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*:*:rm:*' file\-patterns \e 
+    '*\&.o:object\-files' '%p:all\-files'\fP
+.fi
+.RE
+.PP
+To alter the default behaviour of file completion \-\-\- offer files
+matching a pattern and directories on the first attempt, then all files
+\-\-\- to offer only matching files on the first attempt, then directories,
+and finally all files:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' file\-patterns \e 
+    '%p:globbed\-files' '*(\-/):directories' '*:all\-files'\fP
+.fi
+.RE
+.PP
+This works even where there is no special pattern: \fB_files\fP matches
+all files using the pattern `\fB*\fP' at the first step and stops when it
+sees this pattern\&.  Note also it will never try a pattern more than once
+for a single completion attempt\&.
+.PP
+During the execution of completion functions, the \fBEXTENDED_GLOB\fP
+option is in effect, so the characters `\fB#\fP', `\fB~\fP' and `\fB^\fP' have
+special meanings in the patterns\&.
+.RE
+.TP
+\fBfile\-sort\fP
+The standard filename completion function uses this style without a tag
+to determine in which order the names should be listed; menu completion
+will cycle through them in the same order\&.  The possible
+values are: `\fBsize\fP' to sort by the size of the file;
+`\fBlinks\fP' to sort by the number of links to the file;
+`\fBmodification\fP' (or `\fBtime\fP' or `\fBdate\fP') to sort by the last
+modification time; `\fBaccess\fP' to sort by the last access time; and
+`\fBinode\fP' (or `\fBchange\fP') to sort by the last inode change
+time\&.  If the style is set to any other value, or is unset, files will be
+sorted alphabetically by name\&.  If the value contains the string
+`\fBreverse\fP', sorting is done in the opposite order\&.
+.TP
+\fBfilter\fP
+This is used by the LDAP plugin for e\-mail address completion to specify
+the attributes to match against when filtering entries\&.  So for example, if
+the style is set to `\fBsn\fP', matching is done against surnames\&.  Standard
+LDAP filtering is used so normal completion matching is bypassed\&.  If this
+style is not set, the LDAP plugin is skipped\&.  You may also need to set the
+\fBcommand\fP style to specify how to connect to your LDAP server\&.
+.TP
+\fBforce\-list\fP
+This forces a list of completions to be shown at any point where listing is
+done, even in cases where the list would usually be suppressed\&.
+For example, normally the list is only shown if
+there are at least two different matches\&.  By setting this style to
+`\fBalways\fP', the list will always be shown, even if there is only a
+single match that will immediately be accepted\&.  The style may also
+be set to a number\&.  In this case the list will be shown if there are
+at least that many matches, even if they would all insert the same
+string\&.
+.RS
+.PP
+This style is tested for the default tag as well as for each tag valid
+for the current completion\&.  Hence the listing can be forced only for
+certain types of match\&.
+.RE
+.TP
+\fBformat\fP
+If this is set for the \fBdescriptions\fP tag, its value is used as a
+string to display above matches in completion lists\&.  The sequence
+`\fB%d\fP' in this string will be replaced with a short description of
+what these matches are\&.  This string may also contain the sequences to
+specify output attributes, such as `\fB%B\fP', `\fB%S\fP' and
+`\fB%{\fP\&.\&.\&.\fB%}\fP'\&.
+.RS
+.PP
+The style is tested with each tag valid for the current completion
+before it is tested for the \fBdescriptions\fP tag\&.  Hence different format 
+strings can be defined for different types of match\&.
+.PP
+Note also that some completer functions define additional
+`\fB%\fP'\-sequences\&.  These are described for the completer functions that 
+make use of them\&.
+.PP
+Some completion functions display messages that may be customised by
+setting this style for the \fBmessages\fP tag\&.  Here, the `\fB%d\fP' is
+replaced with a message given by the completion function\&.
+.PP
+Finally, the format string is looked up with the \fBwarnings\fP tag, 
+for use when no matches could be generated at all\&.  In this case the
+`\fB%d\fP' is replaced with the descriptions for the matches that were
+expected separated by spaces\&.  The sequence `\fB%D\fP' is replaced with
+the same descriptions separated by newlines\&.
+.PP
+It is possible to use printf\-style field width specifiers with `\fB%d\fP'
+and similar escape sequences\&.  This is handled by the \fBzformat\fP
+builtin command from the \fBzsh/zutil\fP module, see
+\fIzshmodules\fP(1)\&.
+.RE
+.TP
+\fBglob\fP
+This is used by the \fB_expand\fP completer\&.  If
+it is set to `true' (the default), globbing will be attempted on the
+words resulting from a previous substitution (see the \fBsubstitute\fP
+style) or else the original string from the line\&.
+.TP
+\fBglobal\fP
+If this is set to `true' (the default), the \fB_expand_alias\fP
+completer and bindable command will try to expand global aliases\&.
+.TP
+\fBgroup\-name\fP
+The completion system can group different types of matches, which appear
+in separate lists\&.  This style can be used to give the names of groups
+for particular tags\&.  For example, in command position the completion
+system generates names of builtin and external commands, names of
+aliases, shell functions and parameters and reserved words as possible
+completions\&.  To have the external commands and shell functions listed
+separately:
+.RS
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*:*:\-command\-:*:commands' group\-name commands
+zstyle ':completion:*:*:\-command\-:*:functions' group\-name functions\fP
+.fi
+.RE
+.PP
+As a consequence, any match with the same tag will be displayed in the
+same group\&.
+.PP
+If the name given is the empty string the name of the tag for
+the matches will be used as the name of the group\&.  So, to have all
+different types of matches displayed separately, one can just set:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' group\-name ''\fP
+.fi
+.RE
+.PP
+All matches for which no group name is defined will be put in a group
+named \fB\-default\-\fP\&.
+.RE
+.TP
+\fBgroup\-order\fP
+This style is additional to the \fBgroup\-name\fP style to specify the
+order for display of the groups defined by that style (compare \fBtag\-order\fP,
+which determines which completions appear at all)\&.  The groups named
+are shown in the given order; any other groups
+are shown in the order defined by the completion function\&.
+.RS
+.PP
+For example, to have names of builtin commands, shell functions and
+external commands appear in that order when completing in command
+position:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*:*:\-command\-:*' group\-order \e 
+       builtins functions commands\fP
+.fi
+.RE
+.RE
+.TP
+\fBgroups\fP
+A list of names of UNIX groups\&.  If this is not set,
+group names are taken from the YP database or the file `\fB/etc/group\fP'\&.
+.TP
+\fBhidden\fP
+If this is set to true, matches for the given context
+will not be listed, although
+any description for the matches set with the \fBformat\fP style will be
+shown\&.  If it is set to `\fBall\fP', not even the description will be
+displayed\&.
+.RS
+.PP
+Note that the matches will still be completed; they are just not shown 
+in the list\&.  To avoid having matches considered as possible
+completions at all, the \fBtag\-order\fP style can be modified as described
+below\&.
+.RE
+.TP
+\fBhosts\fP
+A list of names of hosts that should be completed\&.  If this is not set,
+hostnames are taken from the file `\fB/etc/hosts\fP'\&.
+.TP
+\fBhosts\-ports\fP
+This style is used by commands that need or accept hostnames and
+network ports\&.  The strings in the value should be of the form
+`\fIhost\fP\fB:\fP\fIport\fP'\&.  Valid ports are determined by the presence
+of hostnames; multiple ports for the same host may appear\&.
+.TP
+\fBignore\-line\fP
+This is tested for each tag valid for the current completion\&.  If
+it is set to `\fBtrue\fP', none of the words that are already on the line
+will be considered as possible completions\&.  If it is set to
+`\fBcurrent\fP', the word the cursor is on will not be considered as a
+possible completion\&.  The value `\fBcurrent\-shown\fP' is similar but only
+applies if the list of completions is currently shown on the screen\&.
+Finally, if the style is set to `\fBother\fP', no word apart from the
+current one will be considered as a possible completion\&.
+.RS
+.PP
+The values `\fBcurrent\fP' and `\fBcurrent\-shown\fP' are a bit like the
+opposite of the \fBaccept\-exact\fP style:  only strings with
+missing characters will be completed\&.
+.PP
+Note that you almost certainly don't want to set this to `true' or
+`\fBother\fP' for a general
+context such as `\fB:completion:*\fP'\&.  This is because it would disallow
+completion of, for example, options multiple times even if the command
+in question accepts the option more than once\&.
+.RE
+.TP
+\fBignore\-parents\fP
+The style is tested without a tag by the function completing pathnames
+in order to determine whether to ignore
+the names of directories already mentioned in the current word, or the
+name of the current working directory\&.  The value must include one or both
+of the following strings:
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fBparent\fP
+The name of any directory whose path is already contained in the word on
+the line is ignored\&.  For example, when completing after \fBfoo/\&.\&./\fP, the
+directory \fBfoo\fP will not be considered a valid completion\&.
+.TP
+\fBpwd\fP
+The name of the current working directory will not be completed; hence,
+for example, completion after \fB\&.\&./\fP will not use the name of the current
+directory\&.
+.PP
+In addition, the value may include one or both of:
+.PP
+.PD 0
+.TP
+.PD
+\fB\&.\&.\fP
+Ignore the specified directories only when the word on the line contains
+the substring `\fB\&.\&./\fP'\&.
+.TP
+\fBdirectory\fP
+Ignore the specified directories only when names of directories are
+completed, not when completing names of files\&.
+.PP
+Excluded values act in a similar fashion to values of the
+\fBignored\-patterns\fP style, so they can be restored to consideration by
+the \fB_ignored\fP completer\&.
+.RE
+.TP
+\fBignored\-patterns\fP
+A list of patterns; any trial completion matching one of the patterns
+will be excluded from consideration\&.  The
+\fB_ignored\fP completer can appear in the list of completers to
+restore the ignored matches\&.  This is a more configurable
+version of the shell parameter \fB$fignore\fP\&.
+.RS
+.PP
+Note that the
+\fBEXTENDED_GLOB\fP option is set during the execution of completion
+functions, so the characters `\fB#\fP', `\fB~\fP' and `\fB^\fP' have special
+meanings in the patterns\&.
+.RE
+.TP
+\fBinsert\fP
+This style is used by the \fB_all_matches\fP completer to decide whether to
+insert the list of all matches unconditionally instead of adding the
+list as another match\&.
+.TP
+\fBinsert\-ids\fP
+When completing process IDs, for example as arguments to the \fBkill\fP and
+\fBwait\fP builtins the name of a
+command may be converted to the appropriate process ID\&.  A problem
+arises when the process name typed is not unique\&.  By default (or if this
+style is set explicitly to `\fBmenu\fP') the name will be converted
+immediately to a set of possible IDs, and menu completion will be started
+to cycle through them\&.
+.RS
+.PP
+If the value of the style is `\fBsingle\fP',
+the shell will wait until the user has typed enough to make the command
+unique before converting the name to an ID; attempts at completion will
+be unsuccessful until that point\&.  If the value is any other
+string, menu completion will be started when the string typed by the
+user is longer than the common prefix to the corresponding IDs\&.
+.RE
+.TP
+\fBinsert\-tab\fP
+If this is set to `true', the completion system will
+insert a TAB character (assuming that was used to start completion) instead
+of performing completion when there is no non\-blank character to the left
+of the cursor\&.  If it is set to `false', completion will be done even there\&.
+.RS
+.PP
+The value may also contain the substrings `\fBpending\fP' or
+`\fBpending=\fP\fIval\fP'\&.  In this case, the typed character will be
+inserted instead of staring completion when there is unprocessed input
+pending\&.  If a \fIval\fP is given, completion will not be done if there
+are at least that many characters of unprocessed input\&.  This is often
+useful when pasting characters into a terminal\&.  Note
+however, that it relies on the \fB$PENDING\fP special parameter from the
+\fBzsh/zle\fP module being set properly which is not guaranteed on all
+platforms\&.
+.PP
+The default value of this style is `true' except for completion within
+\fBvared\fP builtin command where it is `false'\&.
+.RE
+.TP
+\fBinsert\-unambiguous\fP
+This is used by the \fB_match\fP and \fB_approximate\fP completers\&.
+These completers are often used with menu completion since the word typed
+may bear little resemblance to the final completion\&.
+However, if this style is `true', the completer will start menu
+completion only if it could find no unambiguous initial string at
+least as long as the original string typed by the user\&.
+.RS
+.PP
+In the case of the \fB_approximate\fP completer, the completer
+field in the context will already have been set to one of
+\fBcorrect\-\fP\fInum\fP or \fBapproximate\-\fP\fInum\fP, where \fInum\fP is the
+number of errors that were accepted\&.
+.PP
+In the case of the \fB_match\fP completer, the style may also be set to
+the string `\fBpattern\fP'\&.  Then the pattern on the line is left
+unchanged if it does not match unambiguously\&.
+.RE
+.TP
+\fBkeep\-prefix\fP
+This style is used by the \fB_expand\fP completer\&.  If it is `true', the
+completer will try to keep a prefix containing a tilde or parameter
+expansion\&.  Hence, for example, the string `\fB~/f*\fP' would be expanded to
+`\fB~/foo\fP' instead of `\fB/home/user/foo\fP'\&.  If the style is set to
+`\fBchanged\fP' (the default), the prefix will only be left unchanged if
+there were other changes between the expanded words and the original
+word from the command line\&.  Any other value forces the prefix to be
+expanded unconditionally\&.
+.RS
+.PP
+The behaviour of expand when this style is true is to cause \fB_expand\fP
+to give up when a single expansion with the restored prefix is the same
+as the original; hence any remaining completers may be called\&.
+.RE
+.TP
+\fBlast\-prompt\fP
+This is a more flexible form of the \fBALWAYS_LAST_PROMPT\fP option\&.
+If it is true, the completion system will try to return the cursor to
+the previous command line after displaying a completion list\&.  It is
+tested for all tags valid for the current completion, then the
+\fBdefault\fP tag\&.  The cursor will be moved back to the
+previous line if this style is `true' for all types of match\&.  Note
+that unlike the \fBALWAYS_LAST_PROMPT\fP option this is independent of the
+numeric prefix argument\&.
+.TP
+\fBlist\fP
+This style is used by the \fB_history_complete_word\fP bindable command\&.
+If it is set to `true' it has no effect\&.  If it is set to `false'
+matches will not be listed\&.  This overrides the setting of the options
+controlling listing behaviour, in particular \fBAUTO_LIST\fP\&.  The context
+always starts with `\fB:completion:history\-words\fP'\&.
+.TP
+\fBlist\-colors\fP
+If the \fBzsh/complist\fP module is loaded, this style can be used to set
+color specifications\&.  This mechanism replaces the use of the
+\fBZLS_COLORS\fP and \fBZLS_COLOURS\fP parameters described in
+the section `The zsh/complist Module' in \fIzshmodules\fP(1), but the syntax is the same\&.
+.RS
+.PP
+If this style is set for the \fBdefault\fP tag, the strings in the value 
+are taken as specifications that are to be used everywhere\&.  If it is
+set for other tags, the specifications are used only for matches of
+the type described by the tag\&.  For this to work best, the \fBgroup\-name\fP
+style must be set to an empty string\&.  
+.PP
+In addition to setting styles for specific tags, it is also possible to
+use group names specified explicitly by the \fBgroup\-name\fP tag together
+with the `\fB(group)\fP' syntax allowed by the \fBZLS_COLORS\fP and
+\fBZLS_COLOURS\fP parameters and simply using the \fBdefault\fP tag\&.
+.PP
+It is possible to use any color specifications already set up for the GNU
+version of the \fBls\fP command:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*:default' list\-colors ${(s\&.:\&.)LS_COLORS}\fP
+.fi
+.RE
+.PP
+The default colors are the same as for the GNU \fBls\fP command and can be
+obtained by setting the style to an empty string (i\&.e\&. \fB''\fP)\&.
+.RE
+.TP
+\fBlist\-grouped\fP
+If this style is `true' (the default), the completion system will try to
+make certain completion listings more compact by grouping matches\&.
+For example, options for commands that have the same description (shown
+when the \fBverbose\fP style is set to `true') will appear as a single
+entry\&.  However, menu selection can be used to cycle through all the
+matches\&.
+.TP
+\fBlist\-packed\fP
+This is tested for each tag valid in the current context as well as the
+\fBdefault\fP tag\&.  If it is set to `true', the corresponding matches
+appear in listings as if the \fBLIST_PACKED\fP option were set\&.  If it is
+set to `false', they are listed normally\&.
+.TP
+\fBlist\-prompt\fP
+If this style is set for the \fBdefault\fP tag,
+completion lists that don't fit on the screen can be scrolled (see
+the description of the \fBzsh/complist\fP module in \fIzshmodules\fP(1))\&.  The value, if not the empty string, will be displayed after every
+screenful and the shell will prompt for a key press; if the style is
+set to the empty string,
+a default prompt will be used\&.
+.RS
+.PP
+The value may contain the escape sequences:
+`\fB%l\fP' or `\fB%L\fP', which will be replaced by the number of the last line
+displayed and the total number of lines; `\fB%m\fP' or `\fB%M\fP', 
+the number of the  last match shown and the total number of
+matches; and `\fB%p\fP' and `\fB%P\fP', `\fBTop\fP'
+when at the beginning of the list, `\fBBottom\fP' when at the end and the
+position shown as a percentage of the total length otherwise\&.  In each
+case the form with the uppercase letter will be replaced by a string of fixed
+width, padded to the  right with spaces, while the lowercase form will
+be replaced by a variable width string\&.  As in other prompt strings, the
+escape sequences `\fB%S\fP', `\fB%s\fP', `\fB%B\fP', `\fB%b\fP', `\fB%U\fP',
+`\fB%u\fP' for entering and leaving the display modes
+standout, bold and underline are also available, as is the form
+`\fB%{\fP\&.\&.\&.\fB%}\fP' for enclosing escape sequences which display with zero
+width\&.
+.RE
+.TP
+\fBlist\-rows\-first\fP
+This style is tested in the same way as the \fBlist\-packed\fP style and
+determines whether matches are to be listed in a rows\-first fashion as
+if the \fBLIST_ROWS_FIRST\fP option were set\&.
+.TP
+\fBlist\-suffixes\fP
+This style is used by the function that completes filenames\&.  If it is
+true, and completion is attempted on a string containing multiple partially
+typed pathname components, all ambiguous components will be shown\&.
+Otherwise, completion stops at the first ambiguous component\&.
+.TP
+\fBlist\-separator\fP
+The value of this style is used in completion listing to separate the
+string to complete from a description when possible (e\&.g\&. when
+completing options)\&.  It defaults to `\fB\-\fP\fB\-\fP' (two hyphens)\&.
+.TP
+\fBlocal\fP
+This is for use with functions that complete URLs for which the
+corresponding files are available directly from the filing system\&.
+Its value should consist of three strings: a
+hostname, the path to the default web pages for the server, and the
+directory name used by a user placing web pages within their home
+area\&.
+.RS
+.PP
+For example:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' local toast \e 
+    /var/http/public/toast public_html\fP
+.fi
+.RE
+.PP
+Completion after `\fBhttp://toast/stuff/\fP' will look for files in the
+directory \fB/var/http/public/toast/stuff\fP,  while completion after
+`\fBhttp://toast/~yousir/\fP' will look for files in the directory
+\fB~yousir/public_html\fP\&.
+.RE
+.TP
+\fBmail\-directory\fP
+If set, zsh will assume that mailbox files can be found in
+the directory specified\&.  It defaults to `\fB~/Mail\fP'\&.
+.TP
+\fBmatch\-original\fP
+This is used by the \fB_match\fP completer\&.  If it is set to
+\fBonly\fP, \fB_match\fP will try to generate matches without inserting a
+`\fB*\fP' at the cursor position\&.  If set to any other non\-empty value,
+it will first try to generate matches without inserting the `\fB*\fP'
+and if that yields no matches, it will try again with the `\fB*\fP'
+inserted\&.  If it is unset or set to the empty string, matching will
+only be performed with the `\fB*\fP' inserted\&.
+.TP
+\fBmatcher\fP
+This style is tested separately for each tag valid in the current
+context\&.  Its value is added to any match specifications given by the 
+\fBmatcher\-list\fP style\&.  It should be in the form described in
+the section `Matching Control' in \fIzshcompwid\fP(1)\&.
+.TP
+\fBmatcher\-list\fP
+This style can be set to a list of match specifications that are to
+be applied everywhere\&. Match specifications are described in
+the section `Matching Control' in \fIzshcompwid\fP(1)\&.
+The completion system will try them one after another for each completer
+selected\&.  For example, to try first simple completion and, if that
+generates no matches, case\-insensitive completion:
+.RS
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' matcher\-list '' 'm:{a\-zA\-Z}={A\-Za\-z}'\fP
+.fi
+.RE
+.PP
+By default each specification replaces the previous one; however, if a
+specification is prefixed with \fB+\fP, it is added to the existing list\&.
+Hence it is possible to create increasingly general specifications
+without repetition:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' matcher\-list '' '+m{a\-Z}={A\-Z}' '+m{A\-Z}={a\-z}'\fP
+.fi
+.RE
+.PP
+It is possible to create match specifications valid for particular
+completers by using the third field of the context\&.  For example, to
+use the completers \fB_complete\fP and \fB_prefix\fP but only allow
+case\-insensitive completion with \fB_complete\fP:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' completer _complete _prefix
+zstyle ':completion:*:complete:*' matcher\-list \e 
+       '' 'm:{a\-zA\-Z}={A\-Za\-z}'\fP
+.fi
+.RE
+.PP
+User\-defined names, as explained for the \fBcompleter\fP style, are
+available\&.  This makes it possible to try the same completer more than
+once with different match specifications each time\&.  For example, to try
+normal completion without a match specification, then normal completion
+with case\-insensitive matching, then correction, and finally
+partial\-word completion:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' completer _complete _correct _complete:foo
+zstyle ':completion:*:complete:*' matcher\-list \e 
+    '' 'm:{a\-zA\-Z}={A\-Za\-z}'
+zstyle ':completion:*:foo:*' matcher\-list \e 
+    'm:{a\-zA\-Z}={A\-Za\-z} r:|[\-_\&./]=* r:|=*'\fP
+.fi
+.RE
+.PP
+If the style is unset in any context no match specification is applied\&.
+Note also that some completers such as \fB_correct\fP and \fB_approximate\fP
+do not use the match specifications at all, though these completers will
+only ever called once even if the \fBmatcher\-list\fP contains more than
+one element\&.
+.PP
+Where multiple specifications are useful, note that the \fIentire\fP
+completion is done for each element of \fBmatcher\-list\fP, which can
+quickly reduce the shell's performance\&.  As a rough rule of thumb,
+one to three strings will give acceptable performance\&.  On the other
+hand, putting multiple space\-separated values into the same string does
+not have an appreciable impact on performance\&.
+.RE
+.TP
+\fBmax\-errors\fP
+This is used by the \fB_approximate\fP and \fB_correct\fP completer functions
+to determine the maximum number of errors to allow\&.  The completer will try
+to generate completions by first allowing one error, then two errors, and
+so on, until either a match or matches were found or the maximum number of
+errors given by this style has been reached\&.
+.RS
+.PP
+If the value for this style contains the string `\fBnumeric\fP', the 
+completer function will take any numeric argument as the
+maximum number of errors allowed\&. For example, with
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*:approximate:::' max\-errors 2 numeric\fP
+.fi
+.RE
+.PP
+two errors are allowed if no numeric argument is given, but with
+a numeric argument of six (as in `\fBESC\-6 TAB\fP'), up to six
+errors are accepted\&.  Hence with a value of `\fB0 numeric\fP', no correcting
+completion will be attempted unless a numeric argument is given\&.
+.PP
+If the value contains the string `\fBnot\-numeric\fP', the completer
+will \fInot\fP try to generate corrected
+completions when given a numeric argument, so in this case the number given
+should be greater than zero\&.  For example, `\fB2 not\-numeric\fP' specifies that
+correcting completion with two errors will usually be performed, but if a
+numeric argument is given, correcting completion will not be
+performed\&.
+.PP
+The default value for this style is `\fB2 numeric\fP'\&.
+.RE
+.TP
+\fBmax\-matches\-width\fP
+This style is used to determine the trade off between the width of the
+display used for matches and the width used for their descriptions when
+the \fBverbose\fP style is in effect\&.  The value gives the number of
+display columns to reserve for the matches\&.  The default is half the
+width of the screen\&.
+.RS
+.PP
+This has the most impact when several matches have the
+same description and so will be grouped together\&.  Increasing the style
+will allow more matches to be grouped together; decreasing it will allow
+more of the description to be visible\&.
+.RE
+.TP
+\fBmenu\fP
+If this is true in the context of any of the tags defined
+for the current completion menu completion will be used\&.  The value for
+a specific tag will take precedence over that for the `\fBdefault\fP' tag\&.
+.RS
+.PP
+If none of the values found in this way is true but at least
+one is set to `\fBauto\fP', the shell behaves as if the \fBAUTO_MENU\fP
+option is set\&.
+.PP
+If one of the values is explicitly set to false, menu
+completion will be explicitly turned off, overriding the
+\fBMENU_COMPLETE\fP option and other settings\&.
+.PP
+In the form `\fByes=\fP\fInum\fP', where `\fByes\fP' may be any of the
+true values (`\fByes\fP', `\fBtrue\fP', `\fBon\fP' and `\fB1\fP'),
+menu completion will be turned on if there are at least \fInum\fP matches\&.
+In the form `\fByes=long\fP', menu completion will be turned on
+if the list does not fit on the screen\&.  This does not activate menu
+completion if the widget normally only lists completions, but menu
+completion can be activated in that case with the value `\fByes=long\-list\fP'
+(Typically, the value `\fBselect=long\-list\fP' described later is more
+useful as it provides control over scrolling\&.)
+.PP
+Similarly, with any of the `false' values (as in `\fBno=10\fP'), menu
+completion will \fInot\fP be used if there are \fInum\fP or more matches\&.  
+.PP
+The value of this widget also controls menu selection, as implemented by
+the \fBzsh/complist\fP module\&.  The following values may appear either
+alongside or instead of the values above\&.
+.PP
+If the value contains the string `\fBselect\fP', menu selection
+will be started unconditionally\&.
+.PP
+In the form `\fBselect=\fP\fInum\fP', menu selection will only be started if
+there are at least \fInum\fP matches\&.  If the values for more than one
+tag provide a number, the smallest number is taken\&.
+.PP
+Menu selection can be turned off explicitly by defining a value
+containing the string`\fBno\-select\fP'\&.
+.PP
+It is also possible to start menu selection only if the list of
+matches does not fit on the screen by using the value
+`\fBselect=long\fP'\&.  To start menu selection even if the current widget
+only performs listing, use the value `\fBselect=long\-list\fP'\&.
+.PP
+To turn on menu completion or menu selection when a there are a certain
+number of matches \fIor\fP the list of matches does not fit on the
+screen, both of `\fByes=\fP' and `\fBselect=\fP' may be given twice, once
+with a number and once with `\fBlong\fP' or `\fBlong\-list\fP'\&.
+.PP
+Finally, it is possible to activate two special modes of menu selection\&.
+The word `\fBinteractive\fP' in the value causes interactive mode
+to be entered immediately when menu selection is started; see
+the description of the \fBzsh/complist\fP module in \fIzshmodules\fP(1).RE for a description of interactive mode\&.  Including the string
+`\fBsearch\fP' does the same for incremental search mode\&.  To select backward
+incremental search, include the string `\fBsearch\-backward\fP'\&.
+)
+.TP
+\fBmuttrc\fP
+If set, gives the location of the mutt configuration file\&.  It defaults
+to `\fB~/\&.muttrc\fP'\&.
+.TP
+\fBnumbers\fP
+This is used with the \fBjobs\fP tag\&.  If it is `true', the shell will
+complete job numbers instead of the shortest unambiguous prefix
+of the job command text\&.  If the value is a number, job numbers will
+only be used if that many words from the job descriptions are required to
+resolve ambiguities\&.  For example, if the value is `\fB1\fP', strings will
+only be used if all jobs differ in the first word on their command lines\&.
+.TP
+\fBold\-list\fP
+This is used by the \fB_oldlist\fP completer\&.  If it is set to `\fBalways\fP',
+then standard widgets which perform listing will retain the current list of
+matches, however they were generated; this can be turned off explicitly
+with the value `\fBnever\fP', giving the behaviour without the \fB_oldlist\fP
+completer\&.  If the style is unset, or any other value, then the existing
+list of completions is displayed if it is not already; otherwise, the
+standard completion list is generated; this is the default behaviour of
+\fB_oldlist\fP\&.  However, if there is an old list and this style contains
+the name of the completer function that generated the list, then the
+old list will be used even if it was generated by a widget which does
+not do listing\&.
+.RS
+.PP
+For example, suppose you type \fB^Xc\fP to use the \fB_correct_word\fP
+widget, which generates a list of corrections for the word under the
+cursor\&.  Usually, typing \fB^D\fP would generate a standard list of
+completions for the word on the command line, and show that\&.  With
+\fB_oldlist\fP, it will instead show the list of corrections already
+generated\&.
+.PP
+As another example consider the \fB_match\fP completer: with the
+\fBinsert\-unambiguous\fP style set to `true' it inserts only a common prefix
+string, if there is any\&.  However, this may remove parts of the original
+pattern, so that further completion could produce more matches than on the
+first attempt\&.  By using the \fB_oldlist\fP completer and setting this style
+to \fB_match\fP, the list of matches generated on the first attempt will be
+used again\&.
+.RE
+.TP
+\fBold\-matches\fP
+This is used by the \fB_all_matches\fP completer to decide if an old
+list of matches should be used if one exists\&.  This is selected by one of
+the `true' values or by the string `\fBonly\fP'\&.  If
+the value is `\fBonly\fP', \fB_all_matches\fP will only use an old list
+and won't have any effect on the list of matches currently being
+generated\&.
+.RS
+.PP
+If this style is set it is generally unwise to call the \fB_all_matches\fP
+completer unconditionally\&.  One possible use is for either this style or
+the \fBcompleter\fP style to be defined with the \fB\-e\fP option to
+\fBzstyle\fP to make the style conditional\&.
+.RE
+.TP
+\fBold\-menu\fP
+This is used by the \fB_oldlist\fP completer\&.  It controls how menu
+completion behaves when a completion has already been inserted and the
+user types a standard completion key such as \fBTAB\fP\&.  The default
+behaviour of \fB_oldlist\fP is that menu completion always continues
+with the existing list of completions\&.  If this style is set to
+`false', however, a new completion is started if the old list was
+generated by a different completion command; this is the behaviour without
+the \fB_oldlist\fP completer\&.
+.RS
+.PP
+For example, suppose you type \fB^Xc\fP to generate a list of corrections,
+and menu completion is started in one of the usual ways\&.  Usually, or with
+this style set to \fBfalse\fP, typing \fBTAB\fP at this point would start
+trying to complete the line as it now appears\&.  With \fB_oldlist\fP, it
+instead continues to cycle through the list of corrections\&.
+.RE
+.TP
+\fBoriginal\fP
+This is used by the \fB_approximate\fP and \fB_correct\fP
+completers to decide if the original string should be added as
+a possible completion\&.  Normally, this is done only if there are
+at least two possible corrections, but if this style is set to `true', it
+is always added\&.  Note that the style will be examined with the
+completer field in the context name set to \fBcorrect\-\fP\fInum\fP or
+\fBapproximate\-\fP\fInum\fP, where \fInum\fP is the number of errors that
+were accepted\&.
+.TP
+\fBpackageset\fP
+This style is used when completing arguments of the Debian `\fBdpkg\fP'
+program\&.  It contains an override for the default package set
+for a given context\&.  For example,
+.RS
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*:complete:dpkg:option\-\-status\-1:*' \e 
+               packageset avail\fP
+.fi
+.RE
+.PP
+causes available packages, rather than only installed packages,
+to be completed for `dpkg \-\-status'\&.
+.RE
+.TP
+\fBpath\fP
+The function that completes color names uses this style with the 
+\fBcolors\fP tag\&.  The value should be the pathname of a file
+containing color names in the format of an X11 \fBrgb\&.txt\fP file\&.  If
+the style is not set but this file is found in one of various standard
+locations it will be used as the default\&.
+.TP
+\fBpine\-directory\fP
+If set, specifies the directory containing PINE mailbox files\&.  It
+defaults to `\fB~/mail\fP'\&.
+.TP
+\fBports\fP
+A list of Internet service names (network ports) to complete\&.  If this is
+not set, service names are taken from the file `\fB/etc/services\fP'\&.
+.TP
+\fBprefix\-hidden\fP
+This is used for certain completions which share a common prefix, for
+example command options beginning with dashes\&.  If it is `true', the
+prefix will not be shown in the list of matches\&.
+.RS
+.PP
+The default value for this style is `false'\&.
+.RE
+.TP
+\fBprefix\-needed\fP
+This, too, is used for matches with a common prefix\&.  If it is set to
+`true' this common prefix must be typed by the user to generate the
+matches\&.  In the case of command options, this means that the initial
+`\fB\-\fP', `\fB+\fP', or `\fB\-\fP\fB\-\fP' must be typed explicitly before option
+names will be completed\&.
+.RS
+.PP
+The default value for this style is `true'\&.
+.RE
+.TP
+\fBpreserve\-prefix\fP
+This style is used when completing path names\&.  Its value should be a
+pattern matching an initial prefix of the word to complete that should
+be left unchanged under all circumstances\&.  For example, on some Unices
+an initial `\fB//\fP' (double slash) has a special meaning; setting
+this style to the string `\fB//\fP' will preserve it\&.  As another example,
+setting this style to `\fB?:/\fP' under Cygwin would allow completion
+after `\fBa:/\&.\&.\&.\fP' and so on\&.
+.TP
+\fBrange\fP
+This is used by the \fB_history\fP completer and the
+\fB_history_complete_word\fP bindable command to decide which words
+should be completed\&.  
+.RS
+.PP
+If it is a singe number, only the last \fIN\fP words from the history
+will be completed\&.
+.PP
+If it is a range of the form `\fImax\fP\fB:\fP\fIslice\fP',
+the last \fIslice\fP words will be completed; then if that
+yields no matches, the \fIslice\fP words before those will be tried and 
+so on\&.  This process stops either when at least one match was been
+found, or \fImax\fP words have been tried\&.
+.PP
+The default is to complete all words from the history at once\&.
+.RE
+.TP
+\fBregular\fP
+This style is used by the \fB_expand_alias\fP completer and bindable 
+command\&.  If set to `\fBtrue\fP' (the default), regular aliases will be
+expanded but only in command position\&.  If it is set to `\fBfalse\fP',
+regular aliases will never be expanded\&.   If it is set to `\fBalways\fP',
+regular aliases will be expanded even if not in command position\&.
+.TP
+\fBremote\-access\fP
+If set to \fBfalse\fP, certain commands will be prevented from making
+Internet connections to retrieve remote information\&.  This includes the
+completion for the \fBCVS\fP command\&.
+.RS
+.PP
+It is not always possible to know if connections are in fact to a remote
+site, so some may be prevented unnecessarily\&.
+.RE
+.TP
+\fBremove\-all\-dups\fP
+The \fB_history_complete_word\fP bindable command and the \fB_history\fP
+completer use this to decide if all duplicate matches should be
+removed, rather than just consecutive duplicates\&.
+.TP
+\fBselect\-prompt\fP
+If this is set for the \fBdefault\fP tag, its
+value will be displayed during menu selection (see the \fBmenu\fP style
+above) when the completion list does not fit on the screen as a
+whole\&.  The same escapes as for the \fBlist\-prompt\fP style are
+understood, except that the numbers refer to the match or line the mark is
+on\&.  A default prompt is used when the value is the empty string\&.
+.TP
+\fBselect\-scroll\fP
+This style is tested for the \fBdefault\fP tag and determines how a
+completion list is scrolled during a menu selection (see the \fBmenu\fP
+style above) when the completion list does not fit on the screen as a
+whole\&.  If the value is `\fB0\fP' (zero), the list is scrolled by
+half\-screenfuls; if it is a positive integer, the list is scrolled by the
+given number of lines; if it is a negative number, the list is scrolled by a
+screenful minus the absolute value of the given number of lines\&.
+The default is to scroll by single lines\&.
+.TP
+\fBseparate\-sections\fP
+This style is used with the \fBmanuals\fP tag when completing names of
+manual pages\&.  If it is `true', entries for different sections are
+added separately using tag names of the form `\fBmanual\&.\fP\fIX\fP',
+where \fIX\fP is the section number\&.  When the \fBgroup\-name\fP style is
+also in effect, pages from different sections will appear separately\&.
+This style is also used similarly with the \fBwords\fP style when
+completing words for the dict command\&. It allows words from different
+dictionary databases to be added separately\&.
+The default for this style is `false'\&.
+.TP
+\fBshow\-completer\fP
+Tested whenever a new completer is tried\&.  If it is true, the completion
+system outputs a progress message in the listing area showing what
+completer is being tried\&.  The message will be overwritten by any output
+when completions are found and is removed after completion is finished\&.
+.TP
+\fBsingle\-ignored\fP
+This is used by the \fB_ignored\fP completer when there is only one match\&.
+If its value is `\fBshow\fP', the single match will be
+displayed but not inserted\&.  If the value is `\fBmenu\fP', then the single
+match and the original string are both added as matches and menu completion
+is started, making it easy to select either of them\&.
+.TP
+\fBsort\fP
+Many completion widgets call \fB_description\fP at some point which
+decides whether the matches are added sorted or unsorted (often
+indirectly via \fB_wanted\fP or \fB_requested\fP)\&.  This style can be set
+explicitly to one of the usual true or false values as an override\&.
+If it is not set for the context, the standard behaviour of the
+calling widget is used\&.
+.RS
+.PP
+The style is tested first against the full context including the tag, and
+if that fails to produce a value against the context without the tag\&.
+.PP
+If the calling widget explicitly requests unsorted matches, this is usually
+honoured\&.  However, the default (unsorted) behaviour of completion
+for the command history may be overridden by setting the style to
+\fBtrue\fP\&.
+.PP
+In the \fB_expand\fP completer, if it is set to
+`true', the expansions generated will always be sorted\&.  If it is set
+to `\fBmenu\fP', then the expansions are only sorted when they are offered 
+as single strings but not in the string containing all possible
+expansions\&.
+.RE
+.TP
+\fBspecial\-dirs\fP
+Normally, the completion code will not produce the directory names
+`\fB\&.\fP' and `\fB\&.\&.\fP' as possible completions\&.  If this style is set to
+`true', it will add both `\fB\&.\fP' and `\fB\&.\&.\fP' as possible completions;
+if it is set to `\fB\&.\&.\fP', only `\fB\&.\&.\fP' will be added\&.
+.RS
+.PP
+The following example sets \fBspecial\-dirs\fP to `\fB\&.\&.\fP' when the
+current prefix is empty, is a single `\fB\&.\fP', or consists only of a path
+beginning with `\fB\&.\&./\fP'\&.  Otherwise the value is `false'\&.
+.PP
+.RS
+.nf
+\fBzstyle \-e ':completion:*' special\-dirs \e 
+   '[[ $PREFIX = (\&.\&./)#(|\&.|\&.\&.) ]] && reply=(\&.\&.)'\fP
+.fi
+.RE
+.RE
+.TP
+\fBsqueeze\-slashes\fP
+If set to `true', sequences of slashes in filename paths (for example in
+`\fBfoo//bar\fP') will be treated as a single slash\&.  This is the usual
+behaviour of UNIX paths\&.  However, by default the file completion
+function behaves as if there were a `\fB*\fP' between the slashes\&.
+.TP
+\fBstop\fP
+If set to `true', the \fB_history_complete_word\fP bindable
+command will stop once when reaching the beginning or end of the
+history\&.  Invoking \fB_history_complete_word\fP will then wrap around to 
+the opposite end of the history\&.  If this style is set to `false' (the 
+default), \fB_history_complete_word\fP will loop immediately as in a
+menu completion\&.
+.TP
+\fBstrip\-comments\fP
+If set to `true', this style causes non\-essential comment text to be
+removed from completion matches\&.  Currently it is only used when
+completing e\-mail addresses where it removes any display name from the
+addresses, cutting them down to plain \fIuser@host\fP form\&.
+.TP
+\fBsubst\-globs\-only\fP
+This is used by the \fB_expand\fP completer\&.  If it is set to `true',
+the expansion will only be used if it resulted from globbing; hence,
+if expansions resulted from the use of the \fBsubstitute\fP style
+described below, but these were not further changed by globbing, the
+expansions will be rejected\&.
+.RS
+.PP
+The default for this style is `false'\&.
+.RE
+.TP
+\fBsubstitute\fP
+This boolean style controls whether the \fB_expand\fP completer will
+first try to expand all substitutions in the string (such as
+`\fB$(\&.\&.\&.)\fP' and `\fB${\&.\&.\&.}\fP')\&.
+.RS
+.PP
+The default is `true'\&.
+.RE
+.TP
+\fBsuffix\fP
+This is used by the \fB_expand\fP completer if the word starts with a
+tilde or contains a parameter expansion\&.  If it is set to `true', the
+word will only be expanded if it doesn't have a suffix, i\&.e\&. if it is
+something like `\fB~foo\fP' or `\fB$foo\fP' rather than `\fB~foo/\fP' or
+`\fB$foo/bar\fP', unless that suffix itself contains characters eligible
+for expansion\&.  The default for this style is `true'\&.
+.TP
+\fBtag\-order\fP
+This provides a mechanism for sorting how the tags available in a
+particular context will be used\&.
+.RS
+.PP
+The values for the style are sets of space\-separated lists of tags\&.
+The tags in each value will be tried at the same time; if no match is
+found, the next value is used\&.  (See the \fBfile\-patterns\fP style for
+an exception to this behavior\&.)
+.PP
+For example:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*:complete:\-command\-:*' tag\-order \e 
+    'commands functions'\fP
+.fi
+.RE
+.PP
+specifies that completion in command position first offers
+external commands and shell functions\&.  Remaining tags will be tried if
+no completions are found\&.
+.PP
+In addition to tag names, each string in the value may take one of the
+following forms:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-\fP
+If any value consists of only a hyphen,
+then \fIonly\fP the tags specified in the other values are
+generated\&.  Normally all tags not explicitly selected are tried last
+if the specified tags fail to generate any matches\&.  This means 
+that a single value consisting only of a single hyphen
+turns off completion\&.
+.TP
+\fB!\fP \fItags\fP\&.\&.\&.
+A string starting with an exclamation mark
+specifies names of tags that are \fInot\fP to be used\&.  The effect is
+the same as if all other possible tags for the context had been
+listed\&.
+.TP
+\fItag\fP\fB:\fP\fIlabel\fP \&.\&.\&.
+Here, \fItag\fP is one of the standard tags and \fIlabel\fP is an
+arbitrary name\&.  Matches are generated as normal but the name \fIlabel\fP
+is used in contexts instead of \fItag\fP\&.  This is not useful in words
+starting with \fB!\fP\&.
+.RS
+.PP
+If the \fIlabel\fP starts with a hyphen, the \fItag\fP is prepended to the
+\fIlabel\fP to form the name used for lookup\&.  This can be
+used to make the completion system try a certain tag more than once,
+supplying different style settings for each attempt; see below for an
+example\&.
+.RE
+.TP
+\fItag\fP\fB:\fP\fIlabel\fP\fB:\fP\fIdescription\fP
+As before, but \fBdescription\fP will replace the `\fB%d\fP' in
+the value of the \fBformat\fP style instead of the default description
+supplied by the completion function\&.  Spaces in the description must
+be quoted with a backslash\&.  A `\fB%d\fP' appearing
+in \fIdescription\fP is replaced with the description given by the
+completion function\&.
+.PP
+In any of the forms above the tag may be a pattern or several
+patterns in the form `\fB{\fP\fIpat1\fP\fB,\fP\fIpat2\&.\&.\&.\fP\fB}\fP'\&.  In this
+case all matching tags will be used except 
+for any given explicitly in the same string\&.
+.PP
+One use of these features is to try
+one tag more than once, setting other styles differently on
+each attempt, but still to use all the other tags without having to
+repeat them all\&.  For example, to make completion of function names in
+command position ignore all the completion functions starting with an
+underscore the first time completion is tried:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*:*:\-command\-:*' tag\-order \e 
+    'functions:\-non\-comp *' functions
+zstyle ':completion:*:functions\-non\-comp' ignored\-patterns '_*'\fP
+.fi
+.RE
+.PP
+On the first attempt, all tags will be offered but the \fBfunctions\fP tag
+will be replaced by \fBfunctions\-non\-comp\fP\&.  The \fBignored\-patterns\fP style 
+is set for this tag to exclude functions starting with an underscore\&.
+If there are no matches, the second value of the
+\fBtag\-order\fP style is used which completes functions using the default
+tag, this time presumably including all function names\&.
+.PP
+The matches for one tag can be split into different groups\&.  For example:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' tag\-order \e 
+    'options:\-long:long\e options
+     options:\-short:short\e options
+     options:\-single\-letter:single\e letter\e options'
+.PP
+zstyle ':completion:*:options\-long' ignored\-patterns '[\-+](|\-|[^\-]*)'
+zstyle ':completion:*:options\-short' ignored\-patterns '\-\-*' '[\-+]?'
+zstyle ':completion:*:options\-single\-letter' ignored\-patterns '???*'\fP
+.fi
+.RE
+.PP
+With the \fBgroup\-names\fP style set, options beginning with
+`\fB\-\fP\fB\-\fP', options beginning with a single `\fB\-\fP' or `\fB+\fP' but
+containing multiple characters, and single\-letter options will be
+displayed in separate groups with different descriptions\&.
+.PP
+Another use of patterns is to
+try multiple match specifications one after another\&.  The
+\fBmatcher\-list\fP style offers something similar, but it is tested very
+early in the completion system and hence can't be set for single
+commands nor for more specific contexts\&.  Here is how to
+try normal completion without any match specification and, if that
+generates no matches, try again with case\-insensitive matching, restricting
+the effect to arguments of the command \fBfoo\fP:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*:*:foo:*' tag\-order '*' '*:\-case'
+zstyle ':completion:*\-case' matcher 'm:{a\-z}={A\-Z}'\fP
+.fi
+.RE
+.PP
+First, all the tags offered when completing after \fBfoo\fP are tried using
+the normal tag name\&.  If that generates no matches, the second value of
+\fBtag\-order\fP is used, which tries all tags again except that this time
+each has \fB\-case\fP appended to its name for lookup of styles\&.  Hence this
+time the value for the \fBmatcher\fP style from the second call to \fBzstyle\fP
+in the example is used to make completion case\-insensitive\&.
+.PP
+It is possible to use the \fB\-e\fP option of the \fBzstyle\fP builtin
+command to specify conditions for the use of particular tags\&.  For
+example:
+.PP
+.RS
+.nf
+\fBzstyle \-e '*:\-command\-:*' tag\-order '
+    if [[ \-n $PREFIX$SUFFIX ]]; then
+      reply=( )
+    else
+      reply=( \- )
+    fi'\fP
+.fi
+.RE
+.PP
+Completion in command position will be attempted only if the string
+typed so far is not empty\&.  This is tested using the \fBPREFIX\fP
+special parameter; see
+zshcompwid
+for a description of parameters which are special inside completion widgets\&.
+Setting \fBreply\fP to an empty array provides the default
+behaviour of trying all tags at once; setting it to an
+array containing only a hyphen disables the use of all tags and hence of
+all completions\&.
+.PP
+If no \fBtag\-order\fP style has been defined for a context, the strings
+`\fB(|*\-)argument\-* (|*\-)option\-* values\fP' and `\fBoptions\fP' plus all
+tags offered by the completion function will be used to provide a
+sensible default behavior that causes arguments (whether normal command
+arguments or arguments of options) to be completed before option names for
+most commands\&.
+.RE
+.TP
+\fBurls\fP
+This is used together with the the \fBurls\fP tag by
+functions completing URLs\&.
+.RS
+.PP
+If the value consists of more than one string, or if the only string
+does not name a file or directory, the strings are used as the URLs to
+complete\&.
+.PP
+If the value contains only one string which is the name of a normal 
+file the URLs are taken from that file (where the URLs may be
+separated by white space or newlines)\&.
+.PP
+Finally, if the only string in the value names a directory, the
+directory hierarchy rooted at this directory gives the completions\&.  The
+top level directory should be the file access method, such as
+`\fBhttp\fP', `\fBftp\fP', `\fBbookmark\fP' and so on\&.  In many cases the next
+level of directories will be a filename\&.  The directory hierarchy can
+descend as deep as necessary\&.
+.PP
+For example, 
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' urls ~/\&.urls
+mkdir \-p ~/\&.urls/ftp/ftp\&.zsh\&.org/pub/development
+\fP
+.fi
+.RE
+.PP
+allows completion of all the components of the URL
+\fBftp://ftp\&.zsh\&.org/pub/development\fP after suitable commands such as
+`\fBnetscape\fP' or `\fBlynx\fP'\&.  Note, however, that access methods and
+files are completed separately, so if the \fBhosts\fP style is set hosts
+can be completed without reference to the \fBurls\fP style\&.
+.PP
+See the description in the function \fB_urls\fP itself
+for more information (e\&.g\&. `\fBmore $^fpath/_urls(N)\fP')\&.
+.RE
+.TP
+\fBuse\-cache\fP
+If this is set, the completion caching layer is activated for any completions
+which use it (via the \fB_store_cache\fP, \fB_retrieve_cache\fP, and
+\fB_cache_invalid\fP functions)\&.  The directory containing the cache
+files can be changed with the \fBcache\-path\fP style\&.
+.TP
+\fBuse\-compctl\fP
+If this style is set to a string \fInot\fP equal to \fBfalse\fP, \fB0\fP,
+\fBno\fP, and \fBoff\fP, the completion system may use any completion
+specifications defined with the \fBcompctl\fP builtin command\&.  If the
+style is unset, this is done only if the \fBzsh/compctl\fP module
+is loaded\&.  The string may also contain the substring `\fBfirst\fP' to
+use completions defined with `\fBcompctl \-T\fP', and the substring
+`\fBdefault\fP' to use the completion defined with `\fBcompctl \-D\fP'\&.
+.RS
+.PP
+Note that this is only intended to smooth the transition from
+\fBcompctl\fP to the new completion system and may disappear in the
+future\&.
+.PP
+Note also that the definitions from \fBcompctl\fP will only be used if
+there is no specific completion function for the command in question\&.  For
+example, if there is a function \fB_foo\fP to complete arguments to the
+command \fBfoo\fP, \fBcompctl\fP will never be invoked for \fBfoo\fP\&.
+However, the \fBcompctl\fP version will be tried if \fBfoo\fP only uses
+default completion\&.
+.RE
+.TP
+\fBuse\-perl\fP
+Various parts of the function system use awk to extract words from
+files or command output as this universally available\&.  However, many
+versions of awk have arbitrary limits on the size of input\&.  If this
+style is set, perl will be used instead\&.  This is almost always
+preferable if perl is available on your system\&.
+.RS
+.PP
+Currently this is only used in completions for `make', but it may be
+extended depending on authorial frustration\&.
+.RE
+.TP
+\fBusers\fP
+This may be set to a list of usernames to be completed\&.
+If it is not set or the string on the line
+doesn't match any of the strings in this list, all usernames will be
+completed\&.
+.TP
+\fBusers\-hosts\fP
+The values of this style should be of the form
+`\fIuser\fP\fB@\fP\fIhost\fP' or `\fIuser\fP\fB:\fP\fIhost\fP'\&. It is used for
+commands that need pairs of
+user\- and hostnames\&.  These commands will complete usernames from this
+style (only), and will restrict subsequent hostname completion to hosts
+paired with that user in one of the values of the style\&.
+.RS
+.PP
+It is possible to group values for sets of commands which allow a remote
+login, such as \fBrlogin\fP and \fBssh\fP, by using the \fBmy\-accounts\fP tag\&.
+Similarly, values for sets of commands which usually refer to the
+accounts of other people, such as \fBtalk\fP and \fBfinger\fP, can be
+grouped by using the \fBother\-accounts\fP tag\&.  More ambivalent commands
+may use the \fBaccounts\fP tag\&.
+.RE
+.TP
+\fBusers\-hosts\-ports\fP
+Like \fBusers\-hosts\fP but used for commands like \fBtelnet\fP and
+containing strings of the form `\fIuser\fP\fB@\fP\fIhost\fP\fB:\fP\fIport\fP'\&.
+.TP
+\fBverbose\fP
+If set, as it is by default, the completion listing is more verbose\&.
+In particular many commands show descriptions for options if this
+style is `true'\&.
+.TP
+\fBword\fP
+This is used by the \fB_list\fP completer, which prevents the insertion of
+completions until a second completion attempt when the line has not
+changed\&.  The normal way of finding out if the line has changed is to
+compare its entire contents between the two occasions\&.  If this style is
+true, the comparison is instead performed only on the current word\&.
+Hence if completion is performed on another word with the same contents,
+completion will not be delayed\&.
+.PP
+.SH "CONTROL FUNCTIONS"
+.PP
+The initialization script \fBcompinit\fP redefines all the widgets
+which perform completion to call the supplied widget function
+\fB_main_complete\fP\&.  This function acts as a wrapper calling the
+so\-called `completer' functions that generate matches\&.  If
+\fB_main_complete\fP is called with arguments, these are taken as the
+names of completer functions to be called in the order given\&.  If no
+arguments are given, the set of functions to try is taken from the
+\fBcompleter\fP style\&.  For example, to use normal completion and
+correction if that doesn't generate any matches:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' completer _complete _correct\fP
+.fi
+.RE
+.PP
+after calling \fBcompinit\fP\&. The default value for this style is
+`\fB_complete _ignored\fP', i\&.e\&. normally only ordinary completion is tried,
+first with the effect of the \fBignored\-patterns\fP style and then without
+it\&.  The \fB_main_complete\fP function uses the return value of the completer
+functions to decide if other completers should be called\&.  If the return
+value is zero, no other completers are tried and the \fB_main_complete\fP
+function returns\&.
+.PP
+If the first argument to \fB_main_complete\fP is a single hyphen, the
+arguments will not be taken as names of completers\&.  Instead, the
+second argument gives a name to use in the \fIcompleter\fP field of the 
+context and the other arguments give a command name and arguments to
+call to generate the matches\&.
+.PP
+The following completer functions are contained in the distribution,
+although users may write their own\&.  Note that in contexts the leading
+underscore is stripped, for example basic completion is performed in the
+context `\fB:completion::complete:\fP\fI\&.\&.\&.\fP'\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB_all_matches\fP
+This completer can be used to add a string consisting of all other
+matches\&.  As it influences later completers it must appear as the first
+completer in the list\&.  The list of all matches is affected by the
+\fBavoid\-completer\fP and \fBold\-matches\fP styles described above\&.
+.RS
+.PP
+It may be useful to use the \fB_generic\fP function described below
+to bind \fB_all_matches\fP to its own keystroke, for example:
+.PP
+.RS
+.nf
+\fBzle \-C all\-matches complete\-word _generic
+bindkey '^Xa' all\-matches
+zstyle ':completion:all\-matches:*' old\-matches only
+zstyle ':completion:all\-matches::::' completer _all_matches\fP
+.fi
+.RE
+.RE
+.TP
+\fB_approximate\fP
+This is similar to the basic \fB_complete\fP completer but allows the
+completions to undergo corrections\&.  The maximum number of errors can be
+specified by the \fBmax\-errors\fP style; see the description of
+approximate matching in
+\fIzshexpn\fP(1)
+for how errors are counted\&.  Normally this completer will only be tried
+after the normal \fB_complete\fP completer:
+.RS
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' completer _complete _approximate\fP
+.fi
+.RE
+.PP
+This will give correcting completion if and only if
+normal completion yields no possible completions\&.  When
+corrected completions are found, the completer will normally start
+menu completion allowing you to cycle through these strings\&.
+.PP
+This completer uses the tags \fBcorrections\fP and \fBoriginal\fP when
+generating the possible corrections and the original string\&.  The
+\fBformat\fP style for the former may contain the additional sequences
+`\fB%e\fP' and `\fB%o\fP' which will be replaced by the number of errors
+accepted to generate the corrections and the original string,
+respectively\&.
+.PP
+The completer progressively increases the number of errors allowed up to
+the limit by the \fBmax\-errors\fP style, hence if a completion is found
+with one error, no completions with two errors will be shown, and so on\&.
+It modifies the completer name in the context to indicate the number of
+errors being tried: on the first try the completer field contains
+`\fBapproximate\-1\fP', on the second try `\fBapproximate\-2\fP', and so on\&.
+.PP
+When \fB_approximate\fP is called from another function, the number of
+errors to accept may be passed with the \fB\-a\fP option\&.  The argument
+is in the same format as the \fBmax\-errors\fP style, all in one string\&.
+.PP
+Note that this completer (and the \fB_correct\fP completer mentioned
+below) can be quite expensive to call, especially when a large number
+of errors are allowed\&.  One way to avoid this is to set up the
+\fBcompleter\fP style using the \fB\-e\fP option to zstyle so that some
+completers are only used when completion is attempted a second time on 
+the same string, e\&.g\&.:
+.PP
+.RS
+.nf
+\fBzstyle \-e ':completion:*' completer '
+  if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then
+    _last_try="$HISTNO$BUFFER$CURSOR"
+    reply=(_complete _match _prefix)
+  else
+    reply=(_ignored _correct _approximate)
+  fi'\fP
+.fi
+.RE
+.PP
+This uses the \fBHISTNO\fP parameter and the \fBBUFFER\fP and \fBCURSOR\fP
+special parameters that are available inside zle and completion
+widgets to find out if the command line hasn't changed since the last
+time completion was tried\&.  Only then are the \fB_ignored\fP,
+\fB_correct\fP and \fB_approximate\fP completers called\&.
+.RE
+.TP
+\fB_complete\fP
+This completer generates all possible completions in a context\-sensitive
+manner, i\&.e\&. using the settings defined with the \fBcompdef\fP function
+explained above and the current settings of all special parameters\&.
+This gives the normal completion behaviour\&.
+.RS
+.PP
+To complete arguments of commands, \fB_complete\fP uses the utility function
+\fB_normal\fP, which is in turn responsible for finding the particular
+function; it is described below\&.  Various contexts of the form
+\fB\-\fP\fIcontext\fP\fB\-\fP are handled specifically\&. These are all
+mentioned above as possible arguments to the \fB#compdef\fP tag\&.
+.PP
+Before trying to find a function for a specific context, \fB_complete\fP 
+checks if the parameter `\fBcompcontext\fP' is set\&. Setting
+`\fBcompcontext\fP' allows the usual completion dispatching to be
+overridden which is useful in places such as a function that uses
+\fBvared\fP for input\&. If it is set to an array, the elements are taken
+to be the possible matches which will be completed using the tag
+`\fBvalues\fP' and the description `\fBvalue\fP'\&. If it is set to an
+associative array, the keys are used as the possible completions and
+the values (if non\-empty) are used as descriptions for the matches\&.  If
+`\fBcompcontext\fP' is set to a string containing colons, it should be of
+the form `\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP'\&.  In this case the
+\fItag\fP and \fIdescr\fP give the tag and description to use and the
+\fIaction\fP indicates what should be completed in one of the forms
+accepted by the \fB_arguments\fP utility function described below\&.
+.PP
+Finally, if `\fBcompcontext\fP' is set to a string without colons, the
+value is taken as the name of the context to use and the function
+defined for that context will be called\&.  For this purpose, there is a
+special context named \fB\-command\-line\-\fP that completes whole command
+lines (commands and their arguments)\&.  This is not used by the completion
+system itself but is nonetheless handled when explicitly called\&.
+.RE
+.TP
+\fB_correct\fP
+Generate corrections, but not completions, for the current word; this is
+similar to \fB_approximate\fP but will not allow any number of extra
+characters at the cursor as that completer does\&.  The effect is
+similar to spell\-checking\&.  It is based on \fB_approximate\fP, but the
+completer field in the context name is \fBcorrect\fP\&.
+.RS
+.PP
+For example, with:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:::::' completer _complete _correct _approximate
+zstyle ':completion:*:correct:::' max\-errors 2 not\-numeric
+zstyle ':completion:*:approximate:::' max\-errors 3 numeric\fP
+.fi
+.RE
+.PP
+correction will accept up to two errors\&.  If a numeric argument is
+given, correction will not be performed, but correcting completion
+will be, and will accept as many errors as given by the numeric
+argument\&.  Without a numeric argument, first correction and then
+correcting completion will be tried, with the first one accepting two
+errors and the second one accepting three errors\&.
+.PP
+When \fB_correct\fP is called as a function, the number of errors to accept
+may be given following the \fB\-a\fP option\&.  The argument is in the same
+form a values to the \fBaccept\fP style, all in one string\&.
+.PP
+This completer function is intended to be used without the
+\fB_approximate\fP completer or, as in the example, just before
+it\&.  Using it after the \fB_approximate\fP completer is useless since
+\fB_approximate\fP will at least generate the corrected strings
+generated by the \fB_correct\fP completer \-\- and probably more\&.
+.RE
+.TP
+\fB_expand\fP
+This completer function does not really perform completion, but instead
+checks if the word on the command line is eligible for expansion and,
+if it is, gives detailed control over how this expansion is done\&.  For
+this to happen, the completion system needs to be invoked with
+\fBcomplete\-word\fP, not \fBexpand\-or\-complete\fP (the default binding for
+\fBTAB\fP), as otherwise the string will be expanded by the shell's
+internal mechanism before the completion system is started\&.
+Note also this completer should be called before the \fB_complete\fP 
+completer function\&.
+.RS
+.PP
+The tags used when generating expansions are \fBall\-expansions\fP for the
+string containing all possible expansions, \fBexpansions\fP when adding
+the possible expansions as single matches and \fBoriginal\fP when adding
+the original string from the line\&.  The order in which these strings are
+generated, if at all, can be controlled by the \fBgroup\-order\fP and
+\fBtag\-order\fP styles, as usual\&.
+.PP
+The format string for \fBall\-expansions\fP and for \fBexpansions\fP may
+contain the sequence `\fB%o\fP' which will be replaced by the original
+string from the line\&.
+.PP
+The kind of expansion to be tried is controlled by the \fBsubstitute\fP,
+\fBglob\fP and \fBsubst\-globs\-only\fP styles\&.
+.PP
+It is also possible to call \fB_expand\fP as a function, in which case the
+different modes may be selected with options: \fB\-s\fP for
+\fBsubstitute\fP, \fB\-g\fP for \fBglob\fP and \fB\-o\fP for \fBsubst\-globs\-only\fP\&.
+.RE
+.TP
+\fB_expand_alias\fP
+If the word the cursor is on is an alias, it is expanded and no other
+completers are called\&.  The types of aliases which are to be expanded can
+be controlled with the styles \fBregular\fP, \fBglobal\fP and \fBdisabled\fP\&.
+.RS
+.PP
+This function is also a bindable command, see
+the section `Bindable Commands' below\&.
+.RE
+.TP
+\fB_history\fP
+Complete words from the shell's command  history\&.  This completer 
+can be controlled by the \fBremove\-all\-dups\fP, and \fBsort\fP styles as for the
+\fB_history_complete_word\fP bindable command, see
+the section `Bindable Commands' below
+and
+the section `Completion System Configuration' above\&.
+.TP
+\fB_ignored\fP
+The \fBignored\-patterns\fP style can be set to a list of patterns which are
+compared against possible completions; matching ones are removed\&.
+With this completer those matches can be reinstated, as
+if no \fBignored\-patterns\fP style were set\&.  The completer actually
+generates its own list of matches; which completers are invoked
+is determined in the same way as for the \fB_prefix\fP completer\&.
+The \fBsingle\-ignored\fP style is also available as described above\&.
+.TP
+\fB_list\fP
+This completer allows the insertion of matches to be delayed until
+completion is attempted a second time without the word on the line
+being changed\&.  On the first attempt, only the list of matches will be
+shown\&.  It is affected by the styles \fBcondition\fP and \fBword\fP, see
+the section `Completion System Configuration' above\&.
+.TP
+\fB_match\fP
+This completer is intended to be used after the \fB_complete\fP
+completer\&.  It behaves similarly but the string on the command line may
+be a pattern to match against trial completions\&.  This gives the effect
+of the \fBGLOB_COMPLETE\fP option\&.
+.RS
+.PP
+Normally completion will be performed by taking the pattern from the line,
+inserting a `\fB*\fP' at the cursor position and comparing the resulting
+pattern with the possible completions generated\&.  This can be modified
+with the \fBmatch\-original\fP style described above\&.
+.PP
+The generated matches will be offered in a menu completion unless the
+\fBinsert\-unambiguous\fP style is set to `true'; see the description above
+for other options for this style\&.
+.PP
+Note that matcher specifications defined globally or used by the
+completion functions (the styles \fBmatcher\-list\fP and \fBmatcher\fP) will
+not be used\&.
+.RE
+.TP
+\fB_menu\fP
+This completer was written as simple example function to show how menu
+completion can be enabled in shell code\&. However, it has the notable
+effect of disabling menu selection which can be useful with
+\fB_generic\fP based widgets\&. It should be used as the first completer in
+the list\&.  Note that this is independent of the setting of the
+\fBMENU_COMPLETE\fP option and does not work with the other menu
+completion widgets such as \fBreverse\-menu\-complete\fP, or
+\fBaccept\-and\-menu\-complete\fP\&.
+.TP
+\fB_oldlist\fP
+This completer controls how the standard completion widgets behave
+when there is an existing list of completions which may have been
+generated by a special completion (i\&.e\&. a separately\-bound completion
+command)\&.  It allows the ordinary completion keys to continue to use the
+list of completions thus generated, instead of producing a new list of
+ordinary contextual completions\&.
+It should appear in the list of completers before any of
+the widgets which generate matches\&.  It uses two styles: \fBold\-list\fP and
+\fBold\-menu\fP, see
+the section `Completion System Configuration' above\&.
+.TP
+\fB_prefix\fP
+This completer can be used to try completion with the suffix (everything
+after the cursor) ignored\&.  In other words, the suffix will not be
+considered to be part of the word to complete\&.  The effect is similar
+to the \fBexpand\-or\-complete\-prefix\fP command\&.
+.RS
+.PP
+The \fBcompleter\fP style is used to decide which other completers are to
+be called to generate matches\&.  If this style is unset, the list of
+completers set for the current context is used \-\- except, of course, the
+\fB_prefix\fP completer itself\&.  Furthermore, if this completer appears
+more than once in the list of completers only those completers not
+already tried by the last invocation of \fB_prefix\fP will be called\&.
+.PP
+For example, consider this global \fBcompleter\fP style:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' completer \e 
+    _complete _prefix _correct _prefix:foo\fP
+.fi
+.RE
+.PP
+Here, the \fB_prefix\fP completer tries normal completion but ignoring the
+suffix\&.  If that doesn't generate any matches, and neither does
+the call to the \fB_correct\fP completer after it, \fB_prefix\fP will 
+be called a second time and, now only trying correction with the
+suffix ignored\&.  On the second invocation the completer part of the
+context appears as `\fBfoo\fP'\&.
+.PP
+To use \fB_prefix\fP as the last resort and try only normal completion
+when it is invoked:
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' completer _complete \&.\&.\&. _prefix
+zstyle ':completion::prefix:*' completer _complete\fP
+.fi
+.RE
+.PP
+The \fBadd\-space\fP style is also respected\&.  If it is set to `true' then
+\fB_prefix\fP will insert a space between the matches generated (if any) 
+and the suffix\&.
+.PP
+Note that this completer is only useful if the
+\fBCOMPLETE_IN_WORD\fP option is set; otherwise, the cursor will
+be moved to the end of the current word before the completion code is
+called and hence there will be no suffix\&.
+.RE
+.TP
+\fBbashcompinit\fP
+This function provides compatibility with bash's programmable completion
+system\&.  When run it will define the functions, \fBcompgen\fP and
+\fBcomplete\fP which correspond to the bash builtins with the same names\&.
+It will then be possible to use completion specifications and functions
+written for bash\&.
+.PP
+.SH "BINDABLE COMMANDS"
+.PP
+In addition to the context\-dependent completions provided, which are
+expected to work in an intuitively obvious way, there are a few widgets
+implementing special behaviour which can be bound separately to keys\&.  The
+following is a list of these and their default bindings\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB_bash_completions\fP
+This function is used by two widgets, \fB_bash_complete\-word\fP and
+\fB_bash_list\-choices\fP\&.  It exists to provide compatibility with
+completion bindings in bash\&.  The last character of the binding determines
+what is completed: `\fB!\fP', command names; `\fB$\fP', environment variables;
+`\fB@\fP', host names; `\fB/\fP', file names; `\fB~\fP' user names\&.  In bash, the
+binding preceded by `\fB\ee\fP' gives completion, and preceded by `\fB^X\fP'
+lists options\&.  As some of these bindings clash with standard zsh
+bindings, only `\fB\ee~\fP' and `\fB^X~\fP' are bound by default\&.  To add the
+rest, the following should be added to \fB\&.zshrc\fP after \fBcompinit\fP has
+been run:
+.RS
+.PP
+.RS
+.nf
+\fBfor key in '!' '$' '@' '/' '~'; do
+  bindkey "\ee$key" _bash_complete\-word
+  bindkey "^X$key" _bash_list\-choices
+done\fP
+.fi
+.RE
+.PP
+This includes the bindings for `\fB~\fP' in case they were already bound to
+something else; the completion code does not override user bindings\&.
+.RE
+.TP
+\fB_correct_filename (^XC)\fP
+Correct the filename path at the cursor position\&.  Allows up to six errors
+in the name\&.  Can also be called with an argument to correct
+a filename path, independently of zle; the correction is printed on
+standard output\&.
+.TP
+\fB_correct_word\fP (^Xc)
+Performs correction of the current argument using the usual contextual
+completions as possible choices\&. This stores the string
+`\fBcorrect\-word\fP' in the \fIfunction\fP field of the context name and
+then calls the \fB_correct\fP completer\&.
+.TP
+\fB_expand_alias (^Xa)\fP
+This function can be used as a completer and as a bindable command\&.
+It expands the word the cursor is on if it is an alias\&.  The types of
+alias expanded can be controlled with the styles \fBregular\fP, \fBglobal\fP
+and \fBdisabled\fP\&.
+.RS
+.PP
+When used as a bindable command there is one additional feature that
+can be selected by setting the \fBcomplete\fP style to `true'\&.  In this
+case, if the word is not the name of an alias, \fB_expand_alias\fP tries
+to complete the word to a full alias name without expanding it\&.  It
+leaves the cursor directly after the completed word so that invoking
+\fB_expand_alias\fP once more will expand the now\-complete alias name\&.
+.RE
+.TP
+\fB_expand_word (^Xe)\fP
+Performs expansion on the current word:  equivalent to the standard
+\fBexpand\-word\fP command, but using the \fB_expand\fP completer\&.  Before
+calling it, the \fIfunction\fP field of the context is set to
+`\fBexpand\-word\fP'\&.
+.TP
+\fB_generic\fP
+This function is not defined as a widget and not bound by
+default\&.  However, it can be used to define a widget and will then
+store the name of the widget in the \fIfunction\fP field of the context 
+and call the completion system\&.  This allows custom completion widgets
+with their own set of style settings to be defined easily\&.  For example, 
+to define a widget that performs normal completion and starts
+menu selection:
+.RS
+.PP
+.RS
+.nf
+\fBzle \-C foo complete\-word _generic
+bindkey '\&.\&.\&.' foo
+zstyle ':completion:foo:*' menu yes select=1\fP
+.fi
+.RE
+.RE
+.TP
+\fB_history_complete_word\fP (\ee/)
+Complete words from the shell's command history\&. This uses the
+\fBlist\fP, \fBremove\-all\-dups\fP, \fBsort\fP, and \fBstop\fP styles\&.
+.TP
+\fB_most_recent_file (^Xm)\fP
+Complete the name of the most recently modified file matching the pattern
+on the command line (which may be blank)\&.  If given a numeric argument
+\fIN\fP, complete the \fIN\fPth most recently modified file\&.  Note the
+completion, if any, is always unique\&.
+.TP
+\fB_next_tags\fP (^Xn)
+This command alters the set of matches used to that for the next tag, or
+set of tags, either as given by the \fBtag\-order\fP style or as set by
+default; these matches would otherwise not be available\&.
+Successive invocations of the command cycle through all possible sets of
+tags\&.
+.TP
+\fB_read_comp (^X^R)\fP
+Prompt the user for a string, and use that to perform completion on the
+current word\&.  There are two possibilities for the string\&.  First, it can
+be a set of words beginning `\fB_\fP', for example `\fB_files \-/\fP', in which
+case the function with any arguments will be called to generate the
+completions\&.  Unambiguous parts of the function name will be completed
+automatically (normal completion is not available at this point) until a
+space is typed\&.
+.RS
+.PP
+Second, any other string will be passed as a set of arguments to
+\fBcompadd\fP and should hence be an expression specifying what should
+be completed\&.
+.PP
+A very restricted set of editing commands is available when reading the
+string:  `\fBDEL\fP' and `\fB^H\fP' delete the last character; `\fB^U\fP' deletes
+the line, and `\fB^C\fP' and `\fB^G\fP' abort the function, while `\fBRET\fP'
+accepts the completion\&.  Note the string is used verbatim as a command
+line, so arguments must be quoted in accordance with standard shell rules\&.
+.PP
+Once a string has been read, the next call to \fB_read_comp\fP will use the
+existing string instead of reading a new one\&.  To force a new string to be
+read, call \fB_read_comp\fP with a numeric argument\&.
+.RE
+.TP
+\fB_complete_debug (^X?)\fP
+This widget performs ordinary completion, but captures in a temporary file
+a trace of the shell commands executed by the completion system\&.  Each
+completion attempt gets its own file\&.  A command to view each of these
+files is pushed onto the editor buffer stack\&.
+.TP
+\fB_complete_help (^Xh)\fP
+This widget displays information about the context names, 
+the tags, and the completion functions used 
+when completing at the current cursor position\&. If given a numeric
+argument other than \fB1\fP (as in `\fBESC\-2 ^Xh\fP'), then the styles
+used and the contexts for which they are used will be shown, too\&.
+.RS
+.PP
+Note that the information about styles may be incomplete; it depends on the
+information available from the completion functions called, which in turn
+is determined by the user's own styles and other settings\&.
+.RE
+.TP
+\fB_complete_tag (^Xt)\fP
+This widget completes symbol tags created by the \fBetags\fP or \fBctags\fP
+programmes (note there is no connection with the completion system's tags)
+stored in a file \fBTAGS\fP, in the format used by \fBetags\fP, or \fBtags\fP, in the
+format created by \fBctags\fP\&.  It will look back up the path hierarchy for
+the first occurrence of either file; if both exist, the file \fBTAGS\fP is
+preferred\&.  You can specify the full path to a \fBTAGS\fP or \fBtags\fP file by
+setting the parameter \fB$TAGSFILE\fP or \fB$tagsfile\fP respectively\&.
+The corresponding completion tags used are \fBetags\fP and \fBvtags\fP, after
+emacs and vi respectively\&.
+.PP
+.SH "UTILITY FUNCTIONS"
+.PP
+Descriptions follow for utility functions that may be
+useful when writing completion functions\&.  If functions are installed in
+subdirectories, most of these reside in the
+\fBBase\fP subdirectory\&.  Like the example 
+functions for commands in the distribution, the utility functions
+generating matches all follow the convention of returning zero if they
+generated completions and non\-zero if no matching completions could be 
+added\&.
+.PP
+Two more features are offered by the \fB_main_complete\fP function\&.  The
+arrays \fBcompprefuncs\fP and \fBcomppostfuncs\fP may contain
+names of functions that are to be called immediately before or after
+completion has been tried\&.  A function will only be called once unless
+it explicitly reinserts itself into the array\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB_all_labels\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP [ \fIcommand\fP \fIargs\fP \&.\&.\&. ]
+This is a convenient interface to the \fB_next_label\fP function below,
+implementing the loop shown in the \fB_next_label\fP example\&.  The
+\fIcommand\fP and its arguments are called to generate the matches\&.  The
+options stored in the parameter \fIname\fP will automatically be inserted
+into the \fIargs\fP passed to the \fIcommand\fP\&.  Normally, they are put
+directly after the \fIcommand\fP, but if one of the \fIargs\fP is a single
+hyphen, they are inserted directly before that\&.  If the hyphen is the last
+argument, it will be removed from the argument list before the
+\fIcommand\fP is called\&.  This allows \fB_all_labels\fP to be used in almost all
+cases where the matches can be generated by a single call to the
+\fBcompadd\fP builtin command or by a call to one of the utility functions\&.
+.RS
+.PP
+For example:
+.PP
+.RS
+.nf
+\fBlocal expl
+\&.\&.\&.
+if _requested foo; then
+  \&.\&.\&.
+  _all_labels foo expl '\&.\&.\&.' compadd \&.\&.\&. \- $matches
+fi\fP
+.fi
+.RE
+.PP
+Will complete the strings from the \fBmatches\fP parameter, using
+\fBcompadd\fP with additional options which will take precedence over
+those generated by \fB_all_labels\fP\&.
+.RE
+.TP
+\fB_alternative\fP [ \fB\-C\fP \fIname\fP ] \fIspec\fP \&.\&.\&.
+This function is useful in simple cases where multiple tags are available\&.
+Essentially it implements a loop like the one described for the \fB_tags\fP
+function below\&.
+.RS
+.PP
+The tags to use and the action to perform if a tag is requested are
+described using the \fIspec\fPs which are of the form:
+`\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP'\&.  The \fItag\fPs are offered using
+\fB_tags\fP and if the tag is requested, the \fIaction\fP is executed with the
+given description \fIdescr\fP\&.  The \fIaction\fPs are those accepted
+by the \fB_arguments\fP function (described below), excluding the
+`\fB\->\fP\fIstate\fP' and `\fB=\fP\fI\&.\&.\&.\fP' forms\&.
+.PP
+For example, the \fIaction\fP may be a simple function call:
+.PP
+.RS
+.nf
+\fB_alternative \e 
+    'users:user:_users' \e 
+    'hosts:host:_hosts'\fP
+.fi
+.RE
+.PP
+offers usernames and hostnames as possible matches,
+generated by the \fB_users\fP and \fB_hosts\fP functions respectively\&.
+.PP
+Like \fB_arguments\fP, this functions uses \fB_all_labels\fP to execute 
+the actions, which will loop over all sets of tags\&.  Special handling is
+only required if there is an additional valid tag, for example inside a
+function called from \fB_alternative\fP\&.
+.PP
+Like \fB_tags\fP this function supports the \fB\-C\fP option to give a
+different name for the argument context field\&.
+.RE
+.TP
+\fB_arguments\fP [ \fB\-swWACRS\fP ] [ \fB\-O\fP \fIname\fP ] [ \fB\-M\fP \fImatchspec\fP ] [ \fB:\fP ] \fIspec\fP \&.\&.\&.
+This function can be used to give a complete specification for
+completion for a command whose arguments follow standard UNIX option and
+argument conventions\&.  The following forms specify individual sets of
+options and arguments; to avoid ambiguity, these may be separated from the
+options to \fB_arguments\fP itself by a single colon\&.
+.RS
+.PP
+.PD 0
+.TP
+.PD 0
+\fIn\fP\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD
+\fIn\fP\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP
+This describes the \fIn\fP'th normal argument\&.  The \fImessage\fP will be 
+printed above the matches generated and the \fIaction\fP indicates what can
+be completed in this position (see below)\&.  If there are two colons
+before the \fImessage\fP the argument is optional\&.  If the
+\fImessage\fP contains only white space, nothing will be printed above
+the matches unless the action adds an explanation string itself\&.
+.TP
+.PD 0
+\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD
+\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP
+Similar, but describes the \fInext\fP argument, whatever number that
+happens to be\&.  If all arguments are specified in this form in the
+correct order the numbers are unnecessary\&.
+.TP
+.PD 0
+\fB*:\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD 0
+\fB*::\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD
+\fB*:::\fP\fImessage\fP\fB:\fP\fIaction\fP
+This describes how arguments (usually non\-option arguments, those not
+beginning with \fB\-\fP or \fB+\fP) are to be completed when neither
+of the first two forms was provided\&.  Any number of arguments can
+be completed in this fashion\&.
+.RS
+.PP
+With two colons before the \fImessage\fP, the \fBwords\fP special array and
+the \fBCURRENT\fP special parameter are modified to refer only to the
+normal arguments when the \fIaction\fP is executed or evaluated\&.  With
+three colons before the \fImessage\fP they are modified to refer only to
+the normal arguments covered by this description\&.
+.RE
+.TP
+.PD 0
+\fIoptspec\fP
+.TP
+.PD
+\fIoptspec\fP:\fI\&.\&.\&.\fP
+This describes an option\&.  The colon indicates handling for one or more
+arguments to the option; if it is not present, the option is assumed to
+take no arguments\&.
+.RS
+.PP
+By default, options are multi\-character name, one `\fB\-\fP\fIword\fP' per
+option\&.  With \fB\-s\fP, options may be single characters, with more than
+one option per word, although words starting with two hyphens, such as
+`\fB\-\fP\fB\-prefix\fP', are still considered complete option names\&.  This is
+suitable for standard GNU options\&.
+.PP
+The combination of \fB\-s\fP with \fB\-w\fP allows single\-letter options to be
+combined in a single word even if one or more of the options take
+arguments\&.  For example, if \fB\-a\fP takes an argument, with no
+\fB\-s\fP `\fB\-ab\fP' is considered as a single (unhandled) option; with
+\fB\-s\fP \fB\-ab\fP is an option with the argument `\fBb\fP'; with both \fB\-s\fP
+and \fB\-w\fP, \fB\-ab\fP may be the option \fB\-a\fP and the option(\-b) with
+arguments still to come\&.
+.PP
+The option \fB\-W\fP takes this a stage further:  it is possible to
+complete single\-letter options even after an argument that occurs in the
+same word\&.  However, it depends on the action performed whether options
+will really be completed at this point\&.  For more control, use a
+utility function like \fB_guard\fP as part of the action\&.
+.PP
+The following forms are available for the initial \fIoptspec\fP, whether
+or not the option has arguments\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB*\fP\fIoptspec\fP
+Here \fIoptspec\fP is one of the remaining forms below\&.  This indicates
+the following \fIoptspec\fP may be repeated\&.  Otherwise if the
+corresponding option is already present on the command line to the left
+of the cursor it will not be offered again\&.
+.TP
+.PD 0
+\fB\-\fP\fIoptname\fP
+.TP
+.PD
+\fB+\fP\fIoptname\fP
+In the simplest form the \fIoptspec\fP is just the option name beginning
+with a minus or a plus sign, such as `\fB\-foo\fP'\&.  The first argument for
+the option (if any) must follow as a \fIseparate\fP word directly after the
+option\&.
+.RS
+.PP
+Either of `\fB\-+\fP\fIoptname\fP' and `\fB+\-\fP\fIoptname\fP' can be used to
+specify that \fB\-\fP\fIoptname\fP and \fB+\fP\fIoptname\fP are both valid\&.
+.PP
+In all the remaining forms, the leading `\fB\-\fP' may be replaced by or
+paired with `\fB+\fP' in this way\&.
+.RE
+.TP
+\fB\-\fP\fIoptname\fP\fB\-\fP
+The first argument of the option must come directly after the option name
+\fIin the same word\fP\&.  For example, `\fB\-foo\-:\fP\fI\&.\&.\&.\fP' specifies that
+the completed option and argument will look like `\fB\-foo\fP\fIarg\fP'\&.
+.TP
+\fB\-\fP\fIoptname\fP\fB+\fP
+The first argument may appear immediately after \fIoptname\fP in the same
+word, or may appear as a separate word after the option\&.  For example,
+`\fB\-foo+:\fP\fI\&.\&.\&.\fP' specifies that the completed option and argument
+will look like either `\fB\-foo\fP\fIarg\fP' or `\fB\-foo\fP \fIarg\fP'\&.
+.TP
+\fB\-\fP\fIoptname\fP\fB=\fP
+The argument may appear as the next word, or in same word as the option
+name provided that it is separated from it by an equals sign, for
+example `\fB\-foo=\fP\fIarg\fP' or `\fB\-foo\fP \fIarg\fP'\&.
+.TP
+\fB\-\fP\fIoptname\fP\fB=\-\fP
+The argument to the option must appear after an equals sign in the same
+word, and may not be given in the next argument\&.
+.TP
+\fIoptspec\fP\fB[\fP\fIexplanation\fP\fB]\fP
+An explanation string may be appended to any of the preceding forms of
+\fIoptspec\fP by enclosing it in brackets, as in `\fB\-q[query operation]\fP'\&.
+.RS
+.PP
+The \fBverbose\fP style is used to decide whether the explanation strings
+are displayed with the option in a completion listing\&.
+.PP
+If no bracketed explanation string is given but the \fBauto\-description\fP
+style is set and only one argument is described for this \fIoptspec\fP, the
+value of the style is displayed, with any appearance of the sequence
+`\fB%d\fP' in it replaced by the \fImessage\fP of the first \fIoptarg\fP
+that follows the \fIoptspec\fP; see below\&.
+.RE
+.RE
+.PP
+It is possible for options with a literal `+' or `\fB=\fP' to
+appear, but that character must be quoted, for example `\fB\-\e+\fP'\&.
+.PP
+Each \fIoptarg\fP following an \fIoptspec\fP must take one of the
+following forms:
+.PP
+.PD 0
+.TP
+.PD 0
+\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD
+\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP
+An argument to the option; \fImessage\fP and \fIaction\fP are treated as
+for ordinary arguments\&.  In the first form, the argument is mandatory,
+and in the second form it is optional\&.
+.RS
+.PP
+This group may be repeated for options which take multiple arguments\&.
+In other words,
+\fB:\fP\fImessage1\fP\fB:\fP\fIaction1\fP\fB:\fP\fImessage2\fP\fB:\fP\fIaction2\fP
+specifies that the option takes two arguments\&.
+.RE
+.TP
+.PD 0
+\fB:*\fP\fIpattern\fP\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD 0
+\fB:*\fP\fIpattern\fP\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP
+.TP
+.PD
+\fB:*\fP\fIpattern\fP\fB:::\fP\fImessage\fP\fB:\fP\fIaction\fP
+This describes multiple arguments\&.  Only the last \fIoptarg\fP for
+an option taking multiple arguments may be
+given in this form\&.  If the \fIpattern\fP is empty (i\&.e\&., \fB:*:\fP), all
+the remaining words on the line are to be completed as described by the
+\fIaction\fP; otherwise, all the words up to a word matching the
+\fIpattern\fP are to be completed using the \fIaction\fP\&.
+.RS
+.PP
+Multiple colons are treated as for the `\fB*:\fP\fI\&.\&.\&.\fP' forms for
+ordinary arguments:  when the \fImessage\fP is preceded by two colons,
+the \fBwords\fP special array and the \fBCURRENT\fP special parameter are
+modified during the execution or evaluation of the \fIaction\fP to refer
+only to the words after the option\&.  When preceded by three colons, they
+are modified to refer only to the words covered by this description\&.
+.RE
+.RE
+.RE
+.RE
+.PP
+Any literal colon in an \fIoptname\fP, \fImessage\fP, or \fIaction\fP
+must be preceded by a backslash, `\fB\e:\fP'\&.
+.PP
+Each of the forms above may be preceded by a list in parentheses
+of option names and argument numbers\&.  If the given option is on
+the command line, the options and arguments indicated in parentheses
+will not be offered\&.  For example, 
+`\fB(\-two \-three 1)\-one:\&.\&.\&.\fP' completes the option `\fB\-one\fP'; if this
+appears on the command line, the options \fB\-two\fP and \fB\-three\fP and the
+first ordinary argument will not be completed after it\&.
+`\fB(\-foo):\fP\fI\&.\&.\&.\fP' specifies an ordinary argument completion;
+\fB\-foo\fP will not be completed if that argument is already present\&.
+.PP
+Other items may appear in the list of excluded options to indicate
+various other items that should not be applied when the current
+specification is matched: a single star (\fB*\fP) for the rest arguments
+(i\&.e\&. a specification of the form `\fB*:\&.\&.\&.\fP'); a colon (\fB:\fP)
+for all normal (non\-option\-) arguments; and a hyphen (\fB\-\fP) for all
+options\&.  For example, if `\fB(*)\fP' appears before an option and the
+option appears on the command line, the list of remaining arguments
+(those shown in the above table beginning with `\fB*:\fP') will not be
+completed\&.
+.PP
+To aid in reuse of specifications, it is possible to precede any of the
+forms above with `\fB!\fP'; then the form will no longer be completed,
+although if the option or argument appears on the command line they will
+be skipped as normal\&.  The main use for this is when the arguments are
+given by an array, and \fB_arguments\fP is called repeatedly for more
+specific contexts: on the first call `\fB_arguments $global_options\fP' is
+used, and on subsequent calls `\fB_arguments !$^global_options\fP'\&.
+.PP
+In each of the forms above the \fIaction\fP determines how
+completions should be generated\&.  Except for the `\fB\->\fP\fIstring\fP'
+form below, the \fIaction\fP will be executed by calling the
+\fB_all_labels\fP function to process all tag labels\&.  No special handling
+of tags is needed unless a function call introduces a new one\&.
+.PP
+The forms for \fIaction\fP are as follows\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB \fP (single unquoted space)
+This is useful where an argument is required but it is not possible or
+desirable to generate matches for it\&.  The
+\fImessage\fP will be displayed but no completions listed\&.  Note
+that even in this case the colon at the end of the \fImessage\fP is
+needed; it may only be omitted when neither a \fImessage\fP
+nor an \fIaction\fP is given\&.
+.TP
+\fB(\fP\fIitem1\fP \fIitem2\fP \fI\&.\&.\&.\fP\fB)\fP
+One of a list of possible matches, for example:
+.RS
+.PP
+.RS
+.nf
+\fB\fB:foo:(foo bar baz\fP\fB)\fP\fP
+.fi
+.RE
+.RE
+.TP
+\fB((\fIitem1\fP\e:\fIdesc1\fP \fI\&.\&.\&.\fP))\fP
+Similar to the above, but with descriptions for each possible match\&.
+Note the backslash before the colon\&.  For example,
+.RS
+.PP
+.RS
+.nf
+\fB\fB:foo:((a\e:bar b\e:baz\fP\fB))\fP\fP
+.fi
+.RE
+.PP
+The matches will be listed together with their descriptions if the
+\fBdescription\fP style is set with the \fBvalues\fP tag in the context\&.
+.RE
+.TP
+\fB\->\fP\fIstring\fP
+In this form, \fB_arguments\fP processes the arguments and options and then
+returns control to the calling function with parameters set to indicate the
+state of processing; the calling function then makes its own arrangements
+for generating completions\&.  For example, functions that implement a state
+machine can use this type of action\&.
+.RS
+.PP
+Where \fB_arguments\fP encounters a `\fB\->\fP\fIstring\fP', it will strip
+all leading and trailing whitespace from \fIstring\fP and set the array
+\fBstate\fP to the set of all \fIstrings\fPs for which an action is to be
+performed\&.
+.PP
+By default and in common with all other well behaved completion
+functions, _arguments returns zero if it was able to add matches and
+non\-zero otherwise\&. However, if the \fB\-R\fP option is given,
+\fB_arguments\fP will instead return a status of 300 to indicate that
+\fB$state\fP is to be handled\&.
+.PP
+In addition to \fB$state\fP, \fB_arguments\fP also sets the global
+parameters `\fBcontext\fP', `\fBline\fP' and `\fBopt_args\fP' as described
+below, and does not reset any changes made to the special parameters
+such as \fBPREFIX\fP and \fBwords\fP\&.  This gives the calling function the
+choice of resetting these parameters or propagating changes in them\&.
+.PP
+A function calling \fB_arguments\fP with at least
+one action containing a `\fB\->\fP\fIstring\fP' therefore must declare
+appropriate local parameters:
+.PP
+.RS
+.nf
+\fBlocal context state line
+typeset \-A opt_args\fP
+.fi
+.RE
+.PP
+to avoid \fB_arguments\fP from altering the global environment\&.
+.RE
+.TP
+\fB{\fP\fIeval\-string\fP\fB}\fP
+A string in braces is evaluated as shell code to generate matches\&.  If the
+\fIeval\-string\fP itself does not begin with an opening parenthesis or
+brace it is split into separate words before execution\&.
+.TP
+\fB= \fP\fIaction\fP
+If the \fIaction\fP starts with `\fB= \fP' (an equals sign followed by a
+space), \fB_arguments\fP will insert the contents of the \fIargument\fP
+field of the current context as the new first element in the \fBwords\fP 
+special array and increment the value of the \fBCURRENT\fP special
+parameter\&.  This has the effect of inserting a dummy word onto the
+completion command line while not changing the point at which completion is
+taking place\&.
+.RS
+.PP
+This is most useful with one of the specifiers that restrict the words on
+the command line on which the \fIaction\fP is to operate (the two\- and
+three\-colon forms above)\&.  One particular use is when an \fIaction\fP itself
+causes \fB_arguments\fP on a restricted range; it is necessary to use this
+trick to insert an appropriate command name into the range for the second
+call to \fB_arguments\fP to be able to parse the line\&.
+.RE
+.TP
+.PD 0
+ \fIword\&.\&.\&.\fP
+.TP
+.PD
+\fIword\&.\&.\&.\fP
+This covers all forms other than those above\&.  If the \fIaction\fP
+starts with a space, the remaining list of words will be invoked unchanged\&.
+.RS
+.PP
+Otherwise it will be invoked with some extra strings placed after the
+first word; these are to be passed down as options to the \fBcompadd\fP
+builtin\&.  They ensure that the state specified by \fB_arguments\fP, in
+particular the descriptions of options and arguments, is correctly passed
+to the completion command\&.  These additional arguments
+are taken from the array parameter `\fBexpl\fP'; this will be set up
+before executing the \fIaction\fP and hence may be referred to inside it,
+typically in an expansion of the form `\fB$expl[@]\fP' which preserves empty
+elements of the array\&.
+.RE
+.RE
+.PP
+During the performance of the action the array `\fBline\fP'
+will be set to the command name and normal arguments from the command
+line, i\&.e\&. the words from the command line excluding all options
+and their arguments\&.  Options are stored in the associative array
+`\fBopt_args\fP' with option names as keys and their arguments as
+the values\&.  For options that have more than one argument these are
+given as one string, separated by colons\&.  All colons in the original
+arguments are preceded with backslashes\&.
+.PP
+The parameter `\fBcontext\fP' is set when returning to the calling function
+to perform an action of the form `\fB\->\fP\fIstring\fP'\&.  It is set to an
+array of elements corresponding to the elements of \fB$state\fP\&.  Each
+element is a suitable name for the argument field of the context: either a
+string of the form `\fBoption\fP\fI\-opt\fP\fB\-\fP\fIn\fP' for the \fIn\fP'th
+argument of the option \fI\-opt\fP, or a string of the form
+`\fBargument\-\fP\fIn\fP' for the \fIn\fP'th argument\&.  For `rest' arguments,
+that is those in the list at the end not handled by position, \fIn\fP is the
+string `\fBrest\fP'\&.  For example, when completing the argument of the \fB\-o\fP
+option, the name is `\fBoption\-o\-1\fP', while for the second normal
+(non\-option\-) argument it is `\fBargument\-2\fP'\&.
+.PP
+Furthermore, during the evaluation of the \fIaction\fP the context name in
+the \fBcurcontext\fP parameter is altered to append the same string that is
+stored in the \fBcontext\fP parameter\&.
+.PP
+It is possible to specify multiple sets of options and
+arguments with the sets separated by single hyphens\&.  The specifications
+before the first hyphen (if any) are shared by all the remaining sets\&.
+The first word in every other set provides a name for the
+set which may appear in exclusion lists in specifications,
+either alone or before one of the possible values described above\&.
+In the second case a `\fB\-\fP' should appear between this name and the
+remainder\&.
+.PP
+For example:
+.PP
+.RS
+.nf
+\fB_arguments \e 
+    \-a \e 
+  \- set1 \e 
+    \-c \e 
+  \- set2 \e 
+    \-d \e 
+    ':arg:(x2 y2)'\fP
+.fi
+.RE
+.PP
+This defines two sets\&.  When the command line contains the option
+`\fB\-c\fP', the `\fB\-d\fP' option and the argument will not be considered
+possible completions\&.  When it contains `\fB\-d\fP' or an argument, the
+option `\fB\-c\fP' will not be considered\&.  However, after `\fB\-a\fP'
+both sets will still be considered valid\&.
+.PP
+If the name given for one of the mutually exclusive sets is of the form
+`\fB(\fP\fIname\fP\fB)\fP' then only one value from each set will ever
+be completed; more formally, all specifications are mutually
+exclusive to all other specifications in the same set\&.  This is
+useful for defining multiple sets of options which are mutually
+exclusive and in which the options are aliases for each other\&.  For
+example:
+.PP
+.RS
+.nf
+\fB_arguments \e 
+    \-a \-b \e 
+  \- '(compress)' \e 
+    {\-c,\-\-compress}'[compress]' \e 
+  \- '(uncompress)' \e 
+    {\-d,\-\-decompress}'[decompress]'\fP
+.fi
+.RE
+.PP
+As the completion code has to parse the command line separately for each
+set this form of argument is slow and should only be used when necessary\&.
+A useful alternative is often an option specification with rest\-arguments
+(as in `\fB\-foo:*:\&.\&.\&.\fP'); here the option \fB\-foo\fP swallows up all
+remaining arguments as described by the \fIoptarg\fP definitions\&.
+.PP
+The options \fB\-S\fP and \fB\-A\fP are available to simplify the specifications
+for commands with standard option parsing\&.  With \fB\-S\fP, no option will be
+completed after a `\fB\-\fP\fB\-\fP' appearing on its own on the line; this
+argument will otherwise be ignored; hence in the line
+.PP
+.RS
+.nf
+\fBfoobar \-a \-\- \-b\fP
+.fi
+.RE
+.PP
+the `\fB\-a\fP' is considered an option but the `\fB\-b\fP' is considered an
+argument, while the `\fB\-\fP\fB\-\fP' is considered to be neither\&.
+.PP
+With \fB\-A\fP, no options will be completed after the first non\-option
+argument on the line\&.  The \fB\-A\fP must be followed by a pattern matching
+all strings which are not to be taken as arguments\&.  For example, to make
+\fB_arguments\fP stop completing options after the first normal argument, but
+ignoring all strings starting with a hyphen even if they are not described
+by one of the \fIoptspec\fPs, the form is `\fB\-A "\-*"\fP'\&.
+.PP
+The option `\fB\-O\fP \fIname\fP' specifies the name of an array whose elements
+will be passed as arguments to functions called to execute \fIactions\fP\&.
+For example, this can be used to pass the same set of options for the
+\fBcompadd\fP builtin to all \fIaction\fPs\&.
+.PP
+The option `\fB\-M\fP \fIspec\fP' sets a match specification to use to
+completion option names and values\&.  It must appear before the first
+argument specification\&.  The default is `\fBr:|[_\-]=* r:|=*\fP': this allows
+partial word completion after `\fB_\fP' and `\fB\-\fP', for example `\-f\-b'
+can be completed to `\fB\-foo\-bar\fP'\&.
+.PP
+The option \fB\-C\fP tells \fB_arguments\fP to modify
+the \fBcurcontext\fP parameter for an action of the form
+`\fB\->\fP\fIstate\fP'\&.  This is the standard parameter used to keep track of
+the current context\&.  Here it (and not the \fBcontext\fP array) should be
+made local to the calling function
+to avoid passing back the modified value and should be initialised to the
+current value at the start of the function:
+.PP
+.RS
+.nf
+\fBlocal curcontext="$curcontext"\fP
+.fi
+.RE
+.PP
+This is useful where it is not possible for multiple states to be valid
+together\&.
+.PP
+The option `\fB\-\-\fP' allows \fB_arguments\fP to work out the names of long
+options that support the `\fB\-\fP\fB\-help\fP' option which is standard in many
+GNU commands\&.  The command word is called with the argument
+`\fB\-\fP\fB\-help\fP' and the output examined for option names\&.  Clearly, it can
+be dangerous to pass this to commands which may not support this option as
+the behaviour of the command is unspecified\&.
+.PP
+In addition to options, `\fB_arguments \-\fP\fB\-\fP' will try to deduce the
+types of arguments available for options when the form
+`\fB\-\fP\fB\-\fP\fIopt\fP=\fIval\fP' is valid\&.  It is also possible to provide
+hints by examining the help text of the command and adding specifiers of
+the form `\fIpattern\fP\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP'; note that normal
+\fB_arguments\fP specifiers are not used\&.  The \fIpattern\fP is matched
+against the help text for an option, and if it matches the \fImessage\fP and
+\fIaction\fP are used as for other argument specifiers\&.  For example:
+.PP
+.RS
+.nf
+\fB_arguments \-\- '*\e*:toggle:(yes no)' \e 
+              '*=FILE*:file:_files' \e 
+              '*=DIR*:directory:_files \-/' \e 
+              '*=PATH*:directory:_files \-/'\fP
+.fi
+.RE
+.PP
+Here, `\fByes\fP' and `\fBno\fP' will be completed as the argument of
+options whose description ends in a star; file names will be completed for
+options that contain the substring `\fB=FILE\fP' in the description; and
+directories will be completed for options whose description contains
+`\fB=DIR\fP' or `\fB=PATH\fP'\&.  The last three are in fact the default and so
+need not be given explicitly, although it is possible to override the use
+of these patterns\&.  A typical help text which uses this feature is:
+.PP
+.RS
+.nf
+\fB  \-C, \-\-directory=DIR          change to directory DIR\fP
+.fi
+.RE
+.PP
+so that the above specifications will cause directories to be completed
+after `\fB\-\-directory\fP', though not after `\fB\-C\fP'\&.
+.PP
+Note also that \fB_arguments\fP tries to find out automatically if the
+argument for an option is optional\&.  This can be specified explicitly by
+doubling the colon before the \fImessage\fP\&.
+.PP
+If the \fIpattern\fP ends in `\fB(\-)\fP', this will removed from the
+pattern and the \fIaction\fP will be used only directly after the
+`\fB=\fP', not in the next word\&.  This is the behaviour of a normal
+specification defined with the form `\fB=\-\fP'\&.
+.PP
+The `\fB_arguments \-\fP\fB\-\fP' can be followed by the option `\fB\-i\fP
+\fIpatterns\fP' to give patterns for options which are not to be
+completed\&.  The patterns can be given as the name of an array parameter
+or as a literal list in parentheses\&.  For example,
+.PP
+.RS
+.nf
+\fB_arguments \-\- \-i \e 
+    "(\-\fB\-(en|dis)able\-FEATURE*)"\fP\fP
+.fi
+.RE
+.PP
+will cause completion to ignore the options
+`\fB\-\fP\fB\-enable\-FEATURE\fP' and `\fB\-\fP\fB\-disable\-FEATURE\fP' (this example is
+useful with GNU \fBconfigure\fP)\&.
+.PP
+The `\fB_arguments \-\fP\fB\-\fP' form can also be followed by the option `\fB\-s\fP
+\fIpair\fP' to describe option aliases\&.  Each \fIpair\fP consists of a
+pattern and a replacement\&.  For example, some \fBconfigure\fP\-scripts
+describe options only as `\fB\-\fP\fB\-enable\-foo\fP', but also accept
+`\fB\-\fP\fB\-disable\-foo\fP'\&.  To allow completion of the second form:
+.PP
+.RS
+.nf
+\fB_arguments \-\- \-s "(#\-\fB\-enable\- \-\fP\fB\-disable\-)"\fP\fP
+.fi
+.RE
+.PP
+Here is a more general example of the use of \fB_arguments\fP:
+.PP
+.RS
+.nf
+\fB_arguments '\-l+:left border:' \e 
+           '\-format:paper size:(letter A4)' \e 
+           '*\-copy:output file:_files::resolution:(300 600)' \e 
+           ':postscript file:_files \-g \e*\&.\e(ps\e|eps\e)' \e 
+           '*:page number:'\fP
+.fi
+.RE
+.PP
+This describes three options: `\fB\-l\fP', `\fB\-format\fP', and
+`\fB\-copy\fP'\&.  The first takes one argument described as `\fIleft
+border\fP' for which no completion will be offered because of the empty
+action\&.  Its argument may come directly after the `\fB\-l\fP' or it may be 
+given as the next word on the line\&.
+.PP
+The `\fB\-format\fP' option takes one
+argument in the next word, described as `\fIpaper size\fP' for which
+only the strings `\fBletter\fP' and `\fBA4\fP' will be completed\&.
+.PP
+The `\fB\-copy\fP' option may appear more than once on the command line and
+takes two arguments\&.  The first is mandatory and will be completed as a
+filename\&.  The second is optional (because of the second colon before
+the description `\fIresolution\fP') and will be completed from the strings
+`\fB300\fP' and `\fB600\fP'\&.
+.PP
+The last two descriptions say what should be completed as
+arguments\&.  The first describes the first argument as a
+`\fIpostscript file\fP' and makes files ending in `\fBps\fP' or `\fBeps\fP' 
+be completed\&.  The last description gives all other arguments the
+description `\fIpage numbers\fP' but does not offer completions\&.
+.RE
+.TP
+\fB_cache_invalid\fP \fIcache_identifier\fP
+This function returns status zero if the completions cache corresponding to
+the given cache identifier needs rebuilding\&.  It determines this by
+looking up the \fBcache\-policy\fP style for the current context\&.
+This should provide a function name which is run with the full path to the
+relevant cache file as the only argument\&.
+.RS
+.PP
+Example:
+.PP
+.RS
+.nf
+\fB_example_caching_policy () {
+    # rebuild if cache is more than a week old
+    oldp=( "$1"(Nmw+1) )
+    (( $#oldp ))
+}\fP
+.fi
+.RE
+.RE
+.TP
+\fB_call_function\fP \fIreturn\fP \fIname\fP [ \fIargs\fP \&.\&.\&. ]
+If a function \fIname\fP exists, it is called with the arguments
+\fIargs\fP\&.  The \fIreturn\fP argument gives the name of a parameter in which
+the return status from the function \fIname\fP; if \fIreturn\fP is empty or a
+single hyphen it is ignored\&.
+.RS
+.PP
+The return value of \fB_call_function\fP itself is zero if the function
+\fIname\fP exists and was called and non\-zero otherwise\&.
+.RE
+.TP
+\fB_call_program\fP \fItag\fP \fIstring\fP \&.\&.\&.
+This function provides a mechanism for the user to override the use of an
+external command\&.  It looks up the \fBcommand\fP style with the supplied
+\fItag\fP\&.  If the style is set, its value is used as the command to
+execute\&.  The \fIstring\fPs from the call to \fB_call_program\fP, or from the
+style if set, are concatenated with spaces between them and the resulting
+string is evaluated\&.  The return value is the return value of the command
+called\&.
+.TP
+\fB_combination\fP [ \fB\-s\fP \fIpattern\fP ] \fItag\fP \fIstyle\fP \fIspec\fP \&.\&.\&. \fIfield\fP \fIopts\fP \&.\&.\&.
+This function is used to complete combinations of values,  for example
+pairs of hostnames and usernames\&.  The \fIstyle\fP argument gives the style
+which defines the pairs; it is looked up in a context with the \fItag\fP
+specified\&.
+.RS
+.PP
+The style name consists of field names separated by hyphens, for example
+`\fBusers\-hosts\-ports\fP'\&.  For each field for a value is already known, a
+\fIspec\fP of the form `\fIfield\fP\fB=\fP\fIpattern\fP' is given\&.  For example,
+if the command line so far specifies a user `\fBpws\fP', the argument
+`\fBusers=pws\fP' should appear\&.
+.PP
+The next argument with no equals sign is taken as the name of the field
+for which completions should be generated (presumably not one of the
+\fIfield\fPs for which the value is known)\&.
+.PP
+The matches generated will be taken from the value of the style\&.  These
+should contain the possible values for the combinations in the appropriate
+order (users, hosts, ports in the example above)\&.  The different fields
+the values for the different fields are separated by colons\&.  This
+can be altered with the option \fB\-s\fP to \fB_combination\fP which specifies a
+pattern\&.  Typically this is a character class, as for example
+`\fB\-s "[:@]"\fP' in the case of the \fBusers\-hosts\fP style\&.    Each
+`\fIfield\fP\fB=\fP\fIpattern\fP' specification restricts the
+completions which apply to elements of the style with appropriately
+matching fields\&.
+.PP
+If no style with the given name is defined for the given tag,
+or if none of the strings in style's value match, but a
+function name of the required field preceded by an
+underscore is defined, that function will be called to generate the
+matches\&.  For example, if there is no `\fBusers\-hosts\-ports\fP' or no
+matching hostname when a host is required, the function `\fB_hosts\fP' will
+automatically be called\&.
+.PP
+If the same name is used for more than one field, in both the
+`\fIfield\fP\fB=\fP\fIpattern\fP' and the argument that gives the name of the
+field to be completed, the number of the field (starting with one) may
+be given after the fieldname, separated from it by a colon\&.
+.PP
+All arguments after the required field name are passed to
+\fBcompadd\fP when generating matches from the style value, or to 
+the functions for the fields if they are called\&.
+.RE
+.TP
+\fB_describe\fP [ \fB\-oO\fP | \fB\-t\fP \fItag\fP ] \fIdescr\fP \fIname1\fP [ \fIname2\fP ] \fIopts\fP \&.\&.\&. \fB\-\fP\fB\-\fP \&.\&.\&.
+This function associates completions with descriptions\&.
+Multiple groups separated by \fB\-\fP\fB\-\fP can be supplied, potentially with
+different completion options \fIopts\fP\&.
+.RS
+.PP
+The \fIdescr\fP is taken as a string to display above the matches if the
+\fBformat\fP style for the \fBdescriptions\fP tag is set\&.  This is followed by
+one or two names of arrays followed by options to pass to \fBcompadd\fP\&.  The
+first array contains the possible completions with their descriptions in
+the form `\fIcompletion\fP\fB:\fP\fIdescription\fP'\&.  If a second array is
+given, it should have the same number of elements as the first; in this
+case the corresponding elements are added as possible completions instead
+of the \fIcompletion\fP strings from the first array\&.  The completion list
+will retain the descriptions from the first array\&.  Finally, a set of
+completion options can appear\&.
+.PP
+If the option `\fB\-o\fP' appears before the first argument, the matches added
+will be treated as names of command options (N\&.B\&. not shell options),
+typically following a `\fB\-\fP', `\fB\-\fP\fB\-\fP' or `\fB+\fP' on the command
+line\&.  In this case \fB_describe\fP uses the \fBprefix\-hidden\fP,
+\fBprefix\-needed\fP and \fBverbose\fP styles to find out if the strings should
+be added as completions and if the descriptions should be shown\&.  Without
+the `\fB\-o\fP' option, only the \fBverbose\fP style is used to decide how
+descriptions are shown\&.  If `\fB\-O\fP' is used instead of `\fB\-O\fP', command
+options are completed as above but \fB_describe\fP will not handle the
+\fBprefix\-needed\fP style\&.
+.PP
+With the \fB\-t\fP option a \fItag\fP can be specified\&.  The default is
+`\fBvalues\fP' or, if the \fB\-o\fP option is given, `\fBoptions\fP'\&.
+.PP
+If selected by the \fBlist\-grouped\fP style, strings with the same
+description will appear together in the list\&.
+.PP
+\fB_describe\fP uses the \fB_all_labels\fP function to generate the matches, so
+it does not need to appear inside a loop over tag labels\&.
+.RE
+.TP
+\fB_description\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP [ \fIspec\fP \&.\&.\&. ]
+This function is not to be confused with the previous one; it is used as
+a helper function for creating options to \fBcompadd\fP\&.  It is buried
+inside many of the higher level completion functions and so often does
+not need to be called directly\&.
+.RS
+.PP
+The styles listed below are tested in the current context using the
+given \fItag\fP\&.  The resulting options for \fBcompadd\fP are put into the
+array named \fIname\fP (this is traditionally `\fBexpl\fP', but this
+convention is not enforced)\&.  The description for the corresponding set
+of matches is passed to the function in \fIdescr\fP\&.
+.PP
+The styles tested are: \fBformat\fP, \fBhidden\fP, \fBmatcher\fP,
+\fBignored\-patterns\fP and \fBgroup\-name\fP\&.  The \fBformat\fP style is first
+tested for the given \fItag\fP and then for the \fBdescriptions\fP tag if
+no value was found, while the remainder are only tested for the tag
+given as the first argument\&.  The function also calls \fB_setup\fP
+which tests some more styles\&.
+.PP
+The string returned by the \fBformat\fP style (if any) will be modified so
+that the sequence `\fB%d\fP' is replaced by the \fIdescr\fP given as the third
+argument without any leading or trailing white space\&.  If, after
+removing the white space, the \fIdescr\fP is the empty string, the format
+style will not be used and the options put into the \fIname\fP array will
+not contain an explanation string to be displayed above the matches\&.
+.PP
+If \fB_description\fP is called with more than three arguments,
+the additional \fIspec\fPs should be of the form `\fIchar\fP\fB:\fP\fIstr\fP'\&.
+These supply escape sequence replacements for the \fBformat\fP style:
+every appearance of `\fB%\fP\fIchar\fP' will be
+replaced by \fIstring\fP\&.
+.PP
+If the \fB\-x\fP option is given, the description will be passed to
+\fBcompadd\fP using the \fB\-x\fP option instead of the default \fB\-X\fP\&.  This
+means that the description will be displayed even if there are no
+corresponding matches\&.
+.PP
+The options placed in the array \fIname\fP take account of the
+\fBgroup\-name\fP style, so matches are placed in a separate group where
+necessary\&.  The group normally has its elements sorted (by passing the
+option \fB\-J\fP to \fBcompadd\fP), but if an option starting with `\fB\-V\fP',
+`\fB\-J\fP', `\fB\-1\fP', or `\fB\-2\fP' is passed to \fB_description\fP, that
+option will be included in the array\&.  Hence it is possible for the
+completion group to be unsorted by giving the option `\fB\-V\fP',
+`\fB\-1V\fP', or `\fB\-2V\fP'\&.
+.PP
+In most cases, the function will be used like this:
+.PP
+.RS
+.nf
+\fBlocal expl
+_description files expl file
+compadd "$expl[@]" \- "$files[@]"\fP
+.fi
+.RE
+.PP
+Note the use of the parameter \fBexpl\fP, the hyphen, and the list of
+matches\&.  Almost all calls to \fBcompadd\fP within the completion system use
+a similar format; this ensures that user\-specified styles are correctly
+passed down to the builtins which implement the internals of completion\&.
+.RE
+.TP
+\fB_dispatch\fP \fIcontext string \&.\&.\&.\fP
+This sets the current context to \fIcontext\fP and looks for completion
+functions to handle this context by hunting through the list of command
+names or special contexts (as described above for \fBcompdef\fP)
+given as \fIstring \&.\&.\&.\fP\&.  The first completion function to be defined
+for one of the contexts in the list is used to generate matches\&.
+Typically, the last \fIstring\fP is \fB\-default\-\fP to cause the function
+for default completion to be used as a fallback\&.
+.RS
+.PP
+The function sets the parameter
+\fB$service\fP to the \fIstring\fP being tried, and sets
+the \fIcontext/command\fP field (the fourth) of the \fB$curcontext\fP
+parameter to the \fIcontext\fP given as the first argument\&.
+.RE
+.TP
+\fB_files\fP
+The function \fB_files\fP calls \fB_path_files\fP with all the arguments it
+was passed except for \fB\-g\fP and \fB\-/\fP\&.  The use of these two options
+depends on the setting of the  \fBfile\-patterns\fP style\&.
+.RS
+.PP
+This function accepts the full set of options allowed by
+\fB_path_files\fP, described below\&.
+.RE
+.TP
+\fB_gnu_generic\fP
+This function is a simple wrapper around the \fB_arguments\fP function
+described above\&.  It can be used to determine automatically the long
+options understood by commands that produce a list when passed the
+option `\fB\-\fP\fB\-help\fP'\&.  It is intended to be used as a top\-level
+completion function in its own right\&.  For example, to enable option
+completion for the commands \fBfoo\fP and \fBbar\fP, use
+.RS
+.PP
+.RS
+.nf
+\fBcompdef _gnu_generic foo bar\fP
+.fi
+.RE
+.PP
+after the call to \fBcompinit\fP\&.
+.PP
+The completion system as supplied is conservative in its use of this
+function, since it is important to be sure the command understands the
+option `\fB\-\fP'\fB\-help\fP'\&.
+.RE
+.TP
+\fB_guard\fP [ \fIoptions\fP ] \fIpattern descr\fP
+This function is intended to be used in the \fIaction\fP for
+the specifications passed to \fB_arguments\fP and similar functions\&.  It
+returns immediately with a non\-zero return value if
+the string to be completed does not match the \fIpattern\fP\&.  If the
+pattern matches, the \fIdescr\fP is displayed; the function then returns
+zero if the word to complete is not empty, non\-zero otherwise\&.
+.RS
+.PP
+The \fIpattern\fP may be preceded by any of the options understood by
+\fBcompadd\fP that are passed down from \fB_description\fP, namely \fB\-M\fP,
+\fB\-J\fP, \fB\-V\fP, \fB\-1\fP, \fB\-2\fP, \fB\-n\fP, \fB\-F\fP and \fB\-X\fP\&.  All of these
+options will be ignored\&.  This fits in conveniently with the
+argument\-passing conventions of actions for \fB_arguments\fP\&.
+.PP
+As an example, consider a command taking the options \fB\-n\fP and
+\fB\-none\fP, where \fB\-n\fP must be followed by a numeric value in the
+same word\&.  By using:
+.PP
+.RS
+.nf
+\fB_arguments '\-n\-: :_guard "[0\-9]#" "numeric value"' '\-none'\fP
+.fi
+.RE
+.PP
+\fB_arguments\fP can be made to both display the message `\fBnumeric
+value\fP' and complete options after `\fB\-n<TAB>\fP'\&.  If the `\fB\-n\fP' is
+already followed by one or more digits (the pattern passed to
+\fB_guard\fP) only the message will be displayed; if the `\fB\-n\fP' is
+followed by another character, only options are completed\&.
+.RE
+.TP
+.PD 0
+\fB_message\fP [ \fB\-r12\fP ] [ \fB\-VJ\fP \fIgroup\fP ] \fIdescr\fP
+.TP
+.PD
+\fB_message \-e\fP [ \fItag\fP ] \fIdescr\fP
+The \fIdescr\fP is used in the same way as the third
+argument to the \fB_description\fP function, except that the resulting
+string will always be shown whether or not matches were
+generated\&.  This is useful for displaying a help message in places where
+no completions can be generated\&.
+.RS
+.PP
+The \fBformat\fP style is examined with the \fBmessages\fP tag to find a
+message; the usual tag, \fBdescriptions\fP, is used only if the style is
+not set with the former\&.
+.PP
+If the \fB\-r\fP option is given, no style is used; the \fIdescr\fP is
+taken literally as the string to display\&.  This is most useful
+when the \fIdescr\fP comes from a pre\-processed argument list
+which already contains an expanded description\&.
+.PP
+The \fB\-12VJ\fP options and the \fIgroup\fP are passed to \fBcompadd\fP and
+hence determine the group the message string is added to\&.
+.PP
+The second form gives a description for completions with the tag
+\fItag\fP to be shown even if there are no matches for that tag\&.  The tag
+can be omitted and if so the tag is taken from the parameter
+\fB$curtag\fP; this is maintained by the completion system and so is
+usually correct\&.
+.RE
+.TP
+\fB_multi_parts\fP \fIsep\fP \fIarray\fP
+The argument \fIsep\fP is a separator character\&.
+The \fIarray\fP may be either the
+name of an array parameter or a literal array in the form
+`\fB(foo bar\fP\fB)\fP', a parenthesised list of words separated
+by whitespace\&.  The possible completions are the
+strings from the array\&.  However, each chunk delimited by \fIsep\fP will be
+completed separately\&.  For example, the \fB_tar\fP function uses
+`\fB_multi_parts\fP \fB/\fP \fIpatharray\fP' to complete partial file paths
+from the given array of complete file paths\&.
+.RS
+.PP
+The \fB\-i\fP option causes \fB_multi_parts\fP to insert a unique match even
+if that requires multiple separators to be inserted\&.  This is not usually
+the expected behaviour with filenames, but certain other types of
+completion, for example those with a fixed set of possibilities, may be
+more suited to this form\&.
+.PP
+Like other utility functions, this function accepts the `\fB\-V\fP',
+`\fB\-J\fP', `\fB\-1\fP', `\fB\-2\fP', `\fB\-n\fP', `\fB\-f\fP', `\fB\-X\fP', `\fB\-M\fP',
+`\fB\-P\fP', `\fB\-S\fP', `\fB\-r\fP', `\fB\-R\fP', and `\fB\-q\fP' options and passes
+them to the \fBcompadd\fP builtin\&.
+.RE
+.TP
+\fB_next_label\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP [ \fIoptions\fP \&.\&.\&. ]
+This function is used to implement the loop over different tag
+labels for a particular tag as described above for the \fBtag\-order\fP
+style\&.  On each call it checks to see if there are any more tag labels; if
+there is it returns status zero, otherwise non\-zero\&.
+As this function requires a current tag to be set, it must always follow
+a call to \fB_tags\fP or \fB_requested\fP\&.
+.RS
+.PP
+The \fB\-x12VJ\fP options and the first three arguments are passed to the
+\fB_description\fP function\&.  Where appropriate the \fItag\fP will be
+replaced by a tag label in this call\&.  Any description given in
+the \fBtag\-order\fP style is preferred to the \fIdescr\fP passed to
+\fB_next_label\fP\&.
+.PP
+The \fIoptions\fP given after the \fIdescr\fP
+are set in the parameter given by \fIname\fP, and hence are to be passed
+to \fBcompadd\fP or whatever function is called to add the matches\&.
+.PP
+Here is a typical use of this function for the tag \fBfoo\fP\&.  The call to
+\fB_requested\fP determines if tag \fBfoo\fP is required at all; the loop
+over \fB_next_label\fP handles any labels defined for the tag in the
+\fBtag\-order\fP style\&.
+.PP
+.RS
+.nf
+\fBlocal expl ret=1
+\&.\&.\&.
+if _requested foo; then
+  \&.\&.\&.
+  while _next_label foo expl '\&.\&.\&.'; do
+    compadd "$expl[@]" \&.\&.\&. && ret=0
+  done
+  \&.\&.\&.
+fi
+return ret\fP
+.fi
+.RE
+.RE
+.TP
+\fB_normal\fP
+This is the standard function called to handle completion outside
+any special \fI\-context\-\fP\&.  It is called both to complete the command
+word and also the arguments for a command\&.  In the second case,
+\fB_normal\fP looks for a special completion for that command, and if
+there is none it uses the completion for the \fB\-default\-\fP context\&.
+.RS
+.PP
+A second use is to reexamine the command line specified by the \fB$words\fP
+array and the \fB$CURRENT\fP parameter after those have been modified\&.
+For example, the function \fB_precommand\fP, which
+completes after pre\-command specifiers such as \fBnohup\fP, removes the
+first word from the \fBwords\fP array, decrements the \fBCURRENT\fP parameter,
+then calls \fB_normal\fP again\&.  The effect is that `\fBnohup\fP \fIcmd \&.\&.\&.\fP'
+is treated in the same way as `\fIcmd \&.\&.\&.\fP'\&.
+.PP
+If the command name matches one of the patterns given by one of the
+options \fB\-p\fP or \fB\-P\fP to \fBcompdef\fP, the corresponding completion
+function is called and then the parameter \fB_compskip\fP is
+checked\&.  If it is set completion is terminated at that point even if
+no matches have been found\&.  This is the same effect as in the
+\fB\-first\-\fP context\&.
+.RE
+.TP
+\fB_options\fP
+This can be used to complete the names of shell options\&.  It provides a
+matcher specification that ignores a leading `\fBno\fP', ignores
+underscores and allows upper\-case letters to
+match their lower\-case counterparts (for example, `\fBglob\fP',
+`\fBnoglob\fP', `\fBNO_GLOB\fP' are all completed)\&.  Any arguments
+are propagated to the \fBcompadd\fP builtin\&.
+.TP
+\fB_options_set\fP and \fB_options_unset\fP
+These functions complete only set or unset options, with the same
+matching specification used in the \fB_options\fP function\&.
+.RS
+.PP
+Note that you need to uncomment a few lines in the \fB_main_complete\fP
+function for these functions to work properly\&.  The lines in question
+are used to store the option settings in effect before the completion
+widget locally sets the options it needs\&.  Hence these functions are not
+generally used by the completion system\&.
+.RE
+.TP
+\fB_parameters\fP
+This is used to complete the names of shell parameters\&.
+.RS
+.PP
+The option `\fB\-g \fIpattern\fP\fP' limits the completion to parameters
+whose type matches the \fIpattern\fP\&.  The type of a parameter is that
+shown by `\fBprint ${(t)\fP\fIparam\fP\fB}\fP', hence judicious use of
+`\fB*\fP' in \fIpattern\fP is probably necessary\&.
+.PP
+All other arguments are passed to the \fBcompadd\fP builtin\&.
+.RE
+.TP
+\fB_path_files\fP
+This function is used throughout the completion system
+to complete filenames\&.  It allows completion of partial paths\&.  For
+example, the string `\fB/u/i/s/sig\fP' may be completed to
+`\fB/usr/include/sys/signal\&.h\fP'\&.
+.RS
+.PP
+The options accepted by both \fB_path_files\fP and \fB_files\fP are:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-f\fP
+Complete all filenames\&.  This is the default\&.
+.TP
+\fB\-/\fP
+Specifies that only directories should be completed\&.
+.TP
+\fB\-g\fP \fIpattern\fP
+Specifies that only files matching the \fIpattern\fP should be completed\&.
+.TP
+\fB\-W\fP \fIpaths\fP
+Specifies path prefixes that are to be prepended to the string from the
+command line to generate the filenames but that should not be inserted
+as completions nor shown in completion listings\&.  Here, \fIpaths\fP may be
+the name of an array parameter, a literal list of paths enclosed in
+parentheses or an absolute pathname\&.
+.TP
+\fB\-F\fP \fIignored\-files\fP
+This behaves as for the corresponding option to the \fBcompadd\fP builtin\&.
+It gives direct control over which
+filenames should be ignored\&.  If the option is not present, the
+\fBignored\-patterns\fP style is used\&.
+.PP
+Both \fB_path_files\fP and \fB_files\fP also accept the following options
+which are passed to \fBcompadd\fP: `\fB\-J\fP', `\fB\-V\fP',
+`\fB\-1\fP', `\fB\-2\fP', `\fB\-n\fP', `\fB\-X\fP', `\fB\-M\fP', `\fB\-P\fP', `\fB\-S\fP',
+`\fB\-q\fP', `\fB\-r\fP', and `\fB\-R\fP'\&.
+.PP
+Finally, the \fB_path_files\fP function  uses the styles \fBexpand\fP,
+\fBambiguous\fP, \fBspecial\-dirs\fP, \fBlist\-suffixes\fP and \fBfile\-sort\fP
+described above\&.
+.RE
+.TP
+\fB_pick_variant [ \fB\-c\fP \fIcommand\fP ] [ \fB\-r\fP \fIname\fP ] \fIlabel\fP\fB=\fP\fIpattern\fP \&.\&.\&. \fIlabel\fP [ \fIargs\fP \&.\&.\&. ]\fP
+This function is used to resolve situations where a single command name
+requires more than one type of handling, either because it
+has more than one variant or because there is a name clash between two
+different commands\&.
+.RS
+.PP
+The command to run is taken from the first element of the array
+\fBwords\fP unless this is overridden by the option \fB\-c\fP\&.  This command
+is run and its output is compared with a series of patterns\&.  Arguments
+to be passed to the command can be specified at the end after all the
+other arguments\&.  The patterns to try in order are given by the arguments
+\fIlabel\fP\fB=\fP\fIpattern\fP; if the output of `\fIcommand\fP \fIargs\fP
+\fB\&.\&.\&.\fP' contains \fIpattern\fP, then \fBlabel\fP is selected as the label
+for the command variant\&.  If none of the patterns match, the final
+command label is selected and status 1 is returned\&.
+.PP
+If the `\fB\-r\fP \fIname\fP' is given, the \fIlabel\fP picked is stored in
+the parameter named \fIname\fP\&.
+.PP
+The results are also cached in the \fI_cmd_variant\fP associative array
+indexed by the name of the command run\&.
+.RE
+.TP
+\fB_regex_arguments\fP \fIname\fP \fIspec\fP \&.\&.\&.
+This function generates a completion function \fIname\fP which matches
+the specifications \fIspec\fP \fB\&.\&.\&.\fP, a set of regular expressions as
+described below\&.  After running \fB_regex_arguments\fP, the function
+\fIname\fP should be called at the appropriate point\&.
+The pattern to be matched is given by the contents of
+the \fBwords\fP array up to the current cursor position joined together
+with null characters; no quotation is applied\&.
+.RS
+.PP
+The arguments are grouped as sets of alternatives separated by `\fB|\fP',
+which are tried one after the other until one matches\&.  Each alternative
+consists of a one or more specifications which are tried left to right,
+with each pattern matched being stripped in turn from the command line
+being tested, until all of the group succeeds or until one fails; in the
+latter case, the next alternative is tried\&.  This structure can be
+repeated to arbitrary depth by using parentheses; matching proceeds from
+inside to outside\&.
+.PP
+A special procedure is applied if no test succeeds but the remaining
+command line string contains no null character (implying the remaining
+word is the one for which completions are to be generated)\&.  The
+completion target is restricted to the remaining word and any
+\fIaction\fPs for the corresponding patterns are executed\&.  In this case,
+nothing is stripped from the command line string\&.  The order of
+evaluation of the \fIaction\fPs can be determined by the \fBtag\-order\fP
+style; the various formats supported by \fB_alternative\fP can be used
+in \fIaction\fP\&.  The \fIdescr\fP is used for setting up the array
+parameter \fBexpl\fP\&.
+.PP
+Specification arguments take one of following forms, in which
+metacharacters such as `\fB(\fP', `\fB)\fP', `\fB#\fP' and `\fB|\fP'
+should be quoted\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB/\fP\fIpattern\fP\fB/\fP [\fB%\fP\fIlookahead\fP\fB%\fP] [\fB\-\fP\fIguard\fP] [\fB:\fP\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP]
+This is a single primitive component\&.
+The function tests whether the combined pattern
+`\fB(#b)((#B)\fP\fIpattern\fP\fB)\fP\fIlookahead\fP\fB*\fP' matches
+the command line string\&.  If so, `\fIguard\fP' is evaluated and
+its return status is examined to determine if the test has succeeded\&.
+The \fIpattern\fP string `\fB[]\fP' is guaranteed never to match\&.
+The \fIlookahead\fP is not stripped from the command line before the next
+pattern is examined\&.
+.TP
+\fB/\fP\fIpattern\fP\fB/+\fP [\fB%\fP\fIlookahead\fP\fB%\fP] [\fB\-\fP\fIguard\fP] [\fB:\fP\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP]
+This is similar to `\fB/\fP\fIpattern\fP\fB/\fP \&.\&.\&.' but the left part of the
+command line string (i\&.e\&. the part already matched by previous patterns)
+is also considered part of the completion target\&.
+.TP
+\fB/\fP\fIpattern\fP\fB/\-\fP [\fB%\fP\fIlookahead\fP\fB%\fP] [\fB\-\fP\fIguard\fP] [\fB:\fP\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP]
+This is similar to `\fB/\fP\fIpattern\fP\fB/\fP \&.\&.\&.' but the \fIaction\fPs of the
+current and previously matched patterns are ignored even if the
+following `\fIpattern\fP' matches the empty string\&.
+.TP
+\fB(\fP \fIspec\fP \fB)\fP
+Parentheses may be used to groups \fIspec\fPs; note each parenthesis
+is a single argument to \fB_regex_arguments\fP\&.
+.TP
+\fIspec\fP \fB#\fP
+This allows any number of repetitions of \fIspec\fP\&.
+.TP
+\fIspec\fP \fIspec\fP
+The two \fIspec\fPs are to be matched one after the other as described
+above\&.
+.TP
+\fIspec\fP \fB|\fP \fIspec\fP
+Either of the two \fIspec\fPs can be matched\&.
+.RE
+.TP
+\fB_requested\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP [ \fIname\fP \fIdescr\fP [ \fIcommand\fP \fIargs\fP \&.\&.\&. ] ]
+This function is called to decide whether a tag already registered by a
+call to \fB_tags\fP (see below) has been requested by the user and hence
+completion should be performed for it\&.  It returns status zero if the
+tag is requested and non\-zero otherwise\&.  The function is typically used
+as part of a loop over different tags as follows:
+.RS
+.PP
+.RS
+.nf
+\fB_tags foo bar baz
+while _tags; do
+  if _requested foo; then
+    \&.\&.\&. # perform completion for foo
+  fi
+  \&.\&.\&. # test the tags bar and baz in the same way
+  \&.\&.\&. # exit loop if matches were generated
+done\fP
+.fi
+.RE
+.PP
+Note that the test for whether matches were generated is not performed
+until the end of the \fB_tags\fP loop\&.  This is so that the user can set
+the \fBtag\-order\fP style to specify a set of tags to be completed at the
+same time\&.
+.PP
+If \fIname\fP and \fIdescr\fP are given, \fB_requested\fP calls the
+\fB_description\fP function with these arguments together with the options
+passed to \fB_requested\fP\&.
+.PP
+If \fIcommand\fP is given, the \fB_all_labels\fP function will be called
+immediately with the same arguments\&.  In simple cases this makes it
+possible to perform the test for the tag and the matching in one go\&.
+For example:
+.PP
+.RS
+.nf
+\fBlocal expl ret=1
+_tags foo bar baz
+while _tags; do
+  _requested foo expl 'description' \e 
+      compadd foobar foobaz && ret=0
+  \&.\&.\&.
+  (( ret )) || break
+done\fP
+.fi
+.RE
+.PP
+If the \fIcommand\fP is not \fBcompadd\fP, it must nevertheless be prepared
+to handle the same options\&.
+.RE
+.TP
+\fB_retrieve_cache\fP \fIcache_identifier\fP
+This function retrieves completion information from the file given by
+\fIcache_identifier\fP, stored in a directory specified by the
+\fBcache\-path\fP style which defaults to \fB~/\&.zcompcache\fP\&.  The return value
+is zero if retrieval was successful\&.  It will only attempt retrieval
+if the \fBuse\-cache\fP style is set, so you can call this function
+without worrying about whether the user wanted to use the caching
+layer\&.
+.RS
+.PP
+See \fB_store_cache\fP below for more details\&.
+.RE
+.TP
+\fB_sep_parts\fP
+This function is passed alternating arrays and separators as arguments\&.
+The arrays specify completions for parts of strings to be separated by the
+separators\&.  The arrays may be the names of array parameters or
+a quoted list of words in parentheses\&.  For example, with the array
+`\fBhosts=(ftp news)\fP' the call `\fB_sep_parts '(foo bar)' @ hosts\fP' will
+complete the string  `\fBf\fP' to `\fBfoo\fP' and the string `\fBb@n\fP' to
+`\fBbar@news\fP'\&.
+.RS
+.PP
+This function accepts the \fBcompadd\fP options `\fB\-V\fP', `\fB\-J\fP',
+`\fB\-1\fP', `\fB\-2\fP', `\fB\-n\fP', `\fB\-X\fP', `\fB\-M\fP', `\fB\-P\fP', `\fB\-S\fP',
+`\fB\-r\fP', `\fB\-R\fP', and `\fB\-q\fP' and passes them on to the \fBcompadd\fP
+builtin used to add the matches\&.
+.RE
+.TP
+\fB_setup\fP \fItag\fP [ \fIgroup\fP ]
+This function sets up the special
+parameters used by the completion system appropriately for the \fItag\fP
+given as the first argument\&.  It uses the styles \fBlist\-colors\fP,
+\fBlist\-packed\fP, \fBlist\-rows\-first\fP, \fBlast\-prompt\fP, \fBaccept\-exact\fP,
+\fBmenu\fP and \fBforce\-list\fP\&.
+.RS
+.PP
+The optional \fIgroup\fP supplies the name of the group in which the
+matches will be placed\&.  If it is not given, the \fItag\fP is used as
+the group name\&.
+.PP
+This function is called automatically from \fB_description\fP
+and hence is not normally called explicitly\&.
+.RE
+.TP
+\fB_store_cache\fP \fIcache_identifier\fP \fIparams\fP \&.\&.\&.
+This function, together with \fB_retrieve_cache\fP and
+\fB_cache_invalid\fP, implements a caching layer which can be used
+in any completion function\&.  Data obtained by
+costly operations are stored in parameters;
+this function then dumps the values of those parameters to a file\&.  The
+data can then be retrieved quickly from that file via \fB_retrieve_cache\fP,
+even in different instances of the shell\&.
+.RS
+.PP
+The \fIcache_identifier\fP specifies the file which the data should be
+dumped to\&.  The file is stored in a directory specified by the
+\fBcache\-path\fP style which defaults to \fB~/\&.zcompcache\fP\&.  The remaining
+\fIparams\fP arguments are the parameters to dump to the file\&.
+.PP
+The return value is zero if storage was successful\&.  The function will
+only attempt storage if the \fBuse\-cache\fP style is set, so you can
+call this function without worrying about whether the user wanted to
+use the caching layer\&.
+.PP
+The completion function may avoid calling \fB_retrieve_cache\fP when it
+already has the completion data available as parameters\&. 
+However, in that case it should
+call \fB_cache_invalid\fP to check whether the data in the parameters and
+in the cache are still valid\&.
+.PP
+See the _perl_modules completion function for a simple example of
+the usage of the caching layer\&.
+.RE
+.TP
+\fB_tags\fP [ [ \fB\-C\fP \fIname\fP ] \fItags\fP \&.\&.\&. ]
+If called with arguments, these are taken to be the names of tags
+valid for completions in the current context\&.  These tags are stored
+internally and sorted by using the \fBtag\-order\fP style\&.
+.RS
+.PP
+Next, \fB_tags\fP is called repeatedly without arguments from the same
+completion function\&.  This successively selects the first, second,
+etc\&. set of tags requested by the user\&.  The return value is zero if at
+least one of the tags is requested and non\-zero otherwise\&.  To test if a
+particular tag is to be tried, the \fB_requested\fP function should be
+called (see above)\&.
+.PP
+If `\fB\-C\fP \fIname\fP' is given, \fIname\fP is temporarily stored in the
+argument field (the fifth) of the context in the \fBcurcontext\fP parameter
+during the call to \fB_tags\fP; the field is restored on exit\&.  This
+allows \fB_tags\fP to use a more 
+specific context without having to change and reset the
+\fBcurcontext\fP parameter (which has the same effect)\&.
+.RE
+.TP
+\fB_values\fP [ \fB\-O\fP \fIname\fP ] [ \fB\-s\fP \fIsep\fP ] [ \fB\-S\fP \fIsep\fP ] [ \fB\-wC\fP ] \fIdesc\fP \fIspec\fP \&.\&.\&.
+This is used to complete arbitrary keywords (values) and their arguments,
+or lists of such combinations\&.
+.RS
+.PP
+If the first argument is the option `\fB\-O\fP \fIname\fP', it will be used
+in the same way as by the \fB_arguments\fP function\&.  In other words, the
+elements of the \fIname\fP array will be passed to \fBcompadd\fP
+when executing an action\&.
+.PP
+If the first argument (or the first argument after `\fB\-O\fP \fIname\fP')
+is `\fB\-s\fP', the next argument is used as the character that separates
+multiple values\&.  This character is automatically added after each value
+in an auto\-removable fashion (see below); all values completed by
+`\fB_values \-s\fP' appear in the same word on the command line, unlike
+completion using \fB_arguments\fP\&.  If this option is not present, only a
+single value will be completed per word\&.
+.PP
+Normally, \fB_values\fP will only use the current word to determine
+which values are already present on the command line and hence are not
+to be completed again\&.  If the \fB\-w\fP option is given, other arguments
+are examined as well\&.
+.PP
+The first non\-option argument is used as a string to print as a
+description before listing the values\&.
+.PP
+All other arguments describe the possible values and their
+arguments in the same format used for the description of options by
+the \fB_arguments\fP function (see above)\&.  The only differences are that
+no minus or plus sign is required at the beginning,
+values can have only one argument, and the forms of action
+beginning with an equal sign are not supported\&.
+.PP
+The character separating a value from its argument can be set using the
+option \fB\-S\fP (like \fB\-s\fP, followed by the character to use as the
+separator in the next argument)\&.  By default the equals
+sign will be used as the separator between values and arguments\&.
+.PP
+Example:
+.PP
+.RS
+.nf
+\fB_values \-s , 'description' \e 
+        '*foo[bar]' \e 
+        '(two)*one[number]:first count:' \e 
+        'two[another number]::second count:(1 2 3)'\fP
+.fi
+.RE
+.PP
+This describes three possible values: `\fBfoo\fP', `\fBone\fP', and
+`\fBtwo\fP'\&.  The first is described as `\fBbar\fP', takes no argument 
+and may appear more than once\&.  The second is described as
+`\fBnumber\fP', may appear more than once, and takes one mandatory
+argument described as `\fBfirst count\fP'; no action is
+specified, so it will not be completed\&.  The
+`\fB(two)\fP' at the beginning says that if the value `\fBone\fP' is on
+the line, the value `\fBtwo\fP' will no longer be considered a possible
+completion\&.  Finally, the last value (`\fBtwo\fP') is described
+as `\fBanother number\fP' and takes an optional argument described as
+`\fBsecond count\fP' for which the completions (to appear after an
+`\fB=\fP') are `\fB1\fP', `\fB2\fP', and `\fB3\fP'\&.  The \fB_values\fP function
+will complete lists of these values separated by commas\&.
+.PP
+Like \fB_arguments\fP, this function temporarily adds another context name
+component to the arguments element (the fifth) of the current context
+while executing the \fIaction\fP\&.  Here this name is just the name of the
+value for which the argument is completed\&.
+.PP
+The style \fBverbose\fP is used to decide if the descriptions for the
+values (but not those for the arguments) should be printed\&.
+.PP
+The associative array \fBval_args\fP is used to report values and their
+arguments; this works similarly to the \fBopt_args\fP associative array
+used by \fB_arguments\fP\&.  Hence the function calling \fB_values\fP should
+declare the local parameters \fBstate\fP, \fBline\fP, \fBcontext\fP and
+\fBval_args\fP:
+.PP
+.RS
+.nf
+\fBlocal context state line
+typeset \-A val_args\fP
+.fi
+.RE
+.PP
+when using an action of the form `\fB\->\fP\fIstring\fP'\&.  With this
+function the \fBcontext\fP parameter will be set to the name of the
+value whose argument is to be completed\&.
+.PP
+Note also that \fB_values\fP normally adds the character used as the
+separator between values as an auto\-removable suffix (similar to a
+`\fB/\fP' after a directory)\&.  However, this is not possible for a
+`\fB\->\fP\fIstring\fP' action as the matches for the argument are
+generated by the calling function\&.  To get the usual behaviour, the
+the calling function can add the separator \fIx\fP as a suffix by
+passing the options `\fB\-qS\fP \fIx\fP' either directly or indirectly to
+\fBcompadd\fP\&.
+.PP
+The option \fB\-C\fP is treated in the same way as it is by \fB_arguments\fP\&.
+In that case the parameter \fBcurcontext\fP should be made local instead 
+of \fBcontext\fP (as described above)\&.
+.RE
+.TP
+\fB_wanted\fP [ \fB\-x\fP ] [ \fB\-C\fP \fIname\fP ]  [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP \fIcommand\fP \fIargs\fP \&.\&.\&.
+In many contexts, completion can only generate one particular set of
+matches, usually corresponding to a single tag\&.  However, it is
+still necessary to decide whether the user requires matches of this type\&.
+This function is useful in such a case\&.
+.RS
+.PP
+The arguments to \fB_wanted\fP are the same as those to \fB_requested\fP,
+i\&.e\&. arguments to be passed to \fB_description\fP\&.  However, in this case
+the \fIcommand\fP is not optional;  all the processing of tags, including
+the loop over both tags and tag labels and the generation of matches,
+is carried out automatically by \fB_wanted\fP\&.
+.PP
+Hence to offer only one tag and immediately add the corresponding
+matches with the given description:
+.PP
+.RS
+.nf
+\fB_wanted tag expl 'description' \e 
+    compadd matches\&.\&.\&.\fP
+.fi
+.RE
+.PP
+Note that, as for \fB_requested\fP, the \fIcommand\fP must be able to
+accept options to be passed down to \fBcompadd\fP\&.
+.PP
+Like \fB_tags\fP this function supports the \fB\-C\fP option to give a
+different name for the argument context field\&.  The \fB\-x\fP option has
+the same meaning as for \fB_description\fP\&.
+.RE
+.RE
+.PP
+.SH "COMPLETION DIRECTORIES"
+.PP
+In the source distribution, the files are contained in various
+subdirectories of the \fBCompletion\fP directory\&.  They may have been
+installed in the same structure, or into one single function directory\&.
+The following is a description of the files found in the original directory
+structure\&.  If you wish to alter an installed file, you will need to copy
+it to some directory which appears earlier in your \fBfpath\fP than the
+standard directory where it appears\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBBase\fP
+The core functions and special completion widgets automatically bound
+to keys\&.  You will certainly need most of these, though will
+probably not need to alter them\&.  Many of these are documented above\&.
+.TP
+\fBZsh\fP
+Functions for completing arguments of shell builtin commands and
+utility functions for this\&.  Some of these are also used by functions from
+the \fBUnix\fP directory\&.
+.TP
+\fBUnix\fP
+Functions for completing arguments of external commands and suites of
+commands\&.  They may need modifying for your system, although in many cases
+some attempt is made to decide which version of a command is present\&.  For
+example, completion for the \fBmount\fP command tries to determine the system
+it is running on, while completion for many other utilities try to decide
+whether the GNU version of the command is in use, and hence whether the
+\fB\-\-help\fP option is supported\&.
+.TP
+\fBX\fP, \fBAIX\fP, \fBBSD\fP, \&.\&.\&.
+Completion and utility function for commands available only on some systems\&.
+These are not arranged hierarchically, so, for example, both the
+\fBLinux\fP and \fBDebian\fP directories, as well as the \fBX\fP directory,
+may be useful on your system\&.
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshcontrib.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshcontrib.1
@@ -0,0 +1,1792 @@
+.TH "ZSHCONTRIB" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshcontrib \- user contributions to zsh
+.\" Yodl file: Zsh/contrib.yo
+.SH "DESCRIPTION"
+.PP
+The Zsh source distribution includes a number of items contributed by the
+user community\&.  These are not inherently a part of the shell, and some
+may not be available in every zsh installation\&.  The most significant of
+these are documented here\&.  For documentation on other contributed items
+such as shell functions, look for comments in the function source files\&.
+.PP
+.PP
+.SH "UTILITIES"
+.PP
+.SS "Accessing On\-Line Help"
+.PP
+The key sequence \fBESC h\fP is normally bound by ZLE to execute the
+\fBrun\-help\fP widget (see
+\fIzshzle\fP(1))\&.  This invokes the \fBrun\-help\fP command with the command word from the
+current input line as its argument\&.  By default, \fBrun\-help\fP is an alias
+for the \fBman\fP command, so this often fails when the command word is a
+shell builtin or a user\-defined function\&.  By redefining the \fBrun\-help\fP
+alias, one can improve the on\-line help provided by the shell\&.
+.PP
+The \fBhelpfiles\fP utility, found in the \fBUtil\fP directory of the
+distribution, is a Perl program that can be used to process the zsh manual
+to produce a separate help file for each shell builtin and for many other
+shell features as well\&.  The autoloadable \fBrun\-help\fP function, found in
+\fBFunctions/Misc\fP, searches for these helpfiles and performs several
+other tests to produce the most complete help possible for the command\&.
+.PP
+There may already be a directory of help files on your system; look in
+\fB/usr/share/zsh\fP or \fB/usr/local/share/zsh\fP and subdirectories below
+those, or ask your system administrator\&.
+.PP
+To create your own help files with \fBhelpfiles\fP, choose or create a
+directory where the individual command help files will reside\&.  For
+example, you might choose \fB~/zsh_help\fP\&.  If you unpacked the zsh
+distribution in your home directory, you would use the commands:
+.PP
+.RS
+.nf
+\fBmkdir ~/zsh_help
+cd ~/zsh_help
+man zshall | colcrt \- | \e 
+perl ~/zsh\-4\&.2\&.1\-dev\-1/Util/helpfiles\fP
+.fi
+.RE
+.PP
+Next, to use the \fBrun\-help\fP function, you need to add lines something
+like the following to your \fB\&.zshrc\fP or equivalent startup file:
+.PP
+.RS
+.nf
+\fBunalias run\-help
+autoload run\-help
+HELPDIR=~/zsh_help\fP
+.fi
+.RE
+.PP
+The \fBHELPDIR\fP parameter tells \fBrun\-help\fP where to look for the help
+files\&.  If your system already has a help file directory installed, set
+\fBHELPDIR\fP to the path of that directory instead\&.
+.PP
+Note that in order for `\fBautoload run\-help\fP' to work, the \fBrun\-help\fP
+file must be in one of the directories named in your \fBfpath\fP array (see
+\fIzshparam\fP(1))\&.  This should already be the case if you have a standard zsh
+installation; if it is not, copy \fBFunctions/Misc/run\-help\fP to an
+appropriate directory\&.
+.PP
+.SS "Recompiling Functions"
+.PP
+If you frequently edit your zsh functions, or periodically update your zsh
+installation to track the latest developments, you may find that function
+digests compiled with the \fBzcompile\fP builtin are frequently out of date
+with respect to the function source files\&.  This is not usually a problem,
+because zsh always looks for the newest file when loading a function, but
+it may cause slower shell startup and function loading\&.  Also, if a digest
+file is explicitly used as an element of \fBfpath\fP, zsh won't check whether
+any of its source files has changed\&.
+.PP
+The \fBzrecompile\fP autoloadable function, found in \fBFunctions/Misc\fP, can
+be used to keep function digests up to date\&.
+.PP
+.PD 0
+.TP
+.PD 0
+\fBzrecompile\fP [ \fB\-qt\fP ] [ \fIname\fP \&.\&.\&. ]
+.TP
+.PD
+\fBzrecompile\fP [ \fB\-qt\fP ] \fB\-p\fP \fIargs\fP [ \fB\-\fP\fB\-\fP \fIargs\fP \&.\&.\&. ]
+This tries to find \fB*\&.zwc\fP files and automatically re\-compile them if at
+least one of the original files is newer than the compiled file\&.  This
+works only if the names stored in the compiled files are full paths or are
+relative to the directory that contains the \fB\&.zwc\fP file\&.
+.RS
+.PP
+In the first form, each \fIname\fP is the name of a compiled file or a
+directory containing \fB*\&.zwc\fP files that should be checked\&.  If no
+arguments are given, the directories and \fB*\&.zwc\fP files in \fBfpath\fP are
+used\&.
+.PP
+When \fB\-t\fP is given, no compilation is performed, but a return status of
+zero (true) is set if there are files that need to be re\-compiled and
+non\-zero (false) otherwise\&.  The \fB\-q\fP option quiets the chatty output
+that describes what \fBzrecompile\fP is doing\&.
+.PP
+Without the \fB\-t\fP option, the return status is zero if all files that
+needed re\-compilation could be compiled and non\-zero if compilation for at
+least one of the files failed\&.
+.PP
+If the \fB\-p\fP option is given, the \fIargs\fP are interpreted as one
+or more sets of arguments for \fBzcompile\fP, separated by `\fB\-\fP\fB\-\fP'\&.
+For example:
+.PP
+.RS
+.nf
+\fBzrecompile \-p \e 
+           \-R ~/\&.zshrc \-\- \e 
+           \-M ~/\&.zcompdump \-\- \e 
+           ~/zsh/comp\&.zwc ~/zsh/Completion/*/_*\fP
+.fi
+.RE
+.PP
+This compiles \fB~/\&.zshrc\fP into \fB~/\&.zshrc\&.zwc\fP if that doesn't exist or
+if it is older than \fB~/\&.zshrc\fP\&. The compiled file will be marked for
+reading instead of mapping\&. The same is done for \fB~/\&.zcompdump\fP and
+\fB~/\&.zcompdump\&.zwc\fP, but this compiled file is marked for mapping\&. The
+last line re\-creates the file \fB~/zsh/comp\&.zwc\fP if any of the files
+matching the given pattern is newer than it\&.
+.PP
+Without the \fB\-p\fP option, \fBzrecompile\fP does not create function digests
+that do not already exist, nor does it add new functions to the digest\&.
+.RE
+.RE
+.PP
+The following shell loop is an example of a method for creating function
+digests for all functions in your \fBfpath\fP, assuming that you have write
+permission to the directories:
+.PP
+.RS
+.nf
+\fBfor ((i=1; i <= $#fpath; ++i)); do
+  dir=$fpath[i]
+  zwc=${dir:t}\&.zwc
+  if [[ $dir == (\&.|\&.\&.) || $dir == (\&.|\&.\&.)/* ]]; then
+    continue
+  fi
+  files=($dir/*(N\-\&.))
+  if [[ \-w $dir:h && \-n $files ]]; then
+    files=(${${(M)files%/*/*}#/})
+    if ( cd $dir:h &&
+         zrecompile \-p \-U \-z $zwc $files ); then
+      fpath[i]=$fpath[i]\&.zwc
+    fi
+  fi
+done\fP
+.fi
+.RE
+.PP
+The \fB\-U\fP and \fB\-z\fP options are appropriate for functions in the default
+zsh installation \fBfpath\fP; you may need to use different options for your
+personal function directories\&.
+.PP
+Once the digests have been created and your \fBfpath\fP modified to refer to
+them, you can keep them up to date by running \fBzrecompile\fP with no
+arguments\&.
+.PP
+.SS "Keyboard Definition"
+.PP
+The large number of possible combinations of keyboards, workstations,
+terminals, emulators, and window systems makes it impossible for zsh to
+have built\-in key bindings for every situation\&.  The \fBzkbd\fP utility,
+found in Functions/Misc, can help you quickly create key bindings for your
+configuration\&.
+.PP
+Run \fBzkbd\fP either as an autoloaded function, or as a shell script:
+.PP
+.RS
+.nf
+\fBzsh \-f ~/zsh\-4\&.2\&.1\-dev\-1/Functions/Misc/zkbd\fP
+.fi
+.RE
+.PP
+When you run \fBzkbd\fP, it first asks you to enter your terminal type; if
+the default it offers is correct, just press return\&.  It then asks you to
+press a number of different keys to determine characteristics of your
+keyboard and terminal; \fBzkbd\fP warns you if it finds anything out of the
+ordinary, such as a Delete key that sends neither \fB^H\fP nor \fB^?\fP\&.
+.PP
+The keystrokes read by \fBzkbd\fP are recorded as a definition for an
+associative array named \fBkey\fP, written to a file in the subdirectory
+\fB\&.zkbd\fP within either your \fBHOME\fP or \fBZDOTDIR\fP directory\&.  The name
+of the file is composed from the \fBTERM\fP, \fBVENDOR\fP and \fBOSTYPE\fP
+parameters, joined by hyphens\&.
+.PP
+You may read this file into your \fB\&.zshrc\fP or another startup file with
+the "source" or "\&." commands, then reference the \fBkey\fP parameter in
+bindkey commands, like this:
+.PP
+.RS
+.nf
+\fBsource ${ZDOTDIR:\-$HOME}/\&.zkbd/$TERM\-$VENDOR\-$OSTYPE
+[[ \-n ${key[Left]} ]] && bindkey "${key[Left]}" backward\-char
+[[ \-n ${key[Right]} ]] && bindkey "${key[Right]}" forward\-char
+# etc\&.\fP
+.fi
+.RE
+.PP
+Note that in order for `\fBautoload zkbd\fP' to work, the \fBzkdb\fP file must
+be in one of the directories named in your \fBfpath\fP array (see
+\fIzshparam\fP(1))\&.  This should already be the case if you have a standard zsh
+installation; if it is not, copy \fBFunctions/Misc/zkbd\fP to an
+appropriate directory\&.
+.PP
+.SS "Dumping Shell State"
+.PP
+Occasionally you may encounter what appears to be a bug in the shell,
+particularly if you are using a beta version of zsh or a development
+release\&.  Usually it is sufficient to send a description of the
+problem to one of the zsh mailing lists (see
+\fIzsh\fP(1)), but sometimes one of the zsh developers will need to recreate your
+environment in order to track the problem down\&.
+.PP
+The script named \fBreporter\fP, found in the \fBUtil\fP directory of the
+distribution, is provided for this purpose\&.  (It is also possible to
+\fBautoload reporter\fP, but \fBreporter\fP is not installed in \fBfpath\fP
+by default\&.)  This script outputs a detailed dump of the shell state,
+in the form of another script that can be read with `\fBzsh \-f\fP' to
+recreate that state\&.
+.PP
+To use \fBreporter\fP, read the script into your shell with the `\fB\&.\fP'
+command and redirect the output into a file:
+.PP
+.RS
+.nf
+\fB\&. ~/zsh\-4\&.2\&.1\-dev\-1/Util/reporter > zsh\&.report\fP
+.fi
+.RE
+.PP
+You should check the \fBzsh\&.report\fP file for any sensitive information
+such as passwords and delete them by hand before sending the script to the
+developers\&.  Also, as the output can be voluminous, it's best to wait for
+the developers to ask for this information before sending it\&.
+.PP
+You can also use \fBreporter\fP to dump only a subset of the shell state\&.
+This is sometimes useful for creating startup files for the first time\&.
+Most of the output from reporter is far more detailed than usually is
+necessary for a startup file, but the \fBaliases\fP, \fBoptions\fP, and
+\fBzstyles\fP states may be useful because they include only changes from
+the defaults\&.  The \fBbindings\fP state may be useful if you have created
+any of your own keymaps, because \fBreporter\fP arranges to dump the keymap
+creation commands as well as the bindings for every keymap\&.
+.PP
+As is usual with automated tools, if you create a startup file with
+\fBreporter\fP, you should edit the results to remove unnecessary commands\&.
+Note that if you're using the new completion system, you should \fInot\fP
+dump the \fBfunctions\fP state to your startup files with \fBreporter\fP; use
+the \fBcompdump\fP function instead (see
+\fIzshcompsys\fP(1))\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBreporter\fP [ \fIstate\fP \&.\&.\&. ]
+Print to standard output the indicated subset of the current shell state\&.
+The \fIstate\fP arguments may be one or more of:
+.RS
+.PP
+.PD 0
+.TP
+\fBall\fP
+Output everything listed below\&.
+.TP
+\fBaliases\fP
+Output alias definitions\&.
+.TP
+\fBbindings\fP
+Output ZLE key maps and bindings\&.
+.TP
+\fBcompletion\fP
+Output old\-style \fBcompctl\fP commands\&.
+New completion is covered by \fBfunctions\fP and \fBzstyles\fP\&.
+.TP
+\fBfunctions\fP
+Output autoloads and function definitions\&.
+.TP
+\fBlimits\fP
+Output \fBlimit\fP commands\&.
+.TP
+\fBoptions\fP
+Output \fBsetopt\fP commands\&.
+.TP
+\fBstyles\fP
+Same as \fBzstyles\fP\&.
+.TP
+\fBvariables\fP
+Output shell parameter assignments, plus \fBexport\fP
+commands for any environment variables\&.
+.TP
+\fBzstyles\fP
+Output \fBzstyle\fP commands\&.
+.PD
+.PP
+If the \fIstate\fP is omitted, \fBall\fP is assumed\&.
+.RE
+.PP
+With the exception of `\fBall\fP', every \fIstate\fP can be abbreviated by
+any prefix, even a single letter; thus \fBa\fP is the same as \fBaliases\fP,
+\fBz\fP is the same as \fBzstyles\fP, etc\&.
+.RE
+.PP
+.SH "PROMPT THEMES"
+.PP
+.SS "Installation"
+.PP
+You should make sure all the functions from the \fBFunctions/Prompts\fP
+directory of the source distribution are available; they all begin with
+the string `\fBprompt_\fP' except for the special function`\fBpromptinit\fP'\&.
+You also need the `\fBcolors\fP' function from \fBFunctions/Misc\fP\&.  All of
+these functions may already have been installed on your system; if not,
+you will need to find them and copy them\&.  The directory should appear as
+one of the elements of the \fBfpath\fP array (this should already be the
+case if they were installed), and at least the function \fBpromptinit\fP
+should be autoloaded; it will autoload the rest\&.  Finally, to initialize
+the use of the system you need to call the \fBpromptinit\fP function\&.  The
+following code in your \fB\&.zshrc\fP will arrange for this; assume the
+functions are stored in the directory \fB~/myfns\fP:
+.PP
+.RS
+.nf
+\fBfpath=(~/myfns $fpath)
+autoload \-U promptinit
+promptinit\fP
+.fi
+.RE
+.PP
+.SS "Theme Selection"
+.PP
+Use the \fBprompt\fP command to select your preferred theme\&.  This command
+may be added to your \fB\&.zshrc\fP following the call to \fBpromptinit\fP in
+order to start zsh with a theme already selected\&.
+.PP
+.PD 0
+.TP
+.PD 0
+\fBprompt\fP [ \fB\-c\fP | \fB\-l\fP ]
+.TP
+.PD 0
+\fBprompt\fP [ \fB\-p\fP | \fB\-h\fP ] [ \fItheme\fP \&.\&.\&. ]
+.TP
+.PD
+\fBprompt\fP [ \fB\-s\fP ] \fItheme\fP [ \fIarg\fP \&.\&.\&. ]
+Set or examine the prompt theme\&.  With no options and a \fItheme\fP
+argument, the theme with that name is set as the current theme\&.  The
+available themes are determined at run time; use the \fB\-l\fP option to see
+a list\&.  The special \fItheme\fP `\fBrandom\fP' selects at random one of the
+available themes and sets your prompt to that\&.
+.RS
+.PP
+In some cases the \fItheme\fP may be modified by one or more arguments,
+which should be given after the theme name\&.  See the help for each theme
+for descriptions of these arguments\&.
+.PP
+Options are:
+.PP
+.PD 0
+.TP
+\fB\-c\fP
+Show the currently selected theme and its parameters, if any\&.
+.TP
+\fB\-l\fP
+List all available prompt themes\&.
+.TP
+\fB\-p\fP
+Preview the theme named by \fItheme\fP, or all themes if no
+\fItheme\fP is given\&.
+.TP
+\fB\-h\fP
+Show help for the theme named by \fItheme\fP, or for the
+\fBprompt\fP function if no \fItheme\fP is given\&.
+.TP
+\fB\-s\fP
+Set \fItheme\fP as the current theme and save state\&.
+.PD
+.RE
+.TP
+\fBprompt_\fP\fItheme\fP\fB_setup\fP
+Each available \fItheme\fP has a setup function which is called by the
+\fBprompt\fP function to install that theme\&.  This function may define
+other functions as necessary to maintain the prompt, including functions
+used to preview the prompt or provide help for its use\&.  You should not
+normally call a theme's setup function directly\&.
+.PP
+.SH "ZLE FUNCTIONS"
+.PP
+.SS "Widgets"
+.PP
+These functions all implement user\-defined ZLE widgets (see
+\fIzshzle\fP(1)) which can be bound to keystrokes in interactive shells\&.  To use them,
+your \fB\&.zshrc\fP should contain lines of the form
+.PP
+.RS
+.nf
+\fBautoload \fIfunction\fP
+zle \-N \fIfunction\fP\fP
+.fi
+.RE
+.PP
+followed by an appropriate \fBbindkey\fP command to associate the function
+with a key sequence\&.  Suggested bindings are described below\&.
+.PP
+.PD 0
+.TP
+.PD
+bash\-style word functions
+If you are looking for functions to implement moving over and editing
+words in the manner of bash, where only alphanumeric characters are
+considered word characters, you can use the functions described in
+the next section\&.  The following is sufficient:
+.RS
+.PP
+.RS
+.nf
+\fBautoload \-U select\-word\-style
+select\-word\-style bash\fP
+.fi
+.RE
+.PP
+.RE
+.TP
+.PD 0
+\fBforward\-word\-match\fP, \fBbackward\-word\-match\fP
+.TP
+.PD 0
+\fBkill\-word\-match\fP, \fBbackward\-kill\-word\-match\fP
+.TP
+.PD 0
+\fBtranspose\-words\-match\fP, \fBcapitalize\-word\-match\fP
+.TP
+.PD 0
+\fBup\-case\-word\-match\fP, \fBdown\-case\-word\-match\fP
+.TP
+.PD
+\fBselect\-word\-style\fP, \fBmatch\-words\-by\-style\fP
+The eight `\fB\-match\fP' functions are drop\-in replacements for the
+builtin widgets without the suffix\&.  By default they behave in a similar
+way\&.  However, by the use of styles and the function \fBselect\-word\-style\fP,
+the way words are matched can be altered\&.
+.RS
+.PP
+The simplest way of configuring the functions is to use
+\fBselect\-word\-style\fP, which can either be called as a normal function with
+the appropriate argument, or invoked as a user\-defined widget that will
+prompt for the first character of the word style to be used\&.  The first
+time it is invoked, the eight \fB\-match\fP functions will automatically
+replace the builtin versions, so they do not need to be loaded explicitly\&.
+.PP
+The word styles available are as follows\&.  Only the first character
+is examined\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBbash\fP
+Word characters are alphanumeric characters only\&.
+.TP
+\fBnormal\fP
+As in normal shell operation:  word characters are alphanumeric characters
+plus any characters present in the string given by the parameter
+\fB$WORDCHARS\fP\&.
+.TP
+\fBshell\fP
+Words are complete shell command arguments, possibly including complete
+quoted strings, or any tokens special to the shell\&.
+.TP
+\fBwhitespace\fP
+Words are any set of characters delimited by whitespace\&.
+.TP
+\fBdefault\fP
+Restore the default settings; this is usually the same as `\fBnormal\fP'\&.
+.PP
+More control can be obtained using the \fBzstyle\fP command, as described in
+\fIzshmodules\fP(1)\&.  Each style is looked up in the
+context \fB:zle:\fP\fIwidget\fP where \fIwidget\fP is the name of the
+user\-defined widget, not the name of the function implementing it, so in
+the case of the definitions supplied by \fBselect\-word\-style\fP the
+appropriate contexts are \fB:zle:forward\-word\fP, and so on\&.  The function
+\fBselect\-word\-style\fP itself always defines styles for the context
+`\fB:zle:*\fP' which can be overridden by more specific (longer) patterns as
+well as explicit contexts\&.
+.PP
+The style \fBword\-style\fP specifies the rules to use\&.  This may have the
+following values\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBnormal\fP
+Use the standard shell rules, i\&.e\&. alphanumerics and \fB$WORDCHARS\fP, unless
+overridden by the styles \fBword\-chars\fP or \fBword\-class\fP\&.
+.TP
+\fBspecified\fP
+Similar to \fBnormal\fP, but \fIonly\fP the specified characters, and not also
+alphanumerics, are considered word characters\&.
+.TP
+\fBunspecified\fP
+The negation of specified\&.  The given characters are those which will
+\fInot\fP be considered part of a word\&.
+.TP
+\fBshell\fP
+Words are obtained by using the syntactic rules for generating shell
+command arguments\&.  In addition, special tokens which are never command
+arguments such as `\fB()\fP' are also treated as words\&.
+.TP
+\fBwhitespace\fP
+Words are whitespace\-delimited strings of characters\&.
+.PP
+The first three of those styles usually use \fB$WORDCHARS\fP, but the value
+in the parameter can be overridden by the style \fBword\-chars\fP, which works
+in exactly the same way as \fB$WORDCHARS\fP\&.  In addition, the style
+\fBword\-class\fP uses character class syntax to group characters and takes
+precedence over \fBword\-chars\fP if both are set\&.  The \fBword\-class\fP style
+does not include the surrounding brackets of the character class; for
+example, `\fB\-:[:alnum:]\fP' is a valid \fBword\-class\fP to include all
+alphanumerics plus the characters `\fB\-\fP' and `\fB:\fP'\&.  Be careful
+including `\fB]\fP', `\fB^\fP' and `\fB\-\fP' as these are special inside
+character classes\&.
+.PP
+The final style is \fBskip\-chars\fP\&.  This is mostly useful for
+\fBtranspose\-words\fP and similar functions\&.  If set, it gives a count of
+characters starting at the cursor position which will not be considered
+part of the word and are treated as space, regardless of what they actually
+are\&.  For example, if
+.PP
+.RS
+.nf
+\fBzstyle ':zle:transpose\-words' skip\-chars 1\fP
+.fi
+.RE
+.PP
+has been set, and \fBtranspose\-words\-match\fP is called with the cursor on
+the \fIX\fP of \fBfoo\fP\fIX\fP\fBbar\fP, where \fIX\fP can be any character, then
+the resulting expression is \fBbar\fP\fIX\fP\fBfoo\fP\&.
+.PP
+Here are some examples of use of the styles, actually taken from the
+simplified interface in \fBselect\-word\-style\fP:
+.PP
+.RS
+.nf
+\fBzstyle ':zle:*' word\-style standard
+zstyle ':zle:*' word\-chars ''\fP
+.fi
+.RE
+.PP
+Implements bash\-style word handling for all widgets, i\&.e\&. only
+alphanumerics are word characters; equivalent to setting
+the parameter \fBWORDCHARS\fP empty for the given context\&.
+.PP
+.RS
+.nf
+\fBstyle ':zle:*kill*' word\-style space\fP
+.fi
+.RE
+.PP
+Uses space\-delimited words for widgets with the word `kill' in the name\&.
+Neither of the styles \fBword\-chars\fP nor \fBword\-class\fP is used in this case\&.
+.PP
+The word matching and all the handling of \fBzstyle\fP settings is actually
+implemented by the function \fBmatch\-words\-by\-style\fP\&.  This can be used to
+create new user\-defined widgets\&.  The calling function should set the local
+parameter \fBcurcontext\fP to \fB:zle:\fP\fIwidget\fP, create the local
+parameter \fBmatched_words\fP and call \fBmatch\-words\-by\-style\fP with no
+arguments\&.  On return, \fBmatched_words\fP will be set to an array with the
+elements: (1) the start of the line (2) the word before the cursor (3) any
+non\-word characters between that word and the cursor (4) any non\-word
+character at the cursor position plus any remaining non\-word characters
+before the next word, including all characters specified by the
+\fBskip\-chars\fP style, (5) the word at or following the cursor (6) any
+non\-word characters following that word (7) the remainder of the line\&.  Any
+of the elements may be an empty string; the calling function should test
+for this to decide whether it can perform its function\&.
+.RE
+.TP
+\fBdelete\-whole\-word\-match\fP
+This is another function which works like the \fB\-match\fP functions
+described immediately above, i\&.e\&. using styles to decide the word
+boundaries\&.  However, it is not a replacement for any existing function\&.
+.RS
+.PP
+The basic behaviour is to delete the word around the cursor\&.  There is no
+numeric prefix handling; only the single word around the cursor is
+considered\&.  If the widget contains the string \fBkill\fP, the removed text
+will be placed in the cutbuffer for future yanking\&.  This can be obtained
+by defining \fBkill\-whole\-word\-match\fP as follows:
+.PP
+.RS
+.nf
+\fBzle \-N kill\-whole\-word\-match delete\-whole\-word\-match\fP
+.fi
+.RE
+.PP
+and then binding the widget \fBkill\-whole\-word\-match\fP\&.
+.RE
+.TP
+\fBcopy\-earlier\-word\fP
+This widget works like a combination of \fBinsert\-last\-word\fP and
+\fBcopy\-prev\-shell\-word\fP\&.  Repeated invocations of the widget retrieve
+earlier words on the relevant history line\&.  With a numeric argument
+\fIN\fP, insert the \fIN\fPth word from the history line; \fIN\fP may be
+negative to count from the end of the line\&.
+.RS
+.PP
+If \fBinsert\-last\-word\fP has been used to retrieve the last word on a
+previous history line, repeated invocations will replace that word with
+earlier words from the same line\&.
+.PP
+Otherwise, the widget applies to words on the line currently being edited\&.
+The \fBwidget\fP style can be set to the name of another widget that should
+be called to retrieve words\&.  This widget must accept the same three
+arguments as \fBinsert\-last\-word\fP\&.
+.RE
+.TP
+\fBcycle\-completion\-positions\fP
+After inserting an unambiguous string into the command line, the new
+function based completion system may know about multiple places in
+this string where characters are missing or differ from at least one
+of the possible matches\&.  It will then place the cursor on the
+position it considers to be the most interesting one, i\&.e\&. the one
+where one can disambiguate between as many matches as possible with as 
+little typing as possible\&.
+.RS
+.PP
+This widget allows the cursor to be easily moved to the other interesting
+spots\&.  It can be invoked repeatedly to cycle between all positions
+reported by the completion system\&.
+.RE
+.TP
+\fBedit\-command\-line\fP
+Edit the command line using your visual editor, as in \fBksh\fP\&.
+.RS
+.PP
+.RS
+.nf
+\fBbindkey \-M vicmd v edit\-command\-line\fP
+.fi
+.RE
+.RE
+.TP
+\fBhistory\-search\-end\fP
+This function implements the widgets
+\fBhistory\-beginning\-search\-backward\-end\fP and
+\fBhistory\-beginning\-search\-forward\-end\fP\&.  These commands work by first
+calling the corresponding builtin widget (see
+`History Control' in \fIzshzle\fP(1)) and then moving the cursor to the end of the line\&.  The original cursor
+position is remembered and restored before calling the builtin widget a
+second time, so that the same search is repeated to look farther through
+the history\&.
+.RS
+.PP
+Although you \fBautoload\fP only one function, the commands to use it are
+slightly different because it implements two widgets\&.
+.PP
+.RS
+.nf
+\fBzle \-N history\-beginning\-search\-backward\-end \e 
+       history\-search\-end
+zle \-N history\-beginning\-search\-forward\-end \e 
+       history\-search\-end
+bindkey '\ee^P' history\-beginning\-search\-backward\-end
+bindkey '\ee^N' history\-beginning\-search\-forward\-end\fP
+.fi
+.RE
+.RE
+.TP
+\fBhistory\-pattern\-search\fP
+The function \fBhistory\-pattern\-search\fP implements widgets which prompt
+for a pattern with which to search the history backwards or forwards\&.  The
+pattern is in the usual zsh format, however the first character may be
+\fB^\fP to anchor the search to the start of the line, and the last character
+may be \fB$\fP to anchor the search to the end of the line\&.  If the
+search was not anchored to the end of the line the cursor is positioned
+just after the pattern found\&.
+.RS
+.PP
+The commands to create bindable widgets are similar to those in the
+example immediately above:
+.PP
+.RS
+.nf
+\fBautoload \-U history\-pattern\-search
+zle \-N history\-pattern\-search\-backward history\-pattern\-search
+zle \-N history\-pattern\-search\-forward history\-pattern\-search\fP
+.fi
+.RE
+.RE
+.TP
+\fBup\-line\-or\-beginning\-search\fP, \fBdown\-line\-or\-beginning\-search\fP
+These widgets are similar to the builtin functions \fBup\-line\-or\-search\fP
+and \fBdown\-line\-or\-search\fP:  if in a multiline buffer they move up or
+down within the buffer, otherwise they search for a history line matching
+the start of the current line\&.  In this case, however, they search for
+a line which matches the current line up to the current cursor position, in
+the manner of \fBhistory\-beginning\-search\-backward\fP and \fB\-forward\fP, rather
+than the first word on the line\&.
+.TP
+\fBincarg\fP
+Typing the keystrokes for this widget with the cursor placed on or to the
+left of an integer causes that integer to be incremented by one\&.  With a
+numeric prefix argument, the number is incremented by the amount of the
+argument (decremented if the prefix argument is negative)\&.  The shell
+parameter \fBincarg\fP may be set to change the default increment something
+other than one\&.
+.RS
+.PP
+.RS
+.nf
+\fBbindkey '^X+' incarg\fP
+.fi
+.RE
+.RE
+.TP
+\fBincremental\-complete\-word\fP
+This allows incremental completion of a word\&.  After starting this
+command, a list of completion choices can be shown after every character
+you type, which you can delete with \fB^H\fP or \fBDEL\fP\&.  Pressing return
+accepts the completion so far and returns you to normal editing (that is,
+the command line is \fInot\fP immediately executed)\&.  You can hit \fBTAB\fP to
+do normal completion, \fB^G\fP to abort back to the state when you started,
+and \fB^D\fP to list the matches\&.
+.RS
+.PP
+This works only with the new function based completion system\&.
+.PP
+.RS
+.nf
+\fBbindkey '^Xi' incremental\-complete\-word\fP
+.fi
+.RE
+.RE
+.TP
+\fBinsert\-files\fP
+This function allows you type a file pattern, and see the results of the
+expansion at each step\&.  When you hit return, all expansions are inserted
+into the command line\&.
+.RS
+.PP
+.RS
+.nf
+\fBbindkey '^Xf' insert\-files\fP
+.fi
+.RE
+.RE
+.TP
+.PD 0
+\fBnarrow\-to\-region [ \-p\fP \fIpre\fP \fB] [ \-P\fP \fIpost\fP \fB]\fP
+.TP
+.PD 0
+    \fB[ \-S\fP \fIstatepm\fP \fB| \-R\fP \fIstatepm\fP \fB] [ \-n ] [\fP \fIstart\fP \fIend\fP \fB]\fP)
+.TP
+.PD
+\fBnarrow\-to\-region\-invisible\fP
+Narrow the editable portion of the buffer to the region between the cursor
+and the mark, which may be in either order\&.  The region may not be empty\&.
+.RS
+.PP
+\fBnarrow\-to\-region\fP may be used as a widget or called as a function from a
+user\-defined widget; by default, the text outside the editable area remains
+visible\&.  A \fBrecursive\-edit\fP is performed and the original widening
+status is then restored\&.  Various options and arguments are available when
+it is called as a function\&.
+.PP
+The options \fB\-p\fP \fIpretext\fP and \fB\-P\fP \fIposttext\fP may be
+used to replace the text before and after the display for the duration of
+the function; either or both may be an empty string\&.
+.PP
+If the option \fB\-n\fP is also given, \fIpretext\fP or \fIposttext\fP will only
+be inserted if there is text before or after the region respectively which
+will be made invisible\&.
+.PP
+Two numeric arguments may be given which will be used instead of the cursor
+and mark positions\&.
+.PP
+The option \fB\-S\fP \fIstatepm\fP is used to narrow according to the other
+options while saving the original state in the parameter with name
+\fIstatepm\fP, while the option \fB\-R\fP \fIstatepm\fP is used to restore the
+state from the parameter; note in both cases the \fIname\fP of the parameter
+is required\&.  In the second case, other options and arguments are
+irrelevant\&.  When this method is used, no \fBrecursive\-edit\fP is performed;
+the calling widget should call this function with the option \fB\-S\fP,
+perform its own editing on the command line or pass control to the user
+via `\fBzle recursive\-edit\fP', then call this function with the option
+\fB\-R\fP\&.  The argument \fIstatepm\fP must be a suitable name for an ordinary
+parameter, except that parameters beginning with the prefix \fB_ntr_\fP are
+reserved for use within \fBnarrow\-to\-region\fP\&.  Typically the parameter will
+be local to the calling function\&.
+.PP
+\fBnarrow\-to\-region\-invisible\fP is a simple widget which calls
+\fBnarrow\-to\-region\fP with arguments which replace any text outside the
+region with `\fB\&.\&.\&.\fP'\&.
+.PP
+The display is restored (and the widget returns) upon any zle command
+which would usually cause the line to be accepted or aborted\&.  Hence an
+additional such command is required to accept or abort the current line\&.
+.PP
+The return status of both widgets is zero if the line was accepted, else
+non\-zero\&.
+.PP
+Here is a trivial example of a widget using this feature\&.
+.RS
+.nf
+\fBlocal state
+narrow\-to\-region \-p $'Editing restricted region\en' \e 
+  \-P '' \-S state
+zle recursive\-edit
+narrow\-to\-region \-R state\fP
+.fi
+.RE
+.RE
+.TP
+\fBpredict\-on\fP
+This set of functions implements predictive typing using history search\&.
+After \fBpredict\-on\fP, typing characters causes the editor to look backward
+in the history for the first line beginning with what you have typed so
+far\&.  After \fBpredict\-off\fP, editing returns to normal for the line found\&.
+In fact, you often don't even need to use \fBpredict\-off\fP, because if the
+line doesn't match something in the history, adding a key performs
+standard completion, and then inserts itself if no completions were found\&.
+However, editing in the middle of a line is liable to confuse prediction;
+see the \fBtoggle\fP style below\&.
+.RS
+.PP
+With the function based completion system (which is needed for this), you
+should be able to type \fBTAB\fP at almost any point to advance the cursor
+to the next ``interesting'' character position (usually the end of the
+current word, but sometimes somewhere in the middle of the word)\&.  And of
+course as soon as the entire line is what you want, you can accept with
+return, without needing to move the cursor to the end first\&.
+.PP
+The first time \fBpredict\-on\fP is used, it creates several additional
+widget functions:
+.PP
+.PD 0
+.TP
+\fBdelete\-backward\-and\-predict\fP
+Replaces the \fBbackward\-delete\-char\fP
+widget\&.  You do not need to bind this yourself\&.
+.TP
+\fBinsert\-and\-predict\fP
+Implements predictive typing by replacing the
+\fBself\-insert\fP widget\&.  You do not need to bind this yourself\&.
+.TP
+\fBpredict\-off\fP
+Turns off predictive typing\&.
+.PD
+.PP
+Although you \fBautoload\fP only the \fBpredict\-on\fP function, it is
+necessary to create a keybinding for \fBpredict\-off\fP as well\&.
+.PP
+.RS
+.nf
+\fBzle \-N predict\-on
+zle \-N predict\-off
+bindkey '^X^Z' predict\-on
+bindkey '^Z' predict\-off\fP
+.fi
+.RE
+.RE
+.TP
+\fBread\-from\-minibuffer\fP
+This is most useful when called as a function from inside a widget, but will
+work correctly as a widget in its own right\&.  It prompts for a value
+below the current command line; a value may be input using all of the
+standard zle operations (and not merely the restricted set available
+when executing, for example, \fBexecute\-named\-cmd\fP)\&.  The value is then
+returned to the calling function in the parameter \fB$REPLY\fP and the
+editing buffer restored to its previous state\&.  If the read was aborted
+by a keyboard break (typically \fB^G\fP), the function returns status 1
+and \fB$REPLY\fP is not set\&.
+.RS
+.PP
+If one argument is supplied to the function it is taken as a prompt,
+otherwise `\fB? \fP' is used\&.  If two arguments are supplied, they are the
+prompt and the initial value of \fB$LBUFFER\fP, and if a third argument is
+given it is the initial value of \fB$RBUFFER\fP\&.  This provides a default
+value and starting cursor placement\&.  Upon return the entire buffer is the
+value of \fB$REPLY\fP\&.
+.PP
+One option is available: `\fB\-k\fP \fInum\fP' specifies that \fInum\fP
+characters are to be read instead of a whole line\&.  The line editor is not
+invoked recursively in this case, so depending on the terminal settings
+the input may not be visible, and only the input keys are placed in
+\fB$REPLY\fP, not the entire buffer\&.  Note that unlike the \fBread\fP builtin
+\fInum\fP must be given; there is no default\&.
+.PP
+The name is a slight misnomer, as in fact the shell's own minibuffer is
+not used\&.  Hence it is still possible to call \fBexecuted\-named\-cmd\fP and
+similar functions while reading a value\&.
+.RE
+.TP
+\fBreplace\-string\fP, \fBreplace\-pattern\fP
+The function \fBreplace\-string\fP implements two widgets\&.
+If defined under the same name as the function, it prompts for two
+strings; the first (source) string will be replaced by the second
+everywhere it occurs in the line editing buffer\&.
+.RS
+.PP
+If the widget name contains the word `\fBpattern\fP', for example by
+defining the widget using the command `\fBzle \-N replace\-pattern
+replace\-string\fP', then the replacement is done by pattern matching\&.  All
+zsh extended globbing patterns can be used in the source string; note
+that unlike filename generation the pattern does not need to match an
+entire word, nor do glob qualifiers have any effect\&.  In addition, the
+replacement string can contain parameter or command substitutions\&.
+Furthermore, a `\fB&\fP' in the replacement string will be replaced with
+the matched source string, and a backquoted digit `\fB\e\fP\fIN\fP' will be
+replaced by the \fIN\fPth parenthesised expression matched\&.  The form
+`\fB\e{\fP\fIN\fP\fB}\fP' may be used to protect the digit from following
+digits\&.
+.PP
+For example, starting from the line:
+.PP
+.RS
+.nf
+\fBprint This line contains fan and fond\fP
+.fi
+.RE
+.PP
+and invoking \fBreplace\-pattern\fP with the source string `\fBf(?)n\fP' and
+the replacment string `\fBc\e1r\fP' produces the not very useful line:
+.PP
+.RS
+.nf
+\fBprint This line contains car and cord\fP
+.fi
+.RE
+.PP
+The range of the replacement string can be limited by using the
+\fBnarrow\-to\-region\-invisible\fP widget\&.  One limitation of the current
+version is that \fBundo\fP will cycle through changes to the replacement
+and source strings before undoing the replacement itself\&.
+.RE
+.TP
+\fBsmart\-insert\-last\-word\fP
+This function may replace the \fBinsert\-last\-word\fP widget, like so:
+.RS
+.PP
+.RS
+.nf
+\fBzle \-N insert\-last\-word smart\-insert\-last\-word\fP
+.fi
+.RE
+.PP
+With a numeric prefix, or when passed command line arguments in a call
+from another widget, it behaves like \fBinsert\-last\-word\fP, except that
+words in comments are ignored when \fBINTERACTIVE_COMMENTS\fP is set\&.
+.PP
+Otherwise, the rightmost ``interesting'' word from the previous command is
+found and inserted\&.  The default definition of ``interesting'' is that the
+word contains at least one alphabetic character, slash, or backslash\&.
+This definition may be overridden by use of the \fBmatch\fP style\&.  The
+context used to look up the style is the widget name, so usually the
+context is \fB:insert\-last\-word\fP\&.  However, you can bind this function to
+different widgets to use different patterns:
+.PP
+.RS
+.nf
+\fBzle \-N insert\-last\-assignment smart\-insert\-last\-word
+zstyle :insert\-last\-assignment match '[[:alpha:]][][[:alnum:]]#=*'
+bindkey '\ee=' insert\-last\-assignment\fP
+.fi
+.RE
+.RE
+.RE
+.PP
+.SS "Styles"
+.PP
+The behavior of several of the above widgets can be controlled by the use
+of the \fBzstyle\fP mechanism\&.  In particular, widgets that interact with
+the completion system pass along their context to any completions that
+they invoke\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBbreak\-keys\fP
+This style is used by the \fBincremental\-complete\-word\fP widget\&. Its value
+should be a pattern, and all keys matching this pattern will cause the
+widget to stop incremental completion without the key having any further
+effect\&. Like all styles used directly by
+\fBincremental\-complete\-word\fP, this style is looked up using the
+context `\fB:incremental\fP'\&.
+.TP
+\fBcompleter\fP
+The \fBincremental\-complete\-word\fP and \fBinsert\-and\-predict\fP widgets set
+up their top\-level context name before calling completion\&.  This allows
+one to define different sets of completer functions for normal completion
+and for these widgets\&.  For example, to use completion, approximation and
+correction for normal completion, completion and correction for
+incremental completion and only completion for prediction one could use:
+.RS
+.PP
+.RS
+.nf
+\fBzstyle ':completion:*' completer \e 
+        _complete _correct _approximate
+zstyle ':completion:incremental:*' completer \e 
+        _complete _correct
+zstyle ':completion:predict:*' completer \e 
+        _complete\fP
+.fi
+.RE
+.PP
+It is a good idea to restrict the completers used in prediction, because
+they may be automatically invoked as you type\&.  The \fB_list\fP and
+\fB_menu\fP completers should never be used with prediction\&.  The
+\fB_approximate\fP, \fB_correct\fP, \fB_expand\fP, and \fB_match\fP completers may
+be used, but be aware that they may change characters anywhere in the word
+behind the cursor, so you need to watch carefully that the result is what
+you intended\&.
+.RE
+.TP
+\fBcursor\fP
+The \fBinsert\-and\-predict\fP widget uses this style, in the context
+`\fB:predict\fP', to decide where to place the cursor after completion has
+been tried\&.  Values are:
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fBcomplete\fP
+The cursor is left where it was when completion finished, but only if
+it is after a character equal to the one just inserted by the user\&.  If 
+it is after another character, this value is the same as `\fBkey\fP'\&.
+.TP
+\fBkey\fP
+The cursor is left
+after the \fIn\fPth occurrence of the character just inserted, where
+\fIn\fP is the number of times that character appeared in the word
+before completion was attempted\&.  In short, this has the effect of
+leaving the cursor after the character just typed even if the
+completion code found out that no other characters need to be inserted 
+at that position\&.
+.PP
+Any other value for this style unconditionally leaves the cursor at the
+position where the completion code left it\&.
+.RE
+.TP
+\fBlist\fP
+When using the \fBincremental\-complete\-word\fP widget, this style says
+if the matches should be listed on every key press (if they fit on the 
+screen)\&.  Use the context prefix `\fB:completion:incremental\fP'\&.
+.RS
+.PP
+The \fBinsert\-and\-predict\fP widget uses this style to decide if the
+completion should be shown even if there is only one possible completion\&.
+This is done if the value of this style is the string \fBalways\fP\&.  In this
+case the context is `\fB:predict\fP' (\fInot\fP `\fB:completion:predict\fP')\&.
+.RE
+.TP
+\fBmatch\fP
+This style is used by \fBsmart\-insert\-last\-word\fP to provide a pattern
+(using full \fBEXTENDED_GLOB\fP syntax) that matches an interesting word\&.
+The context is the name of the widget to which \fBsmart\-insert\-last\-word\fP
+is bound (see above)\&.  The default behavior of \fBsmart\-insert\-last\-word\fP
+is equivalent to:
+.RS
+.PP
+.RS
+.nf
+\fBzstyle :insert\-last\-word match '*[[:alpha:]/\e\e]*'\fP
+.fi
+.RE
+.PP
+However, you might want to include words that contain spaces:
+.PP
+.RS
+.nf
+\fBzstyle :insert\-last\-word match '*[[:alpha:][:space:]/\e\e]*'\fP
+.fi
+.RE
+.PP
+Or include numbers as long as the word is at least two characters long:
+.PP
+.RS
+.nf
+\fBzstyle :insert\-last\-word match '*([[:digit:]]?|[[:alpha:]/\e\e])*'\fP
+.fi
+.RE
+.PP
+The above example causes redirections like "2>" to be included\&.
+.RE
+.TP
+\fBprompt\fP
+The \fBincremental\-complete\-word\fP widget shows the value of this
+style in the status line during incremental completion\&.  The string
+value may contain any of the following substrings in the manner of
+the \fBPS1\fP and other prompt parameters:
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fB%c\fP
+Replaced by the name of the completer function that generated the
+matches (without the leading underscore)\&.
+.TP
+\fB%l\fP
+When the \fBlist\fP style is set,
+replaced by `\fB\&.\&.\&.\fP' if the list of matches is too long to fit on the
+screen and with an empty string otherwise\&.  If the \fBlist\fP style is
+`false' or not set, `\fB%l\fP' is always removed\&.
+.TP
+\fB%n\fP
+Replaced by the number of matches generated\&.
+.TP
+\fB%s\fP
+Replaced by `\fB\-no match\-\fP', `\fB\-no prefix\-\fP', or an empty string
+if there is no completion matching the word on the line, if the
+matches have no common prefix different from the word on the line, or
+if there is such a common prefix, respectively\&.
+.TP
+\fB%u\fP
+Replaced by the unambiguous part of all matches, if there
+is any, and if it is different from the word on the line\&.
+.PP
+Like `\fBbreak\-keys\fP', this uses the `\fB:incremental\fP' context\&.
+.RE
+.TP
+\fBstop\-keys\fP
+This style is used by the \fBincremental\-complete\-word\fP widget\&.  Its value
+is treated similarly to the one for the \fBbreak\-keys\fP style (and uses 
+the same context: `\fB:incremental\fP')\&.  However, in
+this case all keys matching the pattern given as its value will stop
+incremental completion and will then execute their usual function\&.
+.TP
+\fBtoggle\fP
+This boolean style is used by \fBpredict\-on\fP and its related widgets in
+the context `\fB:predict\fP'\&.  If set to one of the standard `true' values,
+predictive typing is automatically toggled off in situations where it is
+unlikely to be useful, such as when editing a multi\-line buffer or after
+moving into the middle of a line and then deleting a character\&.  The
+default is to leave prediction turned on until an explicit call to
+\fBpredict\-off\fP\&.
+.TP
+\fBverbose\fP
+This boolean style is used by \fBpredict\-on\fP and its related widgets in
+the context `\fB:predict\fP'\&.  If set to one of the standard `true' values,
+these widgets display a message below the prompt when the predictive state
+is toggled\&.  This is most useful in combination with the \fBtoggle\fP style\&.
+The default does not display these messages\&.
+.TP
+\fBwidget\fP
+This style is similar to the \fBcommand\fP style: For widget functions that
+use \fBzle\fP to call other widgets, this style can sometimes be used to
+override the widget which is called\&.  The context for this style is the
+name of the calling widget (\fInot\fP the name of the calling function,
+because one function may be bound to multiple widget names)\&.
+.RS
+.PP
+.RS
+.nf
+\fBzstyle :copy\-earlier\-word widget smart\-insert\-last\-word\fP
+.fi
+.RE
+.PP
+Check the documentation for the calling widget or function to determine
+whether the \fBwidget\fP style is used\&.
+.RE
+.RE
+.PP
+.SH "MIME FUNCTIONS"
+.PP
+Three functions are available to provide handling of files recognised by
+extension, for example to dispatch a file \fBtext\&.ps\fP when executed as a
+command to an appropriate viewer\&.
+.PP
+.PD 0
+.TP
+.PD 0
+\fBzsh\-mime\-setup [\-flv]\fP
+.TP
+.PD
+\fBzsh\-mime\-handler\fP
+These two functions use the files \fB~/\&.mime\&.types\fP and \fB/etc/mime\&.types\fP,
+which associate types and extensions, as well as \fB~/\&.mailcap\fP and
+\fB/etc/mailcap\fP files, which associate types and the programs that
+handle them\&.  These are provided on many systems with the Multimedia
+Internet Mail Extensions\&.
+.RS
+.PP
+To enable the system, the function \fBzsh\-mime\-setup\fP should be
+autoloaded and run\&.  This allows files with extensions to be treated
+as executable; such files be completed by the function completion system\&.
+The function \fBzsh\-mime\-handler\fP should not need to be called by the
+user\&.
+.PP
+The system works by setting up suffix aliases with `\fBalias \-s\fP'\&.
+Suffix aliases already installed by the user will not be overwritten\&.
+.PP
+Repeated calls to \fBzsh\-mime\-setup\fP do not override the existing
+mapping between suffixes and executable files unless the option \fB\-f\fP
+is given\&.  Note, however, that this does not override existing suffix
+aliases assigned to handlers other than \fBzsh\-mime\-handler\fP\&.
+Calling \fBzsh\-mime\-setup\fP with the option \fB\-l\fP lists the existing
+mapping without altering it\&.  Calling \fBzsh\-mime\-setup\fP with the option
+\fB\-v\fP causes verbose output to be shown during the setup operation\&.
+.PP
+The system respects the \fBmailcap\fP flags \fBneedsterminal\fP and
+\fBcopiousoutput\fP, see \fImailcap\fP(4)\&.
+.PP
+The functions use the following styles, which are defined with the
+\fBzstyle\fP builtin command (see \fIzshmodules\fP(1))\&.  They should be defined
+before \fBzsh\-mime\-setup\fP is run\&.  The contexts used all
+start with \fB:mime:\fP, with additional components in some cases\&.
+It is recommended that a trailing \fB*\fP (suitably quoted) be appended
+to style patterns in case the system is extended in future\&.  Some
+examples are given below\&.
+.PD 0
+.TP
+.PD
+mime\-types
+A list of files in the format of \fB~/\&.mime\&.types\fP and
+\fB/etc/mime\&.types\fP to be read during setup, replacing the default list
+which consists of those two files\&.  The context is \fB:mime:\fP\&.
+A \fB+\fP in the list will be replaced by the default files\&.
+.TP
+mailcap
+A list of files in the format of \fB~/\&.mailcap\fP and
+\fB/etc/mailcap\fP to be read during setup, replacing the default list
+which consists of those two files\&.  The context is \fB:mime:\fP\&.
+A \fB+\fP in the list will be replaced by the default files\&.
+.TP
+handler
+Specifies a handler for a suffix; the suffix is given by the context as
+\fB:mime:\&.\fP\fIsuffix\fP\fB:\fP, and the format of the handler is exactly
+that in \fBmailcap\fP\&.  Note in particular the `\fB\&.\fP' and trailing colon
+to distinguish this use of the context\&.  This overrides any handler
+specified by the \fBmailcap\fP files\&.  If the handler requires a terminal,
+the \fBflags\fP style should be set to include the word \fBneedsterminal\fP,
+or if the output is to be displayed through a pager (but not if the
+handler is itself a pager), it should include \fBcopiousoutput\fP\&.
+.TP
+flags
+Defines flags to go with a handler; the context is as for the
+\fBhandler\fP style, and the format is as for the flags in \fBmailcap\fP\&.
+.TP
+pager
+If set, will be used instead of \fB$PAGER\fP or \fBmore\fP to handle
+suffixes where the \fBcopiousoutput\fP flag is set\&.  The context is
+as for \fBhandler\fP, i\&.e\&. \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP for handling
+a file with the given \fIsuffix\fP\&.
+.PP
+Examples:
+.PP
+.RS
+.nf
+\fBzstyle ':mime:*' mailcap ~/\&.mailcap /usr/local/etc/mailcap
+zstyle ':mime:\&.txt' handler less %s
+zstyle ':mime:\&.txt' flags needsterminal\fP
+.fi
+.RE
+.PP
+When \fBzsh\-mime\-setup\fP is subsequently run, it will look for
+\fBmailcap\fP entries in the two files given\&.  Files of suffix \fB\&.txt\fP
+will be handled by running `\fBless\fP \fIfile\&.txt\fP'\&.  The flag
+\fBneedsterminal\fP is set to show that this program must run attached to a
+terminal\&.
+.PP
+As there are several steps to dispatching a command, the following
+should be checked if attempting to execute a file by extension
+\fB\&.\fP\fIext\fP does not have the expected effect\&.
+starteit()
+eit()(
+The command `\fBalias \-s\fP \fIext\fP' should show
+`\fBps=zsh\-mime\-handler\fP'\&.  If it shows something else, another suffix
+alias was already installed and was not overwritten\&.  If it shows
+nothing, no handler was installed:  this is most likely because no
+handler was found in the \fB\&.mime\&.types\fP and \fBmailcap\fP combination for
+\fB\&.ext\fP files\&.  In that case, appropriate handling should be added to
+\fB~/\&.mime\&.types\fP and \fBmailcap\fP\&.
+)
+eit()(
+If the extension is handled by \fBzsh\-mime\-handler\fP but the file is
+not opened correctly, either the handler defined for the type is
+incorrect, or the flags associated with it are in appropriate\&.  Running
+\fBzsh\-mime\-setup \-l\fP will show the handler and, if there are any, the
+flags\&.  A \fB%s\fP in the handler is replaced by the file (suitably quoted
+if necessary)\&.  Check that the handler program listed lists and can
+be run in the way shown\&.  Also check that the flags \fBneedsterminal\fP or
+\fBcopiousoutput\fP are set if the handler needs to be run under a
+terminal; the second flag is used if the output should be sent to a pager\&.
+An example of a suitable \fBmailcap\fP entry for such a program is:
+.PP
+.RS
+.nf
+\fBtext/html; /usr/bin/lynx '%s'; needsterminal\fP
+.fi
+.RE
+)
+endeit()
+.RE
+.TP
+\fBpick\-web\-browser\fP
+This function is separate from the two MIME functions described above
+and can be assigned directly to a suffix:
+.RS
+.PP
+.RS
+.nf
+\fBautoload \-U pick\-web\-browser
+alias \-s html=pick\-web\-browser\fP
+.fi
+.RE
+.PP
+It is provided as an intelligent front end to dispatch a web browser\&.
+It will check if an X Windows display is available, and if so
+if there is already a browser running which can accept a remote
+connection\&.  In that case, the file will be displayed in that browser;
+you should check explicitly if it has appeared in the running browser's
+window\&.  Otherwise, it will start a new browser according to a builtin
+set of preferences\&.
+.PP
+Alternatively, \fBpick\-web\-browser\fP can be run as a zsh script\&.
+.PP
+Two styles are available to customize the choice of browsers:
+\fBx\-browsers\fP when running under the X Windows System, and
+\fBtty\-browsers\fP otherwise\&.  These are arrays in decreasing order
+of preference consiting of the command name under which to start the
+browser\&.  They are looked up in the context \fB:mime:\fP (which may
+be extended in future, so appending `\fB*\fP' is recommended)\&.  For
+example,
+.PP
+.RS
+.nf
+\fBzstyle ':mime:*' x\-browsers opera konqueror netscape\fP
+.fi
+.RE
+.PP
+specifies that \fBpick\-web\-browser\fP should first look for a runing
+instance of Opera, Konqueror or Netscape, in that order, and if it
+fails to find any should attempt to start Opera\&.
+.RE
+.RE
+.PP
+.SH "OTHER FUNCTIONS"
+.PP
+There are a large number of helpful functions in the \fBFunctions/Misc\fP
+directory of the zsh distribution\&.  Most are very simple and do not
+require documentation here, but a few are worthy of special mention\&.
+.PP
+.SS "Descriptions"
+.PP
+.PD 0
+.TP
+.PD
+\fBcolors\fP
+This function initializes several associative arrays to map color names to
+(and from) the ANSI standard eight\-color terminal codes\&.  These are used
+by the prompt theme system (see above)\&.  You seldom should need to run
+\fBcolors\fP more than once\&.
+.RS
+.PP
+The eight base colors are: black, red, green, yellow, blue, magenta, cyan,
+and white\&.  Each of these has codes for foreground and background\&.  In
+addition there are eight intensity attributes: bold, faint, standout,
+underline, blink, reverse, and conceal\&.  Finally, there are six codes used
+to negate attributes: none (reset all attributes to the defaults), normal
+(neither bold nor faint), no\-standout, no\-underline, no\-blink, and
+no\-reverse\&.
+.PP
+Some terminals do not support all combinations of colors and intensities\&.
+.PP
+The associative arrays are:
+.PP
+.PD 0
+.TP
+.PD 0
+color
+.TP
+.PD
+colour
+Map all the color names to their integer codes, and integer codes to the
+color names\&.  The eight base names map to the foreground color codes, as
+do names prefixed with `\fBfg\-\fP', such as `\fBfg\-red\fP'\&.  Names prefixed
+with `\fBbg\-\fP', such as `\fBbg\-blue\fP', refer to the background codes\&.  The
+reverse mapping from code to color yields base name for foreground codes
+and the \fBbg\-\fP form for backgrounds\&.
+.RS
+.PP
+Although it is a misnomer to call them `colors', these arrays also map the
+other fourteen attributes from names to codes and codes to names\&.
+.RE
+.TP
+.PD 0
+fg
+.TP
+.PD 0
+fg_bold
+.TP
+.PD
+fg_no_bold
+Map the eight basic color names to ANSI terminal escape sequences that set
+the corresponding foreground text properties\&.  The \fBfg\fP sequences change
+the color without changing the eight intensity attributes\&.
+.TP
+.PD 0
+bg
+.TP
+.PD 0
+bg_bold
+.TP
+.PD
+bg_no_bold
+Map the eight basic color names to ANSI terminal escape sequences that set
+the corresponding background properties\&.  The \fBbg\fP sequences change the
+color without changing the eight intensity attributes\&.
+.PP
+In addition, the scalar parameters \fBreset_color\fP and \fBbold_color\fP are
+set to the ANSI terminal escapes that turn off all attributes and turn on
+bold intensity, respectively\&.
+.RE
+.TP
+\fBfned\fP \fIname\fP
+Same as \fBzed \-f\fP\&.  This function does not appear in the zsh
+distribution, but can be created by linking \fBzed\fP to the name \fBfned\fP
+in some directory in your \fBfpath\fP\&.
+.TP
+\fBis\-at\-least\fP \fIneeded\fP [ \fIpresent\fP ]
+Perform a greater\-than\-or\-equal\-to comparison of two strings having the
+format of a zsh version number; that is, a string of numbers and text with
+segments separated by dots or dashes\&.  If the \fIpresent\fP string is not
+provided, \fB$ZSH_VERSION\fP is used\&.  Segments are paired left\-to\-right in
+the two strings with leading non\-number parts ignored\&.  If one string has
+fewer segments than the other, the missing segments are considered zero\&.
+.RS
+.PP
+This is useful in startup files to set options and other state that are
+not available in all versions of zsh\&.
+.PP
+.RS
+.nf
+\fBis\-at\-least 3\&.1\&.6\-15 && setopt NO_GLOBAL_RCS
+is\-at\-least 3\&.1\&.0 && setopt HIST_REDUCE_BLANKS
+is\-at\-least 2\&.6\-17 || print "You can't use is\-at\-least here\&."\fP
+.fi
+.RE
+.RE
+.TP
+\fBnslookup\fP [ \fIarg\fP \&.\&.\&. ]
+This wrapper function for the \fBnslookup\fP command requires the
+\fBzsh/zpty\fP module (see
+\fIzshmodules\fP(1))\&.  It behaves exactly like the standard \fBnslookup\fP
+except that it provides customizable prompts (including a right\-side
+prompt) and completion of nslookup commands, host names, etc\&. (if you use
+the function\-based completion system)\&.  Completion styles may be set with
+the context prefix `\fB:completion:nslookup\fP'\&.
+.RS
+.PP
+See also the \fBpager\fP, \fBprompt\fP and \fBrprompt\fP styles below\&.
+.RE
+.TP
+\fBrun\-help\fP
+See `Accessing On\-Line Help'
+above\&.
+.TP
+\fBtetris\fP
+Zsh was once accused of not being as complete as Emacs,
+because it lacked a Tetris game\&.  This function was written to
+refute this vicious slander\&.
+.RS
+.PP
+This function must be used as a ZLE widget:
+.PP
+.RS
+.nf
+\fBautoload \-U tetris
+zle \-N tetris
+bindkey \fIkeys\fP tetris\fP
+.fi
+.RE
+.PP
+To start a game, execute the widget by typing the \fIkeys\fP\&.  Whatever command
+line you were editing disappears temporarily, and your keymap is also
+temporarily replaced by the Tetris control keys\&.  The previous editor state
+is restored when you quit the game (by pressing `\fBq\fP') or when you lose\&.
+.PP
+If you quit in the middle of a game, the next invocation of the \fBtetris\fP
+widget will continue where you left off\&.  If you lost, it will start a new
+game\&.
+.RE
+.TP
+\fBzargs\fP [ \fIoption\fP \&.\&.\&. \fB\-\fP\fB\-\fP ] [ \fIinput\fP \&.\&.\&. ] [ \fB\-\fP\fB\-\fP \fIcommand\fP [ \fIarg\fP \&.\&.\&. ] ]
+This function works like GNU xargs, except that instead of reading lines
+of arguments from the standard input, it takes them from the command line\&.
+This is useful because zsh, especially with recursive glob operators,
+often can construct a command line for a shell function that is longer
+than can be accepted by an external command\&.
+.RS
+.PP
+The \fIoption\fP list represents options of the \fBzargs\fP command itself,
+which are the same as those of \fBxargs\fP\&.  The \fIinput\fP list is the
+collection of strings (often file names) that become the arguments of the
+\fBcommand\fP, analogous to the standard input of \fBxargs\fP\&.  Finally, the
+\fIarg\fP list consists of those arguments (usually options) that are
+passed to the \fIcommand\fP each time it runs\&.  The \fIarg\fP list precedes
+the elements from the \fBinput\fP list in each run\&.  If no \fIcommand\fP is
+provided, then no \fIarg\fP list may be provided, and in that event the
+default command is `\fBprint\fP' with arguments `\fB\-r \-\fP\fB\-\fP'\&.
+.PP
+For example, to get a long \fBls\fP listing of all plain files in the
+current directory or its subdirectories:
+.PP
+.RS
+.nf
+\fBautoload \-U zargs
+zargs \-\- **/*(\&.) \-\- ls \-l\fP
+.fi
+.RE
+.PP
+Note that `\fB\-\fP\fB\-\fP' is used both to mark the end of the \fIoption\fP
+list and to mark the end of the \fIinput\fP list, so it must appear twice
+whenever the \fIinput\fP list may be empty\&.  If there is guaranteed to be
+at least one \fIinput\fP and the first \fIinput\fP does not begin with a
+`\fB\-\fP', then the first `\fB\-\fP\fB\-\fP' may be omitted\&.
+.PP
+In the event that the string `\fB\-\fP\fB\-\fP' is or may be an \fIinput\fP, the
+\fB\-e\fP option may be used to change the end\-of\-inputs marker\&.  Note that
+this does \fInot\fP change the end\-of\-options marker\&.  For example, to use
+`\fB\&.\&.\fP' as the marker:
+.PP
+.RS
+.nf
+\fBzargs \-e\&.\&. \-\- **/*(\&.) \&.\&. ls \-l\fP
+.fi
+.RE
+.PP
+This is a good choice in that example because no plain file can be named
+`\fB\&.\&.\fP', but the best end\-marker depends on the circumstances\&.
+.PP
+For details of the other \fBzargs\fP options, see \fIxargs\fP(1) or run
+\fBzargs\fP with the \fB\-\fP\fB\-help\fP option\&.
+.RE
+.TP
+\fBzcalc\fP [ \fIexpression\fP \&.\&.\&. ]
+A reasonably powerful calculator based on zsh's arithmetic evaluation
+facility\&.  The syntax is similar to that of formulae in most programming
+languages; see
+the section `Arithmetic Evaluation' in \fIzshmisc\fP(1) for details\&.  The mathematical
+library \fBzsh/mathfunc\fP will be loaded if it is available; see
+the section `The zsh/mathfunc Module' in \fIzshmodules\fP(1)\&.  The mathematical functions
+correspond to the raw system libraries, so trigonometric functions are
+evaluated using radians, and so on\&.
+.RS
+.PP
+Each line typed is evaluated as an expression\&.  The prompt shows a number,
+which corresponds to a positional parameter where the result of that
+calculation is stored\&.  For example, the result of the calculation on the
+line preceded by `\fB4> \fP' is available as \fB$4\fP\&.  Full command line
+editing, including the history of previous calculations, is available; the
+history is saved in the file \fB~/\&.zcalc_history\fP\&.  To exit, enter a blank
+line or type `\fBq\fP' on its own\&.
+.PP
+If arguments are given to \fBzcalc\fP on start up, they are used to prime the
+first few positional parameters\&.  A visual indication of this is given when
+the calculator starts\&.
+.PP
+The constants \fBPI\fP (3\&.14159\&.\&.\&.) and \fBE\fP (2\&.71828\&.\&.\&.) are provided\&.
+Parameter assignment is possible, but note that all parameters will be put
+into the global namespace\&.
+.PP
+An extra facility is provided for changing the default output base\&.  Use,
+for example, `\fB[#16]\fP' to display hexadecimal output preceded by an
+indication of the base, or `\fB[##16]\fP' just to display the raw number in
+the given base\&.  Bases themselves are always specified in decimal\&.
+`\fB[#]\fP' restores the normal output format\&.
+.PP
+The output base can be initialised by passing the option `\fB\-#\fP\fIbase\fP',
+for example `\fBzcalc \-#16\fP' (the `\fB#\fP' may have to be quoted, depending
+on the globbing options set)\&.
+.PP
+The prompt is configurable via the parameter \fBZCALCPROMPT\fP, which
+undergoes standard prompt expansion\&.  The index of the current entry is
+stored locally in the first element of the array \fBpsvar\fP, which can be
+referred to in \fBZCALCPROMPT\fP as `\fB%1v\fP'\&.  The default prompt is
+`\fB%1v> \fP'\&.
+.PP
+See the comments in the function for a few extra tips\&.
+.RE
+.TP
+.PD 0
+\fBzed\fP [ \fB\-f\fP ] \fIname\fP
+.TP
+.PD
+\fBzed \-b\fP
+This function uses the ZLE editor to edit a file or function\&.
+.RS
+.PP
+Only one \fIname\fP argument is allowed\&.
+If the \fB\-f\fP option is given, the name is taken to be that of
+a function; if the function is marked for autoloading, \fBzed\fP searches
+for it in the \fBfpath\fP and loads it\&.  Note that functions edited this way
+are installed into the current shell, but \fInot\fP written back to the
+autoload file\&.
+.PP
+Without \fB\-f\fP, \fIname\fP is the path name of the file to edit, which need
+not exist; it is created on write, if necessary\&.
+.PP
+While editing, the function sets the main keymap to \fBzed\fP and the
+vi command keymap to \fBzed\-vicmd\fP\&.  These will be copied from the existing
+\fBmain\fP and \fBvicmd\fP keymaps if they do not exist the first time \fBzed\fP
+is run\&.  They can be used to provide special key bindings used only in zed\&.
+.PP
+If it creates the keymap, \fBzed\fP rebinds the return key to insert a line
+break and `\fB^X^W\fP' to accept the edit in the \fBzed\fP keymap, and binds
+`\fBZZ\fP' to accept the edit in the \fBzed\-vicmd\fP keymap\&.
+.PP
+The bindings alone can be installed by running `\fBzed \-b\fP'\&.  This is
+suitable for putting into a startup file\&.  Note that, if rerun,
+this will overwrite the existing \fBzed\fP and \fBzed\-vicmd\fP keymaps\&.
+.PP
+Completion is available, and styles may be set with the context prefix
+`\fB:completion:zed\fP'\&.
+.PP
+A zle widget \fBzed\-set\-file\-name\fP is available\&.  This can be called by
+name from within zed using `\fB\eex zed\-set\-file\-name\fP' (note, however, that
+because of zed's rebindings you will have to type \fB^j\fP at the end instead
+of the return key), or can be bound to a key in either of the \fBzed\fP or
+\fBzed\-vicmd\fP keymaps after `\fBzed \-b\fP' has been run\&.  When the widget is
+called, it prompts for a new name for the file being edited\&.  When zed
+exits the file will be written under that name and the original file will
+be left alone\&.  The widget has no effect with `\fBzed \-f\fP'\&.
+.PP
+While \fBzed\-set\-file\-name\fP is running, zed uses the keymap
+\fBzed\-normal\-keymap\fP, which is linked from the main keymap in effect
+at the time zed initialised its bindings\&.  (This is to make the return key
+operate normally\&.)  The result is that if the main keymap has been changed,
+the widget won't notice\&.  This is not a concern for most users\&.
+.RE
+.TP
+.PD 0
+\fBzcp\fP [ \fB\-finqQvwW\fP ] \fIsrcpat\fP \fIdest\fP
+.TP
+.PD
+\fBzln\fP [ \fB\-finqQsvwW\fP ] \fIsrcpat\fP \fIdest\fP
+Same as \fBzmv \-C\fP and \fBzmv \-L\fP, respectively\&.  These functions do not
+appear in the zsh distribution, but can be created by linking \fBzmv\fP to
+the names \fBzcp\fP and \fBzln\fP in some directory in your \fBfpath\fP\&.
+.TP
+\fBzkbd\fP
+See `Keyboard Definition'
+above\&.
+.TP
+\fBzmv\fP [ \fB\-finqQsvwW\fP ] [ \-C | \-L | \-M | \-p \fIprogram\fP ] [ \-o \fIoptstring\fP ] \fIsrcpat\fP \fIdest\fP 
+Move (usually, rename) files matching the pattern \fIsrcpat\fP to
+corresponding files having names of the form given by \fIdest\fP, where
+\fIsrcpat\fP contains parentheses surrounding patterns which will be
+replaced in turn by $1, $2, \&.\&.\&. in \fIdest\fP\&.  For example,
+.RS
+.PP
+.RS
+.nf
+\fBzmv '(*)\&.lis' '$1\&.txt'\fP
+.fi
+.RE
+.PP
+renames `\fBfoo\&.lis\fP' to `\fBfoo\&.txt\fP', `\fBmy\&.old\&.stuff\&.lis\fP' to
+`\fBmy\&.old\&.stuff\&.txt\fP', and so on\&.
+.PP
+The pattern is always treated as an \fBEXTENDED_GLOB\fP pattern\&.  Any file
+whose name is not changed by the substitution is simply ignored\&.  Any
+error (a substitution resulted in an empty string, two substitutions gave
+the same result, the destination was an existing regular file and \fB\-f\fP
+was not given) causes the entire function to abort without doing anything\&.
+.PP
+Options:
+.PP
+.PD 0
+.TP
+\fB\-f\fP
+Force overwriting of destination files\&.  Not currently
+passed down to the \fBmv\fP/\fBcp\fP/\fBln\fP command due to vagaries of
+implementations (but you can use \fB\-o\-f\fP to do that)\&.
+.TP
+\fB\-i\fP
+Interactive: show each line to be executed and ask the user
+whether to execute it\&.  `Y' or `y' will execute it, anything else will
+skip it\&.  Note that you just need to type one character\&.
+.TP
+\fB\-n\fP
+No execution: print what would happen, but don't do it\&.
+.TP
+\fB\-q\fP
+Turn bare glob qualifiers off: now assumed by default, so
+this has no effect\&.
+.TP
+\fB\-Q\fP
+Force bare glob qualifiers on\&.  Don't turn this on unless
+you are actually using glob qualifiers in a pattern\&.
+.TP
+\fB\-s\fP
+Symbolic, passed down to \fBln\fP; only works with \fB\-L\fP\&.
+.TP
+\fB\-v\fP
+Verbose: print each command as it's being executed\&.
+.TP
+\fB\-w\fP
+Pick out wildcard parts of the pattern, as described above,
+and implicitly add parentheses for referring to them\&.
+.TP
+\fB\-W\fP
+Just like \fB\-w\fP, with the addition of turning wildcards in
+the replacement pattern into sequential ${1} \&.\&. ${N} references\&.
+.TP
+\fB\-C\fP
+.TP
+\fB\-L\fP
+.TP
+\fB\-M\fP
+Force \fBcp\fP, \fBln\fP or \fBmv\fP, respectively, regardless of
+the name of the function\&.
+.TP
+\fB\-p\fP \fIprogram\fP
+Call \fIprogram\fP instead of \fBcp\fP, \fBln\fP or
+\fBmv\fP\&.  Whatever it does, it should at least understand the form
+`\fIprogram\fP \fB\-\fP\fB\-\fP \fIoldname\fP \fInewname\fP'
+where \fIoldname\fP and \fInewname\fP are filenames generated by \fBzmv\fP\&.
+.TP
+\fB\-o\fP \fIoptstring\fP
+The \fIoptstring\fP is split into words and
+passed down verbatim to the \fBcp\fP, \fBln\fP or \fBmv\fP command called to
+perform the work\&.  It should probably begin with a `\fB\-\fP'\&.
+.PD
+.PP
+For more complete examples and other implementation details, see the
+\fBzmv\fP source file, usually located in one of the directories named in
+your \fBfpath\fP, or in \fBFunctions/Misc/zmv\fP in the zsh distribution\&.
+.RE
+.TP
+\fBzrecompile\fP
+See `Recompiling Functions'
+above\&.
+.TP
+\fBzstyle+\fP \fIcontext\fP \fIstyle\fP \fIvalue\fP [ + \fIsubcontext\fP \fIstyle\fP \fIvalue\fP \&.\&.\&. ]
+This makes defining styles a bit simpler by using a single `\fB+\fP' as a
+special token that allows you to append a context name to the previously
+used context name\&.  Like this:
+.RS
+.PP
+.RS
+.nf
+\fBzstyle+ ':foo:bar' style1 value1 \e 
+      + ':baz'     style2 value2 \e 
+      + ':frob'    style3 value3\fP
+.fi
+.RE
+.PP
+This defines `style1' with `value1' for the context \fB:foo:bar\fP as usual,
+but it also defines `style2' with `value2' for the context
+\fB:foo:bar:baz\fP and `style3' with `value3' for \fB:foo:bar:frob\fP\&.  Any
+\fIsubcontext\fP may be the empty string to re\-use the first context
+unchanged\&.
+.RE
+.RE
+.PP
+.SS "Styles"
+.PP
+.PD 0
+.TP
+.PD
+\fBinsert\-tab\fP
+The \fBzed\fP function \fIsets\fP this style in context `\fB:completion:zed:*\fP'
+to turn off completion when \fBTAB\fP is typed at the beginning of a line\&.
+You may override this by setting your own value for this context and style\&.
+.TP
+\fBpager\fP
+The \fBnslookup\fP function looks up this style in the context
+`\fB:nslookup\fP' to determine the program used to display output that does
+not fit on a single screen\&.
+.TP
+.PD 0
+\fBprompt\fP
+.TP
+.PD
+\fBrprompt\fP
+The \fBnslookup\fP function looks up this style in the context
+`\fB:nslookup\fP' to set the prompt and the right\-side prompt, respectively\&.
+The usual expansions for the \fBPS1\fP and \fBRPS1\fP parameters may be used
+(see
+\fIzshmisc\fP(1))\&.
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshexpn.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshexpn.1
@@ -0,0 +1,1956 @@
+.TH "ZSHEXPN" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshexpn \- zsh expansion and substitution
+.\" Yodl file: Zsh/expn.yo
+.SH "DESCRIPTION"
+The following types of expansions are performed in the indicated order in
+five steps:
+.PP
+.PD 0
+.TP
+.PD
+\fIHistory Expansion\fP
+This is performed only in interactive shells\&.
+.TP
+\fIAlias Expansion\fP
+Aliases are expanded immediately before the command line is parsed as
+explained
+under Aliasing in \fIzshmisc\fP(1)\&.
+.TP
+.PD 0
+\fIProcess Substitution\fP
+.TP
+.PD 0
+\fIParameter Expansion\fP
+.TP
+.PD 0
+\fICommand Substitution\fP
+.TP
+.PD 0
+\fIArithmetic Expansion\fP
+.TP
+.PD
+\fIBrace Expansion\fP
+These five are performed in one step in left\-to\-right fashion\&.  After
+these expansions, all unquoted occurrences of the characters `\fB\e\fP',
+`\fB'\fP' and `\fB"\fP' are removed\&.
+.TP
+\fIFilename Expansion\fP
+If the \fBSH_FILE_EXPANSION\fP option is set, the order of expansion is
+modified for compatibility with \fBsh\fP and \fBksh\fP\&.  In that case
+\fIfilename expansion\fP is performed immediately after \fIalias expansion\fP,
+preceding the set of five expansions mentioned above\&.
+.TP
+\fIFilename Generation\fP
+This expansion, commonly referred to as \fBglobbing\fP, is always done last\&.
+.PP
+The following sections explain the types of expansion in detail\&.
+.PP
+.SH "HISTORY EXPANSION"
+History expansion allows you to use words from previous command
+lines in the command line you are typing\&.  This simplifies spelling
+corrections and the repetition of complicated commands or arguments\&.
+Immediately before execution, each command is saved in the history list,
+the size of which is controlled by the \fBHISTSIZE\fP parameter\&.  The one
+most recent command is always retained in any case\&.  Each saved command in
+the history list is called a history \fIevent\fP and is assigned a number,
+beginning with 1 (one) when the shell starts up\&.  The history number that
+you may see in your prompt (see
+Prompt Expansion in \fIzshmisc\fP(1)) is the number that is to be assigned to the \fInext\fP command\&.
+.PP
+.SS "Overview"
+A history expansion begins with the first character of the \fBhistchars\fP
+parameter, which is `\fB!\fP' by default, and may occur anywhere on the
+command line; history expansions do not nest\&.  The `\fB!\fP' can be escaped
+with `\fB\e\fP' or can be enclosed between a pair of single quotes (\fB''\fP)
+to suppress its special meaning\&.  Double quotes will \fInot\fP work for
+this\&.  Following this history character is an optional event designator
+(see the section `Event Designators') and then an optional word
+designator (the section `Word Designators'); if neither of these designators is
+present, no history expansion occurs\&.
+.PP
+Input lines containing history expansions are echoed after being expanded,
+but before any other expansions take place and before the command is
+executed\&.  It is this expanded form that is recorded as the history event
+for later references\&.
+.PP
+By default, a history reference with no event designator refers to the
+same event as any preceding history reference on that command line; if it
+is the only history reference in a command, it refers to the previous
+command\&.
+However, if the option \fBCSH_JUNKIE_HISTORY\fP is set, then every history
+reference with no event specification \fIalways\fP refers to the previous
+command\&.
+.PP
+For example, `\fB!\fP' is the event designator for the previous command, so
+`\fB!!:1\fP' always refers to the first word of the previous command, and
+`\fB!!$\fP' always refers to the last word of the previous command\&.  With
+\fBCSH_JUNKIE_HISTORY\fP set, then `\fB!:1\fP' and `\fB!$\fP' function in the
+same manner as `\fB!!:1\fP' and `\fB!!$\fP', respectively\&.  Conversely, if
+\fBCSH_JUNKIE_HISTORY\fP is unset, then `\fB!:1\fP' and `\fB!$\fP' refer to the
+first and last words, respectively, of the same event referenced by the
+nearest other history reference preceding them on the current command
+line, or to the previous command if there is no preceding reference\&.
+.PP
+The character sequence `\fB^\fP\fIfoo\fP\fB^\fP\fIbar\fP' (where `\fB^\fP' is
+actually the second character of the \fBhistchars\fP parameter)
+repeats the last command, replacing the string \fIfoo\fP with \fIbar\fP\&.
+More precisely, the sequence `\fB^\fP\fIfoo\fP\fB^\fP\fIbar\fP\fB^\fP' is
+synonymous with `\fB!!:s\fP\fB^\fP\fIfoo\fP\fB^\fP\fIbar\fP\fB^\fP', hence other
+modifiers (see the section `Modifiers') may follow the final `\fB^\fP'\&.
+.PP
+If the shell encounters the character sequence `\fB!"\fP'
+in the input, the history mechanism is temporarily disabled until
+the current list (see
+\fIzshmisc\fP(1)) is fully parsed\&.  The `\fB!"\fP' is removed from the input, and any
+subsequent `\fB!\fP' characters have no special significance\&.
+.PP
+A less convenient but more comprehensible form of command history support
+is provided by the \fBfc\fP builtin\&.
+.SS "Event Designators"
+An event designator is a reference to a command\-line entry in the history
+list\&.  In the list below, remember that the initial \fB`!'\fP in each item
+may be changed to another character by setting the \fBhistchars\fP
+parameter\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB!\fP
+Start a history expansion, except when followed by a blank, newline,
+`\fB=\fP' or `\fB(\fP'\&.  If followed immediately by a word designator
+(see the section `Word Designators'), this forms a history reference
+with no event designator (see the section `Overview')\&.
+.TP
+\fB!!\fP
+Refer to the previous command\&.
+By itself, this expansion
+repeats the previous command\&.
+.TP
+\fB!\fP\fIn\fP
+Refer to command\-line \fIn\fP\&.
+.TP
+\fB!\-\fP\fIn\fP
+Refer to the current command\-line minus \fIn\fP\&.
+.TP
+\fB!\fP\fIstr\fP
+Refer to the most recent command starting with \fIstr\fP\&.
+.TP
+\fB!?\fP\fIstr\fP[\fB?\fP]
+Refer to the most recent command containing \fIstr\fP\&.  The trailing
+`\fB?\fP' is necessary if this reference is to be followed by a modifier or
+followed by any text that is not to be considered part of \fIstr\fP\&.
+.TP
+\fB!#\fP
+Refer to the current command line typed in so far\&.  The line is
+treated as if it were complete up to and including the word before the
+one with the `\fB!#\fP' reference\&.
+.TP
+\fB!{\fP\&.\&.\&.\fB}\fP
+Insulate a history reference from adjacent characters (if necessary)\&.
+.SS "Word Designators"
+A word designator indicates which word or words of a given command line are
+to be included in a history reference\&.  A `\fB:\fP' usually
+separates the event specification from the word designator\&.
+It may be omitted only if the word designator begins with a
+`\fB^\fP', `\fB$\fP', `\fB*\fP', `\fB\-\fP' or `\fB%\fP'\&.
+Word designators include:
+.PP
+.PD 0
+.TP
+\fB0\fP
+The first input word (command)\&.
+.TP
+\fIn\fP
+The \fIn\fPth argument\&.
+.TP
+\fB^\fP
+The first argument\&.  That is, \fB1\fP\&.
+.TP
+\fB$\fP
+The last argument\&.
+.TP
+\fB%\fP
+The word matched by (the most recent) \fB?\fP\fIstr\fP search\&.
+.TP
+\fIx\fP\fB\-\fP\fIy\fP
+A range of words; \fIx\fP defaults to \fB0\fP\&.
+.TP
+\fB*\fP
+All the arguments, or a null value if there are none\&.
+.TP
+\fIx\fP\fB*\fP
+Abbreviates `\fIx\fP\fB\-$\fP'\&.
+.TP
+\fIx\fP\fB\-\fP
+Like `\fIx\fP\fB*\fP' but omitting word \fB$\fP\&.
+.PD
+.PP
+Note that a `\fB%\fP' word designator works only when used in one of
+`\fB!%\fP', `\fB!:%\fP' or `\fB!?\fP\fIstr\fP\fB?:%\fP', and only when used after a
+\fB!?\fP expansion (possibly in an earlier command)\&.  Anything else results
+in an error, although the error may not be the most obvious one\&.
+.SS "Modifiers"
+After the optional word designator, you can add
+a sequence of one or more of the following modifiers,
+each preceded by a `\fB:\fP'\&.  These modifiers also work on the result
+of \fIfilename generation\fP and \fIparameter expansion\fP, except where
+noted\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBh\fP
+Remove a trailing pathname component, leaving the head\&.  This works
+like `\fBdirname\fP'\&.
+.TP
+\fBr\fP
+Remove a filename extension of the form `\fB\&.\fP\fIxxx\fP', leaving
+the root name\&.
+.TP
+\fBe\fP
+Remove all but the extension\&.
+.TP
+\fBt\fP
+Remove all leading pathname components, leaving the tail\&.  This works
+like `\fBbasename\fP'\&.
+.TP
+\fBp\fP
+Print the new command but do not execute it\&.  Only works with history
+expansion\&.
+.TP
+\fBq\fP
+Quote the substituted words, escaping further substitutions\&.  Works
+with history expansion and parameter expansion, though for parameters
+it is only useful if the resulting text is to be re\-evaluated such as
+by \fBeval\fP\&.
+.TP
+\fBQ\fP
+Remove one level of quotes from the substituted words\&.
+.TP
+\fBx\fP
+Like \fBq\fP, but break into words at whitespace\&.  Does not work with
+parameter expansion\&.
+.TP
+\fBl\fP
+Convert the words to all lowercase\&.
+.TP
+\fBu\fP
+Convert the words to all uppercase\&.
+.TP
+\fBs/\fP\fIl\fP\fB/\fP\fIr\fP[\fB/\fP]
+Substitute \fIr\fP for \fIl\fP as described below\&.
+Unless preceded immediately by a \fBg\fP, with no colon between,
+the substitution is done only for the
+first string that matches \fIl\fP\&.  For arrays and for filename
+generation, this applies to each word of the expanded text\&.
+.TP
+\fB&\fP
+Repeat the previous \fBs\fP substitution\&.  Like \fBs\fP, may be preceded
+immediately by a \fBg\fP\&.  In parameter expansion the \fB&\fP must appear
+inside braces, and in filename generation it must be quoted with a
+backslash\&.
+.PP
+The \fBs/l/r/\fP substitution works as follows\&.  The left\-hand side of
+substitutions are not regular expressions, but character strings\&.  Any
+character can be used as the delimiter in place of `\fB/\fP'\&.  A
+backslash quotes the delimiter character\&.  The character `\fB&\fP', in
+the right\-hand\-side \fIr\fP, is replaced by the text from the
+left\-hand\-side \fIl\fP\&.  The `\fB&\fP' can be quoted with a backslash\&.  A
+null \fIl\fP uses the previous string either from the previous \fIl\fP
+or from the contextual scan string \fIs\fP from `\fB!?\fP\fIs\fP'\&.  You can
+omit the rightmost delimiter if a newline immediately follows \fIr\fP;
+the rightmost `\fB?\fP' in a context scan can similarly be omitted\&.
+Note the same record of the last \fIl\fP and \fIr\fP is maintained
+across all forms of expansion\&.
+.PP
+The following \fBf\fP, \fBF\fP, \fBw\fP and \fBW\fP modifiers work only with
+parameter expansion and filename generation\&.  They are listed here to
+provide a single point of reference for all modifiers\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBf\fP
+Repeats the immediately (without a colon) following modifier until the
+resulting word doesn't change any more\&.
+.TP
+\fBF:\fP\fIexpr\fP\fB:\fP
+Like \fBf\fP, but repeats only \fIn\fP times if the expression
+\fIexpr\fP evaluates to \fIn\fP\&.  Any character can be used instead of
+the `\fB:\fP'; if `\fB(\fP', `\fB[\fP', or `\fB{\fP'
+is used as the opening delimiter,
+the closing delimiter should be '\fB)\fP', `\fB]\fP', or `\fB}\fP',
+respectively\&.
+.TP
+\fBw\fP
+Makes the immediately following modifier work on each word in the
+string\&.
+.TP
+\fBW:\fP\fIsep\fP\fB:\fP
+Like \fBw\fP but words are considered to be the parts of the string
+that are separated by \fIsep\fP\&. Any character can be used instead of
+the `\fB:\fP'; opening parentheses are handled specially, see above\&.
+.SH "PROCESS SUBSTITUTION"
+Each command argument of the form
+`\fB<(\fP\fIlist\fP\fB)\fP',
+`\fB>(\fP\fIlist\fP\fB)\fP' or
+`\fB=(\fP\fIlist\fP\fB)\fP'
+is subject to process substitution\&.
+In the case of the \fB<\fP or \fB>\fP forms, the shell runs process
+\fIlist\fP asynchronously\&.  If the system supports the \fB/dev/fd\fP
+mechanism, the command argument is the name of the device file
+corresponding to a file descriptor; otherwise, if the system supports named
+pipes (FIFOs), the command argument will be a named pipe\&.  If the form with
+\fB>\fP is selected then writing on this special file will provide input for
+\fIlist\fP\&.  If \fB<\fP is used, then the file passed as an argument will
+be connected to the output of the \fIlist\fP process\&.  For example,
+.PP
+.RS
+.nf
+\fB\fBpaste <(cut \-f1\fP \fIfile1\fP\fB) <(cut \-f3\fP \fIfile2\fP\fB) |
+tee >(\fP\fIprocess1\fP\fB) >(\fP\fIprocess2\fP\fB) >/dev/null\fP\fP
+.fi
+.RE
+.PP
+cuts fields 1 and 3 from the files \fIfile1\fP and \fIfile2\fP respectively,
+pastes the results together, and sends it to the processes
+\fIprocess1\fP and \fIprocess2\fP\&.
+.PP
+If \fB=(\fP\fI\&.\&.\&.\fP\fB)\fP is used instead of
+\fB<(\fP\fI\&.\&.\&.\fP\fB)\fP,
+then the file passed as an argument will be the name
+of a temporary file containing the output of the \fIlist\fP
+process\&.  This may be used instead of the \fB<\fP
+form for a program that expects to lseek (see \fIlseek\fP(2))
+on the input file\&.
+.PP
+The \fB=\fP form is useful as both the \fB/dev/fd\fP and the named pipe
+implementation of \fB<(\fP\fI\&.\&.\&.\fP\fB)\fP have drawbacks\&.  In 
+the former case, some programmes may automatically close the file
+descriptor in question before examining the file on the command line,
+particularly if this is necessary for security reasons such as when the
+programme is running setuid\&.  In the second case, if the
+programme does not actually open the file, the subshell attempting to read
+from or write to the pipe will (in a typical implementation, different
+operating systems may have different behaviour) block for ever and have to
+be killed explicitly\&.  In both cases, the shell actually supplies the
+information using a pipe, so that programmes that expect to lseek
+(see \fIlseek\fP(2)) on the file will not work\&.
+.PP
+Also note that the previous example can be more compactly and
+efficiently written (provided the \fBMULTIOS\fP option is set) as:
+.PP
+.RS
+.nf
+\fB\fBpaste <(cut \-f1\fP \fIfile1\fP\fB) <(cut \-f3\fP \fIfile2\fP\fB)\fP \e 
+\fB> >(\fP\fIprocess1\fP\fB) > >(\fP\fIprocess2\fP\fB)\fP\fP
+.fi
+.RE
+.PP
+The shell uses pipes instead of FIFOs to implement the latter
+two process substitutions in the above example\&.
+.PP
+There is an additional problem with \fB>(\fP\fIprocess\fP\fB)\fP; when
+this is attached to an external command, the parent shell does not wait
+for \fIprocess\fP to finish and hence an immediately following command
+cannot rely on the results being complete\&.  The problem and solution are
+the same as described in the section \fIMULTIOS\fP in
+\fIzshmisc\fP(1)\&.  Hence in a simplified
+version of the example above:
+.PP
+.RS
+.nf
+\fB\fBpaste <(cut \-f1\fP \fIfile1\fP\fB) <(cut \-f3\fP \fIfile2\fP\fB)\fP \fB> >(\fP\fIprocess\fP\fB)\fP\fP
+.fi
+.RE
+.PP
+(note that no \fBMULTIOS\fP are involved), \fIprocess\fP will be run
+asynchronously\&.  The workaround is:
+.PP
+.RS
+.nf
+\fB\fB{ paste <(cut \-f1\fP \fIfile1\fP\fB) <(cut \-f3\fP \fIfile2\fP\fB) }\fP \fB> >(\fP\fIprocess\fP\fB)\fP\fP
+.fi
+.RE
+.PP
+The extra processes here are
+spawned from the parent shell which will wait for their completion\&.
+.PP
+.SH "PARAMETER EXPANSION"
+The character `\fB$\fP' is used to introduce parameter expansions\&.
+See
+\fIzshparam\fP(1)
+for a description of parameters, including arrays, associative arrays,
+and subscript notation to access individual array elements\&.
+.PP
+Note in particular the fact that words of unquoted parameters are not
+automatically split on whitespace unless the option \fBSH_WORD_SPLIT\fP is
+set; see references to this option below for more details\&.  This is an
+important difference from other shells\&.
+.PP
+In the expansions discussed below that require a pattern, the form of
+the pattern is the same as that used for filename generation;
+see the section `Filename Generation'\&.  Note that these patterns, along with
+the replacement text of any substitutions, are themselves subject to
+parameter expansion, command substitution, and arithmetic expansion\&.
+In addition to the following operations, the colon modifiers described in
+the section `Modifiers' in the section `History Expansion' can be
+applied:  for example, \fB${i:s/foo/bar/}\fP performs string
+substitution on the expansion of parameter \fB$i\fP\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB${\fP\fIname\fP\fB}\fP
+The value, if any, of the parameter \fIname\fP is substituted\&.
+The braces are required if the expansion is to be followed by
+a letter, digit, or underscore that is not to be interpreted
+as part of \fIname\fP\&.  In addition, more complicated forms of substitution
+usually require the braces to be present; exceptions, which only apply if
+the option \fBKSH_ARRAYS\fP is not set, are a single subscript or any colon
+modifiers appearing after the name, or any of the characters `\fB^\fP',
+`\fB=\fP', `\fB~\fP', `\fB#\fP' or `\fB+\fP' appearing before the name, all of
+which work with or without braces\&.
+.RS
+.PP
+If \fIname\fP is an array parameter, and the \fBKSH_ARRAYS\fP option is not
+set, then the value of each
+element of \fIname\fP is substituted, one element per word\&.  Otherwise, the
+expansion results in one word only; with \fBKSH_ARRAYS\fP, this is the first
+element of an array\&.  No field splitting is done on the result unless the
+\fBSH_WORD_SPLIT\fP option is set\&.
+.RE
+.TP
+\fB${+\fP\fIname\fP\fB}\fP
+If \fIname\fP is the name of a set parameter `\fB1\fP' is substituted,
+otherwise `\fB0\fP' is substituted\&.
+.TP
+\fB${\fP\fIname\fP\fB:\-\fP\fIword\fP\fB}\fP
+If \fIname\fP is set and is non\-null then substitute its
+value; otherwise substitute \fIword\fP\&. If \fIname\fP is
+missing, substitute \fIword\fP\&.
+.TP
+.PD 0
+\fB${\fP\fIname\fP\fB:=\fP\fIword\fP\fB}\fP
+.TP
+.PD
+\fB${\fP\fIname\fP\fB::=\fP\fIword\fP\fB}\fP
+In the first form, if \fIname\fP is unset or is null then
+set it to \fIword\fP; in the second form, unconditionally
+set \fIname\fP to \fIword\fP\&.  In both forms, the value of
+the parameter is then substituted\&.
+.TP
+\fB${\fP\fIname\fP\fB:?\fP\fIword\fP\fB}\fP
+If \fIname\fP is set and is non\-null then substitute
+its value; otherwise, print \fIword\fP and exit from the shell\&.
+Interactive shells instead return to the prompt\&.
+If \fIword\fP is omitted, then a standard message is printed\&.
+.TP
+\fB${\fP\fIname\fP\fB:+\fP\fIword\fP\fB}\fP
+If \fIname\fP is set and is non\-null then substitute
+\fIword\fP; otherwise substitute nothing\&.
+.PP
+If the colon is omitted from one of the above expressions
+containing a colon, then the shell only checks whether
+\fIname\fP is set, not whether its value is null\&.
+.PP
+In the following expressions, when \fIname\fP is an array and
+the substitution is not quoted, or if the `\fB(@)\fP' flag or the
+\fIname\fP\fB[@]\fP syntax is used, matching and replacement is
+performed on each array element separately\&.
+.PP
+.PD 0
+.TP
+.PD 0
+\fB${\fP\fIname\fP\fB#\fP\fIpattern\fP\fB}\fP
+.TP
+.PD
+\fB${\fP\fIname\fP\fB##\fP\fIpattern\fP\fB}\fP
+If the \fIpattern\fP matches the beginning of the value of
+\fIname\fP, then substitute the value of \fIname\fP with
+the matched portion deleted; otherwise, just
+substitute the value of \fIname\fP\&.  In the first
+form, the smallest matching pattern is preferred;
+in the second form, the largest matching pattern is
+preferred\&.
+.TP
+.PD 0
+\fB${\fP\fIname\fP\fB%\fP\fIpattern\fP\fB}\fP
+.TP
+.PD
+\fB${\fP\fIname\fP\fB%%\fP\fIpattern\fP\fB}\fP
+If the \fIpattern\fP matches the end of the value of
+\fIname\fP, then substitute the value of \fIname\fP with
+the matched portion deleted; otherwise, just
+substitute the value of \fIname\fP\&.  In the first
+form, the smallest matching pattern is preferred;
+in the second form, the largest matching pattern is
+preferred\&.
+.TP
+\fB${\fP\fIname\fP\fB:#\fP\fIpattern\fP\fB}\fP
+If the \fIpattern\fP matches the value of \fIname\fP, then substitute
+the empty string; otherwise, just substitute the value of \fIname\fP\&.
+If \fIname\fP is an array
+the matching array elements are removed (use the `\fB(M)\fP' flag to
+remove the non\-matched elements)\&.
+.TP
+.PD 0
+\fB${\fP\fIname\fP\fB/\fP\fIpattern\fP\fB/\fP\fIrepl\fP\fB}\fP
+.TP
+.PD
+\fB${\fP\fIname\fP\fB//\fP\fIpattern\fP\fB/\fP\fIrepl\fP\fB}\fP
+Replace the longest possible match of \fIpattern\fP in the expansion of
+parameter \fIname\fP by string \fIrepl\fP\&.  The first form
+replaces just the first occurrence, the second form all occurrences\&.
+Both \fIpattern\fP and \fIrepl\fP are subject to double\-quoted substitution,
+so that expressions like \fB${name/$opat/$npat}\fP will work, but note the
+usual rule that pattern characters in \fB$opat\fP are not treated specially
+unless either the option \fBGLOB_SUBST\fP is set, or \fB$opat\fP is instead
+substituted as \fB${~opat}\fP\&.
+.RS
+.PP
+The \fIpattern\fP may begin with a `\fB#\fP', in which case the
+\fIpattern\fP must match at the start of the string, or `\fB%\fP', in
+which case it must match at the end of the string\&.  The \fIrepl\fP may
+be an empty string, in which case the final `\fB/\fP' may also be omitted\&.
+To quote the final `\fB/\fP' in other cases it should be preceded by a
+single backslash; this is not necessary if the
+`\fB/\fP' occurs inside a substituted parameter\&.  Note also that the `\fB#\fP'
+and `\fB%\fP' are not active if they occur inside a substituted parameter,
+even at the start\&.
+.PP
+The first `\fB/\fP' may be preceded by a `\fB:\fP', in which case the match
+will only succeed if it matches the entire word\&.  Note also the
+effect of the \fBI\fP and \fBS\fP parameter expansion flags below; however,
+the flags \fBM\fP, \fBR\fP, \fBB\fP, \fBE\fP and \fBN\fP are not useful\&.
+.PP
+For example,
+.PP
+.RS
+.nf
+\fBfoo="twinkle twinkle little star" sub="t*e" rep="spy"
+print ${foo//${~sub}/$rep}
+print ${(S)foo//${~sub}/$rep}\fP
+.fi
+.RE
+.PP
+Here, the `\fB~\fP' ensures that the text of \fB$sub\fP is treated as a
+pattern rather than a plain string\&.  In the first case, the longest
+match for \fBt*e\fP is substituted and the result is `\fBspy star\fP',
+while in the second case, the shortest matches are taken and the
+result is `\fBspy spy lispy star\fP'\&.
+.RE
+.TP
+\fB${#\fP\fIspec\fP\fB}\fP
+If \fIspec\fP is one of the above substitutions, substitute
+the length in characters of the result instead of
+the result itself\&.  If \fIspec\fP is an array expression,
+substitute the number of elements of the result\&.
+Note that `\fB^\fP', `\fB=\fP', and `\fB~\fP', below, must appear
+to the left of `\fB#\fP' when these forms are combined\&.
+.TP
+\fB${^\fP\fIspec\fP\fB}\fP
+Turn on the \fBRC_EXPAND_PARAM\fP option for the
+evaluation of \fIspec\fP; if the `\fB^\fP' is doubled, turn it off\&.
+When this option is set, array expansions of the form
+\fIfoo\fP\fB${\fP\fIxx\fP\fB}\fP\fIbar\fP,
+where the parameter \fIxx\fP
+is set to \fB(\fP\fIa b c\fP\fB)\fP, are substituted with
+`\fIfooabar foobbar foocbar\fP' instead of the default
+`\fIfooa b cbar\fP'\&.
+.RS
+.PP
+Internally, each such expansion is converted into the
+equivalent list for brace expansion\&.  E\&.g\&., \fB${^var}\fP becomes
+\fB{$var[1],$var[2],\fP\&.\&.\&.\fB}\fP, and is processed as described in
+the section `Brace Expansion' below\&.
+If word splitting is also in effect the
+\fB$var[\fP\fIN\fP\fB]\fP may themselves be split into different list
+elements\&.
+.RE
+.TP
+\fB${=\fP\fIspec\fP\fB}\fP
+Perform word splitting using the rules for \fBSH_WORD_SPLIT\fP during the
+evaluation of \fIspec\fP, but regardless of whether the parameter appears in
+double quotes; if the `\fB=\fP' is doubled, turn it off\&.
+This forces parameter expansions to be split into
+separate words before substitution, using \fBIFS\fP as a delimiter\&.
+This is done by default in most other shells\&.
+.RS
+.PP
+Note that splitting is applied to \fIword\fP in the assignment forms
+of \fIspec\fP \fIbefore\fP the assignment to \fIname\fP is performed\&.
+This affects the result of array assignments with the \fBA\fP flag\&.
+.RE
+.TP
+\fB${~\fP\fIspec\fP\fB}\fP
+Turn on the \fBGLOB_SUBST\fP option for the evaluation of
+\fIspec\fP; if the `\fB~\fP' is doubled, turn it off\&.  When this option is
+set, the string resulting from the expansion will be interpreted as a
+pattern anywhere that is possible, such as in filename expansion and
+filename generation and pattern\-matching contexts like the right
+hand side of the `\fB=\fP' and `\fB!=\fP' operators in conditions\&.
+.PP
+If a \fB${\fP\&.\&.\&.\fB}\fP type parameter expression or a
+\fB$(\fP\&.\&.\&.\fB)\fP type command substitution is used in place of
+\fIname\fP above, it is expanded first and the result is used as if
+it were the value of \fIname\fP\&.  Thus it is
+possible to perform nested operations:  \fB${${foo#head}%tail}\fP
+substitutes the value of \fB$foo\fP with both `\fBhead\fP' and `\fBtail\fP'
+deleted\&.  The form with \fB$(\fP\&.\&.\&.\fB)\fP is often useful in
+combination with the flags described next; see the examples below\&.
+Each \fIname\fP or nested \fB${\fP\&.\&.\&.\fB}\fP in a parameter expansion may
+also be followed by a subscript expression as described in
+\fIArray Parameters\fP in \fIzshparam\fP(1)\&.
+.PP
+Note that double quotes may appear around nested expressions, in which
+case only the part inside is treated as quoted; for example,
+\fB${(f)"$(foo)"}\fP quotes the result of \fB$(foo)\fP, but the flag `\fB(f)\fP'
+(see below) is applied using the rules for unquoted expansions\&.  Note
+further that quotes are themselves nested in this context; for example, in
+\fB"${(@f)"$(foo)"}"\fP, there are two sets of quotes, one surrounding the
+whole expression, the other (redundant) surrounding the \fB$(foo)\fP as
+before\&.
+.PP
+.SS "Parameter Expansion Flags"
+If the opening brace is directly followed by an opening parenthesis,
+the string up to the matching closing parenthesis will be taken as a
+list of flags\&.  In cases where repeating a flag is meaningful, the
+repetitions need not be consecutive; for example, `(\fBq%q%q\fP)'
+means the same thing as the more readable `(\fB%%qqq\fP)'\&.  The
+following flags are supported:
+.PP
+.PD 0
+.TP
+.PD
+\fB%\fP
+Expand all \fB%\fP escapes in the resulting words in the same way as in in
+prompts (see the section `Prompt Expansion')\&. If this flag is given twice,
+full prompt expansion is done on the resulting words, depending on the
+setting of the \fBPROMPT_PERCENT\fP, \fBPROMPT_SUBST\fP and \fBPROMPT_BANG\fP
+options\&.
+.TP
+\fB@\fP
+In double quotes, array elements are put into separate words\&.
+E\&.g\&., `\fB"${(@)foo}"\fP' is equivalent to `\fB"${foo[@]}"\fP' and
+`\fB"${(@)foo[1,2]}"\fP' is the same as `\fB"$foo[1]" "$foo[2]"\fP'\&.
+This is distinct from \fIfield splitting\fP by the the \fBf\fP, \fBs\fP
+or \fBz\fP flags, which still applies within each array element\&.
+.TP
+\fBA\fP
+Create an array parameter with `\fB${\fP\&.\&.\&.\fB=\fP\&.\&.\&.\fB}\fP',
+`\fB${\fP\&.\&.\&.\fB:=\fP\&.\&.\&.\fB}\fP' or `\fB${\fP\&.\&.\&.\fB::=\fP\&.\&.\&.\fB}\fP'\&.
+If this flag is repeated (as in `\fBAA\fP'), create an associative
+array parameter\&.  Assignment is made before sorting or padding\&.
+The \fIname\fP part may be a subscripted range for ordinary
+arrays; the \fIword\fP part \fImust\fP be converted to an array, for
+example by using `\fB${(AA)=\fP\fIname\fP\fB=\fP\&.\&.\&.\fB}\fP' to activate
+field splitting, when creating an associative array\&.
+.TP
+\fBa\fP
+With \fBo\fP or \fBO\fP, sort in array index order\&. Note that `\fBoa\fP' is
+therefore equivalent to the default but `\fBOa\fP' is useful for
+obtaining an array's elements in reverse order\&.
+.TP
+\fBc\fP
+With \fB${#\fP\fIname\fP\fB}\fP, count the total number of characters in an array,
+as if the elements were concatenated with spaces between them\&.
+.TP
+\fBC\fP
+Capitalize the resulting words\&.  `Words' in this case refers to sequences
+of alphanumeric characters separated by non\-alphanumerics, \fInot\fP to words
+that result from field splitting\&.
+.TP
+\fBe\fP
+Perform \fIparameter expansion\fP, \fIcommand substitution\fP and
+\fIarithmetic expansion\fP on the result\&. Such expansions can be
+nested but too deep recursion may have unpredictable effects\&.
+.TP
+\fBf\fP
+Split the result of the expansion to lines\&. This is a shorthand
+for `\fBps:\en:\fP'\&.
+.TP
+\fBF\fP
+Join the words of arrays together using newline as a separator\&.
+This is a shorthand for `\fBpj:\en:\fP'\&.
+.TP
+\fBi\fP
+With \fBo\fP or \fBO\fP, sort case\-independently\&.
+.TP
+\fBk\fP
+If \fIname\fP refers to an associative array, substitute the \fIkeys\fP
+(element names) rather than the values of the elements\&.  Used with
+subscripts (including ordinary arrays), force indices or keys to be
+substituted even if the subscript form refers to values\&.  However,
+this flag may not be combined with subscript ranges\&.
+.TP
+\fBL\fP
+Convert all letters in the result to lower case\&.
+.TP
+\fBn\fP
+With \fBo\fP or \fBO\fP, sort numerically\&.
+.TP
+\fBo\fP
+Sort the resulting words in ascending order\&.
+.TP
+\fBO\fP
+Sort the resulting words in descending order\&.
+.TP
+\fBP\fP
+This forces the value of the parameter \fIname\fP to be interpreted as a
+further parameter name, whose value will be used where appropriate\&. If
+used with a nested parameter or command substitution, the result of that
+will be taken as a parameter name in the same way\&.  For example, if you
+have `\fBfoo=bar\fP' and `\fBbar=baz\fP', the strings \fB${(P)foo}\fP,
+\fB${(P)${foo}}\fP, and \fB${(P)$(echo bar)}\fP will be expanded to `\fBbaz\fP'\&.
+.TP
+\fBq\fP
+Quote the resulting words with backslashes\&. If this flag is given
+twice, the resulting words are quoted in single quotes and if it is
+given three times, the words are quoted in double quotes\&. If it is
+given four times, the words are quoted in single quotes preceded by a \fB$\fP\&.
+.TP
+\fBQ\fP
+Remove one level of quotes from the resulting words\&.
+.TP
+\fBt\fP
+Use a string describing the type of the parameter where the value
+of the parameter would usually appear\&. This string consists of keywords
+separated by hyphens (`\fB\-\fP')\&. The first keyword in the string describes
+the main type, it can be one of `\fBscalar\fP', `\fBarray\fP', `\fBinteger\fP',
+`\fBfloat\fP' or `\fBassociation\fP'\&. The other keywords describe the type in
+more detail:
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fBlocal\fP
+for local parameters
+.TP
+\fBleft\fP
+for left justified parameters
+.TP
+\fBright_blanks\fP
+for right justified parameters with leading blanks
+.TP
+\fBright_zeros\fP
+for right justified parameters with leading zeros
+.TP
+\fBlower\fP
+for parameters whose value is converted to all lower case when it is
+expanded
+.TP
+\fBupper\fP
+for parameters whose value is converted to all upper case when it is
+expanded
+.TP
+\fBreadonly\fP
+for readonly parameters
+.TP
+\fBtag\fP
+for tagged parameters
+.TP
+\fBexport\fP
+for exported parameters
+.TP
+\fBunique\fP
+for arrays which keep only the first occurrence of duplicated values
+.TP
+\fBhide\fP
+for parameters with the `hide' flag
+.TP
+\fBspecial\fP
+for special parameters defined by the shell
+.RE
+.TP
+\fBu\fP
+Expand only the first occurrence of each unique word\&.
+.TP
+\fBU\fP
+Convert all letters in the result to upper case\&.
+.TP
+\fBv\fP
+Used with \fBk\fP, substitute (as two consecutive words) both the key
+and the value of each associative array element\&.  Used with subscripts,
+force values to be substituted even if the subscript form refers to
+indices or keys\&.
+.TP
+\fBV\fP
+Make any special characters in the resulting words visible\&.
+.TP
+\fBw\fP
+With \fB${#\fP\fIname\fP\fB}\fP, count words in arrays or strings; the \fBs\fP
+flag may be used to set a word delimiter\&.
+.TP
+\fBW\fP
+Similar to \fBw\fP with the difference that empty words between
+repeated delimiters are also counted\&.
+.TP
+\fBX\fP
+With this flag parsing errors occurring with the \fBQ\fP and \fBe\fP flags or the
+pattern matching forms such as `\fB${\fP\fIname\fP\fB#\fP\fIpattern\fP\fB}\fP' 
+are reported\&. Without the flag they are silently ignored\&.
+.TP
+\fBz\fP
+Split the result of the expansion into words using shell parsing to
+find the words, i\&.e\&. taking into account any quoting in the value\&.
+.RS
+.PP
+Note that this is done very late, as for the `\fB(s)\fP' flag\&. So to
+access single words in the result, one has to use nested expansions as 
+in `\fB${${(z)foo}[2]}\fP'\&. Likewise, to remove the quotes in the
+resulting words one would do: `\fB${(Q)${(z)foo}}\fP'\&.
+.RE
+.RE
+.PP
+The following flags (except \fBp\fP) are followed by one or more arguments
+as shown\&.  Any character, or the matching pairs `\fB(\fP\&.\&.\&.\fB)\fP',
+`\fB{\fP\&.\&.\&.\fB}\fP', `\fB[\fP\&.\&.\&.\fB]\fP', or `\fB<\fP\&.\&.\&.\fB>\fP', may be used in place
+of a colon as delimiters, but note that when a flag takes more than one
+argument, a matched pair of delimiters must surround each argument\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBp\fP
+Recognize the same escape sequences as the \fBprint\fP builtin
+in string arguments to any of the flags described below\&.
+.TP
+\fBj:\fP\fIstring\fP\fB:\fP
+Join the words of arrays together using \fIstring\fP as a separator\&.
+Note that this occurs before field splitting by the \fBSH_WORD_SPLIT\fP
+option\&.
+.TP
+\fBl:\fP\fIexpr\fP\fB::\fP\fIstring1\fP\fB::\fP\fIstring2\fP\fB:\fP
+Pad the resulting words on the left\&.  Each word will be truncated if
+required and placed in a field \fIexpr\fP characters wide\&.  The space
+to the left will be filled with \fIstring1\fP (concatenated as often
+as needed) or spaces if \fIstring1\fP is not given\&.  If both
+\fIstring1\fP and \fIstring2\fP are given, this string is inserted
+once directly to the left of each word, before padding\&.
+.TP
+\fBr:\fP\fIexpr\fP\fB::\fP\fIstring1\fP\fB::\fP\fIstring2\fP\fB:\fP
+As \fBl\fP, but pad the words on the right and insert \fIstring2\fP
+on the right\&.
+.TP
+\fBs:\fP\fIstring\fP\fB:\fP
+Force field splitting (see the option \fBSH_WORD_SPLIT\fP) at the
+separator \fIstring\fP\&.  Note that a \fIstring\fP of two or more
+characters means all must all match in sequence; this differs from
+the treatment of two or more characters in the \fBIFS\fP parameter\&.
+.PP
+The following flags are meaningful with the \fB${\fP\&.\&.\&.\fB#\fP\&.\&.\&.\fB}\fP or
+\fB${\fP\&.\&.\&.\fB%\fP\&.\&.\&.\fB}\fP forms\&.  The \fBS\fP and \fBI\fP flags may also be
+used with the \fB${\fP\&.\&.\&.\fB/\fP\&.\&.\&.\fB}\fP forms\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBS\fP
+Search substrings as well as beginnings or ends; with \fB#\fP start
+from the beginning and with \fB%\fP start from the end of the string\&.
+With substitution via \fB${\fP\&.\&.\&.\fB/\fP\&.\&.\&.\fB}\fP or
+\fB${\fP\&.\&.\&.\fB//\fP\&.\&.\&.\fB}\fP, specifies non\-greedy matching, i\&.e\&. that the
+shortest instead of the longest match should be replaced\&.
+.TP
+\fBI:\fP\fIexpr\fP\fB:\fP
+Search the \fIexpr\fPth match (where \fIexpr\fP evaluates to a number)\&.
+This only applies when searching for substrings, either with the \fBS\fP
+flag, or with \fB${\fP\&.\&.\&.\fB/\fP\&.\&.\&.\fB}\fP (only the \fIexpr\fPth match is
+substituted) or \fB${\fP\&.\&.\&.\fB//\fP\&.\&.\&.\fB}\fP (all matches from the
+\fIexpr\fPth on are substituted)\&.  The default is to take the first match\&.
+.RS
+.PP
+The \fIexpr\fPth match is counted such that there is either one or zero
+matches from each starting position in the string, although for global
+substitution matches overlapping previous replacements are ignored\&.  With
+the \fB${\fP\&.\&.\&.\fB%\fP\&.\&.\&.\fB}\fP and \fB${\fP\&.\&.\&.\fB%%\fP\&.\&.\&.\fB}\fP forms, the starting
+position for the match moves backwards from the end as the index increases,
+while with the other forms it moves forward from the start\&.
+.PP
+Hence with the string
+.RS
+.nf
+\fBwhich switch is the right switch for Ipswich?\fP
+.fi
+.RE
+substitutions of the form
+\fB${\fP(\fBSI:\fP\fIN\fP\fB:\fP)\fBstring#w*ch}\fP as \fIN\fP increases
+from 1 will match and remove `\fBwhich\fP', `\fBwitch\fP', `\fBwitch\fP' and
+`\fBwich\fP'; the form using `\fB##\fP' will match and remove `\fBwhich switch
+is the right switch for Ipswich\fP', `\fBwitch is the right switch for
+Ipswich\fP', `\fBwitch for Ipswich\fP' and `\fBwich\fP'\&. The form using `\fB%\fP'
+will remove the same matches as for `\fB#\fP', but in reverse order, and the
+form using `\fB%%\fP' will remove the same matches as for `\fB##\fP' in reverse
+order\&.
+.RE
+.TP
+\fBB\fP
+Include the index of the beginning of the match in the result\&.
+.TP
+\fBE\fP
+Include the index of the end of the match in the result\&.
+.TP
+\fBM\fP
+Include the matched portion in the result\&.
+.TP
+\fBN\fP
+Include the length of the match in the result\&.
+.TP
+\fBR\fP
+Include the unmatched portion in the result (the \fIR\fPest)\&.
+.PP
+.SS "Rules"
+.PP
+Here is a summary of the rules for substitution; this assumes that braces
+are present around the substitution, i\&.e\&. \fB${\&.\&.\&.}\fP\&.  Some particular
+examples are given below\&.  Note that the Zsh Development Group accepts
+\fIno responsibility\fP for any brain damage which may occur during the
+reading of the following rules\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB1\&.\fP \fINested Substitution\fP
+If multiple nested \fB${\&.\&.\&.}\fP 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, just as if the nested substitution were the
+outermost\&.  The flags are not propagated up to enclosing
+substitutions; the nested substitution 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 `\fB(P)\fP' flag is present, the flags and any subscripts
+apply directly to the value of the nested substitution; for example, the
+expansion \fB${${foo}}\fP behaves exactly the same as \fB${foo}\fP\&.
+.TP
+\fB2\&.\fP \fIParameter Subscripting\fP
+If the value is a raw parameter reference with a subscript, such as
+\fB${\fP\fIvar\fP\fB[3]}\fP, the effect of subscripting is applied directly to
+the parameter\&.  Subscripts are evaluated left to right; subsequent
+subscripts apply to the scalar or array value yielded by the previous
+subscript\&.  Thus if \fBvar\fP is an array, \fB${var[1][2]}\fP is the second
+character of the first word, but \fB${var[2,4][2]}\fP 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\&.
+.TP
+\fB3\&.\fP \fIParameter Name Replacement\fP
+The effect of any \fB(P)\fP flag, which treats the value so far as a
+parameter name and replaces it with the corresponding value, is applied\&.
+.TP
+\fB4\&.\fP \fIDouble\-Quoted Joining\fP
+If the value after this process is an array, and the substitution
+appears in double quotes, and no \fB(@)\fP flag is present at the current
+level, the words of the value are joined with the first character of the
+parameter \fB$IFS\fP, by default a space, between each word (single word
+arrays are not modified)\&.  If the \fB(j)\fP flag is present, that is used for
+joining instead of \fB$IFS\fP\&.
+.TP
+\fB5\&.\fP \fINested Subscripting\fP
+Any remaining subscripts (i\&.e\&. of a nested substitution) are evaluated at
+this point, based on whether the value is an array or a scalar\&.  As with
+\fB2\&.\fP, multiple subscripts can appear\&.  Note that \fB${foo[2,4][2]}\fP is
+thus equivalent to \fB${${foo[2,4]}[2]}\fP and also to
+\fB"${${(@)foo[2,4]}[2]}"\fP (the nested substitution returns an array in
+both cases), but not to \fB"${${foo[2,4]}[2]}"\fP (the nested substitution
+returns a scalar because of the quotes)\&.
+.TP
+\fB6\&.\fP \fIModifiers\fP
+Any modifiers, as specified by a trailing `\fB#\fP', `\fB%\fP', `\fB/\fP'
+(possibly doubled) or by a set of modifiers of the form \fB:\&.\&.\&.\fP (see
+the section `Modifiers' in the section `History Expansion'), are applied to the words
+of the value at this level\&.
+.TP
+\fB7\&.\fP \fIForced Joining\fP
+If the `\fB(j)\fP' flag is present, or no `\fB(j)\fP' flag is present but
+the string is to be split as given by rules \fB8\&.\fP or \fB9\&.\fP, and joining
+did not take place at step \fB4\&.\fP, any words in the value are joined
+together using the given string or the first character of \fB$IFS\fP if none\&.
+Note that the `\fB(F)\fP' flag implicitly supplies a string for joining in this
+manner\&.
+.TP
+\fB8\&.\fP \fIForced Splitting\fP
+If one of the `\fB(s)\fP', `\fB(f)\fP' or `\fB(z)\fP' flags are present, or the `\fB=\fP'
+specifier was present (e\&.g\&. \fB${=\fP\fIvar\fP\fB}\fP), the word is split on
+occurrences of the specified string, or (for \fB=\fP with neither of the two
+flags present) any of the characters in \fB$IFS\fP\&.
+.TP
+\fB9\&.\fP \fIShell Word Splitting\fP
+If no `\fB(s)\fP', `\fB(f)\fP' or `\fB=\fP' was given, but the word is not
+quoted and the option \fBSH_WORD_SPLIT\fP is set, the word is split on
+occurrences of any of the characters in \fB$IFS\fP\&.  Note this step, too,
+takes place at all levels of a nested substitution\&.
+.TP
+\fB10\&.\fP \fIRe\-Evaluation\fP
+Any `\fB(e)\fP' flag is applied to the value, forcing it to be re\-examined
+for new parameter substitutions, but also for command and arithmetic
+substitutions\&.
+.TP
+\fB11\&.\fP \fIPadding\fP
+Any padding of the value by the `\fB(l\&.\fP\fIfill\fP\fB\&.)\fP' or
+`\fB(r\&.\fP\fIfill\fP\fB\&.)\fP' flags is applied\&.
+.TP
+\fB12\&.\fP \fISemantic Joining\fP
+In contexts where expansion semantics requires a single word to
+result, all words are rejoined with the first character of \fBIFS\fP
+between\&.  So in `\fB${(P\fP\fB)${(f\fP\fB)lines}}\fP'
+the value of \fB${lines}\fP is split at newlines, but then must be
+joined again before the \fBP\fP flag can be applied\&.
+.RS
+.PP
+If a single word is not required, this rule is skipped\&.
+.RE
+.RE
+.PP
+.SS "Examples"
+The flag \fBf\fP is useful to split a double\-quoted substitution line by
+line\&.  For example, \fB${(f)"$(<\fP\fIfile\fP\fB)"}\fP
+substitutes the contents of \fIfile\fP divided so that each line is
+an element of the resulting array\&.  Compare this with the effect of
+\fB$\fP\fB(<\fP\fIfile\fP\fB)\fP alone, which divides the file
+up by words, or the same inside double quotes, which makes the entire
+content of the file a single string\&.
+.PP
+The following illustrates the rules for nested parameter expansions\&.
+Suppose that \fB$foo\fP contains the array \fB(bar baz\fP\fB)\fP:
+.PP
+.PD 0
+.TP
+.PD
+\fB"${(@)${foo}[1]}"\fP
+This produces the result \fBb\fP\&.  First, the inner substitution
+\fB"${foo}"\fP, which has no array (\fB@\fP) flag, produces a single word
+result \fB"bar baz"\fP\&.  The outer substitution \fB"${(@)\&.\&.\&.[1]}"\fP detects
+that this is a scalar, so that (despite the `\fB(@)\fP' flag) the subscript
+picks the first character\&. 
+.TP
+\fB"${${(@)foo}[1]}"\fP
+This produces the result `\fBbar\fP'\&.  In this case, the inner substitution
+\fB"${(@)foo}"\fP produces the array `\fB(bar baz\fP\fB)\fP'\&.  The outer
+substitution \fB"${\&.\&.\&.[1]}"\fP detects that this is an array and picks the
+first word\&.  This is similar to the simple case \fB"${foo[1]}"\fP\&.
+.PP
+As an example of the rules for word splitting and joining, suppose \fB$foo\fP
+contains the array `\fB(ax1 bx1\fP\fB)\fP'\&.  Then
+.PP
+.PD 0
+.TP
+.PD
+\fB${(s/x/)foo}\fP
+produces the words `\fBa\fP', `\fB1 b\fP' and `\fB1\fP'\&.
+.TP
+\fB${(j/x/s/x/)foo}\fP
+produces `\fBa\fP', `\fB1\fP', `\fBb\fP' and `\fB1\fP'\&.
+.TP
+\fB${(s/x/)foo%%1*}\fP
+produces `\fBa\fP' and `\fB b\fP' (note the extra space)\&.  As substitution
+occurs before either joining or splitting, the operation  first generates
+the modified array \fB(ax bx\fP\fB)\fP, which is joined to give
+\fB"ax bx"\fP, and then split to give `\fBa\fP', `\fB b\fP' and `'\&.  The final
+empty string will then be elided, as it is not in double quotes\&.
+.PP
+.SH "COMMAND SUBSTITUTION"
+A command enclosed in parentheses preceded by a dollar sign, like
+`\fB$(\fP\&.\&.\&.\fB)\fP', or quoted with grave 
+accents, like `\fB`\fP\&.\&.\&.\fB`\fP', is replaced with its standard output, with
+any trailing newlines deleted\&.
+If the substitution is not enclosed in double quotes, the
+output is broken into words using the \fBIFS\fP parameter\&.
+The substitution `\fB$(cat\fP \fIfoo\fP\fB)\fP' may be replaced
+by the equivalent but faster `\fB$(<\fP\fIfoo\fP\fB)\fP'\&.
+In either case, if the option \fBGLOB_SUBST\fP is set,
+the output is eligible for filename generation\&.
+.SH "ARITHMETIC EXPANSION"
+A string of the form `\fB$[\fP\fIexp\fP\fB]\fP' or
+`\fB$((\fP\fIexp\fP\fB))\fP' is substituted
+with the value of the arithmetic expression \fIexp\fP\&.  \fIexp\fP is
+subjected to \fIparameter expansion\fP, \fIcommand substitution\fP
+and \fIarithmetic expansion\fP before it is evaluated\&.
+See the section `Arithmetic Evaluation'\&.
+.SH "BRACE EXPANSION"
+A string of the form
+`\fIfoo\fP\fB{\fP\fIxx\fP\fB,\fP\fIyy\fP\fB,\fP\fIzz\fP\fB}\fP\fIbar\fP'
+is expanded to the individual words
+`\fIfooxxbar\fP', `\fIfooyybar\fP' and `\fIfoozzbar\fP'\&.
+Left\-to\-right order is preserved\&.  This construct
+may be nested\&.  Commas may be quoted in order to
+include them literally in a word\&.
+.PP
+An expression of the form `\fB{\fP\fIn1\fP\fB\&.\&.\fP\fIn2\fP\fB}\fP',
+where \fIn1\fP and \fIn2\fP are integers,
+is expanded to every number between
+\fIn1\fP and \fIn2\fP inclusive\&.  If either number begins with a
+zero, all the resulting numbers will be padded with leading zeroes to
+that minimum width\&.  If the numbers are in decreasing order the
+resulting sequence will also be in decreasing order\&.
+.PP
+If a brace expression matches none of the above forms, it is left
+unchanged, unless the \fBBRACE_CCL\fP option is set\&.
+In that case, it is expanded to a sorted list of the individual
+characters between the braces, in the manner of a search set\&.
+`\fB\-\fP' is treated specially as in a search set, but `\fB^\fP' or `\fB!\fP' as
+the first character is treated normally\&.
+.PP
+Note that brace expansion is not part of filename generation (globbing); an
+expression such as \fB*/{foo,bar}\fP is split into two separate words
+\fB*/foo\fP and \fB*/bar\fP before filename generation takes place\&.  In
+particular, note that this is liable to produce a `no match' error if
+\fIeither\fP of the two expressions does not match; this is to be contrasted
+with \fB*/(foo|bar)\fP, which is treated as a single pattern but otherwise
+has similar effects\&.
+.SH "FILENAME EXPANSION"
+Each word is checked to see if it begins with an unquoted `\fB~\fP'\&.
+If it does, then the word up to a `\fB/\fP',
+or the end of the word if there is no `\fB/\fP',
+is checked to see if it can be substituted in one of the ways
+described here\&.  If so, then the `\fB~\fP' and the checked portion are
+replaced with the appropriate substitute value\&.
+.PP
+A `\fB~\fP' by itself is replaced by the value of \fB$HOME\fP\&.
+A `\fB~\fP' followed by a `\fB+\fP' or a `\fB\-\fP' is replaced by the value of
+\fB$PWD\fP or \fB$OLDPWD\fP, respectively\&.
+.PP
+A `\fB~\fP' followed by a number is replaced by the directory at that
+position in the directory stack\&.
+`\fB~0\fP' is equivalent to `\fB~+\fP',
+and `\fB~1\fP' is the top of the stack\&.
+`\fB~+\fP' followed by a number is replaced by the directory at that
+position in the directory stack\&.
+`\fB~+0\fP' is equivalent to `\fB~+\fP',
+and `\fB~+1\fP' is the top of the stack\&.
+`\fB~\-\fP' followed by a number is replaced by the directory that
+many positions from the bottom of the stack\&.
+`\fB~\-0\fP' is the bottom of the stack\&.
+The \fBPUSHD_MINUS\fP
+option exchanges the effects of `\fB~+\fP' and `\fB~\-\fP' where they are
+followed by a number\&.
+.PP
+A `\fB~\fP' followed by anything not already covered is looked up as a
+named directory, and replaced by the value of that named directory if found\&.
+Named directories are typically home directories for users on the system\&.
+They may also be defined if the text after the `\fB~\fP' is the name
+of a string shell parameter whose value begins with a `\fB/\fP'\&.
+It is also possible to define directory names using the \fB\-d\fP option to the
+\fBhash\fP builtin\&.
+.PP
+In certain circumstances (in prompts, for instance), when the shell
+prints a path, the path is checked to see if it has a named
+directory as its prefix\&.  If so, then the prefix portion
+is replaced with a `\fB~\fP' followed by the name of the directory\&.
+The shortest way of referring to the directory is used,
+with ties broken in favour of using a named directory,
+except when the directory is \fB/\fP itself\&.  The parameters \fB$PWD\fP and
+\fB$OLDPWD\fP are never abbreviated in this fashion\&.
+.PP
+If a word begins with an unquoted `\fB=\fP'
+and the \fBEQUALS\fP option is set,
+the remainder of the word is taken as the
+name of a command\&.  If a command
+exists by that name, the word is replaced
+by the full pathname of the command\&.
+.PP
+Filename expansion is performed on the right hand side of a parameter
+assignment, including those appearing after commands of the
+\fBtypeset\fP family\&.  In this case, the right hand side will be treated
+as a colon\-separated list in the manner of the \fBPATH\fP parameter,
+so that a `\fB~\fP' or an `\fB=\fP' following a `\fB:\fP' is eligible for expansion\&.
+All such behaviour can be
+disabled by quoting the `\fB~\fP', the `\fB=\fP', or the whole expression (but not
+simply the colon); the \fBEQUALS\fP option is also respected\&.
+.PP
+If the option \fBMAGIC_EQUAL_SUBST\fP is set, any unquoted shell
+argument in the form `\fIidentifier\fP\fB=\fP\fIexpression\fP' becomes eligible
+for file expansion as described in the previous paragraph\&.  Quoting the
+first `\fB=\fP' also inhibits this\&.
+.SH "FILENAME GENERATION"
+If a word contains an unquoted instance of one of the characters
+`\fB*\fP', `\fB(\fP', `\fB|\fP', `\fB<\fP', `\fB[\fP', or `\fB?\fP', it is regarded
+as a pattern for filename generation, unless the \fBGLOB\fP option is unset\&.
+If the \fBEXTENDED_GLOB\fP option is set,
+the `\fB^\fP' and `\fB#\fP' characters also denote a pattern; otherwise
+they are not treated specially by the shell\&.
+.PP
+The word is replaced with a list of sorted filenames that match
+the pattern\&.  If no matching pattern is found, the shell gives
+an error message, unless the \fBNULL_GLOB\fP option is set,
+in which case the word is deleted; or unless the \fBNOMATCH\fP
+option is unset, in which case the word is left unchanged\&.
+.PP
+In filename generation,
+the character `\fB/\fP' must be matched explicitly;
+also, a `\fB\&.\fP' must be matched
+explicitly at the beginning of a pattern or after a `\fB/\fP', unless the
+\fBGLOB_DOTS\fP option is set\&.
+No filename generation pattern
+matches the files `\fB\&.\fP' or `\fB\&.\&.\fP'\&.  In other instances of pattern
+matching, the `\fB/\fP' and `\fB\&.\fP' are not treated specially\&.
+.SS "Glob Operators"
+.PD 0
+.TP
+.PD
+\fB*\fP
+Matches any string, including the null string\&.
+.TP
+\fB?\fP
+Matches any character\&.
+.TP
+\fB[\fP\&.\&.\&.\fB]\fP
+Matches any of the enclosed characters\&.  Ranges of characters
+can be specified by separating two characters by a `\fB\-\fP'\&.
+A `\fB\-\fP' or `\fB]\fP' may be matched by including it as the
+first character in the list\&.
+There are also several named classes of characters, in the form
+`\fB[:\fP\fIname\fP\fB:]\fP' with the following meanings:  `\fB[:alnum:]\fP'
+alphanumeric, `\fB[:alpha:]\fP' alphabetic,
+`\fB[:ascii:]\fP' 7\-bit,
+`\fB[:blank:]\fP' space or tab,
+`\fB[:cntrl:]\fP' control character, `\fB[:digit:]\fP' decimal
+digit, `\fB[:graph:]\fP' printable character except whitespace,
+`\fB[:lower:]\fP' lowercase letter, `\fB[:print:]\fP' printable character,
+`\fB[:punct:]\fP' printable character neither alphanumeric nor whitespace,
+`\fB[:space:]\fP' whitespace character, `\fB[:upper:]\fP' uppercase letter, 
+`\fB[:xdigit:]\fP' hexadecimal digit\&.  These use the macros provided by
+the operating system to test for the given character combinations,
+including any modifications due to local language settings:  see
+\fIctype\fP(3)\&.  Note that the square brackets are additional
+to those enclosing the whole set of characters, so to test for a
+single alphanumeric character you need `\fB[[:alnum:]]\fP'\&.  Named
+character sets can be used alongside other types,
+e\&.g\&. `\fB[[:alpha:]0\-9]\fP'\&.
+.TP
+.PD 0
+\fB[^\fP\&.\&.\&.\fB]\fP
+.TP
+.PD
+\fB[!\fP\&.\&.\&.\fB]\fP
+Like \fB[\fP\&.\&.\&.\fB]\fP, except that it matches any character which is
+not in the given set\&.
+.TP
+\fB<\fP[\fIx\fP]\fB\-\fP[\fIy\fP]\fB>\fP
+Matches any number in the range \fIx\fP to \fIy\fP, inclusive\&.
+Either of the numbers may be omitted to make the range open\-ended;
+hence `\fB<\->\fP' matches any number\&.  To match individual digits, the
+\fB[\fP\&.\&.\&.\fB]\fP form is more efficient\&.
+.RS
+.PP
+Be careful when using other wildcards adjacent to patterns of this form;
+for example, \fB<0\-9>*\fP will actually match any number whatsoever at the
+start of the string, since the `\fB<0\-9>\fP' will match the first digit, and
+the `\fB*\fP' will match any others\&.  This is a trap for the unwary, but is
+in fact an inevitable consequence of the rule that the longest possible
+match always succeeds\&.  Expressions such as `\fB<0\-9>[^[:digit:]]*\fP' can be
+used instead\&.
+.RE
+.TP
+\fB(\fP\&.\&.\&.\fB)\fP
+Matches the enclosed pattern\&.  This is used for grouping\&.
+If the \fBKSH_GLOB\fP option is set, then a
+`\fB@\fP', `\fB*\fP', `\fB+\fP', `\fB?\fP' or `\fB!\fP' immediately preceding
+the `\fB(\fP' is treated specially, as detailed below\&. The option
+\fBSH_GLOB\fP prevents bare parentheses from being used in this way, though
+the \fBKSH_GLOB\fP option is still available\&.
+.RS
+.PP
+Note that grouping cannot extend over multiple directories: it is an error
+to have a `\fB/\fP' within a group (this only applies for patterns used in
+filename generation)\&.  There is one exception:  a group of the form
+\fB(\fP\fIpat\fP\fB/)#\fP appearing as a complete path segment can
+match a sequence of directories\&.  For example, \fBfoo/(a*/)#bar\fP matches
+\fBfoo/bar\fP, \fBfoo/any/bar\fP, \fBfoo/any/anyother/bar\fP, and so on\&.
+.RE
+.TP
+\fIx\fP\fB|\fP\fIy\fP
+Matches either \fIx\fP or \fIy\fP\&.
+This operator has lower precedence than any other\&.
+The `\fB|\fP' character
+must be within parentheses, to avoid interpretation as a pipeline\&.
+.TP
+\fB^\fP\fIx\fP
+(Requires \fBEXTENDED_GLOB\fP to be set\&.)
+Matches anything except the pattern \fIx\fP\&.
+This has a higher precedence than `\fB/\fP', so `\fB^foo/bar\fP'
+will search directories in `\fB\&.\fP' except `\fB\&./foo\fP'
+for a file named `\fBbar\fP'\&.
+.TP
+\fIx\fP\fB~\fP\fIy\fP
+(Requires \fBEXTENDED_GLOB\fP to be set\&.)
+Match anything that matches the pattern \fIx\fP but does not match \fIy\fP\&.
+This has lower precedence than any operator except `\fB|\fP', so
+`\fB*/*~foo/bar\fP' will search for all files in all directories in `\fB\&.\fP'
+and then exclude `\fBfoo/bar\fP' if there was such a match\&.
+Multiple patterns can be excluded by
+`\fIfoo\fP\fB~\fP\fIbar\fP\fB~\fP\fIbaz\fP'\&.
+In the exclusion pattern (\fIy\fP), `\fB/\fP' and `\fB\&.\fP' are not treated
+specially the way they usually are in globbing\&.
+.TP
+\fIx\fP\fB#\fP
+(Requires \fBEXTENDED_GLOB\fP to be set\&.)
+Matches zero or more occurrences of the pattern \fIx\fP\&.
+This operator has high precedence; `\fB12#\fP' is equivalent to `\fB1(2#)\fP',
+rather than `\fB(12)#\fP'\&.  It is an error for an unquoted `\fB#\fP' to follow
+something which cannot be repeated; this includes an empty string, a
+pattern already followed by `\fB##\fP', or parentheses when part of a
+\fBKSH_GLOB\fP pattern (for example, `\fB!(\fP\fIfoo\fP\fB)#\fP' is
+invalid and must be replaced by
+`\fB*(!(\fP\fIfoo\fP\fB))\fP')\&.
+.TP
+\fIx\fP\fB##\fP
+(Requires \fBEXTENDED_GLOB\fP to be set\&.)
+Matches one or more occurrences of the pattern \fIx\fP\&.
+This operator has high precedence; `\fB12##\fP' is equivalent to `\fB1(2##)\fP',
+rather than `\fB(12)##\fP'\&.  No more than two active `\fB#\fP' characters may
+appear together\&.
+.SS "ksh\-like Glob Operators"
+If the \fBKSH_GLOB\fP option is set, the effects of parentheses can be
+modified by a preceding `\fB@\fP', `\fB*\fP', `\fB+\fP', `\fB?\fP' or `\fB!\fP'\&.
+This character need not be unquoted to have special effects,
+but the `\fB(\fP' must be\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB@(\fP\&.\&.\&.\fB)\fP
+Match the pattern in the parentheses\&.  (Like `\fB(\fP\&.\&.\&.\fB)\fP'\&.)
+.TP
+\fB*(\fP\&.\&.\&.\fB)\fP
+Match any number of occurrences\&.  (Like `\fB(\fP\&.\&.\&.\fB)#\fP'\&.)
+.TP
+\fB+(\fP\&.\&.\&.\fB)\fP
+Match at least one occurrence\&.  (Like `\fB(\fP\&.\&.\&.\fB)##\fP'\&.)
+.TP
+\fB?(\fP\&.\&.\&.\fB)\fP
+Match zero or one occurrence\&.  (Like `\fB(|\fP\&.\&.\&.\fB)\fP'\&.)
+.TP
+\fB!(\fP\&.\&.\&.\fB)\fP
+Match anything but the expression in parentheses\&.
+(Like `\fB(^(\fP\&.\&.\&.\fB))\fP'\&.)
+.SS "Precedence"
+The precedence of the operators given above is (highest) `\fB^\fP', `\fB/\fP',
+`\fB~\fP', `\fB|\fP' (lowest); the
+remaining operators are simply treated from left to right as part of a
+string, with `\fB#\fP' and `\fB##\fP' applying to the shortest possible
+preceding unit (i\&.e\&. a character, `\fB?\fP', `\fB[\fP\&.\&.\&.\fB]\fP',
+`\fB<\fP\&.\&.\&.\fB>\fP', or a parenthesised expression)\&.  As mentioned
+above, a `\fB/\fP' used as a directory separator may not appear inside
+parentheses, while a `\fB|\fP' must do so; in patterns used in other contexts
+than filename generation (for example, in \fBcase\fP statements and tests
+within `\fB[[\fP\&.\&.\&.\fB]]\fP'), a `\fB/\fP' is not special; and `\fB/\fP' is also
+not special after a `\fB~\fP' appearing outside parentheses in a filename
+pattern\&.
+.SS "Globbing Flags"
+There are various flags which affect any text to their right up to the
+end of the enclosing group or to the end of the pattern; they require
+the \fBEXTENDED_GLOB\fP option\&. All take the form
+\fB(#\fP\fIX\fP\fB)\fP where \fIX\fP may have one of the following
+forms:
+.PP
+.PD 0
+.TP
+.PD
+i
+Case insensitive:  upper or lower case characters in the pattern match
+upper or lower case characters\&.
+.TP
+l
+Lower case characters in the pattern match upper or lower case
+characters; upper case characters in the pattern still only match
+upper case characters\&.
+.TP
+I
+Case sensitive:  locally negates the effect of \fBi\fP or \fBl\fP from
+that point on\&.
+.TP
+b
+Activate backreferences for parenthesised groups in the pattern;
+this does not work in filename generation\&.  When a pattern with a set of
+active parentheses is matched, the strings matched by the groups are
+stored in the array \fB$match\fP, the indices of the beginning of the matched
+parentheses in the array \fB$mbegin\fP, and the indices of the end in the array
+\fB$mend\fP, with the first element of each array corresponding to the first
+parenthesised group, and so on\&.  These arrays are not otherwise special to
+the shell\&.  The indices use the same convention as does parameter
+substitution, so that elements of \fB$mend\fP and \fB$mbegin\fP may be used in
+subscripts; the \fBKSH_ARRAYS\fP option is respected\&.  Sets of globbing flags
+are not considered parenthesised groups; only the first nine active
+parentheses can be referenced\&.
+.RS
+.PP
+For example,
+.PP
+.RS
+.nf
+\fBfoo="a string with a message"
+if [[ $foo = (a|an)' '(#b)(*)' '* ]]; then
+  print ${foo[$mbegin[1],$mend[1]]}
+fi\fP
+.fi
+.RE
+.PP
+prints `\fBstring with a\fP'\&.  Note that the first parenthesis is before the
+\fB(#b)\fP and does not create a backreference\&.
+.PP
+Backreferences work with all forms of pattern matching other than filename
+generation, but note that when performing matches on an entire array, such
+as \fB${\fP\fIarray\fP\fB#\fP\fIpattern\fP\fB}\fP, or a global substitution, such
+as \fB${\fP\fIparam\fP\fB//\fP\fIpat\fP\fB/\fP\fIrepl\fP\fB}\fP, only the data for the
+last match remains available\&.  In the case of global replacements this may
+still be useful\&.  See the example for the \fBm\fP flag below\&.
+.PP
+The numbering of backreferences strictly follows the order of the opening
+parentheses from left to right in the pattern string, although sets of
+parentheses may be nested\&.  There are special rules for parentheses followed
+by `\fB#\fP' or `\fB##\fP'\&.  Only the last match of the parenthesis is
+remembered: for example, in `\fB[[ abab = (#b)([ab])# ]]\fP', only the final
+`\fBb\fP' is stored in \fBmatch[1]\fP\&.  Thus extra parentheses may be necessary
+to match the complete segment: for example, use `\fBX((ab|cd)#)Y\fP' to match
+a whole string of either `\fBab\fP' or `\fBcd\fP' between `\fBX\fP' and `\fBY\fP',
+using the value of \fB$match[1]\fP rather than \fB$match[2]\fP\&.
+.PP
+If the match fails none of the parameters is altered, so in some cases it
+may be necessary to initialise them beforehand\&.  If some of the
+backreferences fail to match \-\-\- which happens if they are in an alternate
+branch which fails to match, or if they are followed by \fB#\fP and matched
+zero times \-\-\- then the matched string is set to the empty string, and the
+start and end indices are set to \-1\&.
+.PP
+Pattern matching with backreferences is slightly slower than without\&.
+.RE
+.TP
+B
+Deactivate backreferences, negating the effect of the \fBb\fP flag from that
+point on\&.
+.TP
+m
+Set references to the match data for the entire string matched; this is
+similar to backreferencing and does not work in filename generation\&.  The
+flag must be in effect at the end of the pattern, i\&.e\&. not local to a
+group\&. The parameters \fB$MATCH\fP,  \fB$MBEGIN\fP and \fB$MEND\fP will be set to
+the string matched and to the indices of the beginning and end of the
+string, respectively\&.  This is most useful in parameter substitutions, as
+otherwise the string matched is obvious\&.
+.RS
+.PP
+For example,
+.PP
+.RS
+.nf
+\fBarr=(veldt jynx grimps waqf zho buck)
+print ${arr//(#m)[aeiou]/${(U)MATCH}}\fP
+.fi
+.RE
+.PP
+forces all the matches (i\&.e\&. all vowels) into uppercase, printing
+`\fBvEldt jynx grImps wAqf zhO bUck\fP'\&.
+.PP
+Unlike backreferences, there is no speed penalty for using match
+references, other than the extra substitutions required for the
+replacement strings in cases such as the example shown\&.
+.RE
+.TP
+M
+Deactivate the \fBm\fP flag, hence no references to match data will be
+created\&.
+.TP
+\fBa\fP\fInum\fP
+Approximate matching: \fInum\fP errors are allowed in the string matched by
+the pattern\&.  The rules for this are described in the next subsection\&.
+.TP
+\fBs\fP, \fBe\fP
+Unlike the other flags, these have only a local effect, and each must
+appear on its own:  `\fB(#s)\fP' and `\fB(#e)\fP' are the only valid forms\&.
+The `\fB(#s)\fP' flag succeeds only at the start of the test string, and the
+`\fB(#e)\fP' flag succeeds only at the end of the test string; they
+correspond to `\fB^\fP' and `\fB$\fP' in standard regular expressions\&.  They
+are useful for matching path segments in patterns other than those in
+filename generation (where path segments are in any case treated
+separately)\&.  For example, `\fB*((#s)|/)test((#e)|/)*\fP' matches a path
+segment `\fBtest\fP' in any of the following strings: \fBtest\fP,
+\fBtest/at/start\fP, \fBat/end/test\fP, \fBin/test/middle\fP\&.
+.RS
+.PP
+Another use is in parameter substitution; for example
+`\fB${array/(#s)A*Z(#e)}\fP' will remove only elements of an array which
+match the complete pattern `\fBA*Z\fP'\&.  There are other ways of performing
+many operations of this type, however the combination of the substitution
+operations `\fB/\fP' and `\fB//\fP' with the `\fB(#s)\fP' and `\fB(#e)\fP' flags
+provides a single simple and memorable method\&.
+.PP
+Note that assertions of the form `\fB(^(#s))\fP' also work, i\&.e\&. match
+anywhere except at the start of the string, although this actually means
+`anything except a zero\-length portion at the start of the string'; you
+need to use `\fB(""~(#s))\fP' to match a zero\-length portion of the string
+not at the start\&.
+.RE
+.TP
+\fBq\fP
+A `\fBq\fP' and everything up to the closing parenthesis of the globbing
+flags are ignored by the pattern matching code\&.  This is intended to
+support the use of glob qualifiers, see below\&.  The result is that
+the pattern `\fB(#b)(*)\&.c(#q\&.)\fP' can be used both for globbing and for
+matching against a string\&.  In the former case, the `\fB(#q\&.)\fP' will be
+treated as a glob qualifier and the `\fB(#b)\fP' will not be useful, while in
+the latter case the `\fB(#b)\fP' is useful for backreferences and the
+`\fB(#q\&.)\fP' will be ignored\&.  Note that colon modifiers in the glob
+qualifiers are also not applied in ordinary pattern matching\&.
+.PP
+For example, the test string \fBfooxx\fP can be matched by the pattern
+\fB(#i\fP\fB)FOOXX\fP, but not by \fB(#l\fP\fB)FOOXX\fP,
+\fB(#i\fP\fB)FOO\fP\fB(#I\fP\fB)XX\fP or
+\fB((#i\fP\fB)FOOX\fP\fB)X\fP\&.  The string
+\fB(#ia2\fP\fB)readme\fP specifies case\-insensitive matching of
+\fBreadme\fP with up to two errors\&.
+.PP
+When using the ksh syntax for grouping both \fBKSH_GLOB\fP and
+\fBEXTENDED_GLOB\fP must be set and the left parenthesis should be
+preceded by \fB@\fP\&.  Note also that the flags do not affect letters
+inside \fB[\&.\&.\&.]\fP groups, in other words \fB(#i\fP\fB)[a\-z]\fP
+still matches only lowercase letters\&.  Finally, note that when
+examining whole paths case\-insensitively every directory must be
+searched for all files which match, so that a pattern of the form
+\fB(#i\fP\fB)/foo/bar/\&.\&.\&.\fP is potentially slow\&.
+.PP
+.SS "Approximate Matching"
+When matching approximately, the shell keeps a count of the errors found,
+which cannot exceed the number specified in the
+\fB(#a\fP\fInum\fP\fB)\fP flags\&.  Four types of error are recognised:
+.PP
+.PD 0
+.TP
+.PD
+1\&.
+Different characters, as in \fBfooxbar\fP and \fBfooybar\fP\&.
+.TP
+2\&.
+Transposition of characters, as in \fBbanana\fP and \fBabnana\fP\&.
+.TP
+3\&.
+A character missing in the target string, as with the pattern \fBroad\fP and
+target string \fBrod\fP\&.
+.TP
+4\&.
+An extra character appearing in the target string, as with \fBstove\fP
+and \fBstrove\fP\&.
+.PP
+Thus, the pattern \fB(#a3\fP\fB)abcd\fP matches \fBdcba\fP, with the
+errors occurring by using the first rule twice and the second once,
+grouping the string as \fB[d][cb][a]\fP and \fB[a][bc][d]\fP\&.
+.PP
+Non\-literal parts of the pattern must match exactly, including characters
+in character ranges: hence \fB(#a1\fP\fB)???\fP  matches strings of
+length four, by applying rule 4 to an empty part of the pattern, but not
+strings of length two, since all the \fB?\fP must match\&.  Other characters
+which must match exactly are initial dots in filenames (unless the
+\fBGLOB_DOTS\fP option is set), and all slashes in filenames, so that
+\fBa/bc\fP is two errors from \fBab/c\fP (the slash cannot be transposed with
+another character)\&.  Similarly, errors are counted separately for
+non\-contiguous strings in the pattern, so that \fB(ab|cd\fP\fB)ef\fP
+is two errors from \fBaebf\fP\&.
+.PP
+When using exclusion via the \fB~\fP operator, approximate matching is
+treated entirely separately for the excluded part and must be activated
+separately\&.  Thus, \fB(#a1\fP\fB)README~READ_ME\fP matches
+\fBREAD\&.ME\fP but not \fBREAD_ME\fP, as the trailing \fBREAD_ME\fP is matched
+without approximation\&.  However,
+\fB(#a1\fP\fB)README~(#a1\fP\fB)READ_ME\fP
+does not match any pattern of the form \fBREAD\fP\fI?\fP\fBME\fP as all
+such forms are now excluded\&.
+.PP
+Apart from exclusions, there is only one overall error count; however, the
+maximum errors allowed may be altered locally, and this can be delimited by
+grouping\&.  For example,
+\fB(#a1\fP\fB)cat\fP\fB((#a0\fP\fB)dog\fP\fB)fox\fP
+allows one error in total, which may not occur in the \fBdog\fP section, and
+the pattern
+\fB(#a1\fP\fB)cat\fP\fB(#a0\fP\fB)dog\fP\fB(#a1\fP\fB)fox\fP
+is equivalent\&.  Note that the point at which an error is first found is the
+crucial one for establishing whether to use approximation; for example,
+\fB(#a1)abc(#a0)xyz\fP will not match \fBabcdxyz\fP, because the error occurs
+at the `\fBx\fP', where approximation is turned off\&.
+.PP
+Entire path segments may be matched approximately, so that
+`\fB(#a1)/foo/d/is/available/at/the/bar\fP' allows one error in any path
+segment\&.  This is much less efficient than without the \fB(#a1)\fP, however,
+since every directory in the path must be scanned for a possible
+approximate match\&.  It is best to place the \fB(#a1)\fP after any path
+segments which are known to be correct\&.
+.PP
+.SS "Recursive Globbing"
+A pathname component of the form `\fB(\fP\fIfoo\fP\fB/)#\fP'
+matches a path consisting of zero or more directories
+matching the pattern \fIfoo\fP\&.
+.PP
+As a shorthand, `\fB**/\fP' is equivalent to `\fB(*/)#\fP'; note that this
+therefore matches files in the current directory as well as
+subdirectories\&.
+Thus:
+.PP
+.RS
+.nf
+\fBls (*/)#bar\fP
+.fi
+.RE
+.PP
+or
+.PP
+.RS
+.nf
+\fBls **/bar\fP
+.fi
+.RE
+.PP
+does a recursive directory search for files named `\fBbar\fP' (potentially
+including the file `\fBbar\fP' in the current directory)\&.  This form does not
+follow symbolic links; the alternative form `\fB***/\fP' does, but is
+otherwise identical\&.  Neither of these can be combined with other forms of
+globbing within the same path segment; in that case, the `\fB*\fP'
+operators revert to their usual effect\&.
+.SS "Glob Qualifiers"
+Patterns used for filename generation may end in a
+list of qualifiers enclosed in parentheses\&.
+The qualifiers specify which filenames that otherwise match the given pattern
+will be inserted in the argument list\&.
+.PP
+If the option \fBBARE_GLOB_QUAL\fP is set, then a trailing set of parentheses
+containing no `\fB|\fP' or `\fB(\fP' characters (or `\fB~\fP' if it is special)
+is taken as a set of
+glob qualifiers\&.  A glob subexpression that would normally be taken as glob
+qualifiers, for example `\fB(^x)\fP', can be forced to be treated as part of
+the glob pattern by doubling the parentheses, in this case producing
+`\fB((^x))\fP'\&.
+.PP
+If the option \fBEXTENDED_GLOB\fP is set, a different syntax for glob
+qualifiers is available, namely `\fB(#qx)\fP' where \fBx\fP is any of the same
+glob qualifiers used in the other format\&.  The qualifiers must still appear
+at the end of the pattern\&.  However, with this syntax multiple glob
+qualifiers may be chained together\&.  They are treated as a logical AND of
+the individual sets of flags\&.  Also, as the syntax is unambiguous, the
+expression will be treated as glob qualifiers just as long any parentheses
+contained within it are balanced; appearance of `\fB|\fP', `\fB(\fP' or
+`\fB~\fP' does not negate the effect\&.  Note that qualifiers will be
+recognised in this form even if a bare glob qualifier exists at the end of
+the pattern, for example `\fB*(#q*)(\&.)\fP' will recognise executable regular
+files if both options are set; however, mixed syntax should probably be
+avoided for the sake of clarity\&.
+.PP
+A qualifier may be any one of the following:
+.PP
+.PD 0
+.TP
+.PD
+\fB/\fP
+directories
+.TP
+\fBF\fP
+`full' (i\&.e\&. non\-empty) directories\&.  Note that the
+opposite sense \fB(^F\fP\fB)\fP expands to empty directories
+and all non\-directories\&.  Use \fB(/^F\fP\fB)\fP for
+empty directories
+.TP
+\fB\&.\fP
+plain files
+.TP
+\fB@\fP
+symbolic links
+.TP
+\fB=\fP
+sockets
+.TP
+\fBp\fP
+named pipes (FIFOs)
+.TP
+\fB*\fP
+executable plain files (0100)
+.TP
+\fB%\fP
+device files (character or block special)
+.TP
+\fB%b\fP
+block special files
+.TP
+\fB%c\fP
+character special files
+.TP
+\fBr\fP
+owner\-readable files (0400)
+.TP
+\fBw\fP
+owner\-writable files (0200)
+.TP
+\fBx\fP
+owner\-executable files (0100)
+.TP
+\fBA\fP
+group\-readable files (0040)
+.TP
+\fBI\fP
+group\-writable files (0020)
+.TP
+\fBE\fP
+group\-executable files (0010)
+.TP
+\fBR\fP
+world\-readable files (0004)
+.TP
+\fBW\fP
+world\-writable files (0002)
+.TP
+\fBX\fP
+world\-executable files (0001)
+.TP
+\fBs\fP
+setuid files (04000)
+.TP
+\fBS\fP
+setgid files (02000)
+.TP
+\fBt\fP
+files with the sticky bit (01000)
+.TP
+\fBf\fP\fIspec\fP
+files with access rights matching \fIspec\fP\&. This \fIspec\fP may be a
+octal number optionally preceded by a `\fB=\fP', a `\fB+\fP', or a
+`\fB\-\fP'\&. If none of these characters is given, the behavior is the
+same as for `\fB=\fP'\&. The octal number describes the mode bits to be
+expected, if combined with a `\fB=\fP', the value given must match the
+file\-modes exactly, with a `\fB+\fP', at least the bits in the
+given number must be set in the file\-modes, and with a `\fB\-\fP', the
+bits in the number must not be set\&. Giving a `\fB?\fP' instead of a
+octal digit anywhere in the number ensures that the corresponding bits 
+in the file\-modes are not checked, this is only useful in combination
+with `\fB=\fP'\&.
+.RS
+.PP
+If the qualifier `\fBf\fP' is followed by any other character anything
+up to the next matching character (`\fB[\fP', `\fB{\fP', and `\fB<\fP' match 
+`\fB]\fP', `\fB}\fP', and `\fB>\fP' respectively, any other character
+matches itself) is taken as a list of comma\-separated
+\fIsub\-spec\fPs\&. Each \fIsub\-spec\fP may be either an octal number as
+described above or a list of any of the characters `\fBu\fP', `\fBg\fP',
+`\fBo\fP', and `\fBa\fP', followed by a `\fB=\fP', a `\fB+\fP', or a
+`\fB\-\fP', followed by a list of any of the characters `\fBr\fP', `\fBw\fP', 
+`\fBx\fP', `\fBs\fP', and `\fBt\fP', or an octal digit\&. The first list of
+characters specify which access rights are to be checked\&. If a `\fBu\fP'
+is given, those for the owner of the file are used, if a `\fBg\fP' is
+given, those of the group are checked, a `\fBo\fP' means to test those
+of other users, and the `\fBa\fP' says to test all three groups\&. The
+`\fB=\fP', `\fB+\fP', and `\fB\-\fP' again says how the modes are to be
+checked and have the same meaning as described for the first form
+above\&. The second list of characters finally says which access rights
+are to be expected: `\fBr\fP' for read access, `\fBw\fP' for write access, 
+`\fBx\fP' for the right to execute the file (or to search a directory),
+`\fBs\fP' for the setuid and setgid bits, and `\fBt\fP' for the sticky
+bit\&.
+.PP
+Thus, `\fB*(f70?)\fP' gives the files for which the owner has read,
+write, and execute permission, and for which other group members have
+no rights, independent of the permissions for other users\&. The pattern
+`\fB*(f\-100)\fP' gives all files for which the owner does not have
+execute permission, and `\fB*(f:gu+w,o\-rx:)\fP' gives the files for which 
+the owner and the other members of the group have at least write
+permission, and for which other users don't have read or execute
+permission\&.
+.RE
+.TP
+\fBe\fP\fIstring\fP
+The \fIstring\fP will be executed as shell code\&.  The filename will be
+included in the list if and only if the code returns a zero status (usually
+the status of the last command)\&.  The first character after the `\fBe\fP'
+will be used as a separator and anything up to the next matching separator
+will be taken  as the \fIstring\fP; `\fB[\fP', `\fB{\fP', and `\fB<\fP' match
+`\fB]\fP', `\fB}\fP', and `\fB>\fP', respectively, while any other character
+matches itself\&. Note that expansions must be quoted in the \fIstring\fP
+to prevent them from being expanded before globbing is done\&.
+.RS
+.PP
+During the execution of \fIstring\fP the filename currently being tested is
+available in the parameter \fBREPLY\fP; the parameter may be altered to
+a string to be inserted into the list instead of the original
+filename\&.  In addition, the parameter \fBreply\fP may be set to an array or a
+string, which overrides the value of \fBREPLY\fP\&.  If set to an array, the
+latter is inserted into the command line word by word\&.
+.PP
+For example, suppose a directory contains a single file `\fBlonely\fP'\&.  Then
+the expression `\fB*(e:'reply=(${REPLY}{1,2})':)\fP' will cause the words
+`\fBlonely1 lonely2\fP' to be inserted into the command line\&.  Note the
+quotation marks\&.
+.RE
+.TP
+\fBd\fP\fIdev\fP
+files on the device \fIdev\fP
+.TP
+\fBl\fP[\fB\-\fP|\fB+\fP]\fIct\fP
+files having a link count less than \fIct\fP (\fB\-\fP), greater than
+\fIct\fP (\fB+\fP), or equal to \fIct\fP
+.TP
+\fBU\fP
+files owned by the effective user ID
+.TP
+\fBG\fP
+files owned by the effective group ID
+.TP
+\fBu\fP\fIid\fP
+files owned by user ID \fIid\fP if it is a number, if not, than the
+character after the `\fBu\fP' will be used as a separator and the string
+between it and the next matching separator
+(`\fB[\fP', `\fB{\fP', and `\fB<\fP'
+match `\fB]\fP', `\fB}\fP', and `\fB>\fP' respectively,
+any other character matches
+itself) will be taken as a user name, and the user ID of this user will
+be taken (e\&.g\&. `\fBu:foo:\fP' or `\fBu[foo]\fP' for user `\fBfoo\fP')
+.TP
+\fBg\fP\fIid\fP
+like \fBu\fP\fIid\fP but with group IDs or names
+.TP
+\fBa\fP[\fBMwhms\fP][\fB\-\fP|\fB+\fP]\fIn\fP
+files accessed exactly \fIn\fP days ago\&.  Files accessed within the last
+\fIn\fP days are selected using a negative value for \fIn\fP (\fB\-\fP\fIn\fP)\&.
+Files accessed more than \fIn\fP days ago are selected by a positive \fIn\fP
+value (\fB+\fP\fIn\fP)\&.  Optional unit specifiers `\fBM\fP', `\fBw\fP',
+`\fBh\fP', `\fBm\fP' or `\fBs\fP' (e\&.g\&. `\fBah5\fP') cause the check to be
+performed with months (of 30 days), weeks, hours, minutes or seconds
+instead of days, respectively\&.  For instance, `\fBecho *(ah\-5)\fP' would
+echo files accessed within the last five hours\&.
+.TP
+\fBm\fP[\fBMwhms\fP][\fB\-\fP|\fB+\fP]\fIn\fP
+like the file access qualifier, except that it uses the file modification
+time\&.
+.TP
+\fBc\fP[\fBMwhms\fP][\fB\-\fP|\fB+\fP]\fIn\fP
+like the file access qualifier, except that it uses the file inode change
+time\&.
+.TP
+\fBL\fP[\fB+\fP|\fB\-\fP]\fIn\fP
+files less than \fIn\fP bytes (\fB\-\fP), more than \fIn\fP bytes (\fB+\fP), or
+exactly \fIn\fP bytes in length\&. If this flag is directly followed by a `\fBk\fP'
+(`\fBK\fP'), `\fBm\fP' (`\fBM\fP'), or `\fBp\fP' (`\fBP\fP') (e\&.g\&. `\fBLk\-50\fP')
+the check is performed with kilobytes, megabytes, or blocks (of 512 bytes)
+instead\&.
+.TP
+\fB^\fP
+negates all qualifiers following it
+.TP
+\fB\-\fP
+toggles between making the qualifiers work on symbolic links (the
+default) and the files they point to
+.TP
+\fBM\fP
+sets the \fBMARK_DIRS\fP option for the current pattern
+.TP
+\fBT\fP
+appends a trailing qualifier mark to the filenames, analogous to the
+\fBLIST_TYPES\fP option, for the current pattern (overrides \fBM\fP)
+.TP
+\fBN\fP
+sets the \fBNULL_GLOB\fP option for the current pattern
+.TP
+\fBD\fP
+sets the \fBGLOB_DOTS\fP option for the current pattern
+.TP
+\fBn\fP
+sets the \fBNUMERIC_GLOB_SORT\fP option for the current pattern
+.TP
+\fBo\fP\fIc\fP
+specifies how the names of the files should be sorted\&. If \fIc\fP is
+\fBn\fP they are sorted by name (the default); if it is \fBL\fP they
+are sorted depending on the size (length) of the files; if \fBl\fP 
+they are sorted by the number of links; if \fBa\fP, \fBm\fP, or \fBc\fP
+they are sorted by the time of the last access, modification, or
+inode change respectively; if \fBd\fP, files in subdirectories appear before
+those in the current directory at each level of the search \-\-\- this is best
+combined with other criteria, for example `\fBodon\fP' to sort on names for
+files within the same directory\&.  Note that \fBa\fP, \fBm\fP, and \fBc\fP compare
+the age against the current time, hence the first name in the list is the
+youngest file\&. Also note that the modifiers \fB^\fP and \fB\-\fP are used,
+so `\fB*(^\-oL)\fP' gives a list of all files sorted by file size in descending
+order, following any symbolic links\&.
+.TP
+\fBO\fP\fIc\fP
+like `\fBo\fP', but sorts in descending order; i\&.e\&. `\fB*(^oc)\fP' is the
+same as `\fB*(Oc)\fP' and `\fB*(^Oc)\fP' is the same as `\fB*(oc)\fP'; `\fBOd\fP'
+puts files in the current directory before those in subdirectories at each
+level of the search\&.
+.TP
+\fB[\fP\fIbeg\fP[\fB,\fP\fIend\fP]\fB]\fP
+specifies which of the matched filenames should be included in the
+returned list\&. The syntax is the same as for array
+subscripts\&. \fIbeg\fP and the optional \fIend\fP may be mathematical
+expressions\&. As in parameter subscripting they may be negative to make 
+them count from the last match backward\&. E\&.g\&.: `\fB*(\-OL[1,3])\fP'
+gives a list of the names of the three largest files\&.
+.PP
+More than one of these lists can be combined, separated by commas\&. The
+whole list matches if at least one of the sublists matches (they are
+`or'ed, the qualifiers in the sublists are `and'ed)\&.  Some qualifiers,
+however, affect all matches generated, independent of the sublist in
+which they are given\&.  These are the qualifiers `\fBM\fP', `\fBT\fP',
+`\fBN\fP', `\fBD\fP', `\fBn\fP', `\fBo\fP', `\fBO\fP' and the subscripts given
+in brackets (`\fB[\&.\&.\&.]\fP')\&.
+.PP
+If a `\fB:\fP' appears in a qualifier list, the remainder of the expression in
+parenthesis is interpreted as a modifier (see the section `Modifiers'
+in the section `History Expansion')\&.  Note that
+each modifier must be introduced by a separate `\fB:\fP'\&.  Note also that the
+result after modification does not have to be an existing file\&.  The
+name of any existing file can be followed by a modifier of the form
+`\fB(:\&.\&.)\fP' even if no actual filename generation is performed\&.
+Thus:
+.PP
+.RS
+.nf
+\fBls *(\-/)\fP
+.fi
+.RE
+.PP
+lists all directories and symbolic links that point to directories,
+and
+.PP
+.RS
+.nf
+\fBls *(%W)\fP
+.fi
+.RE
+.PP
+lists all world\-writable device files in the current directory, and
+.PP
+.RS
+.nf
+\fBls *(W,X)\fP
+.fi
+.RE
+.PP
+lists all files in the current directory that are
+world\-writable or world\-executable, and
+.PP
+.RS
+.nf
+\fBecho /tmp/foo*(u0^@:t)\fP
+.fi
+.RE
+.PP
+outputs the basename of all root\-owned files beginning with the string
+`\fBfoo\fP' in \fB/tmp\fP, ignoring symlinks, and
+.PP
+.RS
+.nf
+\fBls *\&.*~(lex|parse)\&.[ch](^D^l1)\fP
+.fi
+.RE
+.PP
+lists all files having a link count of one whose names contain a dot
+(but not those starting with a dot, since \fBGLOB_DOTS\fP is explicitly
+switched off) except for \fBlex\&.c\fP, \fBlex\&.h\fP, \fBparse\&.c\fP and \fBparse\&.h\fP\&.
+.PP
+.RS
+.nf
+\fBprint b*\&.pro(#q:s/pro/shmo/)(#q\&.:s/builtin/shmiltin/)\fP
+.fi
+.RE
+.PP
+demonstrates how colon modifiers and other qualifiers may be chained
+together\&.  The ordinary qualifier `\fB\&.\fP' is applied first, then the colon
+modifiers in order from left to right\&.  So if \fBEXTENDED_GLOB\fP is set and
+the base pattern matches the regular file \fBbuiltin\&.pro\fP, the shell will
+print `\fBshmiltin\&.shmo\fP'\&.
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshmisc.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshmisc.1
@@ -0,0 +1,1888 @@
+.TH "ZSHMISC" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshmisc \- everything and then some
+.\" Yodl file: Zsh/grammar.yo
+.SH "SIMPLE COMMANDS & PIPELINES"
+A \fIsimple command\fP is a sequence of optional parameter
+assignments followed by blank\-separated words,
+with optional redirections interspersed\&.
+The first word is the command to be executed, and the remaining
+words, if any, are arguments to the command\&.
+If a command name is given, the parameter assignments modify
+the environment of the command when it is executed\&.
+The value of a simple command is its exit status,
+or 128 plus the signal number if terminated by a signal\&.
+For example,
+.PP
+.RS
+.nf
+\fBecho foo\fP
+.fi
+.RE
+.PP
+is a simple command with arguments\&.
+.PP
+A \fIpipeline\fP is either a simple command, or a sequence of two or more
+simple commands where each command is separated from the next by `\fB|\fP'
+or `\fB|&\fP'\&.  Where commands are separated by `\fB|\fP', the standard
+output of the first command is connected to the
+standard input of the next\&.  `\fB|&\fP' is shorthand for `\fB2>&1 |\fP', which
+connects both the standard output and the standard error of the
+command to the standard input of the next\&.  The value of a pipeline
+is the value of the last command, unless the pipeline is preceded by
+`\fB!\fP' in which case the value is the logical inverse of the value of the
+last command\&.
+For example,
+.PP
+.RS
+.nf
+\fBecho foo | sed 's/foo/bar/'\fP
+.fi
+.RE
+.PP
+is a pipeline, where the output (`\fBfoo\fP' plus a newline) of the first
+command will be passed to the input of the second\&.
+.PP
+If a pipeline is preceded by `\fBcoproc\fP', it is executed as a coprocess;
+a two\-way pipe is established between it and the parent shell\&.  The
+shell can read from or write to the coprocess by means of the `\fB>&p\fP'
+and `\fB<&p\fP' redirection operators or with `\fBprint \-p\fP' and `\fBread \-p\fP'\&.
+A pipeline cannot be preceded by both `\fBcoproc\fP' and `\fB!\fP'\&.
+If job control is active, the coprocess can be treated in other than input
+and output as an ordinary background job\&.
+.PP
+A \fIsublist\fP is either a single pipeline, or a sequence of two or more
+pipelines separated by `\fB&&\fP' or `\fB||\fP'\&.  If two pipelines are separated
+by `\fB&&\fP', the second pipeline is executed only if the first succeeds
+(returns a zero value)\&.  If two pipelines are separated by `\fB||\fP', the
+second is executed only if the first fails (returns a nonzero value)\&.
+Both operators have equal precedence and are left associative\&.
+The value of the sublist is the value of the last pipeline executed\&.
+For example,
+.PP
+.RS
+.nf
+\fBdmesg | grep panic && print yes\fP
+.fi
+.RE
+.PP
+is a sublist consisting of two pipelines, the second just a simple command
+which will be executed if and only if the \fBgrep\fP command returns a zero
+value\&.  If it does not, the value of the sublist is that return value, else
+it is the value returned by the \fBprint\fP (almost certainly zero)\&.
+.PP
+A \fIlist\fP is a sequence of zero or more sublists, in which each sublist
+is terminated by `\fB;\fP', `\fB&\fP', `\fB&|\fP', `\fB&!\fP', or a newline\&.
+This terminator
+may optionally be omitted from the last sublist in the list when the
+list appears as a complex command inside `\fB(\fP\&.\&.\&.\fB)\fP'
+or `\fB{\fP\&.\&.\&.\fB}\fP'\&.  When a
+sublist is terminated by `\fB;\fP' or newline, the shell waits for it to
+finish before executing the next sublist\&.  If a sublist is terminated
+by a `\fB&\fP', `\fB&|\fP', or `\fB&!\fP',
+the shell executes the last pipeline in it in the background, and
+does not wait for it to finish (note the difference from other shells
+which execute the whole sublist in the background)\&.
+A backgrounded pipeline returns a status of zero\&.
+.PP
+More generally, a list can be seen as a set of any shell commands
+whatsoever, including the complex commands below; this is implied wherever
+the word `list' appears in later descriptions\&.  For example, the commands
+in a shell function form a special sort of list\&.
+.SH "PRECOMMAND MODIFIERS"
+A simple command may be preceded by a \fIprecommand modifier\fP,
+which will alter how the command is interpreted\&.  These modifiers are
+shell builtin commands with the exception of \fBnocorrect\fP which is
+a reserved word\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB\-\fP
+The command is executed with a `\fB\-\fP' prepended to its
+\fBargv[0]\fP string\&.
+.TP
+\fBnoglob\fP
+Filename generation (globbing) is not performed on any of
+the words\&.
+.TP
+\fBnocorrect\fP
+Spelling correction is not done on any of the words\&.  This must appear
+before any other precommand modifier, as it is interpreted immediately,
+before any parsing is done\&.  It has no effect in non\-interactive shells\&.
+.TP
+\fBexec\fP
+The command is executed in the parent shell without forking\&.
+.TP
+\fBcommand\fP
+The command word is taken to be the name of an external command,
+rather than a shell function or builtin\&.
+.TP
+\fBbuiltin\fP
+The command word is taken to be the name of a builtin command,
+rather than a shell function or external command\&.
+.SH "COMPLEX COMMANDS"
+A \fIcomplex command\fP in zsh is one of the following:
+.PP
+.PD 0
+.TP
+.PD
+\fBif\fP \fIlist\fP \fBthen\fP \fIlist\fP [ \fBelif\fP \fIlist\fP \fBthen\fP \fIlist\fP ] \&.\&.\&. [ \fBelse\fP \fIlist\fP ] \fBfi\fP
+The \fBif\fP \fIlist\fP is executed, and if it returns a zero exit status,
+the \fBthen\fP \fIlist\fP is executed\&.
+Otherwise, the \fBelif\fP \fIlist\fP is executed and if its value is zero,
+the \fBthen\fP \fIlist\fP is executed\&.
+If each \fBelif\fP \fIlist\fP returns nonzero, the \fBelse\fP \fIlist\fP is executed\&.
+.TP
+\fBfor\fP \fIname\fP \&.\&.\&. [ \fBin\fP \fIword\fP \&.\&.\&. ] \fIterm\fP \fBdo\fP \fIlist\fP \fBdone\fP
+where \fIterm\fP is at least one newline or \fB;\fP\&.
+Expand the list of \fIword\fPs, and set the parameter
+\fIname\fP to each of them in turn, executing
+\fIlist\fP each time\&.  If the \fBin\fP \fIword\fP is omitted,
+use the positional parameters instead of the \fIword\fPs\&.
+.RS
+.PP
+More than one parameter \fIname\fP can appear before the list of
+\fIword\fPs\&.  If \fIN\fP \fIname\fPs are given, then on each execution of the
+loop the next \fBN\fP \fIword\fPs are assigned to the corresponding
+parameters\&.  If there are more \fIname\fPs than remaining \fIword\fPs, the
+remaining parameters are each set to the empty string\&.  Execution of the
+loop ends when there is no remaining \fIword\fP to assign to the first
+\fIname\fP\&.  It is only possible for \fBin\fP to appear as the first \fIname\fP
+in the list, else it will be treated as marking the end of the list\&.
+.RE
+.TP
+\fBfor ((\fP [\fIexpr1\fP] \fB;\fP [\fIexpr2\fP] \fB;\fP [\fIexpr3\fP] \fB)) do\fP \fIlist\fP \fBdone\fP
+The arithmetic expression \fIexpr1\fP is evaluated first (see
+the section `Arithmetic Evaluation')\&.  The arithmetic expression
+\fIexpr2\fP is repeatedly evaluated until it evaluates to zero and
+when non\-zero, \fIlist\fP is executed and the arithmetic expression
+\fIexpr3\fP evaluated\&.  If any expression is omitted, then it behaves
+as if it evaluated to 1\&.
+.TP
+\fBwhile\fP \fIlist\fP \fBdo\fP \fIlist\fP \fBdone\fP
+Execute the \fBdo\fP \fIlist\fP as long as the \fBwhile\fP \fIlist\fP
+returns a zero exit status\&.
+.TP
+\fBuntil\fP \fIlist\fP \fBdo\fP \fIlist\fP \fBdone\fP
+Execute the \fBdo\fP \fIlist\fP as long as \fBuntil\fP \fIlist\fP
+returns a nonzero exit status\&.
+.TP
+\fBrepeat\fP \fIword\fP \fBdo\fP \fIlist\fP \fBdone\fP
+\fIword\fP is expanded and treated as an arithmetic expression,
+which must evaluate to a number \fIn\fP\&.
+\fIlist\fP is then executed \fIn\fP times\&.
+.TP
+\fBcase\fP \fIword\fP \fBin\fP [ [\fB(\fP] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \&.\&.\&. \fB)\fP \fIlist\fP (\fB;;\fP|\fB;&\fP) ] \&.\&.\&. \fBesac\fP
+Execute the \fIlist\fP associated with the first \fIpattern\fP
+that matches \fIword\fP, if any\&.  The form of the patterns
+is the same as that used for filename generation\&.  See
+the section `Filename Generation'\&.
+If the \fIlist\fP that is executed is terminated with \fB;&\fP rather than
+\fB;;\fP, the following list is also executed\&.  This continues until either
+a list is terminated with \fB;;\fP or the \fBesac\fP is reached\&.
+.TP
+\fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP \&.\&.\&. \fIterm\fP ] \fBdo\fP \fIlist\fP \fBdone\fP
+where \fIterm\fP is one or more newline or \fB;\fP to terminate the \fIword\fPs\&.
+Print the set of \fIword\fPs, each preceded by a number\&.
+If the \fBin\fP \fIword\fP is omitted, use the positional parameters\&.
+The \fBPROMPT3\fP prompt is printed and a line is read from the line editor
+if the shell is interactive and that is active, or else standard input\&.
+If this line consists of the
+number of one of the listed \fIword\fPs, then the parameter \fIname\fP
+is set to the \fIword\fP corresponding to this number\&.
+If this line is empty, the selection list is printed again\&.
+Otherwise, the value of the parameter \fIname\fP is set to null\&.
+The contents of the line read from standard input is saved
+in the parameter \fBREPLY\fP\&.  \fIlist\fP is executed
+for each selection until a break or end\-of\-file is encountered\&.
+.TP
+\fB(\fP \fIlist\fP \fB)\fP
+Execute \fIlist\fP in a subshell\&.  Traps set by the \fBtrap\fP builtin
+are reset to their default values while executing \fIlist\fP\&.
+.TP
+\fB{\fP \fIlist\fP \fB}\fP
+Execute \fIlist\fP\&.
+.TP
+\fB{\fP \fItry\-list\fP \fB} always {\fP \fIalways\-list\fP \fB}\fP
+First execute \fItry\-list\fP\&.  Regardless of errors, or \fBbreak\fP,
+\fBcontinue\fP, or \fBreturn\fP commands encountered within \fItry\-list\fP,
+execute \fIalways\-list\fP\&.  Execution then continues from the
+result of the execution of \fItry\-list\fP; in other words, any error,
+or \fBbreak\fP, \fBcontinue\fP, or \fBreturn\fP command is treated in the
+normal way, as if \fIalways\-list\fP were not present\&.  The two
+chunks of code are referred to as the `try block' and the `always block'\&.
+.RS
+.PP
+Optional newlines or semicolons may appear after the \fBalways\fP;
+note, however, that they may \fInot\fP appear between the preceeding
+closing brace and the \fBalways\fP\&.
+.PP
+An `error' in this context is a condition such as a syntax error which
+causes the shell to abort execution of the current function, script, or
+list\&.  Syntax errors encountered while the shell is parsing the
+code do not cause the \fIalways\-list\fP to be executed\&.  For example,
+an erroneously constructed \fBif\fP block in \fBtry\-list\fP would cause the
+shell to abort during parsing, so that \fBalways\-list\fP would not be
+executed, while an erroneous substitution such as \fB${*foo*}\fP would
+cause a run\-time error, after which \fBalways\-list\fP would be executed\&.
+.PP
+An error condition can be tested and reset with the special integer
+variable \fBTRY_BLOCK_ERROR\fP\&.  Outside an \fBalways\-list\fP the value is
+irrelevant, but it is initialised to \fB\-1\fP\&.  Inside \fBalways\-list\fP, the
+value is 1 if an error occurred in the \fBtry\-list\fP, else 0\&.  If
+\fBTRY_BLOCK_ERROR\fP is set to 0 during the \fBalways\-list\fP, the error
+condition caused by the \fBtry\-list\fP is reset, and shell execution
+continues normally after the end of \fBalways\-list\fP\&.  Altering the value
+during the \fBtry\-list\fP is not useful (unless this forms part of an
+enclosing \fBalways\fP block)\&.
+.PP
+Regardless of \fBTRY_BLOCK_ERROR\fP, after the end of \fBalways\-list\fP the
+normal shell status \fB$?\fP is the value returned from \fBalways\-list\fP\&.
+This will be non\-zero if there was an error, even if \fBTRY_BLOCK_ERROR\fP
+was set to zero\&.
+.PP
+The following executes the given code, ignoring any errors it causes\&.
+This is an alternative to the usual convention of protecting code by
+executing it in a subshell\&.
+.PP
+.RS
+.nf
+\fB{
+    # code which may cause an error
+  } always {
+    # This code is executed regardless of the error\&.
+    (( TRY_BLOCK_ERROR = 0 ))
+}
+# The error condition has been reset\&.\fP
+.fi
+.RE
+.PP
+An \fBexit\fP command encountered in \fBtry\-list\fP does \fInot\fP cause the
+execution of \fIalways\-list\fP\&.  Instead, the shell exits immediately
+after any \fBEXIT\fP trap has been executed\&.
+.RE
+.TP
+.PD 0
+\fBfunction\fP \fIword\fP \&.\&.\&. [ \fB()\fP ] [ \fIterm\fP ] \fB{\fP \fIlist\fP \fB}\fP
+.TP
+.PD 0
+\fIword\fP \&.\&.\&. \fB()\fP [ \fIterm\fP ] \fB{\fP \fIlist\fP \fB}\fP
+.TP
+.PD
+\fIword\fP \&.\&.\&. \fB()\fP [ \fIterm\fP ] \fIcommand\fP
+where \fIterm\fP is one or more newline or \fB;\fP\&.
+Define a function which is referenced by any one of \fIword\fP\&.
+Normally, only one \fIword\fP is provided; multiple \fIword\fPs
+are usually only useful for setting traps\&.
+The body of the function is the \fIlist\fP between
+the \fB{\fP and \fB}\fP\&.  See the section `Functions'\&.
+.RS
+.PP
+If the option \fBSH_GLOB\fP is set for compatibility with other shells, then
+whitespace may appear between between the left and right parentheses when
+there is a single \fIword\fP;  otherwise, the parentheses will be treated as
+forming a globbing pattern in that case\&.
+.RE
+.TP
+\fBtime\fP [ \fIpipeline\fP ]
+The \fIpipeline\fP is executed, and timing statistics are
+reported on the standard error in the form specified
+by the \fBTIMEFMT\fP parameter\&.
+If \fIpipeline\fP is omitted, print statistics about the
+shell process and its children\&.
+.TP
+\fB[[\fP \fIexp\fP \fB]]\fP
+Evaluates the conditional expression \fIexp\fP
+and return a zero exit status if it is true\&.
+See the section `Conditional Expressions'
+for a description of \fIexp\fP\&.
+.SH "ALTERNATE FORMS FOR COMPLEX COMMANDS"
+Many of zsh's complex commands have alternate forms\&.  These particular
+versions of complex commands should be considered deprecated and may be
+removed in the future\&.  The versions in the previous section should be
+preferred instead\&.
+.PP
+The short versions below only work if \fIsublist\fP is of the form `\fB{\fP
+\fIlist\fP \fB}\fP' or if the \fBSHORT_LOOPS\fP option is set\&.  For the \fBif\fP,
+\fBwhile\fP and \fBuntil\fP commands, in both these cases the test part of the
+loop must also be suitably delimited, such as by `\fB[[ \&.\&.\&. ]]\fP' or `\fB((
+\&.\&.\&. ))\fP', else the end of the test will not be recognized\&.  For the
+\fBfor\fP, \fBrepeat\fP, \fBcase\fP and \fBselect\fP commands no such special form
+for the arguments is necessary, but the other condition (the special form
+of \fIsublist\fP or use of the \fBSHORT_LOOPS\fP option) still applies\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBif\fP \fIlist\fP \fB{\fP \fIlist\fP \fB}\fP [ \fBelif\fP \fIlist\fP \fB{\fP \fIlist\fP \fB}\fP ] \&.\&.\&. [ \fBelse {\fP \fIlist\fP \fB}\fP ]
+An alternate form of \fBif\fP\&.  The rules mean that
+.RS
+.PP
+.RS
+.nf
+\fBif [[ \-o ignorebraces ]] {
+  print yes
+}\fP
+.fi
+.RE
+.PP
+works, but
+.PP
+.RS
+.nf
+\fBif true {  # Does not work!
+  print yes
+}
+\fP
+.fi
+.RE
+.PP
+does \fInot\fP, since the test is not suitably delimited\&.
+.RE
+.TP
+\fBif\fP \fIlist\fP \fIsublist\fP
+A short form of the alternate `if'\&.  The same limitations on the form of
+\fIlist\fP apply as for the previous form\&.
+.TP
+\fBfor\fP \fIname\fP \&.\&.\&. \fB(\fP \fIword\fP \&.\&.\&. \fB)\fP \fIsublist\fP
+A short form of \fBfor\fP\&.
+.TP
+\fBfor\fP \fIname\fP \&.\&.\&. [ \fBin\fP \fIword\fP \&.\&.\&. ] \fIterm\fP \fIsublist\fP
+where \fIterm\fP is at least one newline or \fB;\fP\&.
+Another short form of \fBfor\fP\&.
+.TP
+\fBfor ((\fP [\fIexpr1\fP] \fB;\fP [\fIexpr2\fP] \fB;\fP [\fIexpr3\fP] \fB))\fP \fIsublist\fP
+A short form of the arithmetic \fBfor\fP command\&.
+.TP
+\fBforeach\fP \fIname\fP \&.\&.\&. \fB(\fP \fIword\fP \&.\&.\&. \fB)\fP \fIlist\fP \fBend\fP
+Another form of \fBfor\fP\&.
+.TP
+\fBwhile\fP \fIlist\fP \fB{\fP \fIlist\fP \fB}\fP
+An alternative form of \fBwhile\fP\&.  Note the limitations on the form of
+\fIlist\fP mentioned above\&.
+.TP
+\fBuntil\fP \fIlist\fP \fB{\fP \fIlist\fP \fB}\fP
+An alternative form of \fBuntil\fP\&.  Note the limitations on the form of
+\fIlist\fP mentioned above\&.
+.TP
+\fBrepeat\fP \fIword\fP \fIsublist\fP
+This is a short form of \fBrepeat\fP\&.
+.TP
+\fBcase\fP \fIword\fP \fB{\fP [ [\fB(\fP] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \&.\&.\&. \fB)\fP \fIlist\fP (\fB;;\fP|\fB;&\fP) ] \&.\&.\&. \fB}\fP
+An alternative form of \fBcase\fP\&.
+.TP
+\fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP \fIterm\fP ] \fIsublist\fP
+where \fIterm\fP is at least one newline or \fB;\fP\&.
+A short form of \fBselect\fP\&.
+.SH "RESERVED WORDS"
+The following words are recognized as reserved words when used as the first
+word of a command unless quoted or disabled using \fBdisable \-r\fP:
+.PP
+\fBdo done esac then elif else fi for case
+if while function repeat time until
+select coproc nocorrect foreach end ! [[ { }\fP
+.PP
+Additionally, `\fB}\fP' is recognized in any position if the \fBIGNORE_BRACES\fP option
+is not set\&.
+.SH "COMMENTS"
+In noninteractive shells, or in interactive shells with the
+\fBINTERACTIVE_COMMENTS\fP option set, a word beginning
+with the third character of the \fBhistchars\fP parameter
+(`\fB#\fP' by default) causes that word and all the following
+characters up to a newline to be ignored\&.
+.SH "ALIASING"
+Every token in the shell input is checked to see if there
+is an alias defined for it\&.
+If so, it is replaced by the text of the alias if it is in command
+position (if it could be the first word of a simple command),
+or if the alias is global\&.
+If the text ends with a space, the next word in the shell input
+is treated as though it were in command position for purposes of alias
+expansion\&.
+An alias is defined using the \fBalias\fP builtin; global aliases
+may be defined using the \fB\-g\fP option to that builtin\&.
+.PP
+Alias expansion is done on the shell input before any
+other expansion except history expansion\&.  Therefore,
+if an alias is defined for the word \fBfoo\fP, alias expansion
+may be avoided by quoting part of the word, e\&.g\&. \fB\efoo\fP\&.
+But there is nothing to prevent an alias being defined
+for \fB\efoo\fP as well\&.
+.SH "QUOTING"
+A character may be \fIquoted\fP (that is, made
+to stand for itself) by preceding it with a `\fB\e\fP'\&.
+`\fB\e\fP' followed by a newline is ignored\&.
+.PP
+A string enclosed between `\fB$'\fP' and `\fB'\fP' is
+processed the same way as the string arguments of the
+\fBprint\fP builtin, and the resulting string is considered to be
+entirely quoted\&.  A literal `\fB'\fP' character can be included in the
+string by using the `\fB\e'\fP' escape\&.
+.PP
+All characters enclosed between a pair of single quotes (\fB''\fP) that
+is not preceded by a `\fB$\fP' are quoted\&.  A single quote cannot appear
+within single quotes unless the option \fBRC_QUOTES\fP is set, in which case
+a pair of single quotes are turned into a single quote\&.  For example,
+.PP
+.RS
+.nf
+\fBprint ''''\fP
+.fi
+.RE
+.PP
+outputs nothing apart from a newline if \fBRC_QUOTES\fP is not set, but one
+single quote if it is set\&.
+.PP
+Inside double quotes (\fB""\fP), parameter and
+command substitution occur, and `\fB\e\fP' quotes the characters
+`\fB\e\fP', `\fB`\fP', `\fB"\fP', and `\fB$\fP'\&.
+.\" Yodl file: Zsh/redirect.yo
+.SH "REDIRECTION"
+If a command is followed by \fB&\fP
+and job control is not active,
+then the default standard input
+for the command is the empty file \fB/dev/null\fP\&.
+Otherwise, the environment for the execution of a command contains the
+file descriptors of the invoking shell as modified by
+input/output specifications\&.
+.PP
+The following may appear anywhere in a simple command
+or may precede or follow a complex command\&.
+Expansion occurs before \fIword\fP or \fIdigit\fP
+is used except as noted below\&.
+If the result of substitution on \fIword\fP
+produces more than one filename,
+redirection occurs for each
+separate filename in turn\&.
+.PP
+.PD 0
+.TP
+.PD
+\fB<\fP \fIword\fP
+Open file \fIword\fP for reading as standard input\&.
+.TP
+\fB<>\fP \fIword\fP
+Open file \fIword\fP for reading and writing as standard input\&.
+If the file does not exist then it is created\&.
+.TP
+\fB>\fP \fIword\fP
+Open file \fIword\fP for writing as standard output\&.
+If the file does not exist then it is created\&.
+If the file exists, and the \fBCLOBBER\fP option is unset,
+this causes an error;
+otherwise, it is truncated to zero length\&.
+.TP
+.PD 0
+\fB>|\fP \fIword\fP
+.TP
+.PD
+\fB>!\fP \fIword\fP
+Same as \fB>\fP, except that the file is truncated to zero length
+if it exists, even if \fBCLOBBER\fP is unset\&.
+.TP
+\fB>>\fP \fIword\fP
+Open file \fIword\fP for writing in append mode as standard output\&.
+If the file does not exist, and the \fBCLOBBER\fP
+option is unset, this causes an error;
+otherwise, the file is created\&.
+.TP
+.PD 0
+\fB>>|\fP \fIword\fP
+.TP
+.PD
+\fB>>!\fP \fIword\fP
+Same as \fB>>\fP, except that the file is created if it does not
+exist, even if \fBCLOBBER\fP is unset\&.
+.TP
+\fB<<\fP[\fB\-\fP] \fIword\fP
+The shell input is read up to a line that is the same as
+\fIword\fP, or to an end\-of\-file\&.
+No parameter expansion, command substitution or
+filename generation is performed on \fIword\fP\&.
+The resulting document, called a
+\fIhere\-document\fP, becomes the standard input\&.
+.RS
+.PP
+If any character of \fIword\fP is quoted with
+single or double quotes or a `\fB\e\fP',
+no interpretation is placed upon the characters of the document\&.
+Otherwise, parameter and command substitution
+occurs, `\fB\e\fP' followed by a newline is removed,
+and `\fB\e\fP' must be used to quote the characters
+`\fB\e\fP', `\fB$\fP', `\fB`\fP' and the first character of \fIword\fP\&.
+.PP
+Note that \fIword\fP itself does not undergo shell expansion\&.  Backquotes
+in \fIword\fP do not have their usual effect; instead they behave
+similarly to double quotes, except that the backquotes themselves are
+passed through unchanged\&.  (This information is given for completeness
+and it is not recommended that backquotes be used\&.)  Quotes in the form
+\fB$'\fP\fI\&.\&.\&.\fP\fB'\fP have their standard effect of expanding backslashed
+references to special characters\&.
+.PP
+If \fB<<\-\fP is used, then all leading
+tabs are stripped from \fIword\fP and from the document\&.
+.RE
+.TP
+\fB<<<\fP \fIword\fP
+Perform shell expansion on \fIword\fP and pass the result
+to standard input\&.  This is known as a \fIhere\-string\fP\&.
+Compare the use of \fIword\fP in here\-documents above, where \fIword\fP
+does not undergo shell expansion\&.
+.TP
+.PD 0
+\fB<&\fP \fInumber\fP
+.TP
+.PD
+\fB>&\fP \fInumber\fP
+The standard input/output is duplicated from file descriptor
+\fInumber\fP (see \fIdup2\fP(2))\&.
+.TP
+.PD 0
+\fB<& \-\fP
+.TP
+.PD
+\fB>& \-\fP
+Close the standard input/output\&.
+.TP
+.PD 0
+\fB<& p\fP
+.TP
+.PD
+\fB>& p\fP
+The input/output from/to the coprocess is moved to the standard input/output\&.
+.TP
+.PD 0
+\fB>&\fP \fIword\fP
+.TP
+.PD
+\fB&>\fP \fIword\fP
+(Except where `\fB>&\fP \fIword\fP' matches one of the above syntaxes;
+`\fB&>\fP' can always be used to avoid this ambiguity\&.)
+Redirects both standard output and standard error (file descriptor 2)
+in the manner of `\fB>\fP \fIword\fP'\&.
+Note that this does \fInot\fP have the same effect as `\fB>\fP \fIword\fP \fB2>&1\fP'
+in the presence of multios (see the section below)\&.
+.TP
+.PD 0
+\fB>&|\fP \fIword\fP
+.TP
+.PD 0
+\fB>&!\fP \fIword\fP
+.TP
+.PD 0
+\fB&>|\fP \fIword\fP
+.TP
+.PD
+\fB&>!\fP \fIword\fP
+Redirects both standard output and standard error (file descriptor 2)
+in the manner of `\fB>|\fP \fIword\fP'\&.
+.TP
+.PD 0
+\fB>>&\fP \fIword\fP
+.TP
+.PD
+\fB&>>\fP \fIword\fP
+Redirects both standard output and standard error (file descriptor 2)
+in the manner of `\fB>>\fP \fIword\fP'\&.
+.TP
+.PD 0
+\fB>>&|\fP \fIword\fP
+.TP
+.PD 0
+\fB>>&!\fP \fIword\fP
+.TP
+.PD 0
+\fB&>>|\fP \fIword\fP
+.TP
+.PD
+\fB&>>!\fP \fIword\fP
+Redirects both standard output and standard error (file descriptor 2)
+in the manner of `\fB>>|\fP \fIword\fP'\&.
+.PP
+If one of the above is preceded by a digit, then the file
+descriptor referred to is that specified by the digit
+instead of the default 0 or 1\&.
+The order in which redirections are specified is significant\&.
+The shell evaluates each redirection in terms of the
+(\fIfile descriptor\fP, \fIfile\fP)
+association at the time of evaluation\&.
+For example:
+.PP
+.RS
+.nf
+\&.\&.\&. \fB1>\fP\fIfname\fP \fB2>&1\fP
+.fi
+.RE
+.PP
+first associates file descriptor 1 with file \fIfname\fP\&.
+It then associates file descriptor 2 with the file associated with file
+descriptor 1 (that is, \fIfname\fP)\&.
+If the order of redirections were reversed,
+file descriptor 2 would be associated
+with the terminal (assuming file descriptor 1 had been)
+and then file descriptor 1 would be associated with file \fIfname\fP\&.
+.PP
+The `\fB|&\fP' command separator described in
+\fISimple Commands & Pipelines\fP in \fIzshmisc\fP(1)
+is a shorthand for `\fB2>&1 |\fP'\&.
+.PP
+For output redirections only, if \fIword\fP is of the form
+`\fB>(\fP\fIlist\fP\fB)\fP' then the output is piped to the command
+represented by \fIlist\fP\&.  See
+\fIProcess Substitution\fP in \fIzshexpn\fP(1)\&.
+.SH "MULTIOS"
+If the user tries to open a file descriptor for writing more than once,
+the shell opens the file descriptor as a pipe to a process that copies
+its input to all the specified outputs, similar to \fBtee\fP,
+provided the \fBMULTIOS\fP option is set, as it is by default\&.  Thus:
+.PP
+.RS
+.nf
+\fBdate >foo >bar\fP
+.fi
+.RE
+.PP
+writes the date to two files, named `\fBfoo\fP' and `\fBbar\fP'\&.
+Note that a pipe is an implicit redirection; thus
+.PP
+.RS
+.nf
+\fBdate >foo | cat\fP
+.fi
+.RE
+.PP
+writes the date to the file `\fBfoo\fP', and also pipes it to cat\&.
+.PP
+If the \fBMULTIOS\fP
+option is set, the word after a redirection operator is also subjected
+to filename generation (globbing)\&.  Thus
+.PP
+.RS
+.nf
+\fB: > *\fP
+.fi
+.RE
+.PP
+will truncate all files in the current directory,
+assuming there's at least one\&.  (Without the \fBMULTIOS\fP
+option, it would create an empty file called `\fB*\fP'\&.)
+Similarly, you can do
+.PP
+.RS
+.nf
+\fBecho exit 0 >> *\&.sh\fP
+.fi
+.RE
+.PP
+If the user tries to open a file descriptor for reading more than once,
+the shell opens the file descriptor as a pipe to a process that copies
+all the specified inputs to its output in the order
+specified, similar to \fBcat\fP,
+provided the \fBMULTIOS\fP option is set\&.  Thus
+.PP
+.RS
+.nf
+\fBsort <foo <fubar\fP
+.fi
+.RE
+.PP
+or even
+.PP
+.RS
+.nf
+\fBsort <f{oo,ubar}\fP
+.fi
+.RE
+.PP
+is equivalent to `\fBcat foo fubar | sort\fP'\&.
+.PP
+Note that a pipe is an implicit redirection; thus
+.PP
+.RS
+.nf
+\fBcat bar | sort <foo\fP
+.fi
+.RE
+.PP
+is equivalent to `\fBcat bar foo | sort\fP' (note the order of the inputs)\&.
+.PP
+If the \fBMULTIOS\fP option is \fIun\fPset,
+each redirection replaces the previous redirection for that file descriptor\&.
+However, all files redirected to are actually opened, so
+.PP
+.RS
+.nf
+\fBecho foo > bar > baz\fP
+.fi
+.RE
+.PP
+when \fBMULTIOS\fP is unset will truncate bar, and write `\fBfoo\fP' into baz\&.
+.PP
+There is a problem when an output multio is attached to an external
+program\&.  A simple example shows this:
+.PP
+.RS
+.nf
+\fBcat file >file1 >file2
+cat file1 file2\fP
+.fi
+.RE
+.PP
+Here, it is possible that the second `\fBcat\fP' will not display the full
+contents of \fBfile1\fP and \fBfile2\fP (i\&.e\&. the original contents of
+\fBfile\fP repeated twice)\&.
+.PP
+The reason for this is that the multios are spawned after the \fBcat\fP
+process is forked from the parent shell, so the parent shell does not
+wait for the multios to finish writing data\&.  This means the command as
+shown can exit before \fBfile1\fP and \fBfile2\fP are completely written\&.
+As a workaround, it is possible to run the \fBcat\fP process as part of a
+job in the current shell:
+.PP
+.RS
+.nf
+\fB{ cat file } >file >file2\fP
+.fi
+.RE
+.PP
+Here, the \fB{\fP\fI\&.\&.\&.\fP\fB}\fP job will pause to wait for both files to be
+written\&.
+.PP
+.SH "REDIRECTIONS WITH NO COMMAND"
+When a simple command consists of one or more redirection operators
+and zero or more parameter assignments, but no command name, zsh can
+behave in several ways\&.
+.PP
+If the parameter \fBNULLCMD\fP is not set or the option \fBCSH_NULLCMD\fP is
+set, an error is caused\&.  This is the \fBcsh\fP behavior and \fBCSH_NULLCMD\fP
+is set by default when emulating \fBcsh\fP\&.
+.PP
+If the option \fBSH_NULLCMD\fP is set, the builtin `\fB:\fP' is inserted as a
+command with the given redirections\&.  This is the default when emulating
+\fBsh\fP or \fBksh\fP\&.
+.PP
+Otherwise, if the parameter \fBNULLCMD\fP is set, its value will be used as a
+command with the given redirections\&.  If both \fBNULLCMD\fP and
+\fBREADNULLCMD\fP are set, then the value of the latter will be used instead
+of that of the former when the redirection is an input\&.  The default for
+\fBNULLCMD\fP is `\fBcat\fP' and for \fBREADNULLCMD\fP is `\fBmore\fP'\&. Thus
+.PP
+.RS
+.nf
+\fB< file\fP
+.fi
+.RE
+.PP
+shows the contents of \fBfile\fP on standard output, with paging if that is a
+terminal\&.  \fBNULLCMD\fP and \fBREADNULLCMD\fP may refer to shell functions\&.
+.PP
+.\" Yodl file: Zsh/exec.yo
+.SH "COMMAND EXECUTION"
+If a command name contains no slashes, the shell attempts to locate
+it\&.  If there exists a shell function by that name, the function
+is invoked as described in the section `Functions'\&.  If there exists
+a shell builtin by that name, the builtin is invoked\&.
+.PP
+Otherwise, the shell searches each element of \fB$path\fP for a
+directory containing an executable file by that name\&.  If the
+search is unsuccessful, the shell prints an error message and returns
+a nonzero exit status\&.
+.PP
+If execution fails because the file is not in executable format,
+and the file is not a directory, it is assumed to be a shell
+script\&.  \fB/bin/sh\fP is spawned to execute it\&.  If the program
+is a file beginning with `\fB#!\fP', the remainder of the first line
+specifies an interpreter for the program\&.  The shell will
+execute the specified interpreter on operating systems that do
+not handle this executable format in the kernel\&.
+.\" Yodl file: Zsh/func.yo
+.SH "FUNCTIONS"
+Shell functions are defined with the \fBfunction\fP reserved word or the
+special syntax `\fIfuncname\fP \fB()\fP'\&.
+Shell functions are read in and stored internally\&.
+Alias names are resolved when the function is read\&.
+Functions are executed like commands with the arguments
+passed as positional parameters\&.
+(See the section `Command Execution'\&.)
+.PP
+Functions execute in the same process as the caller and
+share all files
+and present working directory with the
+caller\&.  A trap on \fBEXIT\fP set inside a function
+is executed after the function completes in the environment
+of the caller\&.
+.PP
+The \fBreturn\fP builtin is used to return from function calls\&.
+.PP
+Function identifiers can be listed with the \fBfunctions\fP builtin\&.
+Functions can be undefined with the \fBunfunction\fP builtin\&.
+.SH "AUTOLOADING FUNCTIONS"
+.PP
+A function can be marked as \fIundefined\fP using the \fBautoload\fP builtin
+(or `\fBfunctions \-u\fP' or `\fBtypeset \-fu\fP')\&.  Such a function has no
+body\&.  When the function is first executed, the shell searches for its
+definition using the elements of the \fBfpath\fP variable\&.  Thus to define
+functions for autoloading, a typical sequence is:
+.PP
+.RS
+.nf
+\fBfpath=(~/myfuncs $fpath)
+autoload myfunc1 myfunc2 \&.\&.\&.\fP
+.fi
+.RE
+.PP
+The usual alias expansion during reading will be suppressed if the
+\fBautoload\fP builtin or its equivalent is given the option \fB\-U\fP\&. This is
+recommended for the use of functions supplied with the zsh distribution\&.
+Note that for functions precompiled with the \fBzcompile\fP builtin command
+the flag \fB\-U\fP must be provided when the \fB\&.zwc\fP file is created, as the
+corresponding information is compiled into the latter\&.
+.PP
+For each \fIelement\fP in \fBfpath\fP, the shell looks for three possible
+files, the newest of which is used to load the definition for the function:
+.PP
+.PD 0
+.TP
+.PD
+\fIelement\fP\fB\&.zwc\fP
+A file created with the \fBzcompile\fP builtin command, which is expected to
+contain the definitions for all functions in the directory named
+\fIelement\fP\&.  The file is treated in the same manner as a directory
+containing files for functions and is searched for the definition of the
+function\&.   If the definition is not found, the search for a definition
+proceeds with the other two possibilities described below\&.
+.RS
+.PP
+If \fIelement\fP already includes a \fB\&.zwc\fP extension (i\&.e\&. the extension
+was explicitly given by the user), \fIelement\fP is searched for the
+definition of the function without comparing its age to that of other
+files; in fact, there does not need to be any directory named \fIelement\fP
+without the suffix\&.  Thus including an element such as
+`\fB/usr/local/funcs\&.zwc\fP' in \fBfpath\fP will speed up the search for
+functions, with the disadvantage that functions included must be explicitly
+recompiled by hand before the shell notices any changes\&.
+.RE
+.TP
+\fIelement\fP\fB/\fP\fIfunction\fP\fB\&.zwc\fP
+A file created with \fBzcompile\fP, which is expected to contain the
+definition for \fIfunction\fP\&.  It may include other function definitions
+as well, but those are neither loaded nor executed; a file found in this
+way is searched \fIonly\fP for the definition of \fIfunction\fP\&.
+.TP
+\fIelement\fP\fB/\fP\fIfunction\fP
+A file of zsh command text, taken to be the definition for \fIfunction\fP\&.
+.PP
+In summary, the order of searching is, first, in the \fIparents of\fP
+directories in \fBfpath\fP for the newer of either a compiled directory or
+a directory in \fBfpath\fP; second, if more than one of these contains a
+definition for the function that is sought, the leftmost in the \fBfpath\fP
+is chosen; and third, within a directory, the newer of either a compiled
+function or an ordinary function definition is used\&.
+.PP
+If the \fBKSH_AUTOLOAD\fP option is set, or the file contains only a
+simple definition of the function, the file's contents will be executed\&.
+This will normally define the function in question, but may also perform
+initialization, which is executed in the context of the function execution,
+and may therefore define local parameters\&.  It is an error if the function
+is not defined by loading the file\&.
+.PP
+Otherwise, the function body (with no surrounding `\fIfuncname\fP\fB()
+{\fP\fI\&.\&.\&.\fP\fB}\fP') is taken to be the complete contents of the file\&.  This
+form allows the file to be used directly as an executable shell script\&.  If
+processing of the file results in the function being re\-defined, the
+function itself is not re\-executed\&.  To force the shell to perform
+initialization and then call the function defined, the file should contain
+initialization code (which will be executed then discarded) in addition to
+a complete function definition (which will be retained for subsequent calls
+to the function), and a call to the shell function, including any
+arguments, at the end\&.
+.PP
+For example, suppose the autoload file \fBfunc\fP contains
+.PP
+.RS
+.nf
+\fBfunc() { print This is func; }
+print func is initialized
+\fP
+.fi
+.RE
+.PP
+then `\fBfunc; func\fP' with \fBKSH_AUTOLOAD\fP set will produce both messages
+on the first call, but only the message `\fBThis is func\fP' on the second
+and subsequent calls\&.  Without \fBKSH_AUTOLOAD\fP set, it will produce
+the initialization message on the first call, and the other message on the
+second and subsequent calls\&.
+.PP
+It is also possible to create a function that is not marked as autoloaded,
+but which loads its own definition by searching \fBfpath\fP, by using
+`\fBautoload \-X\fP' within a shell function\&.  For example, the following are
+equivalent:
+.PP
+.RS
+.nf
+\fBmyfunc() {
+  autoload \-X
+}
+myfunc args\&.\&.\&.\fP
+.fi
+.RE
+.PP
+and
+.PP
+.RS
+.nf
+\fBunfunction myfunc   # if myfunc was defined
+autoload myfunc
+myfunc args\&.\&.\&.\fP
+.fi
+.RE
+.PP
+In fact, the \fBfunctions\fP command outputs `\fBbuiltin autoload \-X\fP' as
+the body of an autoloaded function\&.  This is done so that
+.PP
+.RS
+.nf
+\fBeval "$(functions)"\fP
+.fi
+.RE
+.PP
+produces a reasonable result\&.  A true autoloaded function can be
+identified by the presence of the comment `\fB# undefined\fP' in the body,
+because all comments are discarded from defined functions\&.
+.PP
+To load the definition of an autoloaded function \fBmyfunc\fP without
+executing \fBmyfunc\fP, use:
+.PP
+.RS
+.nf
+\fBautoload +X myfunc\fP
+.fi
+.RE
+.PP
+.SH "SPECIAL FUNCTIONS"
+The following functions, if defined, have special meaning to
+the shell:
+.PP
+.PD 0
+.TP
+.PD
+\fBchpwd\fP
+Executed whenever the current working directory is changed\&.
+.TP
+\fBperiodic\fP
+If the parameter \fBPERIOD\fP
+is set, this function is executed every \fB$PERIOD\fP
+seconds, just before a prompt\&.
+.TP
+\fBprecmd\fP
+Executed before each prompt\&.
+.TP
+\fBpreexec\fP
+Executed just after a command has been read and is about to be
+executed\&.  If the history mechanism is active (and the line was not
+discarded from the history buffer), the string that the user typed is
+passed as the first argument, otherwise it is an empty string\&.  The
+actual command that will be executed (including expanded aliases) is
+passed in two different forms: the second argument is a single\-line,
+size\-limited version of the command (with things like function bodies
+elided); the third argument contains the full text that is being
+executed\&.
+.TP
+\fBTRAP\fP\fINAL\fP
+If defined and non\-null,
+this function will be executed whenever the shell
+catches a signal \fBSIG\fP\fINAL\fP, where \fINAL\fP is a signal
+name as specified for the \fBkill\fP builtin\&.
+The signal number will be passed as the first parameter to the function\&.
+.RS
+.PP
+If a function of this form is defined and null,
+the shell and processes spawned by it will ignore \fBSIG\fP\fINAL\fP\&.
+.PP
+The return value from the function is handled specially\&.  If it is
+zero, the signal is assumed to have been handled, and execution continues
+normally\&.  Otherwise, the normal effect of the signal is produced;
+if this causes execution to terminate, the status returned to the shell is
+the status returned from the function\&.
+.PP
+Programs terminated by uncaught signals typically return the status 128
+plus the signal number\&.  Hence the following causes the handler for
+\fBSIGINT\fP to print a message, then mimic the usual effect of the signal\&.
+.PP
+.RS
+.nf
+\fBTRAPINT() {
+  print "Caught SIGINT, aborting\&."
+  return $(( 128 + $1 ))
+}\fP
+.fi
+.RE
+.PP
+The functions \fBTRAPZERR\fP, \fBTRAPDEBUG\fP and \fBTRAPEXIT\fP are never
+executed inside other traps\&.
+.RE
+.TP
+\fBTRAPDEBUG\fP
+Executed after each command\&.
+.TP
+\fBTRAPEXIT\fP
+Executed when the shell exits,
+or when the current function exits if defined inside a function\&.
+.TP
+\fBTRAPZERR\fP
+Executed whenever a command has a non\-zero exit status\&.  However, the
+function is not executed if the command occurred in a sublist followed by
+`\fB&&\fP' or `\fB||\fP'; only the final command in a sublist of this type
+causes the trap to be executed\&.
+.PP
+The functions beginning `\fBTRAP\fP' may alternatively be defined with the
+\fBtrap\fP builtin:  this may be preferable for some uses, as they are then
+run in the environment of the calling process, rather than in their own
+function environment\&.  Apart from the difference in calling procedure and
+the fact that the function form appears in lists of functions, the forms
+.PP
+.RS
+.nf
+\fBTRAPNAL() { 
+ # code
+}\fP
+.fi
+.RE
+.PP
+and
+.PP
+.RS
+.nf
+\fBtrap '
+ # code
+' NAL\fP
+.fi
+.RE
+.PP
+are equivalent\&.
+.\" Yodl file: Zsh/jobs.yo
+.SH "JOBS"
+If the \fBMONITOR\fP option is set,
+an interactive shell associates a \fIjob\fP with each pipeline\&.
+It keeps a table of current jobs, printed by the \fBjobs\fP
+command, and assigns them small integer numbers\&.
+When a job is started asynchronously with `\fB&\fP',
+the shell prints a line to standard error which looks like:
+.PP
+.RS
+.nf
+\fB[1] 1234\fP
+.fi
+.RE
+.PP
+indicating that the job which was started asynchronously was job number
+1 and had one (top\-level) process, whose process ID was 1234\&.
+.PP
+If a job is started with `\fB&|\fP' or `\fB&!\fP',
+then that job is immediately disowned\&.  After startup, it
+does not have a place in the job table, and is not subject
+to the job control features described here\&.
+.PP
+If you are running a job and wish to do something else you may hit the key
+^Z (control\-Z) which sends a \fBTSTP\fP signal to the current job:  this key
+may be redefined by the \fBsusp\fP option of the external \fBstty\fP command\&.
+The shell will then normally indicate that the job has been `suspended',
+and print another prompt\&.  You can then manipulate the state of this job,
+putting it in the background with the \fBbg\fP command, or run some other
+commands and then eventually bring the job back into the foreground with
+the foreground command \fBfg\fP\&.  A ^Z takes effect immediately and
+is like an interrupt in that pending output and unread input are discarded
+when it is typed\&.
+.PP
+A job being run in the background will suspend if it tries to read
+from the terminal\&.
+Background jobs are normally allowed to produce output,
+but this can be disabled by giving the command `\fBstty tostop\fP'\&.
+If you set this
+tty option, then background jobs will suspend when they try to produce
+output like they do when they try to read input\&.
+.PP
+When a command is suspended and continued later with the \fBfg\fP or
+\fBwait\fP builtins, zsh restores tty modes that were in effect when it was
+suspended\&.  This (intentionally) does not apply if the command is
+continued via `\fBkill \-CONT\fP', nor when it is continued with \fBbg\fP\&.
+.PP
+There are several ways to refer to jobs in the shell\&.
+A job can be referred to by the process ID of any process of the job
+or by one of the following:
+.PP
+.PD 0
+.TP
+\fB%\fP\fInumber\fP
+The job with the given number\&.
+.TP
+\fB%\fP\fIstring\fP
+Any job whose command line begins with \fIstring\fP\&.
+.TP
+\fB%?\fP\fIstring\fP
+Any job whose command line contains \fIstring\fP\&.
+.TP
+\fB%%\fP
+Current job\&.
+.TP
+\fB%+\fP
+Equivalent to `\fB%%\fP'\&.
+.TP
+\fB%\-\fP
+Previous job\&.
+.PD
+.PP
+The shell learns immediately whenever a process changes state\&.
+It normally informs you whenever a job becomes blocked so that
+no further progress is possible\&.  If the \fBNOTIFY\fP option is not set,
+it waits until just before it prints a prompt before it informs you\&.
+All such notifications are sent directly to the terminal, not to
+the standard output or standard error\&.
+.PP
+When the monitor mode is on, each background job that completes
+triggers any trap set for \fBCHLD\fP\&.
+.PP
+When you try to leave the shell while jobs are running or suspended, you will
+be warned that `You have suspended (running) jobs'\&.
+You may use the \fBjobs\fP command to see what they are\&.
+If you do this or immediately try to
+exit again, the shell will not warn you a second time; the suspended
+jobs will be terminated, and the running jobs will be sent
+a \fBSIGHUP\fP signal, if the \fBHUP\fP option is set\&.
+.PP
+To avoid having the shell terminate the running jobs, either
+use the \fBnohup\fP command (see \fInohup\fP(1))
+or the \fBdisown\fP builtin\&.
+.SH "SIGNALS"
+The \fBINT\fP and \fBQUIT\fP signals for an invoked
+command are ignored if the command is followed by
+`\fB&\fP' and the \fBMONITOR\fP option is not active\&.
+Otherwise, signals have the values
+inherited by the shell from its parent
+(but see the \fBTRAP\fP\fINAL\fP special functions in the section `Functions')\&.
+.\" Yodl file: Zsh/arith.yo
+.SH "ARITHMETIC EVALUATION"
+The shell can perform integer and floating point arithmetic, either using
+the builtin \fBlet\fP, or via a substitution of the form \fB$((\&.\&.\&.))\fP\&.  For
+integers, the shell is usually compiled to use 8\-byte precision where this
+is available, otherwise precision is 4 bytes\&.  This can be tested, for
+example, by giving the command `\fBprint \- $(( 12345678901 ))\fP'; if the
+number appears unchanged, the precision is at least 8 bytes\&.  Floating
+point arithmetic is always double precision\&.
+.PP
+The \fBlet\fP builtin command takes arithmetic expressions as arguments; each
+is evaluated separately\&.  Since many of the arithmetic operators, as well
+as spaces, require quoting, an alternative form is provided: for any
+command which begins with a `\fB((\fP', all the characters until a
+matching `\fB))\fP' are treated as a quoted expression and
+arithmetic expansion performed as for an argument of \fBlet\fP\&.  More
+precisely, `\fB((\fP\fI\&.\&.\&.\fP\fB))\fP' is equivalent to
+`\fBlet "\fP\fI\&.\&.\&.\fP\fB"\fP'\&.  For example, the following statement
+.PP
+.RS
+.nf
+\fB(( val = 2 + 1 ))\fP
+.fi
+.RE
+.PP
+is equivalent to
+.PP
+.RS
+.nf
+\fBlet "val = 2 + 1"\fP
+.fi
+.RE
+.PP
+both assigning the value 3 to the shell variable \fBval\fP and returning a
+zero status\&.
+.PP
+Integers can be in bases other than 10\&.
+A leading `\fB0x\fP' or `\fB0X\fP' denotes hexadecimal\&.
+Integers may also be of the form `\fIbase\fP\fB#\fP\fIn\fP',
+where \fIbase\fP is a decimal number between two and thirty\-six
+representing the arithmetic base and \fIn\fP
+is a number in that base (for example, `\fB16#ff\fP' is 255 in hexadecimal)\&.
+The \fIbase\fP\fB#\fP may also be omitted, in which case
+base 10 is used\&.  For backwards compatibility the form
+`\fB[\fP\fIbase\fP\fB]\fP\fIn\fP' is also accepted\&.
+.PP
+It is also possible to specify a base to be used for output in the form
+`\fB[#\fP\fIbase\fP\fB]\fP', for example `\fB[#16]\fP'\&.  This is used when
+outputting arithmetical substitutions or when assigning to scalar
+parameters, but an explicitly defined integer or floating point parameter
+will not be affected\&.  If an integer variable is implicitly defined by an
+arithmetic expression, any base specified in this way will be set as the
+variable's output arithmetic base as if the option `\fB\-i\fP \fIbase\fP' to
+the \fBtypeset\fP builtin had been used\&.  The expression has no precedence
+and if it occurs more than once in a mathematical expression, the last
+encountered is used\&.  For clarity it is recommended that it appear at the
+beginning of an expression\&.  As an example:
+.PP
+.RS
+.nf
+\fBtypeset \-i 16 y
+print $(( [#8] x = 32, y = 32 ))
+print $x $y\fP
+.fi
+.RE
+.PP
+outputs first `\fB8#40\fP', the rightmost value in the given output base, and
+then `\fB8#40 16#20\fP', because \fBy\fP has been explicitly declared to
+have output base 16, while \fBx\fP (assuming it does not already exist) is
+implicitly typed by the arithmetic evaluation, where it acquires the output
+base 8\&.
+.PP
+If the \fBC_BASES\fP option is set, hexadecimal numbers in the standard C
+format, for example \fB0xFF\fP instead of the usual `\fB16#FF\fP'\&.  If the
+option \fBOCTAL_ZEROES\fP is also set (it is not by default), octal numbers
+will be treated similarly and hence appear as `\fB077\fP' instead of
+`\fB8#77\fP'\&.  This option has no effect on the output of bases other than
+hexadecimal and octal, and these formats are always understood on input\&.
+.PP
+When an output base is specified using the `\fB[#\fP\fIbase\fP\fB]\fP' syntax,
+an appropriate base prefix will be output if necessary, so that the value
+output is valid syntax for input\&.  If the \fB#\fP is doubled, for example
+`\fB[##16]\fP', then no base prefix is output\&.
+.PP
+Floating point constants are recognized by the presence of a decimal point
+or an exponent\&.  The decimal point may be the first character of the
+constant, but the exponent character \fBe\fP or \fBE\fP may not, as it will be
+taken for a parameter name\&.
+.PP
+An arithmetic expression uses nearly the same syntax, precedence, and
+associativity of expressions in C\&.
+The following operators are supported (listed in decreasing order
+of precedence):
+.PP
+.PD 0
+.TP
+\fB+ \- ! ~ ++ \-\-\fP
+unary plus/minus, logical NOT, complement, {pre,post}{in,de}crement
+.TP
+\fB<< >>\fP
+bitwise shift left, right
+.TP
+\fB&\fP
+bitwise AND
+.TP
+\fB^\fP
+bitwise XOR
+.TP
+\fB|\fP
+bitwise OR
+.TP
+\fB**\fP
+exponentiation
+.TP
+\fB* / %\fP
+multiplication, division, modulus (remainder)
+.TP
+\fB+ \-\fP
+addition, subtraction
+.TP
+\fB< > <= >=\fP
+comparison
+.TP
+\fB== !=\fP
+equality and inequality
+.TP
+\fB&&\fP
+logical AND
+.TP
+\fB|| ^^\fP
+logical OR, XOR
+.TP
+\fB? :\fP
+ternary operator
+.TP
+\fB= += \-= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **=\fP
+assignment
+.TP
+\fB,\fP
+comma operator
+.PD
+.PP
+The operators `\fB&&\fP', `\fB||\fP', `\fB&&=\fP', and `\fB||=\fP' are
+short\-circuiting, and only one of the latter two expressions in a ternary
+operator is evaluated\&.  Note the precedence of the bitwise AND, OR,
+and XOR operators\&.
+.PP
+Mathematical functions can be called with the syntax
+`\fIfunc\fP\fB(\fP\fIargs\fP\fB)\fP', where the function decides
+if the \fIargs\fP is used as a string or a comma\-separated list of
+arithmetic expressions\&. The shell currently defines no mathematical
+functions by default, but the module \fBzsh/mathfunc\fP may be loaded with
+the \fBzmodload\fP builtin to provide standard floating point mathematical
+functions\&.
+.PP
+An expression of the form `\fB##\fP\fIx\fP' where \fIx\fP is any character
+sequence such as `\fBa\fP', `\fB^A\fP', or `\fB\eM\-\eC\-x\fP' gives the ASCII
+value of this character and an expression of the form `\fB#\fP\fIfoo\fP'
+gives the ASCII value of the first character of the value of the
+parameter \fIfoo\fP\&.  Note that this is different from the expression
+`\fB$#\fP\fIfoo\fP', a standard parameter substitution which gives the
+length of the parameter \fIfoo\fP\&.  `\fB#\e\fP' is accepted instead of
+`\fB##\fP', but its use is deprecated\&.
+.PP
+Named parameters and subscripted arrays can be referenced by name within an
+arithmetic expression without using the parameter expansion syntax\&.  For
+example,
+.PP
+.RS
+.nf
+\fB((val2 = val1 * 2))\fP
+.fi
+.RE
+.PP
+assigns twice the value of \fB$val1\fP to the parameter named \fBval2\fP\&.
+.PP
+An internal integer representation of a named parameter
+can be specified with the \fBinteger\fP builtin\&.
+Arithmetic evaluation is performed on the value of each
+assignment to a named parameter declared integer
+in this manner\&.  Assigning a floating point number to an integer results in
+rounding down to the next integer\&.
+.PP
+Likewise, floating point numbers can be declared with the \fBfloat\fP
+builtin; there are two types, differing only in their output format, as
+described for the \fBtypeset\fP builtin\&.  The output format can be bypassed
+by using arithmetic substitution instead of the parameter substitution,
+i\&.e\&. `\fB${\fP\fIfloat\fP\fB}\fP' uses the defined format, but
+`\fB$((\fP\fIfloat\fP\fB))\fP' uses a generic floating point
+format\&.
+.PP
+Promotion of integer to floating point values is performed where
+necessary\&.  In addition, if any operator which requires an integer
+(`\fB~\fP', `\fB&\fP', `\fB|\fP', `\fB^\fP', `\fB%\fP', `\fB<<\fP', `\fB>>\fP' and their
+equivalents with assignment) is given a floating point argument, it will be
+silently rounded down to the next integer\&.
+.PP
+Scalar variables can hold integer or floating point values at different
+times; there is no memory of the numeric type in this case\&.
+.PP
+If a variable is first assigned in a numeric context without previously
+being declared, it will be implicitly typed as \fBinteger\fP or \fBfloat\fP and
+retain that type either until the type is explicitly changed or until the
+end of the scope\&.  This can have unforeseen consequences\&.  For example, in
+the loop
+.PP
+.RS
+.nf
+\fBfor (( f = 0; f < 1; f += 0\&.1 )); do
+# use $f
+done\fP
+.fi
+.RE
+.PP
+if \fBf\fP has not already been declared, the first assignment will cause it
+to be created as an integer, and consequently the operation `\fBf += 0\&.1\fP'
+will always cause the result to be truncated to zero, so that the loop will
+fail\&.  A simple fix would be to turn the initialization into `\fBf = 0\&.0\fP'\&.
+It is therefore best to declare numeric variables with explicit types\&.
+.\" Yodl file: Zsh/cond.yo
+.SH "CONDITIONAL EXPRESSIONS"
+A \fIconditional expression\fP is used with the \fB[[\fP
+compound command to test attributes of files and to compare strings\&.
+Each expression can be constructed from one or more
+of the following unary or binary expressions:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-a\fP \fIfile\fP
+true if \fIfile\fP exists\&.
+.TP
+\fB\-b\fP \fIfile\fP
+true if \fIfile\fP exists and is a block special file\&.
+.TP
+\fB\-c\fP \fIfile\fP
+true if \fIfile\fP exists and is a character special file\&.
+.TP
+\fB\-d\fP \fIfile\fP
+true if \fIfile\fP exists and is a directory\&.
+.TP
+\fB\-e\fP \fIfile\fP
+true if \fIfile\fP exists\&.
+.TP
+\fB\-f\fP \fIfile\fP
+true if \fIfile\fP exists and is a regular file\&.
+.TP
+\fB\-g\fP \fIfile\fP
+true if \fIfile\fP exists and has its setgid bit set\&.
+.TP
+\fB\-h\fP \fIfile\fP
+true if \fIfile\fP exists and is a symbolic link\&.
+.TP
+\fB\-k\fP \fIfile\fP
+true if \fIfile\fP exists and has its sticky bit set\&.
+.TP
+\fB\-n\fP \fIstring\fP
+true if length of \fIstring\fP is non\-zero\&.
+.TP
+\fB\-o\fP \fIoption\fP
+true if option named \fIoption\fP is on\&.  \fIoption\fP
+may be a single character, in which case it is a single letter option name\&.
+(See the section `Specifying Options'\&.)
+.TP
+\fB\-p\fP \fIfile\fP
+true if \fIfile\fP exists and is a FIFO special file (named pipe)\&.
+.TP
+\fB\-r\fP \fIfile\fP
+true if \fIfile\fP exists and is readable by current process\&.
+.TP
+\fB\-s\fP \fIfile\fP
+true if \fIfile\fP exists and has size greater than zero\&.
+.TP
+\fB\-t\fP \fIfd\fP
+true if file descriptor number \fIfd\fP
+is open and associated with a terminal device\&.
+(note: \fIfd\fP is not optional)
+.TP
+\fB\-u\fP \fIfile\fP
+true if \fIfile\fP exists and has its setuid bit set\&.
+.TP
+\fB\-w\fP \fIfile\fP
+true if \fIfile\fP exists and is writable by current process\&.
+.TP
+\fB\-x\fP \fIfile\fP
+true if \fIfile\fP exists and is executable by current process\&.
+If \fIfile\fP exists and is a directory, then the current process
+has permission to search in the directory\&.
+.TP
+\fB\-z\fP \fIstring\fP
+true if length of \fIstring\fP is zero\&.
+.TP
+\fB\-L\fP \fIfile\fP
+true if \fIfile\fP exists and is a symbolic link\&.
+.TP
+\fB\-O\fP \fIfile\fP
+true if \fIfile\fP exists and is owned by the effective user ID of this process\&.
+.TP
+\fB\-G\fP \fIfile\fP
+true if \fIfile\fP exists and its group matches
+the effective group ID of this process\&.
+.TP
+\fB\-S\fP \fIfile\fP
+true if \fIfile\fP exists and is a socket\&.
+.TP
+\fB\-N\fP \fIfile\fP
+true if \fIfile\fP exists and its access time is
+not newer than its modification time\&.
+.TP
+\fIfile1\fP \fB\-nt\fP \fIfile2\fP
+true if \fIfile1\fP exists and is newer than \fIfile2\fP\&.
+.TP
+\fIfile1\fP \fB\-ot\fP \fIfile2\fP
+true if \fIfile1\fP exists and is older than \fIfile2\fP\&.
+.TP
+\fIfile1\fP \fB\-ef\fP \fIfile2\fP
+true if \fIfile1\fP and \fIfile2\fP exist and refer to the same file\&.
+.TP
+.PD 0
+\fIstring\fP \fB=\fP \fIpattern\fP
+.TP
+.PD
+\fIstring\fP \fB==\fP \fIpattern\fP
+true if \fIstring\fP matches \fIpattern\fP\&.
+The `\fB==\fP' form is the preferred one\&.  The `\fB=\fP' form is for
+backward compatibility and should be considered obsolete\&.
+.TP
+\fIstring\fP \fB!=\fP \fIpattern\fP
+true if \fIstring\fP does not match \fIpattern\fP\&.
+.TP
+\fIstring1\fP \fB<\fP \fIstring2\fP
+true if \fIstring1\fP comes before \fIstring2\fP
+based on ASCII value of their characters\&.
+.TP
+\fIstring1\fP \fB>\fP \fIstring2\fP
+true if \fIstring1\fP comes after \fIstring2\fP
+based on ASCII value of their characters\&.
+.TP
+\fIexp1\fP \fB\-eq\fP \fIexp2\fP
+true if \fIexp1\fP is numerically equal to \fIexp2\fP\&.
+.TP
+\fIexp1\fP \fB\-ne\fP \fIexp2\fP
+true if \fIexp1\fP is numerically not equal to \fIexp2\fP\&.
+.TP
+\fIexp1\fP \fB\-lt\fP \fIexp2\fP
+true if \fIexp1\fP is numerically less than \fIexp2\fP\&.
+.TP
+\fIexp1\fP \fB\-gt\fP \fIexp2\fP
+true if \fIexp1\fP is numerically greater than \fIexp2\fP\&.
+.TP
+\fIexp1\fP \fB\-le\fP \fIexp2\fP
+true if \fIexp1\fP is numerically less than or equal to \fIexp2\fP\&.
+.TP
+\fIexp1\fP \fB\-ge\fP \fIexp2\fP
+true if \fIexp1\fP is numerically greater than or equal to \fIexp2\fP\&.
+.TP
+\fB(\fP \fIexp\fP \fB)\fP
+true if \fIexp\fP is true\&.
+.TP
+\fB!\fP \fIexp\fP
+true if \fIexp\fP is false\&.
+.TP
+\fIexp1\fP \fB&&\fP \fIexp2\fP
+true if \fIexp1\fP and \fIexp2\fP are both true\&.
+.TP
+\fIexp1\fP \fB||\fP \fIexp2\fP
+true if either \fIexp1\fP or \fIexp2\fP is true\&.
+.PP
+Normal shell expansion is performed on the \fIfile\fP, \fIstring\fP and
+\fIpattern\fP arguments, but the result of each expansion is constrained to
+be a single word, similar to the effect of double quotes\&.  However, pattern
+metacharacters are active for the \fIpattern\fP arguments; the patterns
+are the same as those used for filename generation, see
+\fIzshexpn\fP(1), but there is no special behaviour
+of `\fB/\fP' nor initial dots, and no glob qualifiers are allowed\&.
+.PP
+In each of the above expressions, if
+\fIfile\fP is of the form `\fB/dev/fd/\fP\fIn\fP',
+where \fIn\fP is an integer,
+then the test applied to the open file whose
+descriptor number is \fIn\fP,
+even if the underlying system does not support
+the \fB/dev/fd\fP directory\&.
+.PP
+In the forms which do numeric comparison, the expressions \fIexp\fP
+undergo arithmetic expansion as if they were enclosed in \fB$((\&.\&.\&.))\fP\&.
+.PP
+For example, the following:
+.PP
+.RS
+.nf
+\fB[[ ( \-f foo || \-f bar ) && $report = y* ]] && print File exists\&.\fP
+.fi
+.RE
+.PP
+tests if either file \fBfoo\fP or file \fBbar\fP exists, and if so, if the
+value of the parameter \fBreport\fP begins with `\fBy\fP'; if the complete
+condition is true, the message `\fBFile exists\&.\fP' is printed\&.
+.\" Yodl file: Zsh/prompt.yo
+.SH "PROMPT EXPANSION"
+Prompt sequences undergo a special form of expansion\&.  This type of expansion
+is also available using the \fB\-P\fP option to the \fBprint\fP builtin\&.
+.PP
+If the \fBPROMPT_SUBST\fP option is set, the prompt string is first subjected to
+\fIparameter expansion\fP,
+\fIcommand substitution\fP and
+\fIarithmetic expansion\fP\&.
+See
+\fIzshexpn\fP(1)\&.
+
+Certain escape sequences may be recognised in the prompt string\&.
+.PP
+If the \fBPROMPT_BANG\fP option is set, a `\fB!\fP' in the prompt is replaced
+by the current history event number\&.  A literal `\fB!\fP' may then be
+represented as `\fB!!\fP'\&.
+.PP
+If the \fBPROMPT_PERCENT\fP option is set, certain escape sequences that
+start with `\fB%\fP' are expanded\&.
+Some escapes take an optional integer argument, which
+should appear between the `\fB%\fP' and the next character of the
+sequence\&.  The following escape sequences are recognized:
+.PP
+.SS "Special characters"
+.PD 0
+.TP
+.PD
+\fB%%\fP
+A `\fB%\fP'\&.
+.TP
+\fB%)\fP
+A `\fB)\fP'\&.
+.PP
+.SS "Login information"
+.PD 0
+.TP
+.PD
+\fB%l\fP
+The line (tty) the user is logged in on, without `\fB/dev/\fP' prefix\&.
+If the name starts with `\fB/dev/tty\fP', that prefix is stripped\&.
+.TP
+\fB%M\fP
+The full machine hostname\&.
+.TP
+\fB%m\fP
+The hostname up to the first `\fB\&.\fP'\&.
+An integer may follow the `\fB%\fP' to specify
+how many components of the hostname are desired\&.  With a negative integer,
+trailing components of the hostname are shown\&.
+.TP
+\fB%n\fP
+\fB$USERNAME\fP\&.
+.TP
+\fB%y\fP
+The line (tty) the user is logged in on, without `\fB/dev/\fP' prefix\&.
+This does not treat `\fB/dev/tty\fP' names specially\&.
+.PP
+.SS "Shell state"
+.PD 0
+.TP
+.PD
+\fB%#\fP
+A `\fB#\fP' if the shell is running with privileges, a `\fB%\fP' if not\&.
+Equivalent to `\fB%(!\&.#\&.%%)\fP'\&.
+The definition of `privileged', for these purposes, is that either the
+effective user ID is zero, or, if POSIX\&.1e capabilities are supported, that
+at least one capability is raised in either the Effective or Inheritable
+capability vectors\&.
+.TP
+\fB%?\fP
+The return code of the last command executed just before the prompt\&.
+.TP
+\fB%_\fP
+The status of the parser, i\&.e\&. the shell constructs (like `\fBif\fP' and
+`\fBfor\fP') that have been started on the command line\&. If given an integer
+number that many strings will be printed; zero or negative or no integer means
+print as many as there are\&.  This is most useful in prompts \fBPS2\fP for
+continuation lines and \fBPS4\fP for debugging with the \fBXTRACE\fP option; in
+the latter case it will also work non\-interactively\&.
+.TP
+.PD 0
+\fB%d\fP
+.TP
+.PD
+\fB%/\fP
+Present working directory (\fB$PWD\fP)\&.  If an integer follows the `\fB%\fP',
+it specifies a number of trailing components of \fB$PWD\fP to show; zero
+means the whole path\&.  A negative integer specifies leading components,
+i\&.e\&. \fB%\-1d\fP specifies the first component\&.
+.TP
+\fB%~\fP
+As \fB%d\fP and \fB%/\fP, but if \fB$PWD\fP has a named directory as its prefix,
+that part is replaced by a `\fB~\fP' followed by the name of the directory\&.
+If it starts with \fB$HOME\fP, that part is replaced by a `\fB~\fP'\&.
+.TP
+.PD 0
+\fB%h\fP
+.TP
+.PD
+\fB%!\fP
+Current history event number\&.
+.TP
+\fB%i\fP
+The line number currently being executed in the script, sourced file, or
+shell function given by \fB%N\fP\&.  This is most useful for debugging as part
+of \fB$PS4\fP\&.
+.TP
+\fB%j\fP
+The number of jobs\&.
+.TP
+\fB%L\fP
+The current value of \fB$SHLVL\fP\&.
+.TP
+\fB%N\fP
+The name of the script, sourced file, or shell function that zsh is
+currently executing, whichever was started most recently\&.  If there is
+none, this is equivalent to the parameter \fB$0\fP\&.  An integer may follow
+the `\fB%\fP' to specify a number of trailing path components to show; zero
+means the full path\&.  A negative integer specifies leading components\&.
+.TP
+.PD 0
+\fB%c\fP
+.TP
+.PD 0
+\fB%\&.\fP
+.TP
+.PD
+\fB%C\fP
+Trailing component of \fB$PWD\fP\&.
+An integer may follow the `\fB%\fP' to get more than one component\&.
+Unless `\fB%C\fP' is used, tilde contraction is performed first\&.  These are
+deprecated as \fB%c\fP and \fB%C\fP are equivalent to \fB%1~\fP and \fB%1/\fP,
+respectively, while explicit positive integers have the same effect as for
+the latter two sequences\&.
+.PP
+.SS "Date and time"
+.PD 0
+.TP
+.PD
+\fB%D\fP
+The date in \fIyy\fP\fB\-\fP\fImm\fP\fB\-\fP\fIdd\fP format\&.
+.TP
+\fB%T\fP
+Current time of day, in 24\-hour format\&.
+.TP
+.PD 0
+\fB%t\fP
+.TP
+.PD
+\fB%@\fP
+Current time of day, in 12\-hour, am/pm format\&.
+.TP
+\fB%*\fP
+Current time of day in 24\-hour format, with seconds\&.
+.TP
+\fB%w\fP
+The date in \fIday\fP\fB\-\fP\fIdd\fP format\&.
+.TP
+\fB%W\fP
+The date in \fImm\fP\fB/\fP\fIdd\fP\fB/\fP\fIyy\fP format\&.
+.TP
+\fB%D{\fP\fIstring\fP\fB}\fP
+\fIstring\fP is formatted using the \fBstrftime\fP function\&.
+See \fIstrftime\fP(3) for more details\&.  Three additional codes are
+available:  \fB%f\fP prints the day of the month, like \fB%e\fP but
+without any preceding space if the day is a single digit, and
+\fB%K\fP/\fB%L\fP correspond to \fB%k\fP/\fB%l\fP for the hour of the day
+(24/12 hour clock) in the same way\&.
+.PP
+.SS "Visual effects"
+.PD 0
+.TP
+.PD
+\fB%B\fP (\fB%b\fP)
+Start (stop) boldface mode\&.
+.TP
+\fB%E\fP
+Clear to end of line\&.
+.TP
+\fB%U\fP (\fB%u\fP)
+Start (stop) underline mode\&.
+.TP
+\fB%S\fP (\fB%s\fP)
+Start (stop) standout mode\&.
+.TP
+\fB%{\fP\&.\&.\&.\fB%}\fP
+Include a string as a literal escape sequence\&.
+The string within the braces should not change the cursor
+position\&.  Brace pairs can nest\&.
+.PP
+.SS "Conditional substrings"
+.PD 0
+.TP
+.PD
+\fB%v\fP
+The value of the first element of the \fBpsvar\fP array parameter\&.  Following
+the `\fB%\fP' with an integer gives that element of the array\&.  Negative
+integers count from the end of the array\&.
+.TP
+\fB%(\fP\fIx\&.true\-text\&.false\-text\fP\fB)\fP
+Specifies a ternary expression\&.  The character following the \fIx\fP is
+arbitrary; the same character is used to separate the text for the
+`true' result from that for the `false' result\&.
+This separator may not appear in the \fItrue\-text\fP, except as part of a
+%\-escape
+sequence\&.  A `\fB)\fP' may appear in the \fIfalse\-text\fP as `\fB%)\fP'\&.
+\fItrue\-text\fP
+and \fIfalse\-text\fP may both contain arbitrarily\-nested escape
+sequences, including further ternary expressions\&.
+.RS
+.PP
+The left parenthesis may be preceded or followed by a positive integer \fIn\fP,
+which defaults to zero\&.  A negative integer will be multiplied by \-1\&.
+The test character \fIx\fP may be any of the following:
+.PP
+.PD 0
+.TP
+\fB!\fP
+True if the shell is running with privileges\&.
+.TP
+\fB#\fP
+True if the effective uid of the current process is \fIn\fP\&.
+.TP
+\fB?\fP
+True if the exit status of the last command was \fIn\fP\&.
+.TP
+\fB_\fP
+True if at least \fIn\fP shell constructs were started\&.
+.TP
+\fBC\fP
+.TP
+\fB/\fP
+True if the current absolute path has at least \fIn\fP elements
+relative to the root directory, hence \fB/\fP is counted as 0 elements\&.
+.TP
+\fBc\fP
+.TP
+\fB\&.\fP
+.TP
+\fB~\fP
+True if the current path, with prefix replacement, has at
+least \fIn\fP elements relative to the root directory, hence \fB/\fP is
+counted as 0 elements\&.
+.TP
+\fBD\fP
+True if the month is equal to \fIn\fP (January = 0)\&.
+.TP
+\fBd\fP
+True if the day of the month is equal to \fIn\fP\&.
+.TP
+\fBg\fP
+True if the effective gid of the current process is \fIn\fP\&.
+.TP
+\fBj\fP
+True if the number of jobs is at least \fIn\fP\&.
+.TP
+\fBL\fP
+True if the \fBSHLVL\fP parameter is at least \fIn\fP\&.
+.TP
+\fBl\fP
+True if at least \fIn\fP characters have already been
+printed on the current line\&.
+.TP
+\fBS\fP
+True if the \fBSECONDS\fP parameter is at least \fIn\fP\&.
+.TP
+\fBT\fP
+True if the time in hours is equal to \fIn\fP\&.
+.TP
+\fBt\fP
+True if the time in minutes is equal to \fIn\fP\&.
+.TP
+\fBv\fP
+True if the array \fBpsvar\fP has at least \fIn\fP elements\&.
+.TP
+\fBw\fP
+True if the day of the week is equal to \fIn\fP (Sunday = 0)\&.
+.PD
+.RE
+.TP
+.PD 0
+\fB%<\fP\fIstring\fP\fB<\fP
+.TP
+.PD 0
+\fB%>\fP\fIstring\fP\fB>\fP
+.TP
+.PD
+\fB%[\fP\fIxstring\fP\fB]\fP
+Specifies truncation behaviour for the remainder of the prompt string\&.
+The third, deprecated, form is equivalent to `\fB%\fP\fIxstringx\fP',
+i\&.e\&. \fIx\fP may be `\fB<\fP' or `\fB>\fP'\&.
+The numeric argument, which in the third form may appear immediately
+after the `\fB[\fP', specifies the maximum permitted length of
+the various strings that can be displayed in the prompt\&.
+The \fIstring\fP will be displayed in
+place of the truncated portion of any string; note this does not
+undergo prompt expansion\&.
+.RS
+.PP
+The forms with `\fB<\fP' truncate at the left of the string,
+and the forms with `\fB>\fP' truncate at the right of the string\&.
+For example, if the current directory is `\fB/home/pike\fP',
+the prompt `\fB%8<\&.\&.<%/\fP' will expand to `\fB\&.\&.e/pike\fP'\&.
+In this string, the terminating character (`\fB<\fP', `\fB>\fP' or `\fB]\fP'),
+or in fact any character, may be quoted by a preceding `\fB\e\fP'; note
+when using \fBprint \-P\fP, however, that this must be doubled as the
+string is also subject to standard \fBprint\fP processing, in addition
+to any backslashes removed by a double quoted string:  the worst case
+is therefore `\fBprint \-P "%<\e\e\e\e<<\&.\&.\&."\fP'\&.
+.PP
+If the \fIstring\fP is longer than the specified truncation length,
+it will appear in full, completely replacing the truncated string\&.
+.PP
+The part of the prompt string to be truncated runs to the end of the
+string, or to the end of the next enclosing group of the `\fB%(\fP'
+construct, or to the next truncation encountered at the same grouping
+level (i\&.e\&. truncations inside a `\fB%(\fP' are separate), which
+ever comes first\&.  In particular, a truncation with argument zero
+(e\&.g\&. `\fB%<<\fP') marks the end of the range of the string to be
+truncated while turning off truncation from there on\&. For example, the
+prompt '%10<\&.\&.\&.<%~%<<%# ' will print a truncated representation of the
+current directory, followed by a `\fB%\fP' or `\fB#\fP', followed by a
+space\&.  Without the `\fB%<<\fP', those two characters would be included
+in the string to be truncated\&.
+.RE
+.RE
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshmodules.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshmodules.1
@@ -0,0 +1,2926 @@
+.TH "ZSHMODULES" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshmodules \- zsh loadable modules
+.\" Yodl file: Zsh/modules.yo
+.SH "DESCRIPTION"
+Some optional parts of zsh are in modules, separate from the core
+of the shell\&.  Each of these modules may be linked in to the
+shell at build time,
+or can be dynamically linked while the shell is running
+if the installation supports this feature\&.  The modules that
+are bundled with the zsh distribution are:
+.PP
+.\" Yodl file: Zsh/modlist.yo
+.PD 0
+.TP
+.PD
+\fBzsh/cap\fP
+Builtins for manipulating POSIX\&.1e (POSIX\&.6) capability (privilege) sets\&.
+.TP
+\fBzsh/clone\fP
+A builtin that can clone a running shell onto another terminal\&.
+.TP
+\fBzsh/compctl\fP
+The \fBcompctl\fP builtin for controlling completion\&.
+.TP
+\fBzsh/complete\fP
+The basic completion code\&.
+.TP
+\fBzsh/complist\fP
+Completion listing extensions\&.
+.TP
+\fBzsh/computil\fP
+A module with utility builtins needed for the shell function based
+completion system\&.
+.TP
+\fBzsh/datetime\fP
+Some date/time commands and parameters\&.
+.TP
+\fBzsh/deltochar\fP
+A ZLE function duplicating EMACS' \fBzap\-to\-char\fP\&.
+.TP
+\fBzsh/example\fP
+An example of how to write a module\&.
+.TP
+\fBzsh/files\fP
+Some basic file manipulation commands as builtins\&.
+.TP
+\fBzsh/mapfile\fP
+Access to external files via a special associative array\&.
+.TP
+\fBzsh/mathfunc\fP
+Standard scientific functions for use in mathematical evaluations\&.
+.TP
+\fBzsh/parameter\fP
+Access to internal hash tables via special associative arrays\&.
+.TP
+\fBzsh/pcre\fP
+Interface to the PCRE library\&.
+.TP
+\fBzsh/sched\fP
+A builtin that provides a timed execution facility within the shell\&.
+.TP
+\fBzsh/net/socket\fP
+Manipulation of Unix domain sockets
+.TP
+\fBzsh/stat\fP
+A builtin command interface to the \fBstat\fP system call\&.
+.TP
+\fBzsh/system\fP
+A builtin interface to various low\-level system features\&.
+.TP
+\fBzsh/net/tcp\fP
+Manipulation of TCP sockets
+.TP
+\fBzsh/termcap\fP
+Interface to the termcap database\&.
+.TP
+\fBzsh/terminfo\fP
+Interface to the terminfo database\&.
+.TP
+\fBzsh/zftp\fP
+A builtin FTP client\&.
+.TP
+\fBzsh/zle\fP
+The Zsh Line Editor, including the \fBbindkey\fP and \fBvared\fP builtins\&.
+.TP
+\fBzsh/zleparameter\fP
+Access to internals of the Zsh Line Editor via parameters\&.
+.TP
+\fBzsh/zprof\fP
+A module allowing profiling for shell functions\&.
+.TP
+\fBzsh/zpty\fP
+A builtin for starting a command in a pseudo\-terminal\&.
+.TP
+\fBzsh/zselect\fP
+Block and return when file descriptors are ready\&.
+.TP
+\fBzsh/zutil\fP
+Some utility builtins, e\&.g\&. the one for supporting configuration via 
+styles\&.
+.\" Yodl file: Zsh/modmenu.yo
+.SH "THE ZSH/CAP MODULE"
+.\" Yodl file: Zsh/mod_cap.yo
+
+The \fBzsh/cap\fP module is used for manipulating POSIX\&.1e (POSIX\&.6) capability
+sets\&.  If the operating system does not support this interface, the
+builtins defined by this module will do nothing\&.
+The builtins in this module are:
+.PP
+.PD 0
+.TP
+.PD
+\fBcap\fP [ \fIcapabilities\fP ]
+Change the shell's process capability sets to the specified \fIcapabilities\fP,
+otherwise display the shell's current capabilities\&.
+.TP
+\fBgetcap\fP \fIfilename\fP \&.\&.\&.
+This is a built\-in implementation of the POSIX standard utility\&.  It displays
+the capability sets on each specified \fIfilename\fP\&.
+.TP
+\fBsetcap\fP \fIcapabilities\fP \fIfilename\fP \&.\&.\&.
+This is a built\-in implementation of the POSIX standard utility\&.  It sets
+the capability sets on each specified \fIfilename\fP to the specified
+\fIcapabilities\fP\&.
+.SH "THE ZSH/CLONE MODULE"
+.\" Yodl file: Zsh/mod_clone.yo
+
+The \fBzsh/clone\fP module makes available one builtin command:
+.PP
+.PD 0
+.TP
+.PD
+\fBclone\fP \fItty\fP
+Creates a forked instance of the current shell, attached to the specified
+\fItty\fP\&.  In the new shell, the \fBPID\fP, \fBPPID\fP and \fBTTY\fP special
+parameters are changed appropriately\&.  \fB$!\fP is set to zero in the new
+shell, and to the new shell's PID in the original shell\&.
+.RS
+.PP
+The return value of the builtin is zero in both shells if successful,
+and non\-zero on error\&.
+.PP
+The target of \fBclone\fP should be an unused terminal, such as an unused virtual
+console or a virtual terminal created by
+.PP
+xterm \-e sh \-c 'trap : INT QUIT TSTP; tty; while :; do sleep 100000000; done'
+.PP
+Some words of explanation are warranted about this long xterm command
+line: when doing clone on a pseudo\-terminal, some other session
+("session" meant as a unix session group, or SID) is already owning
+the terminal\&. Hence the cloned zsh cannot acquire the pseudo\-terminal
+as a controlling tty\&. That means two things:
+.PP
+the job control signals will go to the sh\-started\-by\-xterm process
+      group (that's why we disable INT QUIT and TSTP with trap; otherwise
+      the while loop could get suspended or killed)
+.PP
+the cloned shell will have job control disabled, and the job
+      control keys (control\-C, control\-\e and control\-Z) will not work\&.
+.PP
+This does not apply when cloning to an \fBunused\fP vc\&.
+.PP
+Cloning to an used (and unprepared) terminal will result in two
+processes reading simultaneously from the same terminal, with
+input bytes going randomly to either process\&.
+.PP
+\fBclone\fP is mostly useful as a shell built\-in replacement for
+openvt\&.
+.RE
+.RE
+.SH "THE ZSH/COMPCTL MODULE"
+.\" Yodl file: Zsh/mod_compctl.yo
+
+The \fBzsh/compctl\fP module makes available two builtin commands\&. \fBcompctl\fP,
+is the old, deprecated way to control completions for ZLE\&.  See
+\fIzshcompctl\fP(1)\&.
+The other builtin command, \fBcompcall\fP can be used in user\-defined
+completion widgets, see
+\fIzshcompwid\fP(1)\&.
+.SH "THE ZSH/COMPLETE MODULE"
+.\" Yodl file: Zsh/mod_complete.yo
+
+The \fBzsh/complete\fP module makes available several builtin commands which
+can be used in user\-defined completion widgets, see
+\fIzshcompwid\fP(1)\&.
+.SH "THE ZSH/COMPLIST MODULE"
+.\" Yodl file: Zsh/mod_complist.yo
+
+The \fBzsh/complist\fP module offers three extensions to completion listings:
+the ability to highlight matches in such a list, the ability to
+scroll through long lists and a different style of menu completion\&.
+.PP
+.SS "Colored completion listings"
+Whenever one of the parameters \fBZLS_COLORS\fP or \fBZLS_COLOURS\fP is set 
+and the \fBzsh/complist\fP module is loaded or linked into the shell,
+completion lists will be colored\&.  Note, however, that \fBcomplist\fP will
+not automatically be loaded if it is not linked in:  on systems with
+dynamic loading, `\fBzmodload zsh/complist\fP' is required\&.
+.PP
+The parameters \fBZLS_COLORS\fP and \fBZLS_COLOURS\fP describe how matches
+are highlighted\&.  To turn on highlighting an empty value suffices, in
+which case all the default values given below will be used\&.  The format of
+the value of these parameters is the same as used by the GNU version of the
+\fBls\fP command: a colon\-separated list of specifications of the form
+`\fIname\fP=\fIvalue\fP'\&.  The \fIname\fP may be one of the following strings,
+most of which specify file types for which the \fIvalue\fP will be used\&.
+The strings and their default values are:
+.PP
+.PD 0
+.TP
+.PD
+\fBno 0\fP
+for normal text (i\&.e\&. when displaying something other than a matched file)
+.TP
+\fBfi 0\fP
+for regular files
+.TP
+\fBdi 32\fP
+for directories
+.TP
+\fBln 36\fP
+for symbolic links
+.TP
+\fBpi 31\fP
+for named pipes (FIFOs)
+.TP
+\fBso 33\fP
+for sockets
+.TP
+\fBbd 44;37\fP
+for block devices
+.TP
+\fBcd 44;37\fP
+for character devices
+.TP
+\fBex 35\fP
+for executable files
+.TP
+\fBmi\fP \fInone\fP
+for a non\-existent file (default is the value defined for \fBfi\fP)
+.TP
+\fBlc \ee[\fP
+for the left code (see below)
+.TP
+\fBrc m\fP
+for the right code
+.TP
+\fBtc 0\fP
+for the character indicating the file type  printed after filenames if
+the \fBLIST_TYPES\fP option is set
+.TP
+\fBsp 0\fP
+for the spaces printed after matches to align the next column
+.TP
+\fBec\fP \fInone\fP
+for the end code
+.PP
+Apart from these strings, the \fIname\fP may also be an asterisk
+(`\fB*\fP') followed by any string\&. The \fIvalue\fP given for such a
+string will be used for all files whose name ends with the string\&.
+The \fIname\fP may also be an equals sign (`\fB=\fP') followed by a
+pattern\&.  The \fIvalue\fP given for this pattern will be used for all
+matches (not just filenames) whose display string are matched by
+the pattern\&.  Definitions for both of these take precedence over the
+values defined for file types and the form with the leading asterisk 
+takes precedence over the form with the leading equal sign\&.
+.PP
+The last form also allows different parts of the displayed
+strings to be colored differently\&.  For this, the pattern has to use the
+`\fB(#b)\fP' globbing flag and pairs of parentheses surrounding the
+parts of the strings that are to be colored differently\&.  In this case 
+the \fIvalue\fP may consist of more than one color code separated by
+equal signs\&.  The first code will be used for all parts for which no
+explicit code is specified and the following codes will be used for
+the parts matched by the sub\-patterns in parentheses\&.  For example,
+the specification `\fB=(#b)(?)*(?)=0=3=7\fP' will be used for all
+matches which are at least two characters long and will use
+the code `\fB3\fP' for the first character, `\fB7\fP' for the last
+character and `\fB0\fP' for the rest\&.
+.PP
+All three forms of \fIname\fP may be preceded by a pattern in
+parentheses\&.  If this is given, the \fIvalue\fP will be used
+only for matches in groups whose names are matched by the pattern
+given in the parentheses\&.  For example, `\fB(g*)m*=43\fP' highlights all
+matches beginning with `\fBm\fP' in groups whose names  begin with
+`\fBg\fP' using the color code `\fB43\fP'\&.  In case of the `\fBlc\fP',
+`\fBrc\fP', and `\fBec\fP' codes, the group pattern is ignored\&.
+.PP
+Note also that all patterns are tried in the order in which they
+appear in the parameter value until the first one matches which is
+then used\&.
+.PP
+When printing a match, the code prints the value of \fBlc\fP, the value
+for the file\-type or the last matching specification with a `\fB*\fP',
+the value of \fBrc\fP, the string to display for the match itself, and
+then the value of \fBec\fP if that is defined or the values of \fBlc\fP,
+\fBno\fP, and \fBrc\fP if \fBec\fP is not defined\&.
+.PP
+The default values are ISO 6429 (ANSI) compliant and can be used on
+vt100 compatible terminals such as \fBxterm\fPs\&.  On monochrome terminals
+the default values will have no visible effect\&.  The \fBcolors\fP
+function from the contribution can be used to get associative arrays
+containing the codes for ANSI terminals (see
+the section `Other Functions' in \fIzshcontrib\fP(1))\&.  For example, after loading \fBcolors\fP, one could use
+`\fB$colors[red]\fP' to get the code for foreground color red and
+`\fB$colors[bg\-green]\fP' for the code for background color green\&.
+.PP
+If the completion system invoked by compinit is used, these
+parameters should not be set directly because the system controls them 
+itself\&.  Instead, the \fBlist\-colors\fP style should be used (see
+the section `Completion System Configuration' in \fIzshcompsys\fP(1))\&.
+.PP
+.SS "Scrolling in completion listings"
+To enable scrolling through a completion list, the \fBLISTPROMPT\fP
+parameter must be set\&.  Its value will be used as the prompt; if it
+is the empty string, a default prompt will be used\&.  The value may
+contain escapes of the form `\fB%x\fP'\&.  It supports the escapes
+`\fB%B\fP', `\fB%b\fP', `\fB%S\fP', `\fB%s\fP', `\fB%U\fP', `\fB%u\fP' and
+`\fB%{\&.\&.\&.%}\fP' used also in shell prompts as well as three pairs of
+additional sequences: a `\fB%l\fP' or `\fB%L\fP' is replaced by the number
+of the last line shown and the total number of lines in the form
+`\fInumber\fP\fB/\fP\fItotal\fP'; a `\fB%m\fP' or `\fB%M\fP' is replaced with
+the number of the last match shown and the total number of matches; and 
+`\fB%p\fP' or `\fB%P\fP' is replaced with `\fBTop\fP', `\fBBottom\fP' or the
+position of the first line shown in percent of the total number of
+lines, respectively\&.  In each of these cases the form with the uppercase
+letter will be replaced with a string of fixed width, padded to the
+right with spaces, while the lowercase form will not be padded\&.
+.PP
+If the parameter \fBLISTPROMPT\fP is set, the completion code will not ask if
+the list should be shown\&.  Instead it immediately starts displaying the
+list, stopping after the first screenful, showing the prompt at the bottom,
+waiting for a keypress after temporarily switching to the \fBlistscroll\fP
+keymap\&.  Some of the zle functions have a special meaning while scrolling
+lists:
+.PP
+.PD 0
+.TP
+.PD
+\fBsend\-break\fP
+stops listing discarding the key pressed
+.TP
+.PD 0
+\fBaccept\-line\fP, \fBdown\-history\fP, \fBdown\-line\-or\-history\fP
+.TP
+.PD
+\fBdown\-line\-or\-search\fP, \fBvi\-down\-line\-or\-history\fP
+scrolls forward one line
+.TP
+.PD 0
+\fBcomplete\-word\fP, \fBmenu\-complete\fP, \fBexpand\-or\-complete\fP
+.TP
+.PD
+\fBexpand\-or\-complete\-prefix\fP, \fBmenu\-complete\-or\-expand\fP
+scrolls forward one screenful
+.PP
+Every other character stops listing and immediately processes the key
+as usual\&.  Any key that is not bound in the \fBlistscroll\fP keymap or
+that is bound to \fBundefined\-key\fP is looked up in the keymap
+currently selected\&.
+.PP
+As for the \fBZLS_COLORS\fP and \fBZLS_COLOURS\fP parameters,
+\fBLISTPROMPT\fP should not be set directly when using the shell
+function based completion system\&.  Instead, the \fBlist\-prompt\fP style
+should be used\&.
+.PP
+.SS "Menu selection"
+The \fBzsh/complist\fP module also offers an alternative style of selecting
+matches from a list, called menu selection, which can be used if the
+shell is set up to return to the last prompt after showing a
+completion list (see the \fBALWAYS_LAST_PROMPT\fP option in
+\fIzshoptions\fP(1))\&.  It can be invoked directly by
+the widget \fBmenu\-select\fP defined by the module\&.  Alternatively,
+the parameter \fBMENUSELECT\fP can be set to an integer, which gives the
+minimum number of matches that must be present before menu selection is
+automatically turned on\&.  This second method requires that menu completion
+be started, either directly from a widget such as \fBmenu\-complete\fP, or due
+to one of the options \fBMENU_COMPLETE\fP or \fBAUTO_MENU\fP being set\&.  If
+\fBMENUSELECT\fP is set, but is 0, 1 or empty, menu selection will always be
+started during an ambiguous menu completion\&.
+.PP
+When using the completion system based on shell functions, the
+\fBMENUSELECT\fP parameter should not be used (like the \fBZLS_COLORS\fP
+and \fBZLS_COLOURS\fP parameters described above)\&.  Instead, the \fBmenu\fP 
+style should be used with the \fBselect=\fP\fI\&.\&.\&.\fP keyword\&.
+.PP
+After menu selection is started, the matches will be listed\&. If there
+are more matches than fit on the screen, only the first screenful is
+shown\&.  The
+matches to insert into the command line can be selected from this
+list\&.  In the list one match is highlighted using the value for \fBma\fP
+from the \fBZLS_COLORS\fP or \fBZLS_COLOURS\fP parameter\&.  The default
+value for this is `\fB7\fP' which forces the selected match to be
+highlighted using standout mode on a vt100\-compatible terminal\&.  If
+neither \fBZLS_COLORS\fP nor \fBZLS_COLOURS\fP is set, the same terminal
+control sequence as for the `\fB%S\fP' escape in prompts is used\&.
+.PP
+If there are more matches than fit on the screen and the parameter
+\fBMENUPROMPT\fP is set, its value will be shown below the matches\&.  It
+supports the same escape sequences as \fBLISTPROMPT\fP, but the number
+of the match or line shown will be that of the one where the mark is
+placed\&.  If its value is the empty string, a default prompt will be
+used\&.
+.PP
+The \fBMENUSCROLL\fP parameter can be used to specify how the list is
+scrolled\&.  If the parameter is unset, this is done line by line, if it
+is set to `\fB0\fP' (zero), the list will scroll half the number of
+lines of the screen\&.  If the value is positive, it gives the number of
+lines to scroll and if it is negative, the list will be scrolled
+the number of lines of the screen minus the (absolute) value\&.
+.PP
+As for the \fBZLS_COLORS\fP, \fBZLS_COLOURS\fP and \fBLISTPROMPT\fP
+parameters, neither \fBMENUPROMPT\fP nor \fBMENUSCROLL\fP should be
+set directly when using the shell function based completion
+system\&.  Instead, the \fBselect\-prompt\fP and \fBselect\-scroll\fP styles
+should be used\&.
+.PP
+The completion code sometimes decides not to show all of the matches
+in the list\&.  These hidden matches are either matches for which the
+completion function which added them explicitly requested that they
+not appear in the list (using the \fB\-n\fP option of the \fBcompadd\fP
+builtin command) or they are matches which duplicate a string already
+in the list (because they differ only in things like prefixes or
+suffixes that are not displayed)\&.  In the list used for menu selection,
+however, even these matches are shown so that it is possible to select
+them\&.  To highlight such matches the \fBhi\fP and \fBdu\fP capabilities in
+the \fBZLS_COLORS\fP and \fBZLS_COLOURS\fP parameters are supported for
+hidden matches of the first and second kind, respectively\&.
+.PP
+Selecting matches is done by moving the mark around using the zle movement
+functions\&.  When not all matches can be shown on the screen at the same 
+time, the list will scroll up and down when crossing the top or
+bottom line\&.  The following zle functions have special meaning during
+menu selection:
+.PP
+.PD 0
+.TP
+.PD
+\fBaccept\-line\fP
+accepts the current match and leaves menu selection
+.TP
+\fBsend\-break\fP
+leaves menu selection and restores the previous contents of the
+command line
+.TP
+\fBredisplay\fP, \fBclear\-screen\fP
+execute their normal function without leaving menu selection
+.TP
+\fBaccept\-and\-hold\fP, \fBaccept\-and\-menu\-complete\fP
+accept the currently inserted match and continue selection allowing to 
+select the next match to insert into the line
+.TP
+\fBaccept\-and\-infer\-next\-history\fP
+accepts the current match and then tries completion with
+menu selection again;  in the case of files this allows one to select
+a directory and immediately attempt to complete files in it;  if there 
+are no matches, a message is shown and one can use \fBundo\fP to go back 
+to completion on the previous level, every other key leaves menu
+selection (including the other zle functions which are otherwise
+special during menu selection)
+.TP
+\fBundo\fP
+removes matches inserted during the menu selection by one of the three 
+functions before
+.TP
+.PD 0
+\fBdown\-history\fP, \fBdown\-line\-or\-history\fP
+.TP
+.PD
+\fBvi\-down\-line\-or\-history\fP,  \fBdown\-line\-or\-search\fP
+moves the mark one line down
+.TP
+.PD 0
+\fBup\-history\fP, \fBup\-line\-or\-history\fP
+.TP
+.PD
+\fBvi\-up\-line\-or\-history\fP, \fBup\-line\-or\-search\fP
+moves the mark one line up
+.TP
+\fBforward\-char\fP, \fBvi\-forward\-char\fP
+moves the mark one column right
+.TP
+\fBbackward\-char\fP, \fBvi\-backward\-char\fP
+moves the mark one column left
+.TP
+.PD 0
+\fBforward\-word\fP, \fBvi\-forward\-word\fP
+.TP
+.PD
+\fBvi\-forward\-word\-end\fP, \fBemacs\-forward\-word\fP
+moves the mark one screenful down
+.TP
+\fBbackward\-word\fP, \fBvi\-backward\-word\fP, \fBemacs\-backward\-word\fP
+moves the mark one screenful up
+.TP
+\fBvi\-forward\-blank\-word\fP, \fBvi\-forward\-blank\-word\-end\fP
+moves the mark to the first line of the next group of matches
+.TP
+\fBvi\-backward\-blank\-word\fP
+moves the mark to the last line of the previous group of matches
+.TP
+\fBbeginning\-of\-history\fP
+moves the mark to the first line
+.TP
+\fBend\-of\-history\fP
+moves the mark to the last line
+.TP
+.PD 0
+\fBbeginning\-of\-buffer\-or\-history\fP, \fBbeginning\-of\-line\fP
+.TP
+.PD
+\fBbeginning\-of\-line\-hist\fP, \fBvi\-beginning\-of\-line\fP
+moves the mark to the leftmost column
+.TP
+.PD 0
+\fBend\-of\-buffer\-or\-history\fP, \fBend\-of\-line\fP
+.TP
+.PD
+\fBend\-of\-line\-hist\fP, \fBvi\-end\-of\-line\fP
+moves the mark to the rightmost column
+.TP
+.PD 0
+\fBcomplete\-word\fP, \fBmenu\-complete\fP, \fBexpand\-or\-complete\fP
+.TP
+.PD
+\fBexpand\-or\-complete\-prefix\fP, \fBmenu\-expand\-or\-complete\fP
+moves the mark to the next match
+.TP
+\fBreverse\-menu\-complete\fP
+moves the mark to the previous match
+.TP
+\fBvi\-insert\fP
+this toggles between normal and interactive mode; in interactive mode
+the keys bound to \fBself\-insert\fP and \fBself\-insert\-unmeta\fP insert
+into the command line as in normal editing mode but without leaving
+menu selection; after each character completion is tried again and the
+list changes to contain only the new matches; the completion widgets
+make the longest unambiguous string be inserted in the command line
+and \fBundo\fP and \fBbackward\-delete\-char\fP go back to the previous set
+of matches
+.TP
+\fBhistory\-incremental\-search\-forward\fP,
+\fBhistory\-incremental\-search\-backward\fP
+this starts incremental searches in the list of completions displayed;
+in this mode, \fBaccept\-line\fP only leaves incremental search, going
+back to the normal menu selection mode
+.PP
+All movement functions wrap around at the edges; any other zle function not
+listed leaves menu selection and executes that function\&.  It is possible to
+make widgets in the above list do the same by using the form of the widget
+with a `\fB\&.\fP' in front\&.  For example, the widget `\fB\&.accept\-line\fP' has
+the effect of leaving menu selection and accepting the entire command line\&.
+.PP
+During this selection the widget uses the keymap \fBmenuselect\fP\&.  Any
+key that is not defined in this keymap or that is bound to
+\fBundefined\-key\fP is looked up in the keymap currently selected\&.  This
+is used to ensure that the most important keys used during selection
+(namely the cursor keys, return, and TAB) have sensible defaults\&.  However,
+keys in the \fBmenuselect\fP keymap can be modified directly using the
+\fBbindkey\fP builtin command (see
+\fIzshmodules\fP(1))\&. For example, to make the return key leave menu selection without
+accepting the match currently selected one could call
+.PP
+.RS
+.nf
+\fBbindkey \-M menuselect '^M' send\-break\fP
+.fi
+.RE
+.PP
+after loading the \fBzsh/complist\fP module\&.
+.SH "THE ZSH/COMPUTIL MODULE"
+.\" Yodl file: Zsh/mod_computil.yo
+
+The \fBzsh/computil\fP module adds several builtin commands that are used by
+some of the completion functions in the completion system based on shell
+functions (see 
+\fIzshcompsys\fP(1)
+)\&.  Except for \fBcompquote\fP these builtin commands are very
+specialised and thus not very interesting when writing your own
+completion functions\&.  In summary, these builtin commands are:
+.PP
+.PD 0
+.TP
+.PD
+\fBcomparguments\fP
+This is used by the \fB_arguments\fP function to do the argument and
+command line parsing\&.  Like \fBcompdescribe\fP it has an option \fB\-i\fP to 
+do the parsing and initialize some internal state and various options
+to access the state information to decide what should be completed\&.
+.TP
+\fBcompdescribe\fP
+This is used by the \fB_describe\fP function to build the displays for
+the matches and to get the strings to add as matches with their
+options\&.  On the first call one of the options \fB\-i\fP or \fB\-I\fP should be
+supplied as the first argument\&.  In the first case, display strings without
+the descriptions will be generated, in the second case, the string used to
+separate the matches from their descriptions must be given as the
+second argument and the descriptions (if any) will be shown\&.  All other 
+arguments are like the definition arguments to \fB_describe\fP itself\&.
+.RS
+.PP
+Once \fBcompdescribe\fP has been called with either the \fB\-i\fP or the
+\fB\-I\fP option, it can be repeatedly called with the \fB\-g\fP option and
+the names of five arrays as its arguments\&.  This will step through the
+different sets of matches and store the options in the first array,
+the strings with descriptions in the second, the matches for these in
+the third, the strings without descriptions in the fourth, and the
+matches for them in the fifth array\&.  These are then directly given to
+\fBcompadd\fP to register the matches with the completion code\&.
+.RE
+.TP
+\fBcompfiles\fP
+Used by the \fB_path_files\fP function to optimize complex recursive
+filename generation (globbing)\&.  It does three things\&.  With the
+\fB\-p\fP and \fB\-P\fP options it builds the glob patterns to use,
+including the paths already handled and trying to optimize the
+patterns with respect to the prefix and suffix from the line and the
+match specification currently used\&.  The \fB\-i\fP option does the
+directory tests for the \fBignore\-parents\fP style and the \fB\-r\fP option 
+tests if a component for some of the matches are equal to the string
+on the line and removes all other matches if that is true\&.
+.TP
+\fBcompgroups\fP
+Used by the \fB_tags\fP function to implement the internals of the
+\fBgroup\-order\fP style\&.  This only takes its arguments as names of
+completion groups and creates the groups for it (all six types: sorted 
+and unsorted, both without removing duplicates, with removing all
+duplicates and with removing consecutive duplicates)\&.
+.TP
+\fBcompquote\fP [ \fB\-p\fP ] \fInames\fP \&.\&.\&.
+There may be reasons to write completion functions that have to add
+the matches using the \fB\-Q\fP option to \fBcompadd\fP and perform quoting
+themselves\&.  Instead of interpreting the first character of the
+\fBall_quotes\fP key of the \fBcompstate\fP special association and using
+the \fBq\fP flag for parameter expansions, one can use this builtin
+command\&.  The arguments are the names of scalar or array parameters
+and the values of these parameters are quoted as needed for the
+innermost quoting level\&.  If the \fB\-p\fP option is given, quoting is
+done as if there is some prefix before the values of the parameters,
+so that a leading equal sign will not be quoted\&.
+.RS
+.PP
+The return value is non\-zero in case of an error and zero otherwise\&.
+.RE
+.TP
+.PD 0
+\fBcomptags\fP
+.TP
+.PD
+\fBcomptry\fP
+These implement the internals of the tags mechanism\&.
+.TP
+\fBcompvalues\fP
+Like \fBcomparguments\fP, but for the \fB_values\fP function\&.
+.SH "THE ZSH/DATETIME MODULE"
+.\" Yodl file: Zsh/mod_datetime.yo
+
+The \fBzsh/datetime\fP module makes available one builtin command:
+.PP
+.PD 0
+.TP
+.PD
+\fBstrftime\fP [ \fB\-s\fP \fIscalar\fP ] \fIformat\fP \fIepochtime\fP 
+Output the date denoted by \fIepochtime\fP in the \fIformat\fP
+specified\&.
+.RS
+.PP
+If \fB\-s\fP \fIscalar\fP is given, assign the date to \fIscalar\fP instead
+of printing it\&.
+.RE
+.RE
+.PP
+The \fBzsh/datetime\fP module makes available one parameter:
+.PP
+.PD 0
+.TP
+.PD
+\fBEPOCHSECONDS\fP
+An integer value representing the number of seconds since the
+epoch\&.
+.SH "THE ZSH/DELTOCHAR MODULE"
+.\" Yodl file: Zsh/mod_deltochar.yo
+
+The \fBzsh/deltochar\fP module makes available two ZLE functions:
+.PP
+.PD 0
+.TP
+.PD
+\fBdelete\-to\-char\fP
+Read a character from the keyboard, and
+delete from the cursor position up to and including the next
+(or, with repeat count \fIn\fP, the \fIn\fPth) instance of that character\&.
+Negative repeat counts mean delete backwards\&.
+.TP
+\fBzap\-to\-char\fP
+This behaves like \fBdelete\-to\-char\fP, except that the final occurrence of
+the character itself is not deleted\&.
+.SH "THE ZSH/EXAMPLE MODULE"
+.\" Yodl file: Zsh/mod_example.yo
+
+The \fBzsh/example\fP module makes available one builtin command:
+.PP
+.PD 0
+.TP
+.PD
+\fBexample\fP [ \fB\-flags\fP ] [ \fIargs\fP \&.\&.\&. ]
+Displays the flags and arguments it is invoked with\&.
+.PP
+The purpose of the module is to serve as an example of how to write a
+module\&.
+.SH "THE ZSH/FILES MODULE"
+.\" Yodl file: Zsh/mod_files.yo
+
+The \fBzsh/files\fP module makes some standard commands available as builtins:
+.PP
+.PD 0
+.TP
+.PD
+\fBchgrp\fP [ \fB\-Rs\fP ] \fIgroup\fP \fIfilename\fP \&.\&.\&.
+Changes group of files specified\&.  This is equivalent to \fBchown\fP with
+a \fIuser\-spec\fP argument of `\fB:\fP\fIgroup\fP'\&.
+.TP
+\fBchown\fP [ \fB\-Rs\fP ] \fIuser\-spec\fP \fIfilename\fP \&.\&.\&.
+Changes ownership and group of files specified\&.
+.RS
+.PP
+The \fIuser\-spec\fP can be in four forms:
+.PP
+.PD 0
+.TP
+\fIuser\fP
+change owner to \fIuser\fP; do not change group
+.TP
+\fIuser\fP\fB::\fP
+change owner to \fIuser\fP; do not change group
+.TP
+\fIuser\fP\fB:\fP
+change owner to \fIuser\fP; change group to \fIuser\fP's primary group
+.TP
+\fIuser\fP\fB:\fP\fIgroup\fP
+change owner to \fIuser\fP; change group to \fIgroup\fP
+.TP
+\fB:\fP\fIgroup\fP
+do not change owner; change group to \fIgroup\fP
+.PD
+.PP
+In each case, the `\fB:\fP' may instead be a `\fB\&.\fP'\&.  The rule is that
+if there is a `\fB:\fP' then the separator is `\fB:\fP', otherwise
+if there is a `\fB\&.\fP' then the separator is `\fB\&.\fP', otherwise
+there is no separator\&.
+.PP
+Each of \fIuser\fP and \fIgroup\fP may be either a username (or group name, as
+appropriate) or a decimal user ID (group ID)\&.  Interpretation as a name
+takes precedence, if there is an all\-numeric username (or group name)\&.
+.PP
+The \fB\-R\fP option causes \fBchown\fP to recursively descend into directories,
+changing the ownership of all files in the directory after
+changing the ownership of the directory itself\&.
+.PP
+The \fB\-s\fP option is a zsh extension to \fBchown\fP functionality\&.  It enables
+paranoid behaviour, intended to avoid security problems involving
+a \fBchown\fP being tricked into affecting files other than the ones
+intended\&.  It will refuse to follow symbolic links, so that (for example)
+``\fBchown luser /tmp/foo/passwd\fP'' can't accidentally chown \fB/etc/passwd\fP
+if \fB/tmp/foo\fP happens to be a link to \fB/etc\fP\&.  It will also check
+where it is after leaving directories, so that a recursive chown of
+a deep directory tree can't end up recursively chowning \fB/usr\fP as
+a result of directories being moved up the tree\&.
+.RE
+.TP
+.PD 0
+\fBln\fP [ \fB\-dfis\fP ] \fIfilename\fP \fIdest\fP
+.TP
+.PD
+\fBln\fP [ \fB\-dfis\fP ] \fIfilename\fP \&.\&.\&. \fIdir\fP
+Creates hard (or, with \fB\-s\fP, symbolic) links\&.  In the first form, the
+specified \fIdest\fPination is created, as a link to the specified
+\fIfilename\fP\&.  In the second form, each of the \fIfilename\fPs is
+taken in turn, and linked to a pathname in the specified \fIdir\fPectory
+that has the same last pathname component\&.
+.RS
+.PP
+Normally, \fBln\fP will not attempt to create hard links to
+directories\&.  This check can be overridden using the \fB\-d\fP option\&.
+Typically only the super\-user can actually succeed in creating
+hard links to directories\&.
+This does not apply to symbolic links in any case\&.
+.PP
+By default, existing files cannot be replaced by links\&.
+The \fB\-i\fP option causes the user to be queried about replacing
+existing files\&.  The \fB\-f\fP option causes existing files to be
+silently deleted, without querying\&.  \fB\-f\fP takes precedence\&.
+.RE
+.TP
+\fBmkdir\fP [ \fB\-p\fP ] [ \fB\-m\fP \fImode\fP ] \fIdir\fP \&.\&.\&.
+Creates directories\&.  With the \fB\-p\fP option, non\-existing parent
+directories are first created if necessary, and there will be
+no complaint if the directory already exists\&.
+The \fB\-m\fP option can be used to specify (in octal) a set of file permissions
+for the created directories, otherwise mode 777 modified by the current
+\fBumask\fP (see \fIumask\fP(2)) is used\&.
+.TP
+.PD 0
+\fBmv\fP [ \fB\-fi\fP ] \fIfilename\fP \fIdest\fP
+.TP
+.PD
+\fBmv\fP [ \fB\-fi\fP ] \fIfilename\fP \&.\&.\&. \fIdir\fP
+Moves files\&.  In the first form, the specified \fIfilename\fP is moved
+to the specified \fIdest\fPination\&.  In the second form, each of the
+\fIfilename\fPs is
+taken in turn, and moved to a pathname in the specified \fIdir\fPectory
+that has the same last pathname component\&.
+.RS
+.PP
+By default, the user will be queried before replacing any file
+that the user cannot write to, but writable files will be silently
+removed\&.
+The \fB\-i\fP option causes the user to be queried about replacing
+any existing files\&.  The \fB\-f\fP option causes any existing files to be
+silently deleted, without querying\&.  \fB\-f\fP takes precedence\&.
+.PP
+Note that this \fBmv\fP will not move files across devices\&.
+Historical versions of \fBmv\fP, when actual renaming is impossible,
+fall back on copying and removing files; if this behaviour is desired,
+use \fBcp\fP and \fBrm\fP manually\&.  This may change in a future version\&.
+.RE
+.TP
+\fBrm\fP [ \fB\-dfirs\fP ] \fIfilename\fP \&.\&.\&.
+Removes files and directories specified\&.
+.RS
+.PP
+Normally, \fBrm\fP will not remove directories (except with the \fB\-r\fP
+option)\&.  The \fB\-d\fP option causes \fBrm\fP to try removing directories
+with \fBunlink\fP (see \fIunlink\fP(2)), the same method used for files\&.
+Typically only the super\-user can actually succeed in unlinking
+directories in this way\&.
+\fB\-d\fP takes precedence over \fB\-r\fP\&.
+.PP
+By default, the user will be queried before removing any file
+that the user cannot write to, but writable files will be silently
+removed\&.
+The \fB\-i\fP option causes the user to be queried about removing
+any files\&.  The \fB\-f\fP option causes files to be
+silently deleted, without querying, and suppresses all error indications\&.
+\fB\-f\fP takes precedence\&.
+.PP
+The \fB\-r\fP option causes \fBrm\fP to recursively descend into directories,
+deleting all files in the directory before removing the directory with
+the \fBrmdir\fP system call (see \fIrmdir\fP(2))\&.
+.PP
+The \fB\-s\fP option is a zsh extension to \fBrm\fP functionality\&.  It enables
+paranoid behaviour, intended to avoid common security problems involving
+a root\-run \fBrm\fP being tricked into removing files other than the ones
+intended\&.  It will refuse to follow symbolic links, so that (for example)
+``\fBrm /tmp/foo/passwd\fP'' can't accidentally remove \fB/etc/passwd\fP
+if \fB/tmp/foo\fP happens to be a link to \fB/etc\fP\&.  It will also check
+where it is after leaving directories, so that a recursive removal of
+a deep directory tree can't end up recursively removing \fB/usr\fP as
+a result of directories being moved up the tree\&.
+.RE
+.TP
+\fBrmdir\fP \fIdir\fP \&.\&.\&.
+Removes empty directories specified\&.
+.TP
+\fBsync\fP
+Calls the system call of the same name (see \fIsync\fP(2)), which
+flushes dirty buffers to disk\&.  It might return before the I/O has
+actually been completed\&.
+.SH "THE ZSH/MAPFILE MODULE"
+.\" Yodl file: Zsh/mod_mapfile.yo
+
+The \fBzsh/mapfile\fP module provides one special associative array parameter of
+the same name\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBmapfile\fP
+This associative array takes as keys the names of files; the resulting
+value is the content of the file\&.  The value is treated identically to any
+other text coming from a parameter\&.  The value may also be assigned to, in
+which case the file in question is written (whether or not it originally
+existed); or an element may be unset, which will delete the file in
+question\&.  For example, `\fBvared mapfile[myfile]\fP' works as expected,
+editing the file `\fBmyfile\fP'\&.
+.RS
+.PP
+When the array is accessed as a whole, the keys are the names of files in
+the current directory, and the values are empty (to save a huge overhead in
+memory)\&.  Thus \fB${(k)mapfile}\fP has the same affect as the glob operator
+\fB*(D)\fP, since files beginning with a dot are not special\&.  Care must be
+taken with expressions such as \fBrm ${(k)mapfile}\fP, which will delete
+every file in the current directory without the usual `\fBrm *\fP' test\&.
+.PP
+The parameter \fBmapfile\fP may be made read\-only; in that case, files
+referenced may not be written or deleted\&.
+.RE
+.RE
+.PP
+.SS "Limitations"
+.PP
+Although reading and writing of the file in question is efficiently
+handled, zsh's internal memory management may be arbitrarily baroque\&.  Thus
+it should not automatically be assumed that use of \fBmapfile\fP represents a
+gain in efficiency over use of other mechanisms\&.  Note in particular that
+the whole contents of the file will always reside physically in memory when
+accessed (possibly multiple times, due to standard parameter substitution
+operations)\&.  In particular, this means handling of sufficiently long files
+(greater than the machine's swap space, or than the range of the pointer
+type) will be incorrect\&.
+.PP
+No errors are printed or flagged for non\-existent, unreadable, or
+unwritable files, as the parameter mechanism is too low in the shell
+execution hierarchy to make this convenient\&.
+.PP
+It is unfortunate that the mechanism for loading modules does not yet allow
+the user to specify the name of the shell parameter to be given the special
+behaviour\&.
+.SH "THE ZSH/MATHFUNC MODULE"
+.\" Yodl file: Zsh/mod_mathfunc.yo
+
+The \fBzsh/mathfunc\fP module provides standard
+mathematical functions for use when
+evaluating mathematical formulae\&.  The syntax agrees with normal C and
+FORTRAN conventions, for example,
+.PP
+.RS
+.nf
+\fB(( f = sin(0\&.3) ))\fP
+.fi
+.RE
+.PP
+assigns the sine of 0\&.3 to the parameter f\&.
+.PP
+Most functions take floating point arguments and return a floating point
+value\&.  However, any necessary conversions from or to integer type will be
+performed automatically by the shell\&.  Apart from \fBatan\fP with a second
+argument and the \fBabs\fP, \fBint\fP and \fBfloat\fP functions, all functions
+behave as noted in the manual page for the corresponding C function,
+except that any arguments out of range for the function in question will be
+detected by the shell and an error reported\&.
+.PP
+The following functions take a single floating point argument: \fBacos\fP,
+\fBacosh\fP, \fBasin\fP, \fBasinh\fP, \fBatan\fP, \fBatanh\fP, \fBcbrt\fP, \fBceil\fP,
+\fBcos\fP, \fBcosh\fP, \fBerf\fP, \fBerfc\fP, \fBexp\fP, \fBexpm1\fP, \fBfabs\fP,
+\fBfloor\fP, \fBgamma\fP, \fBj0\fP, \fBj1\fP, \fBlgamma\fP, \fBlog\fP, \fBlog10\fP,
+\fBlog1p\fP, \fBlogb\fP, \fBsin\fP, \fBsinh\fP, \fBsqrt\fP, \fBtan\fP, \fBtanh\fP,
+\fBy0\fP, \fBy1\fP\&.  The \fBatan\fP function can optionally take a second
+argument, in which case it behaves like the C function \fBatan2\fP\&.
+The \fBilogb\fP function takes a single floating point argument, but
+returns an integer\&.
+.PP
+The function \fBsigngam\fP takes no arguments, and returns an integer, which
+is the C variable of the same name, as described in \fIgamma\fP(3)\&.  Note
+that it is therefore only useful immediately after a call to \fBgamma\fP or
+\fBlgamma\fP\&.  Note also that `\fBsigngam()\fP' and `\fBsigngam\fP' are distinct
+expressions\&.
+.PP
+The following functions take two floating point arguments: \fBcopysign\fP,
+\fBfmod\fP, \fBhypot\fP, \fBnextafter\fP\&.
+.PP
+The following take an integer first argument and a floating point second
+argument: \fBjn\fP, \fByn\fP\&.
+.PP
+The following take a floating point first argument and an integer second
+argument: \fBldexp\fP, \fBscalb\fP\&.
+.PP
+The function \fBabs\fP does not convert the type of its single argument; it
+returns the absolute value of either a floating point number or an
+integer\&.  The functions \fBfloat\fP and \fBint\fP convert their arguments into
+a floating point or integer value (by truncation) respectively\&.
+.PP
+Note that the C \fBpow\fP function is available in ordinary math evaluation
+as the `\fB**\fP' operator and is not provided here\&.
+.PP
+The function \fBrand48\fP is available if your system's mathematical library
+has the function \fBerand48(3)\fP\&.  It returns a pseudo\-random floating point
+number between 0 and 1\&.  It takes a single string optional argument\&.
+.PP
+If the argument is not present, the random number seed is initialised by
+three calls to the \fBrand(3)\fP function \-\-\- this produces the same random
+numbers as the next three values of \fB$RANDOM\fP\&.
+.PP
+If the argument is present, it gives the name of a scalar parameter where
+the current random number seed will be stored\&.  On the first call, the
+value must contain at least twelve hexadecimal digits (the remainder of the
+string is ignored), or the seed will be initialised in the same manner as
+for a call to \fBrand48\fP with no argument\&.  Subsequent calls to
+\fBrand48\fP(\fIparam\fP) will then maintain the seed in the
+parameter \fIparam\fP as a string of twelve hexadecimal digits, with no base
+signifier\&.  The random number sequences for different parameters are
+completely independent, and are also independent from that used by calls to
+\fBrand48\fP with no argument\&.
+.PP
+For example, consider
+.PP
+.RS
+.nf
+\fBprint $(( rand48(seed) ))
+print $(( rand48() ))
+print $(( rand48(seed) ))\fP
+.fi
+.RE
+.PP
+Assuming \fB$seed\fP does not exist, it will be initialised by the first
+call\&.  In the second call, the default seed is initialised; note, however,
+that because of the properties of \fBrand()\fP there is a correlation between
+the seeds used for the two initialisations, so for more secure uses, you
+should generate your own 12\-byte seed\&.  The third call returns to the same
+sequence of random numbers used in the first call, unaffected by the
+intervening \fBrand48()\fP\&.
+.SH "THE ZSH/PARAMETER MODULE"
+.\" Yodl file: Zsh/mod_parameter.yo
+
+The \fBzsh/parameter\fP module gives access to some of the internal hash
+tables used by the shell by defining some special parameters\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBoptions\fP
+The keys for this associative array are the names of the options that
+can be set and unset using the \fBsetopt\fP and \fBunsetopt\fP
+builtins\&. The value of each key is either the string \fBon\fP if the
+option is currently set, or the string \fBoff\fP if the option is unset\&.
+Setting a key to one of these strings is like setting or unsetting
+the option, respectively\&. Unsetting a key in this array is like
+setting it to the value \fBoff\fP\&.
+.TP
+\fBcommands\fP
+This array gives access to the command hash table\&. The keys are the
+names of external commands, the values are the pathnames of the files
+that would be executed when the command would be invoked\&. Setting a
+key in this array defines a new entry in this table in the same way as
+with the \fBhash\fP builtin\&. Unsetting a key as in `\fBunset
+"commands[foo]"\fP' removes the entry for the given key from the command 
+hash table\&.
+.TP
+\fBfunctions\fP
+This associative array maps names of enabled functions to their
+definitions\&. Setting a key in it is like defining a function with the
+name given by the key and the body given by the value\&. Unsetting a key
+removes the definition for the function named by the key\&.
+.TP
+\fBdis_functions\fP
+Like \fBfunctions\fP but for disabled functions\&.
+.TP
+\fBbuiltins\fP
+This associative array gives information about the builtin commands
+currently enabled\&. The keys are the names of the builtin commands and
+the values are either `\fBundefined\fP' for builtin commands that will
+automatically be loaded from a module if invoked or `\fBdefined\fP' for
+builtin commands that are already loaded\&.
+.TP
+\fBdis_builtins\fP
+Like \fBbuiltins\fP but for disabled builtin commands\&.
+.TP
+\fBreswords\fP
+This array contains the enabled reserved words\&.
+.TP
+\fBdis_reswords\fP
+Like \fBreswords\fP but for disabled reserved words\&.
+.TP
+\fBaliases\fP
+This maps the names of the regular aliases currently enabled to their
+expansions\&.
+.TP
+\fBdis_aliases\fP
+Like \fBaliases\fP but for disabled regular aliases\&.
+.TP
+\fBgaliases\fP
+Like \fBaliases\fP, but for global aliases\&.
+.TP
+\fBdis_galiases\fP
+Like \fBgaliases\fP but for disabled global aliases\&.
+.TP
+\fBsaliases\fP
+Like \fBraliases\fP, but for suffix aliases\&.
+.TP
+\fBdis_saliases\fP
+Like \fBsaliases\fP but for disabled suffix aliases\&.
+.TP
+\fBparameters\fP
+The keys in this associative array are the names of the parameters
+currently defined\&. The values are strings describing the type of the
+parameter, in the same format used by the \fBt\fP parameter flag, see
+\fIzshexpn\fP(1)
+\&.
+Setting or unsetting keys in this array is not possible\&.
+.TP
+\fBmodules\fP
+An associative array giving information about modules\&. The keys are the names
+of the modules loaded, registered to be autoloaded, or aliased\&. The
+value says which state the named module is in and is one of the
+strings `\fBloaded\fP', `\fBautoloaded\fP', or `\fBalias:\fP\fIname\fP',
+where \fIname\fP is the name the module is aliased to\&.
+.RS
+.PP
+Setting or unsetting keys in this array is not possible\&.
+.RE
+.TP
+\fBdirstack\fP
+A normal array holding the elements of the directory stack\&. Note that
+the output of the \fBdirs\fP builtin command includes one more
+directory, the current working directory\&.
+.TP
+\fBhistory\fP
+This associative array maps history event numbers to the full history lines\&.
+.TP
+\fBhistorywords\fP
+A special array containing the words stored in the history\&.
+.TP
+\fBjobdirs\fP
+This associative array maps job numbers to the directories from which the
+job was started (which may not be the current directory of the job)\&.
+.TP
+\fBjobtexts\fP
+This associative array maps job numbers to the texts of the command lines
+that were used to start the jobs\&.
+.TP
+\fBjobstates\fP
+This associative array gives information about the states of the jobs
+currently known\&. The keys are the job numbers and the values are
+strings of the form
+`\fIjob\-state\fP:\fImark\fP:\fIpid\fP\fB=\fP\fIstate\fP\fB\&.\&.\&.\fP'\&. The
+\fIjob\-state\fP gives the state the whole job is currently in, one of
+`\fBrunning\fP', `\fBsuspended\fP', or `\fBdone\fP'\&. The \fImark\fP is
+`\fB+\fP' for the current job, `\fB\-\fP' for the previous job and empty
+otherwise\&. This is followed by one `\fIpid\fP\fB=\fP\fIstate\fP' for every
+process in the job\&. The \fIpid\fPs are, of course, the process IDs and
+the \fIstate\fP describes the state of that process\&.
+.TP
+\fBnameddirs\fP
+This associative array maps the names of named directories to the pathnames
+they stand for\&.
+.TP
+\fBuserdirs\fP
+This associative array maps user names to the pathnames of their home
+directories\&.
+.TP
+\fBfuncstack\fP
+This array contains the names of the functions currently being
+executed\&. The first element is the name of the function using the
+parameter\&.
+.SH "THE ZSH/PCRE MODULE"
+.\" Yodl file: Zsh/mod_pcre.yo
+
+The \fBzsh/pcre\fP module makes some commands available as builtins:
+.PP
+.PD 0
+.TP
+.PD
+\fBpcre_compile\fP [ \fB\-aimx\fP ] \fIPCRE\fP
+Compiles a perl\-compatible regular expression\&.
+.RS
+.PP
+Option \fB\-a\fP will force the pattern to be anchored\&.
+Option \fB\-i\fP will compile a case\-insensitive pattern\&.
+Option \fB\-m\fP will compile a multi\-line pattern; that is,
+\fB^\fP and \fB$\fP will match newlines within the pattern\&.
+Option \fB\-x\fP will compile an extended pattern, wherein
+whitespace and \fB#\fP comments are ignored\&.
+.RE
+.TP
+\fBpcre_study\fP
+Studies the previously\-compiled PCRE which may result in faster
+matching\&.
+.TP
+\fBpcre_match\fP [ \fB\-a\fP \fIarr\fP ] \fIstring\fP
+Returns successfully if \fBstring\fP matches the previously\-compiled
+PCRE\&.
+.RS
+.PP
+If the expression captures substrings within parentheses,
+\fBpcre_match\fP will set the array \fI$match\fP to those
+substrings, unless the \fB\-a\fP option is given, in which
+case it will set the array \fIarr\fP\&.
+.RE
+.RE
+.PP
+The \fBzsh/pcre\fP module makes available the following test condition:
+.PD 0
+.TP
+.PD
+expr \fB\-pcre\-match\fP pcre
+Matches a string against a perl\-compatible regular expression\&.
+.RS
+.PP
+For example,
+.PP
+[[ "$text" \-pcre\-match ^d+$ ]] && print text variable contains only "d's"\&.
+.RE
+.RE
+.SH "THE ZSH/SCHED MODULE"
+.\" Yodl file: Zsh/mod_sched.yo
+
+The \fBzsh/sched\fP module makes available one builtin command:
+.PP
+.PD 0
+.TP
+.PD 0
+\fBsched\fP [\fB+\fP]\fIhh\fP\fB:\fP\fImm\fP \fIcommand\fP \&.\&.\&.
+.TP
+.PD
+\fBsched\fP [ \fB\-\fP\fIitem\fP ]
+Make an entry in the scheduled list of commands to execute\&.
+The time may be specified in either absolute or relative time\&.
+With no arguments, prints the list of scheduled commands\&.
+With the argument `\fB\-\fP\fIitem\fP', removes the given item
+from the list\&.
+.SH "THE ZSH/NET/SOCKET MODULE"
+.\" Yodl file: Zsh/mod_socket.yo
+
+The \fBzsh/net/socket\fP module makes available one builtin command:
+.PP
+.PD 0
+.TP
+.PD
+\fBzsocket\fP [ \fB\-altv\fP ] [ \fB\-d\fP \fIfd\fP ] [ \fIargs\fP ]
+\fBzsocket\fP is implemented as a builtin to allow full use of shell
+command line editing, file I/O, and job control mechanisms\&.
+.RS
+.PP
+.SS "Outbound Connections"
+.PP
+.PD 0
+.TP
+.PD
+\fBzsocket\fP [ \fB\-v\fP ] [ \fB\-d\fP \fIfd\fP ] \fIfilename\fP
+Open a new Unix domain connection to \fIfilename\fP\&.
+The shell parameter \fBREPLY\fP will be set to the file descriptor
+associated with that connection\&.  Currently, only stream connections
+are supported\&.
+.RS
+.PP
+If \fB\-d\fP is specified, its argument
+will be taken as the target file descriptor for the
+connection\&.
+.PP
+In order to elicit more verbose output, use \fB\-v\fP\&.
+.RE
+.RE
+.PP
+.SS "Inbound Connections"
+.PP
+.PD 0
+.TP
+.PD
+\fBzsocket\fP \fB\-l\fP [ \fB\-v\fP ] [ \fB\-d\fP \fIfd\fP ] \fIfilename\fP
+\fBzsocket \-l\fP will open a socket listening on \fIfilename\fP\&.
+The shell parameter \fBREPLY\fP will be set to the file descriptor
+associated with that listener\&.
+.RS
+.PP
+If \fB\-d\fP is specified, its argument
+will be taken as the target file descriptor for
+the connection\&.
+.PP
+In order to elicit more verbose output, use \fB\-v\fP\&.
+.RE
+.TP
+\fBzsocket\fP \fB\-a\fP [ \fB\-tv\fP ] [ \fB\-d\fP \fItargetfd\fP ] \fIlistenfd\fP
+\fBzsocket \-a\fP will accept an incoming connection
+to the socket associated with \fIlistenfd\fP\&.
+The shell parameter \fBREPLY\fP will
+be set to the file descriptor associated with
+the inbound connection\&.
+.RS
+.PP
+If \fB\-d\fP is specified, its argument
+will be taken as the target file descriptor for the
+connection\&.
+.PP
+If \fB\-t\fP is specified, \fBzsocket\fP will return
+if no incoming connection is pending\&.  Otherwise
+it will wait for one\&.
+.PP
+In order to elicit more verbose output, use \fB\-v\fP\&.
+.RE
+.RE
+.RE
+.RE
+.SH "THE ZSH/STAT MODULE"
+.\" Yodl file: Zsh/mod_stat.yo
+
+The \fBzsh/stat\fP module makes available one builtin command:
+.PP
+.PD 0
+.TP
+.PD
+\fBstat\fP [ \fB\-gnNolLtTrs\fP ] [ \fB\-f\fP \fIfd\fP ] [ \fB\-H\fP \fIhash\fP ] [ \fB\-A\fP \fIarray\fP ] [ \fB\-F\fP \fIfmt\fP ] [ \fB+\fP\fIelement\fP ] [ \fIfile\fP \&.\&.\&. ]
+The command acts as a front end to the \fBstat\fP system call (see
+\fIstat\fP(2))\&.
+If the \fBstat\fP call fails, the appropriate system error message
+printed and status 1 is returned\&.
+The fields of \fBstruct stat\fP give information about
+the files provided as arguments to the command\&.  In addition to those
+available from the \fBstat\fP call, an extra element `\fBlink\fP' is provided\&.
+These elements are:
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fBdevice\fP
+The number of the device on which the file resides\&.
+.TP
+\fBinode\fP
+The unique number of the file on this device (`\fIinode\fP' number)\&.
+.TP
+\fBmode\fP
+The mode of the file; that is, the file's type and access permissions\&.
+With the \fB\-s\fP option, this will
+be returned as a string corresponding to the first column in the
+display of the \fBls \-l\fP command\&.
+.TP
+\fBnlink\fP
+The number of hard links to the file\&.
+.TP
+\fBuid\fP
+The user ID of the owner of the file\&.  With the \fB\-s\fP
+option, this is displayed as a user name\&.
+.TP
+\fBgid\fP
+The group ID of the file\&.  With the \fB\-s\fP option, this
+is displayed as a group name\&.
+.TP
+\fBrdev\fP
+The raw device number\&.  This is only useful for special devices\&.
+.TP
+\fBsize\fP
+The size of the file in bytes\&.
+.TP
+.PD 0
+\fBatime\fP
+.TP
+.PD 0
+\fBmtime\fP
+.TP
+.PD
+\fBctime\fP
+The last access, modification and inode change times
+of the file, respectively, as the number of seconds since
+midnight GMT on 1st January, 1970\&.  With the \fB\-s\fP option,
+these are printed as strings for the local time zone; the format
+can be altered with the \fB\-F\fP option, and with the \fB\-g\fP
+option the times are in GMT\&.
+.TP
+\fBblksize\fP
+The number of bytes in one allocation block on the
+device on which the file resides\&.
+.TP
+\fBblock\fP
+The number of disk blocks used by the file\&.
+.TP
+\fBlink\fP
+If the file is a link and the \fB\-L\fP option is in
+effect, this contains the name of the file linked to, otherwise
+it is empty\&.  Note that if this element is selected (``\fBstat +link\fP'')
+then the \fB\-L\fP option is automatically used\&.
+.PP
+A particular element may be selected by including its name
+preceded by a `\fB+\fP' in the option list; only one element is allowed\&.
+The element may be shortened to any unique set of leading
+characters\&.  Otherwise, all elements will be shown for all files\&.
+.PP
+Options:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-A\fP \fIarray\fP
+Instead of displaying the results on standard
+output, assign them to an \fIarray\fP, one \fBstruct stat\fP element per array
+element for each file in order\&.  In this case neither the name
+of the element nor the name of the files appears in \fIarray\fP unless the
+\fB\-t\fP or \fB\-n\fP options were given, respectively\&.  If \fB\-t\fP is given,
+the element name appears as a prefix to the
+appropriate array element; if \fB\-n\fP is given, the file name
+appears as a separate array element preceding all the others\&.
+Other formatting options are respected\&.
+.TP
+\fB\-H\fP \fIhash\fP
+Similar to \fB\-A\fP, but instead assign the values to \fIhash\fP\&.  The keys
+are the elements listed above\&.  If the \fB\-n\fP option is provided then the
+name of the file is included in the hash with key \fBname\fP\&.
+.TP
+\fB\-f\fP \fIfd\fP
+Use the file on file descriptor \fIfd\fP instead of
+named files; no list of file names is allowed in this case\&.
+.TP
+\fB\-F\fP \fIfmt\fP
+Supplies a \fBstrftime\fP (see \fIstrftime\fP(3)) string for the
+formatting of the time elements\&.  The \fB\-s\fP option is implied\&.
+.TP
+\fB\-g\fP
+Show the time elements in the GMT time zone\&.  The
+\fB\-s\fP option is implied\&.
+.TP
+\fB\-l\fP
+List the names of the type elements (to standard
+output or an array as appropriate) and return immediately;
+options other than \fB\-A\fP and arguments are ignored\&.
+.TP
+\fB\-L\fP
+Perform an \fBlstat\fP (see \fIlstat\fP(2)) rather than a \fBstat\fP
+system call\&.  In this case, if the file is a link, information
+about the link itself rather than the target file is returned\&.
+This option is required to make the \fBlink\fP element useful\&.
+.TP
+\fB\-n\fP
+Always show the names of files\&.  Usually these are
+only shown when output is to standard output and there is more
+than one file in the list\&.
+.TP
+\fB\-N\fP
+Never show the names of files\&.
+.TP
+\fB\-o\fP
+If a raw file mode is printed, show it in octal, which is more useful for
+human consumption than the default of decimal\&.  A leading zero will be
+printed in this case\&.  Note that this does not affect whether a raw or
+formatted file mode is shown, which is controlled by the \fB\-r\fP and \fB\-s\fP
+options, nor whether a mode is shown at all\&.
+.TP
+\fB\-r\fP
+Print raw data (the default format) alongside string
+data (the \fB\-s\fP format); the string data appears in parentheses
+after the raw data\&.
+.TP
+\fB\-s\fP
+Print \fBmode\fP, \fBuid\fP, \fBgid\fP and the three time
+elements as strings instead of numbers\&.  In each case the format
+is like that of \fBls \-l\fP\&.
+.TP
+\fB\-t\fP
+Always show the type names for the elements of
+\fBstruct stat\fP\&.  Usually these are only shown when output is to
+standard output and no individual element has been selected\&.
+.TP
+\fB\-T\fP
+Never show the type names of the \fBstruct stat\fP elements\&.
+.RE
+.RE
+.SH "THE ZSH/SYSTEM MODULE"
+.\" Yodl file: Zsh/mod_system.yo
+
+The \fBzsh/system\fP module makes available three builtin commands and
+a parameter\&.
+.PP
+.SH "BUILTINS"
+.PP
+.PD 0
+.TP
+.PD
+\fBsyserror\fP \fB[ \-e\fP \fIerrvar\fP \fB] [ \-p\fP \fIprefix\fP \fB] [\fP \fIerrno\fP \fB|\fP \fIerrname\fP \fB]\fP
+This command prints out the error message associated with \fIerrno\fP, a
+system error number, followed by a newline to standard error\&.
+.RS
+.PP
+Instead of the error number, a name \fIerrname\fP, for example
+\fBENOENT\fP, may be used\&.  The set of names is the same as the contents
+of the array \fBerrnos\fP, see below\&.
+.PP
+If the string \fIprefix\fP is given, it is printed in front of the error
+message, with no intervening space\&.
+.PP
+If \fIerrvar\fP is supplied, the entire message, without a newline, is
+assigned to the parameter names \fIerrvar\fP and nothing is output\&.
+.PP
+A return value of 0 indicates the message was successfully printed
+(although it may not be useful if the error number was out of the
+system's range), a return value of 1 indicates an error in the
+parameters, and a return value of 2 indicates the error name was
+not recognised (no message is printed for this)\&.
+.RE
+.TP
+.PD 0
+\fBsysread [ \-c\fP \fIcountvar\fP \fB] [ \-i\fP \fIinfd\fP \fB] [ \-o\fP \fIoutfd\fP \fB]\fP
+.TP
+.PD
+  \fB[ \-s\fP \fIbufsize\fP \fB] [ \-t\fP \fItimeout\fP \fB] [\fP \fIparam\fP \fB]\fP
+Perform a single system read from file descriptor \fIinfd\fP, or zero if
+that is not given\&.  The result of the read is stored in \fIparam\fP or
+\fIREPLY\fP if that is not given\&.  If \fIcountvar\fP is given, the number
+of bytes read is assigned to the parameter named by \fIcountvar\fP\&.
+.RS
+.PP
+The maximum number of bytes read is \fIbufsize\fP or 8192 if that is not
+given, however the command returns as soon as any number of bytes was
+successfully read\&.
+.PP
+If \fItimeout\fP is given, it specifies a timeout in seconds, which may
+be zero to poll the file descriptor\&.  This is handled by the \fBpoll\fP
+system call if available, otherwise the \fBselect\fP system call if
+available\&.
+.PP
+If \fIoutfd\fP is given, an attempt is made to write all the bytes just
+read to the file descriptor \fIoutfd\fP\&.  If this fails, because of a
+system error other than \fBEINTR\fP or because of an internal zsh error
+during an interrupt, the bytes read but not written are stored in the
+parameter named by \fIparam\fP if supplied (no default is used in this
+case), and the number of bytes read but not written is stored in the
+parameter named by \fIcountvar\fP if that is supplied\&.  If it was
+successful, \fIcountvar\fP contains the full number of bytes transferred,
+as usual, and \fIparam\fP is not set\&.
+.PP
+The error \fBEINTR\fP (interrupted system call) is handled internally so
+that shell interrupts are transparent to the caller\&.  Any other error
+causes a return\&.
+.PP
+The possible return values are
+.PD 0
+.TP
+.PD
+0
+At least one byte of data was successfully read and, if appropriate,
+written\&.
+.TP
+1
+There was an error in the parameters to the command\&.  This is the only
+error for which a message is printed to standard error\&.
+.TP
+2
+There was an error on the read, or on polling the input file descriptor
+for a timeout\&.  The parameter \fBERRNO\fP gives the error\&.
+.TP
+3
+Data were successfully read, but there was an error writing them
+to \fIoutfd\fP\&.  The parameter \fBERRNO\fP gives the error\&.
+.TP
+4
+The attempt to read timed out\&.  Note this does not set \fBERRNO\fP as this
+is not a system error\&.
+.TP
+5
+No system error occurred, but zero bytes were read\&.  This usually
+indicates end of file\&.  The parameters are set according to the
+usual rules; no write to \fIoutfd\fP is attempted\&.
+.RE
+.TP
+\fBsyswrite [ \-c\fP \fIcountvar\fP \fB] [ \-o\fP \fIoutfd\fP \fB]\fP \fIdata\fP
+The data (a single string of bytes) are written to the file descriptor
+\fIoutfd\fP, or 1 if that is not given, using the \fBwrite\fP system call\&.
+Multiple write operations may be used if the first does not write all
+the data\&.
+.RS
+.PP
+If \fIcountvar\fP is given, the number of byte written is stored in the
+parameter named by \fIcountvar\fP; this may not be the full length of
+\fIdata\fP if an error occurred\&.
+.PP
+The error \fBEINTR\fP (interrupted system call) is handled internally by
+retrying; otherwise an error causes the command to return\&.  For example,
+if the file descriptor is set to non\-blocking output, an error
+\fBEAGAIN\fP (on some systems, \fBEWOULDBLOCK\fP) may result in the command
+returning early\&.
+.PP
+The return status may be 0 for success, 1 for an error in the parameters
+to the command, or 2 for an error on the write; no error message is
+printed in the last case, but the parameter \fBERRNO\fP will reflect
+the error that occurred\&.
+.RE
+.RE
+.PP
+.SH "PARAMETERS"
+.PP
+.PD 0
+.TP
+.PD
+\fBerrnos\fP
+A readonly array of the names of errors defined on the system\&.  These
+are typically macros defined in C by including the system header file
+\fBerrno\&.h\fP\&.  The index of each name (assuming the option \fBKSH_ARRAYS\fP
+is unset) corresponds to the error number\&.  Error numbers \fInum\fP
+before the last known error which have no name are given the name
+\fBE\fP\fInum\fP in the array\&.
+.RS
+.PP
+Note that aliases for errors are not handled; only the canonical name is
+used\&.
+.RE
+.RE
+.SH "THE ZSH/NET/TCP MODULE"
+.\" Yodl file: Zsh/mod_tcp.yo
+
+The \fBzsh/net/tcp\fP module makes available one builtin command:
+.PP
+.PD 0
+.TP
+.PD
+\fBztcp\fP [ \fB\-acflLtv\fP ] [ \fB\-d\fP \fIfd\fP ] [ \fIargs\fP ]
+\fBztcp\fP is implemented as a builtin to allow full use of shell
+command line editing, file I/O, and job control mechanisms\&.
+.RS
+.PP
+If \fBztcp\fP is run with no options, it will output
+the contents of its session table\&.
+.PP
+If it is run with only the option \fB\-L\fP, it will output the contents of
+the session table in a format suitable for automatic parsing\&.  The option
+is ignored if given with a command to open or close a session\&.  The output
+consists of a set of lines, one per session, each containing the following
+elements separated by spaces:
+.PP
+.PD 0
+.TP
+.PD
+File descriptor
+The file descriptor in use for the connection\&.  For normal inbound (\fBI\fP)
+and outbound (\fBO\fP) connections this may be read and written by the usual
+shell mechanisms\&.  However, it should only be close with `\fBztcp \-c\fP'\&.
+.TP
+Connection type
+A letter indicating how the session was created:
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fBZ\fP
+A session created with the \fBzftp\fP command\&.
+.TP
+\fBL\fP
+A connection opened for listening with `\fBztcp \-l\fP'\&.
+.TP
+\fBI\fP
+An inbound connection accepted with `\fBztcp \-a\fP'\&.
+.TP
+\fBO\fP
+An outbound connection created with `\fBztcp\fP \fIhost\fP \fI\&.\&.\&.\fP'\&.
+.PP
+.RE
+.TP
+The local host
+This is usually set to an all\-zero IP address as the address of the
+localhost is irrelevant\&.
+.TP
+The local port
+This is likely to be zero unless the connection is for listening\&.
+.TP
+The remote host
+This is the fully qualified domain name of the peer, if available, else an
+IP address\&.  It is an all\-zero IP address for a session opened for
+listening\&.
+.TP
+The remote port
+This is zero for a connection opened for listening\&.
+.RE
+.RE
+.PP
+.SS "Outbound Connections"
+.PP
+.PD 0
+.TP
+.PD
+\fBztcp\fP [ \fB\-v\fP ] [ \fB\-d\fP \fIfd\fP ] \fIhost\fP [ \fIport\fP ]
+Open a new TCP connection to \fIhost\fP\&.  If the \fIport\fP is
+omitted, it will default to port 23\&.  The connection will
+be added to the session table and the shell parameter
+\fBREPLY\fP will be set to the file descriptor associated
+with that connection\&.
+.RS
+.PP
+If \fB\-d\fP is specified, its argument will be taken as the target file
+descriptor for the connection\&.
+.PP
+In order to elicit more verbose output, use \fB\-v\fP\&.
+.RE
+.RE
+.PP
+.SS "Inbound Connections"
+.PP
+.PD 0
+.TP
+.PD
+\fBztcp\fP \fB\-l\fP [ \fB\-v\fP ] [ \fB\-d\fP \fIfd\fP ] \fIport\fP
+\fBztcp \-l\fP will open a socket listening on TCP
+\fIport\fP\&.  The socket will be added to the
+session table and the shell parameter \fBREPLY\fP
+will be set to the file descriptor associated
+with that listener\&.
+.RS
+.PP
+If \fB\-d\fP is specified, its argument will be taken as the target file
+descriptor for the connection\&.
+.PP
+In order to elicit more verbose output, use \fB\-v\fP\&.
+.RE
+.TP
+\fBztcp\fP \fB\-a\fP [ \fB\-tv\fP ] [ \fB\-d\fP \fItargetfd\fP ] \fIlistenfd\fP
+\fBztcp \-a\fP will accept an incoming connection
+to the port associated with \fIlistenfd\fP\&.
+The connection will be added to the session
+table and the shell parameter \fBREPLY\fP will
+be set to the file descriptor associated with
+the inbound connection\&.
+.RS
+.PP
+If \fB\-d\fP is specified, its argument
+will be taken as the target file descriptor for the
+connection\&.
+.PP
+If \fB\-t\fP is specified, \fBztcp\fP will return
+if no incoming connection is pending\&.  Otherwise
+it will wait for one\&.
+.PP
+In order to elicit more verbose output, use \fB\-v\fP\&.
+.RE
+.RE
+.PP
+.SS "Closing Connections"
+.PP
+.PD 0
+.TP
+.PD 0
+\fBztcp\fP \fB\-cf\fP [ \fB\-v\fP ] [ \fIfd\fP ]
+.TP
+.PD
+\fBztcp\fP \fB\-c\fP [ \fB\-v\fP ] [ \fIfd\fP ]
+\fBztcp \-c\fP will close the socket associated
+with \fIfd\fP\&.  The socket will be removed from the
+session table\&.  If \fIfd\fP is not specified,
+\fBztcp\fP will close everything in the session table\&.
+.RS
+.PP
+Normally, sockets registered by zftp (see
+\fIzshmodules\fP(1)
+) cannot be closed this way\&.  In order
+to force such a socket closed, use \fB\-f\fP\&.
+.PP
+In order to elicit more verbose output, use \fB\-v\fP\&.
+.RE
+.RE
+.PP
+.SS "Example"
+Here is how to create a TCP connection between two instances of zsh\&.  We
+need to pick an unassigned port; here we use the randomly chosen 5123\&.
+.PP
+On \fBhost1\fP,
+.RS
+.nf
+\fBzmodload zsh/net/tcp
+ztcp \-l 5123
+listenfd=$REPLY
+ztcp \-a $listenfd
+fd=$REPLY\fP
+.fi
+.RE
+The second from last command blocks until there is an incoming connection\&.
+.PP
+Now create a connection from \fBhost2\fP (which may, of course, be the same
+machine):
+.RS
+.nf
+\fBzmodload zsh/net/tcp
+ztcp host1 5123
+fd=$REPLY\fP
+.fi
+.RE
+.PP
+Now on each host, \fB$fd\fP contains a file descriptor for talking to the
+other\&.  For example, on \fBhost1\fP:
+.RS
+.nf
+\fBprint This is a message >&$fd\fP
+.fi
+.RE
+and on \fBhost2\fP:
+.RS
+.nf
+\fBread \-r line <&$fd; print \-r \- $line\fP
+.fi
+.RE
+prints `\fBThis is a message\fP'\&.
+.PP
+To tidy up, on \fBhost1\fP:
+.RS
+.nf
+\fBztcp \-c $listenfd
+ztcp \-c $fd\fP
+.fi
+.RE
+and on \fBhost2\fP
+.RS
+.nf
+\fBztcp \-c $fd\fP
+.fi
+.RE
+.SH "THE ZSH/TERMCAP MODULE"
+.\" Yodl file: Zsh/mod_termcap.yo
+
+The \fBzsh/termcap\fP module makes available one builtin command:
+.PP
+.PD 0
+.TP
+.PD
+\fBechotc\fP \fIcap\fP [ \fIarg\fP \&.\&.\&. ]
+Output the termcap value corresponding to the capability
+\fIcap\fP, with optional arguments\&.
+.PP
+The \fBzsh/termcap\fP module makes available one parameter:
+.PP
+.PD 0
+.TP
+.PD
+\fBtermcap\fP
+An associative array that maps termcap capability codes to
+their values\&.
+.SH "THE ZSH/TERMINFO MODULE"
+.\" Yodl file: Zsh/mod_terminfo.yo
+
+The \fBzsh/terminfo\fP module makes available one builtin command:
+.PP
+.PD 0
+.TP
+.PD
+\fBechoti\fP \fIcap\fP [ \fIarg\fP ]
+Output the terminfo value corresponding to the capability
+\fIcap\fP, instantiated with \fIarg\fP if applicable\&.
+.PP
+The \fBzsh/terminfo\fP module makes available one parameter:
+.PP
+.PD 0
+.TP
+.PD
+\fBterminfo\fP
+An associative array that maps terminfo capability names to
+their values\&.
+.SH "THE ZSH/ZFTP MODULE"
+.\" Yodl file: Zsh/mod_zftp.yo
+
+The \fBzsh/zftp\fP module makes available one builtin command:
+.PP
+.PD 0
+.TP
+.PD
+\fBzftp\fP \fIsubcommand\fP [ \fIargs\fP ]
+The \fBzsh/zftp\fP module is a client for FTP (file transfer protocol)\&.  It
+is implemented as a builtin to allow full use of shell command line
+editing, file I/O, and job control mechanisms\&.  Often, users will
+access it via shell functions providing a more powerful interface; a set is
+provided with the \fBzsh\fP distribution and is described in
+\fIzshzftpsys\fP(1)\&.  However, the \fBzftp\fP command is entirely usable in its
+own right\&.
+.RS
+.PP
+All commands consist of the command name \fBzftp\fP followed by the name
+of a subcommand\&.  These are listed below\&.  The return status of each
+subcommand is supposed to reflect the success or failure of the remote
+operation\&.  See a description of the variable \fBZFTP_VERBOSE\fP for
+more information on how responses from the server may be printed\&.
+.RE
+.RE
+.PP
+.SS "Subcommands"
+.PP
+.PD 0
+.TP
+.PD
+\fBopen\fP \fIhost\fP[\fB:\fP\fIport\fP] [ \fIuser\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ]
+Open a new FTP session to \fIhost\fP, which may be the name of a TCP/IP
+connected host or an IP number in the standard dot notation\&.  If the
+argument is in the form \fIhost\fP\fB:\fP\fIport\fP, open a connection to
+TCP port \fIport\fP instead of the standard FTP port 21\&.  This may be
+the name of a TCP service or a number:  see the description of
+\fBZFTP_PORT\fP below for more information\&.
+.RS
+.PP
+If IPv6 addresses in colon format are used, the \fIhost\fP should be
+surrounded by quoted square brackets to distinguish it from the \fIport\fP,
+for example \fB'[fe80::203:baff:fe02:8b56]'\fP\&.  For consistency this is
+allowed with all forms of \fIhost\fP\&.
+.PP
+Remaining arguments are passed to the \fBlogin\fP subcommand\&.  Note that
+if no arguments beyond \fIhost\fP are supplied, \fBopen\fP will \fInot\fP
+automatically call \fBlogin\fP\&.  If no arguments at all are supplied,
+\fBopen\fP will use the parameters set by the \fBparams\fP subcommand\&.
+.PP
+After a successful open, the shell variables \fBZFTP_HOST\fP, \fBZFTP_PORT\fP,
+\fBZFTP_IP\fP and \fBZFTP_SYSTEM\fP are available; see `Variables'
+below\&.
+.RE
+.TP
+.PD 0
+\fBlogin\fP [ \fIname\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ]
+.TP
+.PD
+\fBuser\fP [ \fIname\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ]
+Login the user \fIname\fP with parameters \fIpassword\fP and \fIaccount\fP\&.
+Any of the parameters can be omitted, and will be read from standard
+input if needed (\fIname\fP is always needed)\&.  If 
+standard input is a terminal, a prompt for each one will be printed on
+standard error and \fIpassword\fP will not be echoed\&.  If any of the
+parameters are not used, a warning message is printed\&.
+.RS
+.PP
+After a successful login, the shell variables \fBZFTP_USER\fP,
+\fBZFTP_ACCOUNT\fP and \fBZFTP_PWD\fP are available; see `Variables'
+below\&.
+.PP
+This command may be re\-issued when a user is already logged in, and
+the server will first be reinitialized for a new user\&.
+.RE
+.TP
+.PD 0
+\fBparams\fP [ \fIhost\fP [ \fIuser\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ] ]
+.TP
+.PD
+\fBparams\fP \fB\-\fP
+Store the given parameters for a later \fBopen\fP command with no
+arguments\&.  Only those given on the command line will be remembered\&.
+If no arguments are given, the parameters currently set are printed,
+although the password will appear as a line of stars; the return value is
+one if no parameters were set, zero otherwise\&.
+.RS
+.PP
+Any of the parameters may be specified as a `\fB?\fP', which
+may need to be quoted to protect it from shell expansion\&.  In this case,
+the appropriate parameter will be read from stdin as with the
+\fBlogin\fP subcommand, including special handling of \fIpassword\fP\&.  If the
+`\fB?\fP' is followed by a string, that is used as the prompt for reading the
+parameter instead of the default message (any necessary punctuation and
+whitespace should be included at the end of the prompt)\&.  The first letter
+of the parameter (only) may be quoted with a `\fB\e\fP'; hence an argument
+\fB"\e\e$word"\fP guarantees that the string from the shell parameter \fB$word\fP
+will be treated literally, whether or not it begins with a `\fB?\fP'\&.
+.PP
+If instead a single `\fB\-\fP' is given, the existing parameters, if any,
+are deleted\&.  In that case, calling \fBopen\fP with no arguments will
+cause an error\&.
+.PP
+The list of parameters is not deleted after a \fBclose\fP, however it
+will be deleted if the \fBzsh/zftp\fP module is unloaded\&.
+.PP
+For example,
+.PP
+.RS
+.nf
+\fBzftp params ftp\&.elsewhere\&.xx juser '?Password for juser: '\fP
+.fi
+.RE
+.PP
+will store the host \fBftp\&.elsewhere\&.xx\fP and the user \fBjuser\fP and
+then prompt the user for the corresponding password with the given prompt\&.
+.RE
+.TP
+\fBtest\fP
+Test the connection; if the server has reported
+that it has closed the connection (maybe due to a timeout), return
+status 2; if no connection was open anyway, return status 1; else
+return status 0\&.  The \fBtest\fP subcommand is
+silent, apart from messages printed by the \fB$ZFTP_VERBOSE\fP
+mechanism, or error messages if the connection closes\&.  There is no
+network overhead for this test\&.
+.RS
+.PP
+The test is only supported on systems with either the \fBselect(2)\fP or
+\fBpoll(2)\fP system calls; otherwise the message `\fBnot
+supported on this system\fP' is printed instead\&.
+.PP
+The \fBtest\fP subcommand will automatically be called at the start of any
+other subcommand for the current session when a connection is open\&.
+.RE
+.TP
+\fBcd\fP \fIdirectory\fP
+Change the remote directory to \fIdirectory\fP\&.  Also alters the shell
+variable \fBZFTP_PWD\fP\&.
+.TP
+\fBcdup\fP
+Change the remote directory to the one higher in the directory tree\&.
+Note that \fBcd \&.\&.\fP will also work correctly on non\-UNIX systems\&.
+.TP
+\fBdir\fP [ \fIargs\&.\&.\&.\fP ]
+Give a (verbose) listing of the remote directory\&.  The \fIargs\fP are
+passed directly to the server\&. The command's behaviour is implementation
+dependent, but a UNIX server will typically interpret \fIargs\fP as
+arguments to the \fBls\fP command and with no arguments return the
+result of `\fBls \-l\fP'\&. The directory is listed to standard output\&.
+.TP
+\fBls\fP [ \fIargs\fP ]
+Give a (short) listing of the remote directory\&.  With no \fIargs\fP,
+produces a raw list of the files in the directory, one per line\&.
+Otherwise, up to vagaries of the server implementation, behaves
+similar to \fBdir\fP\&.
+.TP
+\fBtype\fP [ \fItype\fP ]
+Change the type for the transfer to \fItype\fP, or print the current type
+if \fItype\fP is absent\&.  The allowed values are `\fBA\fP' (ASCII),
+`\fBI\fP' (Image, i\&.e\&. binary), or `\fBB\fP' (a synonym for `\fBI\fP')\&.
+.RS
+.PP
+The FTP default for a transfer is ASCII\&.  However, if \fBzftp\fP finds
+that the remote host is a UNIX machine with 8\-bit byes, it will
+automatically switch to using binary for file transfers upon
+\fBopen\fP\&.  This can subsequently be overridden\&.
+.PP
+The transfer type is only passed to the remote host when a data
+connection is established; this command involves no network overhead\&.
+.RE
+.TP
+\fBascii\fP
+The same as \fBtype A\fP\&.
+.TP
+\fBbinary\fP
+The same as \fBtype I\fP\&.
+.TP
+\fBmode\fP [ \fBS\fP | \fBB\fP ]
+Set the mode type to stream (\fBS\fP) or block (\fBB\fP)\&.  Stream mode is
+the default; block mode is not widely supported\&.
+.TP
+.PD 0
+\fBremote\fP \fIfiles\&.\&.\&.\fP
+.TP
+.PD
+\fBlocal\fP [ \fIfiles\&.\&.\&.\fP ]
+Print the size and last modification time of the remote or local
+files\&.  If there is more than one item on the list, the name of the
+file is printed first\&.  The first number is the file size, the second
+is the last modification time of the file in the format
+\fBCCYYMMDDhhmmSS\fP consisting of year, month, date, hour, minutes and
+seconds in GMT\&.  Note that this format, including the length, is
+guaranteed, so that time strings can be directly compared via the
+\fB[[\fP builtin's \fB<\fP and \fB>\fP operators, even if they are too long
+to be represented as integers\&.
+.RS
+.PP
+Not all servers support the commands for retrieving this information\&.
+In that case, the \fBremote\fP command will print nothing and return
+status 2, compared with status 1 for a file not found\&.
+.PP
+The \fBlocal\fP command (but not \fBremote\fP) may be used with no
+arguments, in which case the information comes from examining file
+descriptor zero\&.  This is the same file as seen by a \fBput\fP command
+with no further redirection\&.
+.RE
+.TP
+\fBget\fP \fIfile\fP [\&.\&.\&.]
+Retrieve all \fIfile\fPs from the server, concatenating them
+and sending them to standard output\&.
+.TP
+\fBput\fP \fIfile\fP [\&.\&.\&.]
+For each \fIfile\fP, read a file from standard input and send that to
+the remote host with the given name\&.
+.TP
+\fBappend\fP \fIfile\fP [\&.\&.\&.]
+As \fBput\fP, but if the remote \fIfile\fP already exists, data is
+appended to it instead of overwriting it\&.
+.TP
+.PD 0
+\fBgetat\fP \fIfile\fP \fIpoint\fP
+.TP
+.PD 0
+\fBputat\fP \fIfile\fP \fIpoint\fP
+.TP
+.PD
+\fBappendat\fP \fIfile\fP \fIpoint\fP
+Versions of \fBget\fP, \fBput\fP and \fBappend\fP which will start the
+transfer at the given \fIpoint\fP in the remote \fIfile\fP\&.  This is
+useful for appending to an incomplete local file\&.  However, note that
+this ability is not universally supported by servers (and is not quite
+the behaviour specified by the standard)\&.
+.TP
+\fBdelete\fP \fIfile\fP [\&.\&.\&.]
+Delete the list of files on the server\&.
+.TP
+\fBmkdir\fP \fIdirectory\fP
+Create a new directory \fIdirectory\fP on the server\&.
+.TP
+\fBrmdir\fP \fIdirectory\fP
+Delete the directory \fIdirectory\fP  on the server\&.
+.TP
+\fBrename\fP \fIold\-name\fP \fInew\-name\fP
+Rename file \fIold\-name\fP to \fInew\-name\fP on the server\&.
+.TP
+\fBsite\fP \fIargs\&.\&.\&.\fP
+Send a host\-specific command to the server\&.  You will probably
+only need this if instructed by the server to use it\&.
+.TP
+\fBquote\fP \fIargs\&.\&.\&.\fP
+Send the raw FTP command sequence to the server\&.  You should be
+familiar with the FTP command set as defined in RFC959 before doing
+this\&.  Useful commands may include \fBSTAT\fP and \fBHELP\fP\&.  Note also
+the mechanism for returning messages as described for the variable
+\fBZFTP_VERBOSE\fP below, in particular that all messages from the
+control connection are sent to standard error\&.
+.TP
+.PD 0
+\fBclose\fP
+.TP
+.PD
+\fBquit\fP
+Close the current data connection\&.  This unsets the shell parameters
+\fBZFTP_HOST\fP, \fBZFTP_PORT\fP, \fBZFTP_IP\fP, \fBZFTP_SYSTEM\fP, \fBZFTP_USER\fP,
+\fBZFTP_ACCOUNT\fP, \fBZFTP_PWD\fP, \fBZFTP_TYPE\fP and \fBZFTP_MODE\fP\&.
+.TP
+\fBsession\fP [ \fIsessname\fP ]
+Allows multiple FTP sessions to be used at once\&.  The name of the session
+is an arbitrary string of characters; the default session is called
+`\fBdefault\fP'\&.  If this command is called without an argument, it will list
+all the current sessions; with an argument, it will either switch to the
+existing session called \fIsessname\fP, or create a new session of that name\&.
+.RS
+.PP
+Each session remembers the status of the connection, the set of
+connection\-specific shell parameters (the same set as are unset when a
+connection closes, as given in the description of \fBclose\fP), and any user
+parameters specified with the \fBparams\fP subcommand\&.  Changing to a
+previous session restores those values; changing to a new session
+initialises them in the same way as if \fBzftp\fP had just been loaded\&.  The
+name of the current session is given by the parameter \fBZFTP_SESSION\fP\&.
+.RE
+.TP
+\fBrmsession\fP [ \fIsessname\fP ]
+Delete a session; if a name is not given, the current session is deleted\&.
+If the current session is deleted, the earliest existing session becomes
+the new current session, otherwise the current session is not changed\&.
+If the session being deleted is the only one, a new session called
+`\fBdefault\fP' is created and becomes the current session; note that this is
+a new session even if the session being deleted is also called
+`\fBdefault\fP'\&. It is recommended that sessions not be deleted while
+background commands which use \fBzftp\fP are still active\&.
+.PP
+.SS "Parameters"
+The following shell parameters are used by \fBzftp\fP\&.  Currently none
+of them are special\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBZFTP_TMOUT\fP
+Integer\&.  The time in seconds to wait for a network operation to
+complete before returning an error\&.  If this is not set when the
+module is loaded, it will be given the default value 60\&.  A value of
+zero turns off timeouts\&.  If a timeout occurs on the control
+connection it will be closed\&.  Use a larger value if this occurs too
+frequently\&.
+.TP
+\fBZFTP_IP\fP
+Readonly\&.  The IP address of the current connection in dot notation\&.
+.TP
+\fBZFTP_HOST\fP
+Readonly\&.  The hostname of the current remote server\&.  If the host was
+opened as an IP number, \fBZFTP_HOST\fP contains that instead; this
+saves the overhead for a name lookup, as IP numbers are most commonly
+used when a nameserver is unavailable\&.
+.TP
+\fBZFTP_PORT\fP
+Readonly\&.  The number of the remote TCP port to which the connection is
+open (even if the port was originally specified as a named service)\&.
+Usually this is the standard FTP port, 21\&.
+.RS
+.PP
+In the unlikely event that your system does not have the appropriate
+conversion functions, this appears in network byte order\&.  If your
+system is little\-endian, the port then consists of two swapped bytes and the
+standard port will be reported as 5376\&.  In that case, numeric ports passed
+to \fBzftp open\fP will also need to be in this format\&.
+.RE
+.TP
+\fBZFTP_SYSTEM\fP
+Readonly\&.  The system type string returned by the server in response
+to an FTP \fBSYST\fP request\&.  The most interesting case is a string
+beginning \fB"UNIX Type: L8"\fP, which ensures maximum compatibility
+with a local UNIX host\&.
+.TP
+\fBZFTP_TYPE\fP
+Readonly\&.  The type to be used for data transfers , either `\fBA\fP' or
+`\fBI\fP'\&.   Use the \fBtype\fP subcommand to change this\&.
+.TP
+\fBZFTP_USER\fP
+Readonly\&.  The username currently logged in, if any\&.
+.TP
+\fBZFTP_ACCOUNT\fP
+Readonly\&.  The account name of the current user, if any\&.  Most servers
+do not require an account name\&.
+.TP
+\fBZFTP_PWD\fP
+Readonly\&.  The current directory on the server\&.
+.TP
+\fBZFTP_CODE\fP
+Readonly\&.  The three digit code of the last FTP reply from the server
+as a string\&.  This can still be read after the connection is closed, and
+is not changed when the current session changes\&.
+.TP
+\fBZFTP_REPLY\fP
+Readonly\&.  The last line of the last reply sent by the server\&.  This
+can still be read after the connection is closed, and is not changed when
+the current session changes\&.
+.TP
+\fBZFTP_SESSION\fP
+Readonly\&.  The name of the current FTP session; see the description of the
+\fBsession\fP subcommand\&.
+.TP
+\fBZFTP_PREFS\fP
+A string of preferences for altering aspects of \fBzftp\fP's behaviour\&.
+Each preference is a single character\&.  The following are defined:
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fBP\fP
+Passive:  attempt to make the remote server initiate data transfers\&.
+This is slightly more efficient than sendport mode\&.  If the letter
+\fBS\fP occurs later in the string, \fBzftp\fP will use sendport mode if
+passive mode is not available\&.
+.TP
+\fBS\fP
+Sendport:  initiate transfers by the FTP \fBPORT\fP command\&.  If this
+occurs before any \fBP\fP in the string, passive mode will never be
+attempted\&.
+.TP
+\fBD\fP
+Dumb:  use only the bare minimum of FTP commands\&.  This prevents
+the variables \fBZFTP_SYSTEM\fP and \fBZFTP_PWD\fP from being set, and
+will mean all connections default to ASCII type\&.  It may prevent
+\fBZFTP_SIZE\fP from being set during a transfer if the server
+does not send it anyway (many servers do)\&.
+.PP
+If \fBZFTP_PREFS\fP is not set when \fBzftp\fP is loaded, it will be set to a
+default of `\fBPS\fP', i\&.e\&. use passive mode if available, otherwise
+fall back to sendport mode\&.
+.RE
+.TP
+\fBZFTP_VERBOSE\fP
+A string of digits between 0 and 5 inclusive, specifying which
+responses from the server should be printed\&.  All responses go to
+standard error\&.  If any of the numbers 1 to 5 appear in the string,
+raw responses from the server with reply codes beginning with that
+digit will be printed to standard error\&.  The first digit of the three
+digit reply code is defined by RFC959 to correspond to:
+.RS
+.PP
+.PD 0
+.TP
+.PD
+1\&.
+A positive preliminary reply\&.
+.TP
+2\&.
+A positive completion reply\&.
+.TP
+3\&.
+A positive intermediate reply\&.
+.TP
+4\&.
+A transient negative completion reply\&.
+.TP
+5\&.
+A permanent negative completion reply\&.
+.PP
+It should be noted that, for unknown reasons, the reply `Service not
+available', which forces termination of a connection, is classified as
+421, i\&.e\&. `transient negative', an interesting interpretation of the word
+`transient'\&.
+.PP
+The code 0 is special:  it indicates that all but the last line of
+multiline replies read from the server will be printed to standard
+error in a processed format\&.  By convention, servers use this
+mechanism for sending information for the user to read\&.  The
+appropriate reply code, if it matches the same response, takes
+priority\&.
+.PP
+If \fBZFTP_VERBOSE\fP is not set when \fBzftp\fP is loaded, it will be
+set to the default value \fB450\fP, i\&.e\&., messages destined for the user
+and all errors will be printed\&.  A null string is valid and
+specifies that no messages should be printed\&.
+.RE
+.RE
+.PP
+.SS "Functions"
+.PP
+.PD 0
+.TP
+.PD
+\fBzftp_chpwd\fP
+If this function is set by the user, it is called every time the
+directory changes on the server, including when a user is logged
+in, or when a connection is closed\&.  In the last case, \fB$ZFTP_PWD\fP
+will be unset; otherwise it will reflect the new directory\&.
+.TP
+\fBzftp_progress\fP
+If this function is set by the user, it will be called during
+a \fBget\fP, \fBput\fP or \fBappend\fP operation each time sufficient data
+has been received from the host\&.  During a \fBget\fP, the data is sent
+to standard output, so it is vital that this function should write
+to standard error or directly to the terminal, \fInot\fP to standard
+output\&.
+.RS
+.PP
+When it is called with a transfer in progress, the following
+additional shell parameters are set:
+.PP
+.PD 0
+.TP
+.PD
+\fBZFTP_FILE\fP
+The name of the remote file being transferred from or to\&.
+.TP
+\fBZFTP_TRANSFER\fP
+A \fBG\fP for a \fBget\fP operation and a \fBP\fP for a \fBput\fP operation\&.
+.TP
+\fBZFTP_SIZE\fP
+The total size of the complete file being transferred:
+the same as the first value provided by the
+\fBremote\fP and \fBlocal\fP subcommands for a particular file\&.
+If the server cannot supply this value for a remote file being
+retrieved, it will not be set\&.  If input is from a pipe the value may
+be incorrect and correspond simply to a full pipe buffer\&.
+.TP
+\fBZFTP_COUNT\fP
+The amount of data so far transferred; a number between zero and
+\fB$ZFTP_SIZE\fP, if that is set\&.  This number is always available\&.
+.PP
+The function is initially called with \fBZFTP_TRANSFER\fP set
+appropriately and \fBZFTP_COUNT\fP set to zero\&.  After the transfer is
+finished, the function will be called one more time with
+\fBZFTP_TRANSFER\fP set to \fBGF\fP or \fBPF\fP, in case it wishes to tidy
+up\&.  It is otherwise never called twice with the same value of
+\fBZFTP_COUNT\fP\&.
+.PP
+Sometimes the progress meter may cause disruption\&.  It is up to the
+user to decide whether the function should be defined and to use
+\fBunfunction\fP when necessary\&.
+.RE
+.RE
+.PP
+.SS "Problems"
+.PP
+A connection may not be opened in the left hand side of a pipe as this
+occurs in a subshell and the file information is not updated in the main
+shell\&.  In the case of type or mode changes or closing the connection in a
+subshell, the information is returned but variables are not updated until
+the next call to \fBzftp\fP\&.  Other status changes in subshells will not be
+reflected by changes to the variables (but should be otherwise harmless)\&.
+.PP
+Deleting sessions while a \fBzftp\fP command is active in the background can
+have unexpected effects, even if it does not use the session being deleted\&.
+This is because all shell subprocesses share information on the state of
+all connections, and deleting a session changes the ordering of that
+information\&.
+.PP
+On some operating systems, the control connection is not valid after a
+fork(), so that operations in subshells, on the left hand side of a
+pipeline, or in the background are not possible, as they should be\&.  This
+is presumably a bug in the operating system\&.
+.SH "THE ZSH/ZLE MODULE"
+.\" Yodl file: Zsh/mod_zle.yo
+
+The \fBzsh/zle\fP module contains the Zsh Line Editor\&.  See
+\fIzshzle\fP(1)\&.
+.SH "THE ZSH/ZLEPARAMETER MODULE"
+.\" Yodl file: Zsh/mod_zleparameter.yo
+
+The \fBzsh/zleparameter\fP module defines two special parameters that can be 
+used to access internal information of the Zsh Line Editor (see
+\fIzshzle\fP(1))\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBkeymaps\fP
+This array contains the names of the keymaps currently defined\&.
+.TP
+\fBwidgets\fP
+This associative array contains one entry per widget defined\&. The name 
+of the widget is the key and the value gives information about the
+widget\&. It is either the string `\fBbuiltin\fP' for builtin widgets, a
+string of the form `\fBuser:\fP\fIname\fP' for user\-defined widgets,
+where \fIname\fP is the name of the shell function implementing the
+widget, or it is a string of the form
+`\fBcompletion:\fP\fItype\fP\fB:\fP\fIname\fP', for completion widgets\&. In
+the last case \fItype\fP is the name of the builtin widgets the
+completion widget imitates in its behavior and \fIname\fP is the name
+of the shell function implementing the completion widget\&.
+.SH "THE ZSH/ZPROF MODULE"
+.\" Yodl file: Zsh/mod_zprof.yo
+
+When loaded, the \fBzsh/zprof\fP causes shell functions to be profiled\&.
+The profiling results can be obtained with the \fBzprof\fP
+builtin command made available by this module\&.  There is no way to turn 
+profiling off other than unloading the module\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBzprof\fP [ \fB\-c\fP ]
+Without the \fB\-c\fP option, \fBzprof\fP lists profiling results to
+standard output\&.  The format is comparable to that of commands like
+\fBgprof\fP\&.
+.RS
+.PP
+At the top there is a summary listing all functions that were called
+at least once\&.  This summary is sorted in decreasing order of the
+amount of time spent in each\&.  The lines contain
+the number of the function in order, which is used in 
+other parts of the list in suffixes of the form
+`\fB[\fP\fInum\fP\fB]\fP'.RE, then the number of calls made to the function\&.
+The next three columns list the time in
+milliseconds spent in the function and its descendents, the average
+time in milliseconds spent in the function and its descendents per
+call and the percentage of time spent in all shell functions used in
+this function and its descendents\&.  The following three columns give
+the same information, but counting only the time spent in the function 
+itself\&.  The final column shows the name of the function\&.
+.PP
+After the summary, detailed information about every function that was
+invoked is listed, sorted in decreasing order of the amount of time spent
+in each function and its descendents\&.  Each of these entries consists of
+descriptions for the functions that called the function described, the
+function itself, and the functions that were called from it\&.  The
+description for the function itself has the same format as in the summary
+(and shows the same information)\&.  The other lines don't show the number of
+the function at the beginning and have their function named indented to
+make it easier to distinguish the line showing the function described in
+the section from the surrounding lines\&.
+.PP
+The information shown in this case is almost the same as in the summary,
+but only refers to the call hierarchy being displayed\&.  For example, for a
+calling function the column showing the total running time lists the time
+spent in the described function and its descendents only for the times when
+it was called from that particular calling function\&.  Likewise, for a
+called function, this columns lists the total time spent in the called
+function and its descendents only for the times when it was called from the
+function described\&.
+.PP
+Also in this case, the column showing the number of calls to a function
+also shows a slash and then the total number of invocations made to the
+called function\&.
+.PP
+As long as the \fBzsh/zprof\fP module is loaded, profiling will be done and
+multiple invocations of the \fBzprof\fP builtin command will show the
+times and numbers of calls since the module was loaded\&.  With the
+\fB\-c\fP option, the \fBzprof\fP builtin command will reset its internal
+counters and will not show the listing\&.
+)
+.RE
+.SH "THE ZSH/ZPTY MODULE"
+.\" Yodl file: Zsh/mod_zpty.yo
+
+The \fBzsh/zpty\fP module offers one builtin:
+.PP
+.PD 0
+.TP
+.PD
+\fBzpty\fP [ \fB\-e\fP ] [ \fB\-b\fP ] \fIname\fP [ \fIarg \&.\&.\&.\fP ]
+The arguments following \fIname\fP are concatenated with spaces between,
+then executed as a command, as if passed to the \fBeval\fP builtin\&.  The
+command runs under a newly assigned pseudo\-terminal; this is useful for
+running commands non\-interactively which expect an interactive
+environment\&.  The \fIname\fP is not part of the command, but is used to
+refer to this command in later calls to \fBzpty\fP\&.
+.RS
+.PP
+With the \fB\-e\fP option, the pseudo\-terminal is set up so that input
+characters are echoed\&.
+.PP
+With the \fB\-b\fP option, input to and output from the pseudo\-terminal are
+made non\-blocking\&.
+.RE
+.TP
+\fBzpty\fP \fB\-d\fP [ \fInames\fP \&.\&.\&. ]
+The second form, with the \fB\-d\fP option, is used to delete commands
+previously started, by supplying a list of their \fIname\fPs\&.  If no
+\fInames\fP are given, all commands are deleted\&.  Deleting a command causes
+the HUP signal to be sent to the corresponding process\&.
+.TP
+\fBzpty\fP \fB\-w\fP [ \fB\-n\fP ] \fIname\fP [ \fIstrings \&.\&.\&.\fP ]
+The \fB\-w\fP option can be used to send the to command \fIname\fP the given
+\fIstrings\fP as input (separated by spaces)\&.  If the \fB\-n\fP option is
+\fInot\fP given, a newline is added at the end\&.
+.RS
+.PP
+If no \fIstrings\fP are provided, the standard input is copied to the
+pseudo\-terminal; this may stop before copying the full input if the
+pseudo\-terminal is non\-blocking\&.
+.PP
+Note that the command under the pseudo\-terminal sees this input as if it
+were typed, so beware when sending special tty driver characters such as
+word\-erase, line\-kill, and end\-of\-file\&.
+.RE
+.TP
+\fBzpty\fP \fB\-r\fP [ \fB\-t\fP ] \fIname\fP [ \fIparam\fP [ \fIpattern\fP ] ]
+The \fB\-r\fP option can be used to read the output of the command \fIname\fP\&.
+With only a \fIname\fP argument, the output read is copied to the standard
+output\&.  Unless the pseudo\-terminal is non\-blocking, copying continues
+until the command under the pseudo\-terminal exits; when non\-blocking, only
+as much output as is immediately available is copied\&.  The return value is
+zero if any output is copied\&.
+.RS
+.PP
+When also given a \fIparam\fP argument, at most one line is read and stored
+in the parameter named \fIparam\fP\&.  Less than a full line may be read if
+the pseudo\-terminal is non\-blocking\&.  The return value is zero if at least
+one character is stored in \fIparam\fP\&.
+.PP
+If a \fIpattern\fP is given as well, output is read until the whole string
+read matches the \fIpattern\fP, even in the non\-blocking case\&.  The return
+value is zero if the string read matches the pattern, or if the command
+has exited but at least one character could still be read\&.  As of this
+writing, a maximum of one megabyte of output can be consumed this way; if
+a full megabyte is read without matching the pattern, the return value is
+non\-zero\&.
+.PP
+In all cases, the return value is non\-zero if nothing could be read, and
+is \fB2\fP if this is because the command has finished\&.
+.PP
+If the \fB\-r\fP option is combined with the \fB\-t\fP option, \fBzpty\fP tests
+whether output is available before trying to read\&.  If no output is
+available, \fBzpty\fP immediately returns the value \fB1\fP\&.
+.RE
+.TP
+\fBzpty\fP \fB\-t\fP \fIname\fP
+The \fB\-t\fP option without the \fB\-r\fP option can be used to test
+whether the command \fIname\fP is still running\&.  It returns a zero
+value if the command is running and a non\-zero value otherwise\&.
+.TP
+\fBzpty\fP [ \fB\-L\fP ]
+The last form, without any arguments, is used to list the commands
+currently defined\&.  If the \fB\-L\fP option is given, this is done in the
+form of calls to the \fBzpty\fP builtin\&.
+.SH "THE ZSH/ZSELECT MODULE"
+.\" Yodl file: Zsh/mod_zselect.yo
+
+The \fBzsh/zselect\fP module makes available one builtin command:
+.PP
+.PD 0
+.TP
+.PD
+\fBzselect\fP [ \fB\-rwe\fP \fB\-t\fP \fItimeout\fP \fB\-a\fP \fIarray\fP ] [ \fIfd\fP \&.\&.\&. ]
+The \fBzselect\fP builtin is a front\-end to the `select' system call, which
+blocks until a file descriptor is ready for reading or writing, or has an
+error condition, with an optional timeout\&.  If this is not available on
+your system, the command prints an error message and returns status 2
+(normal errors return status 1)\&.  For more information, see your systems
+documentation for \fIselect\fP(3)\&.  Note there is no connection with the
+shell builtin of the same name\&.
+.RS
+.PP
+Arguments and options may be intermingled in any order\&.  Non\-option
+arguments are file descriptors, which must be decimal integers\&.  By
+default, file descriptors are to be tested for reading, i\&.e\&. \fBzselect\fP
+will return when data is available to be read from the file descriptor, or
+more precisely, when a read operation from the file descriptor will not
+block\&.  After a \fB\-r\fP, \fB\-w\fP and \fB\-e\fP, the given file descriptors are
+to be tested for reading, writing, or error conditions\&.  These options and
+an arbitrary list of file descriptors may be given in any order\&.
+.PP
+(The presence of an `error condition' is not well defined in the
+documentation for many implementations of the select system call\&.
+According to recent versions of the POSIX specification, it is really an
+\fIexception\fP condition, of which the only standard example is out\-of\-band
+data received on a socket\&.  So zsh users are unlikely to find the \fB\-e\fP
+option useful\&.)
+.PP
+The option `\fB\-t\fP \fItimeout\fP' specifies a timeout in hundredths of a
+second\&.  This may be zero, in which case the file descriptors will simply
+be polled and \fBzselect\fP will return immediately\&.  It is possible to call
+zselect with no file descriptors and a non\-zero timeout for use as a
+finer\-grained replacement for `sleep'; not, however, the return status is
+always 1 for a timeout\&.
+.PP
+The option `\fB\-a\fP \fIarray\fP' indicates that \fBarray\fP should be set to
+indicate the file descriptor(s) which are ready\&.  If the option is not
+given, the array \fBreply\fP will be used for this purpose\&.  The array will
+contain a string similar to the arguments for \fBzselect\fP\&.  For example,
+.PP
+.RS
+.nf
+\fBzselect \-t 0 \-r 0 \-w 1\fP
+.fi
+.RE
+.PP
+might return immediately with status 0 and \fB$reply\fP containing `\fB\-r 0 \-w
+1\fP' to show that both file descriptors are ready for the requested
+operations\&.
+.PP
+The option `\fB\-A\fP \fIassoc\fP' indicates that the associative array
+\fBassoc\fP should be set to indicate the file descriptor(s) which are
+ready\&.  This option overrides the option \fB\-a\fP, nor will \fBreply\fP be
+modified\&.  The keys of \fBassoc\fP are the file descriptors, and the
+corresponding values are any of the characters `\fBrwe\fP' to indicate the
+condition\&.
+.PP
+The command returns 0 if some file descriptors are ready for reading\&.  If
+the operation timed out, or a timeout of 0 was given and no file
+descriptors were ready, or there was an error, it returns status 1 and
+the array will not be set (nor modified in any way)\&.  If there was an error
+in the select operation the appropriate error message is printed\&.
+.RE
+.RE
+.SH "THE ZSH/ZUTIL MODULE"
+.\" Yodl file: Zsh/mod_zutil.yo
+
+The \fBzsh/zutil\fP module only adds some builtins:
+.PP
+.PD 0
+.TP
+.PD 0
+\fBzstyle\fP [ \fB\-L\fP ]
+.TP
+.PD 0
+\fBzstyle\fP [ \fB\-e\fP | \fB\-\fP | \fB\-\fP\fB\-\fP ] \fIpattern\fP \fIstyle\fP \fIstrings\fP \&.\&.\&.
+.TP
+.PD 0
+\fBzstyle \-d\fP [ \fIpattern\fP [ \fIstyles\fP \&.\&.\&. ] ]
+.TP
+.PD 0
+\fBzstyle \-g\fP \fIname\fP [ \fIpattern\fP [ \fIstyle\fP ] ]
+.TP
+.PD 0
+\fBzstyle \-abs\fP \fIcontext\fP \fIstyle\fP \fIname\fP [ \fIsep\fP ]
+.TP
+.PD 0
+\fBzstyle \-Tt\fP \fIcontext\fP \fIstyle\fP [ \fIstrings\fP \&.\&.\&.]
+.TP
+.PD
+\fBzstyle \-m\fP \fIcontext\fP \fIstyle\fP \fIpattern\fP
+This builtin command is used to define and lookup styles\&.  Styles are
+pairs of names and values, where the values consist of any number of
+strings\&.  They are stored together with patterns and lookup is done by
+giving a string, called the `context', which is compared to the
+patterns\&.  The definition stored for the first matching pattern will be 
+returned\&.
+.RS
+.PP
+For ordering of comparisons, patterns are searched from most specific to
+least specific, and patterns that are equally specific keep the order in 
+which they were defined\&.  A pattern is considered to be more specific
+than another if it contains more components (substrings separated by
+colons) or if the patterns for the components are more specific, where 
+simple strings are considered to be more specific than patterns and
+complex patterns are considered to be more specific than the pattern
+`\fB*\fP'\&.
+.PP
+The first form (without arguments) lists the definitions in the order
+\fBzstyle\fP will test them\&. If the \fB\-L\fP option is given, listing is
+done in the form of calls to \fBzstyle\fP\&.  Forms with arguments:
+.PP
+.PD 0
+.TP
+.PD
+\fBzstyle\fP [ \fB\-\fP | \fB\-\fP\fB\-\fP | \fB\-e\fP ] \fIpattern\fP \fIstyle\fP \fIstrings\fP \&.\&.\&.
+Defines the given \fIstyle\fP for the \fIpattern\fP with the \fIstrings\fP as
+the value\&.  If the \fB\-e\fP option is given, the \fIstrings\fP will be
+concatenated (separated by spaces) and the resulting string will be
+evaluated (in the same way as it is done by the \fBeval\fP builtin
+command) when the style is looked up\&.  In this case the parameter
+`\fBreply\fP' must be assigned to set the strings returned after the
+evaluation\&.  Before evaluating the value, \fBreply\fP is unset, and
+if it is still unset after the evaluation, the style is treated as if
+it were not set\&.
+.TP
+\fBzstyle \-d\fP [ \fIpattern\fP [ \fIstyles\fP \&.\&.\&. ] ]
+Delete style definitions\&. Without arguments all definitions are deleted,
+with a \fIpattern\fP all definitions for that pattern are deleted and if
+any \fIstyles\fP are given, then only those styles are deleted for the
+\fIpattern\fP\&.
+.TP
+\fBzstyle \-g\fP \fIname\fP [ \fIpattern\fP [ \fIstyle\fP ] ]
+Retrieve a style definition\&. The \fIname\fP is
+used as the name of an array in which the results are stored\&. Without
+any further arguments, all \fIpatterns\fP defined are returned\&. With a
+\fIpattern\fP the styles defined for that pattern are returned and with 
+both a \fIpattern\fP and a \fIstyle\fP, the value strings of that
+combination is returned\&.
+.PP
+The other forms can be used to look up or test patterns\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBzstyle \-s\fP \fIcontext\fP \fIstyle\fP \fIname\fP [ \fIsep\fP ]
+The parameter \fIname\fP is set to the value of the style interpreted as a
+string\&.  If the value contains several strings they are concatenated with
+spaces (or with the \fIsep\fP string if that is given) between them\&.
+.TP
+\fBzstyle \-b\fP \fIcontext\fP \fIstyle\fP \fIname\fP
+The value is stored in \fIname\fP as a boolean, i\&.e\&. as the string
+`\fByes\fP' if the value has only one string and that string is equal to one
+of `\fByes\fP', `\fBtrue\fP', `\fBon\fP', or `\fB1\fP'\&. If the value is any other
+string or has more than one string, the parameter is set to `\fBno\fP'\&.
+.TP
+\fBzstyle \-a\fP \fIcontext\fP \fIstyle\fP \fIname\fP
+The value is stored in \fIname\fP as an array\&. If \fIname\fP is declared 
+as an associative array,  the first, third, etc\&. strings are used as the
+keys and the other strings are used as the values\&.
+.TP
+.PD 0
+\fBzstyle \-t\fP \fIcontext\fP \fIstyle\fP [ \fIstrings\fP \&.\&.\&.]
+.TP
+.PD
+\fBzstyle \-T\fP \fIcontext\fP \fIstyle\fP [ \fIstrings\fP \&.\&.\&.]
+Test the value of a style, i\&.e\&. the \fB\-t\fP option only returns a status
+(sets \fB$?\fP)\&.  Without any \fIstrings\fP the return status is zero if the
+style is defined for at least one matching pattern, has only one string in
+its value, and that is equal to one of `\fBtrue\fP', `\fByes\fP', `\fBon\fP' or
+`\fB1\fP'\&. If any \fIstrings\fP are given the status is zero if and only if
+at least one of the \fIstrings\fP is equal to at least one of the strings
+in the value\&. If the style is not defined, the status is \fB2\fP\&.
+.RS
+.PP
+The \fB\-T\fP option tests the values of the style like \fB\-t\fP, but it
+returns zero (rather than \fB2\fP) if the style is not defined for any
+matching pattern\&.
+.RE
+.TP
+\fBzstyle \-m\fP \fIcontext\fP \fIstyle\fP \fIpattern\fP
+Match a value\&. Returns status zero if the 
+\fIpattern\fP matches at least one of the strings in the value\&.
+.RE
+.TP
+.PD 0
+\fBzformat \-f\fP \fIparam\fP \fIformat\fP \fIspecs\fP \&.\&.\&.
+.TP
+.PD
+\fBzformat \-a\fP \fIarray\fP \fIsep\fP \fIspecs\fP \&.\&.\&.
+This builtin provides two different forms of formatting\&. The first form 
+is selected with the \fB\-f\fP option\&. In this case the \fIformat\fP
+string will be modified by replacing sequences starting with a percent 
+sign in it with strings from the \fIspecs\fP\&.  Each \fIspec\fP should be
+of the form `\fIchar\fP\fB:\fP\fIstring\fP' which will cause every
+appearance of the sequence `\fB%\fP\fIchar\fP' in \fIformat\fP to be replaced 
+by the \fIstring\fP\&.  The `\fB%\fP' sequence may also contain optional
+minimum and maximum field width specifications between the `\fB%\fP' and 
+the `\fIchar\fP' in the form `\fB%\fP\fImin\fP\fB\&.\fP\fImax\fP\fBc\fP',
+i\&.e\&. the minimum field width is given first and if the maximum field
+width is used, it has to be preceded by a dot\&.  Specifying a minimum field
+width makes the result be padded with spaces to the right if the
+\fIstring\fP is shorter than the requested width\&.  Padding to the left
+can be achieved by giving a negative minimum field width\&.  If a maximum 
+field width is specified, the \fIstring\fP will be truncated after that
+many characters\&.  After all `\fB%\fP' sequences for the given \fIspecs\fP
+have been processed, the resulting string is stored in the parameter
+\fIparam\fP\&.
+.RS
+.PP
+The \fB%\fP\-escapes also understand ternary expressions in the form used by
+prompts\&.  The \fB%\fP is followed by a `\fB(\fP' and then an ordinary
+format specifier character as described above\&.  There may be a set of
+digits either before or after the `\fB(\fP'; these specify a test
+number, which defaults to zero\&.  Negative numbers are also allowed\&.  An
+arbitrary delimiter character follows the format specifier, which is
+followed by a piece of `true' text, the delimiter character again, a piece
+of `false' text, and a closing parenthesis\&.  The complete expression
+(without the digits) thus looks like
+`\fB%(\fP\fIX\fP\fB\&.\fP\fItext1\fP\fB\&.\fP\fItext2\fP\fB)\fP', except that
+the `\fB\&.\fP' character is arbitrary\&.  The value given for the format
+specifier in the \fIchar\fP\fB:\fP\fIstring\fP expressions is evaluated as a
+mathematical expression, and compared with the test number\&.  If they are
+the same, \fItext1\fP is output, else \fItext2\fP is output\&.  A parenthesis
+may be escaped in \fItext2\fP as \fB%)\fP\&.  Either of \fItext1\fP or
+\fItext2\fP may contain nested \fB%\fP\-escapes\&.
+.PP
+For example:
+.PP
+.RS
+.nf
+\fBzformat \-f REPLY "The answer is '%3(c\&.yes\&.no)'\&." c:3\fP
+.fi
+.RE
+.PP
+outputs "The answer is 'yes'\&." to \fBREPLY\fP since the value for the format
+specifier \fBc\fP is 3, agreeing with the digit argument to the ternary
+expression\&.
+.PP
+The second form, using the \fB\-a\fP option, can be used for aligning
+strings\&.  Here, the \fIspecs\fP are of the form
+`\fIleft\fP\fB:\fP\fIright\fP' where `\fIleft\fP' and `\fIright\fP' are
+arbitrary strings\&.  These strings are modified by replacing the colons
+by the \fIsep\fP string and padding the \fIleft\fP strings with spaces 
+to the right so that the \fIsep\fP strings in the result (and hence the 
+\fIright\fP strings after them) are all aligned if the strings are
+printed below each other\&.  All strings without a colon are left
+unchanged and all strings with an empty \fIright\fP string have the
+trailing colon removed\&.  In both cases the lengths of the strings
+are not used to determine how the other strings are to be aligned\&.
+The resulting strings are stored in the \fIarray\fP\&.
+.RE
+.TP
+\fBzregexparse\fP
+This implements some internals of the \fB_regex_arguments\fP function\&.
+.TP
+\fBzparseopts\fP [ \fB\-D\fP ] [ \fB\-K\fP ] [ \fB\-E\fP ] [ \fB\-a\fP \fIarray\fP ] [ \fB\-A\fP \fIassoc\fP ] \fIspecs\fP
+This builtin simplifies the parsing of options in positional parameters,
+i\&.e\&. the set of arguments given by \fB$*\fP\&.  Each \fIspec\fP describes one
+option and must be of the form `\fIopt\fP[\fB=\fP\fIarray\fP]'\&.  If an option
+described by \fIopt\fP is found in the positional parameters it is copied
+into the \fIarray\fP specified with the \fB\-a\fP option; if the optional
+`\fB=\fP\fIarray\fP' is given, it is instead copied into that array\&.
+.RS
+.PP
+Note that it is an error to give any \fIspec\fP without an
+`\fB=\fP\fIarray\fP' unless one of the \fB\-a\fP or \fB\-A\fP options is used\&.
+.PP
+Unless the \fB\-E\fP option is given, parsing stops at the first string
+that isn't described by one of the \fIspecs\fP\&.  Even with \fB\-E\fP,
+parsing always stops at a positional parameter equal to `\fB\-\fP' or
+`\fB\-\fP\fB\-\fP'\&.
+.PP
+The \fIopt\fP description must be one of the following\&.  Any of the special
+characters can appear in the option name provided it is preceded by a
+backslash\&.
+.PP
+.PD 0
+.TP
+.PD 0
+\fIname\fP
+.TP
+.PD
+\fIname\fP\fB+\fP
+The \fIname\fP is the name of the option without the leading `\fB\-\fP'\&.  To
+specify a GNU\-style long option, one of the usual two leading `\fB\-\fP' must
+be included in \fIname\fP; for example, a `\fB\-\-file\fP' option is
+represented by a \fIname\fP of `\fB\-file\fP'\&.
+.RS
+.PP
+If a `\fB+\fP' appears after \fIname\fP, the option is appended to \fIarray\fP
+each time it is found in the positional parameters; without the `\fB+\fP'
+only the \fIlast\fP occurrence of the option is preserved\&.
+.PP
+If one of these forms is used, the option takes no argument, so parsing
+stops if the next positional parameter does not also begin with `\fB\-\fP'
+(unless the \fB\-E\fP option is used)\&.
+.RE
+.TP
+.PD 0
+\fIname\fP\fB:\fP
+.TP
+.PD 0
+\fIname\fP\fB:\-\fP
+.TP
+.PD
+\fIname\fP\fB::\fP
+If one or two colons are given, the option takes an argument; with one
+colon, the argument is mandatory and with two colons it is optional\&.  The
+argument is appended to the \fIarray\fP after the option itself\&.
+.RS
+.PP
+An optional argument is put into the same array element as the option name
+(note that this makes empty strings as arguments indistinguishable)\&.  A
+mandatory argument is added as a separate element unless the `\fB:\-\fP' form
+is used, in which case the argument is put into the same element\&.
+.PP
+A `\fB+\fP' as described above may appear between the \fIname\fP and the
+first colon\&.
+.RE
+.RE
+.PP
+The options of \fBzparseopts\fP itself are:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-a\fP \fIarray\fP
+As described above, this names the default array in which to store the
+recognised options\&.
+.TP
+\fB\-A\fP \fIassoc\fP
+If this is given, the options and their values are also put into an
+associative array with the option names as keys and the arguments (if any)
+as the values\&.
+.TP
+\fB\-D\fP
+If this option is given, all options found are removed from the positional
+parameters of the calling shell or shell function, up to but not including
+any not described by the \fIspecs\fP\&.  This is similar to using the \fBshift\fP
+builtin\&.
+.TP
+\fB\-K\fP
+With this option, the arrays specified with the \fB\-a\fP and \fB\-A\fP
+options and with the `\fB=\fP\fIarray\fP' forms are kept unchanged when none
+of the \fIspecs\fP for them is used\&.  This allows assignment of default
+values to them before calling \fBzparseopts\fP\&.
+.TP
+\fB\-E\fP
+This changes the parsing rules to \fInot\fP stop at the first string
+that isn't described by one of the \fIspec\fPs\&.  It can be used to test
+for or (if used together with \fB\-D\fP) extract options and their
+arguments, ignoring all other options and arguments that may be in the
+positional parameters\&.
+.PP
+For example,
+.PP
+.RS
+.nf
+\fBset \-\- \-a \-bx \-c y \-cz baz \-cend
+zparseopts a=foo b:=bar c+:=bar\fP
+.fi
+.RE
+.PP
+will have the effect of
+.PP
+.RS
+.nf
+\fBfoo=(\-a)
+bar=(\-b x \-c y \-c z)\fP
+.fi
+.RE
+.PP
+The arguments from `\fBbaz\fP' on will not be used\&.
+.PP
+As an example for the \fB\-E\fP option, consider:
+.PP
+.RS
+.nf
+\fBset \-\- \-a x \-b y \-c z arg1 arg2
+zparseopts \-E \-D b:=bar\fP
+.fi
+.RE
+.PP
+will have the effect of
+.PP
+.RS
+.nf
+\fBbar=(\-b y)
+set \-\- \-a x \-c z arg1 arg2\fP
+.fi
+.RE
+.PP
+I\&.e\&., the option \fB\-b\fP and its arguments are taken from the
+positional parameters and put into the array \fBbar\fP\&.
+.RE
+.RE
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshoptions.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshoptions.1
@@ -0,0 +1,1294 @@
+.TH "ZSHOPTIONS" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshoptions \- zsh options
+.\" Yodl file: Zsh/options.yo
+.SH "SPECIFYING OPTIONS"
+Options are primarily referred to by name\&.
+These names are case insensitive and underscores are ignored\&.
+For example, `\fBallexport\fP' is equivalent to `\fBA__lleXP_ort\fP'\&.
+.PP
+The sense of an option name may be inverted by preceding it with
+`\fBno\fP', so `\fBsetopt No_Beep\fP' is equivalent to `\fBunsetopt beep\fP'\&.
+This inversion can only be done once, so `\fBnonobeep\fP' is \fInot\fP
+a synonym for `\fBbeep\fP'\&.  Similarly, `\fBtify\fP' is not a synonym for
+`\fBnonotify\fP' (the inversion of `\fBnotify\fP')\&.
+.PP
+Some options also have one or more single letter names\&.
+There are two sets of single letter options: one used by default,
+and another used to emulate \fBsh\fP/\fBksh\fP (used when the
+\fBSH_OPTION_LETTERS\fP option is set)\&.
+The single letter options can be used on the shell command line,
+or with the \fBset\fP, \fBsetopt\fP and \fBunsetopt\fP
+builtins, as normal Unix options preceded by `\fB\-\fP'\&.
+.PP
+The sense of the single letter options may be inverted by using
+`\fB+\fP' instead of `\fB\-\fP'\&.
+Some of the single letter option names refer to an option being off,
+in which case the inversion of that name refers to the option being on\&.
+For example, `\fB+n\fP' is the short name of `\fBexec\fP', and
+`\fB\-n\fP' is the short name of its inversion, `\fBnoexec\fP'\&.
+.PP
+In strings of single letter options supplied to the shell at startup,
+trailing whitespace will be ignored; for example the string `\fB\-f    \fP'
+will be treated just as `\fB\-f\fP', but the string `\fB\-f i\fP' is an error\&.
+This is because many systems which implement the `\fB#!\fP' mechanism for
+calling scripts do not strip trailing whitespace\&.
+.PP
+.SH "DESCRIPTION OF OPTIONS"
+In the following list, options set by default in all emulations are marked
+<D>; those set by default only in csh, ksh, sh, or zsh emulations are marked
+<C>, <K>, <S>, <Z> as appropriate\&.  When listing options (by `\fBsetopt\fP',
+`\fBunsetopt\fP', `\fBset \-o\fP' or `\fBset +o\fP'), those turned on by default
+appear in the list prefixed with `\fBno\fP'\&.  Hence (unless
+\fBKSH_OPTION_PRINT\fP is set), `\fBsetopt\fP' shows all options whose settings
+are changed from the default\&.
+.PP
+.SS "Changing Directories"
+.PD 0
+.TP
+.PD
+\fBAUTO_CD\fP (\fB\-J\fP)
+If a command is issued that can't be executed as a normal command,
+and the command is the name of a directory, perform the \fBcd\fP
+command to that directory\&.
+.TP
+\fBAUTO_PUSHD\fP (\fB\-N\fP)
+Make \fBcd\fP push the old directory onto the directory stack\&.
+.TP
+\fBCDABLE_VARS\fP (\fB\-T\fP)
+If the argument to a \fBcd\fP command (or an implied \fBcd\fP with the
+\fBAUTO_CD\fP option set) is not a directory, and does not begin with a
+slash, try to expand the expression as if it were preceded by a `\fB~\fP' (see
+the section `Filename Expansion')\&.
+.TP
+\fBCHASE_DOTS\fP
+When changing to a directory containing a path segment `\fB\&.\&.\fP' which would
+otherwise be treated as canceling the previous segment in the path (in
+other words, `\fBfoo/\&.\&.\fP' would be removed from the path, or if `\fB\&.\&.\fP' is
+the first part of the path, the last part of \fB$PWD\fP would be deleted),
+instead resolve the path to the physical directory\&.  This option is
+overridden by \fBCHASE_LINKS\fP\&.
+.RS
+.PP
+For example, suppose \fB/foo/bar\fP is a link to the directory \fB/alt/rod\fP\&.
+Without this option set, `\fBcd /foo/bar/\&.\&.\fP' changes to \fB/foo\fP; with it
+set, it changes to \fB/alt\fP\&.  The same applies if the current directory
+is \fB/foo/bar\fP and `\fBcd \&.\&.\fP' is used\&.  Note that all other symbolic
+links in the path will also be resolved\&.
+.RE
+.TP
+\fBCHASE_LINKS\fP (\fB\-w\fP)
+Resolve symbolic links to their true values when changing directory\&.
+This also has the effect of \fBCHASE_DOTS\fP, i\&.e\&. a `\fB\&.\&.\fP' path segment
+will be treated as referring to the physical parent, even if the preceding
+path segment is a symbolic link\&.
+.TP
+\fBPUSHD_IGNORE_DUPS\fP
+Don't push multiple copies of the same directory onto the directory stack\&.
+.TP
+\fBPUSHD_MINUS\fP
+Exchanges the meanings of `\fB+\fP' and `\fB\-\fP'
+when used with a number to specify a directory in the stack\&.
+.TP
+\fBPUSHD_SILENT\fP (\fB\-E\fP)
+Do not print the directory stack after \fBpushd\fP or \fBpopd\fP\&.
+.TP
+\fBPUSHD_TO_HOME\fP (\fB\-D\fP)
+Have \fBpushd\fP with no arguments act like `\fBpushd $HOME\fP'\&.
+.PP
+.SS "Completion"
+.PD 0
+.TP
+.PD
+\fBALWAYS_LAST_PROMPT\fP <D>
+If unset, key functions that list completions try to return to the last
+prompt if given a numeric argument\&. If set these functions try to
+return to the last prompt if given \fIno\fP numeric argument\&.
+.TP
+\fBALWAYS_TO_END\fP
+If a completion is performed with the cursor within a word, and a
+full completion is inserted, the cursor is moved to the end of the
+word\&.  That is, the cursor is moved to the end of the word if either
+a single match is inserted or menu completion is performed\&.
+.TP
+\fBAUTO_LIST\fP (\fB\-9\fP) <D>
+Automatically list choices on an ambiguous completion\&.
+.TP
+\fBAUTO_MENU\fP <D>
+Automatically use menu completion after the second consecutive request for
+completion, for example by pressing the tab key repeatedly\&. This option
+is overridden by \fBMENU_COMPLETE\fP\&.
+.TP
+\fBAUTO_NAME_DIRS\fP
+Any parameter that is set to the absolute name of a directory
+immediately becomes a name for that directory, that will be used
+by the `\fB%~\fP'
+and related prompt sequences, and will be available when completion
+is performed on a word starting with `\fB~\fP'\&.
+(Otherwise, the parameter must be used in the form `\fB~\fP\fIparam\fP' first\&.)
+.TP
+\fBAUTO_PARAM_KEYS\fP <D>
+If a parameter name was completed and a following character
+(normally a space) automatically
+inserted, and the next character typed is one
+of those that have to come directly after the name (like `\fB}\fP', `\fB:\fP',
+etc\&.), the automatically added character is deleted, so that the character
+typed comes immediately after the parameter name\&.
+Completion in a brace expansion is affected similarly: the added character
+is a `\fB,\fP', which will be removed if `\fB}\fP' is typed next\&.
+.TP
+\fBAUTO_PARAM_SLASH\fP <D>
+If a parameter is completed whose content is the name of a directory,
+then add a trailing slash instead of a space\&.
+.TP
+\fBAUTO_REMOVE_SLASH\fP <D>
+When the last character resulting from a completion is a slash and the next
+character typed is a word delimiter, a slash, or a character that ends 
+a command (such as a semicolon or an ampersand), remove the slash\&.
+.TP
+\fBBASH_AUTO_LIST\fP
+On an ambiguous completion, automatically list choices when the
+completion function is called twice in succession\&.  This takes
+precedence over \fBAUTO_LIST\fP\&.  The setting of \fBLIST_AMBIGUOUS\fP is
+respected\&.  If \fBAUTO_MENU\fP is set, the menu behaviour will then start
+with the third press\&.  Note that this will not work with
+\fBMENU_COMPLETE\fP, since repeated completion calls immediately cycle
+through the list in that case\&.
+.TP
+\fBCOMPLETE_ALIASES\fP
+Prevents aliases on the command line from being internally substituted
+before completion is attempted\&.  The effect is to make the alias a
+distinct command for completion purposes\&.
+.TP
+\fBCOMPLETE_IN_WORD\fP
+If unset, the cursor is set to the end of the word if completion is
+started\&. Otherwise it stays there and completion is done from both ends\&.
+.TP
+\fBGLOB_COMPLETE\fP
+When the current word has a glob pattern, do not insert all the words
+resulting from the expansion but generate matches as for completion and
+cycle through them like \fBMENU_COMPLETE\fP\&. The matches are generated as if
+a `\fB*\fP' was added to the end of the word, or inserted at the cursor when
+\fBCOMPLETE_IN_WORD\fP is set\&.  This actually uses pattern matching, not
+globbing, so it works not only for files but for any completion, such as
+options, user names, etc\&.
+.TP
+\fBHASH_LIST_ALL\fP <D>
+Whenever a command completion is attempted, make sure the entire
+command path is hashed first\&.  This makes the first completion slower\&.
+.TP
+\fBLIST_AMBIGUOUS\fP <D>
+This option works when \fBAUTO_LIST\fP or \fBBASH_AUTO_LIST\fP is also
+set\&.  If there is an unambiguous prefix to insert on the command line,
+that is done without a completion list being displayed; in other
+words, auto\-listing behaviour only takes place when nothing would be
+inserted\&.  In the case of \fBBASH_AUTO_LIST\fP, this means that the list
+will be delayed to the third call of the function\&.
+.TP
+\fBLIST_BEEP\fP <D>
+Beep on an ambiguous completion\&.  More accurately, this forces the
+completion widgets to return status 1 on an ambiguous completion, which
+causes the shell to beep if the option \fBBEEP\fP is also set; this may
+be modified if completion is called from a user\-defined widget\&.
+.TP
+\fBLIST_PACKED\fP
+Try to make the completion list smaller (occupying less lines) by
+printing the matches in columns with different widths\&.
+.TP
+\fBLIST_ROWS_FIRST\fP
+Lay out the matches in completion lists sorted horizontally, that is,
+the second match is to the right of the first one, not under it as
+usual\&.
+.TP
+\fBLIST_TYPES\fP (\fB\-X\fP) <D>
+When listing files that are possible completions, show the
+type of each file with a trailing identifying mark\&.
+.TP
+\fBMENU_COMPLETE\fP (\fB\-Y\fP)
+On an ambiguous completion, instead of listing possibilities or beeping,
+insert the first match immediately\&.  Then when completion is requested
+again, remove the first match and insert the second match, etc\&.
+When there are no more matches, go back to the first one again\&.
+\fBreverse\-menu\-complete\fP may be used to loop through the list
+in the other direction\&. This option overrides \fBAUTO_MENU\fP\&.
+.TP
+\fBREC_EXACT\fP (\fB\-S\fP)
+In completion, recognize exact matches even
+if they are ambiguous\&.
+.PP
+.SS "Expansion and Globbing"
+.PD 0
+.TP
+.PD
+\fBBAD_PATTERN\fP (\fB+2\fP) <C> <Z>
+If a pattern for filename generation is badly formed, print an error message\&.
+(If this option is unset, the pattern will be left unchanged\&.)
+.TP
+\fBBARE_GLOB_QUAL\fP <Z>
+In a glob pattern, treat a trailing set of parentheses as a qualifier
+list, if it contains no `\fB|\fP', `\fB(\fP' or (if special) `\fB~\fP'
+characters\&.  See the section `Filename Generation'\&.
+.TP
+\fBBRACE_CCL\fP
+Expand expressions in braces which would not otherwise undergo brace
+expansion to a lexically ordered list of all the characters\&.  See
+the section `Brace Expansion'\&.
+.TP
+\fBCASE_GLOB\fP <D>
+Make globbing (filename generation) sensitive to case\&.  Note that other
+uses of patterns are always sensitive to case\&.  If the option is unset,
+the presence of any character which is special to filename generation
+will cause case\-insensitive matching\&.  For example, \fBcvs(/)\fP can
+match the directory \fBCVS\fP owing to the presence of the globbing flag
+(unless the option \fBBARE_GLOB_QUAL\fP is unset)\&.
+.TP
+\fBCSH_NULL_GLOB\fP <C>
+If a pattern for filename generation has no matches,
+delete the pattern from the argument list;
+do not report an error unless all the patterns
+in a command have no matches\&.
+Overrides \fBNOMATCH\fP\&.
+.TP
+\fBEQUALS\fP <Z>
+Perform \fB=\fP filename expansion\&.
+(See the section `Filename Expansion'\&.)
+.TP
+\fBEXTENDED_GLOB\fP
+Treat the `\fB#\fP', `\fB~\fP' and `\fB^\fP' characters as part of patterns
+for filename generation, etc\&.  (An initial unquoted `\fB~\fP'
+always produces named directory expansion\&.)
+.TP
+\fBGLOB\fP (\fB+F\fP, ksh: \fB+f\fP) <D>
+Perform filename generation (globbing)\&.
+(See the section `Filename Generation'\&.)
+.TP
+\fBGLOB_ASSIGN\fP <C>
+If this option is set, filename generation (globbing) is
+performed on the right hand side of scalar parameter assignments of
+the form `\fIname\fP\fB=\fP\fIpattern\fP (e\&.g\&. `\fBfoo=*\fP')\&.
+If the result has more than one word the parameter will become an array
+with those words as arguments\&. This option is provided for backwards
+compatibility only: globbing is always performed on the right hand side
+of array assignments of the form `\fIname\fP\fB=(\fP\fIvalue\fP\fB)\fP'
+(e\&.g\&. `\fBfoo=(*)\fP') and this form is recommended for clarity;
+with this option set, it is not possible to predict whether the result
+will be an array or a scalar\&.
+.TP
+\fBGLOB_DOTS\fP (\fB\-4\fP)
+Do not require a leading `\fB\&.\fP' in a filename to be matched explicitly\&.
+.TP
+\fBGLOB_SUBST\fP <C> <K> <S>
+Treat any characters resulting from parameter expansion as being
+eligible for file expansion and filename generation, and any
+characters resulting from command substitution as being eligible for
+filename generation\&.  Braces (and commas in between) do not become eligible
+for expansion\&.
+.TP
+\fBIGNORE_BRACES\fP (\fB\-I\fP) <S>
+Do not perform brace expansion\&.
+.TP
+\fBKSH_GLOB\fP <K>
+In pattern matching, the interpretation of parentheses is affected by
+a preceding `\fB@\fP', `\fB*\fP', `\fB+\fP', `\fB?\fP' or `\fB!\fP'\&.
+See the section `Filename Generation'\&.
+.TP
+\fBMAGIC_EQUAL_SUBST\fP
+All unquoted arguments of the form `\fIanything\fP\fB=\fP\fIexpression\fP'
+appearing after the command name have filename expansion (that is,
+where \fIexpression\fP has a leading `\fB~\fP' or `\fB=\fP') performed on
+\fIexpression\fP as if it were a parameter assignment\&.  The argument is
+not otherwise treated specially; it is passed to the command as a single
+argument, and not used as an actual parameter assignment\&.  For example, in
+\fBecho foo=~/bar:~/rod\fP, both occurrences of \fB~\fP would be replaced\&.
+Note that this happens anyway with \fBtypeset\fP and similar statements\&.
+.RS
+.PP
+This option respects the setting of the \fBKSH_TYPESET\fP option\&.  In other
+words, if both options are in effect, arguments looking like
+assignments will not undergo wordsplitting\&.
+.RE
+.TP
+\fBMARK_DIRS\fP (\fB\-8\fP, ksh: \fB\-X\fP)
+Append a trailing `\fB/\fP' to all directory
+names resulting from filename generation (globbing)\&.
+.TP
+\fBNOMATCH\fP (\fB+3\fP) <C> <Z>
+If a pattern for filename generation has no matches,
+print an error, instead of
+leaving it unchanged in the argument list\&.
+This also applies to file expansion
+of an initial `\fB~\fP' or `\fB=\fP'\&.
+.TP
+\fBNULL_GLOB\fP (\fB\-G\fP)
+If a pattern for filename generation has no matches,
+delete the pattern from the argument list instead
+of reporting an error\&.  Overrides \fBNOMATCH\fP\&.
+.TP
+\fBNUMERIC_GLOB_SORT\fP
+If numeric filenames are matched by a filename generation pattern,
+sort the filenames numerically rather than lexicographically\&.
+.TP
+\fBRC_EXPAND_PARAM\fP (\fB\-P\fP)
+Array expansions of the form
+`\fIfoo\fP\fB${\fP\fIxx\fP\fB}\fP\fIbar\fP', where the parameter
+\fIxx\fP is set to \fB(\fP\fIa b c\fP\fB)\fP, are substituted with
+`\fIfooabar foobbar foocbar\fP' instead of the default
+`\fIfooa b cbar\fP'\&.
+.TP
+\fBSH_GLOB\fP <K> <S>
+Disables the special meaning of `\fB(\fP', `\fB|\fP', `\fB)\fP'
+and '\fB<\fP' for globbing the result of parameter and command substitutions,
+and in some other places where
+the shell accepts patterns\&.  This option is set by default if zsh is
+invoked as \fBsh\fP or \fBksh\fP\&.
+.TP
+\fBUNSET\fP (\fB+u\fP, ksh: \fB+u\fP) <K> <S> <Z>
+Treat unset parameters as if they were empty when substituting\&.
+Otherwise they are treated as an error\&.
+.PP
+.SS "History"
+.PD 0
+.TP
+.PD
+\fBAPPEND_HISTORY\fP <D>
+If this is set, zsh sessions will append their history list to
+the history file, rather than overwrite it\&. Thus, multiple parallel
+zsh sessions will all have their history lists added to the
+history file, in the order they are killed\&.
+.TP
+\fBBANG_HIST\fP (\fB+K\fP) <C> <Z>
+Perform textual history expansion, \fBcsh\fP\-style,
+treating the character `\fB!\fP' specially\&.
+.TP
+\fBEXTENDED_HISTORY\fP <C>
+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:
+.RS
+.PP
+`\fB:\fP\fI<beginning time>\fP\fB:\fP\fI<elapsed seconds>\fP\fB:\fP\fI<command>\fP'\&.
+.RE
+.TP
+\fBHIST_ALLOW_CLOBBER\fP
+Add `\fB|\fP' to output redirections in the history\&.  This allows history
+references to clobber files even when \fBCLOBBER\fP is unset\&.
+.TP
+\fBHIST_BEEP\fP <D>
+Beep when an attempt is made to access a history entry which
+isn't there\&.
+.TP
+\fBHIST_EXPIRE_DUPS_FIRST\fP
+If the internal history needs to be trimmed to add the current command line,
+setting this option will cause the oldest history event that has a duplicate
+to be lost before losing a unique event from the list\&.
+You should be sure to set the value of \fBHISTSIZE\fP to a larger number
+than \fBSAVEHIST\fP in order to give you some room for the duplicated
+events, otherwise this option will behave just like
+\fBHIST_IGNORE_ALL_DUPS\fP once the history fills up with unique events\&.
+.TP
+\fBHIST_FIND_NO_DUPS\fP
+When searching for history entries in the line editor, do not display
+duplicates of a line previously found, even if the duplicates are not
+contiguous\&.
+.TP
+\fBHIST_IGNORE_ALL_DUPS\fP
+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)\&.
+.TP
+\fBHIST_IGNORE_DUPS\fP (\fB\-h\fP)
+Do not enter command lines into the history list
+if they are duplicates of the previous event\&.
+.TP
+\fBHIST_IGNORE_SPACE\fP (\fB\-g\fP)
+Remove command lines from the history list when the first character on
+the line is a space, or when one of the expanded aliases contains a
+leading space\&.
+Note that the command lingers in the internal history until the next
+command is entered before it vanishes, allowing you to briefly reuse
+or edit the line\&.  If you want to make it vanish right away without
+entering another command, type a space and press return\&.
+.TP
+\fBHIST_NO_FUNCTIONS\fP
+Remove function definitions from the history list\&.
+Note that the function lingers in the internal history until the next
+command is entered before it vanishes, allowing you to briefly reuse
+or edit the definition\&.
+.TP
+\fBHIST_NO_STORE\fP
+Remove the \fBhistory\fP (\fBfc \-l\fP) command from the history list
+when invoked\&.
+Note that the command lingers in the internal history until the next
+command is entered before it vanishes, allowing you to briefly reuse
+or edit the line\&.
+.TP
+\fBHIST_REDUCE_BLANKS\fP
+Remove superfluous blanks from each command line
+being added to the history list\&.
+.TP
+\fBHIST_SAVE_NO_DUPS\fP
+When writing out the history file, older commands that duplicate
+newer ones are omitted\&.
+.TP
+\fBHIST_VERIFY\fP
+Whenever the user enters a line with history expansion,
+don't execute the line directly; instead, perform
+history expansion and reload the line into the editing buffer\&.
+.TP
+\fBINC_APPEND_HISTORY\fP
+This options works like \fBAPPEND_HISTORY\fP except that new history lines
+are added to the \fB$HISTFILE\fP incrementally (as soon as they are
+entered), rather than waiting until the shell is killed\&.
+The file is periodically trimmed to the number of lines specified by
+\fB$SAVEHIST\fP, but can exceed this value between trimmings\&.
+.TP
+\fBSHARE_HISTORY\fP <K>
+.RS
+.PP
+This option both imports new commands from the history file, and also
+causes your typed commands to be appended to the history file (the
+latter is like specifying \fBINC_APPEND_HISTORY\fP)\&.
+The history lines are also output with timestamps ala
+\fBEXTENDED_HISTORY\fP (which makes it easier to find the spot where
+we left off reading the file after it gets re\-written)\&.
+.PP
+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\&.
+.PP
+If you find that you want more control over when commands
+get imported, you may wish to turn \fBSHARE_HISTORY\fP off,
+\fBINC_APPEND_HISTORY\fP on, and then manually import
+commands whenever you need them using `\fBfc \-RI\fP'\&.
+.RE
+.RE
+.PP
+.SS "Initialisation"
+.PD 0
+.TP
+.PD
+\fBALL_EXPORT\fP (\fB\-a\fP, ksh: \fB\-a\fP)
+All parameters subsequently defined are automatically exported\&.
+.TP
+\fBGLOBAL_EXPORT\fP (\fB<Z>\fP)
+If this option is set, passing the \fB\-x\fP flag to the builtins \fBdeclare\fP,
+\fBfloat\fP, \fBinteger\fP, \fBreadonly\fP and \fBtypeset\fP (but not \fBlocal\fP)
+will also set the \fB\-g\fP flag;  hence parameters exported to
+the environment will not be made local to the enclosing function, unless
+they were already or the flag \fB+g\fP is given explicitly\&.  If the option is
+unset, exported parameters will be made local in just the same way as any
+other parameter\&.
+.RS
+.PP
+This option is set by default for backward compatibility; it is not
+recommended that its behaviour be relied upon\&.  Note that the builtin
+\fBexport\fP always sets both the \fB\-x\fP and \fB\-g\fP flags, and hence its
+effect extends beyond the scope of the enclosing function; this is the
+most portable way to achieve this behaviour\&.
+.RE
+.TP
+\fBGLOBAL_RCS\fP (\fB\-d\fP) <D>
+If this option is unset, the startup files \fB/etc/zprofile\fP,
+\fB/etc/zshrc\fP, \fB/etc/zlogin\fP and \fB/etc/zlogout\fP will not be run\&.  It
+can be disabled and re\-enabled at any time, including inside local startup
+files (\fB\&.zshrc\fP, etc\&.)\&.
+.TP
+\fBRCS\fP (\fB+f\fP) <D>
+After \fB/etc/zshenv\fP is sourced on startup, source the
+\fB\&.zshenv\fP, \fB/etc/zprofile\fP, \fB\&.zprofile\fP,
+\fB/etc/zshrc\fP, \fB\&.zshrc\fP, \fB/etc/zlogin\fP, \fB\&.zlogin\fP, and \fB\&.zlogout\fP
+files, as described in the section `Files'\&.
+If this option is unset, the \fB/etc/zshenv\fP file is still sourced, but any
+of the others will not be; it can be set at any time to prevent the
+remaining startup files after the currently executing one from
+being sourced\&.
+.PP
+.SS "Input/Output"
+.PD 0
+.TP
+.PD
+\fBALIASES\fP <D>
+Expand aliases\&.
+.TP
+\fBCLOBBER\fP (\fB+C\fP, ksh: \fB+C\fP) <D>
+Allows `\fB>\fP' redirection to truncate existing files,
+and `\fB>>\fP' to create files\&.
+Otherwise `\fB>!\fP' or `\fB>|\fP' must be used to truncate a file,
+and `\fB>>!\fP' or `\fB>>|\fP' to create a file\&.
+.TP
+\fBCORRECT\fP (\fB\-0\fP)
+Try to correct the spelling of commands\&.
+Note that, when the \fBHASH_LIST_ALL\fP option is not set or when some
+directories in the path are not readable, this may falsely report spelling
+errors the first time some commands are used\&.
+.TP
+\fBCORRECT_ALL\fP (\fB\-O\fP)
+Try to correct the spelling of all arguments in a line\&.
+.TP
+\fBDVORAK\fP
+Use the Dvorak keyboard instead of the standard qwerty keyboard as a basis
+for examining spelling mistakes for the \fBCORRECT\fP and \fBCORRECT_ALL\fP
+options and the \fBspell\-word\fP editor command\&.
+.TP
+\fBFLOW_CONTROL\fP <D>
+If this option is unset,
+output flow control via start/stop characters (usually assigned to
+^S/^Q) is disabled in the shell's editor\&.
+.TP
+\fBIGNORE_EOF\fP (\fB\-7\fP)
+Do not exit on end\-of\-file\&.  Require the use
+of \fBexit\fP or \fBlogout\fP instead\&.
+However, ten consecutive EOFs will cause the shell to exit anyway,
+to avoid the shell hanging if its tty goes away\&.
+.RS
+.PP
+Also, if this option is set and the Zsh Line Editor is used, widgets
+implemented by shell functions can be bound to EOF (normally
+Control\-D) without printing the normal warning message\&.  This works
+only for normal widgets, not for completion widgets\&.
+.RE
+.TP
+\fBINTERACTIVE_COMMENTS\fP (\fB\-k\fP) <K> <S>
+Allow comments even in interactive shells\&.
+.TP
+\fBHASH_CMDS\fP <D>
+Note the location of each command the first time it is executed\&.
+Subsequent invocations of the same command will use the
+saved location, avoiding a path search\&.
+If this option is unset, no path hashing is done at all\&.
+However, when \fBCORRECT\fP is set, commands whose names do not appear in
+the functions or aliases hash tables are hashed in order to avoid
+reporting them as spelling errors\&.
+.TP
+\fBHASH_DIRS\fP <D>
+Whenever a command name is hashed, hash the directory containing it,
+as well as all directories that occur earlier in the path\&.
+Has no effect if neither \fBHASH_CMDS\fP nor \fBCORRECT\fP is set\&.
+.TP
+\fBMAIL_WARNING\fP (\fB\-U\fP)
+Print a warning message if a mail file has been
+accessed since the shell last checked\&.
+.TP
+\fBPATH_DIRS\fP (\fB\-Q\fP)
+Perform a path search even on command names with slashes in them\&.
+Thus if `\fB/usr/local/bin\fP' is in the user's path, and he or she types
+`\fBX11/xinit\fP', the command `\fB/usr/local/bin/X11/xinit\fP' will be executed
+(assuming it exists)\&.
+Commands explicitly beginning with `\fB/\fP', `\fB\&./\fP' or `\fB\&.\&./\fP'
+are not subject to the path search\&.
+This also applies to the \fB\&.\fP builtin\&.
+.RS
+.PP
+Note that subdirectories of the current directory are always searched for
+executables specified in this form\&.  This takes place before any search
+indicated by this option, and regardless of whether `\fB\&.\fP' or the current
+directory appear in the command search path\&.
+.RE
+.TP
+\fBPRINT_EIGHT_BIT\fP
+Print eight bit characters literally in completion lists, etc\&.
+This option is not necessary if your system correctly returns the
+printability of eight bit characters (see \fIctype\fP(3))\&.
+.TP
+\fBPRINT_EXIT_VALUE\fP (\fB\-1\fP)
+Print the exit value of programs with non\-zero exit status\&.
+.TP
+\fBRC_QUOTES\fP
+Allow the character sequence `\fB''\fP' to signify a single quote
+within singly quoted strings\&.  Note this does not apply in quoted strings
+using the format \fB$'\fP\fI\&.\&.\&.\fP\fB'\fP, where a backslashed single quote can
+be used\&.
+.TP
+\fBRM_STAR_SILENT\fP (\fB\-H\fP) <K> <S>
+Do not query the user before executing `\fBrm *\fP' or `\fBrm path/*\fP'\&.
+.TP
+\fBRM_STAR_WAIT\fP
+If querying the user before executing `\fBrm *\fP' or `\fBrm path/*\fP',
+first wait ten seconds and ignore anything typed in that time\&.
+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 `\fB*\fP' in ZLE (with tab)\&.
+.TP
+\fBSHORT_LOOPS\fP <C> <Z>
+Allow the short forms of \fBfor\fP, \fBrepeat\fP, \fBselect\fP,
+\fBif\fP, and \fBfunction\fP constructs\&.
+.TP
+\fBSUN_KEYBOARD_HACK\fP (\fB\-L\fP)
+If a line ends with a backquote, and there are an odd number
+of backquotes on the line, ignore the trailing backquote\&.
+This is useful on some keyboards where the return key is
+too small, and the backquote key lies annoyingly close to it\&.
+.PP
+.SS "Job Control"
+.PD 0
+.TP
+.PD
+\fBAUTO_CONTINUE\fP
+With this option set, stopped jobs that are removed from the job table
+with the \fBdisown\fP builtin command are automatically sent a \fBCONT\fP
+signal to make them running\&.
+.TP
+\fBAUTO_RESUME\fP (\fB\-W\fP)
+Treat single word simple commands without redirection
+as candidates for resumption of an existing job\&.
+.TP
+\fBBG_NICE\fP (\fB\-6\fP) <C> <Z>
+Run all background jobs at a lower priority\&.  This option
+is set by default\&.
+.TP
+\fBCHECK_JOBS\fP <Z>
+Report the status of background and suspended jobs before exiting a shell
+with job control; a second attempt to exit the shell will succeed\&.
+\fBNO_CHECK_JOBS\fP is best used only in combination with \fBNO_HUP\fP, else
+such jobs will be killed automatically\&.
+.RS
+.PP
+The check is omitted if the commands run from the previous command line
+included a `\fBjobs\fP' command, since it is assumed the user is aware that
+there are background or suspended jobs\&.  A `\fBjobs\fP' command run from the
+\fBprecmd\fP function is not counted for this purpose\&.
+.RE
+.TP
+\fBHUP\fP <Z>
+Send the \fBHUP\fP signal to running jobs when the
+shell exits\&.
+.TP
+\fBLONG_LIST_JOBS\fP (\fB\-R\fP)
+List jobs in the long format by default\&.
+.TP
+\fBMONITOR\fP (\fB\-m\fP, ksh: \fB\-m\fP)
+Allow job control\&.  Set by default in interactive shells\&.
+.TP
+\fBNOTIFY\fP (\fB\-5\fP, ksh: \fB\-b\fP) <Z>
+Report the status of background jobs immediately, rather than
+waiting until just before printing a prompt\&.
+.PP
+.SS "Prompting"
+.PD 0
+.TP
+.PD
+\fBPROMPT_BANG\fP <K>
+If set, `\fB!\fP' is treated specially in prompt expansion\&.
+See the section `Prompt Expansion'\&.
+.TP
+\fBPROMPT_CR\fP (\fB+V\fP) <D>
+Print a carriage return just before printing
+a prompt in the line editor\&.  This is on by default as multi\-line editing
+is only possible if the editor knows where the start of the line appears\&.
+.TP
+\fBPROMPT_PERCENT\fP <C> <Z>
+If set, `\fB%\fP' is treated specially in prompt expansion\&.
+See the section `Prompt Expansion'\&.
+.TP
+\fBPROMPT_SUBST\fP <K>
+If set, \fIparameter expansion\fP, \fIcommand substitution\fP and
+\fIarithmetic expansion\fP are performed in prompts\&.  Substitutions
+within prompts do not affect the command status\&.
+.TP
+\fBTRANSIENT_RPROMPT\fP
+Remove any right prompt from display when accepting a command
+line\&.  This may be useful with terminals with other cut/paste methods\&.
+.PP
+.SS "Scripts and Functions"
+.PD 0
+.TP
+.PD
+\fBC_BASES\fP
+Output hexadecimal numbers in the standard C format, for example `\fB0xFF\fP'
+instead of the usual `\fB16#FF\fP'\&.  If the option \fBOCTAL_ZEROES\fP is also
+set (it is not by default), octal numbers will be treated similarly and
+hence appear as `\fB077\fP' instead of `\fB8#77\fP'\&.  This option has no effect
+on the choice of the output base, nor on the output of bases other than
+hexadecimal and octal\&.  Note that these formats will be understood on input
+irrespective of the setting of \fBC_BASES\fP\&.
+.TP
+\fBERR_EXIT\fP (\fB\-e\fP, ksh: \fB\-e\fP)
+If a command has a non\-zero exit status, execute the \fBZERR\fP
+trap, if set, and exit\&.  This is disabled while running initialization
+scripts\&.
+.TP
+\fBERR_RETURN\fP
+If a command has a non\-zero exit status, return immediately from the
+enclosing function\&.  The logic is identical to that for \fBERR_EXIT\fP,
+except that an implicit \fBreturn\fP statement is executed instead of an
+\fBexit\fP\&.  This will trigger an exit at the outermost level of a
+non\-interactive script\&.
+.TP
+\fBEVAL_LINENO\fP <Z>
+If set, line numbers of expressions evaluated using the builtin \fBeval\fP
+are tracked separately of the enclosing environment\&.  This applies both
+to the parameter \fBLINENO\fP and the line number output by the prompt
+escape \fB%i\fP\&.  If the option is set, the prompt escape \fB%N\fP will output
+the string `\fB(eval)\fP' instead of the script or function name as an
+indication\&.   (The two prompt escapes are typically used in the parameter
+\fBPS4\fP to be output when the option \fBXTRACE\fP is set\&.)  If
+\fBEVAL_LINENO\fP is unset, the line number of the surrounding script or
+function is retained during the evaluation\&.
+.TP
+\fBEXEC\fP (\fB+n\fP, ksh: \fB+n\fP) <D>
+Do execute commands\&.  Without this option, commands are
+read and checked for syntax errors, but not executed\&.
+This option cannot be turned off in an interactive shell,
+except when `\fB\-n\fP' is supplied to the shell at startup\&.
+.TP
+\fBFUNCTION_ARGZERO\fP <C> <Z>
+When executing a shell function or sourcing a script, set \fB$0\fP
+temporarily to the name of the function/script\&.
+.TP
+\fBLOCAL_OPTIONS\fP <K>
+If this option is set at the point of return from a shell function,
+all the options (including this one) which were in force upon entry to
+the function are restored\&.  Otherwise, only this option and the
+\fBXTRACE\fP and \fBPRINT_EXIT_VALUE\fP options are restored\&.  Hence
+if this is explicitly unset by a shell function the other options in
+force at the point of return will remain so\&.
+A shell function can also guarantee itself a known shell configuration
+with a formulation like `\fBemulate \-L zsh\fP'; the \fB\-L\fP activates
+\fBLOCAL_OPTIONS\fP\&.
+.TP
+\fBLOCAL_TRAPS\fP <K>
+If this option is set when a signal trap is set inside a function, then the
+previous status of the trap for that signal will be restored when the
+function exits\&.  Note that this option must be set \fIprior\fP to altering the
+trap behaviour in a function; unlike \fBLOCAL_OPTIONS\fP, the value on exit
+from the function is irrelevant\&.  However, it does not need to be set
+before any global trap for that to be correctly restored by a function\&.
+For example,
+.RS
+.PP
+.RS
+.nf
+\fBunsetopt localtraps
+trap \- INT
+fn() { setopt localtraps; trap '' INT; sleep 3; }\fP
+.fi
+.RE
+.PP
+will restore normally handling of \fBSIGINT\fP after the function exits\&.
+.RE
+.TP
+\fBMULTIOS\fP <Z>
+Perform implicit \fBtee\fPs or \fBcat\fPs when multiple
+redirections are attempted (see the section `Redirection')\&.
+.TP
+\fBOCTAL_ZEROES\fP <S>
+Interpret any integer constant beginning with a 0 as octal, per IEEE Std
+1003\&.2\-1992 (ISO 9945\-2:1993)\&.  This is not enabled by default as it
+causes problems with parsing of, for example, date and time strings with
+leading zeroes\&.
+.TP
+\fBTYPESET_SILENT\fP
+If this is unset, executing any of the `\fBtypeset\fP' family of
+commands with no options and a list of parameters that have no values
+to be assigned but already exist will display the value of the parameter\&.
+If the option is set, they will only be shown when parameters are selected
+with the `\fB\-m\fP' option\&.  The option `\fB\-p\fP' is available whether or not
+the option is set\&.
+.TP
+\fBVERBOSE\fP (\fB\-v\fP, ksh: \fB\-v\fP)
+Print shell input lines as they are read\&.
+.TP
+\fBXTRACE\fP (\fB\-x\fP, ksh: \fB\-x\fP)
+Print commands and their arguments as they are executed\&.
+.PP
+.SS "Shell Emulation"
+.PD 0
+.TP
+.PD
+\fBBSD_ECHO\fP <S>
+Make the \fBecho\fP builtin compatible with the BSD \fIecho\fP(1) command\&.
+This disables backslashed escape sequences in echo strings unless the
+\fB\-e\fP option is specified\&.
+.TP
+\fBCSH_JUNKIE_HISTORY\fP <C>
+A history reference without an event specifier will always refer to the
+previous command\&.  Without this option, such a history reference refers
+to the same event as the previous history reference, defaulting to the
+previous command\&.
+.TP
+\fBCSH_JUNKIE_LOOPS\fP <C>
+Allow loop bodies to take the form `\fIlist\fP; \fBend\fP' instead of
+`\fBdo\fP \fIlist\fP; \fBdone\fP'\&.
+.TP
+\fBCSH_JUNKIE_QUOTES\fP <C>
+Changes the rules for single\- and double\-quoted text to match that of
+\fBcsh\fP\&.  These require that embedded newlines be preceded by a backslash;
+unescaped newlines will cause an error message\&.
+In double\-quoted strings, it is made impossible to escape `\fB$\fP', `\fB`\fP'
+or `\fB"\fP' (and `\fB\e\fP' itself no longer needs escaping)\&.
+Command substitutions are only expanded once, and cannot be nested\&.
+.TP
+\fBCSH_NULLCMD\fP <C>
+Do not use the values of \fBNULLCMD\fP and \fBREADNULLCMD\fP 
+when running redirections with no command\&.  This make 
+such redirections fail (see the section `Redirection')\&.
+.TP
+\fBKSH_ARRAYS\fP <K> <S>
+Emulate \fBksh\fP array handling as closely as possible\&.  If this option
+is set, array elements are numbered from zero, an array parameter
+without subscript refers to the first element instead of the whole array,
+and braces are required to delimit a subscript (`\fB${path[2]}\fP' rather
+than just `\fB$path[2]\fP')\&.
+.TP
+\fBKSH_AUTOLOAD\fP <K> <S>
+Emulate \fBksh\fP function autoloading\&.  This means that when a function is
+autoloaded, the corresponding file is merely executed, and must define
+the function itself\&.  (By default, the function is defined to the contents
+of the file\&.  However, the most common \fBksh\fP\-style case \- of the file
+containing only a simple definition of the function \- is always handled
+in the \fBksh\fP\-compatible manner\&.)
+.TP
+\fBKSH_OPTION_PRINT\fP <K>
+Alters the way options settings are printed: instead of separate lists of
+set and unset options, all options are shown, marked `on' if
+they are in the non\-default state, `off' otherwise\&.
+.TP
+\fBKSH_TYPESET\fP <K>
+Alters the way arguments to the \fBtypeset\fP family of commands, including
+\fBdeclare\fP, \fBexport\fP, \fBfloat\fP, \fBinteger\fP, \fBlocal\fP and
+\fBreadonly\fP, are processed\&.  Without this option, zsh will perform normal
+word splitting after command and parameter expansion in arguments of an
+assignment; with it, word splitting does not take place in those cases\&.
+.TP
+\fBPOSIX_BUILTINS\fP <K> <S>
+When this option is set the \fBcommand\fP builtin can be used to execute
+shell builtin commands\&.  Parameter assignments specified before shell
+functions and special builtins are kept after the command completes unless
+the special builtin is prefixed with the \fBcommand\fP builtin\&.  Special
+builtins are
+\fB\&.\fP,
+\fB:\fP,
+\fBbreak\fP,
+\fBcontinue\fP,
+\fBdeclare\fP,
+\fBeval\fP,
+\fBexit\fP,
+\fBexport\fP,
+\fBinteger\fP,
+\fBlocal\fP,
+\fBreadonly\fP,
+\fBreturn\fP,
+\fBset\fP,
+\fBshift\fP,
+\fBsource\fP,
+\fBtimes\fP,
+\fBtrap\fP and
+\fBunset\fP\&.
+.TP
+\fBSH_FILE_EXPANSION\fP <K> <S>
+Perform filename expansion (e\&.g\&., ~ expansion) \fIbefore\fP
+parameter expansion, command substitution, arithmetic expansion
+and brace expansion\&.
+If this option is unset, it is performed \fIafter\fP
+brace expansion, so things like `\fB~$USERNAME\fP' and
+`\fB~{pfalstad,rc}\fP' will work\&.
+.TP
+\fBSH_NULLCMD\fP <K> <S>
+Do not use the values of \fBNULLCMD\fP and \fBREADNULLCMD\fP 
+when doing redirections, use `\fB:\fP' instead (see the section `Redirection')\&.
+.TP
+\fBSH_OPTION_LETTERS\fP <K> <S>
+If this option is set the shell tries to interpret single letter options
+(which are used with \fBset\fP and \fBsetopt\fP) like \fBksh\fP does\&.
+This also affects the value of the \fB\-\fP special parameter\&.
+.TP
+\fBSH_WORD_SPLIT\fP (\fB\-y\fP) <K> <S>
+Causes field splitting to be performed on unquoted parameter expansions\&.
+Note that this option has nothing to do with word splitting\&.
+(See the section `Parameter Expansion'\&.)
+.TP
+\fBTRAPS_ASYNC\fP
+While waiting for a program to exit, handle signals and run traps
+immediately\&.  Otherwise the trap is run after a child process has exited\&.
+Note this does not affect the point at which traps are run for any case
+other than when the shell is waiting for a child process\&.
+.PP
+.SS "Shell State"
+.PD 0
+.TP
+.PD
+\fBINTERACTIVE\fP (\fB\-i\fP, ksh: \fB\-i\fP)
+This is an interactive shell\&.  This option is set upon initialisation if
+the standard input is a tty and commands are being read from standard input\&.
+(See the discussion of \fBSHIN_STDIN\fP\&.)
+This heuristic may be overridden by specifying a state for this option
+on the command line\&.
+The value of this option cannot be changed anywhere other than the command line\&.
+.TP
+\fBLOGIN\fP (\fB\-l\fP, ksh: \fB\-l\fP)
+This is a login shell\&.
+If this option is not explicitly set, the shell is a login shell if
+the first character of the \fBargv[0]\fP passed to the shell is a `\fB\-\fP'\&.
+.TP
+\fBPRIVILEGED\fP (\fB\-p\fP, ksh: \fB\-p\fP)
+Turn on privileged mode\&. This is enabled automatically on startup if the
+effective user (group) ID is not equal to the real user (group) ID\&.  Turning
+this option off causes the effective user and group IDs to be set to the
+real user and group IDs\&. This option disables sourcing user startup files\&.
+If zsh is invoked as `\fBsh\fP' or `\fBksh\fP' with this option set,
+\fB/etc/suid_profile\fP is sourced (after \fB/etc/profile\fP on interactive
+shells)\&. Sourcing \fB~/\&.profile\fP is disabled and the contents of the
+\fBENV\fP variable is ignored\&. This option cannot be changed using the
+\fB\-m\fP option of \fBsetopt\fP and \fBunsetopt\fP, and changing it inside a
+function always changes it globally regardless of the \fBLOCAL_OPTIONS\fP
+option\&.
+.TP
+\fBRESTRICTED\fP (\fB\-r\fP)
+Enables restricted mode\&.  This option cannot be changed using
+\fBunsetopt\fP, and setting it inside a function always changes it
+globally regardless of the \fBLOCAL_OPTIONS\fP option\&.  See
+the section `Restricted Shell'\&.
+.TP
+\fBSHIN_STDIN\fP (\fB\-s\fP, ksh: \fB\-s\fP)
+Commands are being read from the standard input\&.
+Commands are read from standard input if no command is specified with
+\fB\-c\fP and no file of commands is specified\&.  If \fBSHIN_STDIN\fP
+is set explicitly on the command line,
+any argument that would otherwise have been
+taken as a file to run will instead be treated as a normal positional
+parameter\&.
+Note that setting or unsetting this option on the command line does not
+necessarily affect the state the option will have while the shell is
+running \- that is purely an indicator of whether on not commands are
+\fIactually\fP being read from standard input\&.
+The value of this option cannot be changed anywhere other 
+than the command line\&.
+.TP
+\fBSINGLE_COMMAND\fP (\fB\-t\fP, ksh: \fB\-t\fP)
+If the shell is reading from standard input, it exits after a single command
+has been executed\&.  This also makes the shell non\-interactive, unless the
+\fBINTERACTIVE\fP option is explicitly set on the command line\&.
+The value of this option cannot be changed anywhere other than the command line\&.
+.PP
+.SS "Zle"
+.PD 0
+.TP
+.PD
+\fBBEEP\fP (\fB+B\fP) <D>
+Beep on error in ZLE\&.
+.TP
+\fBEMACS\fP
+If ZLE is loaded, turning on this option has the equivalent effect
+of `\fBbindkey \-e\fP'\&.  In addition, the VI option is unset\&.
+Turning it off has no effect\&.  The option setting is
+not guaranteed to reflect the current keymap\&.  This option is
+provided for compatibility; \fBbindkey\fP is the recommended interface\&.
+.TP
+\fBOVERSTRIKE\fP
+Start up the line editor in overstrike mode\&.
+.TP
+\fBSINGLE_LINE_ZLE\fP (\fB\-M\fP) <K>
+Use single\-line command line editing instead of multi\-line\&.
+.TP
+\fBVI\fP
+If ZLE is loaded, turning on this option has the equivalent effect
+of `\fBbindkey \-v\fP'\&.  In addition, the EMACS option is unset\&.
+Turning it off has no effect\&.  The option setting is
+not guaranteed to reflect the current keymap\&.  This option is
+provided for compatibility; \fBbindkey\fP is the recommended interface\&.
+.TP
+\fBZLE\fP (\fB\-Z\fP)
+Use the zsh line editor\&.  Set by default in interactive shells connected to
+a terminal\&.
+.PP
+.SH "OPTION ALIASES"
+Some options have alternative names\&.  These aliases are never used for
+output, but can be used just like normal option names when specifying
+options to the shell\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBBRACE_EXPAND\fP
+\fINO_\fP\fBIGNORE_BRACES\fP
+(ksh and bash compatibility)
+.TP
+\fBDOT_GLOB\fP
+\fBGLOB_DOTS\fP
+(bash compatibility)
+.TP
+\fBHASH_ALL\fP
+\fBHASH_CMDS\fP
+(bash compatibility)
+.TP
+\fBHIST_APPEND\fP
+\fBAPPEND_HISTORY\fP
+(bash compatibility)
+.TP
+\fBHIST_EXPAND\fP
+\fBBANG_HIST\fP
+(bash compatibility)
+.TP
+\fBLOG\fP
+\fINO_\fP\fBHIST_NO_FUNCTIONS\fP
+(ksh compatibility)
+.TP
+\fBMAIL_WARN\fP
+\fBMAIL_WARNING\fP
+(bash compatibility)
+.TP
+\fBONE_CMD\fP
+\fBSINGLE_COMMAND\fP
+(bash compatibility)
+.TP
+\fBPHYSICAL\fP
+\fBCHASE_LINKS\fP
+(ksh and bash compatibility)
+.TP
+\fBPROMPT_VARS\fP
+\fBPROMPT_SUBST\fP
+(bash compatibility)
+.TP
+\fBSTDIN\fP
+\fBSHIN_STDIN\fP
+(ksh compatibility)
+.TP
+\fBTRACK_ALL\fP
+\fBHASH_CMDS\fP
+(ksh compatibility)
+.SH "SINGLE LETTER OPTIONS"
+.SS "Default set"
+.PD 0
+.TP
+\fB\-0\fP
+CORRECT
+.TP
+\fB\-1\fP
+PRINT_EXIT_VALUE
+.TP
+\fB\-2\fP
+\fINO_\fPBAD_PATTERN
+.TP
+\fB\-3\fP
+\fINO_\fPNOMATCH
+.TP
+\fB\-4\fP
+GLOB_DOTS
+.TP
+\fB\-5\fP
+NOTIFY
+.TP
+\fB\-6\fP
+BG_NICE
+.TP
+\fB\-7\fP
+IGNORE_EOF
+.TP
+\fB\-8\fP
+MARK_DIRS
+.TP
+\fB\-9\fP
+AUTO_LIST
+.TP
+\fB\-B\fP
+\fINO_\fPBEEP
+.TP
+\fB\-C\fP
+\fINO_\fPCLOBBER
+.TP
+\fB\-D\fP
+PUSHD_TO_HOME
+.TP
+\fB\-E\fP
+PUSHD_SILENT
+.TP
+\fB\-F\fP
+\fINO_\fPGLOB
+.TP
+\fB\-G\fP
+NULL_GLOB
+.TP
+\fB\-H\fP
+RM_STAR_SILENT
+.TP
+\fB\-I\fP
+IGNORE_BRACES
+.TP
+\fB\-J\fP
+AUTO_CD
+.TP
+\fB\-K\fP
+\fINO_\fPBANG_HIST
+.TP
+\fB\-L\fP
+SUN_KEYBOARD_HACK
+.TP
+\fB\-M\fP
+SINGLE_LINE_ZLE
+.TP
+\fB\-N\fP
+AUTO_PUSHD
+.TP
+\fB\-O\fP
+CORRECT_ALL
+.TP
+\fB\-P\fP
+RC_EXPAND_PARAM
+.TP
+\fB\-Q\fP
+PATH_DIRS
+.TP
+\fB\-R\fP
+LONG_LIST_JOBS
+.TP
+\fB\-S\fP
+REC_EXACT
+.TP
+\fB\-T\fP
+CDABLE_VARS
+.TP
+\fB\-U\fP
+MAIL_WARNING
+.TP
+\fB\-V\fP
+\fINO_\fPPROMPT_CR
+.TP
+\fB\-W\fP
+AUTO_RESUME
+.TP
+\fB\-X\fP
+LIST_TYPES
+.TP
+\fB\-Y\fP
+MENU_COMPLETE
+.TP
+\fB\-Z\fP
+ZLE
+.TP
+\fB\-a\fP
+ALL_EXPORT
+.TP
+\fB\-e\fP
+ERR_EXIT
+.TP
+\fB\-f\fP
+\fINO_\fPRCS
+.TP
+\fB\-g\fP
+HIST_IGNORE_SPACE
+.TP
+\fB\-h\fP
+HIST_IGNORE_DUPS
+.TP
+\fB\-i\fP
+INTERACTIVE
+.TP
+\fB\-k\fP
+INTERACTIVE_COMMENTS
+.TP
+\fB\-l\fP
+LOGIN
+.TP
+\fB\-m\fP
+MONITOR
+.TP
+\fB\-n\fP
+\fINO_\fPEXEC
+.TP
+\fB\-p\fP
+PRIVILEGED
+.TP
+\fB\-r\fP
+RESTRICTED
+.TP
+\fB\-s\fP
+SHIN_STDIN
+.TP
+\fB\-t\fP
+SINGLE_COMMAND
+.TP
+\fB\-u\fP
+\fINO_\fPUNSET
+.TP
+\fB\-v\fP
+VERBOSE
+.TP
+\fB\-w\fP
+CHASE_LINKS
+.TP
+\fB\-x\fP
+XTRACE
+.TP
+\fB\-y\fP
+SH_WORD_SPLIT
+.PD
+.SS "sh/ksh emulation set"
+.PD 0
+.TP
+\fB\-C\fP
+\fINO_\fPCLOBBER
+.TP
+\fB\-T\fP
+TRAPS_ASYNC
+.TP
+\fB\-X\fP
+MARK_DIRS
+.TP
+\fB\-a\fP
+ALL_EXPORT
+.TP
+\fB\-b\fP
+NOTIFY
+.TP
+\fB\-e\fP
+ERR_EXIT
+.TP
+\fB\-f\fP
+\fINO_\fPGLOB
+.TP
+\fB\-i\fP
+INTERACTIVE
+.TP
+\fB\-l\fP
+LOGIN
+.TP
+\fB\-m\fP
+MONITOR
+.TP
+\fB\-n\fP
+\fINO_\fPEXEC
+.TP
+\fB\-p\fP
+PRIVILEGED
+.TP
+\fB\-r\fP
+RESTRICTED
+.TP
+\fB\-s\fP
+SHIN_STDIN
+.TP
+\fB\-t\fP
+SINGLE_COMMAND
+.TP
+\fB\-u\fP
+\fINO_\fPUNSET
+.TP
+\fB\-v\fP
+VERBOSE
+.TP
+\fB\-x\fP
+XTRACE
+.PD
+.SS "Also note"
+.PD 0
+.TP
+\fB\-A\fP
+Used by \fBset\fP for setting arrays
+.TP
+\fB\-b\fP
+Used on the command line to specify end of option processing
+.TP
+\fB\-c\fP
+Used on the command line to specify a single command
+.TP
+\fB\-m\fP
+Used by \fBsetopt\fP for pattern\-matching option setting
+.TP
+\fB\-o\fP
+Used in all places to allow use of long option names
+.TP
+\fB\-s\fP
+Used by \fBset\fP to sort positional parameters
+.PD
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshparam.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshparam.1
@@ -0,0 +1,1208 @@
+.TH "ZSHPARAM" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshparam \- zsh parameters
+.\" Yodl file: Zsh/params.yo
+.SH "DESCRIPTION"
+A parameter has a name, a value, and a number of attributes\&.
+A name may be any sequence of alphanumeric
+characters and underscores, or the single characters
+`\fB*\fP', `\fB@\fP', `\fB#\fP', `\fB?\fP', `\fB\-\fP', `\fB$\fP', or `\fB!\fP'\&.
+The value may be a \fIscalar\fP (a string),
+an integer, an array (indexed numerically), or an \fIassociative\fP
+array (an unordered set of name\-value pairs, indexed by name)\&.  To declare
+the type of a parameter, or to assign a scalar or integer value to a
+parameter, use the \fBtypeset\fP builtin\&.
+.PP
+The value of a scalar or integer parameter may also be assigned by
+writing:
+.PP
+.RS
+.nf
+\fIname\fP\fB=\fP\fIvalue\fP
+.fi
+.RE
+.PP
+If the integer attribute, \fB\-i\fP, is set for \fIname\fP, the \fIvalue\fP
+is subject to arithmetic evaluation\&.  Furthermore, by replacing `\fB=\fP'
+with `\fB+=\fP', a parameter can be added or appended to\&.  See
+the section `Array Parameters' for additional forms of assignment\&.
+.PP
+To refer to the value of a parameter, write `\fB$\fP\fIname\fP' or
+`\fB${\fP\fIname\fP\fB}\fP'\&.  See
+\fIParameter Expansion\fP in \fIzshexpn\fP(1)
+for complete details\&.
+.PP
+In the parameter lists that follow, the mark `<S>' indicates that the
+parameter is special\&.
+Special parameters cannot have their type changed or their
+readonly attribute turned off, and if a special parameter is unset, then
+later recreated, the special properties will be retained\&.  `<Z>' indicates
+that the parameter does not exist when the shell initializes in \fBsh\fP or
+\fBksh\fP emulation mode\&.
+.SH "ARRAY PARAMETERS"
+To assign an array value, write one of:
+.PP
+.RS
+.nf
+\fBset \-A\fP \fIname\fP \fIvalue\fP \&.\&.\&.
+.fi
+.RE
+.RS
+.nf
+\fIname\fP\fB=(\fP\fIvalue\fP \&.\&.\&.\fB)\fP
+.fi
+.RE
+.PP
+If no parameter \fIname\fP exists, an ordinary array parameter is created\&.
+If the parameter \fIname\fP exists and is a scalar, it is replaced by a new
+array\&.  Ordinary array parameters may also be explicitly declared with:
+.PP
+.RS
+.nf
+\fBtypeset \-a\fP \fIname\fP
+.fi
+.RE
+.PP
+Associative arrays \fImust\fP be declared before assignment, by using:
+.PP
+.RS
+.nf
+\fBtypeset \-A\fP \fIname\fP
+.fi
+.RE
+.PP
+When \fIname\fP refers to an associative array, the list in an assignment
+is interpreted as alternating keys and values:
+.PP
+.RS
+.nf
+set \-A \fIname\fP \fIkey\fP \fIvalue\fP \&.\&.\&.
+.fi
+.RE
+.RS
+.nf
+\fIname\fP\fB=(\fP\fIkey\fP \fIvalue\fP \&.\&.\&.\fB)\fP
+.fi
+.RE
+.PP
+Every \fIkey\fP must have a \fIvalue\fP in this case\&.  Note that this
+assigns to the entire array, deleting any elements that do not appear
+in the list\&.
+.PP
+To create an empty array (including associative arrays), use one of:
+.PP
+.RS
+.nf
+\fBset \-A\fP \fIname\fP
+.fi
+.RE
+.RS
+.nf
+\fIname\fP\fB=()\fP
+.fi
+.RE
+.PP
+.SS "Array Subscripts"
+.PP
+Individual elements of an array may be selected using a subscript\&.  A
+subscript of the form `\fB[\fP\fIexp\fP\fB]\fP' selects the single element
+\fIexp\fP, where \fIexp\fP is an arithmetic expression which will be subject
+to arithmetic expansion as if it were surrounded by
+`\fB$((\fP\&.\&.\&.\fB))\fP'\&.  The elements are numbered
+beginning with 1, unless the \fBKSH_ARRAYS\fP option is set in which case
+they are numbered from zero\&.
+.PP
+Subscripts may be used inside braces used to delimit a parameter name, thus
+`\fB${foo[2]}\fP' is equivalent to `\fB$foo[2]\fP'\&.  If the \fBKSH_ARRAYS\fP
+option is set, the braced form is the only one that works, as bracketed
+expressions otherwise are not treated as subscripts\&.
+.PP
+The same subscripting syntax is used for associative arrays, except that
+no arithmetic expansion is applied to \fIexp\fP\&.  However, the parsing
+rules for arithmetic expressions still apply, which affects the way that
+certain special characters must be protected from interpretation\&.  See
+\fISubscript Parsing\fP below for details\&.
+.PP
+A subscript of the form `\fB[*]\fP' or `\fB[@]\fP' evaluates to all elements
+of an array; there is no difference between the two except when they
+appear within double quotes\&.
+`\fB"$foo[*]"\fP' evaluates to `\fB"$foo[1] $foo[2] \fP\&.\&.\&.\fB"\fP', whereas
+`\fB"$foo[@]"\fP' evaluates to `\fB"$foo[1]" "$foo[2]" \fP\&.\&.\&.'\&.  For
+associative arrays, `\fB[*]\fP' or `\fB[@]\fP' evaluate to all the values,
+in no particular order\&.  Note that this does not substitute
+the keys; see the documentation for the `\fBk\fP' flag under
+\fIParameter Expansion Flags\fP in \fIzshexpn\fP(1)
+for complete details\&.
+When an array parameter is referenced as `\fB$\fP\fIname\fP' (with no
+subscript) it evaluates to `\fB$\fP\fIname\fP\fB[*]\fP', unless the \fBKSH_ARRAYS\fP
+option is set in which case it evaluates to `\fB${\fP\fIname\fP\fB[0]}\fP' (for
+an associative array, this means the value of the key `\fB0\fP', which may
+not exist even if there are values for other keys)\&.
+.PP
+A subscript of the form `\fB[\fP\fIexp1\fP\fB,\fP\fIexp2\fP\fB]\fP'
+selects all elements in the range \fIexp1\fP to \fIexp2\fP,
+inclusive\&. (Associative arrays are unordered, and so do not support
+ranges\&.) If one of the subscripts evaluates to a negative number,
+say \fB\-\fP\fIn\fP, then the \fIn\fPth element from the end
+of the array is used\&.  Thus `\fB$foo[\-3]\fP' is the third element
+from the end of the array \fBfoo\fP, and
+`\fB$foo[1,\-1]\fP' is the same as `\fB$foo[*]\fP'\&.
+.PP
+Subscripting may also be performed on non\-array values, in which
+case the subscripts specify a substring to be extracted\&.
+For example, if \fBFOO\fP is set to `\fBfoobar\fP', then
+`\fBecho $FOO[2,5]\fP' prints `\fBooba\fP'\&.
+.PP
+.SS "Array Element Assignment"
+.PP
+A subscript may be used on the left side of an assignment like so:
+.PP
+.RS
+.nf
+\fIname\fP\fB[\fP\fIexp\fP\fB]=\fP\fIvalue\fP
+.fi
+.RE
+.PP
+In this form of assignment the element or range specified by \fIexp\fP
+is replaced by the expression on the right side\&.  An array (but not an
+associative array) may be created by assignment to a range or element\&.
+Arrays do not nest, so assigning a parenthesized list of values to an
+element or range changes the number of elements in the array, shifting the
+other elements to accommodate the new values\&.  (This is not supported for
+associative arrays\&.)
+.PP
+This syntax also works as an argument to the \fBtypeset\fP command:
+.PP
+.RS
+.nf
+\fBtypeset\fP \fB"\fP\fIname\fP\fB[\fP\fIexp\fP\fB]"=\fP\fIvalue\fP
+.fi
+.RE
+.PP
+The \fIvalue\fP may \fInot\fP be a parenthesized list in this case; only
+single\-element assignments may be made with \fBtypeset\fP\&.  Note that quotes
+are necessary in this case to prevent the brackets from being interpreted
+as filename generation operators\&.  The \fBnoglob\fP precommand modifier
+could be used instead\&.
+.PP
+To delete an element of an ordinary array, assign `\fB()\fP' to
+that element\&.  To delete an element of an associative array, use the
+\fBunset\fP command:
+.PP
+.RS
+.nf
+\fBunset\fP \fB"\fP\fIname\fP\fB[\fP\fIexp\fP\fB]"\fP
+.fi
+.RE
+.PP
+.SS "Subscript Flags"
+.PP
+If the opening bracket, or the comma in a range, in any subscript
+expression is directly followed by an opening parenthesis, the string up
+to the matching closing one is considered to be a list of flags, as in
+`\fIname\fP\fB[(\fP\fIflags\fP\fB)\fP\fIexp\fP\fB]\fP'\&.  The flags
+currently understood are:
+.PP
+.PD 0
+.TP
+.PD
+\fBw\fP
+If the parameter subscripted is a scalar than this flag makes
+subscripting work on words instead of characters\&.  The default word
+separator is whitespace\&.
+.TP
+\fBs:\fP\fIstring\fP\fB:\fP
+This gives the \fIstring\fP that separates words (for use with the
+\fBw\fP flag)\&.
+.TP
+\fBp\fP
+Recognize the same escape sequences as the \fBprint\fP builtin in
+the string argument of a subsequent `\fBs\fP' flag\&.
+.TP
+\fBf\fP
+If the parameter subscripted is a scalar than this flag makes
+subscripting work on lines instead of characters, i\&.e\&. with elements
+separated by newlines\&.  This is a shorthand for `\fBpws:\en:\fP'\&.
+.TP
+\fBr\fP
+Reverse subscripting: if this flag is given, the \fIexp\fP is taken as a
+pattern and the result is the first matching array element, substring or
+word (if the parameter is an array, if it is a scalar, or if it is a
+scalar and the `\fBw\fP' flag is given, respectively)\&.  The subscript used
+is the number of the matching element, so that pairs of subscripts such as
+`\fB$foo[(r)\fP\fI??\fP\fB,3]\fP' and `\fB$foo[(r)\fP\fI??\fP\fB,(r)f*]\fP' are
+possible if the parameter is not an associative array\&.  If the
+parameter is an associative array, only the value part of each pair is
+compared to the pattern, and the result is that value\&.
+.TP
+\fBR\fP
+Like `\fBr\fP', but gives the last match\&.  For associative arrays, gives
+all possible matches\&. May be used for assigning to ordinary array
+elements, but not for assigning to associative arrays\&.
+.TP
+\fBi\fP
+Like `\fBr\fP', but gives the index of the match instead; this may not be
+combined with a second argument\&.  On the left side of an assignment,
+behaves like `\fBr\fP'\&.  For associative arrays, the key part of each pair
+is compared to the pattern, and the first matching key found is the
+result\&.
+.TP
+\fBI\fP
+Like `\fBi\fP', but gives the index of the last match, or all possible
+matching keys in an associative array\&.
+.TP
+\fBk\fP
+If used in a subscript on an associative array, this flag causes the keys
+to be interpreted as patterns, and returns the value for the first key
+found where \fIexp\fP is matched by the key\&.  This flag does not work on
+the left side of an assignment to an associative array element\&.  If used
+on another type of parameter, this behaves like `\fBr\fP'\&.
+.TP
+\fBK\fP
+On an associative array this is like `\fBk\fP' but returns all values where
+\fIexp\fP is matched by the keys\&.  On other types of parameters this has
+the same effect as `\fBR\fP'\&.
+.TP
+\fBn:\fP\fIexpr\fP\fB:\fP
+If combined with `\fBr\fP', `\fBR\fP', `\fBi\fP' or `\fBI\fP', makes them give
+the \fIn\fPth or \fIn\fPth last match (if \fIexpr\fP evaluates to
+\fIn\fP)\&.  This flag is ignored when the array is associative\&.
+.TP
+\fBb:\fP\fIexpr\fP\fB:\fP
+If combined with `\fBr\fP', `\fBR\fP', `\fBi\fP' or `\fBI\fP', makes them begin
+at the \fIn\fPth or \fIn\fPth last element, word, or character (if \fIexpr\fP
+evaluates to \fIn\fP)\&.  This flag is ignored when the array is associative\&.
+.TP
+\fBe\fP
+This flag has no effect and for ordinary arrays is retained for backward
+compatibility only\&.  For associative arrays, this flag can be used to
+force \fB*\fP or \fB@\fP to be interpreted as a single key rather than as a
+reference to all values\&.  This flag may be used on the left side of an
+assignment\&.
+.PP
+See \fIParameter Expansion Flags\fP (\fIzshexpn\fP(1)) for additional ways to manipulate the results of array subscripting\&.
+.PP
+.SS "Subscript Parsing"
+.PP
+This discussion applies mainly to associative array key strings and to
+patterns used for reverse subscripting (the `\fBr\fP', `\fBR\fP', `\fBi\fP',
+etc\&. flags), but it may also affect parameter substitutions that appear
+as part of an arithmetic expression in an ordinary subscript\&.
+.PP
+It is possible to avoid the use of subscripts in assignments to associative
+array elements by using the syntax:
+.PP
+.RS
+.nf
+\fB
+   aa+=('key with "*strange*" characters' 'value string')
+\fP
+.fi
+.RE
+.PP
+This adds a new key/value pair if the key is not already present, and
+replaces the value for the existing key if it is\&.
+.PP
+The basic rule to remember when writing a subscript expression is that all
+text between the opening `\fB[\fP' and the closing `\fB]\fP' is interpreted
+\fIas if\fP it were in double quotes (see \fIzshmisc\fP(1))\&.  However, unlike double quotes which normally cannot nest, subscript
+expressions may appear inside double\-quoted strings or inside other
+subscript expressions (or both!), so the rules have two important
+differences\&.
+.PP
+The first difference is that brackets (`\fB[\fP' and `\fB]\fP') must appear as
+balanced pairs in a subscript expression unless they are preceded by a
+backslash (`\fB\e\fP')\&.  Therefore, within a subscript expression (and unlike
+true double\-quoting) the sequence `\fB\e[\fP' becomes `\fB[\fP', and similarly
+`\fB\e]\fP' becomes `\fB]\fP'\&.  This applies even in cases where a backslash is
+not normally required; for example, the pattern `\fB[^[]\fP' (to match any
+character other than an open bracket) should be written `\fB[^\e[]\fP' in a
+reverse\-subscript pattern\&.  However, note that `\fB\e[^\e[\e]\fP' and even
+`\fB\e[^[]\fP' mean the \fIsame\fP thing, because backslashes are always
+stripped when they appear before brackets!
+.PP
+The same rule applies to parentheses (`\fB(\fP' and `\fB)\fP') and
+braces (`\fB{\fP' and `\fB}\fP'): they must appear either in balanced pairs or
+preceded by a backslash, and backslashes that protect parentheses or
+braces are removed during parsing\&.  This is because parameter expansions
+may be surrounded balanced braces, and subscript flags are introduced by
+balanced parenthesis\&.
+.PP
+The second difference is that a double\-quote (`\fB"\fP') may appear as part
+of a subscript expression without being preceded by a backslash, and
+therefore that the two characters `\fB\e"\fP' remain as two characters in the
+subscript (in true double\-quoting, `\fB\e"\fP' becomes `\fB"\fP')\&.  However,
+because of the standard shell quoting rules, any double\-quotes that appear
+must occur in balanced pairs unless preceded by a backslash\&.  This makes
+it more difficult to write a subscript expression that contains an odd
+number of double\-quote characters, but the reason for this difference is
+so that when a subscript expression appears inside true double\-quotes, one
+can still write `\fB\e"\fP' (rather than `\fB\e\e\e"\fP') for `\fB"\fP'\&.
+.PP
+To use an odd number of double quotes as a key in an assignment, use the
+\fBtypeset\fP builtin and an enclosing pair of double quotes; to refer to
+the value of that key, again use double quotes:
+.PP
+.RS
+.nf
+\fBtypeset \-A aa
+typeset "aa[one\e"two\e"three\e"quotes]"=QQQ
+print "$aa[one\e"two\e"three\e"quotes]"\fP
+.fi
+.RE
+.PP
+It is important to note that the quoting rules do not change when a
+parameter expansion with a subscript is nested inside another subscript
+expression\&.  That is, it is not necessary to use additional backslashes
+within the inner subscript expression; they are removed only once, from
+the innermost subscript outwards\&.  Parameters are also expanded from the
+innermost subscript first, as each expansion is encountered left to right
+in the outer expression\&.
+.PP
+A further complication arises from a way in which subscript parsing is
+\fInot\fP different from double quote parsing\&.  As in true double\-quoting,
+the sequences `\fB\e*\fP', and `\fB\e@\fP' remain as two characters when they
+appear in a subscript expression\&.  To use a literal `\fB*\fP' or `\fB@\fP' as
+an associative array key, the `\fBe\fP' flag must be used:
+.PP
+.RS
+.nf
+\fBtypeset \-A aa
+aa[(e)*]=star
+print $aa[(e)*]\fP
+.fi
+.RE
+.PP
+A last detail must be considered when reverse subscripting is performed\&.
+Parameters appearing in the subscript expression are first expanded and
+then the complete expression is interpreted as a pattern\&.  This has two
+effects: first, parameters behave as if \fBGLOB_SUBST\fP were on (and it
+cannot be turned off); second, backslashes are interpreted twice, once
+when parsing the array subscript and again when parsing the pattern\&.  In a
+reverse subscript, it's necessary to use \fIfour\fP backslashes to cause a
+single backslash to match literally in the pattern\&.  For complex patterns,
+it is often easiest to assign the desired pattern to a parameter and then
+refer to that parameter in the subscript, because then the backslashes,
+brackets, parentheses, etc\&., are seen only when the complete expression is
+converted to a pattern\&.  To match the value of a parameter literally in a
+reverse subscript, rather than as a pattern,
+use `\fB${(q\fP\fB)\fP\fIname\fP\fB}\fP' (see \fIzshexpn\fP(1)) to quote the expanded value\&.
+.PP
+Note that the `\fBk\fP' and `\fBK\fP' flags are reverse subscripting for an
+ordinary array, but are \fInot\fP reverse subscripting for an associative
+array!  (For an associative array, the keys in the array itself are
+interpreted as patterns by those flags; the subscript is a plain string
+in that case\&.)
+.PP
+One final note, not directly related to subscripting: the numeric names
+of positional parameters (described below) are parsed specially, so for example `\fB$2foo\fP' is equivalent to
+`\fB${2}foo\fP'\&.  Therefore, to use subscript syntax to extract a substring
+from a positional parameter, the expansion must be surrounded by braces;
+for example, `\fB${2[3,5]}\fP' evaluates to the third through fifth
+characters of the second positional parameter, but `\fB$2[3,5]\fP' is the
+entire second parameter concatenated with the filename generation pattern
+`\fB[3,5]\fP'\&.
+.PP
+.SH "POSITIONAL PARAMETERS"
+The positional parameters provide access to the command\-line arguments
+of a shell function, shell script, or the shell itself; see
+the section `Invocation', and also the section `Functions'\&.
+The parameter \fIn\fP, where \fIn\fP is a number,
+is the \fIn\fPth positional parameter\&.
+The parameters \fB*\fP, \fB@\fP and \fBargv\fP are
+arrays containing all the positional parameters;
+thus `\fB$argv[\fP\fIn\fP\fB]\fP', etc\&., is equivalent to simply `\fB$\fP\fIn\fP'\&.
+.PP
+Positional parameters may be changed after the shell or function starts by
+using the \fBset\fP builtin, by assigning to the \fBargv\fP array, or by direct
+assignment of the form `\fIn\fP\fB=\fP\fIvalue\fP' where \fIn\fP is the number of
+the positional parameter to be changed\&.  This also creates (with empty
+values) any of the positions from 1 to \fIn\fP that do not already have
+values\&.  Note that, because the positional parameters form an array, an
+array assignment of the form `\fIn\fP\fB=(\fP\fIvalue\fP \&.\&.\&.\fB)\fP' is
+allowed, and has the effect of shifting all the values at positions greater
+than \fIn\fP by as many positions as necessary to accommodate the new values\&.
+.PP
+.SH "LOCAL PARAMETERS"
+Shell function executions delimit scopes for shell parameters\&.
+(Parameters are dynamically scoped\&.)  The \fBtypeset\fP builtin, and its
+alternative forms \fBdeclare\fP, \fBinteger\fP, \fBlocal\fP and \fBreadonly\fP
+(but not \fBexport\fP), can be used to declare a parameter as being local
+to the innermost scope\&.
+.PP
+When a parameter is read or assigned to, the
+innermost existing parameter of that name is used\&.  (That is, the
+local parameter hides any less\-local parameter\&.)  However, assigning
+to a non\-existent parameter, or declaring a new parameter with \fBexport\fP,
+causes it to be created in the \fIouter\fPmost scope\&.
+.PP
+Local parameters disappear when their scope ends\&.
+\fBunset\fP can be used to delete a parameter while it is still in scope;
+any outer parameter of the same name remains hidden\&.
+.PP
+Special parameters may also be made local; they retain their special
+attributes unless either the existing or the newly\-created parameter
+has the \fB\-h\fP (hide) attribute\&.  This may have unexpected effects:
+there is no default value, so if there is no assignment at the
+point the variable is made local, it will be set to an empty value (or zero
+in the case of integers)\&.  
+The following:
+.PP
+.RS
+.nf
+\fBtypeset PATH=/new/directory:$PATH\fP
+.fi
+.RE
+.PP
+is valid for temporarily allowing the shell or programmes called from it to
+find the programs in \fB/new/directory\fP inside a function\&.
+.PP
+Note that the restriction in older versions of zsh that local parameters
+were never exported has been removed\&.
+.PP
+.SH "PARAMETERS SET BY THE SHELL"
+The following parameters are automatically set by the shell:
+.PP
+.PD 0
+.TP
+.PD
+\fB!\fP <S>
+The process ID of the last background command invoked\&.
+.TP
+\fB#\fP <S>
+The number of positional parameters in decimal\&.  Note that some confusion
+may occur with the syntax \fB$#\fP\fIparam\fP which substitutes the length of
+\fIparam\fP\&.  Use \fB${#}\fP to resolve ambiguities\&.  In particular, the
+sequence `\fB$#\-\fP\fI\&.\&.\&.\fP' in an arithmetic expression is interpreted as
+the length of the parameter \fB\-\fP, q\&.v\&.
+.TP
+\fBARGC\fP <S> <Z>
+Same as \fB#\fP\&.
+.TP
+\fB$\fP <S>
+The process ID of this shell\&.
+.TP
+\fB\-\fP <S>
+Flags supplied to the shell on invocation or by the \fBset\fP
+or \fBsetopt\fP commands\&.
+.TP
+\fB*\fP <S>
+An array containing the positional parameters\&.
+.TP
+\fBargv\fP <S> <Z>
+Same as \fB*\fP\&.  Assigning to \fBargv\fP changes the local positional
+parameters, but \fBargv\fP is \fInot\fP itself a local parameter\&.
+Deleting \fBargv\fP with \fBunset\fP in any function deletes it everywhere,
+although only the innermost positional parameter array is deleted (so
+\fB*\fP and \fB@\fP in other scopes are not affected)\&.
+.TP
+\fB@\fP <S>
+Same as \fBargv[@]\fP, even when \fBargv\fP is not set\&.
+.TP
+\fB?\fP <S>
+The exit value returned by the last command\&.
+.TP
+\fB0\fP <S>
+The name used to invoke the current shell\&.  If the \fBFUNCTION_ARGZERO\fP option
+is set, this is set temporarily within a shell function to the name of the
+function, and within a sourced script to the name of the script\&.
+.TP
+\fBstatus\fP <S> <Z>
+Same as \fB?\fP\&.
+.TP
+\fBpipestatus\fP <S> <Z>
+An array containing the exit values returned by all commands in the
+last pipeline\&.
+.TP
+\fB_\fP <S>
+The last argument of the previous command\&.
+Also, this parameter is set in the environment of every command
+executed to the full pathname of the command\&.
+.TP
+\fBCPUTYPE\fP
+The machine type (microprocessor class or machine model),
+as determined at run time\&.
+.TP
+\fBEGID\fP <S>
+The effective group ID of the shell process\&.  If you have sufficient
+privileges, you may change the effective group ID of the shell
+process by assigning to this parameter\&.  Also (assuming sufficient
+privileges), you may start a single command with a different
+effective group ID by `\fB(EGID=\fP\fIgid\fP\fB; command)\fP'
+.TP
+\fBEUID\fP <S>
+The effective user ID of the shell process\&.  If you have sufficient
+privileges, you may change the effective user ID of the shell process
+by assigning to this parameter\&.  Also (assuming sufficient privileges),
+you may start a single command with a different
+effective user ID by `\fB(EUID=\fP\fIuid\fP\fB; command)\fP'
+.TP
+\fBERRNO\fP <S>
+The value of errno (see \fIerrno\fP(3))
+as set by the most recently failed system call\&.
+This value is system dependent and is intended for debugging
+purposes\&.  It is also useful with the \fBzsh/system\fP module which
+allows the number to be turned into a name or message\&.
+.TP
+\fBGID\fP <S>
+The real group ID of the shell process\&.  If you have sufficient privileges,
+you may change the group ID of the shell process by assigning to this
+parameter\&.  Also (assuming sufficient privileges), you may start a single
+command under a different
+group ID by `\fB(GID=\fP\fIgid\fP\fB; command)\fP'
+.TP
+\fBHISTCMD\fP
+The current history line number in an interactive shell, in other
+words the line number for the command that caused \fB$HISTCMD\fP
+to be read\&.
+.TP
+\fBHOST\fP
+The current hostname\&.
+.TP
+\fBLINENO\fP <S>
+The line number of the current line within the current script, sourced
+file, or shell function being executed, whichever was started most
+recently\&.  Note that in the case of shell functions the line
+number refers to the function as it appeared in the original definition,
+not necessarily as displayed by the \fBfunctions\fP builtin\&.
+.TP
+\fBLOGNAME\fP
+If the corresponding variable is not set in the environment of the
+shell, it is initialized to the login name corresponding to the
+current login session\&. This parameter is exported by default but
+this can be disabled using the \fBtypeset\fP builtin\&.
+.TP
+\fBMACHTYPE\fP
+The machine type (microprocessor class or machine model),
+as determined at compile time\&.
+.TP
+\fBOLDPWD\fP
+The previous working directory\&.  This is set when the shell initializes
+and whenever the directory changes\&.
+.TP
+\fBOPTARG\fP <S>
+The value of the last option argument processed by the \fBgetopts\fP
+command\&.
+.TP
+\fBOPTIND\fP <S>
+The index of the last option argument processed by the \fBgetopts\fP
+command\&.
+.TP
+\fBOSTYPE\fP
+The operating system, as determined at compile time\&.
+.TP
+\fBPPID\fP <S>
+The process ID of the parent of the shell\&.
+.TP
+\fBPWD\fP
+The present working directory\&.  This is set when the shell initializes
+and whenever the directory changes\&.
+.TP
+\fBRANDOM\fP <S>
+A pseudo\-random integer from 0 to 32767, newly generated each time
+this parameter is referenced\&.  The random number generator
+can be seeded by assigning a numeric value to \fBRANDOM\fP\&.
+.RS
+.PP
+The values of \fBRANDOM\fP form an intentionally\-repeatable pseudo\-random
+sequence; subshells that reference \fBRANDOM\fP will result
+in identical pseudo\-random values unless the value of \fBRANDOM\fP is
+referenced or seeded in the parent shell in between subshell invocations\&.
+.RE
+.TP
+\fBSECONDS\fP <S>
+The number of seconds since shell invocation\&.  If this parameter
+is assigned a value, then the value returned upon reference
+will be the value that was assigned plus the number of seconds
+since the assignment\&.
+.RS
+.PP
+Unlike other special parameters, the type of the \fBSECONDS\fP parameter can
+be changed using the \fBtypeset\fP command\&.  Only integer and one of the
+floating point types are allowed\&.  For example, `\fBtypeset \-F SECONDS\fP'
+causes the value to be reported as a floating point number\&.  The precision
+is six decimal places, although not all places may be useful\&.
+.RE
+.TP
+\fBSHLVL\fP <S>
+Incremented by one each time a new shell is started\&.
+.TP
+\fBsignals\fP
+An array containing the names of the signals\&.
+.TP
+\fBTRY_BLOCK_ERROR\fP <S>
+In an \fBalways\fP block, indicates whether the preceding list of code
+caused an error\&.  The value is 1 to indicate an error, 0 otherwise\&.
+It may be reset, clearing the error condition\&.  See
+\fIComplex Commands\fP in \fIzshmisc\fP(1)
+.TP
+\fBTTY\fP
+The name of the tty associated with the shell, if any\&.
+.TP
+\fBTTYIDLE\fP <S>
+The idle time of the tty associated with the shell in seconds or \-1 if there
+is no such tty\&.
+.TP
+\fBUID\fP <S>
+The real user ID of the shell process\&.  If you have sufficient privileges,
+you may change the user ID of the shell by assigning to this parameter\&.
+Also (assuming sufficient privileges), you may start a single command
+under a different
+user ID by `\fB(UID=\fP\fIuid\fP\fB; command)\fP'
+.TP
+\fBUSERNAME\fP <S>
+The username corresponding to the real user ID of the shell process\&.  If you
+have sufficient privileges, you may change the username (and also the
+user ID and group ID) of the shell by assigning to this parameter\&.
+Also (assuming sufficient privileges), you may start a single command
+under a different username (and user ID and group ID)
+by `\fB(USERNAME=\fP\fIusername\fP\fB; command)\fP'
+.TP
+\fBVENDOR\fP
+The vendor, as determined at compile time\&.
+.TP
+\fBZSH_NAME\fP
+Expands to the basename of the command used to invoke this instance
+of zsh\&.
+.TP
+\fBZSH_VERSION\fP
+The version number of this zsh\&.
+.SH "PARAMETERS USED BY THE SHELL"
+The following parameters are used by the shell\&.
+.PP
+In cases where there are two parameters with an upper\- and lowercase
+form of the same name, such as \fBpath\fP and \fBPATH\fP, the lowercase form
+is an array and the uppercase form is a scalar with the elements of the
+array joined together by colons\&.  These are similar to tied parameters
+created via `\fBtypeset \-T\fP'\&.  The normal use for the colon\-separated
+form is for exporting to the environment, while the array form is easier
+to manipulate within the shell\&.  Note that unsetting either of the pair
+will unset the other; they retain their special properties when
+recreated, and recreating one of the pair will recreate the other\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBARGV0\fP
+If exported, its value is used as the \fBargv[0]\fP of external commands\&.
+Usually used in constructs like `\fBARGV0=emacs nethack\fP'\&.
+.TP
+\fBBAUD\fP
+The baud rate of the current connection\&.  Used by the line editor
+update mechanism to compensate for a slow terminal by delaying
+updates until necessary\&.  This may be profitably set to a lower value
+in some circumstances, e\&.g\&.
+for slow modems dialing into a communications server which is connected
+to a host via a fast link; in this case, this variable
+would be set by default to the speed of the fast link, and not
+the modem\&.
+This parameter should be set to the baud
+rate of the slowest part of the link for best performance\&. The compensation
+mechanism can be turned off by setting the variable to zero\&.
+.TP
+\fBcdpath\fP <S> <Z> (\fBCDPATH\fP <S>)
+An array (colon\-separated list)
+of directories specifying the search path for the \fBcd\fP command\&.
+.TP
+\fBCOLUMNS\fP <S>
+The number of columns for this terminal session\&.
+Used for printing select lists and for the line editor\&.
+.TP
+\fBDIRSTACKSIZE\fP
+The maximum size of the directory stack\&.  If the
+stack gets larger than this, it will be truncated automatically\&.
+This is useful with the \fBAUTO_PUSHD\fP option\&.
+.TP
+\fBENV\fP
+If the \fBENV\fP environment variable is set when zsh is invoked as \fBsh\fP
+or \fBksh\fP, \fB$ENV\fP is sourced after the profile scripts\&.  The value of
+\fBENV\fP is subjected to parameter expansion, command substitution, and
+arithmetic expansion before being interpreted as a pathname\&.  Note that
+\fBENV\fP is \fInot\fP used unless zsh is emulating \fBsh\fP or \fBksh\fP\&.
+.TP
+\fBFCEDIT\fP
+The default editor for the \fBfc\fP builtin\&.
+.TP
+\fBfignore\fP <S> <Z> (\fBFIGNORE\fP <S>)
+An array (colon separated list)
+containing the suffixes of files to be ignored
+during filename completion\&.  However, if completion only generates files
+with suffixes in this list, then these files are completed anyway\&.
+.TP
+\fBfpath\fP <S> <Z> (\fBFPATH\fP <S>)
+An array (colon separated list)
+of directories specifying the search path for
+function definitions\&.  This path is searched when a function
+with the \fB\-u\fP attribute is referenced\&.  If an executable
+file is found, then it is read and executed in the current environment\&.
+.TP
+\fBhistchars\fP <S>
+Three characters used by the shell's history and lexical analysis
+mechanism\&.  The first character signals the start of a history
+expansion (default `\fB!\fP')\&.  The second character signals the
+start of a quick history substitution (default `\fB^\fP')\&.  The third
+character is the comment character (default `\fB#\fP')\&.
+.TP
+\fBHISTCHARS\fP <S> <Z>
+Same as \fBhistchars\fP\&.  (Deprecated\&.)
+.TP
+\fBHISTFILE\fP
+The file to save the history in when an interactive shell exits\&.
+If unset, the history is not saved\&.
+.TP
+\fBHISTSIZE\fP <S>
+The maximum number of events stored in the internal history list\&.
+If you use the \fBHIST_EXPIRE_DUPS_FIRST\fP option, setting this value
+larger than the \fBSAVEHIST\fP size will give you the difference as a
+cushion for saving duplicated history events\&.
+.TP
+\fBHOME\fP <S>
+The default argument for the \fBcd\fP command\&.
+.TP
+\fBIFS\fP <S>
+Internal field separators (by default space, tab, newline and NUL), that
+are used to separate words which result from
+command or parameter expansion and words read by
+the \fBread\fP builtin\&.  Any characters from the set space, tab and
+newline that appear in the IFS are called \fIIFS white space\fP\&.
+One or more IFS white space characters or one non\-IFS white space
+character together with any adjacent IFS white space character delimit
+a field\&.  If an IFS white space character appears twice consecutively
+in the IFS, this character is treated as if it were not an IFS white
+space character\&.
+.TP
+\fBKEYTIMEOUT\fP
+The time the shell waits, in hundredths of seconds, for another key to
+be pressed when reading bound multi\-character sequences\&.
+.TP
+\fBLANG\fP <S>
+This variable determines the locale category for any category not
+specifically selected via a variable starting with `\fBLC_\fP'\&.
+.TP
+\fBLC_ALL\fP <S>
+This variable overrides the value of the `\fBLANG\fP' variable and the value
+of any of the other variables starting with `\fBLC_\fP'\&.
+.TP
+\fBLC_COLLATE\fP <S>
+This variable determines the locale category for character collation
+information within ranges in glob brackets and for sorting\&.
+.TP
+\fBLC_CTYPE\fP <S>
+This variable determines the locale category for character handling
+functions\&.
+.TP
+\fBLC_MESSAGES\fP <S>
+This variable determines the language in which messages should be
+written\&.  Note that zsh does not use message catalogs\&.
+.TP
+\fBLC_NUMERIC\fP <S>
+This variable affects the decimal point character and thousands
+separator character for the formatted input/output functions
+and string conversion functions\&.  Note that zsh ignores this
+setting when parsing floating point mathematical expressions\&.
+.TP
+\fBLC_TIME\fP <S>
+This variable determines the locale category for date and time
+formatting in prompt escape sequences\&.
+.TP
+\fBLINES\fP <S>
+The number of lines for this terminal session\&.
+Used for printing select lists and for the line editor\&.
+.TP
+\fBLISTMAX\fP
+In the line editor, the number of matches to list without asking
+first\&. If the value is negative, the list will be shown if it spans at 
+most as many lines as given by the absolute value\&.
+If set to zero, the shell asks only if the top of the listing would scroll
+off the screen\&.
+.TP
+\fBLOGCHECK\fP
+The interval in seconds between checks for login/logout activity
+using the \fBwatch\fP parameter\&.
+.TP
+\fBMAIL\fP
+If this parameter is set and \fBmailpath\fP is not set,
+the shell looks for mail in the specified file\&.
+.TP
+\fBMAILCHECK\fP
+The interval in seconds between checks for new mail\&.
+.TP
+\fBmailpath\fP <S> <Z> (\fBMAILPATH\fP <S>)
+An array (colon\-separated list) of filenames to check for
+new mail\&.  Each filename can be followed by a `\fB?\fP' and a
+message that will be printed\&.  The message will undergo
+parameter expansion, command substitution and arithmetic
+expansion with the variable \fB$_\fP defined as the name
+of the file that has changed\&.  The default message is
+`\fBYou have new mail\fP'\&.  If an element is a directory
+instead of a file the shell will recursively check every
+file in every subdirectory of the element\&.
+.TP
+\fBmanpath\fP <S> <Z> (\fBMANPATH\fP <S> <Z>)
+An array (colon\-separated list)
+whose value is not used by the shell\&.  The \fBmanpath\fP
+array can be useful, however, since setting it also sets
+\fBMANPATH\fP, and vice versa\&.
+.TP
+\fBmodule_path\fP <S> <Z> (\fBMODULE_PATH\fP <S>)
+An array (colon\-separated list)
+of directories that \fBzmodload\fP
+searches for dynamically loadable modules\&.
+This is initialized to a standard pathname,
+usually `\fB/usr/local/lib/zsh/$ZSH_VERSION\fP'\&.
+(The `\fB/usr/local/lib\fP' part varies from installation to installation\&.)
+For security reasons, any value set in the environment when the shell
+is started will be ignored\&.
+.RS
+.PP
+These parameters only exist if the installation supports dynamic
+module loading\&.
+.RE
+.TP
+\fBNULLCMD\fP <S>
+The command name to assume if a redirection is specified
+with no command\&.  Defaults to \fBcat\fP\&.  For \fBsh\fP/\fBksh\fP
+behavior, change this to \fB:\fP\&.  For \fBcsh\fP\-like
+behavior, unset this parameter; the shell will print an
+error message if null commands are entered\&.
+.TP
+\fBpath\fP <S> <Z> (\fBPATH\fP <S>)
+An array (colon\-separated list)
+of directories to search for commands\&.
+When this parameter is set, each directory is scanned
+and all files found are put in a hash table\&.
+.TP
+\fBPOSTEDIT\fP <S>
+This string is output whenever the line editor exits\&.
+It usually contains termcap strings to reset the terminal\&.
+.TP
+.PD 0
+\fBPROMPT\fP <S> <Z>
+.TP
+.PD 0
+\fBPROMPT2\fP <S> <Z>
+.TP
+.PD 0
+\fBPROMPT3\fP <S> <Z>
+.TP
+.PD
+\fBPROMPT4\fP <S> <Z>
+Same as \fBPS1\fP, \fBPS2\fP, \fBPS3\fP and \fBPS4\fP,
+respectively\&.
+.TP
+\fBprompt\fP <S> <Z>
+Same as \fBPS1\fP\&.
+.TP
+\fBPS1\fP <S>
+The primary prompt string, printed before a command is read\&.
+the default is `\fB%m%# \fP'\&.  It undergoes a special form of expansion
+before being displayed; see the section `Prompt Expansion'\&.
+.TP
+\fBPS2\fP <S>
+The secondary prompt, printed when the shell needs more information
+to complete a command\&.
+It is expanded in the same way as \fBPS1\fP\&.
+The default is `\fB%_> \fP', which displays any shell constructs or quotation
+marks which are currently being processed\&.
+.TP
+\fBPS3\fP <S>
+Selection prompt used within a \fBselect\fP loop\&.
+It is expanded in the same way as \fBPS1\fP\&.
+The default is `\fB?# \fP'\&.
+.TP
+\fBPS4\fP <S>
+The execution trace prompt\&.  Default is `\fB+%N:%i> \fP', which displays
+the name of the current shell structure and the line number within it\&.
+In sh or ksh emulation, the default is `\fB+ \fP'\&.
+.TP
+\fBpsvar\fP <S> <Z> (\fBPSVAR\fP <S>)
+An array (colon\-separated list) whose first nine values can be used in
+\fBPROMPT\fP strings\&.  Setting \fBpsvar\fP also sets \fBPSVAR\fP, and
+vice versa\&.
+.TP
+\fBREADNULLCMD\fP <S>
+The command name to assume if a single input redirection
+is specified with no command\&.  Defaults to \fBmore\fP\&.
+.TP
+\fBREPORTTIME\fP
+If nonnegative, commands whose combined user and system execution times
+(measured in seconds) are greater than this value have timing
+statistics printed for them\&.
+.TP
+\fBREPLY\fP
+This parameter is reserved by convention to pass string values between
+shell scripts and shell builtins in situations where a function call or
+redirection are impossible or undesirable\&.  The \fBread\fP builtin and the
+\fBselect\fP complex command may set \fBREPLY\fP, and filename generation both
+sets and examines its value when evaluating certain expressions\&.  Some
+modules also employ \fBREPLY\fP for similar purposes\&.
+.TP
+\fBreply\fP
+As \fBREPLY\fP, but for array values rather than strings\&.
+.TP
+.PD 0
+\fBRPROMPT\fP <S>
+.TP
+.PD
+\fBRPS1\fP <S>
+This prompt is displayed on the right\-hand side of the screen
+when the primary prompt is being displayed on the left\&.
+This does not work if the \fBSINGLELINEZLE\fP option is set\&.
+It is expanded in the same way as \fBPS1\fP\&.
+.TP
+.PD 0
+\fBRPROMPT2\fP <S>
+.TP
+.PD
+\fBRPS2\fP <S>
+This prompt is displayed on the right\-hand side of the screen
+when the secondary prompt is being displayed on the left\&.
+This does not work if the \fBSINGLELINEZLE\fP option is set\&.
+It is expanded in the same way as \fBPS2\fP\&.
+.TP
+\fBSAVEHIST\fP
+The maximum number of history events to save in the history file\&.
+.TP
+\fBSPROMPT\fP <S>
+The prompt used for spelling correction\&.  The sequence
+`\fB%R\fP' expands to the string which presumably needs spelling
+correction, and `\fB%r\fP' expands to the proposed correction\&.
+All other prompt escapes are also allowed\&.
+.TP
+\fBSTTY\fP
+If this parameter is set in a command's environment, the shell runs the
+\fBstty\fP command with the value of this parameter as arguments in order to
+set up the terminal before executing the command\&. The modes apply only to the
+command, and are reset when it finishes or is suspended\&. If the command is
+suspended and continued later with the \fBfg\fP or \fBwait\fP builtins it will
+see the modes specified by \fBSTTY\fP, as if it were not suspended\&.  This
+(intentionally) does not apply if the command is continued via `\fBkill
+\-CONT\fP'\&.  \fBSTTY\fP is ignored if the command is run in the background, or
+if it is in the environment of the shell but not explicitly assigned to in
+the input line\&. This avoids running stty at every external command by
+accidentally exporting it\&. Also note that \fBSTTY\fP should not be used for
+window size specifications; these will not be local to the command\&.
+.TP
+\fBTERM\fP <S>
+The type of terminal in use\&.  This is used when looking up termcap
+sequences\&.  An assignment to \fBTERM\fP causes zsh to re\-initialize the
+terminal, even if the value does not change (e\&.g\&., `\fBTERM=$TERM\fP')\&.  It
+is necessary to make such an assignment upon any change to the terminal
+definition database or terminal type in order for the new settings to
+take effect\&.
+.TP
+\fBTIMEFMT\fP
+The format of process time reports with the \fBtime\fP keyword\&.
+The default is `\fB%E real  %U user  %S system  %P %J\fP'\&.
+Recognizes the following escape sequences, although not all
+may be available on all systems, and some that are available
+may not be useful:
+.RS
+.PP
+.PD 0
+.TP
+\fB%%\fP
+A `\fB%\fP'\&.
+.TP
+\fB%U\fP
+CPU seconds spent in user mode\&.
+.TP
+\fB%S\fP
+CPU seconds spent in kernel mode\&.
+.TP
+\fB%E\fP
+Elapsed time in seconds\&.
+.TP
+\fB%P\fP
+The CPU percentage, computed as
+(100*\fB%U\fP+\fB%S\fP)/\fB%E\fP\&.
+.TP
+\fB%W\fP
+Number of times the process was swapped\&.
+.TP
+\fB%X\fP
+The average amount in (shared) text space used in Kbytes\&.
+.TP
+\fB%D\fP
+The average amount in (unshared) data/stack space used in
+Kbytes\&.
+.TP
+\fB%K\fP
+The total space used (%X+%D) in Kbytes\&.
+.TP
+\fB%M\fP
+The  maximum memory the process had in use at any time in
+Kbytes\&.
+.TP
+\fB%F\fP
+The number of major page faults (page needed to be brought
+from disk)\&.
+.TP
+\fB%R\fP
+The number of minor page faults\&.
+.TP
+\fB%I\fP
+The number of input operations\&.
+.TP
+\fB%O\fP
+The number of output operations\&.
+.TP
+\fB%r\fP
+The number of socket messages received\&.
+.TP
+\fB%s\fP
+The number of socket messages sent\&.
+.TP
+\fB%k\fP
+The number of signals received\&.
+.TP
+\fB%w\fP
+Number of voluntary context switches (waits)\&.
+.TP
+\fB%c\fP
+Number of involuntary context switches\&.
+.TP
+\fB%J\fP
+The name of this job\&.
+.PD
+.PP
+A star may be inserted between the percent sign and flags printing time\&.
+This cause the time to be printed in
+`\fIhh\fP\fB:\fP\fImm\fP\fB:\fP\fIss\fP\fB\&.\fP\fIttt\fP'
+format (hours and minutes are only printed if they are not zero)\&.
+.RE
+.TP
+\fBTMOUT\fP
+If this parameter is nonzero, the shell will receive an \fBALRM\fP
+signal if a command is not entered within the specified number of
+seconds after issuing a prompt\&. If there is a trap on \fBSIGALRM\fP, it
+will be executed and a new alarm is scheduled using the value of the
+\fBTMOUT\fP parameter after executing the trap\&.  If no trap is set, and
+the idle time of the terminal is not less than the value of the
+\fBTMOUT\fP parameter, zsh terminates\&.  Otherwise a new alarm is
+scheduled to \fBTMOUT\fP seconds after the last keypress\&.
+.TP
+\fBTMPPREFIX\fP
+A pathname prefix which the shell will use for all temporary files\&.
+Note that this should include an initial part for the file name as
+well as any directory names\&.  The default is `\fB/tmp/zsh\fP'\&.
+.TP
+\fBwatch\fP <S> <Z> (\fBWATCH\fP <S>)
+An array (colon\-separated list) of login/logout events to report\&.
+If it contains the single word `\fBall\fP', then all login/logout events
+are reported\&.  If it contains the single word `\fBnotme\fP', then all
+events are reported as with `\fBall\fP' except \fB$USERNAME\fP\&.
+An entry in this list may consist of a username,
+an `\fB@\fP' followed by a remote hostname,
+and a `\fB%\fP' followed by a line (tty)\&.
+Any or all of these components may be present in an entry;
+if a login/logout event matches all of them,
+it is reported\&.
+.TP
+\fBWATCHFMT\fP
+The format of login/logout reports if the \fBwatch\fP parameter is set\&.
+Default is `\fB%n has %a %l from %m\fP'\&.
+Recognizes the following escape sequences:
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fB%n\fP
+The name of the user that logged in/out\&.
+.TP
+\fB%a\fP
+The observed action, i\&.e\&. "logged on" or "logged off"\&.
+.TP
+\fB%l\fP
+The line (tty) the user is logged in on\&.
+.TP
+\fB%M\fP
+The full hostname of the remote host\&.
+.TP
+\fB%m\fP
+The hostname up to the first `\fB\&.\fP'\&.  If only the
+IP address is available or the utmp field contains
+the name of an X\-windows display, the whole name is printed\&.
+.RS
+.PP
+\fINOTE:\fP
+The `\fB%m\fP' and `\fB%M\fP' escapes will work only if there is a host name
+field in the utmp on your machine\&.  Otherwise they are
+treated as ordinary strings\&.
+.RE
+.TP
+\fB%S\fP (\fB%s\fP)
+Start (stop) standout mode\&.
+.TP
+\fB%U\fP (\fB%u\fP)
+Start (stop) underline mode\&.
+.TP
+\fB%B\fP (\fB%b\fP)
+Start (stop) boldface mode\&.
+.TP
+.PD 0
+\fB%t\fP
+.TP
+.PD
+\fB%@\fP
+The time, in 12\-hour, am/pm format\&.
+.TP
+\fB%T\fP
+The time, in 24\-hour format\&.
+.TP
+\fB%w\fP
+The date in `\fIday\fP\fB\-\fP\fIdd\fP' format\&.
+.TP
+\fB%W\fP
+The date in `\fImm\fP\fB/\fP\fIdd\fP\fB/\fP\fIyy\fP' format\&.
+.TP
+\fB%D\fP
+The date in `\fIyy\fP\fB\-\fP\fImm\fP\fB\-\fP\fIdd\fP' format\&.
+.TP
+\fB%(\fP\fIx\fP\fB:\fP\fItrue\-text\fP\fB:\fP\fIfalse\-text\fP\fB)\fP
+Specifies a ternary expression\&.
+The character following the \fIx\fP is
+arbitrary; the same character is used to separate the text
+for the "true" result from that for the "false" result\&.
+Both the separator and the right parenthesis may be escaped
+with a backslash\&.
+Ternary expressions may be nested\&.
+.RS
+.PP
+The test character \fIx\fP may be any one of `\fBl\fP', `\fBn\fP', `\fBm\fP'
+or `\fBM\fP', which indicate a `true' result if the corresponding
+escape sequence would return a non\-empty value; or it may be `\fBa\fP',
+which indicates a `true' result if the watched user has logged in,
+or `false' if he has logged out\&.
+Other characters evaluate to neither true nor false; the entire
+expression is omitted in this case\&.
+.PP
+If the result is `true', then the \fItrue\-text\fP
+is formatted according to the rules above and printed,
+and the \fIfalse\-text\fP is skipped\&.
+If `false', the \fItrue\-text\fP is skipped and the \fIfalse\-text\fP
+is formatted and printed\&.
+Either or both of the branches may be empty, but
+both separators must be present in any case\&.
+.RE
+.RE
+.RE
+.TP
+\fBWORDCHARS\fP <S>
+A list of non\-alphanumeric characters considered part of a word
+by the line editor\&.
+.TP
+\fBZBEEP\fP
+If set, this gives a string of characters, which can use all the same codes
+as the \fBbindkey\fP command as described in
+the zsh/zle module entry in \fIzshmodules\fP(1), that will be output to the terminal
+instead of beeping\&.  This may have a visible instead of an audible effect;
+for example, the string `\fB\ee[?5h\ee[?5l\fP' on a vt100 or xterm will have
+the effect of flashing reverse video on and off (if you usually use reverse
+video, you should use the string `\fB\ee[?5l\ee[?5h\fP' instead)\&.  This takes
+precedence over the \fBNOBEEP\fP option\&.
+.TP
+\fBZDOTDIR\fP
+The directory to search for shell startup files (\&.zshrc, etc),
+if not \fB$HOME\fP\&.
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshtcpsys.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshtcpsys.1
@@ -0,0 +1,802 @@
+.TH "ZSHTCPSYS" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshtcpsys \- zsh tcp system
+.\" Yodl file: Zsh/tcpsys.yo
+.SH "DESCRIPTION"
+.PP
+A module \fBzsh/net/tcp\fP is provided to provide network I/O over
+TCP/IP from within the shell; see its description in
+\fIzshmodules\fP(1)
+\&.  This manual page describes a function suite based on the module\&.  
+If the module is installed, the functions are usually installed at the
+same time, in which case they will be available for
+autoloading in the default function search path\&.  In addition to the
+\fBzsh/net/tcp\fP module, the \fBzsh/zselect\fP module is used to implement
+timeouts on read operations\&.  For troubleshooting tips, consult the
+corresponding advice for the \fBzftp\fP functions described in
+\fIzshftpsys\fP(1)
+\&.
+.PP
+There are functions corresponding to the basic I/O operations open, close,
+read and send, named \fBtcp_open\fP etc\&., as well as a function
+\fBtcp_expect\fP for pattern match analysis of data read as input\&.  The
+system makes it easy to receive data from and send data to multiple named
+sessions at once\&.  In addition, it can be linked with the shell's line
+editor in such a way that input data is automatically shown at the
+terminal\&.  Other facilities available including logging, filtering and
+configurable output prompts\&.
+.PP
+To use the system where it is available, it should be enough to
+`\fBautoload \-U tcp_open\fP' and run \fBtcp_open\fP as documented below to
+start a session\&.  The \fBtcp_open\fP function will autoload the remaining
+functions\&.
+.PP
+.PP
+.SH "TCP USER FUNCTIONS"
+.PP
+.SS "Basic I/O"
+.PP
+.PD 0
+.TP
+.PD 0
+\fBtcp_open [\-qz]\fP \fIhost port\fP \fB[\fP \fIsess\fP \fB]\fP
+.TP
+.PD 0
+\fBtcp_open [\-qz] [ \-s\fP \fIsess\fP \fB| \-l\fP \fIsess\fP\fB,\&.\&.\&. ] \&.\&.\&. \fP
+.TP
+.PD
+\fBtcp_open [\-qz] [\-a\fP \fIfd\fP \fB| \-f\fP \fIfd\fP \fB] [\fP \fIsess\fP \fB]\fP
+Open a new session\&.  In the first and simplest form, open a TCP connection
+to host \fIhost\fP at port \fIport\fP; numeric and symbolic forms are
+understood for both\&.
+.RS
+.PP
+If \fIsess\fP is given, this becomes the name of the session which can be
+used to refer to multiple different TCP connections\&.  If \fIsess\fP is
+not given, the function will invent a numeric name value (note this is
+\fInot\fP the same as the file descriptor to which the session is attached)\&.
+It is recommended that session names not include `funny' characters, where
+funny characters are not well\-defined but certainly do not include
+alphanumerics or underscores, and certainly do include whitespace\&.
+.PP
+In the second case, one or more sessions to be opened are given by name\&.
+A single session name is given after \fB\-s\fP and a comma\-separated list
+after \fB\-l\fP; both options may be repeated as many times as necessary\&.
+The host and port are read from the file \fB\&.ztcp_sessions\fP in the same
+directory as the user's zsh initialisation files, i\&.e\&. usually the home
+directory, but \fB$ZDOTDIR\fP if that is set\&.  The file consists of lines
+each giving a session name and the corresponding host and port, in that
+order (note the session name comes first, not last), separated by
+whitespace\&.
+.PP
+The third form allows passive and fake TCP connections\&.  If the option
+\fB\-a\fP is used, its argument is a file descriptor open for listening for
+connections\&.  No function front\-end is provided to open such a file
+descriptor, but a call to `\fBztcp \-l\fP \fIport\fP' will create one with the
+file descriptor stored in the parameter \fB$REPLY\fP\&.  The listening port can
+be closed with `\fBztcp \-c\fP \fIfd\fP'\&.  A call to `\fBtcp_open \-a\fP \fIfd\fP'
+will block until a remote TCP connection is made to \fIport\fP on the local
+machine\&.  At this point, a session is created in the usual way and is
+largely indistinguishable from an active connection created with one of the
+first two forms\&.
+.PP
+If the option \fB\-f\fP is used, its argument is a file descriptor which is
+used directly as if it were a TCP session\&.  How well the remainder of the
+TCP function system copes with this depends on what actually underlies this
+file descriptor\&.  A regular file is likely to be unusable; a FIFO (pipe) of
+some sort will work better, but note that it is not a good idea for two
+different sessions to attempt to read from the same FIFO at once\&.
+.PP
+If the option \fB\-q\fP is given with any of the three forms, \fBtcp_open\fP
+will not print informational messages, although it will in any case exit
+with an appropriate status\&.
+.PP
+If the line editor (zle) is in use, which is typically the case if the
+shell is interactive, \fBtcp_open\fP installs a handler inside \fBzle\fP which
+will check for new data at the same time as it checks for keyboard input\&.
+This is convenient as the shell consumes no CPU time while waiting; the
+test is performed by the operating system\&.  Giving the option \fB\-z\fP to
+any of the forms of \fBtcp_open\fP prevents the handler from being
+installed, so data must be read explicitly\&.  Note, however, this is not
+necessary for executing complete sets of send and read commands from a
+function, as zle is not active at this point\&.  Generally speaking, the
+handler is only active when the shell is waiting for input at a command
+prompt or in the \fBvared\fP builtin\&.  The option has no effect if zle is not
+active; `\fB[[ \-o zle]]\fP' will test for this\&.
+.PP
+The first session to be opened becomes the current session and subsequent
+calls to \fBtcp_open\fP do not change it\&.  The current session is stored
+in the parameter \fB$TCP_SESS\fP; see below for more detail about the
+parameters used by the system\&.
+.RE
+.TP
+\fBtcp_close [\-qn] [ \-a | \-l\fP \fIsess\fP\fB,\&.\&.\&. |\fP \fIsess\fP \fB\&.\&.\&. ]\fP
+Close the named sessions, or the current session if none is given,
+or all open sessions if \fB\-a\fP is given\&.  The options \fB\-l\fP and \fB\-s\fP are
+both handled for consistency with \fBtcp_open\fP, although the latter is
+redundant\&.
+.RS
+.PP
+If the session being closed is the current one, \fB$TCP_SESS\fP is unset,
+leaving no current session, even if there are other sessions still open\&.
+.PP
+If the session was opened with \fBtcp_open \-f\fP, the file descriptor is
+closed so long as it is in the range 0 to 9 accessible directly from the
+command line\&.  If the option \fB\-n\fP is given, no attempt will be made to
+close file descriptors in this case\&.  The \fB\-n\fP option is not used for
+genuine \fBztcp\fP session; the file descriptors are always closed with the
+session\&.
+.PP
+If the option \fB\-q\fP is given, no informational messages will be printed\&.
+.RE
+.TP
+.PD 0
+\fBtcp_read [\-bdq] [ \-t\fP \fITO\fP \fB] [ \-T\fP \fITO\fP \fB]\fP
+.TP
+.PD
+    \fB[ \-a | \-u\fP \fIfd\fP \fB\&.\&.\&. | \-l\fP \fIsess\fP\fB,\&.\&.\&. | \-s\fP \fIsess\fP \fB\&.\&.\&.]\fP
+Perform a read operation on the current session, or on a list of
+sessions if any are given with \fB\-u\fP, \fB\-l\fP or \fB\-s\fP, or all open
+sessions if the option \fB\-a\fP is given\&.  Any of the \fB\-u\fP, \fB\-l\fP or
+\fB\-s\fP options may be repeated or mixed together\&.  The \fB\-u\fP option
+specifies a file descriptor directly (only those managed by this system
+are useful), the other two specify sessions as described for
+\fBtcp_open\fP above\&.
+.RS
+.PP
+The function checks for new data available on all the sessions listed\&.
+Unless the \fB\-b\fP option is given, it will not block waiting for new data\&.
+Any one line of data from any of the available sessions will be read,
+stored in the parameter \fB$TCP_LINE\fP, and displayed to standard output
+unless \fB$TCP_SILENT\fP contains a non\-empty string\&.  When printed to
+standard output the string \fB$TCP_PROMPT\fP will be shown at the start of
+the line; the default form for this includes the name of the session being
+read\&.  See below for more information on these parameters\&.  In this mode,
+\fBtcp_read\fP can be called repeatedly until it returns status 2 which
+indicates all pending input from all specified sessions has been handled\&.
+.PP
+With the option \fB\-b\fP, equivalent to an infinite timeout, the function
+will block until a line is available to read from one of the specified
+sessions\&.  However, only a single line is returned\&.
+.PP
+The option \fB\-d\fP indicates that all pending input should be drained\&.  In
+this case \fBtcp_read\fP may process multiple lines in the manner given
+above; only the last is stored in \fB$TCP_LINE\fP, but the complete set is
+stored in the array \fB$tcp_lines\fP\&.  This is cleared at the start of each
+call to \fBtcp_read\fP\&.
+.PP
+The options \fB\-t\fP and \fB\-T\fP specify a timeout in seconds, which may be a
+floating point number for increased accuracy\&.  With \fB\-t\fP the timeout is
+applied before each line read\&.  With \fB\-T\fP, the timeout applies to the
+overall operation, possibly including multiple read operations if the
+option \fB\-d\fP is present; without this option, there is no distinction
+between \fB\-t\fP and \fB\-T\fP\&.
+.PP
+The function does not print informational messages, but if the option
+\fB\-q\fP is given, no error message is printed for a non\-existent session\&.
+.PP
+A return value of 2 indicates a timeout or no data to read\&.  Any other
+non\-zero return value indicates some error condition\&.
+.PP
+See \fBtcp_log\fP for how to control where data is sent by \fBtcp_read\fP\&.
+.RE
+.TP
+.PD 0
+\fBtcp_send [\-nq] [ \-s\fP \fIsess\fP \fB| \-l\fP \fIsess\fP\fB,\&.\&.\&. ]\fP \fIdata\fP \fB\&.\&.\&.\fP
+.TP
+.PD
+\fBtcp_send [\-nq] \-a\fP \fIdata\fP \fB\&.\&.\&.\fP
+Send the supplied data strings to all the specified sessions in turn\&.  The
+underlying operation differs little from a `\fBprint \-r\fP' to the session's
+file descriptor, although it attempts to prevent the shell from dying owing
+to a \fBSIGPIPE\fP caused by an attempt to write to a defunct session\&.
+.RS
+.PP
+The option \fB\-n\fP prevents \fBtcp_send\fP from putting a newline at the end
+of the data strings\&.
+.PP
+The remaining options all behave as for \fBtcp_read\fP\&.
+.PP
+The data arguments are not further processed once they have been passed to
+\fBtcp_send\fP; they are simply passed down to \fBprint \-r\fP\&.
+.PP
+If the parameter \fB$TCP_OUTPUT\fP is a non\-empty string and logging is
+enabled then the data sent to each session will be echoed to the log
+file(s) with \fB$TCP_OUTPUT\fP in front where appropriate, much in the manner
+of \fB$TCP_PROMPT\fP\&.
+.RE
+.RE
+.PP
+.SS "Session Management"
+.PP
+.PD 0
+.TP
+.PD 0
+\fBtcp_alias [\-q]\fP \fIalias\fP\fB=\fP\fIsess\fP \fB\&.\&.\&.\fP
+.TP
+.PD 0
+\fBtcp_alias [\-q] [\fP \fIalias\fP \fB] \&.\&.\&.\fP
+.TP
+.PD
+\fBtcp_alias \-d [\-q]\fP \fIalias\fP \fB\&.\&.\&.\fP
+This function is not particularly well tested\&.
+.RS
+.PP
+The first form creates an alias for a session name; \fIalias\fP can then be
+used to refer to the existing session \fIsess\fP\&.  As many aliases may be
+listed as required\&.
+.PP
+The second form lists any aliases specified, or all aliases if none\&.
+.PP
+The third form deletes all the aliases listed\&.  The underlying sessions are
+not affected\&.
+.PP
+The option \fB\-q\fP suppresses an inconsistently chosen subset of error
+messages\&.
+.RE
+.TP
+\fBtcp_log [\-asc] [ \-n | \-N ] [\fP \fIlogfile\fP \fB]\fP
+With an argument \fIlogfile\fP, all future input from \fBtcp_read\fP will be
+logged to the named file\&.  Unless \fB\-a\fP (append) is given, this file will
+first be truncated or created empty\&.  With no arguments, show the current
+status of logging\&.
+.RS
+.PP
+With the option \fB\-s\fP, per\-session logging is enabled\&.  Input from
+\fBtcp_read\fP is output to the file \fIlogfile\fP\&.\fIsess\fP\&.  As the
+session is automatically discriminated by the filename, the contents are
+raw (no \fB$TCP_PROMPT\fP)\&.  The option  \fB\-a\fP applies as above\&.
+Per\-session logging and logging of all data in one file are not mutually
+exclusive\&.
+.PP
+The option \fB\-c\fP closes all logging, both complete and per\-session logs\&.
+.PP
+The options \fB\-n\fP and \fB\-N\fP respectively turn off or restore output of
+data read by \fBtcp_read\fP to standard output; hence `\fBtcp_log \-cn\fP' turns
+off all output by \fBtcp_read\fP\&.
+.PP
+The function is purely a convenient front end to setting the parameters
+\fB$TCP_LOG\fP, \fB$TCP_LOG_SESS\fP, \fB$TCP_SILENT\fP, which are described below\&.
+.RE
+.TP
+\fBtcp_rename\fP \fIold\fP \fInew\fP
+Rename session \fIold\fP to session \fInew\fP\&.  The old name becomes invalid\&.
+.TP
+\fBtcp_sess [\fP \fIsess\fP \fB[\fP \fIcommand\fP  \fB\&.\&.\&. ] ]\fP
+With no arguments, list all the open sessions and associated file
+descriptors\&.  The current session is marked with a star\&.  For use in
+functions, direct access to the parameters \fB$tcp_by_name\fP, \fB$tcp_by_fd\fP
+and \fB$TCP_SESS\fP is probably more convenient; see below\&.
+.RS
+.PP
+With a \fIsess\fP argument, set the current session to \fIsess\fP\&.
+This is equivalent to changing \fB$TCP_SESS\fP directly\&.
+.PP
+With additional arguments, temporarily set the current session while
+executing the string \fBcommand \&.\&.\&.\fP\&.  The first argument is re\-evaluated
+so as to expand aliases etc\&., but the remaining arguments are passed
+through as the appear to \fBtcp_sess\fP\&.  The original session is restored
+when \fBtcp_sess\fP exits\&.
+.RE
+.RE
+.PP
+.SS "Advanced I/O"
+.PP
+.PD 0
+.TP
+.PD
+\fBtcp_command\fP \fIsend\-options\fP \fB\&.\&.\&.\fP \fIsend\-arguments\fP \fB\&.\&.\&.\fP
+This is a convenient front\-end to \fBtcp_send\fP\&.  All arguments are passed
+to \fBtcp_send\fP, then the function pauses waiting for data\&.  While data is
+arriving at least every \fB$TCP_TIMEOUT\fP (default 0\&.3) seconds, data is
+handled and printed out according to the current settings\&.  Status 0 is
+always returned\&.
+.RS
+.PP
+This is generally only useful for interactive use, to prevent the display
+becoming fragmented by output returned from the connection\&.  Within a
+programme or function it is generally better to handle reading data by a
+more explicit method\&.
+.RE
+.TP
+.PD 0
+\fBtcp_expect [ \-q ] [ \-p\fP \fIvar\fP \fB] [ \-t \fP \fIto\fP \fB| \-T\fP \fITO\fP\fB]\fP
+.TP
+.PD
+\fB    [ \-a | \-s\fP \fIsess\fP \fB\&.\&.\&. | \-l\fP \fIsess\fP\fB,\&.\&.\&. ]\fP \fIpattern\fP \&.\&.\&.
+Wait for input matching any of the given \fIpattern\fPs from any of the
+specified sessions\&.  Input is ignored until an input line matches one of
+the given patterns; at this point status zero is returned, the matching
+line is stored in \fB$TCP_LINE\fP, and the full set of lines read during the
+call to \fBtcp_expect\fP is stored in the array \fB$tcp_expect_lines\fP\&.
+.RS
+.PP
+Sessions are specified in the same way as \fBtcp_read\fP: the default is to
+use the current session, otherwise the sessions specified by \fB\-a\fP,
+\fB\-s\fP, or \fB\-l\fP are used\&.
+.PP
+Each \fIpattern\fP is a standard zsh extended\-globbing pattern; note that it
+needs to be quoted to avoid it being expanded immediately by filename
+generation\&.  It must match the full line, so to match a substring there
+must be a `\fB*\fP' at the start and end\&.  The line matched against includes
+the \fB$TCP_PROMPT\fP added by \fBtcp_read\fP\&.  It is possible to include the
+globbing flags `\fB#b\fP' or `\fB#m\fP' in the patterns to make backreferences
+available in the parameters \fB$MATCH\fP, \fB$match\fP, etc\&., as described in
+the base zsh documentation on pattern matching\&.
+.PP
+Unlike \fBtcp_read\fP, the default behaviour of \fBtcp_expect\fP is to block
+indefinitely until the required input is found\&.  This can be modified by
+specifying a timeout with \fB\-t\fP or \fB\-T\fP; these function as in
+\fBtcp_read\fP, specifying a per\-read or overall timeout, respectively, in
+seconds, as an integer or floating\-point number\&.  As \fBtcp_read\fP, the
+function returns status 2 if a timeout occurs\&.
+.PP
+The function returns as soon as any one of the patterns given match\&.  If
+the caller needs to know which of the patterns matched, the option \fB\-p\fP
+\fIvar\fP can be used; on return, \fB$var\fP is set to the number of the
+pattern using ordinary zsh indexing, i\&.e\&. the first is 1, and so on\&.  Note
+the absence of a `\fB$\fP' in front of \fIvar\fP\&.  To avoid clashes, the
+parameter cannot begin with `\fB_expect\fP'\&.
+.PP
+The option \fB\-q\fP is passed directly down to \fBtcp_read\fP\&.
+.PP
+As all input is done via \fBtcp_read\fP, all the usual rules about output of
+lines read apply\&.  One exception is that the parameter \fB$tcp_lines\fP will
+only reflect the line actually matched by \fBtcp_expect\fP; use
+\fB$tcp_expect_lines\fP for the full set of lines read during the function
+call\&.
+.RE
+.TP
+\fBtcp_proxy\fP
+This is a simple\-minded function to accept a TCP connection and execute a
+command with I/O redirected to the connection\&.  Extreme caution should be
+taken as there is no security whatsoever and this can leave your computer
+open to the world\&.  Ideally, it should only be used behind a firewall\&.
+.RS
+.PP
+The first argument is a TCP port on which the function will listen\&.
+.PP
+The remaining arguments give a command and its arguments to execute with
+standard input, standard output and standard error redirected to the
+file descriptor on which the TCP session has been accepted\&.
+If no command is given, a new zsh is started\&.  This gives everyone on
+your network direct access to your account, which in many cases will be a
+bad thing\&.
+.PP
+The command is run in the background, so \fBtcp_proxy\fP can then accept new
+connections\&.  It continues to accept new connections until interrupted\&.
+.RE
+.TP
+\fBtcp_spam [\-ertv] [ \-a | \-s \fP \fIsess\fP \fB| \-l\fP \fIsess\fP\fB,\&.\&.\&. ]\fP \fIcmd\fP \fB\&.\&.\&.\fP
+Execute `\fIcmd\fP \fB\&.\&.\&.\fP' for each session in turn\&.  Note this executes
+the command and arguments; it does not send the command line as data
+unless the \fB\-t\fP (transmit) option is given\&.
+.RS
+.PP
+The sessions may be selected explicitly with the standard \fB\-a\fP, \fB\-s\fP or
+\fB\-l\fP options, or may be chosen implicitly\&.  If none of the three options
+is given the rules are: first, if the array \fB$tcp_spam_list\fP is set, this
+is taken as the list of sessions, otherwise all sessions are taken\&.
+Second, any sessions given in the array \fB$tcp_no_spam_list\fP are removed
+from the list of sessions\&.
+.PP
+Normally, any sessions added by the `\fB\-a\fP' flag or when all sessions are
+chosen implicitly are spammed in alphabetic order; sessions given by the
+\fB$tcp_spam_list\fP array or on the command line are spammed in the order
+given\&.  The \fB\-r\fP flag reverses the order however it was arrived it\&.
+.PP
+The \fB\-v\fP flag specifies that a \fB$TCP_PROMPT\fP will be output before each
+session\&.  This is output after any modification to TCP_SESS by the
+user\-defined \fBtcp_on_spam\fP function described below\&.  (Obviously that
+function is able to generate its own output\&.)
+.PP
+If the option \fB\-e\fP is present, the line given as \fIcmd \&.\&.\&.\fP is executed
+using \fBeval\fP, otherwise it is executed without any further processing\&.
+.RE
+.TP
+\fBtcp_talk\fP
+This is a fairly simple\-minded attempt to force input to the line editor to
+go straight to the default TCP_SESSION\&.
+.RS
+.PP
+An escape string, \fB$TCP_TALK_ESCAPE\fP, default `:', is used to allow
+access to normal shell operation\&.  If it is on its own at the start of the
+line, or followed only by whitespace, the line editor returns to normal
+operation\&.  Otherwise, the string and any following whitespace are skipped
+and the remainder of the line executed as shell input without any change of
+the line editor's operating mode\&.
+.PP
+The current implementation is somewhat deficient in terms of use of the
+command history\&.  For this reason, many users will prefer to use some form
+of alternative approach for sending data easily to the current session\&.
+One simple approach is to alias some special character (such as `\fB%\fP') to
+`\fBtcp_command \-\-\fP'\&.
+.RE
+.TP
+\fBtcp_wait\fP
+The sole argument is an integer or floating point number which gives the
+seconds to delay\&.  The shell will do nothing for that period except wait
+for input on all TCP sessions by calling \fBtcp_read \-a\fP\&.  This is similar
+to the interactive behaviour at the command prompt when zle handlers are
+installed\&.
+.PP
+.SS "`One\-shot' file transfer"
+.PD 0
+.TP
+.PD 0
+\fBtcp_point\fP \fIport\fP
+.TP
+.PD
+\fBtcp_shoot\fP \fIhost\fP \fIport\fP
+This pair of functions provide a simple way to transfer a file between
+two hosts within the shell\&.  Note, however, that bulk data transfer is
+currently done using \fBcat\fP\&.  \fBtcp_point\fP reads any data arriving at
+\fIport\fP and sends it to standard output; \fBtcp_shoot\fP connects to
+\fIport\fP on \fIhost\fP and sends its standard input\&.  Any unused \fIport\fP
+may be used; the standard mechanism for picking a port is to think of a
+random four\-digit number above 1024 until one works\&.
+.RS
+.PP
+To transfer a file from host \fBwoodcock\fP to host \fBspringes\fP, on
+\fBspringes\fP:
+.PP
+.RS
+.nf
+\fBtcp_point 8091 >output_file\fP
+.fi
+.RE
+.PP
+and on \fBwoodcock\fP:
+.PP
+.RS
+.nf
+\fBtcp_shoot springes 8091 <input_file\fP
+.fi
+.RE
+.PP
+As these two functions do not require \fBtcp_open\fP to set up a TCP
+connection first, they may need to be autoloaded separately\&.
+.RE
+.RE
+.PP
+.SH "TCP USER\-DEFINED FUNCTIONS"
+.PP
+Certain functions, if defined by the user, will be called by the function
+system in certain contexts\&.  This facility depends on the module
+\fBzsh/parameter\fP, which is usually available in interactive shells as the
+completion system depends on it\&.  None of the functions need be defined;
+they simply provide convenient hooks when necessary\&.
+.PP
+Typically, these are called after the requested action has been taken, so
+that the various parameters will reflect the new state\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBtcp_on_alias\fP \fIalias\fP \fIfd\fP
+When an alias is defined, this function will be called with two arguments:
+the name of the alias, and the file descriptor of the corresponding session\&.
+.TP
+\fBtcp_on_close\fP \fIsess\fP \fIfd\fP
+This is called with the name of a session being closed and the file
+descriptor which corresponded to that session\&.  Both will be invalid by
+the time the function is called\&.
+.TP
+\fBtcp_on_open\fP \fIsess\fP \fIfd\fP
+This is called after a new session has been defined with the session name
+and file descriptor as arguments\&.
+.TP
+\fBtcp_on_rename\fP \fIoldsess\fP \fIfd\fP \fInewsess\fP
+This is called after a session has been renamed with the three arguments
+old session name, file descriptor, new session name\&.
+.TP
+\fBtcp_on_spam\fP \fIsess\fP \fIcommand\fP \fB\&.\&.\&.\fP
+This is called once for each session spammed, just \fIbefore\fP a command is
+executed for a session by \fBtcp_spam\fP\&.  The arguments are the session name
+followed by the command list to be executed\&.  If \fBtcp_spam\fP was called
+with the option \fB\-t\fP, the first command will be \fBtcp_send\fP\&.
+.RS
+.PP
+This function is called after \fB$TCP_SESS\fP is set to reflect the session
+to be spammed, but before any use of it is made\&.  Hence it is possible to
+alter the value of \fB$TCP_SESS\fP within this function\&.  For example, the
+session arguments to \fBtcp_spam\fP could include extra information to be
+stripped off and processed in \fBtcp_on_spam\fP\&.
+.PP
+If the function sets the parameter \fB$REPLY\fP to `\fBdone\fP', the command
+line is not executed; in addition, no prompt is printed for the \fB\-v\fP
+option to \fBtcp_spam\fP\&.
+.RE
+.TP
+\fBtcp_on_unalias\fP \fIalias\fP \fIfd\fP
+This is called with the name of an alias and the corresponding session's
+file descriptor after an alias has been deleted\&.
+.PP
+.SH "TCP UTILITY FUNCTIONS"
+.PP
+The following functions are used by the TCP function system but will rarely
+if ever need to be called directly\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBtcp_fd_handler\fP
+This is the function installed by \fBtcp_open\fP for handling input from
+within the line editor, if that is required\&.  It is in the format
+documented for the builtin `\fBzle \-F\fP' in
+\fIzshzle\fP(1)
+\&.
+.RS
+.PP
+While active, the function sets the parameter \fBTCP_HANDLER_ACTIVE\fP to 1\&.
+This allows shell code called internally (for example, by setting
+\fBtcp_on_read\fP) to tell if is being called when the shell is otherwise
+idle at the editor prompt\&.
+.RE
+.TP
+\fBtcp_output [ \-q ] \-P\fP \fIprompt\fP \fB\-F\fP \fIfd\fP \fB\-S\fP \fIsess\fP
+This function is used for both logging and handling output to standard
+output, from within \fBtcp_read\fP and (if \fB$TCP_OUTPUT\fP is set)
+\fBtcp_send\fP\&.
+.RS
+.PP
+The \fIprompt\fP to use is specified by \fB\-P\fP; the default is the empty
+string\&.  It can contain:
+.PD 0
+.TP
+.PD
+\fB%c\fP
+Expands to 1 if the session is the current session, otherwise 0\&.  Used
+with ternary expresions such as `\fB%(c\&.\-\&.+)\fP' to
+output `\fB+\fP' for the current session and `\fB\-\fP' otherwise\&.
+.TP
+\fB%f\fP
+Replaced by the session's file descriptor\&.
+.TP
+\fB%s\fP
+Replaced by the session name\&.
+.TP
+\fB%%\fP
+Replaced by a single `\fB%\fP'\&.
+.PP
+The option \fB\-q\fP suppresses output to standard output, but not to any log
+files which are configured\&.
+.PP
+The \fB\-S\fP and \fB\-F\fP options are used to pass in the session name and file
+descriptor for possible replacement in the prompt\&.
+.RE
+.RE
+.PP
+.SH "TCP USER PARAMETERS"
+.PP
+Parameters follow the usual convention that uppercase is used for scalars
+and integers, while lowercase is used for normal and associative array\&.
+It is always safe for user code to read these parameters\&.  Some parameters
+may also be set; these are noted explicitly\&.  Others are included in this
+group as they are set by the function system for the user's benefit,
+i\&.e\&. setting them is typically not useful but is benign\&.
+.PP
+It is often also useful to make settable parameters local to a function\&.
+For example, `\fBlocal TCP_SILENT=1\fP' specifies that data read during the
+function call will not be printed to standard output, regardless of the
+setting outside the function\&.  Likewise, `\fBlocal TCP_SESS=\fP\fIsess\fP'
+sets a session for the duration of a function, and `\fBlocal
+TCP_PROMPT=\fP' specifies that no prompt is used for input during the
+function\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBtcp_expect_lines\fP
+Array\&.  The set of lines read during the last call to \fBtcp_expect\fP,
+including the last (\fB$TCP_LINE\fP)\&.
+.TP
+\fBtcp_filter\fP
+Array\&. May be set directly\&.  A set of extended globbing patterns which,
+if matched in \fBtcp_output\fP, will cause the line not to be printed to
+standard output\&.  The patterns should be defined as described for the
+arguments to \fBtcp_expect\fP\&.  Output of line to log files is not affected\&.
+.TP
+\fBTCP_HANDLER_ACTIVE\fP
+Scalar\&.  Set to 1 within \fBtcp_fd_handler\fP to indicate to functions
+called recursively that they have been called during an editor session\&.
+Otherwise unset\&.
+.TP
+\fBTCP_LINE\fP
+The last line read by \fBtcp_read\fP, and hence also \fBtcp_expect\fP\&.
+.TP
+\fBTCP_LINE_FD\fP
+The file descriptor from which \fB$TCP_LINE\fP was read\&.
+\fB${tcp_by_fd[$TCP_LINE_FD]}\fP will give the corresponding session name\&.
+.TP
+\fBtcp_lines\fP
+Array\&. The set of lines read during the last call to \fBtcp_read\fP,
+including the last (\fB$TCP_LINE\fP)\&.
+.TP
+\fBTCP_LOG\fP
+May be set directly, although it is also controlled by \fBtcp_log\fP\&.
+The name of a file to which output from all sessions will be sent\&.
+The output is proceeded by the usual \fB$TCP_PROMPT\fP\&.  If it is not an
+absolute path name, it will follow the user's current directory\&.
+.TP
+\fBTCP_LOG_SESS\fP
+May be set directly, although it is also controlled by \fBtcp_log\fP\&.
+The prefix for a set of files to which output from each session separately
+will be sent; the full filename is \fB${TCP_LOG_SESS}\&.\fP\fIsess\fP\&.
+Output to each file is raw; no prompt is added\&.  If it is not an absolute
+path name, it will follow the user's current directory\&.
+.TP
+\fBtcp_no_spam_list\fP
+Array\&.  May be set directly\&.  See \fBtcp_spam\fP for how this is used\&.
+.TP
+\fBTCP_OUTPUT\fP
+May be set directly\&.  If a non\-empty string, any data sent to a session by
+\fBtcp_send\fP will be logged\&.  This parameter gives the prompt to be used
+in a file specified by \fB$TCP_LOG\fP but not in a file generated from
+\fB$TCP_LOG_SESS\fP\&.  The prompt string has the same format as
+\fBTCP_PROMPT\fP and the same rules for its use apply\&.
+.TP
+\fBTCP_PROMPT\fP
+May be set directly\&.  Used as the prefix for data read by \fBtcp_read\fP
+which is printed to standard output or to the log file given by
+\fB$TCP_LOG\fP, if any\&.  Any `\fB%s\fP', `\fB%f\fP' or `\fB%%\fP' occurring in the
+string will be replaced by the name of the session, the session's
+underlying file descriptor, or a single `\fB%\fP', respectively\&.  The
+expression `\fB%c\fP' expands to 1 if the session being read is the current
+session, else 0; this is most useful in ternary expressions such as
+`\fB%(c\&.\-\&.+)\fP' which outputs `\fB+\fP' if the session is
+the current one, else `\fB\-\fP'\&.
+.TP
+\fBTCP_READ_DEBUG\fP
+May be set directly\&.  If this has non\-zero length, \fBtcp_read\fP will give
+some limited diagnostics about data being read\&.
+.TP
+\fBTCP_SECONDS_START\fP
+This value is created and initialised to zero by tcp_open\&.
+.RS
+.PP
+The functions \fBtcp_read\fP and \fBtcp_expect\fP use the shell's
+\fBSECONDS\fP parameter for their own timing purposes\&.  If that parameter
+is not of floating point type on entry to one of the functions, it will
+create a local parameter \fBSECONDS\fP which is floating point and set the
+parameter \fBTCP_SECONDS_START\fP to the previous value of \fB$SECONDS\fP\&.
+If the parameter is already floating point, it is used without a local
+copy being created and \fBTCP_SECONDS_START\fP is not set\&.  As the global
+value is zero, the shell elapsed time is guaranteed to be the sum of
+\fB$SECONDS\fP and \fB$TCP_SECONDS_START\fP\&.
+.PP
+This can be avoided by setting \fBSECONDS\fP globally to a floating point
+value using `\fBtypeset \-F SECONDS\fP'; then the TCP functions will never
+make a local copy and never set \fBTCP_SECONDS_START\fP to a non\-zero value\&.
+.RE
+.TP
+\fBTCP_SESS\fP
+May be set directly\&.  The current session; must refer to one of the
+sessions established by \fBtcp_open\fP\&.
+.TP
+\fBTCP_SILENT\fP
+May be set directly, although it is also controlled by \fBtcp_log\fP\&.
+If of non\-zero length, data read by \fBtcp_read\fP will not be written to
+standard output, though may still be written to a log file\&.
+.TP
+\fBtcp_spam_list\fP
+Array\&.  May be set directly\&.  See the description of the function
+\fBtcp_spam\fP for how this is used\&.
+.TP
+\fBTCP_TALK_ESCAPE\fP
+May be set directly\&.  See the description of the function \fBtcp_talk\fP for
+how this is used\&.
+.TP
+\fBTCP_TIMEOUT\fP
+May be set directly\&.  Currently this is only used by the function
+\fBtcp_command\fP, see above\&.
+.PP
+.SH "TCP USER\-DEFINED PARAMETERS"
+.PP
+The following parameters are not set by the function system, but have
+a special effect if set by the user\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBtcp_on_read\fP
+This should be an associative array; if it is not, the behaviour is
+undefined\&.  Each key is the name of a shell function or other command,
+and the corresponding value is a shell pattern (using \fBEXTENDED_GLOB\fP)\&.
+Every line read from a TCP session directly or indirectly using
+\fBtcp_read\fP (which includes lines read by \fBtcp_expect\fP) is compared
+against the pattern\&.  If the line matches, the command given in the key is
+called with two arguments: the name of the session from which the line was
+read, and the line itself\&.
+.RS
+.PP
+If any function called to handle a line returns a non\-zero status, the
+line is not output\&.  Thus a \fBtcp_on_read\fP handler containing only
+the instruction `\fBreturn 1\fP' can be used to suppress output of
+particular lines (see, however, \fBtcp_filter\fP above)\&.  However, the line
+is still stored in \fBTCP_LINE\fP and \fBtcp_lines\fP; this occurs after all
+\fBtcp_on_read\fP processing\&.
+.RE
+.RE
+.PP
+.SH "TCP UTILITY PARAMETERS"
+.PP
+These parameters are controlled by the function system; they may be read
+directly, but should not usually be set by user code\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBtcp_aliases\fP
+Associative array\&.  The keys are the names of sessions established with
+\fBtcp_open\fP; each value is a space\-separated list of aliases which refer
+to that session\&.
+.TP
+\fBtcp_by_fd\fP
+Associative array\&.  The keys are session file descriptors; each
+value is the name of that session\&.
+.TP
+\fBtcp_by_name\fP
+Associative array\&.  The keys are the names of sessions; each value is the
+file descriptor associated with that session\&.
+.PP
+.SH "TCP EXAMPLES"
+.PP
+Here is a trivial example using a remote calculator\&.
+.PP
+TO create a calculator server on port 7337 (see the \fBdc\fP manual page for
+quite how infuriating the underlying command is):
+.PP
+.RS
+.nf
+\fBtcp_proxy 7337 dc\fP
+.fi
+.RE
+.PP
+To connect to this from the same host with a session also named `\fBdc\fP':
+.PP
+.RS
+.nf
+\fBtcp_open localhost 7337 dc\fP
+.fi
+.RE
+.PP
+To send a command to the remote session and wait a short while for output
+(assuming \fBdc\fP is the current session):
+.PP
+.RS
+.nf
+\fBtcp_command 2 4 + p\fP
+.fi
+.RE
+.PP
+To close the session:
+.PP
+.RS
+.nf
+\fBtcp_close\fP
+.fi
+.RE
+.PP
+The \fBtcp_proxy\fP needs to be killed to be stopped\&.  Note this will not
+usually kill any connections which have already been accepted, and also
+that the port is not immediately available for reuse\&.
+.PP
+The following chunk of code puts a list of sessions into an xterm header,
+with the current session followed by a star\&.
+.PP
+.RS
+.nf
+\fBprint \-n "\e033]2;TCP:" ${(k)tcp_by_name:/$TCP_SESS/$TCP_SESS\e*} "\ea"\fP
+.fi
+.RE
+.PP
+.SH "TCP BUGS"
+.PP
+The function \fBtcp_read\fP uses the shell's normal \fBread\fP builtin\&.  As
+this reads a complete line at once, data arriving without a terminating
+newline can cause the function to block indefinitely\&.
+.PP
+Though the function suite works well for interactive use and for data
+arriving in small amounts, the performance when large amounts of data are
+being exchanged is likely to be extremely poor\&.
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshzftpsys.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshzftpsys.1
@@ -0,0 +1,672 @@
+.TH "ZSHZFTPSYS" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshzftpsys \- zftp function front\-end
+.\" Yodl file: Zsh/zftpsys.yo
+.SH "DESCRIPTION"
+.PP
+This describes the set of shell functions supplied with the source
+distribution as an interface to the \fBzftp\fP builtin command, allowing you
+to perform FTP operations from the shell command line or within functions
+or scripts\&.  The interface is similar to a traditional FTP client (e\&.g\&. the
+\fBftp\fP command itself, see \fIftp\fP(1)), but as it is entirely done
+within the shell all the familiar completion, editing and globbing features,
+and so on, are present, and macros are particularly simple to write as they
+are just ordinary shell functions\&.
+.PP
+The prerequisite is that the \fBzftp\fP command, as described in
+\fIzshmodules\fP(1)
+, must be available in the
+version of \fBzsh\fP installed at your site\&.  If the shell is configured to
+load new commands at run time, it probably is: typing `\fBzmodload zsh/zftp\fP'
+will make sure (if that runs silently, it has worked)\&.  If this is not the
+case, it is possible \fBzftp\fP was linked into the shell anyway: to test
+this, type `\fBwhich zftp\fP' and if \fBzftp\fP is available you will get the
+message `\fBzftp: shell built\-in command\fP'\&.
+.PP
+Commands given directly with \fBzftp\fP builtin may be interspersed between
+the functions in this suite; in a few cases, using \fBzftp\fP directly may
+cause some of the status information stored in shell parameters to become
+invalid\&.  Note in particular the description of the variables
+\fB$ZFTP_TMOUT\fP, \fB$ZFTP_PREFS\fP and \fB$ZFTP_VERBOSE\fP for \fBzftp\fP\&.
+.PP
+.PP
+.SH "INSTALLATION"
+.PP
+You should make sure all the functions from the \fBFunctions/Zftp\fP
+directory of the source distribution are available; they all begin with the
+two letters `\fBzf\fP'\&.  They may already have been installed on your system;
+otherwise, you will need to find them and copy them\&.  The directory should
+appear as one of the elements of the \fB$fpath\fP array (this should already
+be the case if they were installed), and at least the function \fBzfinit\fP
+should be autoloaded; it will autoload the rest\&.  Finally, to initialize
+the use of the system you need to call the \fBzfinit\fP function\&.  The
+following code in your \fB\&.zshrc\fP will arrange for this; assume the
+functions are stored in the directory \fB~/myfns\fP:
+.PP
+.RS
+.nf
+\fBfpath=(~/myfns $fpath)
+autoload \-U zfinit
+zfinit\fP
+.fi
+.RE
+.PP
+Note that \fBzfinit\fP assumes you are using the \fBzmodload\fP method to
+load the \fBzftp\fP command\&.  If it is already built into the shell, change
+\fBzfinit\fP to \fBzfinit \-n\fP\&.  It is helpful (though not essential) if the
+call to \fBzfinit\fP appears after any code to initialize the new completion
+system, else unnecessary \fBcompctl\fP commands will be given\&.
+.PP
+.SH "FUNCTIONS"
+.PP
+The sequence of operations in performing a file transfer is essentially the
+same as that in a standard FTP client\&.  Note that, due to a quirk of the
+shell's \fBgetopts\fP builtin, for those functions that handle options you
+must use `\fB\-\fP\fB\-\fP' rather than `\fB\-\fP' to ensure the remaining arguments
+are treated literally (a single `\fB\-\fP' is treated as an argument)\&.
+.PP
+.SS "Opening a connection"
+.PD 0
+.TP
+.PD
+\fBzfparams [ \fIhost\fP [ \fIuser\fP [ \fIpassword\fP \&.\&.\&. ] ] ]\fP
+Set or show the parameters for a future \fBzfopen\fP with no arguments\&.  If
+no arguments are given, the current parameters are displayed (the password
+will be shown as a line of asterisks)\&.  If a host is given, and either the
+\fIuser\fP or \fIpassword\fP is not, they will be prompted for; also, any
+parameter given as `\fB?\fP' will be prompted for, and if the `\fB?\fP' is
+followed by a string, that will be used as the prompt\&.  As \fBzfopen\fP calls
+\fBzfparams\fP to store the parameters, this usually need not be called
+directly\&.
+.RS
+.PP
+A single argument `\fB\-\fP' will delete the stored parameters\&.  This will
+also cause the memory of the last directory (and so on) on the other host
+to be deleted\&.
+.RE
+.TP
+\fBzfopen [ \-1 ] [ \fIhost\fP [ \fIuser\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ] ]\fP
+If \fIhost\fP is present, open a connection to that host under username
+\fIuser\fP with password \fIpassword\fP (and, on the rare occasions when it
+is necessary, account \fIaccount\fP)\&.  If a necessary parameter is missing or
+given as `\fB?\fP' it will be prompted for\&.  If \fIhost\fP is not present, use
+a previously stored set of parameters\&.
+.RS
+.PP
+If the command was successful, and the terminal is compatible with
+\fBxterm\fP or is \fBsun\-cmd\fP, a summary will appear in the title bar,
+giving the local \fBhost:directory\fP and the remote \fBhost:directory\fP;
+this is handled by the function \fBzftp_chpwd\fP, described below\&.
+.PP
+Normally, the \fIhost\fP, \fIuser\fP and \fIpassword\fP are internally
+recorded for later re\-opening, either by a \fBzfopen\fP with no arguments, or
+automatically (see below)\&.  With the option `\fB\-1\fP', no information is
+stored\&.  Also, if an open command with arguments failed, the parameters
+will not be retained (and any previous parameters will also be deleted)\&.
+A \fBzfopen\fP on its own, or a \fBzfopen \-1\fP, never alters the stored
+parameters\&.
+.PP
+Both \fBzfopen\fP and \fBzfanon\fP (but not \fBzfparams\fP) understand URLs of
+the form \fBftp://\fP\fIhost\fP/\fIpath\&.\&.\&.\fP as meaning to connect to the
+\fIhost\fP, then change directory to \fIpath\fP (which must be a directory,
+not a file)\&.  The `\fBftp://\fP' can be omitted; the trailing `\fB/\fP' is enough
+to trigger recognition of the \fIpath\fP\&.  Note prefixes other than
+`\fBftp:\fP' are not recognized, and that all characters after the first
+slash beyond \fIhost\fP are significant in \fIpath\fP\&.
+.RE
+.TP
+\fBzfanon [ \-1 ] \fIhost\fP\fP
+Open a connection \fIhost\fP for anonymous FTP\&.  The username used is
+`\fBanonymous\fP'\&.  The password (which will be reported the first time) is
+generated as \fIuser\fP\fB@\fP\fIhost\fP; this is then stored in the shell
+parameter \fB$EMAIL_ADDR\fP which can alternatively be set manually to a
+suitable string\&.
+.PP
+.SS "Directory management"
+.PD 0
+.TP
+.PD 0
+\fBzfcd [ \fIdir\fP ]\fP
+.TP
+.PD 0
+\fBzfcd \-\fP
+.TP
+.PD
+\fBzfcd \fIold\fP \fInew\fP\fP
+Change the current directory on the remote server:  this is implemented to
+have many of the features of the shell builtin \fBcd\fP\&.
+.RS
+.PP
+In the first form with \fIdir\fP present, change to the directory \fIdir\fP\&.
+The command `\fBzfcd \&.\&.\fP' is treated specially, so is guaranteed to work on
+non\-UNIX servers (note this is handled internally by \fBzftp\fP)\&.  If \fIdir\fP
+is omitted, has the effect of `\fBzfcd ~\fP'\&.
+.PP
+The second form changes to the directory previously current\&.
+.PP
+The third form attempts to change the current directory by replacing the
+first occurrence of the string \fIold\fP with the string \fInew\fP in the
+current directory\&.
+.PP
+Note that in this command, and indeed anywhere a remote filename is
+expected, the string which on the local host corresponds to `\fB~\fP' is
+converted back to a `\fB~\fP' before being passed to the remote machine\&.
+This is convenient because of the way expansion is performed on the command
+line before \fBzfcd\fP receives a string\&.  For example, suppose the command
+is `\fBzfcd ~/foo\fP'\&.  The shell will expand this to a full path such as
+`\fBzfcd /home/user2/pws/foo\fP'\&.  At this stage, \fBzfcd\fP recognises the
+initial path as corresponding to `\fB~\fP' and will send the directory to
+the remote host as \fB~/foo\fP, so that the `\fB~\fP' will be expanded by the
+server to the correct remote host directory\&.  Other named directories of
+the form `\fB~name\fP' are not treated in this fashion\&.
+.RE
+.TP
+\fBzfhere\fP
+Change directory on the remote server to the one corresponding to the
+current local directory, with special handling of `\fB~\fP' as in \fBzfcd\fP\&.
+For example, if the current local directory is \fB~/foo/bar\fP, then
+\fBzfhere\fP performs the effect of `\fBzfcd ~/foo/bar\fP'\&.
+.TP
+\fBzfdir [ \-rfd ] [ \- ] [ \fIdir\-options\fP ] [ \fIdir\fP ]\fP
+Produce a long directory listing\&.  The arguments \fIdir\-options\fP and
+\fIdir\fP are passed directly to the server and their effect is
+implementation dependent, but specifying a particular remote directory
+\fIdir\fP is usually possible\&.  The output is passed through a pager
+given by the environment variable \fB$PAGER\fP, or `\fBmore\fP' if that is not
+set\&.
+.RS
+.PP
+The directory is usually cached for re\-use\&.  In fact, two caches are
+maintained\&.  One is for use when there is no \fIdir\-options\fP or \fIdir\fP,
+i\&.e\&. a full listing of the current remote directory; it is flushed
+when the current remote directory changes\&.  The other is
+kept for repeated use of \fBzfdir\fP with the same arguments; for example,
+repeated use of `\fBzfdir /pub/gnu\fP' will only require the directory to be
+retrieved on the first call\&.  Alternatively, this cache can be re\-viewed with
+the \fB\-r\fP option\&.  As relative directories will confuse
+\fBzfdir\fP, the \fB\-f\fP option can be used to force the cache to be flushed
+before the directory is listed\&.  The option \fB\-d\fP will delete both
+caches without showing a directory listing; it will also delete the cache
+of file names in the current remote directory, if any\&.
+.RE
+.TP
+\fBzfls\fP [ \fIls\-options\fP ] [ \fIdir\fP ]
+List files on the remote server\&.  With no arguments, this will produce a
+simple list of file names for the current remote directory\&.  Any arguments
+are passed directly to the server\&.  No pager and no caching is used\&.
+.PP
+.SS "Status commands"
+.PD 0
+.TP
+.PD
+\fBzftype\fP [ \fItype\fP ]
+With no arguments, show the type of data to be transferred, usually ASCII
+or binary\&.  With an argument, change the type: the types `\fBA\fP' or
+`\fBASCII\fP' for ASCII data and `\fBB\fP' or `\fBBINARY\fP', `\fBI\fP' or
+`\fBIMAGE\fP' for binary data are understood case\-insensitively\&.
+.TP
+\fBzfstat\fP [ \-v ]
+Show the status of the current or last connection, as well as the status of
+some of \fBzftp\fP's status variables\&.  With the \fB\-v\fP option, a more
+verbose listing is produced by querying the server for its version of
+events, too\&.
+.PP
+.SS "Retrieving files"
+The commands for retrieving files all take at least two options\&. \fB\-G\fP
+suppresses remote filename expansion which would otherwise be performed
+(see below for a more detailed description of that)\&.  \fB\-t\fP attempts
+to set the modification time of the local file to that of the remote file:
+this requires version 5 of \fBperl\fP, see the description of the function
+\fBzfrtime\fP below for more information\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBzfget [ \-Gtc ] \fIfile1\fP \&.\&.\&.\fP
+Retrieve all the listed files \fIfile1\fP \&.\&.\&. one at a time from the remote
+server\&.  If a file contains a `\fB/\fP', the full name is passed to the
+remote server, but the file is stored locally under the name given by the
+part after the final `\fB/\fP'\&.  The option \fB\-c\fP (cat) forces all files to
+be sent as a single stream to standard output; in this case the \fB\-t\fP
+option has no effect\&.
+.TP
+\fBzfuget [ \-Gvst ] \fIfile1\fP \&.\&.\&.\fP
+As \fBzfget\fP, but only retrieve files where the version on the remote
+server is newer (has a later modification time), or where the local file
+does not exist\&.  If the remote file is older but the files have different
+sizes, or if the sizes are the same but the remote file is newer, the user
+will usually be queried\&.  With the option \fB\-s\fP, the command runs silently
+and will always retrieve the file in either of those two cases\&.  With the
+option \fB\-v\fP, the command prints more information about the files while it
+is working out whether or not to transfer them\&.
+.TP
+\fBzfcget [ \-Gt ] \fIfile1\fP \&.\&.\&.\fP
+As \fBzfget\fP, but if any of the local files exists, and is shorter than
+the corresponding remote file, the command assumes that it is the result of
+a partially completed transfer and attempts to transfer the rest of the
+file\&.  This is useful on a poor connection which keeps failing\&.
+.RS
+.PP
+Note that this requires a commonly implemented, but non\-standard, version
+of the FTP protocol, so is not guaranteed to work on all servers\&.
+.RE
+.TP
+.PD 0
+\fBzfgcp [ \-Gt ] \fIremote\-file\fP \fIlocal\-file\fP\fP
+.TP
+.PD
+\fBzfgcp [ \-Gt ] \fIrfile1\fP \&.\&.\&. \fIldir\fP\fP
+This retrieves files from the remote server with arguments behaving
+similarly to the \fBcp\fP command\&.
+.RS
+.PP
+In the first form, copy \fIremote\-file\fP from the server to the local file
+\fIlocal\-file\fP\&.
+.PP
+In the second form, copy all the remote files \fIrfile1\fP \&.\&.\&. into the
+local directory \fIldir\fP retaining the same basenames\&.  This assumes UNIX
+directory semantics\&.
+.RE
+.RE
+.PP
+.SS "Sending files"
+.PD 0
+.TP
+.PD
+\fBzfput [ \-r ] \fIfile1\fP \&.\&.\&.\fP
+Send all the \fIfile1\fP \&.\&.\&. given separately to the remote server\&.  If a
+filename contains a `\fB/\fP', the full filename is used locally to find the
+file, but only the basename is used for the remote file name\&.
+.RS
+.PP
+With the option \fB\-r\fP, if any of the \fIfiles\fP are directories they are
+sent recursively with all their subdirectories, including files beginning
+with `\fB\&.\fP'\&.  This requires that the remote machine understand UNIX file
+semantics, since `\fB/\fP' is used as a directory separator\&.
+.RE
+.TP
+\fBzfuput [ \-vs ] \fIfile1\fP \&.\&.\&.\fP
+As \fBzfput\fP, but only send files which are newer than their local
+equivalents, or if the remote file does not exist\&.  The logic is the same
+as for \fBzfuget\fP, but reversed between local and remote files\&.
+.TP
+\fBzfcput \fIfile1\fP \&.\&.\&.\fP
+As \fBzfput\fP, but if any remote file already exists and is shorter than the
+local equivalent, assume it is the result of an incomplete transfer and
+send the rest of the file to append to the existing part\&.  As the FTP
+append command is part of the standard set, this is in principle more
+likely to work than \fBzfcget\fP\&.
+.TP
+.PD 0
+\fBzfpcp \fIlocal\-file\fP \fIremote\-file\fP\fP
+.TP
+.PD
+\fBzfpcp \fIlfile1\fP \&.\&.\&. \fIrdir\fP\fP
+This sends files to the remote server with arguments behaving similarly to
+the \fBcp\fP command\&.
+.RS
+.PP
+With two arguments, copy \fIlocal\-file\fP to the server as
+\fIremote\-file\fP\&.
+.PP
+With more than two arguments, copy all the local files \fIlfile1\fP \&.\&.\&. into
+the existing remote directory \fIrdir\fP retaining the same basenames\&.  This
+assumes UNIX directory semantics\&.
+.PP
+A problem arises if you attempt to use \fBzfpcp\fP \fIlfile1\fP \fIrdir\fP,
+i\&.e\&. the second form of copying but with two arguments, as the command has
+no simple way of knowing if \fIrdir\fP corresponds to a directory or a
+filename\&.  It attempts to resolve this in various ways\&.  First, if the
+\fIrdir\fP argument is `\fB\&.\fP' or `\fB\&.\&.\fP' or ends in a slash, it is assumed
+to be a directory\&.  Secondly, if the operation of copying to a remote file
+in the first form failed, and the remote server sends back the expected
+failure code 553 and a reply including the string `\fBIs a directory\fP',
+then \fBzfpcp\fP will retry using the second form\&.
+.RE
+.RE
+.PP
+.SS "Closing the connection"
+.PD 0
+.TP
+.PD
+\fBzfclose\fP
+Close the connection\&.
+.PP
+.SS "Session management"
+.PD 0
+.TP
+.PD
+\fBzfsession\fP [ \fB\-lvod\fP ] [ \fIsessname\fP ]
+Allows you to manage multiple FTP sessions at once\&.  By default,
+connections take place in a session called `\fBdefault\fP'; by giving the
+command `\fBzfsession\fP \fIsessname\fP' you can change to a new or existing
+session with a name of your choice\&.  The new session remembers its own
+connection, as well as associated shell parameters, and also the host/user
+parameters set by \fBzfparams\fP\&.  Hence you can have different sessions set
+up to connect to different hosts, each remembering the appropriate host,
+user and password\&.
+.RS
+.PP
+With no arguments, \fBzfsession\fP prints the name of the current session;
+with the option \fB\-l\fP it lists all sessions which currently exist, and
+with the option \fB\-v\fP it gives a verbose list showing the host and
+directory for each session, where the current session is marked with an
+asterisk\&.  With \fB\-o\fP, it will switch to the most recent previous session\&.
+.PP
+With \fB\-d\fP, the given session (or else the current one) is removed;
+everything to do with it is completely forgotten\&.  If it was the only
+session, a new session called `\fBdefault\fP' is created and made current\&.
+It is safest not to delete sessions while background commands using
+\fBzftp\fP are active\&.
+.RE
+.TP
+\fBzftransfer\fP \fIsess1\fP\fB:\fP\fIfile1\fP \fIsess2\fP\fB:\fP\fIfile2\fP
+Transfer files between two sessions; no local copy is made\&.  The file
+is read from the session \fIsess1\fP as \fIfile1\fP and written to session
+\fIsess2\fP as file \fIfile2\fP; \fIfile1\fP and \fIfile2\fP may be relative to
+the current directories of the session\&.  Either \fIsess1\fP or \fIsess2\fP
+may be omitted (though the colon should be retained if there is a
+possibility of a colon appearing in the file name) and defaults to the
+current session; \fIfile2\fP may be omitted or may end with a slash, in
+which case the basename of \fIfile1\fP will be added\&.  The sessions
+\fIsess1\fP and \fIsess2\fP must be distinct\&.
+.RS
+.PP
+The operation is performed using pipes, so it is required that the
+connections still be valid in a subshell, which is not the case under 
+versions of some operating systems, presumably due to a system bug\&.
+.RE
+.RE
+.PP
+.SS "Bookmarks"
+The two functions \fBzfmark\fP and \fBzfgoto\fP allow you to `bookmark' the
+present location (host, user and directory) of the current FTP connection
+for later use\&.  The file to be used for storing and retrieving bookmarks is
+given by the parameter \fB$ZFTP_BMFILE\fP; if not set when one of the two
+functions is called, it will be set to the file \fB\&.zfbkmarks\fP in the
+directory where your zsh startup files live (usually \fB~\fP)\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBzfmark [ \fP\fIbookmark\fP\fB ]\fP
+If given an argument, mark the current host, user and directory under the
+name \fIbookmark\fP for later use by \fBzfgoto\fP\&.  If there is no connection
+open, use the values for the last connection immediately before it was
+closed; it is an error if there was none\&.  Any existing bookmark
+under the same name will be silently replaced\&.
+.RS
+.PP
+If not given an argument, list the existing bookmarks and the points to
+which they refer in the form \fIuser\fP\fB@\fP\fIhost\fP\fB:\fP\fIdirectory\fP;
+this is the format in which they are stored, and the file may be edited
+directly\&.
+.RE
+.TP
+\fBzfgoto [ \-n ] \fP\fIbookmark\fP
+Return to the location given by \fIbookmark\fP, as previously set by
+\fBzfmark\fP\&.  If the location has user `\fBftp\fP' or `\fBanonymous\fP', open
+the connection with \fBzfanon\fP, so that no password is required\&.  If the
+user and host parameters match those stored for the current session, if
+any, those will be used, and again no password is required\&.  Otherwise a
+password will be prompted for\&.
+.RS
+.PP
+With the option \fB\-n\fP, the bookmark is taken to be a nickname stored by
+the \fBncftp\fP program in its bookmark file, which is assumed to be
+\fB~/\&.ncftp/bookmarks\fP\&.  The function works identically in other ways\&.
+Note that there is no mechanism for adding or modifying \fBncftp\fP bookmarks
+from the zftp functions\&.
+.RE
+.RE
+.PP
+.SS "Other functions"
+Mostly, these functions will not be called directly (apart from
+\fBzfinit\fP), but are described here for completeness\&.  You may wish to
+alter \fBzftp_chpwd\fP and \fBzftp_progress\fP, in particular\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBzfinit [ \-n ]\fP
+As described above, this is used to initialize the zftp function system\&.
+The \fB\-n\fP option should be used if the zftp command is already built into
+the shell\&.
+.TP
+\fBzfautocheck [ \-dn ]\fP
+This function is called to implement automatic reopening behaviour, as
+described in more detail below\&.  The options must appear in the first
+argument; \fB\-n\fP prevents the command from changing to the old directory,
+while \fB\-d\fP prevents it from setting the variable \fBdo_close\fP, which it
+otherwise does as a flag for automatically closing the connection after a
+transfer\&.  The host and directory for the last session are stored in the
+variable \fB$zflastsession\fP, but the internal host/user/password parameters
+must also be correctly set\&.
+.TP
+\fBzfcd_match \fIprefix\fP \fIsuffix\fP\fP
+This performs matching for completion of remote directory names\&.  If the
+remote server is UNIX, it will attempt to persuade the server to list the
+remote directory with subdirectories marked, which usually works but is not
+guaranteed\&.  On other hosts it simply calls \fBzfget_match\fP and hence
+completes all files, not just directories\&.  On some systems, directories
+may not even look like filenames\&.
+.TP
+\fBzfget_match \fIprefix\fP \fIsuffix\fP\fP
+This performs matching for completion of remote filenames\&.  It caches files
+for the current directory (only) in the shell parameter \fB$zftp_fcache\fP\&.
+It is in the form to be called by the \fB\-K\fP option of \fBcompctl\fP, but
+also works when called from a widget\-style completion function with
+\fIprefix\fP and \fIsuffix\fP set appropriately\&.
+.TP
+\fBzfrglob \fIvarname\fP\fP
+Perform remote globbing, as describes in more detail below\&.  \fIvarname\fP
+is the name of a variable containing the pattern to be expanded; if there
+were any matches, the same variable will be set to the expanded set of
+filenames on return\&.
+.TP
+\fBzfrtime \fIlfile\fP \fIrfile\fP [ \fItime\fP ]\fP
+Set the local file \fIlfile\fP to have the same modification time as the
+remote file \fIrfile\fP, or the explicit time \fItime\fP in FTP format
+\fBCCYYMMDDhhmmSS\fP for the GMT timezone\&.
+.RS
+.PP
+Currently this requires \fBperl\fP version 5 to perform the conversion from
+GMT to local time\&.  This is unfortunately difficult to do using shell code
+alone\&.
+.RE
+.TP
+\fBzftp_chpwd\fP
+This function is called every time a connection is opened, or closed, or
+the remote directory changes\&.  This version alters the title bar of an
+\fBxterm\fP\-compatible or \fBsun\-cmd\fP terminal emulator to reflect the 
+local and remote hostnames and current directories\&.  It works best when
+combined with the function \fBchpwd\fP\&.  In particular, a function of 
+the form
+.RS
+.PP
+.RS
+.nf
+\fBchpwd() {
+  if [[ \-n $ZFTP_USER ]]; then
+    zftp_chpwd
+  else
+    # usual chpwd e\&.g put host:directory in title bar
+  fi
+}\fP
+.fi
+.RE
+.PP
+fits in well\&.
+.RE
+.TP
+\fBzftp_progress\fP
+This function shows the status of the transfer\&.  It will not write anything
+unless the output is going to a terminal; however, if you transfer files in
+the background, you should turn off progress reports by hand using
+`\fBzstyle ':zftp:*' progress none\fP'\&.  Note also that if you alter it, any
+output \fImust\fP be to standard error, as standard output may be a file
+being received\&.  The form of the progress meter, or whether it is used at
+all, can be configured without altering the function, as described in the
+next section\&.
+.TP
+\fBzffcache\fP
+This is used to implement caching of files in the current directory for
+each session separately\&.  It is used by \fBzfget_match\fP and \fBzfrglob\fP\&.
+.PP
+.SH "MISCELLANEOUS FEATURES"
+.PP
+.SS "Configuration"
+.PP
+Various styles are available using the standard shell style mechanism,
+described in
+\fIzshmodules\fP(1)\&. Briefly, the
+command `\fBzstyle ':zftp:*'\fP \fIstyle\fP \fIvalue\fP \&.\&.\&.'\&.
+defines the \fIstyle\fP to have value \fIvalue\fP; more than one value may be
+given, although that is not useful in the cases described here\&.  These
+values will then be used throughout the zftp function system\&.  For more
+precise control, the first argument, which gives a context in which the
+style applies, can be modified to include a particular function, as for
+example `\fB:zftp:zfget\fP': the style will then have the given value only
+in the \fBzfget\fP function\&.  Values for the same style in different contexts
+may be set; the most specific function will be used, where
+strings are held to be more specific than patterns, and longer patterns and
+shorter patterns\&.  Note that only the top level function name, as called by
+the user, is used; calling of lower level functions is transparent to the
+user\&.  Hence modifications to the title bar in \fBzftp_chpwd\fP use the
+contexts \fB:zftp:zfopen\fP, \fB:zftp:zfcd\fP, etc\&., depending where it was
+called from\&.  The following styles are understood:
+.PP
+.PD 0
+.TP
+.PD
+\fBprogress\fP
+Controls the way that \fBzftp_progress\fP reports on the progress of a
+transfer\&.  If empty, unset, or `\fBnone\fP', no progress report is made; if
+`\fBbar\fP' a growing bar of inverse video is shown; if `\fBpercent\fP' (or any
+other string, though this may change in future), the percentage of the file
+transferred is shown\&.  The bar meter requires that the width of the
+terminal be available via the \fB$COLUMNS\fP parameter (normally this is set
+automatically)\&.  If the size of the file being transferred is not
+available, \fBbar\fP and \fBpercent\fP meters will simply show the number of
+bytes transferred so far\&.
+.RS
+.PP
+When \fBzfinit\fP is run, if this style is not defined for the context
+\fB:zftp:*\fP, it will be set to `bar'\&.
+.RE
+.TP
+\fBupdate\fP
+Specifies the minimum time interval between updates of the progress meter
+in seconds\&.  No update is made unless new data has been received, so the
+actual time interval is limited only by \fB$ZFTP_TIMEOUT\fP\&.
+.RS
+.PP
+As described for \fBprogress\fP, \fBzfinit\fP will force this to default to 1\&.
+.RE
+.TP
+\fBremote\-glob\fP
+If set to `1', `yes' or `true', filename generation (globbing) is
+performed on the remote machine instead of by zsh itself; see below\&.
+.TP
+\fBtitlebar\fP
+If set to `1', `yes' or `true', \fBzftp_chpwd\fP will put the remote host and
+remote directory into the titlebar of terminal emulators such as xterm or
+sun\-cmd that allow this\&.
+.RS
+.PP
+As described for \fBprogress\fP, \fBzfinit\fP will force this to default to 1\&.
+.RE
+.TP
+\fBchpwd\fP
+If set to `1' `yes' or `true', \fBzftp_chpwd\fP will call the function
+\fBchpwd\fP when a connection is closed\&.  This is useful if the remote host
+details were put into the terminal title bar by \fBzftp_chpwd\fP and your
+usual \fBchpwd\fP also modifies the title bar\&.
+.RS
+.PP
+When \fBzfinit\fP is run, it will determine whether \fBchpwd\fP exists and if
+so it will set the default value for the style to 1 if none exists
+already\&.
+.RE
+.RE
+.PP
+Note that there is also an associative array \fBzfconfig\fP which contains
+values used by the function system\&.  This should not be modified or
+overwritten\&.
+.PP
+.SS "Remote globbing"
+.PP
+The commands for retrieving files usually perform filename generation
+(globbing) on their arguments; this can be turned off by passing the option
+\fB\-G\fP to each of the commands\&.  Normally this operates by retrieving a
+complete list of files for the directory in question, then matching these
+locally against the pattern supplied\&.  This has the advantage that the full
+range of zsh patterns (respecting the setting of the option
+\fBEXTENDED_GLOB\fP) can be used\&.  However, it means that the directory part
+of a filename will not be expanded and must be given exactly\&.  If the
+remote server does not support the UNIX directory semantics, directory
+handling is problematic and it is recommended that globbing only be used
+within the current directory\&.  The list of files in the current directory,
+if retrieved, will be cached, so that subsequent globs in the same
+directory without an intervening \fBzfcd\fP are much faster\&.
+.PP
+If the \fBremote\-glob\fP style (see above) is set, globbing is instead
+performed on the remote host: the server is asked for a list of matching
+files\&.  This is highly dependent on how the server is implemented, though
+typically UNIX servers will provide support for basic glob patterns\&.  This
+may in some cases be faster, as it avoids retrieving the entire list of
+directory contents\&.
+.PP
+.SS "Automatic and temporary reopening"
+.PP
+As described for the \fBzfopen\fP command, a subsequent \fBzfopen\fP with no
+parameters will reopen the connection to the last host (this includes
+connections made with the \fBzfanon\fP command)\&.  Opened in this fashion, the
+connection starts in the default remote directory and will remain open
+until explicitly closed\&.
+.PP
+Automatic re\-opening is also available\&.  If a connection is not currently
+open and a command requiring a connection is given, the last connection is
+implicitly reopened\&.  In this case the directory which was current when the
+connection was closed again becomes the current directory (unless, of
+course, the command given changes it)\&.  Automatic reopening will also take
+place if the connection was close by the remote server for whatever reason
+(e\&.g\&. a timeout)\&.  It is not available if the \fB\-1\fP option to \fBzfopen\fP
+or \fBzfanon\fP was used\&.
+.PP
+Furthermore, if the command issued is a file transfer, the connection will
+be closed after the transfer is finished, hence providing a one\-shot mode
+for transfers\&.  This does not apply to directory changing or listing
+commands; for example a \fBzfdir\fP may reopen a connection but will leave it
+open\&.  Also, automatic closure will only ever happen in the same command as
+automatic opening, i\&.e a \fBzfdir\fP directly followed by a \fBzfget\fP will
+never close the connection automatically\&.
+.PP
+Information about the previous connection is given by the \fBzfstat\fP
+function\&.  So, for example, if that reports:
+.PP
+.RS
+.nf
+\fBSession:        default
+Not connected\&.
+Last session:   ftp\&.bar\&.com:/pub/textfiles\fP
+.fi
+.RE
+.PP
+then the command \fBzfget file\&.txt\fP will attempt to reopen a connection to
+\fBftp\&.bar\&.com\fP, retrieve the file \fB/pub/textfiles/file\&.txt\fP, and
+immediately close the connection again\&.  On the other hand, \fBzfcd \&.\&.\fP
+will open the connection in the directory \fB/pub\fP and leave it open\&.
+.PP
+Note that all the above is local to each session; if you return to a
+previous session, the connection for that session is the one which will be
+reopened\&.
+.PP
+.SS "Completion"
+.PP
+Completion of local and remote files, directories, sessions and bookmarks
+is supported\&.  The older, \fBcompctl\fP\-style completion is defined when
+\fBzfinit\fP is called; support for the new widget\-based completion system is
+provided in the function \fBCompletion/Zsh/Command/_zftp\fP, which should be
+installed with the other functions of the completion system and hence
+should automatically be available\&.
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshzle.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshzle.1
@@ -0,0 +1,1777 @@
+.TH "ZSHZLE" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshzle \- zsh command line editor
+.\" Yodl file: Zsh/zle.yo
+.SH "DESCRIPTION"
+If the \fBZLE\fP option is set (which it is by default in interactive shells)
+and the shell input is attached to the terminal, the user
+is able to edit command lines\&.
+.PP
+There are two display modes\&.  The first, multiline mode, is the
+default\&.  It only works if the \fBTERM\fP parameter is set to a valid
+terminal type that can move the cursor up\&.  The second, single line
+mode, is used if \fBTERM\fP is invalid or incapable of moving the
+cursor up, or if the \fBSINGLE_LINE_ZLE\fP option is set\&.
+This mode
+is similar to \fBksh\fP, and uses no termcap sequences\&.  If \fBTERM\fP is
+"emacs", the \fBZLE\fP option will be unset by default\&.
+.PP
+The parameters \fBBAUD\fP, \fBCOLUMNS\fP, and \fBLINES\fP are also used by the
+line editor\&.
+See \fIParameters Used By The Shell\fP in \fIzshparam\fP(1)\&.
+.PP
+.PP
+.SH "KEYMAPS"
+A keymap in ZLE contains a set of bindings between key sequences
+and ZLE commands\&.  The empty key sequence cannot be bound\&.
+.PP
+There can be any number of keymaps at any time, and each keymap has one
+or more names\&.  If all of a keymap's names are deleted, it disappears\&.
+\fBbindkey\fP can be used to manipulate keymap names\&.
+.PP
+Initially, there are four keymaps:
+.PP
+.PD 0
+.TP
+\fBemacs\fP
+EMACS emulation
+.TP
+\fBviins\fP
+vi emulation \- insert mode
+.TP
+\fBvicmd\fP
+vi emulation \- command mode
+.TP
+\fB\&.safe\fP
+fallback keymap
+.PD
+.PP
+The `\fB\&.safe\fP' keymap is special\&.  It can never be altered, and the name
+can never be removed\&.  However, it can be linked to other names, which can
+be removed\&.  In the future other special keymaps may be added; users should
+avoid using names beginning with `\fB\&.\fP' for their own keymaps\&.
+.PP
+In addition to these four names, either `\fBemacs\fP' or `\fBviins\fP' is
+also linked to the name `\fBmain\fP'\&.  If one of the \fBVISUAL\fP or
+\fBEDITOR\fP environment variables contain the string `\fBvi\fP' when the shell
+starts up then it will be `\fBviins\fP', otherwise it will be `\fBemacs\fP'\&.
+\fBbindkey\fP's \fB\-e\fP and \fB\-v\fP
+options provide a convenient way to override this default choice\&.
+.PP
+When the editor starts up, it will select the `\fBmain\fP' keymap\&.
+If that keymap doesn't exist, it will use `\fB\&.safe\fP' instead\&.
+.PP
+In the `\fB\&.safe\fP' keymap, each single key is bound to \fBself\-insert\fP,
+except for ^J (line feed) and ^M (return) which are bound to \fBaccept\-line\fP\&.
+This is deliberately not pleasant to use; if you are using it, it
+means you deleted the main keymap, and you should put it back\&.
+.SS "Reading Commands"
+When ZLE is reading a command from the terminal, it may read a sequence
+that is bound to some command and is also a prefix of a longer bound string\&.
+In this case ZLE will wait a certain time to see if more characters
+are typed, and if not (or they don't match any longer string) it will
+execute the binding\&.  This timeout is defined by the \fBKEYTIMEOUT\fP parameter;
+its default is 0\&.4 sec\&.  There is no timeout if the prefix string is not
+itself bound to a command\&.
+.PP
+As well as ZLE commands, key sequences can be bound to other strings, by using
+`\fBbindkey \-s\fP'\&.
+When such a sequence is read, the replacement string is pushed back as input,
+and the command reading process starts again using these fake keystrokes\&.
+This input can itself invoke further replacement strings, but in order to
+detect loops the process will be stopped if there are twenty such replacements
+without a real command being read\&.
+.PP
+.SH "ZLE BUILTINS"
+The ZLE module contains three related builtin commands\&. The \fBbindkey\fP
+command manipulates keymaps and key bindings; the \fBvared\fP command invokes
+ZLE on the value of a shell parameter; and the \fBzle\fP command manipulates
+editing widgets and allows command line access to ZLE commands from within
+shell functions\&.
+.PP
+.PD 0
+.TP
+.PD 0
+\fBbindkey\fP [ \fIoptions\fP ] \fB\-l\fP
+.TP
+.PD 0
+\fBbindkey\fP [ \fIoptions\fP ] \fB\-d\fP
+.TP
+.PD 0
+\fBbindkey\fP [ \fIoptions\fP ] \fB\-D\fP \fIkeymap\fP \&.\&.\&.
+.TP
+.PD 0
+\fBbindkey\fP [ \fIoptions\fP ] \fB\-A\fP \fIold\-keymap new\-keymap\fP
+.TP
+.PD 0
+\fBbindkey\fP [ \fIoptions\fP ] \fB\-N\fP \fInew\-keymap\fP [ \fIold\-keymap\fP ]
+.TP
+.PD 0
+\fBbindkey\fP [ \fIoptions\fP ] \fB\-m\fP
+.TP
+.PD 0
+\fBbindkey\fP [ \fIoptions\fP ] \fB\-r\fP \fIin\-string\fP \&.\&.\&.
+.TP
+.PD 0
+\fBbindkey\fP [ \fIoptions\fP ] \fB\-s\fP \fIin\-string out\-string\fP \&.\&.\&.
+.TP
+.PD 0
+\fBbindkey\fP [ \fIoptions\fP ] \fIin\-string command\fP \&.\&.\&.
+.TP
+.PD
+\fBbindkey\fP [ \fIoptions\fP ] [ \fIin\-string\fP ]
+\fBbindkey\fP's options can be divided into three categories: keymap selection,
+operation selection, and others\&.  The keymap selection options are:
+.RS
+.PP
+.PD 0
+.TP
+.PD
+\fB\-e\fP
+Selects keymap `\fBemacs\fP', and also links it to `\fBmain\fP'\&.
+.TP
+\fB\-v\fP
+Selects keymap `\fBviins\fP', and also links it to `\fBmain\fP'\&.
+.TP
+\fB\-a\fP
+Selects keymap `\fBvicmd\fP'\&.
+.TP
+\fB\-M\fP \fIkeymap\fP
+The \fIkeymap\fP specifies a keymap name\&.
+.PP
+If a keymap selection is required and none of the options above are used, the
+`\fBmain\fP' keymap is used\&.  Some operations do not permit a keymap to be
+selected, namely:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-l\fP
+List all existing keymap names\&.  If the \fB\-L\fP
+option is also used, list in the form of \fBbindkey\fP
+commands to create the keymaps\&.
+.TP
+\fB\-d\fP
+Delete all existing keymaps and reset to the default state\&.
+.TP
+\fB\-D\fP \fIkeymap\fP \&.\&.\&.
+Delete the named \fIkeymap\fPs\&.
+.TP
+\fB\-A\fP \fIold\-keymap new\-keymap\fP
+Make the \fInew\-keymap\fP name an alias for \fIold\-keymap\fP, so that
+both names refer to the same keymap\&.  The names have equal standing;
+if either is deleted, the other remains\&.  If there is already a keymap
+with the \fInew\-keymap\fP name, it is deleted\&.
+.TP
+\fB\-N\fP \fInew\-keymap\fP [ \fIold\-keymap\fP ]
+Create a new keymap, named \fInew\-keymap\fP\&.  If a keymap already has that
+name, it is deleted\&.  If an \fIold\-keymap\fP name is given, the new keymap
+is initialized to be a duplicate of it, otherwise the new keymap will
+be empty\&.
+.PP
+To use a newly created keymap, it should be linked to \fBmain\fP\&.  Hence
+the sequence of commands to create and use a new keymap `\fBmymap\fP'
+initialized from the \fBemacs\fP keymap (which remains unchanged) is:
+.PP
+.RS
+.nf
+\fBbindkey \-N mymap emacs
+bindkey \-A mymap main\fP
+.fi
+.RE
+.PP
+Note that while `\fBbindkey \-A\fP \fInewmap\fP \fBmain\fP' will work when
+\fInewmap\fP is \fBemacs\fP or \fBviins\fP, it will not work for \fBvicmd\fP, as
+switching from vi insert to command mode becomes impossible\&.
+.PP
+The following operations act on the `\fBmain\fP' keymap if no keymap
+selection option was given:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-m\fP
+Add the built\-in set of meta\-key bindings to the selected keymap\&.
+Only keys that are unbound or bound to \fBself\-insert\fP are affected\&.
+.TP
+\fB\-r\fP \fIin\-string\fP \&.\&.\&.
+Unbind the specified \fIin\-string\fPs in the selected keymap\&.
+This is exactly equivalent to binding the strings to \fBundefined\-key\fP\&.
+.RS
+.PP
+When \fB\-R\fP is also used, interpret the \fIin\-string\fPs as ranges\&.
+.PP
+When \fB\-p\fP is also used, the \fIin\-string\fPs specify prefixes\&.  Any
+binding that has the given \fIin\-string\fP as a prefix, not including the
+binding for the \fIin\-string\fP itself, if any, will be removed\&.  For
+example,
+.PP
+.RS
+.nf
+\fBbindkey \-rpM viins '^['\fP
+.fi
+.RE
+.PP
+will remove all bindings in the vi\-insert keymap beginning with an escape
+character (probably cursor keys), but leave the binding for the escape
+character itself (probably \fBvi\-cmd\-mode\fP)\&.  This is incompatible with the
+option \fB\-R\fP\&.
+.RE
+.TP
+\fB\-s\fP \fIin\-string out\-string\fP \&.\&.\&.
+Bind each \fIin\-string\fP to each \fIout\-string\fP\&.
+When \fIin\-string\fP is typed, \fIout\-string\fP will be
+pushed back and treated as input to the line editor\&.
+When \fB\-R\fP is also used, interpret the \fIin\-string\fPs as ranges\&.
+.TP
+\fIin\-string command\fP \&.\&.\&.
+Bind each \fIin\-string\fP to each \fIcommand\fP\&.
+When \fB\-R\fP is used, interpret the \fIin\-string\fPs as ranges\&.
+.TP
+[ \fIin\-string\fP ]
+List key bindings\&.  If an \fIin\-string\fP is specified, the binding of
+that string in the selected keymap is displayed\&.  Otherwise, all key
+bindings in the selected keymap are displayed\&.  (As a special case,
+if the \fB\-e\fP or \fB\-v\fP option is used alone, the keymap is \fInot\fP
+displayed \- the implicit linking of keymaps is the only thing that
+happens\&.)
+.RS
+.PP
+When the option \fB\-p\fP is used, the \fIin\-string\fP must be present\&.
+The listing shows all bindings which have the given key sequence as a
+prefix, not including any bindings for the key sequence itself\&.
+.PP
+When the \fB\-L\fP option is used, the list is in the form of \fBbindkey\fP
+commands to create the key bindings\&.
+.RE
+.RE
+.PP
+When the \fB\-R\fP option is used as noted above, a valid range consists of
+two characters, with an optional `\fB\-\fP' between them\&.  All characters
+between the two specified, inclusive, are bound as specified\&.
+.PP
+For either \fIin\-string\fP or \fIout\-string\fP, the following
+escape sequences are recognised:
+.PP
+.PD 0
+.TP
+\fB\ea\fP
+bell character
+.TP
+\fB\eb\fP
+backspace
+.TP
+\fB\ee\fP, \fB\eE\fP
+escape
+.TP
+\fB\ef\fP
+form feed
+.TP
+\fB\en\fP
+linefeed (newline)
+.TP
+\fB\er\fP
+carriage return
+.TP
+\fB\et\fP
+horizontal tab
+.TP
+\fB\ev\fP
+vertical tab
+.TP
+\fB\e\fP\fINNN\fP
+character code in octal
+.TP
+\fB\ex\fP\fINN\fP
+character code in hexadecimal
+.TP
+\fB\eM\fP[\fB\-\fP]\fIX\fP
+character with meta bit set
+.TP
+\fB\eC\fP[\fB\-\fP]\fIX\fP
+control character
+.TP
+\fB^\fP\fIX\fP
+control character
+.PD
+.PP
+In all other cases, `\fB\e\fP' escapes the following character\&.  Delete is
+written as `\fB^?\fP'\&.  Note that `\fB\eM^?\fP' and `\fB^\eM?\fP' are not the same,
+and that (unlike emacs), the bindings `\fB\eM\-\fP\fIX\fP' and `\fB\ee\fP\fIX\fP'
+are entirely distinct, although they are initialized to the same bindings
+by `\fBbindkey \-m\fP'\&.
+.RE
+.TP
+.PD 0
+\fBvared\fP [ \fB\-Aache\fP ] [ \fB\-p\fP \fIprompt\fP ] [ \fB\-r\fP \fIrprompt\fP ]
+.TP
+.PD
+  [ \-M \fImain\-keymap\fP ] [ \-m \fIvicmd\-keymap\fP ] \fIname\fP
+The value of the parameter \fIname\fP is loaded into the edit
+buffer, and the line editor is invoked\&.  When the editor exits,
+\fIname\fP is set to the string value returned by the editor\&.
+When the \fB\-c\fP flag is given, the parameter is created if it doesn't
+already exist\&.  The \fB\-a\fP flag may be given with \fB\-c\fP to create
+an array parameter, or the \fB\-A\fP flag to create an associative array\&.
+If the type of an existing parameter does not match the type to be
+created, the parameter is unset and recreated\&.
+.RS
+.PP
+If an array or array slice is being edited, separator characters as defined
+in \fB$IFS\fP will be shown quoted with a backslash, as will backslashes
+themselves\&.  Conversely, when the edited text is split into an array, a
+backslash quotes an immediately following separator character or backslash;
+no other special handling of backslashes, or any handling of quotes, is
+performed\&.
+.PP
+Individual elements of existing array or associative array parameters
+may be edited by using subscript syntax on \fIname\fP\&.  New elements are
+created automatically, even without \fB\-c\fP\&.
+.PP
+If the \fB\-p\fP flag is given, the following string will be taken as
+the prompt to display at the left\&.  If the \fB\-r\fP flag is given,
+the following string gives the prompt to display at the right\&.  If the
+\fB\-h\fP flag is specified, the history can be accessed from ZLE\&. If the
+\fB\-e\fP flag is given, typing \fB^D\fP (Control\-D) on an empty line
+causes \fBvared\fP to exit immediately with a non\-zero return value\&.
+.PP
+The \fB\-M\fP option gives a keymap to link to the \fBmain\fP keymap during
+editing, and the \fB\-m\fP option gives a keymap to link to the \fBvicmd\fP
+keymap during editing\&.  For vi\-style editing, this allows a pair of keymaps
+to override \fBviins\fP and \fBvicmd\fP\&.  For emacs\-style editing, only \fB\-M\fP
+is normally needed but the \fB\-m\fP option may still be used\&.  On exit, the
+previous keymaps will be restored\&.
+.RE
+.TP
+.PD 0
+\fBzle\fP
+.TP
+.PD 0
+\fBzle\fP \fB\-l\fP [ \fB\-L\fP | \fB\-a\fP ] [ \fIstring\fP \&.\&.\&. ]
+.TP
+.PD 0
+\fBzle\fP \fB\-D\fP \fIwidget\fP \&.\&.\&.
+.TP
+.PD 0
+\fBzle\fP \fB\-A\fP \fIold\-widget\fP \fInew\-widget\fP
+.TP
+.PD 0
+\fBzle\fP \fB\-N\fP \fIwidget\fP [ \fIfunction\fP ]
+.TP
+.PD 0
+\fBzle\fP \fB\-C\fP \fIwidget\fP \fIcompletion\-widget\fP \fIfunction\fP
+.TP
+.PD 0
+\fBzle\fP \fB\-R\fP [ \fB\-c\fP ] [ \fIdisplay\-string\fP ] [ \fIstring\fP \&.\&.\&. ]
+.TP
+.PD 0
+\fBzle\fP \fB\-M\fP \fIstring\fP
+.TP
+.PD 0
+\fBzle\fP \fB\-U\fP \fIstring\fP
+.TP
+.PD 0
+\fBzle\fP \fB\-K\fP \fIkeymap\fP
+.TP
+.PD 0
+\fBzle\fP \fB\-F\fP [ \fB\-L\fP ] [ \fIfd\fP [ \fIhandler\fP ] ]
+.TP
+.PD 0
+\fBzle\fP \fB\-I\fP
+.TP
+.PD
+\fBzle\fP \fIwidget\fP \fB[ \-n\fP \fInum\fP \fB]\fP \fB[ \-N ]\fP \fIargs\fP \&.\&.\&.
+The \fBzle\fP builtin performs a number of different actions concerning
+ZLE\&.
+.RS
+.PP
+With no options and no arguments, only the return status will be
+set\&.  It is zero if ZLE is currently active and widgets could be
+invoked using this builtin command and non\-zero otherwise\&.
+Note that even if non\-zero status is returned, zle may still be active as
+part of the completion system; this does not allow direct calls to ZLE
+widgets\&.
+.PP
+Otherwise, which operation it performs depends on its options:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-l\fP [ \fB\-L\fP | \fB\-a\fP ]
+List all existing user\-defined widgets\&.  If the \fB\-L\fP
+option is used, list in the form of \fBzle\fP
+commands to create the widgets\&.
+.RS
+.PP
+When combined with the \fB\-a\fP option, all widget names are listed,
+including the builtin ones\&. In this case the \fB\-L\fP option is ignored\&.
+.PP
+If at least one \fIstring\fP is given, nothing will be printed but the
+return status will be zero if all \fIstring\fPs are names of existing
+widgets (or of user\-defined widgets if the \fB\-a\fP flag is not given)
+and non\-zero if at least one \fIstring\fP is not a name of an defined
+widget\&.
+.RE
+.TP
+\fB\-D\fP \fIwidget\fP \&.\&.\&.
+Delete the named \fIwidget\fPs\&.
+.TP
+\fB\-A\fP \fIold\-widget\fP \fInew\-widget\fP
+Make the \fInew\-widget\fP name an alias for \fIold\-widget\fP, so that
+both names refer to the same widget\&.  The names have equal standing;
+if either is deleted, the other remains\&.  If there is already a widget
+with the \fInew\-widget\fP name, it is deleted\&.
+.TP
+\fB\-N\fP \fIwidget\fP [ \fIfunction\fP ]
+Create a user\-defined widget\&.  If there is already a widget with the
+specified name, it is overwritten\&.  When the new
+widget is invoked from within the editor, the specified shell \fIfunction\fP
+is called\&.  If no function name is specified, it defaults to
+the same name as the widget\&.  For further information, see the section
+\fIWidgets\fP in
+\fIzshzle\fP(1)\&.
+.TP
+\fB\-C\fP \fIwidget\fP \fIcompletion\-widget\fP \fIfunction\fP
+Create a user\-defined completion widget named \fIwidget\fP\&. The 
+completion widget will behave like the built\-in completion\-widget
+whose name is given as \fIcompletion\-widget\fP\&. To generate the
+completions, the shell function \fIfunction\fP will be called\&.
+For further information, see
+\fIzshcompwid\fP(1)\&.
+.TP
+\fB\-R\fP [ \fB\-c\fP ] [ \fIdisplay\-string\fP ] [ \fIstring\fP \&.\&.\&. ]
+Redisplay the command line; this is to be called from within a user\-defined
+widget to allow changes to become visible\&.  If a \fIdisplay\-string\fP is
+given and not empty, this is shown in the status line (immediately
+below the line being edited)\&.
+.RS
+.PP
+If the optional \fIstring\fPs are given they are listed below the
+prompt in the same way as completion lists are printed\&. If no
+\fIstring\fPs are given but the \fB\-c\fP option is used such a list is
+cleared\&.
+.PP
+Note that this option is only useful for widgets that do not exit
+immediately after using it because the strings displayed will be erased 
+immediately after return from the widget\&.
+.PP
+This command can safely be called outside user defined widgets; if zle is
+active, the display will be refreshed, while if zle is not active, the
+command has no effect\&.  In this case there will usually be no other
+arguments\&.
+.PP
+The status is zero if zle was active, else one\&.
+.RE
+.TP
+\fB\-M\fP \fIstring\fP
+As with the \fB\-R\fP option, the \fIstring\fP will be displayed below the 
+command line; unlike the \fB\-R\fP option, the string will not be put into
+the status line but will instead be printed normally below the
+prompt\&.  This means that the \fIstring\fP will still be displayed after
+the widget returns (until it is overwritten by subsequent commands)\&.
+.TP
+\fB\-U\fP \fIstring\fP
+This pushes the characters in the \fIstring\fP onto the input stack of
+ZLE\&.  After the widget currently executed finishes ZLE will behave as
+if the characters in the \fIstring\fP were typed by the user\&.
+.RS
+.PP
+As ZLE uses a stack, if this option is used repeatedly
+the last string pushed onto the stack will be processed first\&.  However,
+the characters in each \fIstring\fP will be processed in the order in which
+they appear in the string\&.
+.RE
+.TP
+\fB\-K\fP \fIkeymap\fP
+Selects the keymap named \fIkeymap\fP\&.  An error message will be displayed if
+there is no such keymap\&.
+.RS
+.PP
+This keymap selection affects the interpretation of following keystrokes
+within this invocation of ZLE\&.  Any following invocation (e\&.g\&., the next
+command line) will start as usual with the `\fBmain\fP' keymap selected\&.
+.RE
+.TP
+\fB\-F\fP [ \fB\-L\fP ] [ \fIfd\fP [ \fIhandler\fP ] ]
+Only available if your system supports one of the `poll' or `select' system
+calls; most modern systems do\&.
+.RS
+.PP
+Installs \fIhandler\fP (the name of a shell function) to handle input from
+file descriptor \fIfd\fP\&.  When zle is attempting to read data, it will
+examine both the terminal and the list of handled \fIfd\fP's\&.  If data
+becomes available on a handled \fIfd\fP, zle will call \fIhandler\fP with
+the fd which is ready for reading as the only argument\&.  If the handler
+produces output to the terminal, it should call `\fBzle \-I\fP' before doing
+so (see below)\&.  The handler should not attempt to read from the terminal\&.
+Note that zle makes no attempt to check whether this fd is actually
+readable when installing the handler\&.  The user must make their own
+arrangements for handling the file descriptor when zle is not active\&.
+.PP
+Any number of handlers for any number of readable file descriptors may be
+installed\&.  Installing a handler for an \fIfd\fP which is already handled
+causes the existing handler to be replaced\&.
+.PP
+If no \fIhandler\fP is given, but an \fIfd\fP is present, any handler for
+that \fIfd\fP is removed\&.  If there is none, an error message is printed
+and status 1 is returned\&.
+.PP
+If no arguments are given, or the \fB\-L\fP option is supplied, a list of
+handlers is printed in a form which can be stored for later execution\&.
+.PP
+An \fIfd\fP (but not a \fIhandler\fP) may optionally be given with the \fB\-L\fP
+option; in this case, the function will list the handler if any, else
+silently return status 1\&.
+.PP
+Note that this feature should be used with care\&.  Activity on one of the
+\fIfd\fP's which is not properly handled can cause the terminal to become
+unusable\&.
+.PP
+Here is a simple example of using this feature\&.  A connection to a remote
+TCP port is created using the ztcp command; see 
+the description of the \fBzsh/net/tcp\fP module in \fIzshmodules\fP(1)\&.  Then a handler is installed
+which simply prints out any data which arrives on this connection\&.  Note
+that `select' will indicate that the file descriptor needs handling
+if the remote side has closed the connection; we handle that by testing
+for a failed read\&.
+.RS
+.nf
+\fBif ztcp pwspc 2811; then
+  tcpfd=$REPLY
+  handler() {
+    zle \-I
+    local line
+    if ! read \-r line <&$1; then
+      # select marks this fd if we reach EOF,
+      # so handle this specially\&.
+      print "[Read on fd $1 failed, removing\&.]" >&2
+      zle \-F $1
+      return 1
+    fi
+    print \-r \- $line
+  }
+  zle \-F $tcpfd handler
+fi\fP
+.fi
+.RE
+.RE
+.TP
+\fB\-I\fP
+Unusually, this option is most useful outside ordinary widget functions,
+though it may be used within if normal output to the terminal is required\&.
+It invalidates the current zle display in preparation for output; typically
+this will be from a trap function\&.  It has no effect if zle is not
+active\&.  When a trap exits, the shell checks to see if the display needs
+restoring, hence the following will print output in such a way as not to
+disturb the line being edited:
+.RS
+.PP
+.RS
+.nf
+\fBTRAPUSR1() {
+    # Invalidate zle display
+  [[ \-o zle ]] && zle \-I
+    # Show output
+  print Hello
+}\fP
+.fi
+.RE
+.PP
+In general, the trap function may need to test whether zle is active before
+using this method (as shown in the example), since the \fBzsh/zle\fP module
+may not even be loaded; if it is not, the command can be skipped\&.
+.PP
+It is possible to call `\fBzle \-I\fP' several times before control is
+returned to the editor; the display will only be invalidated the first time
+to minimise disruption\&.
+.PP
+Note that there are normally better ways of manipulating the display from
+within zle widgets; see, for example, `\fBzle \-R\fP' above\&.
+.PP
+The returned status is zero if zle was invalidated, even though
+this may have been by a previous call to `\fBzle \-I\fP' or by a system
+notification\&.  To test if a zle widget may be called at this point, execute
+\fBzle\fP with no arguments and examine the return status\&.
+.RE
+.TP
+\fIwidget\fP \fB[ \-n\fP \fInum\fP \fB]\fP \fB[ \-N ]\fP \fIargs\fP \&.\&.\&.
+Invoke the specified widget\&.  This can only be done when ZLE is
+active; normally this will be within a user\-defined widget\&.
+.RS
+.PP
+With the options \fB\-n\fP and \fB\-N\fP, the current numerical argument will be
+saved and then restored after the call to \fBwidget\fP; `\fB\-n\fP \fInum\fP'
+sets the numerical argument temporarily to \fInum\fP, while `\fB\-N\fP' sets it
+to the default, i\&.e\&. as if there were none\&.
+.PP
+Any further arguments will be passed to the widget\&.  If it is a shell
+function, these are passed down as positional parameters; for builtin
+widgets it is up to the widget in question what it does with them\&.
+Currently arguments are only handled by the incremental\-search commands,
+the \fBhistory\-search\-forward\fP and \fB\-backward\fP and the corresponding
+functions prefixed by \fBvi\-\fP, and by \fBuniversal\-argument\fP\&.  No error is
+flagged if the command does not use the arguments, or only uses some of
+them\&.
+.PP
+The return status reflects the success or failure of the operation carried
+out by the widget, or if it is a user\-defined widget the return status of
+the shell function\&.  
+.PP
+A non\-zero return status causes the shell to beep when the widget exits,
+unless the \fBBEEP\fP options was unset or the widget was called via the
+\fBzle\fP command\&.  Thus if a user defined widget requires an immediate beep,
+it should call the \fBbeep\fP widget directly\&.
+.RE
+.RE
+.RE
+.RE
+.PP
+.SH "WIDGETS"
+All actions in the editor are performed by `widgets'\&.  A widget's job is
+simply to perform some small action\&.  The ZLE commands that key sequences
+in keymaps are bound to are in fact widgets\&.  Widgets can be user\-defined
+or built in\&.
+.PP
+The standard widgets built in to ZLE are listed in Standard Widgets below\&.
+Other built\-in widgets can be defined by other modules (see
+\fIzshmodules\fP(1))\&.  Each built\-in widget has two names: its normal canonical name, and the
+same name preceded by a `\fB\&.\fP'\&.  The `\fB\&.\fP' name is special: it can't be
+rebound to a different widget\&.  This makes the widget available even when
+its usual name has been redefined\&.
+.PP
+User\-defined widgets are defined using `\fBzle \-N\fP', and implemented
+as shell functions\&.  When the widget is executed, the corresponding
+shell function is executed, and can perform editing (or other) actions\&.
+It is recommended that user\-defined widgets should not have names
+starting with `\fB\&.\fP'\&.
+.SH "USER\-DEFINED WIDGETS"
+User\-defined widgets, being implemented as shell functions,
+can execute any normal shell command\&.  They can also run other widgets
+(whether built\-in or user\-defined) using the \fBzle\fP builtin command\&.
+The standard input of the function is closed to prevent external commands
+from unintentionally blocking ZLE by reading from the terminal, but
+\fBread \-k\fP or \fBread \-q\fP can be used to read characters\&.  Finally,
+they can examine and edit the ZLE buffer being edited by
+reading and setting the special parameters described below\&.
+.PP
+These special parameters are always available in widget functions, but
+are not in any way special outside ZLE\&.  If they have some normal value
+outside ZLE, that value is temporarily inaccessible, but will return
+when the widget function exits\&.  These special parameters in fact have
+local scope, like parameters created in a function using \fBlocal\fP\&.
+.PP
+Inside completion widgets and traps called while ZLE is active, these
+parameters are available read\-only\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBBUFFER\fP (scalar)
+The entire contents of the edit buffer\&.  If it is written to, the
+cursor remains at the same offset, unless that would put it outside the
+buffer\&.
+.TP
+\fBBUFFERLINES\fP (integer)
+The number of screen lines needed for the edit buffer currently
+displayed on screen (i\&.e\&. without any changes to the preceding
+parameters done after the last redisplay); read\-only\&.
+.TP
+\fBCONTEXT\fP (scalar)
+The context in which zle was called to read a line; read\-only\&.  One of
+the values:
+.PD 0
+.TP
+.PD
+start
+The start of a command line (at prompt \fBPS1\fP)\&.
+.TP
+cont
+A continuation to a command line (at prompt \fBPS2\fP)\&.
+.TP
+select
+In a \fBselect\fP loop\&.
+.TP
+vared
+Editing a variable in \fBvared\fP\&.
+.RE
+.TP
+\fBCURSOR\fP (integer)
+The offset of the cursor, within the edit buffer\&.  This is in the range
+0 to \fB$#BUFFER\fP, and is by definition equal to \fB$#LBUFFER\fP\&.
+Attempts to move the cursor outside the buffer will result in the
+cursor being moved to the appropriate end of the buffer\&.
+.TP
+\fBCUTBUFFER\fP (scalar)
+The last item to be cut using one of the `\fBkill\-\fP' commands; the
+string which the next yank would insert in the line\&.
+.TP
+\fBHISTNO\fP (integer)
+The current history number\&.  Setting this has the same effect as
+moving up or down in the history to the corresponding history line\&.
+An attempt to set it is ignored if the line is not stored in the
+history\&.  Note this is not the same as the parameter \fBHISTCMD\fP,
+which always gives the number of the history line being added to the main
+shell's history\&.  \fBHISTNO\fP refers to the line being retrieved within
+zle\&.
+.TP
+\fBKEYMAP\fP (scalar)
+The name of the currently selected keymap; read\-only\&.
+.TP
+\fBKEYS\fP (scalar)
+The keys typed to invoke this widget, as a literal string; read\-only\&.
+.TP
+\fBkillring\fP (array)
+The array of previously killed items, with the most recently killed first\&.
+This gives the items that would be retrieved by a \fByank\-pop\fP in the
+same order\&.
+.RS
+.PP
+The default size for the kill ring is eight, however the length may be
+changed by normal array operations\&.  Any empty string in the kill ring is
+ignored by the \fByank\-pop\fP command, hence the size of the array
+effectively sets the maximum length of the kill ring, while the number of
+non\-zero strings gives the current length, both as seen by the user at the
+command line\&.
+.RE
+.PP
+.TP
+\fBLASTSEARCH\fP (scalar)
+The last search string used by an interactive search ; read\-only\&.
+.TP
+\fBLASTWIDGET\fP (scalar)
+The name of the last widget that was executed; read\-only\&.
+.TP
+\fBLBUFFER\fP (scalar)
+The part of the buffer that lies to the left of the cursor position\&.
+If it is assigned to, only that part of the buffer is replaced, and the
+cursor remains between the new \fB$LBUFFER\fP and the old \fB$RBUFFER\fP\&.
+.TP
+\fBMARK\fP (integer)
+Like \fBCURSOR\fP, but for the mark\&.
+.TP
+\fBNUMERIC\fP (integer)
+The numeric argument\&. If no numeric argument was given, this parameter
+is unset\&. When this is set inside a widget function, builtin widgets
+called with the \fBzle\fP builtin command will use the value
+assigned\&. If it is unset inside a widget function, builtin widgets
+called behave as if no numeric argument was given\&.
+.TP
+\fBPENDING\fP (integer)
+The number of bytes pending for input, i\&.e\&. the number of bytes which have
+already been typed and can immediately be read\&. On systems where the shell
+is not able to get this information, this parameter will always have a
+value of zero\&.  Read\-only\&.
+.TP
+\fBPREBUFFER\fP (scalar)
+In a multi\-line input at the secondary prompt, this read\-only parameter
+contains the contents of the lines before the one the cursor is
+currently in\&.
+.TP
+\fBPREDISPLAY\fP (scalar)
+Text to be displayed before the start of the editable text buffer\&.  This
+does not have to be a complete line; to display a complete line, a newline
+must be appended explicitly\&.    The text is reset on each new invocation
+(but not recursive invocation) of zle\&.
+.TP
+\fBPOSTDISPLAY\fP (scalar)
+Text to be displayed after the end of the editable text buffer\&.  This
+does not have to be a complete line; to display a complete line, a newline
+must be prepended explicitly\&.  The text is reset on each new invocation
+(but not recursive invocation) of zle\&.
+.TP
+\fBRBUFFER\fP (scalar)
+The part of the buffer that lies to the right of the cursor position\&.
+If it is assigned to, only that part of the buffer is replaced, and the
+cursor remains between the old \fB$LBUFFER\fP and the new \fB$RBUFFER\fP\&.
+.TP
+\fBWIDGET\fP (scalar)
+The name of the widget currently being executed; read\-only\&.
+.TP
+\fBWIDGETFUNC\fP (scalar)
+The name of the shell function that implements a widget defined with
+either \fBzle \-N\fP or \fBzle \-C\fP\&.  In the former case, this is the second
+argument to the \fBzle \-N\fP command that defined the widget, or
+the first argument if there was no second argument\&.  In the latter case
+this is the the third argument to the \fBzle \-C\fP command that defined the
+widget\&.  Read\-only\&.
+.TP
+\fBWIDGETSTYLE\fP (scalar)
+Describes the implementation behind the completion widget currently being
+executed; the second argument that followed \fBzle \-C\fP when the widget was
+defined\&.  This is the name of a builtin completion widget\&.  For widgets
+defined with \fBzle \-N\fP this is set to the empty string\&.  Read\-only\&.
+.PP
+.SS "Special Widget"
+.PP
+There is one user\-defined widget which is special to the shell\&.
+If it does not exist, no special action is taken\&.  The environment
+provided is identical to that for any other editing widget\&.
+.PP
+.PD 0
+.TP
+.PD
+\fBzle\-line\-init\fP
+Executed every time the line editor is started to read a new line
+of input\&.  The following example puts the line editor into vi command
+mode when it starts up\&.
+.RS
+.PP
+.RS
+.nf
+\fBzle\-line\-init() { zle \-K vicmd; }
+zle \-N zle\-line\-init\fP
+.fi
+.RE
+.PP
+(The command inside the function sets the keymap directly; it is
+equivalent to \fBzle vi\-cmd\-mode\fP\&.)
+.RE
+.RE
+.PP
+.SH "STANDARD WIDGETS"
+The following is a list of all the standard widgets,
+and their default bindings in emacs mode,
+vi command mode and vi insert mode
+(the `\fBemacs\fP', `\fBvicmd\fP' and `\fBviins\fP' keymaps, respectively)\&.
+.PP
+Note that cursor keys are bound to movement keys in all three keymaps;
+the shell assumes that the cursor keys send the key sequences reported
+by the terminal\-handling library (termcap or terminfo)\&.  The key sequences
+shown in the list are those based on the VT100, common on many modern
+terminals, but in fact these are not necessarily bound\&.  In the case of the
+\fBviins\fP keymap, the initial escape character of the sequences serves also
+to return to the \fBvicmd\fP keymap: whether this happens is determined by
+the \fBKEYTIMEOUT\fP parameter, see \fIzshparam\fP(1)\&.
+.SS "Movement"
+.PD 0
+.TP
+.PD
+\fBvi\-backward\-blank\-word\fP (unbound) (B) (unbound)
+Move backward one word, where a word is defined as a series of
+non\-blank characters\&.
+.TP
+\fBbackward\-char\fP (^B ESC\-[D) (unbound) (unbound)
+Move backward one character\&.
+.TP
+\fBvi\-backward\-char\fP (unbound) (^H h ^?) (ESC\-[D)
+Move backward one character, without changing lines\&.
+.TP
+\fBbackward\-word\fP (ESC\-B ESC\-b) (unbound) (unbound)
+Move to the beginning of the previous word\&.
+.TP
+\fBemacs\-backward\-word\fP
+Move to the beginning of the previous word\&.
+.TP
+\fBvi\-backward\-word\fP (unbound) (b) (unbound)
+Move to the beginning of the previous word, vi\-style\&.
+.TP
+\fBbeginning\-of\-line\fP (^A) (unbound) (unbound)
+Move to the beginning of the line\&.  If already at the beginning
+of the line, move to the beginning of the previous line, if any\&.
+.TP
+\fBvi\-beginning\-of\-line\fP
+Move to the beginning of the line, without changing lines\&.
+.TP
+\fBend\-of\-line\fP (^E) (unbound) (unbound)
+Move to the end of the line\&.  If already at the end
+of the line, move to the end of the next line, if any\&.
+.TP
+\fBvi\-end\-of\-line\fP (unbound) ($) (unbound)
+Move to the end of the line\&.
+If an argument is given to this command, the cursor will be moved to
+the end of the line (argument \- 1) lines down\&.
+.TP
+\fBvi\-forward\-blank\-word\fP (unbound) (W) (unbound)
+Move forward one word, where a word is defined as a series of
+non\-blank characters\&.
+.TP
+\fBvi\-forward\-blank\-word\-end\fP (unbound) (E) (unbound)
+Move to the end of the current word, or, if at the end of the current word,
+to the end of the next word,
+where a word is defined as a series of non\-blank characters\&.
+.TP
+\fBforward\-char\fP (^F ESC\-[C) (unbound) (unbound)
+Move forward one character\&.
+.TP
+\fBvi\-forward\-char\fP (unbound) (space l) (ESC\-[C)
+Move forward one character\&.
+.TP
+\fBvi\-find\-next\-char\fP (^X^F) (f) (unbound)
+Read a character from the keyboard, and move to
+the next occurrence of it in the line\&.
+.TP
+\fBvi\-find\-next\-char\-skip\fP (unbound) (t) (unbound)
+Read a character from the keyboard, and move to
+the position just before the next occurrence of it in the line\&.
+.TP
+\fBvi\-find\-prev\-char\fP (unbound) (F) (unbound)
+Read a character from the keyboard, and move to
+the previous occurrence of it in the line\&.
+.TP
+\fBvi\-find\-prev\-char\-skip\fP (unbound) (T) (unbound)
+Read a character from the keyboard, and move to
+the position just after the previous occurrence of it in the line\&.
+.TP
+\fBvi\-first\-non\-blank\fP (unbound) (^) (unbound)
+Move to the first non\-blank character in the line\&.
+.TP
+\fBvi\-forward\-word\fP (unbound) (w) (unbound)
+Move forward one word, vi\-style\&.
+.TP
+\fBforward\-word\fP (ESC\-F ESC\-f) (unbound) (unbound)
+Move to the beginning of the next word\&.
+The editor's idea of a word is specified with the \fBWORDCHARS\fP
+parameter\&.
+.TP
+\fBemacs\-forward\-word\fP
+Move to the end of the next word\&.
+.TP
+\fBvi\-forward\-word\-end\fP (unbound) (e) (unbound)
+Move to the end of the next word\&.
+.TP
+\fBvi\-goto\-column\fP (ESC\-|) (|) (unbound)
+Move to the column specified by the numeric argument\&.
+.TP
+\fBvi\-goto\-mark\fP (unbound) (`) (unbound)
+Move to the specified mark\&.
+.TP
+\fBvi\-goto\-mark\-line\fP (unbound) (') (unbound)
+Move to beginning of the line containing the specified mark\&.
+.TP
+\fBvi\-repeat\-find\fP (unbound) (;) (unbound)
+Repeat the last \fBvi\-find\fP command\&.
+.TP
+\fBvi\-rev\-repeat\-find\fP (unbound) (,) (unbound)
+Repeat the last \fBvi\-find\fP command in the opposite direction\&.
+.SS "History Control"
+.PD 0
+.TP
+.PD
+\fBbeginning\-of\-buffer\-or\-history\fP (ESC\-<) (unbound) (unbound)
+Move to the beginning of the buffer, or if already there,
+move to the first event in the history list\&.
+.TP
+\fBbeginning\-of\-line\-hist\fP
+Move to the beginning of the line\&.  If already at the
+beginning of the buffer, move to the previous history line\&.
+.TP
+\fBbeginning\-of\-history\fP
+Move to the first event in the history list\&.
+.TP
+\fBdown\-line\-or\-history\fP (^N ESC\-[B) (j) (ESC\-[B)
+Move down a line in the buffer, or if already at the bottom line,
+move to the next event in the history list\&.
+.TP
+\fBvi\-down\-line\-or\-history\fP (unbound) (+) (unbound)
+Move down a line in the buffer, or if already at the bottom line,
+move to the next event in the history list\&.
+Then move to the first non\-blank character on the line\&.
+.TP
+\fBdown\-line\-or\-search\fP
+Move down a line in the buffer, or if already at the bottom line,
+search forward in the history for a line beginning with the first
+word in the buffer\&.
+.RS
+.PP
+If called from a function by the \fBzle\fP command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer\&.
+.RE
+.TP
+\fBdown\-history\fP (unbound) (^N) (unbound)
+Move to the next event in the history list\&.
+.TP
+\fBhistory\-beginning\-search\-backward\fP
+Search backward in the history for a line beginning with the current
+line up to the cursor\&.
+This leaves the cursor in its original position\&.
+.TP
+\fBend\-of\-buffer\-or\-history\fP (ESC\->) (unbound) (unbound)
+Move to the end of the buffer, or if already there,
+move to the last event in the history list\&.
+.TP
+\fBend\-of\-line\-hist\fP
+Move to the end of the line\&.  If already at the end of
+the buffer, move to the next history line\&.
+.TP
+\fBend\-of\-history\fP
+Move to the last event in the history list\&.
+.TP
+\fBvi\-fetch\-history\fP (unbound) (G) (unbound)
+Fetch the history line specified by the numeric argument\&.
+This defaults to the current history line
+(i\&.e\&. the one that isn't history yet)\&.
+.TP
+\fBhistory\-incremental\-search\-backward\fP (^R ^Xr) (unbound) (unbound)
+Search backward incrementally for a specified string\&.  The search is
+case\-insensitive if the search string does not have uppercase letters and no
+numeric argument was given\&.  The string may begin with `\fB^\fP' to anchor the
+search to the beginning of the line\&.
+.RS
+.PP
+A restricted set of editing functions
+is available in the mini\-buffer\&.  An interrupt signal, as defined by the stty
+setting, will stop the search and go back to the original line\&.  An undefined
+key will have the same effect\&. The supported functions are:
+\fBbackward\-delete\-char\fP,
+\fBvi\-backward\-delete\-char\fP,
+\fBclear\-screen\fP,
+\fBredisplay\fP,
+\fBquoted\-insert\fP,
+\fBvi\-quoted\-insert\fP,
+\fBaccept\-and\-hold\fP,
+\fBaccept\-and\-infer\-next\-history\fP,
+\fBaccept\-line\fP and
+\fBaccept\-line\-and\-down\-history\fP\&.
+.PP
+\fBmagic\-space\fP just inserts a space\&.
+\fBvi\-cmd\-mode\fP toggles between the `\fBmain\fP' and `\fBvicmd\fP' keymaps;
+the `\fBmain\fP' keymap (insert mode) will be selected initially\&.
+\fBhistory\-incremental\-search\-backward\fP will get the
+next occurrence of the contents of the mini\-buffer\&.
+\fBhistory\-incremental\-search\-forward\fP inverts the sense of the search\&.
+\fBvi\-repeat\-search\fP and \fBvi\-rev\-repeat\-search\fP are similarly supported\&.
+The direction of the search is indicated in the mini\-buffer\&.
+.PP
+Any multi\-character string
+that is not bound to one of the above functions will beep and interrupt the
+search, leaving the last found line in the buffer\&. Any single character that
+is not bound to one of the above functions, or \fBself\-insert\fP or
+\fBself\-insert\-unmeta\fP, will have the same effect but the function will be
+executed\&.
+.PP
+When called from a widget function by the \fBzle\fP command, the incremental
+search commands can take a string argument\&.  This will be treated as a
+string of keys, as for arguments to the \fBbindkey\fP command, and used as
+initial input for the command\&.  Any characters in the string which are
+unused by the incremental search will be silently ignored\&.  For example,
+.PP
+.RS
+.nf
+\fBzle history\-incremental\-search\-backward forceps\fP
+.fi
+.RE
+.PP
+will search backwards for \fBforceps\fP, leaving the minibuffer containing
+the string `\fBforceps\fP'\&.
+.RE
+.TP
+\fBhistory\-incremental\-search\-forward\fP (^S ^Xs) (unbound) (unbound)
+Search forward incrementally for a specified string\&.  The search is
+case\-insensitive if the search string does not have uppercase letters and no
+numeric argument was given\&.  The string may begin with `\fB^\fP' to anchor the
+search to the beginning of the line\&.  The functions available in the
+mini\-buffer are the same as for \fBhistory\-incremental\-search\-backward\fP\&.
+.TP
+\fBhistory\-search\-backward\fP (ESC\-P ESC\-p) (unbound) (unbound)
+Search backward in the history for a line beginning with the first
+word in the buffer\&.
+.RS
+.PP
+If called from a function by the \fBzle\fP command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer\&.
+.RE
+.TP
+\fBvi\-history\-search\-backward\fP (unbound) (/) (unbound)
+Search backward in the history for a specified string\&.
+The string may begin with `\fB^\fP' to anchor the search to the
+beginning of the line\&.
+.RS
+.PP
+A restricted set of editing functions is available in
+the mini\-buffer\&.  An interrupt signal, as defined by the stty setting,  will
+stop the search\&.
+The functions available in the mini\-buffer are:
+\fBaccept\-line\fP,
+\fBbackward\-delete\-char\fP,
+\fBvi\-backward\-delete\-char\fP,
+\fBbackward\-kill\-word\fP,
+\fBvi\-backward\-kill\-word\fP,
+\fBclear\-screen\fP,
+\fBredisplay\fP,
+\fBquoted\-insert\fP
+and
+\fBvi\-quoted\-insert\fP\&.
+.PP
+\fBvi\-cmd\-mode\fP is treated the same as accept\-line, and
+\fBmagic\-space\fP is treated as a space\&.
+Any other character that is not bound to self\-insert or
+self\-insert\-unmeta will beep and be ignored\&. If the function is called from vi
+command mode, the bindings of the current insert mode will be used\&.
+.PP
+If called from a function by the \fBzle\fP command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer\&.
+.RE
+.TP
+\fBhistory\-search\-forward\fP (ESC\-N ESC\-n) (unbound) (unbound)
+Search forward in the history for a line beginning with the first
+word in the buffer\&.
+.RS
+.PP
+If called from a function by the \fBzle\fP command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer\&.
+.RE
+.TP
+\fBvi\-history\-search\-forward\fP (unbound) (?) (unbound)
+Search forward in the history for a specified string\&.
+The string may begin with `\fB^\fP' to anchor the search to the
+beginning of the line\&. The functions available in the mini\-buffer are the same
+as for \fBvi\-history\-search\-backward\fP\&.  Argument handling is also the same
+as for that command\&.
+.TP
+\fBinfer\-next\-history\fP (^X^N) (unbound) (unbound)
+Search in the history list for a line matching the current one and
+fetch the event following it\&.
+.TP
+\fBinsert\-last\-word\fP (ESC\-_ ESC\-\&.) (unbound) (unbound)
+Insert the last word from the previous history event at the
+cursor position\&.  If a positive numeric argument is given,
+insert that word from the end of the previous history event\&.
+If the argument is zero or negative insert that word from the
+left (zero inserts the previous command word)\&.  Repeating this command
+replaces the word just inserted with the last word from the
+history event prior to the one just used; numeric arguments can be used in
+the same way to pick a word from that event\&.
+.RS
+.PP
+When called from a shell function invoked from a user\-defined widget, the
+command can take one to three arguments\&.  The first argument specifies a
+history offset which applies to successive calls to this widget: if is \-1,
+the default behaviour is used, while if it is 1, successive calls will move
+forwards through the history\&.  The value 0 can be used to indicate that the
+history line examined by the previous execution of the command will be
+reexamined\&.  Note that negative numbers should be preceded with a
+`\fB\-\fP\fB\-\fP' argument to avoid confusing them with options\&.
+.PP
+If two arguments are given, the second specifies the word on the command
+line in normal array index notation (as a more natural alternative to the
+prefix argument)\&.  Hence 1 is the first word, and \-1 (the default) is the
+last word\&.
+.PP
+If a third argument is given, its value is ignored, but it is used to
+signify that the history offset is relative to the current history line,
+rather than the one remembered after the previous invocations of
+\fBinsert\-last\-word\fP\&.
+.PP
+For example, the default behaviour of the command corresponds to
+.PP
+.RS
+.nf
+\fBzle insert\-last\-word \-\- \-1 \-1\fP
+.fi
+.RE
+.PP
+while the command
+.PP
+.RS
+.nf
+\fBzle insert\-last\-word \-\- \-1 1 \-\fP
+.fi
+.RE
+.PP
+always copies the first word of the line in the history immediately before
+the line being edited\&.  This has the side effect that later invocations of
+the widget will be relative to that line\&.
+.RE
+.TP
+\fBvi\-repeat\-search\fP (unbound) (n) (unbound)
+Repeat the last vi history search\&.
+.TP
+\fBvi\-rev\-repeat\-search\fP (unbound) (N) (unbound)
+Repeat the last vi history search, but in reverse\&.
+.TP
+\fBup\-line\-or\-history\fP (^P ESC\-[A) (k) (ESC\-[A)
+Move up a line in the buffer, or if already at the top line,
+move to the previous event in the history list\&.
+.TP
+\fBvi\-up\-line\-or\-history\fP (unbound) (\-) (unbound)
+Move up a line in the buffer, or if already at the top line,
+move to the previous event in the history list\&.
+Then move to the first non\-blank character on the line\&.
+.TP
+\fBup\-line\-or\-search\fP
+Move up a line in the buffer, or if already at the top line,
+search backward in the history for a line beginning with the
+first word in the buffer\&.
+.RS
+.PP
+If called from a function by the \fBzle\fP command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer\&.
+.RE
+.TP
+\fBup\-history\fP (unbound) (^P) (unbound)
+Move to the previous event in the history list\&.
+.TP
+\fBhistory\-beginning\-search\-forward\fP
+Search forward in the history for a line beginning with the current
+line up to the cursor\&.
+This leaves the cursor in its original position\&.
+.SS "Modifying Text"
+.PD 0
+.TP
+.PD
+\fBvi\-add\-eol\fP (unbound) (A) (unbound)
+Move to the end of the line and enter insert mode\&.
+.TP
+\fBvi\-add\-next\fP (unbound) (a) (unbound)
+Enter insert mode after the current cursor position, without changing lines\&.
+.TP
+\fBbackward\-delete\-char\fP (^H ^?) (unbound) (unbound)
+Delete the character behind the cursor\&.
+.TP
+\fBvi\-backward\-delete\-char\fP (unbound) (X) (^H)
+Delete the character behind the cursor, without changing lines\&.
+If in insert mode, this won't delete past the point where insert mode was
+last entered\&.
+.TP
+\fBbackward\-delete\-word\fP
+Delete the word behind the cursor\&.
+.TP
+\fBbackward\-kill\-line\fP
+Kill from the beginning of the line to the cursor position\&.
+.TP
+\fBbackward\-kill\-word\fP (^W ESC\-^H ESC\-^?) (unbound) (unbound)
+Kill the word behind the cursor\&.
+.TP
+\fBvi\-backward\-kill\-word\fP (unbound) (unbound) (^W)
+Kill the word behind the cursor, without going past the point where insert
+mode was last entered\&.
+.TP
+\fBcapitalize\-word\fP (ESC\-C ESC\-c) (unbound) (unbound)
+Capitalize the current word and move past it\&.
+.TP
+\fBvi\-change\fP (unbound) (c) (unbound)
+Read a movement command from the keyboard, and kill
+from the cursor position to the endpoint of the movement\&.
+Then enter insert mode\&.
+If the command is \fBvi\-change\fP, change the current line\&.
+.TP
+\fBvi\-change\-eol\fP (unbound) (C) (unbound)
+Kill to the end of the line and enter insert mode\&.
+.TP
+\fBvi\-change\-whole\-line\fP (unbound) (S) (unbound)
+Kill the current line and enter insert mode\&.
+.TP
+\fBcopy\-region\-as\-kill\fP (ESC\-W ESC\-w) (unbound) (unbound)
+Copy the area from the cursor to the mark to the kill buffer\&.
+.TP
+\fBcopy\-prev\-word\fP (ESC\-^_) (unbound) (unbound)
+Duplicate the word to the left of the cursor\&.
+.TP
+\fBcopy\-prev\-shell\-word\fP
+Like \fBcopy\-prev\-word\fP, but the word is found by using shell parsing, 
+whereas \fBcopy\-prev\-word\fP looks for blanks\&. This makes a difference
+when the word is quoted and contains spaces\&.
+.TP
+\fBvi\-delete\fP (unbound) (d) (unbound)
+Read a movement command from the keyboard, and kill
+from the cursor position to the endpoint of the movement\&.
+If the command is \fBvi\-delete\fP, kill the current line\&.
+.TP
+\fBdelete\-char\fP
+Delete the character under the cursor\&.
+.TP
+\fBvi\-delete\-char\fP (unbound) (x) (unbound)
+Delete the character under the cursor,
+without going past the end of the line\&.
+.TP
+\fBdelete\-word\fP
+Delete the current word\&.
+.TP
+\fBdown\-case\-word\fP (ESC\-L ESC\-l) (unbound) (unbound)
+Convert the current word to all lowercase and move past it\&.
+.TP
+\fBkill\-word\fP (ESC\-D ESC\-d) (unbound) (unbound)
+Kill the current word\&.
+.TP
+\fBgosmacs\-transpose\-chars\fP
+Exchange the two characters behind the cursor\&.
+.TP
+\fBvi\-indent\fP (unbound) (>) (unbound)
+Indent a number of lines\&.
+.TP
+\fBvi\-insert\fP (unbound) (i) (unbound)
+Enter insert mode\&.
+.TP
+\fBvi\-insert\-bol\fP (unbound) (I) (unbound)
+Move to the first non\-blank character on the line and enter insert mode\&.
+.TP
+\fBvi\-join\fP (^X^J) (J) (unbound)
+Join the current line with the next one\&.
+.TP
+\fBkill\-line\fP (^K) (unbound) (unbound)
+Kill from the cursor to the end of the line\&.
+If already on the end of the line, kill the newline character\&.
+.TP
+\fBvi\-kill\-line\fP (unbound) (unbound) (^U)
+Kill from the cursor back to wherever insert mode was last entered\&.
+.TP
+\fBvi\-kill\-eol\fP (unbound) (D) (unbound)
+Kill from the cursor to the end of the line\&.
+.TP
+\fBkill\-region\fP
+Kill from the cursor to the mark\&.
+.TP
+\fBkill\-buffer\fP (^X^K) (unbound) (unbound)
+Kill the entire buffer\&.
+.TP
+\fBkill\-whole\-line\fP (^U) (unbound) (unbound)
+Kill the current line\&.
+.TP
+\fBvi\-match\-bracket\fP (^X^B) (%) (unbound)
+Move to the bracket character (one of \fB{}\fP, \fB()\fP or \fB[]\fP) that
+matches the one under the cursor\&.
+If the cursor is not on a bracket character, move forward without going
+past the end of the line to find one, and then go to the matching bracket\&.
+.TP
+\fBvi\-open\-line\-above\fP (unbound) (O) (unbound)
+Open a line above the cursor and enter insert mode\&.
+.TP
+\fBvi\-open\-line\-below\fP (unbound) (o) (unbound)
+Open a line below the cursor and enter insert mode\&.
+.TP
+\fBvi\-oper\-swap\-case\fP
+Read a movement command from the keyboard, and swap
+the case of all characters
+from the cursor position to the endpoint of the movement\&.
+If the movement command is \fBvi\-oper\-swap\-case\fP,
+swap the case of all characters on the current line\&.
+.TP
+\fBoverwrite\-mode\fP (^X^O) (unbound) (unbound)
+Toggle between overwrite mode and insert mode\&.
+.TP
+\fBvi\-put\-before\fP (unbound) (P) (unbound)
+Insert the contents of the kill buffer before the cursor\&.
+If the kill buffer contains a sequence of lines (as opposed to characters),
+paste it above the current line\&.
+.TP
+\fBvi\-put\-after\fP (unbound) (p) (unbound)
+Insert the contents of the kill buffer after the cursor\&.
+If the kill buffer contains a sequence of lines (as opposed to characters),
+paste it below the current line\&.
+.TP
+\fBquoted\-insert\fP (^V) (unbound) (unbound)
+Insert the next character typed into the buffer literally\&.
+An interrupt character will not be inserted\&.
+.TP
+\fBvi\-quoted\-insert\fP (unbound) (unbound) (^Q ^V)
+Display a `\fB^\fP' at the cursor position, and
+insert the next character typed into the buffer literally\&.
+An interrupt character will not be inserted\&.
+.TP
+\fBquote\-line\fP (ESC\-') (unbound) (unbound)
+Quote the current line; that is, put a `\fB'\fP' character at the
+beginning and the end, and convert all `\fB'\fP' characters
+to `\fB'\e''\fP'\&.
+.TP
+\fBquote\-region\fP (ESC\-") (unbound) (unbound)
+Quote the region from the cursor to the mark\&.
+.TP
+\fBvi\-replace\fP (unbound) (R) (unbound)
+Enter overwrite mode\&.
+.TP
+\fBvi\-repeat\-change\fP (unbound) (\&.) (unbound)
+Repeat the last vi mode text modification\&.
+If a count was used with the modification, it is remembered\&.
+If a count is given to this command, it overrides the remembered count,
+and is remembered for future uses of this command\&.
+The cut buffer specification is similarly remembered\&.
+.TP
+\fBvi\-replace\-chars\fP (unbound) (r) (unbound)
+Replace the character under the cursor with a character
+read from the keyboard\&.
+.TP
+\fBself\-insert\fP (printable characters) (unbound) (printable characters and some control characters)
+Insert a character into the buffer at the cursor position\&.
+.TP
+\fBself\-insert\-unmeta\fP (ESC\-^I ESC\-^J ESC\-^M) (unbound) (unbound)
+Insert a character into the buffer after stripping the meta bit
+and converting ^M to ^J\&.
+.TP
+\fBvi\-substitute\fP (unbound) (s) (unbound)
+Substitute the next character(s)\&.
+.TP
+\fBvi\-swap\-case\fP (unbound) (~) (unbound)
+Swap the case of the character under the cursor and move past it\&.
+.TP
+\fBtranspose\-chars\fP (^T) (unbound) (unbound)
+Exchange the two characters to the left of the
+cursor if at end of line, else exchange the
+character under the cursor with the character
+to the left\&.
+.TP
+\fBtranspose\-words\fP (ESC\-T ESC\-t) (unbound) (unbound)
+Exchange the current word with the one before it\&.
+.TP
+\fBvi\-unindent\fP (unbound) (<) (unbound)
+Unindent a number of lines\&.
+.TP
+\fBup\-case\-word\fP (ESC\-U ESC\-u) (unbound) (unbound)
+Convert the current word to all caps and move past it\&.
+.TP
+\fByank\fP (^Y) (unbound) (unbound)
+Insert the contents of the kill buffer at the cursor position\&.
+.TP
+\fByank\-pop\fP (ESC\-y) (unbound) (unbound)
+Remove the text just yanked, rotate the kill\-ring,
+and yank the new top\&.  Only works following
+\fByank\fP or \fByank\-pop\fP\&.
+.TP
+\fBvi\-yank\fP (unbound) (y) (unbound)
+Read a movement command from the keyboard, and copy the region
+from the cursor position to the endpoint of the movement
+into the kill buffer\&.
+If the command is \fBvi\-yank\fP, copy the current line\&.
+.TP
+\fBvi\-yank\-whole\-line\fP (unbound) (Y) (unbound)
+Copy the current line into the kill buffer\&.
+.TP
+\fBvi\-yank\-eol\fP
+Copy the region from the cursor position to the end of the line
+into the kill buffer\&.
+Arguably, this is what Y should do in vi, but it isn't what it actually does\&.
+.SS "Arguments"
+.PD 0
+.TP
+.PD
+\fBdigit\-argument\fP (ESC\-0\&.\&.ESC\-9) (1\-9) (unbound)
+Start a new numeric argument, or add to the current one\&.
+See also \fBvi\-digit\-or\-beginning\-of\-line\fP\&.  This only works if bound to a
+key sequence ending in a decimal digit\&.
+.RS
+.PP
+Inside a widget function, a call to this function treats the last key of
+the key sequence which called the widget as the digit\&.
+.RE
+.TP
+\fBneg\-argument\fP (ESC\-\-) (unbound) (unbound)
+Changes the sign of the following argument\&.
+.TP
+\fBuniversal\-argument\fP
+Multiply the argument of the next command by 4\&.  Alternatively, if
+this command is followed by an integer (positive or negative), use
+that as the argument for the next command\&.  Thus digits cannot be
+repeated using this command\&.  For example, if this command occurs
+twice, followed immediately by \fBforward\-char\fP, move forward sixteen
+spaces; if instead it is followed by \fB\-2\fP, then \fBforward\-char\fP,
+move backward two spaces\&.
+.RS
+.PP
+Inside a widget function, if passed an argument, i\&.e\&. `\fBzle
+universal\-argument\fP \fInum\fP', the numerical argument will be set to
+\fInum\fP; this is equivalent to `\fBNUMERIC=\fP\fInum\fP'\&.
+.RE
+.RE
+.SS "Completion"
+.PD 0
+.TP
+.PD
+\fBaccept\-and\-menu\-complete\fP
+In a menu completion, insert the current completion into the buffer,
+and advance to the next possible completion\&.
+.TP
+\fBcomplete\-word\fP
+Attempt completion on the current word\&.
+.TP
+\fBdelete\-char\-or\-list\fP (^D) (unbound) (unbound)
+Delete the character under the cursor\&.  If the cursor
+is at the end of the line, list possible completions for the
+current word\&.
+.TP
+\fBexpand\-cmd\-path\fP
+Expand the current command to its full pathname\&.
+.TP
+\fBexpand\-or\-complete\fP (TAB) (unbound) (TAB)
+Attempt shell expansion on the current word\&.
+If that fails,
+attempt completion\&.
+.TP
+\fBexpand\-or\-complete\-prefix\fP
+Attempt shell expansion on the current word up to cursor\&.
+.TP
+\fBexpand\-history\fP (ESC\-space ESC\-!) (unbound) (unbound)
+Perform history expansion on the edit buffer\&.
+.TP
+\fBexpand\-word\fP (^X*) (unbound) (unbound)
+Attempt shell expansion on the current word\&.
+.TP
+\fBlist\-choices\fP (ESC\-^D) (^D =) (^D)
+List possible completions for the current word\&.
+.TP
+\fBlist\-expand\fP (^Xg ^XG) (^G) (^G)
+List the expansion of the current word\&.
+.TP
+\fBmagic\-space\fP
+Perform history expansion and insert a space into the
+buffer\&.  This is intended to be bound to space\&.
+.TP
+\fBmenu\-complete\fP
+Like \fBcomplete\-word\fP, except that menu completion is used\&.
+See the \fBMENU_COMPLETE\fP option\&.
+.TP
+\fBmenu\-expand\-or\-complete\fP
+Like \fBexpand\-or\-complete\fP, except that menu completion is used\&.
+.TP
+\fBreverse\-menu\-complete\fP
+Perform menu completion, like \fBmenu\-complete\fP, except that if
+a menu completion is already in progress, move to the \fIprevious\fP
+completion rather than the next\&.
+.TP
+\fBend\-of\-list\fP
+When a previous completion displayed a list below the prompt, this
+widget can be used to move the prompt below the list\&.
+.SS "Miscellaneous"
+.PD 0
+.TP
+.PD
+\fBaccept\-and\-hold\fP (ESC\-A ESC\-a) (unbound) (unbound)
+Push the contents of the buffer on the buffer stack
+and execute it\&.
+.TP
+\fBaccept\-and\-infer\-next\-history\fP
+Execute the contents of the buffer\&.
+Then search the history list for a line matching the current one
+and push the event following onto the buffer stack\&.
+.TP
+\fBaccept\-line\fP (^J ^M) (^J ^M) (^J ^M)
+Finish editing the buffer\&.  Normally this causes the buffer to be
+executed as a shell command\&.
+.TP
+\fBaccept\-line\-and\-down\-history\fP (^O) (unbound) (unbound)
+Execute the current line, and push the next history
+event on the the buffer stack\&.
+.TP
+\fBbeep\fP
+Beep, unless the \fBBEEP\fP option is unset\&.
+.TP
+\fBvi\-cmd\-mode\fP (^X^V) (unbound) (^[)
+Enter command mode; that is, select the `\fBvicmd\fP' keymap\&.
+Yes, this is bound by default in emacs mode\&.
+.TP
+\fBvi\-caps\-lock\-panic\fP
+Hang until any lowercase key is pressed\&.
+This is for vi users without the mental capacity to keep
+track of their caps lock key (like the author)\&.
+.TP
+\fBclear\-screen\fP (^L ESC\-^L) (^L) (^L)
+Clear the screen and redraw the prompt\&.
+.TP
+\fBdescribe\-key\-briefly\fP
+Reads a key sequence, then prints the function bound to that sequence\&.
+.TP
+\fBexchange\-point\-and\-mark\fP (^X^X) (unbound) (unbound)
+Exchange the cursor position with the position of the mark\&.
+.TP
+\fBexecute\-named\-cmd\fP (ESC\-x) (unbound) (unbound)
+Read the name of an editor command and
+execute it\&.  A restricted set of editing functions is available in the
+mini\-buffer\&.  An interrupt signal, as defined by the stty setting, will
+abort the function\&. The allowed functions are:
+\fBbackward\-delete\-char\fP,
+\fBvi\-backward\-delete\-char\fP,
+\fBclear\-screen\fP,
+\fBredisplay\fP,
+\fBquoted\-insert\fP,
+\fBvi\-quoted\-insert\fP,
+\fBbackward\-kill\-word\fP,
+\fBvi\-backward\-kill\-word\fP,
+\fBkill\-whole\-line\fP,
+\fBvi\-kill\-line\fP,
+\fBbackward\-kill\-line\fP,
+\fBlist\-choices\fP,
+\fBdelete\-char\-or\-list\fP,
+\fBcomplete\-word\fP,
+\fBaccept\-line\fP,
+\fBexpand\-or\-complete\fP and
+\fBexpand\-or\-complete\-prefix\fP\&.
+.RS
+.PP
+\fBkill\-region\fP kills the last word,
+and vi\-cmd\-mode is treated the same as accept\-line\&.
+The space and tab characters, if not bound to one of
+these functions, will complete the name and then list the
+possibilities if the \fBAUTO_LIST\fP option is set\&.
+Any other character that is not bound to \fBself\-insert\fP or
+\fBself\-insert\-unmeta\fP will beep and be ignored\&.
+The bindings of the current insert mode will be used\&.
+.RE
+.TP
+\fBexecute\-last\-named\-cmd\fP (ESC\-z) (unbound) (unbound)
+Redo the last function executed with \fBexecute\-named\-cmd\fP\&.
+.TP
+\fBget\-line\fP (ESC\-G ESC\-g) (unbound) (unbound)
+Pop the top line off the buffer stack and insert it at the
+cursor position\&.
+.TP
+\fBpound\-insert\fP (unbound) (#) (unbound)
+If there is no # character at the beginning of the buffer,
+add one to the beginning of each line\&.
+If there is one, remove a # from each line that has one\&.
+In either case, accept the current line\&.
+The \fBINTERACTIVE_COMMENTS\fP option must be set
+for this to have any usefulness\&.
+.TP
+\fBvi\-pound\-insert\fP
+If there is no # character at the beginning of the current line,
+add one\&.  If there is one, remove it\&.
+The \fBINTERACTIVE_COMMENTS\fP option must be set
+for this to have any usefulness\&.
+.TP
+\fBpush\-input\fP
+Push the entire current multiline construct onto the buffer stack and
+return to the top\-level (\fBPS1\fP) prompt\&.
+If the current parser construct is only a single line, this is exactly
+like \fBpush\-line\fP\&.
+Next time the editor starts up or is popped with \fBget\-line\fP, the
+construct will be popped off the top of the buffer stack and loaded
+into the editing buffer\&.
+.TP
+\fBpush\-line\fP (^Q ESC\-Q ESC\-q) (unbound) (unbound)
+Push the current buffer onto the buffer stack and clear
+the buffer\&.
+Next time the editor starts up, the buffer will be popped
+off the top of the buffer stack and loaded into the editing
+buffer\&.
+.TP
+\fBpush\-line\-or\-edit\fP
+At the top\-level (\fBPS1\fP) prompt, equivalent to \fBpush\-line\fP\&.
+At a secondary (\fBPS2\fP) prompt, move the entire current multiline
+construct into the editor buffer\&.
+The latter is equivalent to \fBpush\-input\fP followed by \fBget\-line\fP\&.
+.TP
+\fBrecursive\-edit\fP
+Only useful from a user\-defined widget\&.  At this point in the function,
+the editor regains control until one of the standard widgets which would
+normally cause zle to exit (typically an \fBaccept\-line\fP caused by
+hitting the return key) is executed\&.  Instead, control returns to the
+user\-defined widget\&.  The status returned is non\-zero if the return was
+caused by an error, but the function still continues executing and hence
+may tidy up\&.  This makes it safe for the user\-defined widget to alter
+the command line or key bindings temporarily\&.
+.RS
+.PP
+The following widget, \fBcaps\-lock\fP, serves as an example\&.
+.RS
+.nf
+\fBself\-insert\-ucase() {
+  LBUFFER+=${(U)KEYS[\-1]}
+}
+.PP
+integer stat
+.PP
+zle \-N self\-insert self\-insert\-ucase
+zle \-A caps\-lock save\-caps\-lock
+zle \-A accept\-line caps\-lock
+.PP
+zle recursive\-edit
+stat=$?
+.PP
+zle \-A \&.self\-insert self\-insert
+zle \-A save\-caps\-lock caps\-lock
+zle \-D save\-caps\-lock
+.PP
+(( stat )) && zle send\-break
+.PP
+return $stat
+\fP
+.fi
+.RE
+This causes typed letters to be inserted capitalised until either
+\fBaccept\-line\fP (i\&.e\&. typically the return key) is typed or the
+\fBcaps\-lock\fP widget is invoked again; the later is handled by saving
+the old definition of \fBcaps\-lock\fP as \fBsave\-caps\-lock\fP and then
+rebinding it to invoke \fBaccept\-line\fP\&.  Note that an error from the
+recursive edit is detected as a non\-zero return status and propagated by
+using the \fBsend\-break\fP widget\&.
+.RE
+.TP
+\fBredisplay\fP (unbound) (^R) (^R)
+Redisplays the edit buffer\&.
+.TP
+\fBreset\-prompt\fP (unbound) (unbound) (unbound)
+Force the prompts on both the left and right of the screen to be
+re\-expanded, then redisplay the edit buffer\&.  This
+reflects changes both to the prompt variables themselves and changes
+in the expansion of the values (for example, changes in time or
+directory, or changes to the value of variables referred to by the
+prompt)\&.
+.RS
+.PP
+Otherwise, the prompt is only expanded each time zle starts, and
+when the display as been interrupted by output from another part of the
+shell (such as a job notification) which causes the command line to be
+reprinted\&.
+.RE
+.TP
+\fBsend\-break\fP (^G ESC\-^G) (unbound) (unbound)
+Abort the current editor function, e\&.g\&. \fBexecute\-named\-command\fP, or the
+editor itself, e\&.g\&. if you are in \fBvared\fP\&. Otherwise abort the parsing of
+the current line\&.
+.TP
+\fBrun\-help\fP (ESC\-H ESC\-h) (unbound) (unbound)
+Push the buffer onto the buffer stack, and execute the
+command `\fBrun\-help\fP \fIcmd\fP', where \fIcmd\fP is the current
+command\&.  \fBrun\-help\fP is normally aliased to \fBman\fP\&.
+.TP
+\fBvi\-set\-buffer\fP (unbound) (") (unbound)
+Specify a buffer to be used in the following command\&.
+There are 35 buffers that can be specified:
+the 26 `named' buffers \fB"a\fP to \fB"z\fP
+and the nine `queued' buffers \fB"1\fP to \fB"9\fP\&.  The named buffers can also
+be specified as \fB"A\fP to \fB"Z\fP\&.
+.RS
+.PP
+When a buffer is specified for a cut command, the text being cut replaces
+the previous contents of the specified buffer\&.  If a named buffer
+is specified using a capital, the newly cut text is appended to the buffer
+instead of overwriting it\&.
+.PP
+If no buffer is specified for a cut command, \fB"1\fP is used, and the
+contents of \fB"1\fP to \fB"8\fP are each shifted along one buffer; the contents of
+\fB"9\fP is lost\&.
+.RE
+.TP
+\fBvi\-set\-mark\fP (unbound) (m) (unbound)
+Set the specified mark at the cursor position\&.
+.TP
+\fBset\-mark\-command\fP (^@) (unbound) (unbound)
+Set the mark at the cursor position\&.
+.TP
+\fBspell\-word\fP (ESC\-$ ESC\-S ESC\-s) (unbound) (unbound)
+Attempt spelling correction on the current word\&.
+.TP
+\fBundefined\-key\fP
+This command is executed when a key sequence that is not bound to any
+command is typed\&.  By default it beeps\&.
+.TP
+\fBundo\fP (^_ ^Xu ^X^U) (unbound) (unbound)
+Incrementally undo the last text modification\&.
+.TP
+\fBredo\fP
+Incrementally redo undone text modifications\&.
+.TP
+\fBvi\-undo\-change\fP (unbound) (u) (unbound)
+Undo the last text modification\&.
+If repeated, redo the modification\&.
+.TP
+\fBwhat\-cursor\-position\fP (^X=) (unbound) (unbound)
+Print the character under the cursor, its code as an octal, decimal and
+hexadecimal number, the current cursor position within the buffer and the
+column of the cursor in the current line\&.
+.TP
+\fBwhere\-is\fP
+Read the name of an editor command and and print the listing of key
+sequences that invoke the specified command\&.
+.TP
+\fBwhich\-command\fP (ESC\-?) (unbound) (unbound)
+Push the buffer onto the buffer stack, and execute the
+command `\fBwhich\-command\fP \fIcmd\fP'\&. where \fIcmd\fP is the current
+command\&.  \fBwhich\-command\fP is normally aliased to \fIwhence\fP\&.
+.TP
+\fBvi\-digit\-or\-beginning\-of\-line\fP (unbound) (0) (unbound)
+If the last command executed was a digit as part of an argument,
+continue the argument\&.  Otherwise, execute vi\-beginning\-of\-line\&.
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zshall.1
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zshall.1
@@ -0,0 +1,530 @@
+.TH "ZSHALL" "1" "August 16, 2004" "zsh 4\&.2\&.1-dev-1"
+.SH "NAME"
+zshall \- the Z shell meta\-man page
+.\" Yodl file: Zsh/intro.yo
+.SH "OVERVIEW"
+Because zsh contains many features, the zsh manual has been split into
+a number of sections\&.  This manual page includes all the separate manual pages in the
+following order:
+.PP
+.PD 0
+.TP
+\fIzshmisc\fP      Anything not fitting into the other sections
+.TP
+\fIzshexpn\fP      Zsh command and parameter expansion
+.TP
+\fIzshparam\fP     Zsh parameters
+.TP
+\fIzshoptions\fP   Zsh options
+.TP
+\fIzshbuiltins\fP  Zsh built\-in functions
+.TP
+\fIzshzle\fP       Zsh command line editing
+.TP
+\fIzshcompwid\fP   Zsh completion widgets
+.TP
+\fIzshcompsys\fP   Zsh completion system
+.TP
+\fIzshcompctl\fP   Zsh completion control
+.TP
+\fIzshmodules\fP   Zsh loadable modules
+.TP
+\fIzshzftpsys\fP   Zsh built\-in FTP client
+.PD
+.SH "DESCRIPTION"
+Zsh is a UNIX command interpreter (shell) usable as an interactive
+login shell and as a shell script command processor\&.  Of the standard shells,
+zsh most closely resembles \fBksh\fP but includes many enhancements\&.  Zsh
+has command line editing, builtin spelling correction, programmable
+command completion, shell functions (with autoloading), a history
+mechanism, and a host of other features\&.
+.\" Yodl file: Zsh/metafaq.yo
+.SH "AUTHOR"
+Zsh was originally written by Paul Falstad \fB<pf@zsh\&.org>\fP\&.
+Zsh is now maintained by the members of the zsh\-workers mailing
+list \fB<zsh\-workers@sunsite\&.dk>\fP\&.  The development is currently
+coordinated by Peter Stephenson \fB<pws@zsh\&.org>\fP\&.  The coordinator
+can be contacted at \fB<coordinator@zsh\&.org>\fP, but matters relating to
+the code should generally go to the mailing list\&.
+.SH "AVAILABILITY"
+Zsh is available from the following anonymous FTP sites\&.  These mirror
+sites are kept frequently up to date\&.  The sites marked with \fI(H)\fP may be
+mirroring \fBftp\&.cs\&.elte\&.hu\fP instead of the primary site\&.
+.PP
+.PD 0
+.TP
+.PD
+Primary site
+.nf
+\fBftp://ftp\&.zsh\&.org/pub/zsh/\fP
+\fBhttp://www\&.zsh\&.org/pub/zsh/\fP
+.fi
+.TP
+Australia
+.nf
+\fBftp://ftp\&.zsh\&.org/pub/zsh/\fP
+\fBhttp://www\&.zsh\&.org/pub/zsh/\fP
+.fi
+.TP
+Denmark
+.nf
+\fBftp://sunsite\&.dk/pub/unix/shells/zsh/\fP
+.fi
+.TP
+Finland
+.nf
+\fBftp://ftp\&.funet\&.fi/pub/unix/shells/zsh/\fP
+.fi
+.TP
+Germany
+.nf
+\fBftp://ftp\&.fu\-berlin\&.de/pub/unix/shells/zsh/\fP  \fI(H)\fP
+\fBftp://ftp\&.gmd\&.de/packages/zsh/\fP
+\fBftp://ftp\&.uni\-trier\&.de/pub/unix/shell/zsh/\fP
+.fi
+.TP
+Hungary
+.nf
+\fBftp://ftp\&.cs\&.elte\&.hu/pub/zsh/\fP
+\fBhttp://www\&.cs\&.elte\&.hu/pub/zsh/\fP
+\fBftp://ftp\&.kfki\&.hu/pub/packages/zsh/\fP
+.fi
+.TP
+Israel
+.nf
+\fBftp://ftp\&.math\&.technion\&.ac\&.il/pub/zsh/\fP
+\fBhttp://www\&.math\&.technion\&.ac\&.il/pub/zsh/\fP
+.fi
+.TP
+Japan
+.nf
+\fBftp://ftp\&.win\&.ne\&.jp/pub/shell/zsh/\fP
+\fBftp://ftp\&.ayamura\&.org/pub/zsh/\fP
+.fi
+.TP
+Korea
+.nf
+\fBftp://linux\&.sarang\&.net/mirror/system/shell/zsh/\fP
+.fi
+.TP
+Netherlands
+.nf
+\fBftp://ftp\&.demon\&.nl/pub/mirrors/zsh/\fP
+.fi
+.TP
+Norway
+.nf
+\fBftp://ftp\&.uit\&.no/pub/unix/shells/zsh/\fP
+.fi
+.TP
+Poland
+.nf
+\fBftp://sunsite\&.icm\&.edu\&.pl/pub/unix/shells/zsh/\fP
+.fi
+.TP
+Romania
+.nf
+\fBftp://ftp\&.roedu\&.net/pub/mirrors/ftp\&.zsh\&.org/pub/zsh/\fP
+\fBftp://ftp\&.kappa\&.ro/pub/mirrors/ftp\&.zsh\&.org/pub/zsh/\fP
+.fi
+.TP
+Slovenia
+.nf
+\fBftp://ftp\&.siol\&.net/mirrors/zsh/\fP
+.fi
+.TP
+Sweden
+.nf
+\fBftp://ftp\&.lysator\&.liu\&.se/pub/unix/zsh/\fP
+.fi
+.TP
+UK
+.nf
+\fBftp://ftp\&.net\&.lut\&.ac\&.uk/zsh/\fP
+\fBftp://sunsite\&.org\&.uk/packages/zsh/\fP
+.fi
+.TP
+USA
+.nf
+\fBftp://uiarchive\&.uiuc\&.edu/mirrors/ftp/ftp\&.zsh\&.org/pub/\fP
+\fBftp://ftp\&.rge\&.com/pub/shells/zsh/\fP
+\fBhttp://zsh\&.disillusion\&.org/\fP
+\fBhttp://foad\&.org/zsh/\fP
+.fi
+.PP
+The up\-to\-date source code is available via anonymous CVS from Sourceforge\&.
+See \fBhttp://sourceforge\&.net/projects/zsh/\fP for details\&.
+.PP
+.SH "MAILING LISTS"
+Zsh has 3 mailing lists:
+.PP
+.PD 0
+.TP
+.PD
+\fB<zsh\-announce@sunsite\&.dk>\fP
+Announcements about releases, major changes in the shell and the
+monthly posting of the Zsh FAQ\&.  (moderated)
+.TP
+\fB<zsh\-users@sunsite\&.dk>\fP
+User discussions\&.
+.TP
+\fB<zsh\-workers@sunsite\&.dk>\fP
+Hacking, development, bug reports and patches\&.
+.PP
+To subscribe or unsubscribe, send mail
+to the associated administrative address for the mailing list\&.
+.PP
+.PD 0
+.TP
+\fB<zsh\-announce\-subscribe@sunsite\&.dk>\fP
+.TP
+\fB<zsh\-users\-subscribe@sunsite\&.dk>\fP
+.TP
+\fB<zsh\-workers\-subscribe@sunsite\&.dk>\fP
+.PP
+.TP
+\fB<zsh\-announce\-unsubscribe@sunsite\&.dk>\fP
+.TP
+\fB<zsh\-users\-unsubscribe@sunsite\&.dk>\fP
+.TP
+\fB<zsh\-workers\-unsubscribe@sunsite\&.dk>\fP
+.PD
+.PP
+YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED\&.
+All submissions to \fBzsh\-announce\fP are automatically forwarded to
+\fBzsh\-users\fP\&.  All submissions to \fBzsh\-users\fP are automatically
+forwarded to \fBzsh\-workers\fP\&.
+.PP
+If you have problems subscribing/unsubscribing to any of the mailing
+lists, send mail to \fB<listmaster@zsh\&.org>\fP\&.  The mailing lists are
+maintained by Karsten Thygesen \fB<karthy@kom\&.auc\&.dk>\fP\&.
+.PP
+The mailing lists are archived; the archives can be accessed via the
+administrative addresses listed above\&.  There is also a hypertext
+archive, maintained by Geoff Wing \fB<gcw@zsh\&.org>\fP, available at
+\fBhttp://www\&.zsh\&.org/mla/\fP\&.
+.SH "THE ZSH FAQ"
+Zsh has a list of Frequently Asked Questions (FAQ), maintained by
+Peter Stephenson \fB<pws@zsh\&.org>\fP\&.  It is regularly posted to the
+newsgroup \fBcomp\&.unix\&.shell\fP and the \fBzsh\-announce\fP mailing list\&.
+The latest version can be found at any of the Zsh FTP sites, or at
+\fBhttp://www\&.zsh\&.org/FAQ/\fP\&.  The contact address for FAQ\-related matters
+is \fB<faqmaster@zsh\&.org>\fP\&.
+.SH "THE ZSH WEB PAGE"
+Zsh has a web page which is located at \fBhttp://www\&.zsh\&.org/\fP\&.  This is
+maintained by Karsten Thygesen \fB<karthy@zsh\&.org>\fP, of SunSITE Denmark\&.
+The contact address for web\-related matters is \fB<webmaster@zsh\&.org>\fP\&.
+.SH "THE ZSH USERGUIDE"
+A userguide is currently in preparation\&.  It is intended to complement the
+manual, with explanations and hints on issues where the manual can be
+cabbalistic, hierographic, or downright mystifying (for example, the word
+`hierographic' does not exist)\&.  It can be viewed in its current state at
+\fBhttp://zsh\&.sunsite\&.dk/Guide/\fP\&.  At the time of writing, chapters
+dealing with startup files and their contents and the new completion system
+were essentially complete\&.
+.SH "THE ZSH WIKI"
+A `wiki' website for zsh has been created at \fBhttp://www\&.zshwiki\&.org/\fP\&.
+This is a site which can be added to and modified directly by users without
+any special permission\&.  You can add your own zsh tips and configurations\&.
+.\" Yodl file: Zsh/invoke.yo
+.SH "INVOCATION OPTIONS"
+The following flags are interpreted by the shell when invoked to determine
+where the shell will read commands from:
+.PP
+.PD 0
+.TP
+.PD
+\fB\-c\fP
+Take the first argument as a command to execute, rather than reading commands
+from a script or standard input\&.  If any further arguments are given, the
+first one is assigned to \fB$0\fP, rather than being used as a positional
+parameter\&.
+.TP
+\fB\-i\fP
+Force shell to be interactive\&.
+.TP
+\fB\-s\fP
+Force shell to read commands from the standard input\&.
+If the \fB\-s\fP flag is not present and an argument is given,
+the first argument is taken to be the pathname of a script to
+execute\&.
+.PP
+After the first one or two arguments have been appropriated as described above,
+the remaining arguments are assigned to the positional parameters\&.
+.PP
+For further options, which are common to invocation and the \fBset\fP
+builtin, see
+\fIzshoptions\fP(1)\&.
+.PP
+Options may be specified by name using the \fB\-o\fP option\&.  \fB\-o\fP acts like
+a single\-letter option, but takes a following string as the option name\&.
+For example,
+.PP
+.RS
+.nf
+\fBzsh \-x \-o shwordsplit scr\fP
+.fi
+.RE
+.PP
+runs the script \fBscr\fP, setting the \fBXTRACE\fP option by the corresponding
+letter `\fB\-x\fP' and the \fBSH_WORD_SPLIT\fP option by name\&.
+Options may be turned \fIoff\fP by name by using \fB+o\fP instead of \fB\-o\fP\&.
+\fB\-o\fP can be stacked up with preceding single\-letter options, so for example
+`\fB\-xo shwordsplit\fP' or `\fB\-xoshwordsplit\fP' is equivalent to
+`\fB\-x \-o shwordsplit\fP'\&.
+.PP
+Options may also be specified by name in GNU long option style,
+`\fB\-\-\fP\fIoption\-name\fP'\&.  When this is done, `\fB\-\fP' characters in the
+option name are permitted: they are translated into `\fB_\fP', and thus ignored\&.
+So, for example, `\fBzsh \-\-sh\-word\-split\fP' invokes zsh with the
+\fBSH_WORD_SPLIT\fP option turned on\&.  Like other option syntaxes, options can
+be turned off by replacing the initial `\fB\-\fP' with a `\fB+\fP'; thus
+`\fB+\-sh\-word\-split\fP' is equivalent to `\fB\-\-no\-sh\-word\-split\fP'\&.
+Unlike other option syntaxes, GNU\-style long options cannot be stacked with
+any other options, so for example `\fB\-x\-shwordsplit\fP' is an error,
+rather than being treated like `\fB\-x \-\-shwordsplit\fP'\&.
+.PP
+The special GNU\-style option `\fB\-\-version\fP' is handled; it sends to standard
+output the shell's version information, then exits successfully\&.
+`\fB\-\-help\fP' is also handled; it sends to standard output a list of options
+that can be used when invoking the shell, then exits successfully\&.
+.PP
+Option processing may be finished, allowing following arguments that start with
+`\fB\-\fP' or `\fB+\fP' to be treated as normal arguments, in two ways\&.
+Firstly, a lone `\fB\-\fP' (or `\fB+\fP') as an argument by itself ends option
+processing\&.  Secondly, a special option `\fB\-\-\fP' (or `\fB+\-\fP'), which may
+be specified on its own (which is the standard POSIX usage) or may be stacked
+with preceding options (so `\fB\-x\-\fP' is equivalent to `\fB\-x \-\-\fP')\&.  Options
+are not permitted to be stacked after `\fB\-\-\fP' (so `\fB\-x\-f\fP' is an error),
+but note the GNU\-style option form discussed above, where `\fB\-\-shwordsplit\fP'
+is permitted and does not end option processing\&.
+.PP
+Except when the \fBsh\fP/\fBksh\fP emulation single\-letter options are in effect,
+the option `\fB\-b\fP' (or `\fB+b\fP') ends option processing\&.
+`\fB\-b\fP' is like `\fB\-\fP\fB\-\fP', except that further single\-letter options
+can be stacked after the `\fB\-b\fP' and will take effect as normal\&.
+.PP
+.PP
+.\" Yodl file: Zsh/compat.yo
+.SH "COMPATIBILITY"
+Zsh tries to emulate \fBsh\fP or \fBksh\fP when it is invoked as
+\fBsh\fP or \fBksh\fP respectively; more precisely, it looks at the first
+letter of the name by which it was invoked, excluding any initial `\fBr\fP'
+(assumed to stand for `restricted'), and if that is `\fBs\fP' or `\fBk\fP' it
+will emulate \fBsh\fP or \fBksh\fP\&.  Furthermore, if invoked as \fBsu\fP (which
+happens on certain systems when the shell is executed by the \fBsu\fP
+command), the shell will try to find an alternative name from the \fBSHELL\fP
+environment variable and perform emulation based on that\&.
+.PP
+In \fBsh\fP and \fBksh\fP compatibility modes the following
+parameters are not special and not initialized by the shell:
+\fBARGC\fP,
+\fBargv\fP,
+\fBcdpath\fP,
+\fBfignore\fP,
+\fBfpath\fP,
+\fBHISTCHARS\fP,
+\fBmailpath\fP,
+\fBMANPATH\fP,
+\fBmanpath\fP,
+\fBpath\fP,
+\fBprompt\fP,
+\fBPROMPT\fP,
+\fBPROMPT2\fP,
+\fBPROMPT3\fP,
+\fBPROMPT4\fP,
+\fBpsvar\fP,
+\fBstatus\fP,
+\fBwatch\fP\&.
+.PP
+The usual zsh startup/shutdown scripts are not executed\&.  Login shells
+source \fB/etc/profile\fP followed by \fB$HOME/\&.profile\fP\&.  If the
+\fBENV\fP environment variable is set on invocation, \fB$ENV\fP is sourced
+after the profile scripts\&.  The value of \fBENV\fP is subjected to
+parameter expansion, command substitution, and arithmetic expansion
+before being interpreted as a pathname\&.  Note that the \fBPRIVILEGED\fP
+option also affects the execution of startup files\&.
+.PP
+The following options are set if the shell is invoked as \fBsh\fP or
+\fBksh\fP:
+\fBNO_BAD_PATTERN\fP,
+\fBNO_BANG_HIST\fP,
+\fBNO_BG_NICE\fP,
+\fBNO_EQUALS\fP,
+\fBNO_FUNCTION_ARGZERO\fP,
+\fBGLOB_SUBST\fP,
+\fBNO_GLOBAL_EXPORT\fP,
+\fBNO_HUP\fP,
+\fBINTERACTIVE_COMMENTS\fP,
+\fBKSH_ARRAYS\fP,
+\fBNO_MULTIOS\fP,
+\fBNO_NOMATCH\fP,
+\fBNO_NOTIFY\fP,
+\fBPOSIX_BUILTINS\fP,
+\fBNO_PROMPT_PERCENT\fP,
+\fBRM_STAR_SILENT\fP,
+\fBSH_FILE_EXPANSION\fP,
+\fBSH_GLOB\fP,
+\fBSH_OPTION_LETTERS\fP,
+\fBSH_WORD_SPLIT\fP\&.
+Additionally the \fBBSD_ECHO\fP and \fBIGNORE_BRACES\fP
+options are set if zsh is invoked as \fBsh\fP\&.
+Also, the
+\fBKSH_OPTION_PRINT\fP,
+\fBLOCAL_OPTIONS\fP,
+\fBPROMPT_BANG\fP,
+\fBPROMPT_SUBST\fP
+and
+\fBSINGLE_LINE_ZLE\fP
+options are set if zsh is invoked as \fBksh\fP\&.
+.\" Yodl file: Zsh/restricted.yo
+.SH "RESTRICTED SHELL"
+When the basename of the command used to invoke zsh starts with the letter
+`\fBr\fP' or the `\fB\-r\fP' command line option is supplied at invocation, the
+shell becomes restricted\&.  Emulation mode is determined after stripping the
+letter `\fBr\fP' from the invocation name\&.  The following are disabled in
+restricted mode:
+.PP
+.PD 0
+.TP
+.PD
+\(bu
+changing directories with the \fBcd\fP builtin
+.TP
+\(bu
+changing or unsetting the \fBPATH\fP, \fBpath\fP, \fBMODULE_PATH\fP,
+\fBmodule_path\fP, \fBSHELL\fP, \fBHISTFILE\fP, \fBHISTSIZE\fP, \fBGID\fP, \fBEGID\fP,
+\fBUID\fP, \fBEUID\fP, \fBUSERNAME\fP, \fBLD_LIBRARY_PATH\fP,
+\fBLD_AOUT_LIBRARY_PATH\fP, \fBLD_PRELOAD\fP and  \fBLD_AOUT_PRELOAD\fP
+parameters
+.TP
+\(bu
+specifying command names containing \fB/\fP
+.TP
+\(bu
+specifying command pathnames using \fBhash\fP
+.TP
+\(bu
+redirecting output to files
+.TP
+\(bu
+using the \fBexec\fP builtin command to replace the shell with another
+command
+.TP
+\(bu
+using \fBjobs \-Z\fP to overwrite the shell process' argument and
+environment space
+.TP
+\(bu
+using the \fBARGV0\fP parameter to override \fBargv[0]\fP for external
+commands
+.TP
+\(bu
+turning off restricted mode with \fBset +r\fP or \fBunsetopt
+RESTRICTED\fP
+.PP
+These restrictions are enforced after processing the startup files\&.  The
+startup files should set up \fBPATH\fP to point to a directory of commands
+which can be safely invoked in the restricted environment\&.  They may also
+add further restrictions by disabling selected builtins\&.
+.PP
+Restricted mode can also be activated any time by setting the
+\fBRESTRICTED\fP option\&.  This immediately enables all the restrictions
+described above even if the shell still has not processed all startup
+files\&.
+.\" Yodl file: Zsh/files.yo
+.SH "STARTUP/SHUTDOWN FILES"
+Commands are first read from \fB/etc/zshenv\fP; this cannot be overridden\&.
+Subsequent behaviour is modified by the \fBRCS\fP and
+\fBGLOBAL_RCS\fP options; the former affects all startup files, while the
+second only affects those in the \fB/etc\fP directory\&.  If one of the options
+is unset at any point, any subsequent startup file(s) of the corresponding
+type will not be read\&.  It is also possible for a file in \fB$ZDOTDIR\fP to
+re\-enable \fBGLOBAL_RCS\fP\&. Both \fBRCS\fP and \fBGLOBAL_RCS\fP are set by
+default\&.
+.PP
+Commands are then read from \fB$ZDOTDIR/\&.zshenv\fP\&.
+If the shell is a login shell, commands
+are read from \fB/etc/zprofile\fP and then \fB$ZDOTDIR/\&.zprofile\fP\&.
+Then, if the shell is interactive,
+commands are read from \fB/etc/zshrc\fP and then \fB$ZDOTDIR/\&.zshrc\fP\&.
+Finally, if the shell is a login shell, \fB/etc/zlogin\fP and
+\fB$ZDOTDIR/\&.zlogin\fP are read\&.
+.PP
+When a login shell exits, the files \fB$ZDOTDIR/\&.zlogout\fP and then
+\fB/etc/zlogout\fP are read\&.  This happens with either an explicit exit
+via the \fBexit\fP or \fBlogout\fP commands, or an implicit exit by reading
+end\-of\-file from the terminal\&.  However, if the shell terminates due
+to \fBexec\fP'ing another process, the logout files are not read\&.
+These are also affected by the \fBRCS\fP and \fBGLOBAL_RCS\fP options\&.
+Note also that the \fBRCS\fP option affects the saving of history files,
+i\&.e\&. if \fBRCS\fP is unset when the shell exits, no history file will be
+saved\&.
+.PP
+If \fBZDOTDIR\fP is unset, \fBHOME\fP is used instead\&.
+Those files listed above as being in \fB/etc\fP may be in another
+directory, depending on the installation\&.
+.PP
+As \fB/etc/zshenv\fP is run for all instances of zsh, it is important that
+it be kept as small as possible\&.  In particular, it is a good idea to
+put code that does not need to be run for every single shell behind
+a test of the form `\fBif [[ \-o rcs ]]; then \&.\&.\&.\fP' so that it will not
+be executed when zsh is invoked with the `\fB\-f\fP' option\&.
+.PP
+Any of these files may be pre\-compiled with the \fBzcompile\fP builtin
+command (see \fIzshbuiltins\fP(1))\&.  If a compiled file exists (named for the original file plus the
+\fB\&.zwc\fP extension) and it is newer than the original file, the compiled
+file will be used instead\&.
+.so man1/zshmisc.1
+.so man1/zshexpn.1
+.so man1/zshparam.1
+.so man1/zshoptions.1
+.so man1/zshbuiltins.1
+.so man1/zshzle.1
+.so man1/zshcompwid.1
+.so man1/zshcompsys.1
+.so man1/zshcompctl.1
+.so man1/zshmodules.1
+.so man1/zshtcpsys.1
+.so man1/zshzftpsys.1
+.so man1/zshcontrib.1
+.TH "ZSHALL" "1" "August 16, 2004" "zsh 4\&.2\&.1\-dev\-1"
+.\" Yodl file: Zsh/filelist.yo
+.SH "FILES"
+.PD 0
+.TP
+\fB$ZDOTDIR/\&.zshenv\fP
+.TP
+\fB$ZDOTDIR/\&.zprofile\fP
+.TP
+\fB$ZDOTDIR/\&.zshrc\fP
+.TP
+\fB$ZDOTDIR/\&.zlogin\fP
+.TP
+\fB$ZDOTDIR/\&.zlogout\fP
+.TP
+\fB${TMPPREFIX}*\fP   (default is /tmp/zsh*)
+.TP
+\fB/etc/zshenv\fP
+.TP
+\fB/etc/zprofile\fP
+.TP
+\fB/etc/zshrc\fP
+.TP
+\fB/etc/zlogin\fP
+.TP
+\fB/etc/zlogout\fP    (installation\-specific \- \fB/etc\fP is the default)
+.PD
+.\" Yodl file: Zsh/seealso.yo
+.SH "SEE ALSO"
+\fIsh\fP(1),
+\fIcsh\fP(1),
+\fItcsh\fP(1),
+\fIrc\fP(1),
+\fIbash\fP(1),
+\fIksh\fP(1)
+.PP
+\fBIEEE Standard for information Technology \-
+Portable Operating System Interface (POSIX) \-
+Part 2: Shell and Utilities\fP,
+IEEE Inc, 1993, ISBN 1\-55937\-255\-9\&.
--- zsh-beta-4.3.0-dev-1+20050424.orig/Doc/zsh.texi
+++ zsh-beta-4.3.0-dev-1+20050424/Doc/zsh.texi
@@ -0,0 +1,26122 @@
+
+\input texinfo.tex
+@c %**start of header
+@iftex
+@afourpaper
+@setchapternewpage off
+@end iftex
+@setfilename zsh.info
+@settitle zsh
+@c %**end of header
+
+@ifinfo
+@set dsq '@:'
+@set dsbq `@:`
+@end ifinfo
+@iftex
+@set dsq '{}'
+@set dsbq `{}`
+@end iftex
+@ifinfo
+@dircategory Utilities
+@direntry
+     * ZSH: (zsh).                     The Z Shell Manual.
+@end direntry
+@end ifinfo
+
+@noindent
+@iftex
+@finalout
+@end iftex
+@titlepage
+@title The Z Shell Manual
+@subtitle Version 4.2.1-dev-1
+@subtitle Updated August 16, 2004
+@author Original documentation by Paul Falstad
+@page
+This is a texinfo version of the documentation for the Z Shell, originally by 
+Paul Falstad.
+
+@noindent
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@noindent
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+@noindent
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end titlepage
+@c Yodl file: Zsh/manual.yo
+@ifnottex
+@node Top, The Z Shell Manual, (dir), (dir)
+@top The Z Shell Manual
+@end ifnottex
+@ifinfo
+This Info file documents Zsh, a freely available UNIX command interpreter
+(shell), which of the standard shells most closely resembles the Korn shell
+(ksh), although it is not completely compatible.
+
+@noindent
+@cindex version
+Version 4.2.1-dev-1, last updated August 16, 2004.
+@end ifinfo
+
+@noindent
+@menu
+* The Z Shell Manual::
+* Introduction::
+* Invocation::
+* Files::
+* Shell Grammar::
+* Redirection::
+* Command Execution::
+* Functions::
+* Jobs & Signals::
+* Arithmetic Evaluation::
+* Conditional Expressions::
+* Prompt Expansion::
+* Expansion::
+* Parameters::
+* Options::
+* Shell Builtin Commands::
+* Zsh Line Editor::
+* Completion Widgets::
+* Completion System::
+* Completion Using compctl::
+* Zsh Modules::
+* TCP Function System::
+* Zftp Function System::
+* User Contributions::
+
+@noindent
+--- Indices ---
+
+@noindent
+* Concept Index::
+* Variables Index::
+* Options Index::
+* Functions Index::
+* Editor Functions Index::
+* Style and Tag Index::
+
+@noindent
+--- The Detailed Node Listing ---
+
+@noindent
+Introduction
+
+@noindent
+* Author::
+* Availability::
+* Mailing Lists::
+* The Zsh FAQ::
+* The Zsh Web Page::
+* The Zsh Userguide::
+* See Also::
+
+@noindent
+Invocation
+
+@noindent
+* Compatibility::
+* Restricted Shell::
+
+@noindent
+Shell Grammar
+
+@noindent
+* Simple Commands & Pipelines::
+* Precommand Modifiers::
+* Complex Commands::
+* Alternate Forms For Complex Commands::
+* Reserved Words::
+* Comments::
+* Aliasing::
+* Quoting::
+
+@noindent
+Expansion
+
+@noindent
+* History Expansion::
+* Process Substitution::
+* Parameter Expansion::
+* Command Substitution::
+* Arithmetic Expansion::
+* Brace Expansion::
+* Filename Expansion::
+* Filename Generation::
+
+@noindent
+Parameters
+
+@noindent
+* Array Parameters::
+* Positional Parameters::
+* Local Parameters::
+* Parameters Set By The Shell::
+* Parameters Used By The Shell::
+
+@noindent
+Options
+
+@noindent
+* Specifying Options::
+* Description of Options::
+* Option Aliases::
+* Single Letter Options::
+
+@noindent
+Zsh Line Editor
+
+@noindent
+* Movement::
+* History Control::
+* Modifying Text::
+* Arguments::
+* Completion::
+* Miscellaneous::
+
+@noindent
+Completion Widgets
+
+@noindent
+* Special Parameters::
+* Builtin Commands::
+* Condition Codes::
+* Matching Control::
+* Completion Widget Example::
+
+@noindent
+Completion System
+
+@noindent
+* Initialization::
+* Completion System Configuration::
+* Control Functions::
+* Bindable Commands::
+* Completion Functions::
+* Completion Directories::
+
+@noindent
+Completion Using compctl
+
+@noindent
+* Command Flags::
+* Option Flags::
+* Alternative Completion::
+* Extended Completion::
+* Example::
+
+@noindent
+Zsh Modules
+
+@noindent
+@c Yodl file: Zsh/manmodmenu.yo
+* The zsh/cap Module::
+* The zsh/clone Module::
+* The zsh/compctl Module::
+* The zsh/complete Module::
+* The zsh/complist Module::
+* The zsh/computil Module::
+* The zsh/datetime Module::
+* The zsh/deltochar Module::
+* The zsh/example Module::
+* The zsh/files Module::
+* The zsh/mapfile Module::
+* The zsh/mathfunc Module::
+* The zsh/parameter Module::
+* The zsh/pcre Module::
+* The zsh/sched Module::
+* The zsh/net/socket Module::
+* The zsh/stat Module::
+* The zsh/system Module::
+* The zsh/net/tcp Module::
+* The zsh/termcap Module::
+* The zsh/terminfo Module::
+* The zsh/zftp Module::
+* The zsh/zle Module::
+* The zsh/zleparameter Module::
+* The zsh/zprof Module::
+* The zsh/zpty Module::
+* The zsh/zselect Module::
+* The zsh/zutil Module::
+@c (avoiding a yodl bug)
+
+@noindent
+TCP Function System
+
+@noindent
+* TCP Functions::
+* TCP Parameters::
+* TCP Examples::
+* TCP Bugs::
+
+@noindent
+Zftp Function System
+
+@noindent
+* Installation::
+* Zftp Functions::
+* Miscellaneous Features::
+
+@noindent
+User Contributions
+
+@noindent
+* Utilities::
+* Prompt Themes::
+* ZLE Functions::
+* Other Functions::
+
+@noindent
+@end menu
+@node The Z Shell Manual, Introduction, Top, Top
+
+@chapter The Z Shell Manual
+@noindent
+This document has been produced from the texinfo file @t{zsh.texi},
+included in the @t{Doc} sub-directory of the Zsh distribution.
+
+@section Producing documentation from zsh.texi
+@noindent
+The texinfo source may be converted into several formats:
+
+@noindent
+@table @asis
+@item The Info manual
+The Info format allows searching for topics, commands, functions, etc.
+from the many Indices. The command `@t{makeinfo zsh.texi}' is used to
+produce the Info documentation.
+
+@item The printed manual
+The command `@t{texi2dvi zsh.texi}' will output @t{zsh.dvi} which can
+then be processed with @cite{dvips} and optionally @cite{gs} (Ghostscript) to
+produce a nicely formatted printed manual.
+
+@item The HTML manual
+An HTML version of this manual is available at the Zsh web site via:
+
+@noindent
+@t{http://zsh.sunsite.dk/Doc/}.
+
+@noindent
+(The HTML version is produced with @cite{texi2html}, which may be obtained
+from @t{http://www.mathematik.uni-kl.de/~obachman/Texi2html/}. The command is
+`@t{texi2html -split chapter -expand info zsh.texi}'.  If necessary,
+upgrade to version 1.64 of texi2html.)
+
+@end table
+
+@noindent
+For those who do not have the necessary tools to process texinfo,
+precompiled documentation (PostScript, dvi, info and HTML formats)
+is available from the zsh archive site or its mirrors, in the file
+@t{zsh-doc.tar.gz}. (See @ref{Availability} for a list of sites.)
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/intro.yo
+@node Introduction, Invocation, The Z Shell Manual, Top
+
+@chapter Introduction
+@noindent
+@cindex introduction
+Zsh is a UNIX command interpreter (shell) usable as an interactive
+login shell and as a shell script command processor.  Of the standard shells,
+zsh most closely resembles @cite{ksh} but includes many enhancements.  Zsh
+has command line editing, builtin spelling correction, programmable
+command completion, shell functions (with autoloading), a history
+mechanism, and a host of other features.
+@c Yodl file: Zsh/metafaq.yo
+@menu
+* Author::
+* Availability::
+* Mailing Lists::
+* The Zsh FAQ::
+* The Zsh Web Page::
+* The Zsh Userguide::
+* See Also::
+@end menu
+@node Author, Availability, , Introduction
+
+@section Author
+@noindent
+@cindex author
+Zsh was originally written by Paul Falstad @t{<pf@@zsh.org>}.
+Zsh is now maintained by the members of the zsh-workers mailing
+list @t{<zsh-workers@@sunsite.dk>}.  The development is currently
+coordinated by Peter Stephenson @t{<pws@@zsh.org>}.  The coordinator
+can be contacted at @t{<coordinator@@zsh.org>}, but matters relating to
+the code should generally go to the mailing list.
+@node Availability, Mailing Lists, Author, Introduction
+
+@section Availability
+@noindent
+Zsh is available from the following anonymous FTP sites.  These mirror
+sites are kept frequently up to date.  The sites marked with @emph{(H)} may be
+mirroring @t{ftp.cs.elte.hu} instead of the primary site.
+
+@noindent
+@cindex FTP sites for zsh
+@cindex acquiring zsh by FTP
+@cindex availability of zsh
+@table @asis
+@item Primary site
+@t{ftp://ftp.zsh.org/pub/zsh/}@*
+@t{http://www.zsh.org/pub/zsh/}
+
+@item Australia
+@t{ftp://ftp.zsh.org/pub/zsh/}@*
+@t{http://www.zsh.org/pub/zsh/}
+
+@item Denmark
+@t{ftp://sunsite.dk/pub/unix/shells/zsh/}
+
+@item Finland
+@t{ftp://ftp.funet.fi/pub/unix/shells/zsh/}
+
+@item Germany
+@t{ftp://ftp.fu-berlin.de/pub/unix/shells/zsh/}  @emph{(H)}@*
+@t{ftp://ftp.gmd.de/packages/zsh/}@*
+@t{ftp://ftp.uni-trier.de/pub/unix/shell/zsh/}
+
+@item Hungary
+@t{ftp://ftp.cs.elte.hu/pub/zsh/}@*
+@t{http://www.cs.elte.hu/pub/zsh/}@*
+@t{ftp://ftp.kfki.hu/pub/packages/zsh/}
+
+@item Israel
+@t{ftp://ftp.math.technion.ac.il/pub/zsh/}@*
+@t{http://www.math.technion.ac.il/pub/zsh/}
+
+@item Japan
+@t{ftp://ftp.win.ne.jp/pub/shell/zsh/}@*
+@t{ftp://ftp.ayamura.org/pub/zsh/}
+
+@item Korea
+@t{ftp://linux.sarang.net/mirror/system/shell/zsh/}
+
+@item Netherlands
+@t{ftp://ftp.demon.nl/pub/mirrors/zsh/}
+
+@item Norway
+@t{ftp://ftp.uit.no/pub/unix/shells/zsh/}
+
+@item Poland
+@t{ftp://sunsite.icm.edu.pl/pub/unix/shells/zsh/}
+
+@item Romania
+@t{ftp://ftp.roedu.net/pub/mirrors/ftp.zsh.org/pub/zsh/}@*
+@t{ftp://ftp.kappa.ro/pub/mirrors/ftp.zsh.org/pub/zsh/}
+
+@item Slovenia
+@t{ftp://ftp.siol.net/mirrors/zsh/}
+
+@item Sweden
+@t{ftp://ftp.lysator.liu.se/pub/unix/zsh/}
+
+@item UK
+@t{ftp://ftp.net.lut.ac.uk/zsh/}@*
+@t{ftp://sunsite.org.uk/packages/zsh/}
+
+@item USA
+@t{ftp://uiarchive.uiuc.edu/mirrors/ftp/ftp.zsh.org/pub/}@*
+@t{ftp://ftp.rge.com/pub/shells/zsh/}@*
+@t{http://zsh.disillusion.org/}@*
+@t{http://foad.org/zsh/}
+
+@end table
+
+@noindent
+The up-to-date source code is available via anonymous CVS from Sourceforge.
+See @t{http://sourceforge.net/projects/zsh/} for details.
+
+@noindent
+@node Mailing Lists, The Zsh FAQ, Availability, Introduction
+
+@section Mailing Lists
+@noindent
+@cindex mailing lists
+Zsh has 3 mailing lists:
+
+@noindent
+@table @asis
+@item @t{<zsh-announce@@sunsite.dk>}
+Announcements about releases, major changes in the shell and the
+monthly posting of the Zsh FAQ.  (moderated)
+
+@item @t{<zsh-users@@sunsite.dk>}
+User discussions.
+
+@item @t{<zsh-workers@@sunsite.dk>}
+Hacking, development, bug reports and patches.
+
+@end table
+
+@noindent
+To subscribe or unsubscribe, send mail
+to the associated administrative address for the mailing list.
+
+@noindent
+@table @asis
+@item @t{<zsh-announce-subscribe@@sunsite.dk>}
+@item @t{<zsh-users-subscribe@@sunsite.dk>}
+@item @t{<zsh-workers-subscribe@@sunsite.dk>}
+
+@noindent
+@item @t{<zsh-announce-unsubscribe@@sunsite.dk>}
+@item @t{<zsh-users-unsubscribe@@sunsite.dk>}
+@item @t{<zsh-workers-unsubscribe@@sunsite.dk>}
+@item
+@end table
+
+@noindent
+YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED.
+All submissions to @cite{zsh-announce} are automatically forwarded to
+@cite{zsh-users}.  All submissions to @cite{zsh-users} are automatically
+forwarded to @cite{zsh-workers}.
+
+@noindent
+If you have problems subscribing/unsubscribing to any of the mailing
+lists, send mail to @t{<listmaster@@zsh.org>}.  The mailing lists are
+maintained by Karsten Thygesen @t{<karthy@@kom.auc.dk>}.
+
+@noindent
+The mailing lists are archived; the archives can be accessed via the
+administrative addresses listed above.  There is also a hypertext
+archive, maintained by Geoff Wing @t{<gcw@@zsh.org>}, available at
+@t{http://www.zsh.org/mla/}.
+@node The Zsh FAQ, The Zsh Web Page, Mailing Lists, Introduction
+
+@section The Zsh FAQ
+@noindent
+Zsh has a list of Frequently Asked Questions (FAQ), maintained by
+Peter Stephenson @t{<pws@@zsh.org>}.  It is regularly posted to the
+newsgroup @cite{comp.unix.shell} and the @cite{zsh-announce} mailing list.
+The latest version can be found at any of the Zsh FTP sites, or at
+@t{http://www.zsh.org/FAQ/}.  The contact address for FAQ-related matters
+is @t{<faqmaster@@zsh.org>}.
+@node The Zsh Web Page, The Zsh Userguide, The Zsh FAQ, Introduction
+
+@section The Zsh Web Page
+@noindent
+Zsh has a web page which is located at @t{http://www.zsh.org/}.  This is
+maintained by Karsten Thygesen @t{<karthy@@zsh.org>}, of SunSITE Denmark.
+The contact address for web-related matters is @t{<webmaster@@zsh.org>}.
+@node The Zsh Userguide, See Also, The Zsh Web Page, Introduction
+
+@section The Zsh Userguide
+@noindent
+A userguide is currently in preparation.  It is intended to complement the
+manual, with explanations and hints on issues where the manual can be
+cabbalistic, hierographic, or downright mystifying (for example, the word
+`hierographic' does not exist).  It can be viewed in its current state at
+@t{http://zsh.sunsite.dk/Guide/}.  At the time of writing, chapters
+dealing with startup files and their contents and the new completion system
+were essentially complete.
+
+@section The Zsh Wiki
+@noindent
+A `wiki' website for zsh has been created at @t{http://www.zshwiki.org/}.
+This is a site which can be added to and modified directly by users without
+any special permission.  You can add your own zsh tips and configurations.
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/seealso.yo
+@node See Also, , The Zsh Userguide, Introduction
+
+@section See Also
+@noindent
+man page sh(1),
+man page csh(1),
+man page tcsh(1),
+man page rc(1),
+man page bash(1),
+man page ksh(1)
+
+@noindent
+@cite{IEEE Standard for information Technology -
+Portable Operating System Interface (POSIX) -
+Part 2: Shell and Utilities},
+IEEE Inc, 1993, ISBN 1-55937-255-9.
+@c (avoiding a yodl bug)
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/invoke.yo
+@node Invocation, Files, Introduction, Top
+
+@chapter Invocation
+@noindent
+@cindex invocation
+
+@section Invocation Options
+@noindent
+@cindex shell options
+@cindex options, shell
+@cindex shell flags
+@cindex flags, shell
+The following flags are interpreted by the shell when invoked to determine
+where the shell will read commands from:
+
+@noindent
+@table @asis
+@item @t{-c}
+Take the first argument as a command to execute, rather than reading commands
+from a script or standard input.  If any further arguments are given, the
+first one is assigned to @t{$0}, rather than being used as a positional
+parameter.
+
+@item @t{-i}
+Force shell to be interactive.
+
+@item @t{-s}
+Force shell to read commands from the standard input.
+If the @t{-s} flag is not present and an argument is given,
+the first argument is taken to be the pathname of a script to
+execute.
+
+@end table
+
+@noindent
+After the first one or two arguments have been appropriated as described above,
+the remaining arguments are assigned to the positional parameters.
+
+@noindent
+For further options, which are common to invocation and the @t{set}
+builtin, see
+@ref{Options}.
+
+@noindent
+Options may be specified by name using the @t{-o} option.  @t{-o} acts like
+a single-letter option, but takes a following string as the option name.
+For example,
+
+@noindent
+@example
+zsh -x -o shwordsplit scr
+@end example
+
+@noindent
+runs the script @t{scr}, setting the @t{XTRACE} option by the corresponding
+letter `@t{-x}' and the @t{SH_WORD_SPLIT} option by name.
+Options may be turned @emph{off} by name by using @t{+o} instead of @t{-o}.
+@t{-o} can be stacked up with preceding single-letter options, so for example
+`@t{-xo shwordsplit}' or `@t{-xoshwordsplit}' is equivalent to
+`@t{-x -o shwordsplit}'.
+
+@noindent
+@cindex long option
+Options may also be specified by name in GNU long option style,
+`@t{--}@var{option-name}'.  When this is done, `@t{-}' characters in the
+option name are permitted: they are translated into `@t{_}', and thus ignored.
+So, for example, `@t{zsh --sh-word-split}' invokes zsh with the
+@t{SH_WORD_SPLIT} option turned on.  Like other option syntaxes, options can
+be turned off by replacing the initial `@t{-}' with a `@t{+}'; thus
+`@t{+-sh-word-split}' is equivalent to `@t{--no-sh-word-split}'.
+Unlike other option syntaxes, GNU-style long options cannot be stacked with
+any other options, so for example `@t{-x-shwordsplit}' is an error,
+rather than being treated like `@t{-x --shwordsplit}'.
+
+@noindent
+@cindex --version
+@cindex --help
+The special GNU-style option `@t{--version}' is handled; it sends to standard
+output the shell's version information, then exits successfully.
+`@t{--help}' is also handled; it sends to standard output a list of options
+that can be used when invoking the shell, then exits successfully.
+
+@noindent
+Option processing may be finished, allowing following arguments that start with
+`@t{-}' or `@t{+}' to be treated as normal arguments, in two ways.
+Firstly, a lone `@t{-}' (or `@t{+}') as an argument by itself ends option
+processing.  Secondly, a special option `@t{--}' (or `@t{+-}'), which may
+be specified on its own (which is the standard POSIX usage) or may be stacked
+with preceding options (so `@t{-x-}' is equivalent to `@t{-x --}').  Options
+are not permitted to be stacked after `@t{--}' (so `@t{-x-f}' is an error),
+but note the GNU-style option form discussed above, where `@t{--shwordsplit}'
+is permitted and does not end option processing.
+
+@noindent
+Except when the @cite{sh}/@cite{ksh} emulation single-letter options are in effect,
+the option `@t{-b}' (or `@t{+b}') ends option processing.
+`@t{-b}' is like `@t{-}@t{-}', except that further single-letter options
+can be stacked after the `@t{-b}' and will take effect as normal.
+
+@noindent
+@menu
+* Compatibility::
+* Restricted Shell::
+@end menu
+
+@noindent
+@c Yodl file: Zsh/compat.yo
+@node Compatibility, Restricted Shell, , Invocation
+
+@section Compatibility
+@noindent
+@cindex compatibility
+@cindex sh compatibility
+@cindex ksh compatibility
+Zsh tries to emulate @cite{sh} or @cite{ksh} when it is invoked as
+@t{sh} or @t{ksh} respectively; more precisely, it looks at the first
+letter of the name by which it was invoked, excluding any initial `@t{r}'
+(assumed to stand for `restricted'), and if that is `@t{s}' or `@t{k}' it
+will emulate @cite{sh} or @cite{ksh}.  Furthermore, if invoked as @t{su} (which
+happens on certain systems when the shell is executed by the @t{su}
+command), the shell will try to find an alternative name from the @t{SHELL}
+environment variable and perform emulation based on that.
+
+@noindent
+In @cite{sh} and @cite{ksh} compatibility modes the following
+parameters are not special and not initialized by the shell:
+@t{ARGC},
+@t{argv},
+@t{cdpath},
+@t{fignore},
+@t{fpath},
+@t{HISTCHARS},
+@t{mailpath},
+@t{MANPATH},
+@t{manpath},
+@t{path},
+@t{prompt},
+@t{PROMPT},
+@t{PROMPT2},
+@t{PROMPT3},
+@t{PROMPT4},
+@t{psvar},
+@t{status},
+@t{watch}.
+
+@noindent
+@vindex ENV, use of
+The usual zsh startup/shutdown scripts are not executed.  Login shells
+source @t{/etc/profile} followed by @t{$HOME/.profile}.  If the
+@t{ENV} environment variable is set on invocation, @t{$ENV} is sourced
+after the profile scripts.  The value of @t{ENV} is subjected to
+parameter expansion, command substitution, and arithmetic expansion
+before being interpreted as a pathname.  Note that the @t{PRIVILEGED}
+option also affects the execution of startup files.
+
+@noindent
+The following options are set if the shell is invoked as @t{sh} or
+@t{ksh}:
+@t{NO_BAD_PATTERN},
+@t{NO_BANG_HIST},
+@t{NO_BG_NICE},
+@t{NO_EQUALS},
+@t{NO_FUNCTION_ARGZERO},
+@t{GLOB_SUBST},
+@t{NO_GLOBAL_EXPORT},
+@t{NO_HUP},
+@t{INTERACTIVE_COMMENTS},
+@t{KSH_ARRAYS},
+@t{NO_MULTIOS},
+@t{NO_NOMATCH},
+@t{NO_NOTIFY},
+@t{POSIX_BUILTINS},
+@t{NO_PROMPT_PERCENT},
+@t{RM_STAR_SILENT},
+@t{SH_FILE_EXPANSION},
+@t{SH_GLOB},
+@t{SH_OPTION_LETTERS},
+@t{SH_WORD_SPLIT}.
+Additionally the @t{BSD_ECHO} and @t{IGNORE_BRACES}
+options are set if zsh is invoked as @t{sh}.
+Also, the
+@t{KSH_OPTION_PRINT},
+@t{LOCAL_OPTIONS},
+@t{PROMPT_BANG},
+@t{PROMPT_SUBST}
+and
+@t{SINGLE_LINE_ZLE}
+options are set if zsh is invoked as @t{ksh}.
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/restricted.yo
+@node Restricted Shell, , Compatibility, Invocation
+
+@section Restricted Shell
+@noindent
+@cindex restricted shell
+@pindex RESTRICTED
+When the basename of the command used to invoke zsh starts with the letter
+`@t{r}' or the `@t{-r}' command line option is supplied at invocation, the
+shell becomes restricted.  Emulation mode is determined after stripping the
+letter `@t{r}' from the invocation name.  The following are disabled in
+restricted mode:
+
+@noindent
+@itemize @bullet
+
+@noindent
+@item 
+changing directories with the @t{cd} builtin
+@item 
+changing or unsetting the @t{PATH}, @t{path}, @t{MODULE_PATH},
+@t{module_path}, @t{SHELL}, @t{HISTFILE}, @t{HISTSIZE}, @t{GID}, @t{EGID},
+@t{UID}, @t{EUID}, @t{USERNAME}, @t{LD_LIBRARY_PATH},
+@t{LD_AOUT_LIBRARY_PATH}, @t{LD_PRELOAD} and  @t{LD_AOUT_PRELOAD}
+parameters
+@item 
+specifying command names containing @t{/}
+@item 
+specifying command pathnames using @t{hash}
+@item 
+redirecting output to files
+@item 
+using the @t{exec} builtin command to replace the shell with another
+command
+@item 
+using @t{jobs -Z} to overwrite the shell process' argument and
+environment space
+@item 
+using the @t{ARGV0} parameter to override @t{argv[0]} for external
+commands
+@item 
+turning off restricted mode with @t{set +r} or @t{unsetopt
+RESTRICTED}
+@end itemize
+
+@noindent
+These restrictions are enforced after processing the startup files.  The
+startup files should set up @t{PATH} to point to a directory of commands
+which can be safely invoked in the restricted environment.  They may also
+add further restrictions by disabling selected builtins.
+
+@noindent
+Restricted mode can also be activated any time by setting the
+@t{RESTRICTED} option.  This immediately enables all the restrictions
+described above even if the shell still has not processed all startup
+files.
+@c (avoiding a yodl bug)
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/files.yo
+@node Files, Shell Grammar, Invocation, Top
+
+@chapter Files
+@noindent
+
+@section Startup/Shutdown Files
+@noindent
+@cindex files, startup
+@cindex startup files
+@cindex files, shutdown
+@cindex shutdown files
+@pindex RCS, use of
+@pindex GLOBAL_RCS, use of
+@pindex NO_RCS, use of
+@pindex NO_GLOBAL_RCS, use of
+@vindex ZDOTDIR, use of
+@cindex zshenv
+Commands are first read from @t{/etc/zshenv}; this cannot be overridden.
+Subsequent behaviour is modified by the @t{RCS} and
+@t{GLOBAL_RCS} options; the former affects all startup files, while the
+second only affects those in the @t{/etc} directory.  If one of the options
+is unset at any point, any subsequent startup file(s) of the corresponding
+type will not be read.  It is also possible for a file in @t{$ZDOTDIR} to
+re-enable @t{GLOBAL_RCS}. Both @t{RCS} and @t{GLOBAL_RCS} are set by
+default.
+
+@noindent
+Commands are then read from @t{$ZDOTDIR/.zshenv}.
+@pindex LOGIN, use of
+@cindex zprofile
+If the shell is a login shell, commands
+are read from @t{/etc/zprofile} and then @t{$ZDOTDIR/.zprofile}.
+@cindex zshrc
+Then, if the shell is interactive,
+commands are read from @t{/etc/zshrc} and then @t{$ZDOTDIR/.zshrc}.
+@cindex zlogin
+Finally, if the shell is a login shell, @t{/etc/zlogin} and
+@t{$ZDOTDIR/.zlogin} are read.
+
+@noindent
+@cindex zlogout
+When a login shell exits, the files @t{$ZDOTDIR/.zlogout} and then
+@t{/etc/zlogout} are read.  This happens with either an explicit exit
+via the @t{exit} or @t{logout} commands, or an implicit exit by reading
+end-of-file from the terminal.  However, if the shell terminates due
+to @t{exec}'ing another process, the logout files are not read.
+These are also affected by the @t{RCS} and @t{GLOBAL_RCS} options.
+Note also that the @t{RCS} option affects the saving of history files,
+i.e. if @t{RCS} is unset when the shell exits, no history file will be
+saved.
+
+@noindent
+@vindex HOME, use of
+If @t{ZDOTDIR} is unset, @t{HOME} is used instead.
+Those files listed above as being in @t{/etc} may be in another
+directory, depending on the installation.
+
+@noindent
+As @t{/etc/zshenv} is run for all instances of zsh, it is important that
+it be kept as small as possible.  In particular, it is a good idea to
+put code that does not need to be run for every single shell behind
+a test of the form `@t{if [[ -o rcs ]]; then ...}' so that it will not
+be executed when zsh is invoked with the `@t{-f}' option.
+@c Yodl file: Zsh/filelist.yo
+
+@section Files
+@noindent
+@cindex files used
+@table @asis
+@item @t{$ZDOTDIR/.zshenv}
+@item @t{$ZDOTDIR/.zprofile}
+@item @t{$ZDOTDIR/.zshrc}
+@item @t{$ZDOTDIR/.zlogin}
+@item @t{$ZDOTDIR/.zlogout}
+@item @t{$@{TMPPREFIX@}*}   (default is /tmp/zsh*)
+@item @t{/etc/zshenv}
+@item @t{/etc/zprofile}
+@item @t{/etc/zshrc}
+@item @t{/etc/zlogin}
+@item @t{/etc/zlogout}    (installation-specific - @t{/etc} is the default)
+@item
+@end table
+@c (avoiding a yodl bug)
+
+@noindent
+Any of these files may be pre-compiled with the @t{zcompile} builtin
+command (@ref{Shell Builtin Commands}).  If a compiled file exists (named for the original file plus the
+@t{.zwc} extension) and it is newer than the original file, the compiled
+file will be used instead.
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/grammar.yo
+@node Shell Grammar, Redirection, Files, Top
+
+@chapter Shell Grammar
+@noindent
+@cindex shell grammar
+@cindex grammar, shell
+@menu
+* Simple Commands & Pipelines::
+* Precommand Modifiers::
+* Complex Commands::
+* Alternate Forms For Complex Commands::
+* Reserved Words::
+* Comments::
+* Aliasing::
+* Quoting::
+@end menu
+@node Simple Commands & Pipelines, Precommand Modifiers, , Shell Grammar
+
+@section Simple Commands & Pipelines
+@noindent
+@cindex simple commands
+@cindex commands, simple
+A @emph{simple command} is a sequence of optional parameter
+assignments followed by blank-separated words,
+with optional redirections interspersed.
+The first word is the command to be executed, and the remaining
+words, if any, are arguments to the command.
+If a command name is given, the parameter assignments modify
+the environment of the command when it is executed.
+The value of a simple command is its exit status,
+or 128 plus the signal number if terminated by a signal.
+For example,
+
+@noindent
+@example
+echo foo
+@end example
+
+@noindent
+is a simple command with arguments.
+
+@noindent
+@cindex pipeline
+A @emph{pipeline} is either a simple command, or a sequence of two or more
+simple commands where each command is separated from the next by `@t{|}'
+or `@t{|&}'.  Where commands are separated by `@t{|}', the standard
+output of the first command is connected to the
+standard input of the next.  `@t{|&}' is shorthand for `@t{2>&1 |}', which
+connects both the standard output and the standard error of the
+command to the standard input of the next.  The value of a pipeline
+is the value of the last command, unless the pipeline is preceded by
+`@t{!}' in which case the value is the logical inverse of the value of the
+last command.
+For example,
+
+@noindent
+@example
+echo foo | sed 's/foo/bar/'
+@end example
+
+@noindent
+is a pipeline, where the output (`@t{foo}' plus a newline) of the first
+command will be passed to the input of the second.
+
+@noindent
+@findex coproc
+@cindex coprocess
+If a pipeline is preceded by `@t{coproc}', it is executed as a coprocess;
+a two-way pipe is established between it and the parent shell.  The
+shell can read from or write to the coprocess by means of the `@t{>&p}'
+and `@t{<&p}' redirection operators or with `@t{print -p}' and `@t{read -p}'.
+A pipeline cannot be preceded by both `@t{coproc}' and `@t{!}'.
+If job control is active, the coprocess can be treated in other than input
+and output as an ordinary background job.
+
+@noindent
+@cindex sublist
+A @emph{sublist} is either a single pipeline, or a sequence of two or more
+pipelines separated by `@t{&&}' or `@t{||}'.  If two pipelines are separated
+by `@t{&&}', the second pipeline is executed only if the first succeeds
+(returns a zero value).  If two pipelines are separated by `@t{||}', the
+second is executed only if the first fails (returns a nonzero value).
+Both operators have equal precedence and are left associative.
+The value of the sublist is the value of the last pipeline executed.
+For example,
+
+@noindent
+@example
+dmesg | grep panic && print yes
+@end example
+
+@noindent
+is a sublist consisting of two pipelines, the second just a simple command
+which will be executed if and only if the @t{grep} command returns a zero
+value.  If it does not, the value of the sublist is that return value, else
+it is the value returned by the @t{print} (almost certainly zero).
+
+@noindent
+@cindex list
+A @emph{list} is a sequence of zero or more sublists, in which each sublist
+is terminated by `@t{;}', `@t{&}', `@t{&|}', `@t{&!}', or a newline.
+This terminator
+may optionally be omitted from the last sublist in the list when the
+list appears as a complex command inside `@t{(}...@t{)}'
+or `@t{@{}...@t{@}}'.  When a
+sublist is terminated by `@t{;}' or newline, the shell waits for it to
+finish before executing the next sublist.  If a sublist is terminated
+by a `@t{&}', `@t{&|}', or `@t{&!}',
+the shell executes the last pipeline in it in the background, and
+does not wait for it to finish (note the difference from other shells
+which execute the whole sublist in the background).
+A backgrounded pipeline returns a status of zero.
+
+@noindent
+More generally, a list can be seen as a set of any shell commands
+whatsoever, including the complex commands below; this is implied wherever
+the word `list' appears in later descriptions.  For example, the commands
+in a shell function form a special sort of list.
+@node Precommand Modifiers, Complex Commands, Simple Commands & Pipelines, Shell Grammar
+
+@section Precommand Modifiers
+@noindent
+@cindex precommand modifiers
+@cindex modifiers, precommand
+A simple command may be preceded by a @emph{precommand modifier},
+which will alter how the command is interpreted.  These modifiers are
+shell builtin commands with the exception of @t{nocorrect} which is
+a reserved word.
+
+@noindent
+@table @asis
+@item @t{-}
+The command is executed with a `@t{-}' prepended to its
+@t{argv[0]} string.
+
+@item @t{noglob}
+Filename generation (globbing) is not performed on any of
+the words.
+
+@item @t{nocorrect}
+Spelling correction is not done on any of the words.  This must appear
+before any other precommand modifier, as it is interpreted immediately,
+before any parsing is done.  It has no effect in non-interactive shells.
+
+@item @t{exec}
+The command is executed in the parent shell without forking.
+
+@item @t{command}
+The command word is taken to be the name of an external command,
+rather than a shell function or builtin.
+
+@item @t{builtin}
+The command word is taken to be the name of a builtin command,
+rather than a shell function or external command.
+
+@end table
+@node Complex Commands, Alternate Forms For Complex Commands, Precommand Modifiers, Shell Grammar
+
+@section Complex Commands
+@noindent
+@cindex complex commands
+@cindex commands, complex
+A @emph{complex command} in zsh is one of the following:
+
+@noindent
+@table @asis
+@findex if
+@cindex if construct
+@item @t{if} @var{list} @t{then} @var{list} [ @t{elif} @var{list} @t{then} @var{list} ] ... [ @t{else} @var{list} ] @t{fi}
+The @t{if} @var{list} is executed, and if it returns a zero exit status,
+the @t{then} @var{list} is executed.
+Otherwise, the @t{elif} @var{list} is executed and if its value is zero,
+the @t{then} @var{list} is executed.
+If each @t{elif} @var{list} returns nonzero, the @t{else} @var{list} is executed.
+
+@findex for
+@cindex for loops
+@cindex loops, for
+@item @t{for} @var{name} ... [ @t{in} @var{word} ... ] @var{term} @t{do} @var{list} @t{done}
+where @var{term} is at least one newline or @t{;}.
+Expand the list of @var{word}s, and set the parameter
+@var{name} to each of them in turn, executing
+@var{list} each time.  If the @t{in} @var{word} is omitted,
+use the positional parameters instead of the @var{word}s.
+
+@noindent
+More than one parameter @var{name} can appear before the list of
+@var{word}s.  If @var{N} @var{name}s are given, then on each execution of the
+loop the next @t{N} @var{word}s are assigned to the corresponding
+parameters.  If there are more @var{name}s than remaining @var{word}s, the
+remaining parameters are each set to the empty string.  Execution of the
+loop ends when there is no remaining @var{word} to assign to the first
+@var{name}.  It is only possible for @t{in} to appear as the first @var{name}
+in the list, else it will be treated as marking the end of the list.
+
+@item @t{for ((} [@var{expr1}] @t{;} [@var{expr2}] @t{;} [@var{expr3}] @t{)) do} @var{list} @t{done}
+The arithmetic expression @var{expr1} is evaluated first (see
+@ref{Arithmetic Evaluation}).  The arithmetic expression
+@var{expr2} is repeatedly evaluated until it evaluates to zero and
+when non-zero, @var{list} is executed and the arithmetic expression
+@var{expr3} evaluated.  If any expression is omitted, then it behaves
+as if it evaluated to 1.
+
+@findex while
+@cindex while loops
+@cindex loops, while
+@item @t{while} @var{list} @t{do} @var{list} @t{done}
+Execute the @t{do} @var{list} as long as the @t{while} @var{list}
+returns a zero exit status.
+
+@findex until
+@cindex until loops
+@cindex loops, until
+@item @t{until} @var{list} @t{do} @var{list} @t{done}
+Execute the @t{do} @var{list} as long as @t{until} @var{list}
+returns a nonzero exit status.
+
+@findex repeat
+@cindex repeat loops
+@cindex loops, repeat
+@item @t{repeat} @var{word} @t{do} @var{list} @t{done}
+@var{word} is expanded and treated as an arithmetic expression,
+which must evaluate to a number @var{n}.
+@var{list} is then executed @var{n} times.
+
+@findex case
+@cindex case selection
+@cindex selection, case
+@item @t{case} @var{word} @t{in} [ [@t{(}] @var{pattern} [ @t{|} @var{pattern} ] ... @t{)} @var{list} (@t{;;}|@t{;&}) ] ... @t{esac}
+Execute the @var{list} associated with the first @var{pattern}
+that matches @var{word}, if any.  The form of the patterns
+is the same as that used for filename generation.  See
+@ref{Filename Generation}.
+If the @var{list} that is executed is terminated with @t{;&} rather than
+@t{;;}, the following list is also executed.  This continues until either
+a list is terminated with @t{;;} or the @t{esac} is reached.
+
+@findex select
+@cindex user selection
+@cindex selection, user
+@item @t{select} @var{name} [ @t{in} @var{word} ... @var{term} ] @t{do} @var{list} @t{done}
+where @var{term} is one or more newline or @t{;} to terminate the @var{word}s.
+@vindex REPLY, use of
+Print the set of @var{word}s, each preceded by a number.
+If the @t{in} @var{word} is omitted, use the positional parameters.
+The @t{PROMPT3} prompt is printed and a line is read from the line editor
+if the shell is interactive and that is active, or else standard input.
+If this line consists of the
+number of one of the listed @var{word}s, then the parameter @var{name}
+is set to the @var{word} corresponding to this number.
+If this line is empty, the selection list is printed again.
+Otherwise, the value of the parameter @var{name} is set to null.
+The contents of the line read from standard input is saved
+in the parameter @t{REPLY}.  @var{list} is executed
+for each selection until a break or end-of-file is encountered.
+
+@cindex subshell
+@item @t{(} @var{list} @t{)}
+Execute @var{list} in a subshell.  Traps set by the @t{trap} builtin
+are reset to their default values while executing @var{list}.
+
+@item @t{@{} @var{list} @t{@}}
+Execute @var{list}.
+
+@findex always
+@cindex always blocks
+@cindex try blocks
+@item @t{@{} @var{try-list} @t{@} always @{} @var{always-list} @t{@}}
+First execute @var{try-list}.  Regardless of errors, or @t{break},
+@t{continue}, or @t{return} commands encountered within @var{try-list},
+execute @var{always-list}.  Execution then continues from the
+result of the execution of @var{try-list}; in other words, any error,
+or @t{break}, @t{continue}, or @t{return} command is treated in the
+normal way, as if @var{always-list} were not present.  The two
+chunks of code are referred to as the `try block' and the `always block'.
+
+@noindent
+Optional newlines or semicolons may appear after the @t{always};
+note, however, that they may @emph{not} appear between the preceeding
+closing brace and the @t{always}.
+
+@noindent
+An `error' in this context is a condition such as a syntax error which
+causes the shell to abort execution of the current function, script, or
+list.  Syntax errors encountered while the shell is parsing the
+code do not cause the @var{always-list} to be executed.  For example,
+an erroneously constructed @t{if} block in @t{try-list} would cause the
+shell to abort during parsing, so that @t{always-list} would not be
+executed, while an erroneous substitution such as @t{$@{*foo*@}} would
+cause a run-time error, after which @t{always-list} would be executed.
+
+@noindent
+An error condition can be tested and reset with the special integer
+variable @t{TRY_BLOCK_ERROR}.  Outside an @t{always-list} the value is
+irrelevant, but it is initialised to @t{-1}.  Inside @t{always-list}, the
+value is 1 if an error occurred in the @t{try-list}, else 0.  If
+@t{TRY_BLOCK_ERROR} is set to 0 during the @t{always-list}, the error
+condition caused by the @t{try-list} is reset, and shell execution
+continues normally after the end of @t{always-list}.  Altering the value
+during the @t{try-list} is not useful (unless this forms part of an
+enclosing @t{always} block).
+
+@noindent
+Regardless of @t{TRY_BLOCK_ERROR}, after the end of @t{always-list} the
+normal shell status @t{$?} is the value returned from @t{always-list}.
+This will be non-zero if there was an error, even if @t{TRY_BLOCK_ERROR}
+was set to zero.
+
+@noindent
+The following executes the given code, ignoring any errors it causes.
+This is an alternative to the usual convention of protecting code by
+executing it in a subshell.
+
+@noindent
+@example
+@{
+    # code which may cause an error
+  @} always @{
+    # This code is executed regardless of the error.
+    (( TRY_BLOCK_ERROR = 0 ))
+@}
+# The error condition has been reset.
+@end example
+
+@noindent
+An @t{exit} command encountered in @t{try-list} does @emph{not} cause the
+execution of @var{always-list}.  Instead, the shell exits immediately
+after any @t{EXIT} trap has been executed.
+
+@findex function
+@item @t{function} @var{word} ... [ @t{()} ] [ @var{term} ] @t{@{} @var{list} @t{@}}
+@itemx @var{word} ... @t{()} [ @var{term} ] @t{@{} @var{list} @t{@}}
+@itemx @var{word} ... @t{()} [ @var{term} ] @var{command}
+where @var{term} is one or more newline or @t{;}.
+Define a function which is referenced by any one of @var{word}.
+Normally, only one @var{word} is provided; multiple @var{word}s
+are usually only useful for setting traps.
+The body of the function is the @var{list} between
+the @t{@{} and @t{@}}.  See @ref{Functions}.
+
+@noindent
+If the option @t{SH_GLOB} is set for compatibility with other shells, then
+whitespace may appear between between the left and right parentheses when
+there is a single @var{word};  otherwise, the parentheses will be treated as
+forming a globbing pattern in that case.
+
+@cindex timing
+@findex time
+@item @t{time} [ @var{pipeline} ]
+The @var{pipeline} is executed, and timing statistics are
+reported on the standard error in the form specified
+by the @t{TIMEFMT} parameter.
+If @var{pipeline} is omitted, print statistics about the
+shell process and its children.
+
+@cindex conditional expression
+@findex [[
+@item @t{[[} @var{exp} @t{]]}
+Evaluates the conditional expression @var{exp}
+and return a zero exit status if it is true.
+See @ref{Conditional Expressions}
+for a description of @var{exp}.
+
+@end table
+@node Alternate Forms For Complex Commands, Reserved Words, Complex Commands, Shell Grammar
+
+@section Alternate Forms For Complex Commands
+@noindent
+@cindex alternate forms for complex commands
+@cindex commands, alternate forms for complex
+Many of zsh's complex commands have alternate forms.  These particular
+versions of complex commands should be considered deprecated and may be
+removed in the future.  The versions in the previous section should be
+preferred instead.
+
+@noindent
+The short versions below only work if @var{sublist} is of the form `@t{@{}
+@var{list} @t{@}}' or if the @t{SHORT_LOOPS} option is set.  For the @t{if},
+@t{while} and @t{until} commands, in both these cases the test part of the
+loop must also be suitably delimited, such as by `@t{[[ ... ]]}' or `@t{((
+... ))}', else the end of the test will not be recognized.  For the
+@t{for}, @t{repeat}, @t{case} and @t{select} commands no such special form
+for the arguments is necessary, but the other condition (the special form
+of @var{sublist} or use of the @t{SHORT_LOOPS} option) still applies.
+
+@noindent
+@table @asis
+@item @t{if} @var{list} @t{@{} @var{list} @t{@}} [ @t{elif} @var{list} @t{@{} @var{list} @t{@}} ] ... [ @t{else @{} @var{list} @t{@}} ]
+An alternate form of @t{if}.  The rules mean that
+
+@noindent
+@example
+if [[ -o ignorebraces ]] @{
+  print yes
+@}
+@end example
+
+@noindent
+works, but
+
+@noindent
+@example
+if true @{  # Does not work!
+  print yes
+@}
+
+@end example
+
+@noindent
+does @emph{not}, since the test is not suitably delimited.
+
+@item @t{if} @var{list} @var{sublist}
+A short form of the alternate `if'.  The same limitations on the form of
+@var{list} apply as for the previous form.
+
+@item @t{for} @var{name} ... @t{(} @var{word} ... @t{)} @var{sublist}
+A short form of @t{for}.
+
+@item @t{for} @var{name} ... [ @t{in} @var{word} ... ] @var{term} @var{sublist}
+where @var{term} is at least one newline or @t{;}.
+Another short form of @t{for}.
+
+@item @t{for ((} [@var{expr1}] @t{;} [@var{expr2}] @t{;} [@var{expr3}] @t{))} @var{sublist}
+A short form of the arithmetic @t{for} command.
+
+@findex foreach
+@item @t{foreach} @var{name} ... @t{(} @var{word} ... @t{)} @var{list} @t{end}
+Another form of @t{for}.
+
+@item @t{while} @var{list} @t{@{} @var{list} @t{@}}
+An alternative form of @t{while}.  Note the limitations on the form of
+@var{list} mentioned above.
+
+@item @t{until} @var{list} @t{@{} @var{list} @t{@}}
+An alternative form of @t{until}.  Note the limitations on the form of
+@var{list} mentioned above.
+
+@item @t{repeat} @var{word} @var{sublist}
+This is a short form of @t{repeat}.
+
+@item @t{case} @var{word} @t{@{} [ [@t{(}] @var{pattern} [ @t{|} @var{pattern} ] ... @t{)} @var{list} (@t{;;}|@t{;&}) ] ... @t{@}}
+An alternative form of @t{case}.
+
+@item @t{select} @var{name} [ @t{in} @var{word} @var{term} ] @var{sublist}
+where @var{term} is at least one newline or @t{;}.
+A short form of @t{select}.
+
+@end table
+@node Reserved Words, Comments, Alternate Forms For Complex Commands, Shell Grammar
+
+@section Reserved Words
+@noindent
+@cindex reserved words
+@findex disable, use of
+The following words are recognized as reserved words when used as the first
+word of a command unless quoted or disabled using @t{disable -r}:
+
+@noindent
+@t{do done esac then elif else fi for case
+if while function repeat time until
+select coproc nocorrect foreach end ! [[ @{ @}}
+
+@noindent
+Additionally, `@t{@}}' is recognized in any position if the @t{IGNORE_BRACES} option
+is not set.
+@node Comments, Aliasing, Reserved Words, Shell Grammar
+
+@section Comments
+@noindent
+@cindex comments
+@pindex INTERACTIVE_COMMENTS, use of
+@vindex histchars, use of
+In noninteractive shells, or in interactive shells with the
+@t{INTERACTIVE_COMMENTS} option set, a word beginning
+with the third character of the @t{histchars} parameter
+(`@t{#}' by default) causes that word and all the following
+characters up to a newline to be ignored.
+@node Aliasing, Quoting, Comments, Shell Grammar
+
+@section Aliasing
+@noindent
+@cindex aliasing
+Every token in the shell input is checked to see if there
+is an alias defined for it.
+If so, it is replaced by the text of the alias if it is in command
+position (if it could be the first word of a simple command),
+or if the alias is global.
+If the text ends with a space, the next word in the shell input
+is treated as though it were in command position for purposes of alias
+expansion.
+@findex alias, use of
+@cindex aliases, global
+An alias is defined using the @t{alias} builtin; global aliases
+may be defined using the @t{-g} option to that builtin.
+
+@noindent
+Alias expansion is done on the shell input before any
+other expansion except history expansion.  Therefore,
+if an alias is defined for the word @t{foo}, alias expansion
+may be avoided by quoting part of the word, e.g. @t{\foo}.
+But there is nothing to prevent an alias being defined
+for @t{\foo} as well.
+@node Quoting, , Aliasing, Shell Grammar
+
+@section Quoting
+@noindent
+@cindex quoting
+A character may be @var{quoted} (that is, made
+to stand for itself) by preceding it with a `@t{\}'.
+`@t{\}' followed by a newline is ignored.
+
+@noindent
+A string enclosed between `@t{$'}' and `@t{'}' is
+processed the same way as the string arguments of the
+@t{print} builtin, and the resulting string is considered to be
+entirely quoted.  A literal `@t{'}' character can be included in the
+string by using the `@t{\'}' escape.
+
+@noindent
+@pindex RC_QUOTES, use of
+All characters enclosed between a pair of single quotes (@t{@value{dsq}}) that
+is not preceded by a `@t{$}' are quoted.  A single quote cannot appear
+within single quotes unless the option @t{RC_QUOTES} is set, in which case
+a pair of single quotes are turned into a single quote.  For example,
+
+@noindent
+@example
+print @value{dsq}@value{dsq}
+@end example
+
+@noindent
+outputs nothing apart from a newline if @t{RC_QUOTES} is not set, but one
+single quote if it is set.
+
+@noindent
+Inside double quotes (@t{""}), parameter and
+command substitution occur, and `@t{\}' quotes the characters
+`@t{\}', `@t{`}', `@t{"}', and `@t{$}'.
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/redirect.yo
+@node Redirection, Command Execution, Shell Grammar, Top
+
+@chapter Redirection
+@noindent
+@cindex redirection
+@cindex file descriptors
+@cindex descriptors, file
+If a command is followed by @t{&}
+and job control is not active,
+then the default standard input
+for the command is the empty file @t{/dev/null}.
+Otherwise, the environment for the execution of a command contains the
+file descriptors of the invoking shell as modified by
+input/output specifications.
+
+@noindent
+The following may appear anywhere in a simple command
+or may precede or follow a complex command.
+Expansion occurs before @var{word} or @var{digit}
+is used except as noted below.
+If the result of substitution on @var{word}
+produces more than one filename,
+redirection occurs for each
+separate filename in turn.
+
+@noindent
+@table @asis
+@item @t{<} @var{word}
+Open file @var{word} for reading as standard input.
+
+@item @t{<>} @var{word}
+Open file @var{word} for reading and writing as standard input.
+If the file does not exist then it is created.
+
+@item @t{>} @var{word}
+Open file @var{word} for writing as standard output.
+If the file does not exist then it is created.
+If the file exists, and the @t{CLOBBER} option is unset,
+this causes an error;
+otherwise, it is truncated to zero length.
+
+@item @t{>|} @var{word}
+@itemx @t{>!} @var{word}
+Same as @t{>}, except that the file is truncated to zero length
+if it exists, even if @t{CLOBBER} is unset.
+
+@item @t{>>} @var{word}
+Open file @var{word} for writing in append mode as standard output.
+If the file does not exist, and the @t{CLOBBER}
+option is unset, this causes an error;
+otherwise, the file is created.
+
+@item @t{>>|} @var{word}
+@itemx @t{>>!} @var{word}
+Same as @t{>>}, except that the file is created if it does not
+exist, even if @t{CLOBBER} is unset.
+
+@item @t{<<}[@t{-}] @var{word}
+The shell input is read up to a line that is the same as
+@var{word}, or to an end-of-file.
+No parameter expansion, command substitution or
+filename generation is performed on @var{word}.
+The resulting document, called a
+@emph{here-document}, becomes the standard input.
+
+@noindent
+If any character of @var{word} is quoted with
+single or double quotes or a `@t{\}',
+no interpretation is placed upon the characters of the document.
+Otherwise, parameter and command substitution
+occurs, `@t{\}' followed by a newline is removed,
+and `@t{\}' must be used to quote the characters
+`@t{\}', `@t{$}', `@t{`}' and the first character of @var{word}.
+
+@noindent
+Note that @var{word} itself does not undergo shell expansion.  Backquotes
+in @var{word} do not have their usual effect; instead they behave
+similarly to double quotes, except that the backquotes themselves are
+passed through unchanged.  (This information is given for completeness
+and it is not recommended that backquotes be used.)  Quotes in the form
+@t{$'}@var{...}@t{'} have their standard effect of expanding backslashed
+references to special characters.
+
+@noindent
+If @t{<<-} is used, then all leading
+tabs are stripped from @var{word} and from the document.
+
+@item @t{<<<} @var{word}
+Perform shell expansion on @var{word} and pass the result
+to standard input.  This is known as a @emph{here-string}.
+Compare the use of @var{word} in here-documents above, where @var{word}
+does not undergo shell expansion.
+
+@item @t{<&} @var{number}
+@itemx @t{>&} @var{number}
+The standard input/output is duplicated from file descriptor
+@var{number} (see man page dup2(2)).
+
+@item @t{<& -}
+@itemx @t{>& -}
+Close the standard input/output.
+
+@item @t{<& p}
+@itemx @t{>& p}
+The input/output from/to the coprocess is moved to the standard input/output.
+
+@item @t{>&} @var{word}
+@itemx @t{&>} @var{word}
+(Except where `@t{>&} @var{word}' matches one of the above syntaxes;
+`@t{&>}' can always be used to avoid this ambiguity.)
+Redirects both standard output and standard error (file descriptor 2)
+in the manner of `@t{>} @var{word}'.
+Note that this does @emph{not} have the same effect as `@t{>} @var{word} @t{2>&1}'
+in the presence of multios (see the section below).
+
+@item @t{>&|} @var{word}
+@itemx @t{>&!} @var{word}
+@itemx @t{&>|} @var{word}
+@itemx @t{&>!} @var{word}
+Redirects both standard output and standard error (file descriptor 2)
+in the manner of `@t{>|} @var{word}'.
+
+@item @t{>>&} @var{word}
+@itemx @t{&>>} @var{word}
+Redirects both standard output and standard error (file descriptor 2)
+in the manner of `@t{>>} @var{word}'.
+
+@item @t{>>&|} @var{word}
+@itemx @t{>>&!} @var{word}
+@itemx @t{&>>|} @var{word}
+@itemx @t{&>>!} @var{word}
+Redirects both standard output and standard error (file descriptor 2)
+in the manner of `@t{>>|} @var{word}'.
+
+@end table
+
+@noindent
+If one of the above is preceded by a digit, then the file
+descriptor referred to is that specified by the digit
+instead of the default 0 or 1.
+The order in which redirections are specified is significant.
+The shell evaluates each redirection in terms of the
+(@emph{file descriptor}, @emph{file})
+association at the time of evaluation.
+For example:
+
+@noindent
+@quotation
+... @t{1>}@var{fname} @t{2>&1}
+@end quotation
+
+@noindent
+first associates file descriptor 1 with file @var{fname}.
+It then associates file descriptor 2 with the file associated with file
+descriptor 1 (that is, @var{fname}).
+If the order of redirections were reversed,
+file descriptor 2 would be associated
+with the terminal (assuming file descriptor 1 had been)
+and then file descriptor 1 would be associated with file @var{fname}.
+
+@noindent
+The `@t{|&}' command separator described in
+@ref{Simple Commands & Pipelines}
+is a shorthand for `@t{2>&1 |}'.
+
+@noindent
+For output redirections only, if @var{word} is of the form
+`@t{>(}@var{list}@t{)}' then the output is piped to the command
+represented by @var{list}.  See
+@ref{Process Substitution}.
+
+@section Multios
+@noindent
+@cindex multios
+@pindex MULTIOS, use of
+If the user tries to open a file descriptor for writing more than once,
+the shell opens the file descriptor as a pipe to a process that copies
+its input to all the specified outputs, similar to @cite{tee},
+provided the @t{MULTIOS} option is set, as it is by default.  Thus:
+
+@noindent
+@example
+date >foo >bar
+@end example
+
+@noindent
+writes the date to two files, named `@t{foo}' and `@t{bar}'.
+Note that a pipe is an implicit redirection; thus
+
+@noindent
+@example
+date >foo | cat
+@end example
+
+@noindent
+writes the date to the file `@t{foo}', and also pipes it to cat.
+
+@noindent
+If the @t{MULTIOS}
+option is set, the word after a redirection operator is also subjected
+to filename generation (globbing).  Thus
+
+@noindent
+@example
+: > *
+@end example
+
+@noindent
+will truncate all files in the current directory,
+assuming there's at least one.  (Without the @t{MULTIOS}
+option, it would create an empty file called `@t{*}'.)
+Similarly, you can do
+
+@noindent
+@example
+echo exit 0 >> *.sh
+@end example
+
+@noindent
+If the user tries to open a file descriptor for reading more than once,
+the shell opens the file descriptor as a pipe to a process that copies
+all the specified inputs to its output in the order
+specified, similar to @cite{cat},
+provided the @t{MULTIOS} option is set.  Thus
+
+@noindent
+@example
+sort <foo <fubar
+@end example
+
+@noindent
+or even
+
+@noindent
+@example
+sort <f@{oo,ubar@}
+@end example
+
+@noindent
+is equivalent to `@t{cat foo fubar | sort}'.
+
+@noindent
+Note that a pipe is an implicit redirection; thus
+
+@noindent
+@example
+cat bar | sort <foo
+@end example
+
+@noindent
+is equivalent to `@t{cat bar foo | sort}' (note the order of the inputs).
+
+@noindent
+If the @t{MULTIOS} option is @emph{un}set,
+each redirection replaces the previous redirection for that file descriptor.
+However, all files redirected to are actually opened, so
+
+@noindent
+@example
+echo foo > bar > baz
+@end example
+
+@noindent
+when @t{MULTIOS} is unset will truncate bar, and write `@t{foo}' into baz.
+
+@noindent
+There is a problem when an output multio is attached to an external
+program.  A simple example shows this:
+
+@noindent
+@example
+cat file >file1 >file2
+cat file1 file2
+@end example
+
+@noindent
+Here, it is possible that the second `@t{cat}' will not display the full
+contents of @t{file1} and @t{file2} (i.e. the original contents of
+@t{file} repeated twice).
+
+@noindent
+The reason for this is that the multios are spawned after the @t{cat}
+process is forked from the parent shell, so the parent shell does not
+wait for the multios to finish writing data.  This means the command as
+shown can exit before @t{file1} and @t{file2} are completely written.
+As a workaround, it is possible to run the @t{cat} process as part of a
+job in the current shell:
+
+@noindent
+@example
+@{ cat file @} >file >file2
+@end example
+
+@noindent
+Here, the @t{@{}@var{...}@t{@}} job will pause to wait for both files to be
+written.
+
+@noindent
+
+@section Redirections with no command
+@noindent
+When a simple command consists of one or more redirection operators
+and zero or more parameter assignments, but no command name, zsh can
+behave in several ways.
+
+@noindent
+@vindex NULLCMD, use of
+@pindex CSH_NULLCMD, use of
+If the parameter @t{NULLCMD} is not set or the option @t{CSH_NULLCMD} is
+set, an error is caused.  This is the @cite{csh} behavior and @t{CSH_NULLCMD}
+is set by default when emulating @cite{csh}.
+
+@noindent
+@pindex SH_NULLCMD, use of
+If the option @t{SH_NULLCMD} is set, the builtin `@t{:}' is inserted as a
+command with the given redirections.  This is the default when emulating
+@cite{sh} or @cite{ksh}.
+
+@noindent
+@vindex READNULLCMD, use of
+Otherwise, if the parameter @t{NULLCMD} is set, its value will be used as a
+command with the given redirections.  If both @t{NULLCMD} and
+@t{READNULLCMD} are set, then the value of the latter will be used instead
+of that of the former when the redirection is an input.  The default for
+@t{NULLCMD} is `@t{cat}' and for @t{READNULLCMD} is `@t{more}'. Thus
+
+@noindent
+@example
+< file
+@end example
+
+@noindent
+shows the contents of @t{file} on standard output, with paging if that is a
+terminal.  @t{NULLCMD} and @t{READNULLCMD} may refer to shell functions.
+
+@noindent
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/exec.yo
+@node Command Execution, Functions, Redirection, Top
+
+@chapter Command Execution
+@noindent
+@cindex command execution
+@cindex execution, of commands
+If a command name contains no slashes, the shell attempts to locate
+it.  If there exists a shell function by that name, the function
+is invoked as described in @ref{Functions}.  If there exists
+a shell builtin by that name, the builtin is invoked.
+
+@noindent
+@vindex path, use of
+Otherwise, the shell searches each element of @t{$path} for a
+directory containing an executable file by that name.  If the
+search is unsuccessful, the shell prints an error message and returns
+a nonzero exit status.
+
+@noindent
+If execution fails because the file is not in executable format,
+and the file is not a directory, it is assumed to be a shell
+script.  @t{/bin/sh} is spawned to execute it.  If the program
+is a file beginning with `@t{#!}', the remainder of the first line
+specifies an interpreter for the program.  The shell will
+execute the specified interpreter on operating systems that do
+not handle this executable format in the kernel.
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/func.yo
+@node Functions, Jobs & Signals, Command Execution, Top
+
+@chapter Functions
+@noindent
+@cindex functions
+@findex function, use of
+Shell functions are defined with the @t{function} reserved word or the
+special syntax `@var{funcname} @t{()}'.
+Shell functions are read in and stored internally.
+Alias names are resolved when the function is read.
+Functions are executed like commands with the arguments
+passed as positional parameters.
+(See @ref{Command Execution}.)
+
+@noindent
+Functions execute in the same process as the caller and
+share all files
+and present working directory with the
+caller.  A trap on @t{EXIT} set inside a function
+is executed after the function completes in the environment
+of the caller.
+
+@noindent
+@findex return, use of
+The @t{return} builtin is used to return from function calls.
+
+@noindent
+@findex functions, use of
+Function identifiers can be listed with the @t{functions} builtin.
+@findex unfunction, use of
+Functions can be undefined with the @t{unfunction} builtin.
+
+@section Autoloading Functions
+@noindent
+@cindex autoloading functions
+@cindex functions, autoloading
+
+@noindent
+@findex autoload, use of
+@vindex fpath, use of
+A function can be marked as @emph{undefined} using the @t{autoload} builtin
+(or `@t{functions -u}' or `@t{typeset -fu}').  Such a function has no
+body.  When the function is first executed, the shell searches for its
+definition using the elements of the @t{fpath} variable.  Thus to define
+functions for autoloading, a typical sequence is:
+
+@noindent
+@example
+fpath=(~/myfuncs $fpath)
+autoload myfunc1 myfunc2 ...
+@end example
+
+@noindent
+The usual alias expansion during reading will be suppressed if the
+@t{autoload} builtin or its equivalent is given the option @t{-U}. This is
+recommended for the use of functions supplied with the zsh distribution.
+@findex zcompile, use of
+Note that for functions precompiled with the @t{zcompile} builtin command
+the flag @t{-U} must be provided when the @t{.zwc} file is created, as the
+corresponding information is compiled into the latter.
+
+@noindent
+For each @var{element} in @t{fpath}, the shell looks for three possible
+files, the newest of which is used to load the definition for the function:
+
+@noindent
+@table @asis
+@item @var{element}@t{.zwc}
+A file created with the @t{zcompile} builtin command, which is expected to
+contain the definitions for all functions in the directory named
+@var{element}.  The file is treated in the same manner as a directory
+containing files for functions and is searched for the definition of the
+function.   If the definition is not found, the search for a definition
+proceeds with the other two possibilities described below.
+
+@noindent
+If @var{element} already includes a @t{.zwc} extension (i.e. the extension
+was explicitly given by the user), @var{element} is searched for the
+definition of the function without comparing its age to that of other
+files; in fact, there does not need to be any directory named @var{element}
+without the suffix.  Thus including an element such as
+`@t{/usr/local/funcs.zwc}' in @t{fpath} will speed up the search for
+functions, with the disadvantage that functions included must be explicitly
+recompiled by hand before the shell notices any changes.
+
+@item @var{element}@t{/}@var{function}@t{.zwc}
+A file created with @t{zcompile}, which is expected to contain the
+definition for @var{function}.  It may include other function definitions
+as well, but those are neither loaded nor executed; a file found in this
+way is searched @emph{only} for the definition of @var{function}.
+
+@item @var{element}@t{/}@var{function}
+A file of zsh command text, taken to be the definition for @var{function}.
+
+@end table
+
+@noindent
+In summary, the order of searching is, first, in the @emph{parents of}
+directories in @t{fpath} for the newer of either a compiled directory or
+a directory in @t{fpath}; second, if more than one of these contains a
+definition for the function that is sought, the leftmost in the @t{fpath}
+is chosen; and third, within a directory, the newer of either a compiled
+function or an ordinary function definition is used.
+
+@noindent
+@pindex KSH_AUTOLOAD, use of
+If the @t{KSH_AUTOLOAD} option is set, or the file contains only a
+simple definition of the function, the file's contents will be executed.
+This will normally define the function in question, but may also perform
+initialization, which is executed in the context of the function execution,
+and may therefore define local parameters.  It is an error if the function
+is not defined by loading the file.
+
+@noindent
+Otherwise, the function body (with no surrounding `@var{funcname}@t{()
+@{}@var{...}@t{@}}') is taken to be the complete contents of the file.  This
+form allows the file to be used directly as an executable shell script.  If
+processing of the file results in the function being re-defined, the
+function itself is not re-executed.  To force the shell to perform
+initialization and then call the function defined, the file should contain
+initialization code (which will be executed then discarded) in addition to
+a complete function definition (which will be retained for subsequent calls
+to the function), and a call to the shell function, including any
+arguments, at the end.
+
+@noindent
+For example, suppose the autoload file @t{func} contains
+
+@noindent
+@example
+func() @{ print This is func; @}
+print func is initialized
+
+@end example
+
+@noindent
+then `@t{func; func}' with @t{KSH_AUTOLOAD} set will produce both messages
+on the first call, but only the message `@t{This is func}' on the second
+and subsequent calls.  Without @t{KSH_AUTOLOAD} set, it will produce
+the initialization message on the first call, and the other message on the
+second and subsequent calls.
+
+@noindent
+It is also possible to create a function that is not marked as autoloaded,
+but which loads its own definition by searching @t{fpath}, by using
+`@t{autoload -X}' within a shell function.  For example, the following are
+equivalent:
+
+@noindent
+@example
+myfunc() @{
+  autoload -X
+@}
+myfunc args...
+@end example
+
+@noindent
+and
+
+@noindent
+@example
+unfunction myfunc   # if myfunc was defined
+autoload myfunc
+myfunc args...
+@end example
+
+@noindent
+In fact, the @t{functions} command outputs `@t{builtin autoload -X}' as
+the body of an autoloaded function.  This is done so that
+
+@noindent
+@example
+eval "$(functions)"
+@end example
+
+@noindent
+produces a reasonable result.  A true autoloaded function can be
+identified by the presence of the comment `@t{# undefined}' in the body,
+because all comments are discarded from defined functions.
+
+@noindent
+To load the definition of an autoloaded function @t{myfunc} without
+executing @t{myfunc}, use:
+
+@noindent
+@example
+autoload +X myfunc
+@end example
+
+@noindent
+
+@section Special Functions
+@noindent
+The following functions, if defined, have special meaning to
+the shell:
+
+@noindent
+@table @asis
+@findex chpwd
+@item @t{chpwd}
+Executed whenever the current working directory is changed.
+
+@findex periodic
+@item @t{periodic}
+@vindex PERIOD
+If the parameter @t{PERIOD}
+is set, this function is executed every @t{$PERIOD}
+seconds, just before a prompt.
+
+@findex precmd
+@item @t{precmd}
+Executed before each prompt.
+
+@findex preexec
+@item @t{preexec}
+Executed just after a command has been read and is about to be
+executed.  If the history mechanism is active (and the line was not
+discarded from the history buffer), the string that the user typed is
+passed as the first argument, otherwise it is an empty string.  The
+actual command that will be executed (including expanded aliases) is
+passed in two different forms: the second argument is a single-line,
+size-limited version of the command (with things like function bodies
+elided); the third argument contains the full text that is being
+executed.
+
+@item @t{TRAP}@var{NAL}
+@cindex signals, trapping
+@cindex trapping signals
+If defined and non-null,
+this function will be executed whenever the shell
+catches a signal @t{SIG}@var{NAL}, where @var{NAL} is a signal
+name as specified for the @t{kill} builtin.
+The signal number will be passed as the first parameter to the function.
+
+@noindent
+If a function of this form is defined and null,
+the shell and processes spawned by it will ignore @t{SIG}@var{NAL}.
+
+@noindent
+The return value from the function is handled specially.  If it is
+zero, the signal is assumed to have been handled, and execution continues
+normally.  Otherwise, the normal effect of the signal is produced;
+if this causes execution to terminate, the status returned to the shell is
+the status returned from the function.
+
+@noindent
+Programs terminated by uncaught signals typically return the status 128
+plus the signal number.  Hence the following causes the handler for
+@t{SIGINT} to print a message, then mimic the usual effect of the signal.
+
+@noindent
+@example
+TRAPINT() @{
+  print "Caught SIGINT, aborting."
+  return $(( 128 + $1 ))
+@}
+@end example
+
+@noindent
+The functions @t{TRAPZERR}, @t{TRAPDEBUG} and @t{TRAPEXIT} are never
+executed inside other traps.
+
+@findex TRAPDEBUG
+@item @t{TRAPDEBUG}
+Executed after each command.
+
+@findex TRAPEXIT
+@item @t{TRAPEXIT}
+Executed when the shell exits,
+or when the current function exits if defined inside a function.
+
+@findex TRAPZERR
+@item @t{TRAPZERR}
+Executed whenever a command has a non-zero exit status.  However, the
+function is not executed if the command occurred in a sublist followed by
+`@t{&&}' or `@t{||}'; only the final command in a sublist of this type
+causes the trap to be executed.
+
+@end table
+
+@noindent
+@findex trap, use of
+The functions beginning `@t{TRAP}' may alternatively be defined with the
+@t{trap} builtin:  this may be preferable for some uses, as they are then
+run in the environment of the calling process, rather than in their own
+function environment.  Apart from the difference in calling procedure and
+the fact that the function form appears in lists of functions, the forms
+
+@noindent
+@example
+TRAPNAL() @{ 
+ # code
+@}
+@end example
+
+@noindent
+and
+
+@noindent
+@example
+trap '
+ # code
+' NAL
+@end example
+
+@noindent
+are equivalent.
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/jobs.yo
+@node Jobs & Signals, Arithmetic Evaluation, Functions, Top
+
+@chapter Jobs & Signals
+@noindent
+
+@section Jobs
+@noindent
+@cindex jobs
+@pindex MONITOR, use of
+If the @t{MONITOR} option is set,
+an interactive shell associates a @emph{job} with each pipeline.
+It keeps a table of current jobs, printed by the @t{jobs}
+command, and assigns them small integer numbers.
+When a job is started asynchronously with `@t{&}',
+the shell prints a line to standard error which looks like:
+
+@noindent
+@example
+[1] 1234
+@end example
+
+@noindent
+indicating that the job which was started asynchronously was job number
+1 and had one (top-level) process, whose process ID was 1234.
+
+@noindent
+If a job is started with `@t{&|}' or `@t{&!}',
+then that job is immediately disowned.  After startup, it
+does not have a place in the job table, and is not subject
+to the job control features described here.
+
+@noindent
+If you are running a job and wish to do something else you may hit the key
+^Z (control-Z) which sends a @t{TSTP} signal to the current job:  this key
+may be redefined by the @t{susp} option of the external @t{stty} command.
+@cindex jobs, suspending
+@cindex suspending jobs
+The shell will then normally indicate that the job has been `suspended',
+and print another prompt.  You can then manipulate the state of this job,
+@findex bg, use of
+putting it in the background with the @t{bg} command, or run some other
+commands and then eventually bring the job back into the foreground with
+@findex fg, use of
+the foreground command @t{fg}.  A ^Z takes effect immediately and
+is like an interrupt in that pending output and unread input are discarded
+when it is typed.
+
+@noindent
+A job being run in the background will suspend if it tries to read
+from the terminal.
+@cindex background jobs, I/O
+@cindex jobs, background, I/O
+Background jobs are normally allowed to produce output,
+but this can be disabled by giving the command `@t{stty tostop}'.
+If you set this
+tty option, then background jobs will suspend when they try to produce
+output like they do when they try to read input.
+
+@noindent
+When a command is suspended and continued later with the @t{fg} or
+@t{wait} builtins, zsh restores tty modes that were in effect when it was
+suspended.  This (intentionally) does not apply if the command is
+continued via `@t{kill -CONT}', nor when it is continued with @t{bg}.
+
+@noindent
+@cindex jobs, referring to
+@cindex referring to jobs
+There are several ways to refer to jobs in the shell.
+A job can be referred to by the process ID of any process of the job
+or by one of the following:
+
+@noindent
+@table @asis
+@item @t{%}@var{number}
+The job with the given number.
+@item @t{%}@var{string}
+Any job whose command line begins with @var{string}.
+@item @t{%?}@var{string}
+Any job whose command line contains @var{string}.
+@item @t{%%}
+Current job.
+@item @t{%+}
+Equivalent to `@t{%%}'.
+@item @t{%-}
+Previous job.
+@end table
+
+@noindent
+The shell learns immediately whenever a process changes state.
+@pindex NOTIFY, use of
+It normally informs you whenever a job becomes blocked so that
+no further progress is possible.  If the @t{NOTIFY} option is not set,
+it waits until just before it prints a prompt before it informs you.
+All such notifications are sent directly to the terminal, not to
+the standard output or standard error.
+
+@noindent
+When the monitor mode is on, each background job that completes
+triggers any trap set for @t{CHLD}.
+
+@noindent
+When you try to leave the shell while jobs are running or suspended, you will
+be warned that `You have suspended (running) jobs'.
+You may use the @t{jobs} command to see what they are.
+If you do this or immediately try to
+exit again, the shell will not warn you a second time; the suspended
+jobs will be terminated, and the running jobs will be sent
+a @t{SIGHUP} signal, if the @t{HUP} option is set.
+@pindex HUP, use of
+
+@noindent
+@cindex jobs, disowning
+@cindex disowning jobs
+@findex disown, use of
+To avoid having the shell terminate the running jobs, either
+use the @cite{nohup} command (see man page nohup(1))
+or the @t{disown} builtin.
+
+@section Signals
+@noindent
+The @t{INT} and @t{QUIT} signals for an invoked
+command are ignored if the command is followed by
+`@t{&}' and the @t{MONITOR} option is not active.
+Otherwise, signals have the values
+inherited by the shell from its parent
+(but see the @t{TRAP}@var{NAL} special functions in @ref{Functions}).
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/arith.yo
+@node Arithmetic Evaluation, Conditional Expressions, Jobs & Signals, Top
+
+@chapter Arithmetic Evaluation
+@noindent
+@cindex arithmetic evaluation
+@cindex evaluation, arithmetic
+@findex let, use of
+The shell can perform integer and floating point arithmetic, either using
+the builtin @t{let}, or via a substitution of the form @t{$((...))}.  For
+integers, the shell is usually compiled to use 8-byte precision where this
+is available, otherwise precision is 4 bytes.  This can be tested, for
+example, by giving the command `@t{print - $(( 12345678901 ))}'; if the
+number appears unchanged, the precision is at least 8 bytes.  Floating
+point arithmetic is always double precision.
+
+@noindent
+The @t{let} builtin command takes arithmetic expressions as arguments; each
+is evaluated separately.  Since many of the arithmetic operators, as well
+as spaces, require quoting, an alternative form is provided: for any
+command which begins with a `@t{((}', all the characters until a
+matching `@t{))}' are treated as a quoted expression and
+arithmetic expansion performed as for an argument of @t{let}.  More
+precisely, `@t{((}@var{...}@t{))}' is equivalent to
+`@t{let "}@var{...}@t{"}'.  For example, the following statement
+
+@noindent
+@example
+(( val = 2 + 1 ))
+@end example
+
+@noindent
+is equivalent to
+
+@noindent
+@example
+let "val = 2 + 1"
+@end example
+
+@noindent
+both assigning the value 3 to the shell variable @t{val} and returning a
+zero status.
+
+@noindent
+@cindex arithmetic base
+@cindex bases, in arithmetic
+Integers can be in bases other than 10.
+A leading `@t{0x}' or `@t{0X}' denotes hexadecimal.
+Integers may also be of the form `@var{base}@t{#}@var{n}',
+where @var{base} is a decimal number between two and thirty-six
+representing the arithmetic base and @var{n}
+is a number in that base (for example, `@t{16#ff}' is 255 in hexadecimal).
+The @var{base}@t{#} may also be omitted, in which case
+base 10 is used.  For backwards compatibility the form
+`@t{[}@var{base}@t{]}@var{n}' is also accepted.
+
+@noindent
+It is also possible to specify a base to be used for output in the form
+`@t{[#}@var{base}@t{]}', for example `@t{[#16]}'.  This is used when
+outputting arithmetical substitutions or when assigning to scalar
+parameters, but an explicitly defined integer or floating point parameter
+will not be affected.  If an integer variable is implicitly defined by an
+arithmetic expression, any base specified in this way will be set as the
+variable's output arithmetic base as if the option `@t{-i} @var{base}' to
+the @t{typeset} builtin had been used.  The expression has no precedence
+and if it occurs more than once in a mathematical expression, the last
+encountered is used.  For clarity it is recommended that it appear at the
+beginning of an expression.  As an example:
+
+@noindent
+@example
+typeset -i 16 y
+print $(( [#8] x = 32, y = 32 ))
+print $x $y
+@end example
+
+@noindent
+outputs first `@t{8#40}', the rightmost value in the given output base, and
+then `@t{8#40 16#20}', because @t{y} has been explicitly declared to
+have output base 16, while @t{x} (assuming it does not already exist) is
+implicitly typed by the arithmetic evaluation, where it acquires the output
+base 8.
+
+@noindent
+@pindex C_BASES, use of
+@pindex OCTAL_ZEROES, use of
+If the @t{C_BASES} option is set, hexadecimal numbers in the standard C
+format, for example @t{0xFF} instead of the usual `@t{16#FF}'.  If the
+option @t{OCTAL_ZEROES} is also set (it is not by default), octal numbers
+will be treated similarly and hence appear as `@t{077}' instead of
+`@t{8#77}'.  This option has no effect on the output of bases other than
+hexadecimal and octal, and these formats are always understood on input.
+
+@noindent
+When an output base is specified using the `@t{[#}@var{base}@t{]}' syntax,
+an appropriate base prefix will be output if necessary, so that the value
+output is valid syntax for input.  If the @t{#} is doubled, for example
+`@t{[##16]}', then no base prefix is output.
+
+@noindent
+Floating point constants are recognized by the presence of a decimal point
+or an exponent.  The decimal point may be the first character of the
+constant, but the exponent character @t{e} or @t{E} may not, as it will be
+taken for a parameter name.
+
+@noindent
+@cindex arithmetic operators
+@cindex operators, arithmetic
+An arithmetic expression uses nearly the same syntax, precedence, and
+associativity of expressions in C.
+The following operators are supported (listed in decreasing order
+of precedence):
+
+@noindent
+@table @asis
+@item @t{+ - ! ~ ++ --}
+unary plus/minus, logical NOT, complement, @{pre,post@}@{in,de@}crement
+@item @t{<< >>}
+bitwise shift left, right
+@item @t{&}
+bitwise AND
+@item @t{^}
+bitwise XOR
+@item @t{|}
+bitwise OR
+@item @t{**}
+exponentiation
+@item @t{* / %}
+multiplication, division, modulus (remainder)
+@item @t{+ -}
+addition, subtraction
+@item @t{< > <= >=}
+comparison
+@item @t{== !=}
+equality and inequality
+@item @t{&&}
+logical AND
+@item @t{|| ^^}
+logical OR, XOR
+@item @t{? :}
+ternary operator
+@item @t{= += -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **=}
+assignment
+@item @t{,}
+comma operator
+@end table
+
+@noindent
+The operators `@t{&&}', `@t{||}', `@t{&&=}', and `@t{||=}' are
+short-circuiting, and only one of the latter two expressions in a ternary
+operator is evaluated.  Note the precedence of the bitwise AND, OR,
+and XOR operators.
+
+@noindent
+@cindex mathematical functions, use of
+@cindex functions, math, use of
+Mathematical functions can be called with the syntax
+`@var{func}@t{(}@var{args}@t{)}', where the function decides
+if the @var{args} is used as a string or a comma-separated list of
+arithmetic expressions. The shell currently defines no mathematical
+functions by default, but the module @t{zsh/mathfunc} may be loaded with
+the @t{zmodload} builtin to provide standard floating point mathematical
+functions.
+
+@noindent
+An expression of the form `@t{##}@var{x}' where @var{x} is any character
+sequence such as `@t{a}', `@t{^A}', or `@t{\M-\C-x}' gives the ASCII
+value of this character and an expression of the form `@t{#}@var{foo}'
+gives the ASCII value of the first character of the value of the
+parameter @var{foo}.  Note that this is different from the expression
+`@t{$#}@var{foo}', a standard parameter substitution which gives the
+length of the parameter @var{foo}.  `@t{#\}' is accepted instead of
+`@t{##}', but its use is deprecated.
+
+@noindent
+Named parameters and subscripted arrays can be referenced by name within an
+arithmetic expression without using the parameter expansion syntax.  For
+example,
+
+@noindent
+@example
+((val2 = val1 * 2))
+@end example
+
+@noindent
+assigns twice the value of @t{$val1} to the parameter named @t{val2}.
+
+@noindent
+An internal integer representation of a named parameter
+can be specified with the @t{integer} builtin.
+@cindex parameters, integer
+@cindex integer parameters
+@findex integer, use of
+Arithmetic evaluation is performed on the value of each
+assignment to a named parameter declared integer
+in this manner.  Assigning a floating point number to an integer results in
+rounding down to the next integer.
+
+@noindent
+@cindex parameters, floating point
+@cindex floating point parameters
+@findex float, use of
+Likewise, floating point numbers can be declared with the @t{float}
+builtin; there are two types, differing only in their output format, as
+described for the @t{typeset} builtin.  The output format can be bypassed
+by using arithmetic substitution instead of the parameter substitution,
+i.e. `@t{$@{}@var{float}@t{@}}' uses the defined format, but
+`@t{$((}@var{float}@t{))}' uses a generic floating point
+format.
+
+@noindent
+Promotion of integer to floating point values is performed where
+necessary.  In addition, if any operator which requires an integer
+(`@t{~}', `@t{&}', `@t{|}', `@t{^}', `@t{%}', `@t{<<}', `@t{>>}' and their
+equivalents with assignment) is given a floating point argument, it will be
+silently rounded down to the next integer.
+
+@noindent
+Scalar variables can hold integer or floating point values at different
+times; there is no memory of the numeric type in this case.
+
+@noindent
+If a variable is first assigned in a numeric context without previously
+being declared, it will be implicitly typed as @t{integer} or @t{float} and
+retain that type either until the type is explicitly changed or until the
+end of the scope.  This can have unforeseen consequences.  For example, in
+the loop
+
+@noindent
+@example
+for (( f = 0; f < 1; f += 0.1 )); do
+# use $f
+done
+@end example
+
+@noindent
+if @t{f} has not already been declared, the first assignment will cause it
+to be created as an integer, and consequently the operation `@t{f += 0.1}'
+will always cause the result to be truncated to zero, so that the loop will
+fail.  A simple fix would be to turn the initialization into `@t{f = 0.0}'.
+It is therefore best to declare numeric variables with explicit types.
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/cond.yo
+@node Conditional Expressions, Prompt Expansion, Arithmetic Evaluation, Top
+
+@chapter Conditional Expressions
+@noindent
+@cindex conditional expressions
+@cindex expressions, conditional
+A @emph{conditional expression} is used with the @t{[[}
+compound command to test attributes of files and to compare strings.
+Each expression can be constructed from one or more
+of the following unary or binary expressions:
+
+@noindent
+@table @asis
+@item @t{-a} @var{file}
+true if @var{file} exists.
+
+@item @t{-b} @var{file}
+true if @var{file} exists and is a block special file.
+
+@item @t{-c} @var{file}
+true if @var{file} exists and is a character special file.
+
+@item @t{-d} @var{file}
+true if @var{file} exists and is a directory.
+
+@item @t{-e} @var{file}
+true if @var{file} exists.
+
+@item @t{-f} @var{file}
+true if @var{file} exists and is a regular file.
+
+@item @t{-g} @var{file}
+true if @var{file} exists and has its setgid bit set.
+
+@item @t{-h} @var{file}
+true if @var{file} exists and is a symbolic link.
+
+@item @t{-k} @var{file}
+true if @var{file} exists and has its sticky bit set.
+
+@item @t{-n} @var{string}
+true if length of @var{string} is non-zero.
+
+@item @t{-o} @var{option}
+true if option named @var{option} is on.  @var{option}
+may be a single character, in which case it is a single letter option name.
+(See @ref{Specifying Options}.)
+
+@item @t{-p} @var{file}
+true if @var{file} exists and is a FIFO special file (named pipe).
+
+@item @t{-r} @var{file}
+true if @var{file} exists and is readable by current process.
+
+@item @t{-s} @var{file}
+true if @var{file} exists and has size greater than zero.
+
+@item @t{-t} @var{fd}
+true if file descriptor number @var{fd}
+is open and associated with a terminal device.
+(note: @var{fd} is not optional)
+
+@item @t{-u} @var{file}
+true if @var{file} exists and has its setuid bit set.
+
+@item @t{-w} @var{file}
+true if @var{file} exists and is writable by current process.
+
+@item @t{-x} @var{file}
+true if @var{file} exists and is executable by current process.
+If @var{file} exists and is a directory, then the current process
+has permission to search in the directory.
+
+@item @t{-z} @var{string}
+true if length of @var{string} is zero.
+
+@item @t{-L} @var{file}
+true if @var{file} exists and is a symbolic link.
+
+@item @t{-O} @var{file}
+true if @var{file} exists and is owned by the effective user ID of this process.
+
+@item @t{-G} @var{file}
+true if @var{file} exists and its group matches
+the effective group ID of this process.
+
+@item @t{-S} @var{file}
+true if @var{file} exists and is a socket.
+
+@item @t{-N} @var{file}
+true if @var{file} exists and its access time is
+not newer than its modification time.
+
+@item @var{file1} @t{-nt} @var{file2}
+true if @var{file1} exists and is newer than @var{file2}.
+
+@item @var{file1} @t{-ot} @var{file2}
+true if @var{file1} exists and is older than @var{file2}.
+
+@item @var{file1} @t{-ef} @var{file2}
+true if @var{file1} and @var{file2} exist and refer to the same file.
+
+@item @var{string} @t{=} @var{pattern}
+@itemx @var{string} @t{==} @var{pattern}
+true if @var{string} matches @var{pattern}.
+The `@t{==}' form is the preferred one.  The `@t{=}' form is for
+backward compatibility and should be considered obsolete.
+
+@item @var{string} @t{!=} @var{pattern}
+true if @var{string} does not match @var{pattern}.
+
+@item @var{string1} @t{<} @var{string2}
+true if @var{string1} comes before @var{string2}
+based on ASCII value of their characters.
+
+@item @var{string1} @t{>} @var{string2}
+true if @var{string1} comes after @var{string2}
+based on ASCII value of their characters.
+
+@item @var{exp1} @t{-eq} @var{exp2}
+true if @var{exp1} is numerically equal to @var{exp2}.
+
+@item @var{exp1} @t{-ne} @var{exp2}
+true if @var{exp1} is numerically not equal to @var{exp2}.
+
+@item @var{exp1} @t{-lt} @var{exp2}
+true if @var{exp1} is numerically less than @var{exp2}.
+
+@item @var{exp1} @t{-gt} @var{exp2}
+true if @var{exp1} is numerically greater than @var{exp2}.
+
+@item @var{exp1} @t{-le} @var{exp2}
+true if @var{exp1} is numerically less than or equal to @var{exp2}.
+
+@item @var{exp1} @t{-ge} @var{exp2}
+true if @var{exp1} is numerically greater than or equal to @var{exp2}.
+
+@item @t{(} @var{exp} @t{)}
+true if @var{exp} is true.
+
+@item @t{!} @var{exp}
+true if @var{exp} is false.
+
+@item @var{exp1} @t{&&} @var{exp2}
+true if @var{exp1} and @var{exp2} are both true.
+
+@item @var{exp1} @t{||} @var{exp2}
+true if either @var{exp1} or @var{exp2} is true.
+
+@end table
+
+@noindent
+Normal shell expansion is performed on the @var{file}, @var{string} and
+@var{pattern} arguments, but the result of each expansion is constrained to
+be a single word, similar to the effect of double quotes.  However, pattern
+metacharacters are active for the @var{pattern} arguments; the patterns
+are the same as those used for filename generation, see
+@ref{Filename Generation}, but there is no special behaviour
+of `@t{/}' nor initial dots, and no glob qualifiers are allowed.
+
+@noindent
+In each of the above expressions, if
+@var{file} is of the form `@t{/dev/fd/}@var{n}',
+where @var{n} is an integer,
+then the test applied to the open file whose
+descriptor number is @var{n},
+even if the underlying system does not support
+the @t{/dev/fd} directory.
+
+@noindent
+In the forms which do numeric comparison, the expressions @var{exp}
+undergo arithmetic expansion as if they were enclosed in @t{$((...))}.
+
+@noindent
+For example, the following:
+
+@noindent
+@example
+[[ ( -f foo || -f bar ) && $report = y* ]] && print File exists.
+@end example
+
+@noindent
+tests if either file @t{foo} or file @t{bar} exists, and if so, if the
+value of the parameter @t{report} begins with `@t{y}'; if the complete
+condition is true, the message `@t{File exists.}' is printed.
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/prompt.yo
+@node Prompt Expansion, Expansion, Conditional Expressions, Top
+
+@chapter Prompt Expansion
+@noindent
+@cindex prompt expansion
+@cindex expansion, prompt
+Prompt sequences undergo a special form of expansion.  This type of expansion
+is also available using the @t{-P} option to the @t{print} builtin.
+
+@noindent
+@pindex PROMPT_SUBST, use of
+If the @t{PROMPT_SUBST} option is set, the prompt string is first subjected to
+@emph{parameter expansion},
+@emph{command substitution} and
+@emph{arithmetic expansion}.
+See
+@ref{Expansion}.
+
+@noindent
+Certain escape sequences may be recognised in the prompt string.
+
+@noindent
+@pindex PROMPT_BANG, use of
+If the @t{PROMPT_BANG} option is set, a `@t{!}' in the prompt is replaced
+by the current history event number.  A literal `@t{!}' may then be
+represented as `@t{!!}'.
+
+@noindent
+@pindex PROMPT_PERCENT, use of
+If the @t{PROMPT_PERCENT} option is set, certain escape sequences that
+start with `@t{%}' are expanded.
+Some escapes take an optional integer argument, which
+should appear between the `@t{%}' and the next character of the
+sequence.  The following escape sequences are recognized:
+
+@noindent
+
+@subsection Special characters
+@noindent
+@table @asis
+@item @t{%%}
+A `@t{%}'.
+
+@item @t{%)}
+A `@t{)}'.
+
+@end table
+
+@noindent
+
+@subsection Login information
+@noindent
+@table @asis
+@item @t{%l}
+The line (tty) the user is logged in on, without `@t{/dev/}' prefix.
+If the name starts with `@t{/dev/tty}', that prefix is stripped.
+
+@item @t{%M}
+The full machine hostname.
+
+@item @t{%m}
+The hostname up to the first `@t{.}'.
+An integer may follow the `@t{%}' to specify
+how many components of the hostname are desired.  With a negative integer,
+trailing components of the hostname are shown.
+
+@item @t{%n}
+@t{$USERNAME}.
+
+@item @t{%y}
+The line (tty) the user is logged in on, without `@t{/dev/}' prefix.
+This does not treat `@t{/dev/tty}' names specially.
+
+@end table
+
+@noindent
+
+@subsection Shell state
+@noindent
+@table @asis
+@item @t{%#}
+A `@t{#}' if the shell is running with privileges, a `@t{%}' if not.
+Equivalent to `@t{%(!.#.%%)}'.
+The definition of `privileged', for these purposes, is that either the
+effective user ID is zero, or, if POSIX.1e capabilities are supported, that
+at least one capability is raised in either the Effective or Inheritable
+capability vectors.
+
+@item @t{%?}
+The return code of the last command executed just before the prompt.
+
+@item @t{%_}
+The status of the parser, i.e. the shell constructs (like `@t{if}' and
+`@t{for}') that have been started on the command line. If given an integer
+number that many strings will be printed; zero or negative or no integer means
+print as many as there are.  This is most useful in prompts @t{PS2} for
+continuation lines and @t{PS4} for debugging with the @t{XTRACE} option; in
+the latter case it will also work non-interactively.
+
+@item @t{%d}
+@itemx @t{%/}
+Present working directory (@t{$PWD}).  If an integer follows the `@t{%}',
+it specifies a number of trailing components of @t{$PWD} to show; zero
+means the whole path.  A negative integer specifies leading components,
+i.e. @t{%-1d} specifies the first component.
+
+@item @t{%~}
+As @t{%d} and @t{%/}, but if @t{$PWD} has a named directory as its prefix,
+that part is replaced by a `@t{~}' followed by the name of the directory.
+If it starts with @t{$HOME}, that part is replaced by a `@t{~}'.
+
+@item @t{%h}
+@itemx @t{%!}
+Current history event number.
+
+@item @t{%i}
+The line number currently being executed in the script, sourced file, or
+shell function given by @t{%N}.  This is most useful for debugging as part
+of @t{$PS4}.
+
+@item @t{%j}
+The number of jobs.
+
+@item @t{%L}
+The current value of @t{$SHLVL}.
+
+@item @t{%N}
+The name of the script, sourced file, or shell function that zsh is
+currently executing, whichever was started most recently.  If there is
+none, this is equivalent to the parameter @t{$0}.  An integer may follow
+the `@t{%}' to specify a number of trailing path components to show; zero
+means the full path.  A negative integer specifies leading components.
+
+@item @t{%c}
+@itemx @t{%.}
+@itemx @t{%C}
+Trailing component of @t{$PWD}.
+An integer may follow the `@t{%}' to get more than one component.
+Unless `@t{%C}' is used, tilde contraction is performed first.  These are
+deprecated as @t{%c} and @t{%C} are equivalent to @t{%1~} and @t{%1/},
+respectively, while explicit positive integers have the same effect as for
+the latter two sequences.
+
+@end table
+
+@noindent
+
+@subsection Date and time
+@noindent
+@table @asis
+@item @t{%D}
+The date in @var{yy}@t{-}@var{mm}@t{-}@var{dd} format.
+
+@item @t{%T}
+Current time of day, in 24-hour format.
+
+@item @t{%t}
+@itemx @t{%@@}
+Current time of day, in 12-hour, am/pm format.
+
+@item @t{%*}
+Current time of day in 24-hour format, with seconds.
+
+@item @t{%w}
+The date in @var{day}@t{-}@var{dd} format.
+
+@item @t{%W}
+The date in @var{mm}@t{/}@var{dd}@t{/}@var{yy} format.
+
+@item @t{%D@{}@var{string}@t{@}}
+@var{string} is formatted using the @t{strftime} function.
+See man page strftime(3) for more details.  Three additional codes are
+available:  @t{%f} prints the day of the month, like @t{%e} but
+without any preceding space if the day is a single digit, and
+@t{%K}/@t{%L} correspond to @t{%k}/@t{%l} for the hour of the day
+(24/12 hour clock) in the same way.
+
+@end table
+
+@noindent
+
+@subsection Visual effects
+@noindent
+@table @asis
+@item @t{%B} (@t{%b})
+Start (stop) boldface mode.
+
+@item @t{%E}
+Clear to end of line.
+
+@item @t{%U} (@t{%u})
+Start (stop) underline mode.
+
+@item @t{%S} (@t{%s})
+Start (stop) standout mode.
+
+@item @t{%@{}...@t{%@}}
+Include a string as a literal escape sequence.
+The string within the braces should not change the cursor
+position.  Brace pairs can nest.
+
+@end table
+
+@noindent
+
+@subsection Conditional substrings
+@noindent
+@table @asis
+@item @t{%v}
+@vindex psvar, use of
+The value of the first element of the @t{psvar} array parameter.  Following
+the `@t{%}' with an integer gives that element of the array.  Negative
+integers count from the end of the array.
+
+@item @t{%(}@var{x.true-text.false-text}@t{)}
+Specifies a ternary expression.  The character following the @var{x} is
+arbitrary; the same character is used to separate the text for the
+`true' result from that for the `false' result.
+This separator may not appear in the @var{true-text}, except as part of a
+%-escape
+sequence.  A `@t{)}' may appear in the @var{false-text} as `@t{%)}'.
+@var{true-text}
+and @var{false-text} may both contain arbitrarily-nested escape
+sequences, including further ternary expressions.
+
+@noindent
+The left parenthesis may be preceded or followed by a positive integer @var{n},
+which defaults to zero.  A negative integer will be multiplied by -1.
+The test character @var{x} may be any of the following:
+
+@noindent
+@table @asis
+@item @t{!}
+True if the shell is running with privileges.
+@item @t{#}
+True if the effective uid of the current process is @var{n}.
+@item @t{?}
+True if the exit status of the last command was @var{n}.
+@item @t{_}
+True if at least @var{n} shell constructs were started.
+@item @t{C}
+@itemx @t{/}
+True if the current absolute path has at least @var{n} elements
+relative to the root directory, hence @t{/} is counted as 0 elements.
+@item @t{c}
+@itemx @t{.}
+@itemx @t{~}
+True if the current path, with prefix replacement, has at
+least @var{n} elements relative to the root directory, hence @t{/} is
+counted as 0 elements.
+@item @t{D}
+True if the month is equal to @var{n} (January = 0).
+@item @t{d}
+True if the day of the month is equal to @var{n}.
+@item @t{g}
+True if the effective gid of the current process is @var{n}.
+@item @t{j}
+True if the number of jobs is at least @var{n}.
+@item @t{L}
+True if the @t{SHLVL} parameter is at least @var{n}.
+@item @t{l}
+True if at least @var{n} characters have already been
+printed on the current line.
+@item @t{S}
+True if the @t{SECONDS} parameter is at least @var{n}.
+@item @t{T}
+True if the time in hours is equal to @var{n}.
+@item @t{t}
+True if the time in minutes is equal to @var{n}.
+@item @t{v}
+True if the array @t{psvar} has at least @var{n} elements.
+@item @t{w}
+True if the day of the week is equal to @var{n} (Sunday = 0).
+@end table
+
+@item @t{%<}@var{string}@t{<}
+@itemx @t{%>}@var{string}@t{>}
+@itemx @t{%[}@var{xstring}@t{]}
+Specifies truncation behaviour for the remainder of the prompt string.
+The third, deprecated, form is equivalent to `@t{%}@var{xstringx}',
+i.e. @var{x} may be `@t{<}' or `@t{>}'.
+The numeric argument, which in the third form may appear immediately
+after the `@t{[}', specifies the maximum permitted length of
+the various strings that can be displayed in the prompt.
+The @var{string} will be displayed in
+place of the truncated portion of any string; note this does not
+undergo prompt expansion.
+
+@noindent
+The forms with `@t{<}' truncate at the left of the string,
+and the forms with `@t{>}' truncate at the right of the string.
+For example, if the current directory is `@t{/home/pike}',
+the prompt `@t{%8<..<%/}' will expand to `@t{..e/pike}'.
+In this string, the terminating character (`@t{<}', `@t{>}' or `@t{]}'),
+or in fact any character, may be quoted by a preceding `@t{\}'; note
+when using @t{print -P}, however, that this must be doubled as the
+string is also subject to standard @t{print} processing, in addition
+to any backslashes removed by a double quoted string:  the worst case
+is therefore `@t{print -P "%<\\\\<<..."}'.
+
+@noindent
+If the @var{string} is longer than the specified truncation length,
+it will appear in full, completely replacing the truncated string.
+
+@noindent
+The part of the prompt string to be truncated runs to the end of the
+string, or to the end of the next enclosing group of the `@t{%(}'
+construct, or to the next truncation encountered at the same grouping
+level (i.e. truncations inside a `@t{%(}' are separate), which
+ever comes first.  In particular, a truncation with argument zero
+(e.g. `@t{%<<}') marks the end of the range of the string to be
+truncated while turning off truncation from there on. For example, the
+prompt '%10<...<%~%<<%# ' will print a truncated representation of the
+current directory, followed by a `@t{%}' or `@t{#}', followed by a
+space.  Without the `@t{%<<}', those two characters would be included
+in the string to be truncated.
+
+@end table
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/expn.yo
+@node Expansion, Parameters, Prompt Expansion, Top
+
+@chapter Expansion
+@noindent
+@cindex expansion
+
+The following types of expansions are performed in the indicated order in
+five steps:
+
+@noindent
+@table @asis
+@item @emph{History Expansion}
+This is performed only in interactive shells.
+
+@item @emph{Alias Expansion}
+Aliases are expanded immediately before the command line is parsed as
+explained
+in @ref{Aliasing}.
+
+@item @emph{Process Substitution}
+@itemx @emph{Parameter Expansion}
+@itemx @emph{Command Substitution}
+@itemx @emph{Arithmetic Expansion}
+@itemx @emph{Brace Expansion}
+These five are performed in one step in left-to-right fashion.  After
+these expansions, all unquoted occurrences of the characters `@t{\}',
+`@t{'}' and `@t{"}' are removed.
+
+@item @emph{Filename Expansion}
+If the @t{SH_FILE_EXPANSION} option is set, the order of expansion is
+modified for compatibility with @cite{sh} and @cite{ksh}.  In that case
+@emph{filename expansion} is performed immediately after @emph{alias expansion},
+preceding the set of five expansions mentioned above.
+
+@cindex globbing
+@item @emph{Filename Generation}
+This expansion, commonly referred to as @cite{globbing}, is always done last.
+
+@end table
+
+@noindent
+The following sections explain the types of expansion in detail.
+
+@noindent
+@menu
+* History Expansion::
+* Process Substitution::
+* Parameter Expansion::
+* Command Substitution::
+* Arithmetic Expansion::
+* Brace Expansion::
+* Filename Expansion::
+* Filename Generation::
+@end menu
+@node History Expansion, Process Substitution, , Expansion
+
+@section History Expansion
+@noindent
+@cindex history
+@cindex history expansion
+@cindex expansion, history
+History expansion allows you to use words from previous command
+lines in the command line you are typing.  This simplifies spelling
+corrections and the repetition of complicated commands or arguments.
+@vindex HISTSIZE, use of
+Immediately before execution, each command is saved in the history list,
+the size of which is controlled by the @t{HISTSIZE} parameter.  The one
+most recent command is always retained in any case.  Each saved command in
+the history list is called a history @emph{event} and is assigned a number,
+beginning with 1 (one) when the shell starts up.  The history number that
+you may see in your prompt (see
+@ref{Prompt Expansion}) is the number that is to be assigned to the @emph{next} command.
+
+@noindent
+@menu
+* Overview::
+* Event Designators::
+* Word Designators::
+* Modifiers::
+@end menu
+@node Overview, Event Designators, , History Expansion
+
+@subsection Overview
+@noindent
+@vindex histchars, use of
+A history expansion begins with the first character of the @t{histchars}
+parameter, which is `@t{!}' by default, and may occur anywhere on the
+command line; history expansions do not nest.  The `@t{!}' can be escaped
+with `@t{\}' or can be enclosed between a pair of single quotes (@t{@value{dsq}})
+to suppress its special meaning.  Double quotes will @emph{not} work for
+this.  Following this history character is an optional event designator
+(@ref{Event Designators}) and then an optional word
+designator (@ref{Word Designators}); if neither of these designators is
+present, no history expansion occurs.
+
+@noindent
+Input lines containing history expansions are echoed after being expanded,
+but before any other expansions take place and before the command is
+executed.  It is this expanded form that is recorded as the history event
+for later references.
+
+@noindent
+By default, a history reference with no event designator refers to the
+same event as any preceding history reference on that command line; if it
+is the only history reference in a command, it refers to the previous
+command.
+@pindex CSH_JUNKIE_HISTORY, use of
+However, if the option @t{CSH_JUNKIE_HISTORY} is set, then every history
+reference with no event specification @emph{always} refers to the previous
+command.
+
+@noindent
+For example, `@t{!}' is the event designator for the previous command, so
+`@t{!!:1}' always refers to the first word of the previous command, and
+`@t{!!$}' always refers to the last word of the previous command.  With
+@t{CSH_JUNKIE_HISTORY} set, then `@t{!:1}' and `@t{!$}' function in the
+same manner as `@t{!!:1}' and `@t{!!$}', respectively.  Conversely, if
+@t{CSH_JUNKIE_HISTORY} is unset, then `@t{!:1}' and `@t{!$}' refer to the
+first and last words, respectively, of the same event referenced by the
+nearest other history reference preceding them on the current command
+line, or to the previous command if there is no preceding reference.
+
+@noindent
+The character sequence `@t{^}@var{foo}@t{^}@var{bar}' (where `@t{^}' is
+actually the second character of the @t{histchars} parameter)
+repeats the last command, replacing the string @var{foo} with @var{bar}.
+More precisely, the sequence `@t{^}@var{foo}@t{^}@var{bar}@t{^}' is
+synonymous with `@t{!!:s}@t{^}@var{foo}@t{^}@var{bar}@t{^}', hence other
+modifiers (see @ref{Modifiers}) may follow the final `@t{^}'.
+
+@noindent
+If the shell encounters the character sequence `@t{!"}'
+in the input, the history mechanism is temporarily disabled until
+the current list (see
+@ref{Shell Grammar}) is fully parsed.  The `@t{!"}' is removed from the input, and any
+subsequent `@t{!}' characters have no special significance.
+
+@noindent
+@findex fc, use of
+A less convenient but more comprehensible form of command history support
+is provided by the @t{fc} builtin.
+@node Event Designators, Word Designators, Overview, History Expansion
+
+@subsection Event Designators
+@noindent
+@cindex history event designators
+@cindex event designators, history
+An event designator is a reference to a command-line entry in the history
+list.  In the list below, remember that the initial @t{`!'} in each item
+may be changed to another character by setting the @t{histchars}
+parameter.
+
+@noindent
+@table @asis
+@item @t{!}
+Start a history expansion, except when followed by a blank, newline,
+`@t{=}' or `@t{(}'.  If followed immediately by a word designator
+(@ref{Word Designators}), this forms a history reference
+with no event designator (@ref{Overview}).
+
+@item @t{!!}
+Refer to the previous command.
+By itself, this expansion
+repeats the previous command.
+
+@item @t{!}@var{n}
+Refer to command-line @var{n}.
+
+@item @t{!-}@var{n}
+Refer to the current command-line minus @var{n}.
+
+@item @t{!}@var{str}
+Refer to the most recent command starting with @var{str}.
+
+@item @t{!?}@var{str}[@t{?}]
+Refer to the most recent command containing @var{str}.  The trailing
+`@t{?}' is necessary if this reference is to be followed by a modifier or
+followed by any text that is not to be considered part of @var{str}.
+
+@item @t{!#}
+Refer to the current command line typed in so far.  The line is
+treated as if it were complete up to and including the word before the
+one with the `@t{!#}' reference.
+
+@item @t{!@{}...@t{@}}
+Insulate a history reference from adjacent characters (if necessary).
+
+@end table
+@node Word Designators, Modifiers, Event Designators, History Expansion
+
+@subsection Word Designators
+@noindent
+@cindex history word designators
+@cindex word designators, history
+A word designator indicates which word or words of a given command line are
+to be included in a history reference.  A `@t{:}' usually
+separates the event specification from the word designator.
+It may be omitted only if the word designator begins with a
+`@t{^}', `@t{$}', `@t{*}', `@t{-}' or `@t{%}'.
+Word designators include:
+
+@noindent
+@table @asis
+@item @t{0}
+The first input word (command).
+@item @var{n}
+The @var{n}th argument.
+@item @t{^}
+The first argument.  That is, @t{1}.
+@item @t{$}
+The last argument.
+@item @t{%}
+The word matched by (the most recent) @t{?}@var{str} search.
+@item @var{x}@t{-}@var{y}
+A range of words; @var{x} defaults to @t{0}.
+@item @t{*}
+All the arguments, or a null value if there are none.
+@item @var{x}@t{*}
+Abbreviates `@var{x}@t{-$}'.
+@item @var{x}@t{-}
+Like `@var{x}@t{*}' but omitting word @t{$}.
+@end table
+
+@noindent
+Note that a `@t{%}' word designator works only when used in one of
+`@t{!%}', `@t{!:%}' or `@t{!?}@var{str}@t{?:%}', and only when used after a
+@t{!?} expansion (possibly in an earlier command).  Anything else results
+in an error, although the error may not be the most obvious one.
+@node Modifiers, , Word Designators, History Expansion
+
+@subsection Modifiers
+@noindent
+@cindex modifiers
+@cindex colon modifiers
+@cindex history modifiers
+@cindex globbing modifiers
+@cindex parameter modifiers
+After the optional word designator, you can add
+a sequence of one or more of the following modifiers,
+each preceded by a `@t{:}'.  These modifiers also work on the result
+of @emph{filename generation} and @emph{parameter expansion}, except where
+noted.
+
+@noindent
+@table @asis
+@item @t{h}
+Remove a trailing pathname component, leaving the head.  This works
+like `@t{dirname}'.
+
+@item @t{r}
+Remove a filename extension of the form `@t{.}@var{xxx}', leaving
+the root name.
+
+@item @t{e}
+Remove all but the extension.
+
+@item @t{t}
+Remove all leading pathname components, leaving the tail.  This works
+like `@t{basename}'.
+
+@item @t{p}
+Print the new command but do not execute it.  Only works with history
+expansion.
+
+@item @t{q}
+Quote the substituted words, escaping further substitutions.  Works
+with history expansion and parameter expansion, though for parameters
+it is only useful if the resulting text is to be re-evaluated such as
+by @t{eval}.
+
+@item @t{Q}
+Remove one level of quotes from the substituted words.
+
+@item @t{x}
+Like @t{q}, but break into words at whitespace.  Does not work with
+parameter expansion.
+
+@item @t{l}
+Convert the words to all lowercase.
+
+@item @t{u}
+Convert the words to all uppercase.
+
+@item @t{s/}@var{l}@t{/}@var{r}[@t{/}]
+Substitute @var{r} for @var{l} as described below.
+Unless preceded immediately by a @t{g}, with no colon between,
+the substitution is done only for the
+first string that matches @var{l}.  For arrays and for filename
+generation, this applies to each word of the expanded text.
+
+@item @t{&}
+Repeat the previous @t{s} substitution.  Like @t{s}, may be preceded
+immediately by a @t{g}.  In parameter expansion the @t{&} must appear
+inside braces, and in filename generation it must be quoted with a
+backslash.
+
+@end table
+
+@noindent
+The @t{s/l/r/} substitution works as follows.  The left-hand side of
+substitutions are not regular expressions, but character strings.  Any
+character can be used as the delimiter in place of `@t{/}'.  A
+backslash quotes the delimiter character.  The character `@t{&}', in
+the right-hand-side @var{r}, is replaced by the text from the
+left-hand-side @var{l}.  The `@t{&}' can be quoted with a backslash.  A
+null @var{l} uses the previous string either from the previous @var{l}
+or from the contextual scan string @var{s} from `@t{!?}@var{s}'.  You can
+omit the rightmost delimiter if a newline immediately follows @var{r};
+the rightmost `@t{?}' in a context scan can similarly be omitted.
+Note the same record of the last @var{l} and @var{r} is maintained
+across all forms of expansion.
+
+@noindent
+The following @t{f}, @t{F}, @t{w} and @t{W} modifiers work only with
+parameter expansion and filename generation.  They are listed here to
+provide a single point of reference for all modifiers.
+
+@noindent
+@table @asis
+@item @t{f}
+Repeats the immediately (without a colon) following modifier until the
+resulting word doesn't change any more.
+
+@item @t{F:}@var{expr}@t{:}
+Like @t{f}, but repeats only @var{n} times if the expression
+@var{expr} evaluates to @var{n}.  Any character can be used instead of
+the `@t{:}'; if `@t{(}', `@t{[}', or `@t{@{}'
+is used as the opening delimiter,
+the closing delimiter should be '@t{)}', `@t{]}', or `@t{@}}',
+respectively.
+
+@item @t{w}
+Makes the immediately following modifier work on each word in the
+string.
+
+@item @t{W:}@var{sep}@t{:}
+Like @t{w} but words are considered to be the parts of the string
+that are separated by @var{sep}. Any character can be used instead of
+the `@t{:}'; opening parentheses are handled specially, see above.
+
+@end table
+@node Process Substitution, Parameter Expansion, History Expansion, Expansion
+
+@section Process Substitution
+@noindent
+@cindex process substitution
+@cindex substitution, process
+Each command argument of the form
+`@t{<(}@var{list}@t{)}',
+`@t{>(}@var{list}@t{)}' or
+`@t{=(}@var{list}@t{)}'
+is subject to process substitution.
+In the case of the @t{<} or @t{>} forms, the shell runs process
+@var{list} asynchronously.  If the system supports the @t{/dev/fd}
+mechanism, the command argument is the name of the device file
+corresponding to a file descriptor; otherwise, if the system supports named
+pipes (FIFOs), the command argument will be a named pipe.  If the form with
+@t{>} is selected then writing on this special file will provide input for
+@var{list}.  If @t{<} is used, then the file passed as an argument will
+be connected to the output of the @var{list} process.  For example,
+
+@noindent
+@example
+@t{paste <(cut -f1} @var{file1}@t{) <(cut -f3} @var{file2}@t{) |
+tee >(}@var{process1}@t{) >(}@var{process2}@t{) >/dev/null}
+@end example
+
+@noindent
+cuts fields 1 and 3 from the files @var{file1} and @var{file2} respectively,
+pastes the results together, and sends it to the processes
+@var{process1} and @var{process2}.
+
+@noindent
+If @t{=(}@var{...}@t{)} is used instead of
+@t{<(}@var{...}@t{)},
+then the file passed as an argument will be the name
+of a temporary file containing the output of the @var{list}
+process.  This may be used instead of the @t{<}
+form for a program that expects to lseek (see man page lseek(2))
+on the input file.
+
+@noindent
+The @t{=} form is useful as both the @t{/dev/fd} and the named pipe
+implementation of @t{<(}@var{...}@t{)} have drawbacks.  In 
+the former case, some programmes may automatically close the file
+descriptor in question before examining the file on the command line,
+particularly if this is necessary for security reasons such as when the
+programme is running setuid.  In the second case, if the
+programme does not actually open the file, the subshell attempting to read
+from or write to the pipe will (in a typical implementation, different
+operating systems may have different behaviour) block for ever and have to
+be killed explicitly.  In both cases, the shell actually supplies the
+information using a pipe, so that programmes that expect to lseek
+(see man page lseek(2)) on the file will not work.
+
+@noindent
+Also note that the previous example can be more compactly and
+efficiently written (provided the @t{MULTIOS} option is set) as:
+
+@noindent
+@example
+@t{paste <(cut -f1} @var{file1}@t{) <(cut -f3} @var{file2}@t{)} @t{> >(}@var{process1}@t{) > >(}@var{process2}@t{)}
+@end example
+
+@noindent
+The shell uses pipes instead of FIFOs to implement the latter
+two process substitutions in the above example.
+
+@noindent
+There is an additional problem with @t{>(}@var{process}@t{)}; when
+this is attached to an external command, the parent shell does not wait
+for @var{process} to finish and hence an immediately following command
+cannot rely on the results being complete.  The problem and solution are
+the same as described in the section @emph{MULTIOS} in
+@ref{Redirection}.  Hence in a simplified
+version of the example above:
+
+@noindent
+@example
+@t{paste <(cut -f1} @var{file1}@t{) <(cut -f3} @var{file2}@t{)} @t{> >(}@var{process}@t{)}
+@end example
+
+@noindent
+(note that no @t{MULTIOS} are involved), @var{process} will be run
+asynchronously.  The workaround is:
+
+@noindent
+@example
+@t{@{ paste <(cut -f1} @var{file1}@t{) <(cut -f3} @var{file2}@t{) @}} @t{> >(}@var{process}@t{)}
+@end example
+
+@noindent
+The extra processes here are
+spawned from the parent shell which will wait for their completion.
+
+@noindent
+@node Parameter Expansion, Command Substitution, Process Substitution, Expansion
+
+@section Parameter Expansion
+@noindent
+@cindex parameter expansion
+@cindex expansion, parameter
+The character `@t{$}' is used to introduce parameter expansions.
+See
+@ref{Parameters}
+for a description of parameters, including arrays, associative arrays,
+and subscript notation to access individual array elements.
+
+@noindent
+Note in particular the fact that words of unquoted parameters are not
+automatically split on whitespace unless the option @t{SH_WORD_SPLIT} is
+set; see references to this option below for more details.  This is an
+important difference from other shells.
+
+@noindent
+In the expansions discussed below that require a pattern, the form of
+the pattern is the same as that used for filename generation;
+see @ref{Filename Generation}.  Note that these patterns, along with
+the replacement text of any substitutions, are themselves subject to
+parameter expansion, command substitution, and arithmetic expansion.
+In addition to the following operations, the colon modifiers described in
+@ref{Modifiers} in @ref{History Expansion} can be
+applied:  for example, @t{$@{i:s/foo/bar/@}} performs string
+substitution on the expansion of parameter @t{$i}.
+
+@noindent
+@table @asis
+@item @t{$@{}@var{name}@t{@}}
+The value, if any, of the parameter @var{name} is substituted.
+The braces are required if the expansion is to be followed by
+a letter, digit, or underscore that is not to be interpreted
+as part of @var{name}.  In addition, more complicated forms of substitution
+usually require the braces to be present; exceptions, which only apply if
+the option @t{KSH_ARRAYS} is not set, are a single subscript or any colon
+modifiers appearing after the name, or any of the characters `@t{^}',
+`@t{=}', `@t{~}', `@t{#}' or `@t{+}' appearing before the name, all of
+which work with or without braces.
+
+@noindent
+If @var{name} is an array parameter, and the @t{KSH_ARRAYS} option is not
+set, then the value of each
+element of @var{name} is substituted, one element per word.  Otherwise, the
+expansion results in one word only; with @t{KSH_ARRAYS}, this is the first
+element of an array.  No field splitting is done on the result unless the
+@t{SH_WORD_SPLIT} option is set.
+
+@item @t{$@{+}@var{name}@t{@}}
+If @var{name} is the name of a set parameter `@t{1}' is substituted,
+otherwise `@t{0}' is substituted.
+
+@item @t{$@{}@var{name}@t{:-}@var{word}@t{@}}
+If @var{name} is set and is non-null then substitute its
+value; otherwise substitute @var{word}. If @var{name} is
+missing, substitute @var{word}.
+
+@item @t{$@{}@var{name}@t{:=}@var{word}@t{@}}
+@itemx @t{$@{}@var{name}@t{::=}@var{word}@t{@}}
+In the first form, if @var{name} is unset or is null then
+set it to @var{word}; in the second form, unconditionally
+set @var{name} to @var{word}.  In both forms, the value of
+the parameter is then substituted.
+
+@item @t{$@{}@var{name}@t{:?}@var{word}@t{@}}
+If @var{name} is set and is non-null then substitute
+its value; otherwise, print @var{word} and exit from the shell.
+Interactive shells instead return to the prompt.
+If @var{word} is omitted, then a standard message is printed.
+
+@item @t{$@{}@var{name}@t{:+}@var{word}@t{@}}
+If @var{name} is set and is non-null then substitute
+@var{word}; otherwise substitute nothing.
+
+@end table
+
+@noindent
+If the colon is omitted from one of the above expressions
+containing a colon, then the shell only checks whether
+@var{name} is set, not whether its value is null.
+
+@noindent
+In the following expressions, when @var{name} is an array and
+the substitution is not quoted, or if the `@t{(@@)}' flag or the
+@var{name}@t{[@@]} syntax is used, matching and replacement is
+performed on each array element separately.
+
+@noindent
+@table @asis
+@item @t{$@{}@var{name}@t{#}@var{pattern}@t{@}}
+@itemx @t{$@{}@var{name}@t{##}@var{pattern}@t{@}}
+If the @var{pattern} matches the beginning of the value of
+@var{name}, then substitute the value of @var{name} with
+the matched portion deleted; otherwise, just
+substitute the value of @var{name}.  In the first
+form, the smallest matching pattern is preferred;
+in the second form, the largest matching pattern is
+preferred.
+
+@item @t{$@{}@var{name}@t{%}@var{pattern}@t{@}}
+@itemx @t{$@{}@var{name}@t{%%}@var{pattern}@t{@}}
+If the @var{pattern} matches the end of the value of
+@var{name}, then substitute the value of @var{name} with
+the matched portion deleted; otherwise, just
+substitute the value of @var{name}.  In the first
+form, the smallest matching pattern is preferred;
+in the second form, the largest matching pattern is
+preferred.
+
+@item @t{$@{}@var{name}@t{:#}@var{pattern}@t{@}}
+If the @var{pattern} matches the value of @var{name}, then substitute
+the empty string; otherwise, just substitute the value of @var{name}.
+If @var{name} is an array
+the matching array elements are removed (use the `@t{(M)}' flag to
+remove the non-matched elements).
+
+@item @t{$@{}@var{name}@t{/}@var{pattern}@t{/}@var{repl}@t{@}}
+@itemx @t{$@{}@var{name}@t{//}@var{pattern}@t{/}@var{repl}@t{@}}
+Replace the longest possible match of @var{pattern} in the expansion of
+parameter @var{name} by string @var{repl}.  The first form
+replaces just the first occurrence, the second form all occurrences.
+Both @var{pattern} and @var{repl} are subject to double-quoted substitution,
+so that expressions like @t{$@{name/$opat/$npat@}} will work, but note the
+usual rule that pattern characters in @t{$opat} are not treated specially
+unless either the option @t{GLOB_SUBST} is set, or @t{$opat} is instead
+substituted as @t{$@{~opat@}}.
+
+@noindent
+The @var{pattern} may begin with a `@t{#}', in which case the
+@var{pattern} must match at the start of the string, or `@t{%}', in
+which case it must match at the end of the string.  The @var{repl} may
+be an empty string, in which case the final `@t{/}' may also be omitted.
+To quote the final `@t{/}' in other cases it should be preceded by a
+single backslash; this is not necessary if the
+`@t{/}' occurs inside a substituted parameter.  Note also that the `@t{#}'
+and `@t{%}' are not active if they occur inside a substituted parameter,
+even at the start.
+
+@noindent
+The first `@t{/}' may be preceded by a `@t{:}', in which case the match
+will only succeed if it matches the entire word.  Note also the
+effect of the @t{I} and @t{S} parameter expansion flags below; however,
+the flags @t{M}, @t{R}, @t{B}, @t{E} and @t{N} are not useful.
+
+@noindent
+For example,
+
+@noindent
+@example
+foo="twinkle twinkle little star" sub="t*e" rep="spy"
+print $@{foo//$@{~sub@}/$rep@}
+print $@{(S)foo//$@{~sub@}/$rep@}
+@end example
+
+@noindent
+Here, the `@t{~}' ensures that the text of @t{$sub} is treated as a
+pattern rather than a plain string.  In the first case, the longest
+match for @t{t*e} is substituted and the result is `@t{spy star}',
+while in the second case, the shortest matches are taken and the
+result is `@t{spy spy lispy star}'.
+
+@item @t{$@{#}@var{spec}@t{@}}
+If @var{spec} is one of the above substitutions, substitute
+the length in characters of the result instead of
+the result itself.  If @var{spec} is an array expression,
+substitute the number of elements of the result.
+Note that `@t{^}', `@t{=}', and `@t{~}', below, must appear
+to the left of `@t{#}' when these forms are combined.
+
+@item @t{$@{^}@var{spec}@t{@}}
+@pindex RC_EXPAND_PARAM, toggle
+@cindex array expansion style, rc
+@cindex rc, array expansion style
+Turn on the @t{RC_EXPAND_PARAM} option for the
+evaluation of @var{spec}; if the `@t{^}' is doubled, turn it off.
+When this option is set, array expansions of the form
+@var{foo}@t{$@{}@var{xx}@t{@}}@var{bar},
+where the parameter @var{xx}
+is set to @t{(}@var{a b c}@t{)}, are substituted with
+`@var{fooabar foobbar foocbar}' instead of the default
+`@var{fooa b cbar}'.
+
+@noindent
+Internally, each such expansion is converted into the
+equivalent list for brace expansion.  E.g., @t{$@{^var@}} becomes
+@t{@{$var[1],$var[2],}...@t{@}}, and is processed as described in
+@ref{Brace Expansion} below.
+If word splitting is also in effect the
+@t{$var[}@var{N}@t{]} may themselves be split into different list
+elements.
+
+@item @t{$@{=}@var{spec}@t{@}}
+@pindex SH_WORD_SPLIT, toggle
+@cindex field splitting, sh style, parameter
+@cindex sh, field splitting style, parameter
+Perform word splitting using the rules for @t{SH_WORD_SPLIT} during the
+evaluation of @var{spec}, but regardless of whether the parameter appears in
+double quotes; if the `@t{=}' is doubled, turn it off.
+@vindex IFS, use of
+This forces parameter expansions to be split into
+separate words before substitution, using @t{IFS} as a delimiter.
+This is done by default in most other shells.
+
+@noindent
+Note that splitting is applied to @var{word} in the assignment forms
+of @var{spec} @emph{before} the assignment to @var{name} is performed.
+This affects the result of array assignments with the @t{A} flag.
+
+@item @t{$@{~}@var{spec}@t{@}}
+@pindex GLOB_SUBST, toggle
+Turn on the @t{GLOB_SUBST} option for the evaluation of
+@var{spec}; if the `@t{~}' is doubled, turn it off.  When this option is
+set, the string resulting from the expansion will be interpreted as a
+pattern anywhere that is possible, such as in filename expansion and
+filename generation and pattern-matching contexts like the right
+hand side of the `@t{=}' and `@t{!=}' operators in conditions.
+
+@end table
+
+@noindent
+If a @t{$@{}...@t{@}} type parameter expression or a
+@t{$(}...@t{)} type command substitution is used in place of
+@var{name} above, it is expanded first and the result is used as if
+it were the value of @var{name}.  Thus it is
+possible to perform nested operations:  @t{$@{$@{foo#head@}%tail@}}
+substitutes the value of @t{$foo} with both `@t{head}' and `@t{tail}'
+deleted.  The form with @t{$(}...@t{)} is often useful in
+combination with the flags described next; see the examples below.
+Each @var{name} or nested @t{$@{}...@t{@}} in a parameter expansion may
+also be followed by a subscript expression as described in
+@ref{Array Parameters}.
+
+@noindent
+Note that double quotes may appear around nested expressions, in which
+case only the part inside is treated as quoted; for example,
+@t{$@{(f)"$(foo)"@}} quotes the result of @t{$(foo)}, but the flag `@t{(f)}'
+(see below) is applied using the rules for unquoted expansions.  Note
+further that quotes are themselves nested in this context; for example, in
+@t{"$@{(@@f)"$(foo)"@}"}, there are two sets of quotes, one surrounding the
+whole expression, the other (redundant) surrounding the @t{$(foo)} as
+before.
+
+@noindent
+
+@subsection Parameter Expansion Flags
+@noindent
+@cindex parameter expansion flags
+@cindex flags, parameter expansion
+@cindex substitution, parameter, flags
+If the opening brace is directly followed by an opening parenthesis,
+the string up to the matching closing parenthesis will be taken as a
+list of flags.  In cases where repeating a flag is meaningful, the
+repetitions need not be consecutive; for example, `(@t{q%q%q})'
+means the same thing as the more readable `(@t{%%qqq})'.  The
+following flags are supported:
+
+@noindent
+@table @asis
+@item @t{%}
+Expand all @t{%} escapes in the resulting words in the same way as in in
+prompts (see @ref{Prompt Expansion}). If this flag is given twice,
+full prompt expansion is done on the resulting words, depending on the
+setting of the @t{PROMPT_PERCENT}, @t{PROMPT_SUBST} and @t{PROMPT_BANG}
+options.
+
+@item @t{@@}
+In double quotes, array elements are put into separate words.
+E.g., `@t{"$@{(@@)foo@}"}' is equivalent to `@t{"$@{foo[@@]@}"}' and
+`@t{"$@{(@@)foo[1,2]@}"}' is the same as `@t{"$foo[1]" "$foo[2]"}'.
+This is distinct from @emph{field splitting} by the the @t{f}, @t{s}
+or @t{z} flags, which still applies within each array element.
+
+@item @t{A}
+Create an array parameter with `@t{$@{}...@t{=}...@t{@}}',
+`@t{$@{}...@t{:=}...@t{@}}' or `@t{$@{}...@t{::=}...@t{@}}'.
+If this flag is repeated (as in `@t{AA}'), create an associative
+array parameter.  Assignment is made before sorting or padding.
+The @var{name} part may be a subscripted range for ordinary
+arrays; the @var{word} part @emph{must} be converted to an array, for
+example by using `@t{$@{(AA)=}@var{name}@t{=}...@t{@}}' to activate
+field splitting, when creating an associative array.
+
+@item @t{a}
+With @t{o} or @t{O}, sort in array index order. Note that `@t{oa}' is
+therefore equivalent to the default but `@t{Oa}' is useful for
+obtaining an array's elements in reverse order.
+
+@item @t{c}
+With @t{$@{#}@var{name}@t{@}}, count the total number of characters in an array,
+as if the elements were concatenated with spaces between them.
+
+@item @t{C}
+Capitalize the resulting words.  `Words' in this case refers to sequences
+of alphanumeric characters separated by non-alphanumerics, @emph{not} to words
+that result from field splitting.
+
+@item @t{e}
+Perform @emph{parameter expansion}, @emph{command substitution} and
+@emph{arithmetic expansion} on the result. Such expansions can be
+nested but too deep recursion may have unpredictable effects.
+
+@item @t{f}
+Split the result of the expansion to lines. This is a shorthand
+for `@t{ps:\n:}'.
+
+@item @t{F}
+Join the words of arrays together using newline as a separator.
+This is a shorthand for `@t{pj:\n:}'.
+
+@item @t{i}
+With @t{o} or @t{O}, sort case-independently.
+
+@item @t{k}
+If @var{name} refers to an associative array, substitute the @emph{keys}
+(element names) rather than the values of the elements.  Used with
+subscripts (including ordinary arrays), force indices or keys to be
+substituted even if the subscript form refers to values.  However,
+this flag may not be combined with subscript ranges.
+
+@item @t{L}
+Convert all letters in the result to lower case.
+
+@item @t{n}
+With @t{o} or @t{O}, sort numerically.
+
+@item @t{o}
+Sort the resulting words in ascending order.
+
+@item @t{O}
+Sort the resulting words in descending order.
+
+@item @t{P}
+This forces the value of the parameter @var{name} to be interpreted as a
+further parameter name, whose value will be used where appropriate. If
+used with a nested parameter or command substitution, the result of that
+will be taken as a parameter name in the same way.  For example, if you
+have `@t{foo=bar}' and `@t{bar=baz}', the strings @t{$@{(P)foo@}},
+@t{$@{(P)$@{foo@}@}}, and @t{$@{(P)$(echo bar)@}} will be expanded to `@t{baz}'.
+
+@item @t{q}
+Quote the resulting words with backslashes. If this flag is given
+twice, the resulting words are quoted in single quotes and if it is
+given three times, the words are quoted in double quotes. If it is
+given four times, the words are quoted in single quotes preceded by a @t{$}.
+
+@item @t{Q}
+Remove one level of quotes from the resulting words.
+
+@item @t{t}
+Use a string describing the type of the parameter where the value
+of the parameter would usually appear. This string consists of keywords
+separated by hyphens (`@t{-}'). The first keyword in the string describes
+the main type, it can be one of `@t{scalar}', `@t{array}', `@t{integer}',
+`@t{float}' or `@t{association}'. The other keywords describe the type in
+more detail:
+
+@noindent
+@table @asis
+@item @t{local}
+for local parameters
+
+@item @t{left}
+for left justified parameters
+
+@item @t{right_blanks}
+for right justified parameters with leading blanks
+
+@item @t{right_zeros}
+for right justified parameters with leading zeros
+
+@item @t{lower}
+for parameters whose value is converted to all lower case when it is
+expanded
+
+@item @t{upper}
+for parameters whose value is converted to all upper case when it is
+expanded
+
+@item @t{readonly}
+for readonly parameters
+
+@item @t{tag}
+for tagged parameters
+
+@item @t{export}
+for exported parameters
+
+@item @t{unique}
+for arrays which keep only the first occurrence of duplicated values
+
+@item @t{hide}
+for parameters with the `hide' flag
+
+@item @t{special}
+for special parameters defined by the shell
+
+@end table
+
+@item @t{u}
+Expand only the first occurrence of each unique word.
+
+@item @t{U}
+Convert all letters in the result to upper case.
+
+@item @t{v}
+Used with @t{k}, substitute (as two consecutive words) both the key
+and the value of each associative array element.  Used with subscripts,
+force values to be substituted even if the subscript form refers to
+indices or keys.
+
+@item @t{V}
+Make any special characters in the resulting words visible.
+
+@item @t{w}
+With @t{$@{#}@var{name}@t{@}}, count words in arrays or strings; the @t{s}
+flag may be used to set a word delimiter.
+
+@item @t{W}
+Similar to @t{w} with the difference that empty words between
+repeated delimiters are also counted.
+
+@item @t{X}
+With this flag parsing errors occurring with the @t{Q} and @t{e} flags or the
+pattern matching forms such as `@t{$@{}@var{name}@t{#}@var{pattern}@t{@}}' 
+are reported. Without the flag they are silently ignored.
+
+@item @t{z}
+Split the result of the expansion into words using shell parsing to
+find the words, i.e. taking into account any quoting in the value.
+
+@noindent
+Note that this is done very late, as for the `@t{(s)}' flag. So to
+access single words in the result, one has to use nested expansions as 
+in `@t{$@{$@{(z)foo@}[2]@}}'. Likewise, to remove the quotes in the
+resulting words one would do: `@t{$@{(Q)$@{(z)foo@}@}}'.
+
+@end table
+
+@noindent
+The following flags (except @t{p}) are followed by one or more arguments
+as shown.  Any character, or the matching pairs `@t{(}...@t{)}',
+`@t{@{}...@t{@}}', `@t{[}...@t{]}', or `@t{<}...@t{>}', may be used in place
+of a colon as delimiters, but note that when a flag takes more than one
+argument, a matched pair of delimiters must surround each argument.
+
+@noindent
+@table @asis
+@item @t{p}
+Recognize the same escape sequences as the @t{print} builtin
+in string arguments to any of the flags described below.
+
+@item @t{j:}@var{string}@t{:}
+Join the words of arrays together using @var{string} as a separator.
+@pindex SH_WORD_SPLIT, use of
+Note that this occurs before field splitting by the @t{SH_WORD_SPLIT}
+option.
+
+@item @t{l:}@var{expr}@t{::}@var{string1}@t{::}@var{string2}@t{:}
+Pad the resulting words on the left.  Each word will be truncated if
+required and placed in a field @var{expr} characters wide.  The space
+to the left will be filled with @var{string1} (concatenated as often
+as needed) or spaces if @var{string1} is not given.  If both
+@var{string1} and @var{string2} are given, this string is inserted
+once directly to the left of each word, before padding.
+
+@item @t{r:}@var{expr}@t{::}@var{string1}@t{::}@var{string2}@t{:}
+As @t{l}, but pad the words on the right and insert @var{string2}
+on the right.
+
+@item @t{s:}@var{string}@t{:}
+Force field splitting (see the option @t{SH_WORD_SPLIT}) at the
+separator @var{string}.  Note that a @var{string} of two or more
+characters means all must all match in sequence; this differs from
+the treatment of two or more characters in the @t{IFS} parameter.
+
+@end table
+
+@noindent
+The following flags are meaningful with the @t{$@{}...@t{#}...@t{@}} or
+@t{$@{}...@t{%}...@t{@}} forms.  The @t{S} and @t{I} flags may also be
+used with the @t{$@{}...@t{/}...@t{@}} forms.
+
+@noindent
+@table @asis
+@item @t{S}
+Search substrings as well as beginnings or ends; with @t{#} start
+from the beginning and with @t{%} start from the end of the string.
+With substitution via @t{$@{}...@t{/}...@t{@}} or
+@t{$@{}...@t{//}...@t{@}}, specifies non-greedy matching, i.e. that the
+shortest instead of the longest match should be replaced.
+
+@item @t{I:}@var{expr}@t{:}
+Search the @var{expr}th match (where @var{expr} evaluates to a number).
+This only applies when searching for substrings, either with the @t{S}
+flag, or with @t{$@{}...@t{/}...@t{@}} (only the @var{expr}th match is
+substituted) or @t{$@{}...@t{//}...@t{@}} (all matches from the
+@var{expr}th on are substituted).  The default is to take the first match.
+
+@noindent
+The @var{expr}th match is counted such that there is either one or zero
+matches from each starting position in the string, although for global
+substitution matches overlapping previous replacements are ignored.  With
+the @t{$@{}...@t{%}...@t{@}} and @t{$@{}...@t{%%}...@t{@}} forms, the starting
+position for the match moves backwards from the end as the index increases,
+while with the other forms it moves forward from the start.
+
+@noindent
+Hence with the string
+@example
+which switch is the right switch for Ipswich?
+@end example
+substitutions of the form
+@t{$@{}(@t{SI:}@var{N}@t{:})@t{string#w*ch@}} as @var{N} increases
+from 1 will match and remove `@t{which}', `@t{witch}', `@t{witch}' and
+`@t{wich}'; the form using `@t{##}' will match and remove `@t{which switch
+is the right switch for Ipswich}', `@t{witch is the right switch for
+Ipswich}', `@t{witch for Ipswich}' and `@t{wich}'. The form using `@t{%}'
+will remove the same matches as for `@t{#}', but in reverse order, and the
+form using `@t{%%}' will remove the same matches as for `@t{##}' in reverse
+order.
+
+@item @t{B}
+Include the index of the beginning of the match in the result.
+
+@item @t{E}
+Include the index of the end of the match in the result.
+
+@item @t{M}
+Include the matched portion in the result.
+
+@item @t{N}
+Include the length of the match in the result.
+
+@item @t{R}
+Include the unmatched portion in the result (the @emph{R}est).
+
+@end table
+
+@noindent
+
+@subsection Rules
+@noindent
+
+@noindent
+Here is a summary of the rules for substitution; this assumes that braces
+are present around the substitution, i.e. @t{$@{...@}}.  Some particular
+examples are given below.  Note that the Zsh Development Group accepts
+@emph{no responsibility} for any brain damage which may occur during the
+reading of the following rules.
+
+@noindent
+@table @asis
+@item @t{1.} @emph{Nested Substitution}
+If multiple nested @t{$@{...@}} 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, just as if the nested substitution were the
+outermost.  The flags are not propagated up to enclosing
+substitutions; the nested substitution 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 `@t{(P)}' flag is present, the flags and any subscripts
+apply directly to the value of the nested substitution; for example, the
+expansion @t{$@{$@{foo@}@}} behaves exactly the same as @t{$@{foo@}}.
+
+@item @t{2.} @emph{Parameter Subscripting}
+If the value is a raw parameter reference with a subscript, such as
+@t{$@{}@var{var}@t{[3]@}}, the effect of subscripting is applied directly to
+the parameter.  Subscripts are evaluated left to right; subsequent
+subscripts apply to the scalar or array value yielded by the previous
+subscript.  Thus if @t{var} is an array, @t{$@{var[1][2]@}} is the second
+character of the first word, but @t{$@{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 @t{3.} @emph{Parameter Name Replacement}
+The effect of any @t{(P)} flag, which treats the value so far as a
+parameter name and replaces it with the corresponding value, is applied.
+
+@item @t{4.} @emph{Double-Quoted Joining}
+If the value after this process is an array, and the substitution
+appears in double quotes, and no @t{(@@)} flag is present at the current
+level, the words of the value are joined with the first character of the
+parameter @t{$IFS}, by default a space, between each word (single word
+arrays are not modified).  If the @t{(j)} flag is present, that is used for
+joining instead of @t{$IFS}.
+
+@item @t{5.} @emph{Nested Subscripting}
+Any remaining subscripts (i.e. of a nested substitution) are evaluated at
+this point, based on whether the value is an array or a scalar.  As with
+@t{2.}, multiple subscripts can appear.  Note that @t{$@{foo[2,4][2]@}} is
+thus equivalent to @t{$@{$@{foo[2,4]@}[2]@}} and also to
+@t{"$@{$@{(@@)foo[2,4]@}[2]@}"} (the nested substitution returns an array in
+both cases), but not to @t{"$@{$@{foo[2,4]@}[2]@}"} (the nested substitution
+returns a scalar because of the quotes).
+
+@item @t{6.} @emph{Modifiers}
+Any modifiers, as specified by a trailing `@t{#}', `@t{%}', `@t{/}'
+(possibly doubled) or by a set of modifiers of the form @t{:...} (see
+@ref{Modifiers} in @ref{History Expansion}), are applied to the words
+of the value at this level.
+
+@item @t{7.} @emph{Forced Joining}
+If the `@t{(j)}' flag is present, or no `@t{(j)}' flag is present but
+the string is to be split as given by rules @t{8.} or @t{9.}, and joining
+did not take place at step @t{4.}, any words in the value are joined
+together using the given string or the first character of @t{$IFS} if none.
+Note that the `@t{(F)}' flag implicitly supplies a string for joining in this
+manner.
+
+@item @t{8.} @emph{Forced Splitting}
+If one of the `@t{(s)}', `@t{(f)}' or `@t{(z)}' flags are present, or the `@t{=}'
+specifier was present (e.g. @t{$@{=}@var{var}@t{@}}), the word is split on
+occurrences of the specified string, or (for @t{=} with neither of the two
+flags present) any of the characters in @t{$IFS}.
+
+@item @t{9.} @emph{Shell Word Splitting}
+If no `@t{(s)}', `@t{(f)}' or `@t{=}' was given, but the word is not
+quoted and the option @t{SH_WORD_SPLIT} is set, the word is split on
+occurrences of any of the characters in @t{$IFS}.  Note this step, too,
+takes place at all levels of a nested substitution.
+
+@item @t{10.} @emph{Re-Evaluation}
+Any `@t{(e)}' flag is applied to the value, forcing it to be re-examined
+for new parameter substitutions, but also for command and arithmetic
+substitutions.
+
+@item @t{11.} @emph{Padding}
+Any padding of the value by the `@t{(l.}@var{fill}@t{.)}' or
+`@t{(r.}@var{fill}@t{.)}' flags is applied.
+
+@item @t{12.} @emph{Semantic Joining}
+In contexts where expansion semantics requires a single word to
+result, all words are rejoined with the first character of @t{IFS}
+between.  So in `@t{$@{(P}@t{)$@{(f}@t{)lines@}@}}'
+the value of @t{$@{lines@}} is split at newlines, but then must be
+joined again before the @t{P} flag can be applied.
+
+@noindent
+If a single word is not required, this rule is skipped.
+
+@end table
+
+@noindent
+
+@subsection Examples
+@noindent
+The flag @t{f} is useful to split a double-quoted substitution line by
+line.  For example, @t{$@{(f)"$(<}@var{file}@t{)"@}}
+substitutes the contents of @var{file} divided so that each line is
+an element of the resulting array.  Compare this with the effect of
+@t{$}@t{(<}@var{file}@t{)} alone, which divides the file
+up by words, or the same inside double quotes, which makes the entire
+content of the file a single string.
+
+@noindent
+The following illustrates the rules for nested parameter expansions.
+Suppose that @t{$foo} contains the array @t{(bar baz}@t{)}:
+
+@noindent
+@table @asis
+@item @t{"$@{(@@)$@{foo@}[1]@}"}
+This produces the result @t{b}.  First, the inner substitution
+@t{"$@{foo@}"}, which has no array (@t{@@}) flag, produces a single word
+result @t{"bar baz"}.  The outer substitution @t{"$@{(@@)...[1]@}"} detects
+that this is a scalar, so that (despite the `@t{(@@)}' flag) the subscript
+picks the first character. 
+
+@item @t{"$@{$@{(@@)foo@}[1]@}"}
+This produces the result `@t{bar}'.  In this case, the inner substitution
+@t{"$@{(@@)foo@}"} produces the array `@t{(bar baz}@t{)}'.  The outer
+substitution @t{"$@{...[1]@}"} detects that this is an array and picks the
+first word.  This is similar to the simple case @t{"$@{foo[1]@}"}.
+
+@end table
+
+@noindent
+As an example of the rules for word splitting and joining, suppose @t{$foo}
+contains the array `@t{(ax1 bx1}@t{)}'.  Then
+
+@noindent
+@table @asis
+@item @t{$@{(s/x/)foo@}}
+produces the words `@t{a}', `@t{1 b}' and `@t{1}'.
+
+@item @t{$@{(j/x/s/x/)foo@}}
+produces `@t{a}', `@t{1}', `@t{b}' and `@t{1}'.
+
+@item @t{$@{(s/x/)foo%%1*@}}
+produces `@t{a}' and `@t{ b}' (note the extra space).  As substitution
+occurs before either joining or splitting, the operation  first generates
+the modified array @t{(ax bx}@t{)}, which is joined to give
+@t{"ax bx"}, and then split to give `@t{a}', `@t{ b}' and `'.  The final
+empty string will then be elided, as it is not in double quotes.
+
+@end table
+
+@noindent
+@node Command Substitution, Arithmetic Expansion, Parameter Expansion, Expansion
+
+@section Command Substitution
+@noindent
+@cindex command substitution
+@cindex substitution, command
+A command enclosed in parentheses preceded by a dollar sign, like
+`@t{$(}...@t{)}', or quoted with grave 
+accents, like `@t{`}...@t{`}', is replaced with its standard output, with
+any trailing newlines deleted.
+If the substitution is not enclosed in double quotes, the
+output is broken into words using the @t{IFS} parameter.
+@vindex IFS, use of
+The substitution `@t{$(cat} @var{foo}@t{)}' may be replaced
+by the equivalent but faster `@t{$(<}@var{foo}@t{)}'.
+In either case, if the option @t{GLOB_SUBST} is set,
+the output is eligible for filename generation.
+@node Arithmetic Expansion, Brace Expansion, Command Substitution, Expansion
+
+@section Arithmetic Expansion
+@noindent
+@cindex arithmetic expansion
+@cindex expansion, arithmetic
+A string of the form `@t{$[}@var{exp}@t{]}' or
+`@t{$((}@var{exp}@t{))}' is substituted
+with the value of the arithmetic expression @var{exp}.  @var{exp} is
+subjected to @emph{parameter expansion}, @emph{command substitution}
+and @emph{arithmetic expansion} before it is evaluated.
+See @ref{Arithmetic Evaluation}.
+@node Brace Expansion, Filename Expansion, Arithmetic Expansion, Expansion
+
+@section Brace Expansion
+@noindent
+@cindex brace expansion
+@cindex expansion, brace
+A string of the form
+`@var{foo}@t{@{}@var{xx}@t{,}@var{yy}@t{,}@var{zz}@t{@}}@var{bar}'
+is expanded to the individual words
+`@var{fooxxbar}', `@var{fooyybar}' and `@var{foozzbar}'.
+Left-to-right order is preserved.  This construct
+may be nested.  Commas may be quoted in order to
+include them literally in a word.
+
+@noindent
+An expression of the form `@t{@{}@var{n1}@t{..}@var{n2}@t{@}}',
+where @var{n1} and @var{n2} are integers,
+is expanded to every number between
+@var{n1} and @var{n2} inclusive.  If either number begins with a
+zero, all the resulting numbers will be padded with leading zeroes to
+that minimum width.  If the numbers are in decreasing order the
+resulting sequence will also be in decreasing order.
+
+@noindent
+If a brace expression matches none of the above forms, it is left
+unchanged, unless the @t{BRACE_CCL} option is set.
+@pindex BRACE_CCL, use of
+In that case, it is expanded to a sorted list of the individual
+characters between the braces, in the manner of a search set.
+`@t{-}' is treated specially as in a search set, but `@t{^}' or `@t{!}' as
+the first character is treated normally.
+
+@noindent
+Note that brace expansion is not part of filename generation (globbing); an
+expression such as @t{*/@{foo,bar@}} is split into two separate words
+@t{*/foo} and @t{*/bar} before filename generation takes place.  In
+particular, note that this is liable to produce a `no match' error if
+@emph{either} of the two expressions does not match; this is to be contrasted
+with @t{*/(foo|bar)}, which is treated as a single pattern but otherwise
+has similar effects.
+@node Filename Expansion, Filename Generation, Brace Expansion, Expansion
+
+@section Filename Expansion
+@noindent
+@cindex filename expansion
+@cindex expansion, filename
+Each word is checked to see if it begins with an unquoted `@t{~}'.
+If it does, then the word up to a `@t{/}',
+or the end of the word if there is no `@t{/}',
+is checked to see if it can be substituted in one of the ways
+described here.  If so, then the `@t{~}' and the checked portion are
+replaced with the appropriate substitute value.
+
+@noindent
+A `@t{~}' by itself is replaced by the value of @t{$HOME}.
+A `@t{~}' followed by a `@t{+}' or a `@t{-}' is replaced by the value of
+@t{$PWD} or @t{$OLDPWD}, respectively.
+
+@noindent
+A `@t{~}' followed by a number is replaced by the directory at that
+position in the directory stack.
+`@t{~0}' is equivalent to `@t{~+}',
+and `@t{~1}' is the top of the stack.
+`@t{~+}' followed by a number is replaced by the directory at that
+position in the directory stack.
+`@t{~+0}' is equivalent to `@t{~+}',
+and `@t{~+1}' is the top of the stack.
+`@t{~-}' followed by a number is replaced by the directory that
+many positions from the bottom of the stack.
+`@t{~-0}' is the bottom of the stack.
+@pindex PUSHD_MINUS, use of
+The @t{PUSHD_MINUS}
+option exchanges the effects of `@t{~+}' and `@t{~-}' where they are
+followed by a number.
+
+@noindent
+@cindex directories, named
+@cindex named directories
+A `@t{~}' followed by anything not already covered is looked up as a
+named directory, and replaced by the value of that named directory if found.
+Named directories are typically home directories for users on the system.
+They may also be defined if the text after the `@t{~}' is the name
+of a string shell parameter whose value begins with a `@t{/}'.
+It is also possible to define directory names using the @t{-d} option to the
+@t{hash} builtin.
+
+@noindent
+In certain circumstances (in prompts, for instance), when the shell
+prints a path, the path is checked to see if it has a named
+directory as its prefix.  If so, then the prefix portion
+is replaced with a `@t{~}' followed by the name of the directory.
+The shortest way of referring to the directory is used,
+with ties broken in favour of using a named directory,
+except when the directory is @t{/} itself.  The parameters @t{$PWD} and
+@t{$OLDPWD} are never abbreviated in this fashion.
+
+@noindent
+If a word begins with an unquoted `@t{=}'
+and the @t{EQUALS} option is set,
+the remainder of the word is taken as the
+name of a command.  If a command
+exists by that name, the word is replaced
+by the full pathname of the command.
+
+@noindent
+Filename expansion is performed on the right hand side of a parameter
+assignment, including those appearing after commands of the
+@t{typeset} family.  In this case, the right hand side will be treated
+as a colon-separated list in the manner of the @t{PATH} parameter,
+so that a `@t{~}' or an `@t{=}' following a `@t{:}' is eligible for expansion.
+All such behaviour can be
+disabled by quoting the `@t{~}', the `@t{=}', or the whole expression (but not
+simply the colon); the @t{EQUALS} option is also respected.
+
+@noindent
+If the option @t{MAGIC_EQUAL_SUBST} is set, any unquoted shell
+argument in the form `@var{identifier}@t{=}@var{expression}' becomes eligible
+for file expansion as described in the previous paragraph.  Quoting the
+first `@t{=}' also inhibits this.
+@node Filename Generation, , Filename Expansion, Expansion
+
+@section Filename Generation
+@noindent
+@cindex filename generation
+If a word contains an unquoted instance of one of the characters
+`@t{*}', `@t{(}', `@t{|}', `@t{<}', `@t{[}', or `@t{?}', it is regarded
+as a pattern for filename generation, unless the @t{GLOB} option is unset.
+@pindex GLOB, use of
+If the @t{EXTENDED_GLOB} option is set,
+@pindex EXTENDED_GLOB, use of
+the `@t{^}' and `@t{#}' characters also denote a pattern; otherwise
+they are not treated specially by the shell.
+
+@noindent
+The word is replaced with a list of sorted filenames that match
+the pattern.  If no matching pattern is found, the shell gives
+an error message, unless the @t{NULL_GLOB} option is set,
+@pindex NULL_GLOB, use of
+in which case the word is deleted; or unless the @t{NOMATCH}
+option is unset, in which case the word is left unchanged.
+@pindex NOMATCH, use of
+
+@noindent
+In filename generation,
+the character `@t{/}' must be matched explicitly;
+also, a `@t{.}' must be matched
+explicitly at the beginning of a pattern or after a `@t{/}', unless the
+@t{GLOB_DOTS} option is set.
+@pindex GLOB_DOTS, use of
+No filename generation pattern
+matches the files `@t{.}' or `@t{..}'.  In other instances of pattern
+matching, the `@t{/}' and `@t{.}' are not treated specially.
+
+@subsection Glob Operators
+@noindent
+@table @asis
+@item @t{*}
+Matches any string, including the null string.
+
+@item @t{?}
+Matches any character.
+
+@item @t{[}...@t{]}
+Matches any of the enclosed characters.  Ranges of characters
+can be specified by separating two characters by a `@t{-}'.
+A `@t{-}' or `@t{]}' may be matched by including it as the
+first character in the list.
+@cindex character classes
+There are also several named classes of characters, in the form
+`@t{[:}@var{name}@t{:]}' with the following meanings:  `@t{[:alnum:]}'
+alphanumeric, `@t{[:alpha:]}' alphabetic,
+`@t{[:ascii:]}' 7-bit,
+`@t{[:blank:]}' space or tab,
+`@t{[:cntrl:]}' control character, `@t{[:digit:]}' decimal
+digit, `@t{[:graph:]}' printable character except whitespace,
+`@t{[:lower:]}' lowercase letter, `@t{[:print:]}' printable character,
+`@t{[:punct:]}' printable character neither alphanumeric nor whitespace,
+`@t{[:space:]}' whitespace character, `@t{[:upper:]}' uppercase letter, 
+`@t{[:xdigit:]}' hexadecimal digit.  These use the macros provided by
+the operating system to test for the given character combinations,
+including any modifications due to local language settings:  see
+man page ctype(3).  Note that the square brackets are additional
+to those enclosing the whole set of characters, so to test for a
+single alphanumeric character you need `@t{[[:alnum:]]}'.  Named
+character sets can be used alongside other types,
+e.g. `@t{[[:alpha:]0-9]}'.
+
+@item @t{[^}...@t{]}
+@itemx @t{[!}...@t{]}
+Like @t{[}...@t{]}, except that it matches any character which is
+not in the given set.
+
+@item @t{<}[@var{x}]@t{-}[@var{y}]@t{>}
+Matches any number in the range @var{x} to @var{y}, inclusive.
+Either of the numbers may be omitted to make the range open-ended;
+hence `@t{<->}' matches any number.  To match individual digits, the
+@t{[}...@t{]} form is more efficient.
+
+@noindent
+Be careful when using other wildcards adjacent to patterns of this form;
+for example, @t{<0-9>*} will actually match any number whatsoever at the
+start of the string, since the `@t{<0-9>}' will match the first digit, and
+the `@t{*}' will match any others.  This is a trap for the unwary, but is
+in fact an inevitable consequence of the rule that the longest possible
+match always succeeds.  Expressions such as `@t{<0-9>[^[:digit:]]*}' can be
+used instead.
+
+@item @t{(}...@t{)}
+Matches the enclosed pattern.  This is used for grouping.
+If the @t{KSH_GLOB} option is set, then a
+`@t{@@}', `@t{*}', `@t{+}', `@t{?}' or `@t{!}' immediately preceding
+the `@t{(}' is treated specially, as detailed below. The option
+@t{SH_GLOB} prevents bare parentheses from being used in this way, though
+the @t{KSH_GLOB} option is still available.
+
+@noindent
+Note that grouping cannot extend over multiple directories: it is an error
+to have a `@t{/}' within a group (this only applies for patterns used in
+filename generation).  There is one exception:  a group of the form
+@t{(}@var{pat}@t{/)#} appearing as a complete path segment can
+match a sequence of directories.  For example, @t{foo/(a*/)#bar} matches
+@t{foo/bar}, @t{foo/any/bar}, @t{foo/any/anyother/bar}, and so on.
+
+@item @var{x}@t{|}@var{y}
+Matches either @var{x} or @var{y}.
+This operator has lower precedence than any other.
+The `@t{|}' character
+must be within parentheses, to avoid interpretation as a pipeline.
+
+@item @t{^}@var{x}
+(Requires @t{EXTENDED_GLOB} to be set.)
+Matches anything except the pattern @var{x}.
+This has a higher precedence than `@t{/}', so `@t{^foo/bar}'
+will search directories in `@t{.}' except `@t{./foo}'
+for a file named `@t{bar}'.
+
+@item @var{x}@t{~}@var{y}
+(Requires @t{EXTENDED_GLOB} to be set.)
+Match anything that matches the pattern @var{x} but does not match @var{y}.
+This has lower precedence than any operator except `@t{|}', so
+`@t{*/*~foo/bar}' will search for all files in all directories in `@t{.}'
+and then exclude `@t{foo/bar}' if there was such a match.
+Multiple patterns can be excluded by
+`@var{foo}@t{~}@var{bar}@t{~}@var{baz}'.
+In the exclusion pattern (@var{y}), `@t{/}' and `@t{.}' are not treated
+specially the way they usually are in globbing.
+
+@item @var{x}@t{#}
+(Requires @t{EXTENDED_GLOB} to be set.)
+Matches zero or more occurrences of the pattern @var{x}.
+This operator has high precedence; `@t{12#}' is equivalent to `@t{1(2#)}',
+rather than `@t{(12)#}'.  It is an error for an unquoted `@t{#}' to follow
+something which cannot be repeated; this includes an empty string, a
+pattern already followed by `@t{##}', or parentheses when part of a
+@t{KSH_GLOB} pattern (for example, `@t{!(}@var{foo}@t{)#}' is
+invalid and must be replaced by
+`@t{*(!(}@var{foo}@t{))}').
+
+@item @var{x}@t{##}
+(Requires @t{EXTENDED_GLOB} to be set.)
+Matches one or more occurrences of the pattern @var{x}.
+This operator has high precedence; `@t{12##}' is equivalent to `@t{1(2##)}',
+rather than `@t{(12)##}'.  No more than two active `@t{#}' characters may
+appear together.
+
+@end table
+
+@subsection ksh-like Glob Operators
+@noindent
+@pindex KSH_GLOB, use of
+If the @t{KSH_GLOB} option is set, the effects of parentheses can be
+modified by a preceding `@t{@@}', `@t{*}', `@t{+}', `@t{?}' or `@t{!}'.
+This character need not be unquoted to have special effects,
+but the `@t{(}' must be.
+
+@noindent
+@table @asis
+@item @t{@@(}...@t{)}
+Match the pattern in the parentheses.  (Like `@t{(}...@t{)}'.)
+
+@item @t{*(}...@t{)}
+Match any number of occurrences.  (Like `@t{(}...@t{)#}'.)
+
+@item @t{+(}...@t{)}
+Match at least one occurrence.  (Like `@t{(}...@t{)##}'.)
+
+@item @t{?(}...@t{)}
+Match zero or one occurrence.  (Like `@t{(|}...@t{)}'.)
+
+@item @t{!(}...@t{)}
+Match anything but the expression in parentheses.
+(Like `@t{(^(}...@t{))}'.)
+
+@end table
+
+@subsection Precedence
+@noindent
+@cindex precedence of glob operators
+The precedence of the operators given above is (highest) `@t{^}', `@t{/}',
+`@t{~}', `@t{|}' (lowest); the
+remaining operators are simply treated from left to right as part of a
+string, with `@t{#}' and `@t{##}' applying to the shortest possible
+preceding unit (i.e. a character, `@t{?}', `@t{[}...@t{]}',
+`@t{<}...@t{>}', or a parenthesised expression).  As mentioned
+above, a `@t{/}' used as a directory separator may not appear inside
+parentheses, while a `@t{|}' must do so; in patterns used in other contexts
+than filename generation (for example, in @t{case} statements and tests
+within `@t{[[}...@t{]]}'), a `@t{/}' is not special; and `@t{/}' is also
+not special after a `@t{~}' appearing outside parentheses in a filename
+pattern.
+
+@subsection Globbing Flags
+@noindent
+There are various flags which affect any text to their right up to the
+end of the enclosing group or to the end of the pattern; they require
+the @t{EXTENDED_GLOB} option. All take the form
+@t{(#}@var{X}@t{)} where @var{X} may have one of the following
+forms:
+
+@noindent
+@table @asis
+@item i
+Case insensitive:  upper or lower case characters in the pattern match
+upper or lower case characters.
+
+@item l
+Lower case characters in the pattern match upper or lower case
+characters; upper case characters in the pattern still only match
+upper case characters.
+
+@item I
+Case sensitive:  locally negates the effect of @t{i} or @t{l} from
+that point on.
+
+@item b
+Activate backreferences for parenthesised groups in the pattern;
+this does not work in filename generation.  When a pattern with a set of
+active parentheses is matched, the strings matched by the groups are
+stored in the array @t{$match}, the indices of the beginning of the matched
+parentheses in the array @t{$mbegin}, and the indices of the end in the array
+@t{$mend}, with the first element of each array corresponding to the first
+parenthesised group, and so on.  These arrays are not otherwise special to
+the shell.  The indices use the same convention as does parameter
+substitution, so that elements of @t{$mend} and @t{$mbegin} may be used in
+subscripts; the @t{KSH_ARRAYS} option is respected.  Sets of globbing flags
+are not considered parenthesised groups; only the first nine active
+parentheses can be referenced.
+
+@noindent
+For example,
+
+@noindent
+@example
+foo="a string with a message"
+if [[ $foo = (a|an)' '(#b)(*)' '* ]]; then
+  print $@{foo[$mbegin[1],$mend[1]]@}
+fi
+@end example
+
+@noindent
+prints `@t{string with a}'.  Note that the first parenthesis is before the
+@t{(#b)} and does not create a backreference.
+
+@noindent
+Backreferences work with all forms of pattern matching other than filename
+generation, but note that when performing matches on an entire array, such
+as @t{$@{}@var{array}@t{#}@var{pattern}@t{@}}, or a global substitution, such
+as @t{$@{}@var{param}@t{//}@var{pat}@t{/}@var{repl}@t{@}}, only the data for the
+last match remains available.  In the case of global replacements this may
+still be useful.  See the example for the @t{m} flag below.
+
+@noindent
+The numbering of backreferences strictly follows the order of the opening
+parentheses from left to right in the pattern string, although sets of
+parentheses may be nested.  There are special rules for parentheses followed
+by `@t{#}' or `@t{##}'.  Only the last match of the parenthesis is
+remembered: for example, in `@t{[[ abab = (#b)([ab])# ]]}', only the final
+`@t{b}' is stored in @t{match[1]}.  Thus extra parentheses may be necessary
+to match the complete segment: for example, use `@t{X((ab|cd)#)Y}' to match
+a whole string of either `@t{ab}' or `@t{cd}' between `@t{X}' and `@t{Y}',
+using the value of @t{$match[1]} rather than @t{$match[2]}.
+
+@noindent
+If the match fails none of the parameters is altered, so in some cases it
+may be necessary to initialise them beforehand.  If some of the
+backreferences fail to match --- which happens if they are in an alternate
+branch which fails to match, or if they are followed by @t{#} and matched
+zero times --- then the matched string is set to the empty string, and the
+start and end indices are set to -1.
+
+@noindent
+Pattern matching with backreferences is slightly slower than without.
+
+@item B
+Deactivate backreferences, negating the effect of the @t{b} flag from that
+point on.
+
+@item m
+Set references to the match data for the entire string matched; this is
+similar to backreferencing and does not work in filename generation.  The
+flag must be in effect at the end of the pattern, i.e. not local to a
+group. The parameters @t{$MATCH},  @t{$MBEGIN} and @t{$MEND} will be set to
+the string matched and to the indices of the beginning and end of the
+string, respectively.  This is most useful in parameter substitutions, as
+otherwise the string matched is obvious.
+
+@noindent
+For example,
+
+@noindent
+@example
+arr=(veldt jynx grimps waqf zho buck)
+print $@{arr//(#m)[aeiou]/$@{(U)MATCH@}@}
+@end example
+
+@noindent
+forces all the matches (i.e. all vowels) into uppercase, printing
+`@t{vEldt jynx grImps wAqf zhO bUck}'.
+
+@noindent
+Unlike backreferences, there is no speed penalty for using match
+references, other than the extra substitutions required for the
+replacement strings in cases such as the example shown.
+
+@item M
+Deactivate the @t{m} flag, hence no references to match data will be
+created.
+
+@item @t{a}@var{num}
+Approximate matching: @var{num} errors are allowed in the string matched by
+the pattern.  The rules for this are described in the next subsection.
+
+@item @t{s}, @t{e}
+Unlike the other flags, these have only a local effect, and each must
+appear on its own:  `@t{(#s)}' and `@t{(#e)}' are the only valid forms.
+The `@t{(#s)}' flag succeeds only at the start of the test string, and the
+`@t{(#e)}' flag succeeds only at the end of the test string; they
+correspond to `@t{^}' and `@t{$}' in standard regular expressions.  They
+are useful for matching path segments in patterns other than those in
+filename generation (where path segments are in any case treated
+separately).  For example, `@t{*((#s)|/)test((#e)|/)*}' matches a path
+segment `@t{test}' in any of the following strings: @t{test},
+@t{test/at/start}, @t{at/end/test}, @t{in/test/middle}.
+
+@noindent
+Another use is in parameter substitution; for example
+`@t{$@{array/(#s)A*Z(#e)@}}' will remove only elements of an array which
+match the complete pattern `@t{A*Z}'.  There are other ways of performing
+many operations of this type, however the combination of the substitution
+operations `@t{/}' and `@t{//}' with the `@t{(#s)}' and `@t{(#e)}' flags
+provides a single simple and memorable method.
+
+@noindent
+Note that assertions of the form `@t{(^(#s))}' also work, i.e. match
+anywhere except at the start of the string, although this actually means
+`anything except a zero-length portion at the start of the string'; you
+need to use `@t{(""~(#s))}' to match a zero-length portion of the string
+not at the start.
+
+@item @t{q}
+A `@t{q}' and everything up to the closing parenthesis of the globbing
+flags are ignored by the pattern matching code.  This is intended to
+support the use of glob qualifiers, see below.  The result is that
+the pattern `@t{(#b)(*).c(#q.)}' can be used both for globbing and for
+matching against a string.  In the former case, the `@t{(#q.)}' will be
+treated as a glob qualifier and the `@t{(#b)}' will not be useful, while in
+the latter case the `@t{(#b)}' is useful for backreferences and the
+`@t{(#q.)}' will be ignored.  Note that colon modifiers in the glob
+qualifiers are also not applied in ordinary pattern matching.
+
+@end table
+
+@noindent
+For example, the test string @t{fooxx} can be matched by the pattern
+@t{(#i}@t{)FOOXX}, but not by @t{(#l}@t{)FOOXX},
+@t{(#i}@t{)FOO}@t{(#I}@t{)XX} or
+@t{((#i}@t{)FOOX}@t{)X}.  The string
+@t{(#ia2}@t{)readme} specifies case-insensitive matching of
+@t{readme} with up to two errors.
+
+@noindent
+When using the ksh syntax for grouping both @t{KSH_GLOB} and
+@t{EXTENDED_GLOB} must be set and the left parenthesis should be
+preceded by @t{@@}.  Note also that the flags do not affect letters
+inside @t{[...]} groups, in other words @t{(#i}@t{)[a-z]}
+still matches only lowercase letters.  Finally, note that when
+examining whole paths case-insensitively every directory must be
+searched for all files which match, so that a pattern of the form
+@t{(#i}@t{)/foo/bar/...} is potentially slow.
+
+@noindent
+
+@subsection Approximate Matching
+@noindent
+When matching approximately, the shell keeps a count of the errors found,
+which cannot exceed the number specified in the
+@t{(#a}@var{num}@t{)} flags.  Four types of error are recognised:
+
+@noindent
+@table @asis
+@item 1.
+Different characters, as in @t{fooxbar} and @t{fooybar}.
+
+@item 2.
+Transposition of characters, as in @t{banana} and @t{abnana}.
+
+@item 3.
+A character missing in the target string, as with the pattern @t{road} and
+target string @t{rod}.
+
+@item 4.
+An extra character appearing in the target string, as with @t{stove}
+and @t{strove}.
+
+@end table
+
+@noindent
+Thus, the pattern @t{(#a3}@t{)abcd} matches @t{dcba}, with the
+errors occurring by using the first rule twice and the second once,
+grouping the string as @t{[d][cb][a]} and @t{[a][bc][d]}.
+
+@noindent
+Non-literal parts of the pattern must match exactly, including characters
+in character ranges: hence @t{(#a1}@t{)???}  matches strings of
+length four, by applying rule 4 to an empty part of the pattern, but not
+strings of length two, since all the @t{?} must match.  Other characters
+which must match exactly are initial dots in filenames (unless the
+@t{GLOB_DOTS} option is set), and all slashes in filenames, so that
+@t{a/bc} is two errors from @t{ab/c} (the slash cannot be transposed with
+another character).  Similarly, errors are counted separately for
+non-contiguous strings in the pattern, so that @t{(ab|cd}@t{)ef}
+is two errors from @t{aebf}.
+
+@noindent
+When using exclusion via the @t{~} operator, approximate matching is
+treated entirely separately for the excluded part and must be activated
+separately.  Thus, @t{(#a1}@t{)README~READ_ME} matches
+@t{READ.ME} but not @t{READ_ME}, as the trailing @t{READ_ME} is matched
+without approximation.  However,
+@t{(#a1}@t{)README~(#a1}@t{)READ_ME}
+does not match any pattern of the form @t{READ}@var{?}@t{ME} as all
+such forms are now excluded.
+
+@noindent
+Apart from exclusions, there is only one overall error count; however, the
+maximum errors allowed may be altered locally, and this can be delimited by
+grouping.  For example,
+@t{(#a1}@t{)cat}@t{((#a0}@t{)dog}@t{)fox}
+allows one error in total, which may not occur in the @t{dog} section, and
+the pattern
+@t{(#a1}@t{)cat}@t{(#a0}@t{)dog}@t{(#a1}@t{)fox}
+is equivalent.  Note that the point at which an error is first found is the
+crucial one for establishing whether to use approximation; for example,
+@t{(#a1)abc(#a0)xyz} will not match @t{abcdxyz}, because the error occurs
+at the `@t{x}', where approximation is turned off.
+
+@noindent
+Entire path segments may be matched approximately, so that
+`@t{(#a1)/foo/d/is/available/at/the/bar}' allows one error in any path
+segment.  This is much less efficient than without the @t{(#a1)}, however,
+since every directory in the path must be scanned for a possible
+approximate match.  It is best to place the @t{(#a1)} after any path
+segments which are known to be correct.
+
+@noindent
+
+@subsection Recursive Globbing
+@noindent
+A pathname component of the form `@t{(}@var{foo}@t{/)#}'
+matches a path consisting of zero or more directories
+matching the pattern @var{foo}.
+
+@noindent
+As a shorthand, `@t{**/}' is equivalent to `@t{(*/)#}'; note that this
+therefore matches files in the current directory as well as
+subdirectories.
+Thus:
+
+@noindent
+@example
+ls (*/)#bar
+@end example
+
+@noindent
+or
+
+@noindent
+@example
+ls **/bar
+@end example
+
+@noindent
+does a recursive directory search for files named `@t{bar}' (potentially
+including the file `@t{bar}' in the current directory).  This form does not
+follow symbolic links; the alternative form `@t{***/}' does, but is
+otherwise identical.  Neither of these can be combined with other forms of
+globbing within the same path segment; in that case, the `@t{*}'
+operators revert to their usual effect.
+
+@subsection Glob Qualifiers
+@noindent
+@cindex globbing, qualifiers
+@cindex qualifiers, globbing
+Patterns used for filename generation may end in a
+list of qualifiers enclosed in parentheses.
+The qualifiers specify which filenames that otherwise match the given pattern
+will be inserted in the argument list.
+
+@noindent
+@pindex BARE_GLOB_QUAL, use of
+If the option @t{BARE_GLOB_QUAL} is set, then a trailing set of parentheses
+containing no `@t{|}' or `@t{(}' characters (or `@t{~}' if it is special)
+is taken as a set of
+glob qualifiers.  A glob subexpression that would normally be taken as glob
+qualifiers, for example `@t{(^x)}', can be forced to be treated as part of
+the glob pattern by doubling the parentheses, in this case producing
+`@t{((^x))}'.
+
+@noindent
+If the option @t{EXTENDED_GLOB} is set, a different syntax for glob
+qualifiers is available, namely `@t{(#qx)}' where @t{x} is any of the same
+glob qualifiers used in the other format.  The qualifiers must still appear
+at the end of the pattern.  However, with this syntax multiple glob
+qualifiers may be chained together.  They are treated as a logical AND of
+the individual sets of flags.  Also, as the syntax is unambiguous, the
+expression will be treated as glob qualifiers just as long any parentheses
+contained within it are balanced; appearance of `@t{|}', `@t{(}' or
+`@t{~}' does not negate the effect.  Note that qualifiers will be
+recognised in this form even if a bare glob qualifier exists at the end of
+the pattern, for example `@t{*(#q*)(.)}' will recognise executable regular
+files if both options are set; however, mixed syntax should probably be
+avoided for the sake of clarity.
+
+@noindent
+A qualifier may be any one of the following:
+
+@noindent
+@table @asis
+@item @t{/}
+directories
+
+@item @t{F}
+`full' (i.e. non-empty) directories.  Note that the
+opposite sense @t{(^F}@t{)} expands to empty directories
+and all non-directories.  Use @t{(/^F}@t{)} for
+empty directories
+
+@item @t{.}
+plain files
+
+@item @t{@@}
+symbolic links
+
+@item @t{=}
+sockets
+
+@item @t{p}
+named pipes (FIFOs)
+
+@item @t{*}
+executable plain files (0100)
+
+@item @t{%}
+device files (character or block special)
+
+@item @t{%b}
+block special files
+
+@item @t{%c}
+character special files
+
+@item @t{r}
+owner-readable files (0400)
+
+@item @t{w}
+owner-writable files (0200)
+
+@item @t{x}
+owner-executable files (0100)
+
+@item @t{A}
+group-readable files (0040)
+
+@item @t{I}
+group-writable files (0020)
+
+@item @t{E}
+group-executable files (0010)
+
+@item @t{R}
+world-readable files (0004)
+
+@item @t{W}
+world-writable files (0002)
+
+@item @t{X}
+world-executable files (0001)
+
+@item @t{s}
+setuid files (04000)
+
+@item @t{S}
+setgid files (02000)
+
+@item @t{t}
+files with the sticky bit (01000)
+
+@item @t{f}@var{spec}
+files with access rights matching @var{spec}. This @var{spec} may be a
+octal number optionally preceded by a `@t{=}', a `@t{+}', or a
+`@t{-}'. If none of these characters is given, the behavior is the
+same as for `@t{=}'. The octal number describes the mode bits to be
+expected, if combined with a `@t{=}', the value given must match the
+file-modes exactly, with a `@t{+}', at least the bits in the
+given number must be set in the file-modes, and with a `@t{-}', the
+bits in the number must not be set. Giving a `@t{?}' instead of a
+octal digit anywhere in the number ensures that the corresponding bits 
+in the file-modes are not checked, this is only useful in combination
+with `@t{=}'.
+
+@noindent
+If the qualifier `@t{f}' is followed by any other character anything
+up to the next matching character (`@t{[}', `@t{@{}', and `@t{<}' match 
+`@t{]}', `@t{@}}', and `@t{>}' respectively, any other character
+matches itself) is taken as a list of comma-separated
+@var{sub-spec}s. Each @var{sub-spec} may be either an octal number as
+described above or a list of any of the characters `@t{u}', `@t{g}',
+`@t{o}', and `@t{a}', followed by a `@t{=}', a `@t{+}', or a
+`@t{-}', followed by a list of any of the characters `@t{r}', `@t{w}', 
+`@t{x}', `@t{s}', and `@t{t}', or an octal digit. The first list of
+characters specify which access rights are to be checked. If a `@t{u}'
+is given, those for the owner of the file are used, if a `@t{g}' is
+given, those of the group are checked, a `@t{o}' means to test those
+of other users, and the `@t{a}' says to test all three groups. The
+`@t{=}', `@t{+}', and `@t{-}' again says how the modes are to be
+checked and have the same meaning as described for the first form
+above. The second list of characters finally says which access rights
+are to be expected: `@t{r}' for read access, `@t{w}' for write access, 
+`@t{x}' for the right to execute the file (or to search a directory),
+`@t{s}' for the setuid and setgid bits, and `@t{t}' for the sticky
+bit.
+
+@noindent
+Thus, `@t{*(f70?)}' gives the files for which the owner has read,
+write, and execute permission, and for which other group members have
+no rights, independent of the permissions for other users. The pattern
+`@t{*(f-100)}' gives all files for which the owner does not have
+execute permission, and `@t{*(f:gu+w,o-rx:)}' gives the files for which 
+the owner and the other members of the group have at least write
+permission, and for which other users don't have read or execute
+permission.
+
+@item @t{e}@var{string}
+The @var{string} will be executed as shell code.  The filename will be
+included in the list if and only if the code returns a zero status (usually
+the status of the last command).  The first character after the `@t{e}'
+will be used as a separator and anything up to the next matching separator
+will be taken  as the @var{string}; `@t{[}', `@t{@{}', and `@t{<}' match
+`@t{]}', `@t{@}}', and `@t{>}', respectively, while any other character
+matches itself. Note that expansions must be quoted in the @var{string}
+to prevent them from being expanded before globbing is done.
+
+@noindent
+@vindex REPLY, use of
+@vindex reply, use of
+During the execution of @var{string} the filename currently being tested is
+available in the parameter @t{REPLY}; the parameter may be altered to
+a string to be inserted into the list instead of the original
+filename.  In addition, the parameter @t{reply} may be set to an array or a
+string, which overrides the value of @t{REPLY}.  If set to an array, the
+latter is inserted into the command line word by word.
+
+@noindent
+For example, suppose a directory contains a single file `@t{lonely}'.  Then
+the expression `@t{*(e:'reply=($@{REPLY@}@{1,2@})':)}' will cause the words
+`@t{lonely1 lonely2}' to be inserted into the command line.  Note the
+quotation marks.
+
+@item @t{d}@var{dev}
+files on the device @var{dev}
+
+@item @t{l}[@t{-}|@t{+}]@var{ct}
+files having a link count less than @var{ct} (@t{-}), greater than
+@var{ct} (@t{+}), or equal to @var{ct}
+
+@item @t{U}
+files owned by the effective user ID
+
+@item @t{G}
+files owned by the effective group ID
+
+@item @t{u}@var{id}
+files owned by user ID @var{id} if it is a number, if not, than the
+character after the `@t{u}' will be used as a separator and the string
+between it and the next matching separator
+(`@t{[}', `@t{@{}', and `@t{<}'
+match `@t{]}', `@t{@}}', and `@t{>}' respectively,
+any other character matches
+itself) will be taken as a user name, and the user ID of this user will
+be taken (e.g. `@t{u:foo:}' or `@t{u[foo]}' for user `@t{foo}')
+
+@item @t{g}@var{id}
+like @t{u}@var{id} but with group IDs or names
+
+@item @t{a}[@t{Mwhms}][@t{-}|@t{+}]@var{n}
+files accessed exactly @var{n} days ago.  Files accessed within the last
+@var{n} days are selected using a negative value for @var{n} (@t{-}@var{n}).
+Files accessed more than @var{n} days ago are selected by a positive @var{n}
+value (@t{+}@var{n}).  Optional unit specifiers `@t{M}', `@t{w}',
+`@t{h}', `@t{m}' or `@t{s}' (e.g. `@t{ah5}') cause the check to be
+performed with months (of 30 days), weeks, hours, minutes or seconds
+instead of days, respectively.  For instance, `@t{echo *(ah-5)}' would
+echo files accessed within the last five hours.
+
+@item @t{m}[@t{Mwhms}][@t{-}|@t{+}]@var{n}
+like the file access qualifier, except that it uses the file modification
+time.
+
+@item @t{c}[@t{Mwhms}][@t{-}|@t{+}]@var{n}
+like the file access qualifier, except that it uses the file inode change
+time.
+
+@item @t{L}[@t{+}|@t{-}]@var{n}
+files less than @var{n} bytes (@t{-}), more than @var{n} bytes (@t{+}), or
+exactly @var{n} bytes in length. If this flag is directly followed by a `@t{k}'
+(`@t{K}'), `@t{m}' (`@t{M}'), or `@t{p}' (`@t{P}') (e.g. `@t{Lk-50}')
+the check is performed with kilobytes, megabytes, or blocks (of 512 bytes)
+instead.
+
+@item @t{^}
+negates all qualifiers following it
+
+@item @t{-}
+toggles between making the qualifiers work on symbolic links (the
+default) and the files they point to
+
+@item @t{M}
+sets the @t{MARK_DIRS} option for the current pattern
+@pindex MARK_DIRS, setting in pattern
+
+@item @t{T}
+appends a trailing qualifier mark to the filenames, analogous to the
+@t{LIST_TYPES} option, for the current pattern (overrides @t{M})
+
+@item @t{N}
+sets the @t{NULL_GLOB} option for the current pattern
+@pindex NULL_GLOB, setting in pattern
+
+@item @t{D}
+sets the @t{GLOB_DOTS} option for the current pattern
+@pindex GLOB_DOTS, setting in pattern
+
+@item @t{n}
+sets the @t{NUMERIC_GLOB_SORT} option for the current pattern
+@pindex NUMERIC_GLOB_SORT, setting in pattern
+
+@item @t{o}@var{c}
+specifies how the names of the files should be sorted. If @var{c} is
+@t{n} they are sorted by name (the default); if it is @t{L} they
+are sorted depending on the size (length) of the files; if @t{l} 
+they are sorted by the number of links; if @t{a}, @t{m}, or @t{c}
+they are sorted by the time of the last access, modification, or
+inode change respectively; if @t{d}, files in subdirectories appear before
+those in the current directory at each level of the search --- this is best
+combined with other criteria, for example `@t{odon}' to sort on names for
+files within the same directory.  Note that @t{a}, @t{m}, and @t{c} compare
+the age against the current time, hence the first name in the list is the
+youngest file. Also note that the modifiers @t{^} and @t{-} are used,
+so `@t{*(^-oL)}' gives a list of all files sorted by file size in descending
+order, following any symbolic links.
+
+@item @t{O}@var{c}
+like `@t{o}', but sorts in descending order; i.e. `@t{*(^oc)}' is the
+same as `@t{*(Oc)}' and `@t{*(^Oc)}' is the same as `@t{*(oc)}'; `@t{Od}'
+puts files in the current directory before those in subdirectories at each
+level of the search.
+
+@item @t{[}@var{beg}[@t{,}@var{end}]@t{]}
+specifies which of the matched filenames should be included in the
+returned list. The syntax is the same as for array
+subscripts. @var{beg} and the optional @var{end} may be mathematical
+expressions. As in parameter subscripting they may be negative to make 
+them count from the last match backward. E.g.: `@t{*(-OL[1,3])}'
+gives a list of the names of the three largest files.
+
+@end table
+
+@noindent
+More than one of these lists can be combined, separated by commas. The
+whole list matches if at least one of the sublists matches (they are
+`or'ed, the qualifiers in the sublists are `and'ed).  Some qualifiers,
+however, affect all matches generated, independent of the sublist in
+which they are given.  These are the qualifiers `@t{M}', `@t{T}',
+`@t{N}', `@t{D}', `@t{n}', `@t{o}', `@t{O}' and the subscripts given
+in brackets (`@t{[...]}').
+
+@noindent
+If a `@t{:}' appears in a qualifier list, the remainder of the expression in
+parenthesis is interpreted as a modifier (see @ref{Modifiers}
+in @ref{History Expansion}).  Note that
+each modifier must be introduced by a separate `@t{:}'.  Note also that the
+result after modification does not have to be an existing file.  The
+name of any existing file can be followed by a modifier of the form
+`@t{(:..)}' even if no actual filename generation is performed.
+Thus:
+
+@noindent
+@example
+ls *(-/)
+@end example
+
+@noindent
+lists all directories and symbolic links that point to directories,
+and
+
+@noindent
+@example
+ls *(%W)
+@end example
+
+@noindent
+lists all world-writable device files in the current directory, and
+
+@noindent
+@example
+ls *(W,X)
+@end example
+
+@noindent
+lists all files in the current directory that are
+world-writable or world-executable, and
+
+@noindent
+@example
+echo /tmp/foo*(u0^@@:t)
+@end example
+
+@noindent
+outputs the basename of all root-owned files beginning with the string
+`@t{foo}' in @t{/tmp}, ignoring symlinks, and
+
+@noindent
+@example
+ls *.*~(lex|parse).[ch](^D^l1)
+@end example
+
+@noindent
+lists all files having a link count of one whose names contain a dot
+(but not those starting with a dot, since @t{GLOB_DOTS} is explicitly
+switched off) except for @t{lex.c}, @t{lex.h}, @t{parse.c} and @t{parse.h}.
+
+@noindent
+@example
+print b*.pro(#q:s/pro/shmo/)(#q.:s/builtin/shmiltin/)
+@end example
+
+@noindent
+demonstrates how colon modifiers and other qualifiers may be chained
+together.  The ordinary qualifier `@t{.}' is applied first, then the colon
+modifiers in order from left to right.  So if @t{EXTENDED_GLOB} is set and
+the base pattern matches the regular file @t{builtin.pro}, the shell will
+print `@t{shmiltin.shmo}'.
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/params.yo
+@node Parameters, Options, Expansion, Top
+
+@chapter Parameters
+@noindent
+@cindex parameters
+
+@section Description
+@noindent
+A parameter has a name, a value, and a number of attributes.
+A name may be any sequence of alphanumeric
+characters and underscores, or the single characters
+`@t{*}', `@t{@@}', `@t{#}', `@t{?}', `@t{-}', `@t{$}', or `@t{!}'.
+The value may be a @emph{scalar} (a string),
+an integer, an array (indexed numerically), or an @emph{associative}
+array (an unordered set of name-value pairs, indexed by name).  To declare
+the type of a parameter, or to assign a scalar or integer value to a
+parameter, use the @t{typeset} builtin.
+@findex typeset, use of
+
+@noindent
+The value of a scalar or integer parameter may also be assigned by
+writing:
+@cindex assignment
+
+@noindent
+@quotation
+@var{name}@t{=}@var{value}
+@end quotation
+
+@noindent
+If the integer attribute, @t{-i}, is set for @var{name}, the @var{value}
+is subject to arithmetic evaluation.  Furthermore, by replacing `@t{=}'
+with `@t{+=}', a parameter can be added or appended to.  See
+@ref{Array Parameters} for additional forms of assignment.
+
+@noindent
+To refer to the value of a parameter, write `@t{$}@var{name}' or
+`@t{$@{}@var{name}@t{@}}'.  See
+@ref{Parameter Expansion}
+for complete details.
+
+@noindent
+In the parameter lists that follow, the mark `<S>' indicates that the
+parameter is special.
+Special parameters cannot have their type changed or their
+readonly attribute turned off, and if a special parameter is unset, then
+later recreated, the special properties will be retained.  `<Z>' indicates
+that the parameter does not exist when the shell initializes in @t{sh} or
+@t{ksh} emulation mode.
+@menu
+* Array Parameters::
+* Positional Parameters::
+* Local Parameters::
+* Parameters Set By The Shell::
+* Parameters Used By The Shell::
+@end menu
+@node Array Parameters, Positional Parameters, , Parameters
+
+@section Array Parameters
+@noindent
+To assign an array value, write one of:
+@findex set, use of
+@cindex array assignment
+
+@noindent
+@quotation
+@t{set -A} @var{name} @var{value} ...
+@end quotation
+@quotation
+@var{name}@t{=(}@var{value} ...@t{)}
+@end quotation
+
+@noindent
+If no parameter @var{name} exists, an ordinary array parameter is created.
+If the parameter @var{name} exists and is a scalar, it is replaced by a new
+array.  Ordinary array parameters may also be explicitly declared with:
+@findex typeset, use of
+
+@noindent
+@quotation
+@t{typeset -a} @var{name}
+@end quotation
+
+@noindent
+Associative arrays @emph{must} be declared before assignment, by using:
+
+@noindent
+@quotation
+@t{typeset -A} @var{name}
+@end quotation
+
+@noindent
+When @var{name} refers to an associative array, the list in an assignment
+is interpreted as alternating keys and values:
+
+@noindent
+@quotation
+set -A @var{name} @var{key} @var{value} ...
+@end quotation
+@quotation
+@var{name}@t{=(}@var{key} @var{value} ...@t{)}
+@end quotation
+
+@noindent
+Every @var{key} must have a @var{value} in this case.  Note that this
+assigns to the entire array, deleting any elements that do not appear
+in the list.
+
+@noindent
+To create an empty array (including associative arrays), use one of:
+
+@noindent
+@quotation
+@t{set -A} @var{name}
+@end quotation
+@quotation
+@var{name}@t{=()}
+@end quotation
+
+@noindent
+
+@subsection Array Subscripts
+@noindent
+@cindex subscripts
+
+@noindent
+Individual elements of an array may be selected using a subscript.  A
+subscript of the form `@t{[}@var{exp}@t{]}' selects the single element
+@var{exp}, where @var{exp} is an arithmetic expression which will be subject
+to arithmetic expansion as if it were surrounded by
+`@t{$((}...@t{))}'.  The elements are numbered
+beginning with 1, unless the @t{KSH_ARRAYS} option is set in which case
+they are numbered from zero.
+@pindex KSH_ARRAYS, use of
+
+@noindent
+Subscripts may be used inside braces used to delimit a parameter name, thus
+`@t{$@{foo[2]@}}' is equivalent to `@t{$foo[2]}'.  If the @t{KSH_ARRAYS}
+option is set, the braced form is the only one that works, as bracketed
+expressions otherwise are not treated as subscripts.
+
+@noindent
+The same subscripting syntax is used for associative arrays, except that
+no arithmetic expansion is applied to @var{exp}.  However, the parsing
+rules for arithmetic expressions still apply, which affects the way that
+certain special characters must be protected from interpretation.  See
+@emph{Subscript Parsing} below for details.
+
+@noindent
+A subscript of the form `@t{[*]}' or `@t{[@@]}' evaluates to all elements
+of an array; there is no difference between the two except when they
+appear within double quotes.
+`@t{"$foo[*]"}' evaluates to `@t{"$foo[1] $foo[2] }...@t{"}', whereas
+`@t{"$foo[@@]"}' evaluates to `@t{"$foo[1]" "$foo[2]" }...'.  For
+associative arrays, `@t{[*]}' or `@t{[@@]}' evaluate to all the values,
+in no particular order.  Note that this does not substitute
+the keys; see the documentation for the `@t{k}' flag under
+@ref{Parameter Expansion}
+for complete details.
+When an array parameter is referenced as `@t{$}@var{name}' (with no
+subscript) it evaluates to `@t{$}@var{name}@t{[*]}', unless the @t{KSH_ARRAYS}
+option is set in which case it evaluates to `@t{$@{}@var{name}@t{[0]@}}' (for
+an associative array, this means the value of the key `@t{0}', which may
+not exist even if there are values for other keys).
+
+@noindent
+A subscript of the form `@t{[}@var{exp1}@t{,}@var{exp2}@t{]}'
+selects all elements in the range @var{exp1} to @var{exp2},
+inclusive. (Associative arrays are unordered, and so do not support
+ranges.) If one of the subscripts evaluates to a negative number,
+say @t{-}@var{n}, then the @var{n}th element from the end
+of the array is used.  Thus `@t{$foo[-3]}' is the third element
+from the end of the array @t{foo}, and
+`@t{$foo[1,-1]}' is the same as `@t{$foo[*]}'.
+
+@noindent
+Subscripting may also be performed on non-array values, in which
+case the subscripts specify a substring to be extracted.
+For example, if @t{FOO} is set to `@t{foobar}', then
+`@t{echo $FOO[2,5]}' prints `@t{ooba}'.
+
+@noindent
+
+@subsection Array Element Assignment
+@noindent
+
+@noindent
+A subscript may be used on the left side of an assignment like so:
+
+@noindent
+@quotation
+@var{name}@t{[}@var{exp}@t{]=}@var{value}
+@end quotation
+
+@noindent
+In this form of assignment the element or range specified by @var{exp}
+is replaced by the expression on the right side.  An array (but not an
+associative array) may be created by assignment to a range or element.
+Arrays do not nest, so assigning a parenthesized list of values to an
+element or range changes the number of elements in the array, shifting the
+other elements to accommodate the new values.  (This is not supported for
+associative arrays.)
+
+@noindent
+This syntax also works as an argument to the @t{typeset} command:
+
+@noindent
+@quotation
+@t{typeset} @t{"}@var{name}@t{[}@var{exp}@t{]"=}@var{value}
+@end quotation
+
+@noindent
+The @var{value} may @emph{not} be a parenthesized list in this case; only
+single-element assignments may be made with @t{typeset}.  Note that quotes
+are necessary in this case to prevent the brackets from being interpreted
+as filename generation operators.  The @t{noglob} precommand modifier
+could be used instead.
+
+@noindent
+To delete an element of an ordinary array, assign `@t{()}' to
+that element.  To delete an element of an associative array, use the
+@t{unset} command:
+
+@noindent
+@quotation
+@t{unset} @t{"}@var{name}@t{[}@var{exp}@t{]"}
+@end quotation
+
+@noindent
+
+@subsection Subscript Flags
+@noindent
+@cindex subscript flags
+
+@noindent
+If the opening bracket, or the comma in a range, in any subscript
+expression is directly followed by an opening parenthesis, the string up
+to the matching closing one is considered to be a list of flags, as in
+`@var{name}@t{[(}@var{flags}@t{)}@var{exp}@t{]}'.  The flags
+currently understood are:
+
+@noindent
+@table @asis
+@item @t{w}
+If the parameter subscripted is a scalar than this flag makes
+subscripting work on words instead of characters.  The default word
+separator is whitespace.
+
+@item @t{s:}@var{string}@t{:}
+This gives the @var{string} that separates words (for use with the
+@t{w} flag).
+
+@item @t{p}
+Recognize the same escape sequences as the @t{print} builtin in
+the string argument of a subsequent `@t{s}' flag.
+
+@item @t{f}
+If the parameter subscripted is a scalar than this flag makes
+subscripting work on lines instead of characters, i.e. with elements
+separated by newlines.  This is a shorthand for `@t{pws:\n:}'.
+
+@item @t{r}
+Reverse subscripting: if this flag is given, the @var{exp} is taken as a
+pattern and the result is the first matching array element, substring or
+word (if the parameter is an array, if it is a scalar, or if it is a
+scalar and the `@t{w}' flag is given, respectively).  The subscript used
+is the number of the matching element, so that pairs of subscripts such as
+`@t{$foo[(r)}@var{??}@t{,3]}' and `@t{$foo[(r)}@var{??}@t{,(r)f*]}' are
+possible if the parameter is not an associative array.  If the
+parameter is an associative array, only the value part of each pair is
+compared to the pattern, and the result is that value.
+
+@item @t{R}
+Like `@t{r}', but gives the last match.  For associative arrays, gives
+all possible matches. May be used for assigning to ordinary array
+elements, but not for assigning to associative arrays.
+
+@item @t{i}
+Like `@t{r}', but gives the index of the match instead; this may not be
+combined with a second argument.  On the left side of an assignment,
+behaves like `@t{r}'.  For associative arrays, the key part of each pair
+is compared to the pattern, and the first matching key found is the
+result.
+
+@item @t{I}
+Like `@t{i}', but gives the index of the last match, or all possible
+matching keys in an associative array.
+
+@item @t{k}
+If used in a subscript on an associative array, this flag causes the keys
+to be interpreted as patterns, and returns the value for the first key
+found where @var{exp} is matched by the key.  This flag does not work on
+the left side of an assignment to an associative array element.  If used
+on another type of parameter, this behaves like `@t{r}'.
+
+@item @t{K}
+On an associative array this is like `@t{k}' but returns all values where
+@var{exp} is matched by the keys.  On other types of parameters this has
+the same effect as `@t{R}'.
+
+@item @t{n:}@var{expr}@t{:}
+If combined with `@t{r}', `@t{R}', `@t{i}' or `@t{I}', makes them give
+the @var{n}th or @var{n}th last match (if @var{expr} evaluates to
+@var{n}).  This flag is ignored when the array is associative.
+
+@item @t{b:}@var{expr}@t{:}
+If combined with `@t{r}', `@t{R}', `@t{i}' or `@t{I}', makes them begin
+at the @var{n}th or @var{n}th last element, word, or character (if @var{expr}
+evaluates to @var{n}).  This flag is ignored when the array is associative.
+
+@item @t{e}
+This flag has no effect and for ordinary arrays is retained for backward
+compatibility only.  For associative arrays, this flag can be used to
+force @t{*} or @t{@@} to be interpreted as a single key rather than as a
+reference to all values.  This flag may be used on the left side of an
+assignment.
+
+@end table
+
+@noindent
+See @emph{Parameter Expansion Flags} (@ref{Parameter Expansion}) for additional ways to manipulate the results of array subscripting.
+
+@noindent
+
+@subsection Subscript Parsing
+@noindent
+
+@noindent
+This discussion applies mainly to associative array key strings and to
+patterns used for reverse subscripting (the `@t{r}', `@t{R}', `@t{i}',
+etc. flags), but it may also affect parameter substitutions that appear
+as part of an arithmetic expression in an ordinary subscript.
+
+@noindent
+It is possible to avoid the use of subscripts in assignments to associative
+array elements by using the syntax:
+
+@noindent
+@example
+
+@noindent
+aa+=('key with "*strange*" characters' 'value string')
+
+@end example
+
+@noindent
+This adds a new key/value pair if the key is not already present, and
+replaces the value for the existing key if it is.
+
+@noindent
+The basic rule to remember when writing a subscript expression is that all
+text between the opening `@t{[}' and the closing `@t{]}' is interpreted
+@emph{as if} it were in double quotes (@ref{Quoting}).  However, unlike double quotes which normally cannot nest, subscript
+expressions may appear inside double-quoted strings or inside other
+subscript expressions (or both!), so the rules have two important
+differences.
+
+@noindent
+The first difference is that brackets (`@t{[}' and `@t{]}') must appear as
+balanced pairs in a subscript expression unless they are preceded by a
+backslash (`@t{\}').  Therefore, within a subscript expression (and unlike
+true double-quoting) the sequence `@t{\[}' becomes `@t{[}', and similarly
+`@t{\]}' becomes `@t{]}'.  This applies even in cases where a backslash is
+not normally required; for example, the pattern `@t{[^[]}' (to match any
+character other than an open bracket) should be written `@t{[^\[]}' in a
+reverse-subscript pattern.  However, note that `@t{\[^\[\]}' and even
+`@t{\[^[]}' mean the @emph{same} thing, because backslashes are always
+stripped when they appear before brackets!
+
+@noindent
+The same rule applies to parentheses (`@t{(}' and `@t{)}') and
+braces (`@t{@{}' and `@t{@}}'): they must appear either in balanced pairs or
+preceded by a backslash, and backslashes that protect parentheses or
+braces are removed during parsing.  This is because parameter expansions
+may be surrounded balanced braces, and subscript flags are introduced by
+balanced parenthesis.
+
+@noindent
+The second difference is that a double-quote (`@t{"}') may appear as part
+of a subscript expression without being preceded by a backslash, and
+therefore that the two characters `@t{\"}' remain as two characters in the
+subscript (in true double-quoting, `@t{\"}' becomes `@t{"}').  However,
+because of the standard shell quoting rules, any double-quotes that appear
+must occur in balanced pairs unless preceded by a backslash.  This makes
+it more difficult to write a subscript expression that contains an odd
+number of double-quote characters, but the reason for this difference is
+so that when a subscript expression appears inside true double-quotes, one
+can still write `@t{\"}' (rather than `@t{\\\"}') for `@t{"}'.
+
+@noindent
+To use an odd number of double quotes as a key in an assignment, use the
+@t{typeset} builtin and an enclosing pair of double quotes; to refer to
+the value of that key, again use double quotes:
+
+@noindent
+@example
+typeset -A aa
+typeset "aa[one\"two\"three\"quotes]"=QQQ
+print "$aa[one\"two\"three\"quotes]"
+@end example
+
+@noindent
+It is important to note that the quoting rules do not change when a
+parameter expansion with a subscript is nested inside another subscript
+expression.  That is, it is not necessary to use additional backslashes
+within the inner subscript expression; they are removed only once, from
+the innermost subscript outwards.  Parameters are also expanded from the
+innermost subscript first, as each expansion is encountered left to right
+in the outer expression.
+
+@noindent
+A further complication arises from a way in which subscript parsing is
+@emph{not} different from double quote parsing.  As in true double-quoting,
+the sequences `@t{\*}', and `@t{\@@}' remain as two characters when they
+appear in a subscript expression.  To use a literal `@t{*}' or `@t{@@}' as
+an associative array key, the `@t{e}' flag must be used:
+
+@noindent
+@example
+typeset -A aa
+aa[(e)*]=star
+print $aa[(e)*]
+@end example
+
+@noindent
+A last detail must be considered when reverse subscripting is performed.
+Parameters appearing in the subscript expression are first expanded and
+then the complete expression is interpreted as a pattern.  This has two
+effects: first, parameters behave as if @t{GLOB_SUBST} were on (and it
+cannot be turned off); second, backslashes are interpreted twice, once
+when parsing the array subscript and again when parsing the pattern.  In a
+reverse subscript, it's necessary to use @emph{four} backslashes to cause a
+single backslash to match literally in the pattern.  For complex patterns,
+it is often easiest to assign the desired pattern to a parameter and then
+refer to that parameter in the subscript, because then the backslashes,
+brackets, parentheses, etc., are seen only when the complete expression is
+converted to a pattern.  To match the value of a parameter literally in a
+reverse subscript, rather than as a pattern,
+use `@t{$@{(q}@t{)}@var{name}@t{@}}' (@ref{Parameter Expansion}) to quote the expanded value.
+
+@noindent
+Note that the `@t{k}' and `@t{K}' flags are reverse subscripting for an
+ordinary array, but are @emph{not} reverse subscripting for an associative
+array!  (For an associative array, the keys in the array itself are
+interpreted as patterns by those flags; the subscript is a plain string
+in that case.)
+
+@noindent
+One final note, not directly related to subscripting: the numeric names
+of positional parameters (@ref{Positional Parameters}) are parsed specially, so for example `@t{$2foo}' is equivalent to
+`@t{$@{2@}foo}'.  Therefore, to use subscript syntax to extract a substring
+from a positional parameter, the expansion must be surrounded by braces;
+for example, `@t{$@{2[3,5]@}}' evaluates to the third through fifth
+characters of the second positional parameter, but `@t{$2[3,5]}' is the
+entire second parameter concatenated with the filename generation pattern
+`@t{[3,5]}'.
+
+@noindent
+@node Positional Parameters, Local Parameters, Array Parameters, Parameters
+
+@section Positional Parameters
+@noindent
+The positional parameters provide access to the command-line arguments
+of a shell function, shell script, or the shell itself; see
+@ref{Invocation}, and also @ref{Functions}.
+The parameter @var{n}, where @var{n} is a number,
+is the @var{n}th positional parameter.
+The parameters @t{*}, @t{@@} and @t{argv} are
+arrays containing all the positional parameters;
+thus `@t{$argv[}@var{n}@t{]}', etc., is equivalent to simply `@t{$}@var{n}'.
+
+@noindent
+Positional parameters may be changed after the shell or function starts by
+using the @t{set} builtin, by assigning to the @t{argv} array, or by direct
+assignment of the form `@var{n}@t{=}@var{value}' where @var{n} is the number of
+the positional parameter to be changed.  This also creates (with empty
+values) any of the positions from 1 to @var{n} that do not already have
+values.  Note that, because the positional parameters form an array, an
+array assignment of the form `@var{n}@t{=(}@var{value} ...@t{)}' is
+allowed, and has the effect of shifting all the values at positions greater
+than @var{n} by as many positions as necessary to accommodate the new values.
+
+@noindent
+@node Local Parameters, Parameters Set By The Shell, Positional Parameters, Parameters
+
+@section Local Parameters
+@noindent
+Shell function executions delimit scopes for shell parameters.
+(Parameters are dynamically scoped.)  The @t{typeset} builtin, and its
+alternative forms @t{declare}, @t{integer}, @t{local} and @t{readonly}
+(but not @t{export}), can be used to declare a parameter as being local
+to the innermost scope.
+
+@noindent
+When a parameter is read or assigned to, the
+innermost existing parameter of that name is used.  (That is, the
+local parameter hides any less-local parameter.)  However, assigning
+to a non-existent parameter, or declaring a new parameter with @t{export},
+causes it to be created in the @emph{outer}most scope.
+
+@noindent
+Local parameters disappear when their scope ends.
+@t{unset} can be used to delete a parameter while it is still in scope;
+any outer parameter of the same name remains hidden.
+
+@noindent
+Special parameters may also be made local; they retain their special
+attributes unless either the existing or the newly-created parameter
+has the @t{-h} (hide) attribute.  This may have unexpected effects:
+there is no default value, so if there is no assignment at the
+point the variable is made local, it will be set to an empty value (or zero
+in the case of integers).  
+The following:
+
+@noindent
+@example
+typeset PATH=/new/directory:$PATH
+@end example
+
+@noindent
+is valid for temporarily allowing the shell or programmes called from it to
+find the programs in @t{/new/directory} inside a function.
+
+@noindent
+Note that the restriction in older versions of zsh that local parameters
+were never exported has been removed.
+
+@noindent
+@node Parameters Set By The Shell, Parameters Used By The Shell, Local Parameters, Parameters
+
+@section Parameters Set By The Shell
+@noindent
+The following parameters are automatically set by the shell:
+
+@noindent
+@table @asis
+@vindex !
+@item @t{!} <S>
+The process ID of the last background command invoked.
+
+@vindex #
+@item @t{#} <S>
+The number of positional parameters in decimal.  Note that some confusion
+may occur with the syntax @t{$#}@var{param} which substitutes the length of
+@var{param}.  Use @t{$@{#@}} to resolve ambiguities.  In particular, the
+sequence `@t{$#-}@var{...}' in an arithmetic expression is interpreted as
+the length of the parameter @t{-}, q.v.
+
+@vindex ARGC
+@item @t{ARGC} <S> <Z>
+Same as @t{#}.
+
+@vindex $
+@item @t{$} <S>
+The process ID of this shell.
+
+@vindex -
+@item @t{-} <S>
+Flags supplied to the shell on invocation or by the @t{set}
+or @t{setopt} commands.
+
+@vindex *
+@item @t{*} <S>
+An array containing the positional parameters.
+
+@vindex argv
+@item @t{argv} <S> <Z>
+Same as @t{*}.  Assigning to @t{argv} changes the local positional
+parameters, but @t{argv} is @emph{not} itself a local parameter.
+Deleting @t{argv} with @t{unset} in any function deletes it everywhere,
+although only the innermost positional parameter array is deleted (so
+@t{*} and @t{@@} in other scopes are not affected).
+
+@vindex @@
+@item @t{@@} <S>
+Same as @t{argv[@@]}, even when @t{argv} is not set.
+
+@vindex ?
+@item @t{?} <S>
+The exit value returned by the last command.
+
+@vindex 0
+@item @t{0} <S>
+The name used to invoke the current shell.  If the @t{FUNCTION_ARGZERO} option
+is set, this is set temporarily within a shell function to the name of the
+function, and within a sourced script to the name of the script.
+
+@vindex status
+@item @t{status} <S> <Z>
+Same as @t{?}.
+
+@vindex pipestatus
+@item @t{pipestatus} <S> <Z>
+An array containing the exit values returned by all commands in the
+last pipeline.
+
+@vindex _
+@item @t{_} <S>
+The last argument of the previous command.
+Also, this parameter is set in the environment of every command
+executed to the full pathname of the command.
+
+@vindex CPUTYPE
+@item @t{CPUTYPE}
+The machine type (microprocessor class or machine model),
+as determined at run time.
+
+@vindex EGID
+@item @t{EGID} <S>
+The effective group ID of the shell process.  If you have sufficient
+privileges, you may change the effective group ID of the shell
+process by assigning to this parameter.  Also (assuming sufficient
+privileges), you may start a single command with a different
+effective group ID by `@t{(EGID=}@var{gid}@t{; command)}'
+
+@vindex EUID
+@item @t{EUID} <S>
+The effective user ID of the shell process.  If you have sufficient
+privileges, you may change the effective user ID of the shell process
+by assigning to this parameter.  Also (assuming sufficient privileges),
+you may start a single command with a different
+effective user ID by `@t{(EUID=}@var{uid}@t{; command)}'
+
+@vindex ERRNO
+@item @t{ERRNO} <S>
+The value of errno (see man page errno(3))
+as set by the most recently failed system call.
+This value is system dependent and is intended for debugging
+purposes.  It is also useful with the @t{zsh/system} module which
+allows the number to be turned into a name or message.
+
+@vindex GID
+@item @t{GID} <S>
+The real group ID of the shell process.  If you have sufficient privileges,
+you may change the group ID of the shell process by assigning to this
+parameter.  Also (assuming sufficient privileges), you may start a single
+command under a different
+group ID by `@t{(GID=}@var{gid}@t{; command)}'
+
+@vindex HISTCMD
+@item @t{HISTCMD}
+The current history line number in an interactive shell, in other
+words the line number for the command that caused @t{$HISTCMD}
+to be read.
+
+@vindex HOST
+@item @t{HOST}
+The current hostname.
+
+@vindex LINENO
+@item @t{LINENO} <S>
+The line number of the current line within the current script, sourced
+file, or shell function being executed, whichever was started most
+recently.  Note that in the case of shell functions the line
+number refers to the function as it appeared in the original definition,
+not necessarily as displayed by the @t{functions} builtin.
+
+@vindex LOGNAME
+@item @t{LOGNAME}
+If the corresponding variable is not set in the environment of the
+shell, it is initialized to the login name corresponding to the
+current login session. This parameter is exported by default but
+this can be disabled using the @t{typeset} builtin.
+
+@vindex MACHTYPE
+@item @t{MACHTYPE}
+The machine type (microprocessor class or machine model),
+as determined at compile time.
+
+@vindex OLDPWD
+@item @t{OLDPWD}
+The previous working directory.  This is set when the shell initializes
+and whenever the directory changes.
+
+@vindex OPTARG
+@item @t{OPTARG} <S>
+The value of the last option argument processed by the @t{getopts}
+command.
+
+@vindex OPTIND
+@item @t{OPTIND} <S>
+The index of the last option argument processed by the @t{getopts}
+command.
+
+@vindex OSTYPE
+@item @t{OSTYPE}
+The operating system, as determined at compile time.
+
+@vindex PPID
+@item @t{PPID} <S>
+The process ID of the parent of the shell.
+
+@vindex PWD
+@item @t{PWD}
+The present working directory.  This is set when the shell initializes
+and whenever the directory changes.
+
+@vindex RANDOM
+@item @t{RANDOM} <S>
+A pseudo-random integer from 0 to 32767, newly generated each time
+this parameter is referenced.  The random number generator
+can be seeded by assigning a numeric value to @t{RANDOM}.
+
+@noindent
+The values of @t{RANDOM} form an intentionally-repeatable pseudo-random
+sequence; subshells that reference @t{RANDOM} will result
+in identical pseudo-random values unless the value of @t{RANDOM} is
+referenced or seeded in the parent shell in between subshell invocations.
+
+@vindex SECONDS
+@item @t{SECONDS} <S>
+The number of seconds since shell invocation.  If this parameter
+is assigned a value, then the value returned upon reference
+will be the value that was assigned plus the number of seconds
+since the assignment.
+
+@noindent
+Unlike other special parameters, the type of the @t{SECONDS} parameter can
+be changed using the @t{typeset} command.  Only integer and one of the
+floating point types are allowed.  For example, `@t{typeset -F SECONDS}'
+causes the value to be reported as a floating point number.  The precision
+is six decimal places, although not all places may be useful.
+
+@vindex SHLVL
+@item @t{SHLVL} <S>
+Incremented by one each time a new shell is started.
+
+@vindex signals
+@item @t{signals}
+An array containing the names of the signals.
+
+@vindex TRY_BLOCK_ERROR
+@item @t{TRY_BLOCK_ERROR} <S>
+In an @t{always} block, indicates whether the preceding list of code
+caused an error.  The value is 1 to indicate an error, 0 otherwise.
+It may be reset, clearing the error condition.  See
+@ref{Complex Commands}
+
+@vindex TTY
+@item @t{TTY}
+The name of the tty associated with the shell, if any.
+
+@vindex TTYIDLE
+@item @t{TTYIDLE} <S>
+The idle time of the tty associated with the shell in seconds or -1 if there
+is no such tty.
+
+@vindex UID
+@item @t{UID} <S>
+The real user ID of the shell process.  If you have sufficient privileges,
+you may change the user ID of the shell by assigning to this parameter.
+Also (assuming sufficient privileges), you may start a single command
+under a different
+user ID by `@t{(UID=}@var{uid}@t{; command)}'
+
+@vindex USERNAME
+@item @t{USERNAME} <S>
+The username corresponding to the real user ID of the shell process.  If you
+have sufficient privileges, you may change the username (and also the
+user ID and group ID) of the shell by assigning to this parameter.
+Also (assuming sufficient privileges), you may start a single command
+under a different username (and user ID and group ID)
+by `@t{(USERNAME=}@var{username}@t{; command)}'
+
+@vindex VENDOR
+@item @t{VENDOR}
+The vendor, as determined at compile time.
+
+@vindex ZSH_NAME
+@item @t{ZSH_NAME}
+Expands to the basename of the command used to invoke this instance
+of zsh.
+
+@vindex ZSH_VERSION
+@item @t{ZSH_VERSION}
+The version number of this zsh.
+
+@end table
+@node Parameters Used By The Shell, , Parameters Set By The Shell, Parameters
+
+@section Parameters Used By The Shell
+@noindent
+The following parameters are used by the shell.
+
+@noindent
+In cases where there are two parameters with an upper- and lowercase
+form of the same name, such as @t{path} and @t{PATH}, the lowercase form
+is an array and the uppercase form is a scalar with the elements of the
+array joined together by colons.  These are similar to tied parameters
+created via `@t{typeset -T}'.  The normal use for the colon-separated
+form is for exporting to the environment, while the array form is easier
+to manipulate within the shell.  Note that unsetting either of the pair
+will unset the other; they retain their special properties when
+recreated, and recreating one of the pair will recreate the other.
+
+@noindent
+@table @asis
+@vindex ARGV0
+@item @t{ARGV0}
+If exported, its value is used as the @t{argv[0]} of external commands.
+Usually used in constructs like `@t{ARGV0=emacs nethack}'.
+
+@vindex BAUD
+@item @t{BAUD}
+The baud rate of the current connection.  Used by the line editor
+update mechanism to compensate for a slow terminal by delaying
+updates until necessary.  This may be profitably set to a lower value
+in some circumstances, e.g.
+for slow modems dialing into a communications server which is connected
+to a host via a fast link; in this case, this variable
+would be set by default to the speed of the fast link, and not
+the modem.
+This parameter should be set to the baud
+rate of the slowest part of the link for best performance. The compensation
+mechanism can be turned off by setting the variable to zero.
+
+@vindex cdpath
+@vindex CDPATH
+@item @t{cdpath} <S> <Z> (@t{CDPATH} <S>)
+An array (colon-separated list)
+of directories specifying the search path for the @t{cd} command.
+
+@vindex COLUMNS
+@item @t{COLUMNS} <S>
+The number of columns for this terminal session.
+Used for printing select lists and for the line editor.
+
+@vindex DIRSTACKSIZE
+@item @t{DIRSTACKSIZE}
+The maximum size of the directory stack.  If the
+stack gets larger than this, it will be truncated automatically.
+This is useful with the @t{AUTO_PUSHD} option.
+@pindex AUTO_PUSHD, use of
+
+@vindex ENV
+@item @t{ENV}
+If the @t{ENV} environment variable is set when zsh is invoked as @t{sh}
+or @t{ksh}, @t{$ENV} is sourced after the profile scripts.  The value of
+@t{ENV} is subjected to parameter expansion, command substitution, and
+arithmetic expansion before being interpreted as a pathname.  Note that
+@t{ENV} is @emph{not} used unless zsh is emulating @cite{sh} or @cite{ksh}.
+
+@vindex FCEDIT
+@item @t{FCEDIT}
+The default editor for the @t{fc} builtin.
+
+@vindex fignore
+@vindex FIGNORE
+@item @t{fignore} <S> <Z> (@t{FIGNORE} <S>)
+An array (colon separated list)
+containing the suffixes of files to be ignored
+during filename completion.  However, if completion only generates files
+with suffixes in this list, then these files are completed anyway.
+
+@vindex fpath
+@vindex FPATH
+@item @t{fpath} <S> <Z> (@t{FPATH} <S>)
+An array (colon separated list)
+of directories specifying the search path for
+function definitions.  This path is searched when a function
+with the @t{-u} attribute is referenced.  If an executable
+file is found, then it is read and executed in the current environment.
+
+@vindex histchars
+@item @t{histchars} <S>
+Three characters used by the shell's history and lexical analysis
+mechanism.  The first character signals the start of a history
+expansion (default `@t{!}').  The second character signals the
+start of a quick history substitution (default `@t{^}').  The third
+character is the comment character (default `@t{#}').
+
+@vindex HISTCHARS
+@item @t{HISTCHARS} <S> <Z>
+Same as @t{histchars}.  (Deprecated.)
+
+@vindex HISTFILE
+@item @t{HISTFILE}
+The file to save the history in when an interactive shell exits.
+If unset, the history is not saved.
+
+@vindex HISTSIZE
+@item @t{HISTSIZE} <S>
+The maximum number of events stored in the internal history list.
+If you use the @t{HIST_EXPIRE_DUPS_FIRST} option, setting this value
+larger than the @t{SAVEHIST} size will give you the difference as a
+cushion for saving duplicated history events.
+
+@vindex HOME
+@item @t{HOME} <S>
+The default argument for the @t{cd} command.
+
+@vindex IFS
+@item @t{IFS} <S>
+Internal field separators (by default space, tab, newline and NUL), that
+are used to separate words which result from
+command or parameter expansion and words read by
+the @t{read} builtin.  Any characters from the set space, tab and
+newline that appear in the IFS are called @emph{IFS white space}.
+One or more IFS white space characters or one non-IFS white space
+character together with any adjacent IFS white space character delimit
+a field.  If an IFS white space character appears twice consecutively
+in the IFS, this character is treated as if it were not an IFS white
+space character.
+
+@vindex KEYTIMEOUT
+@item @t{KEYTIMEOUT}
+The time the shell waits, in hundredths of seconds, for another key to
+be pressed when reading bound multi-character sequences.
+
+@vindex LANG
+@item @t{LANG} <S>
+This variable determines the locale category for any category not
+specifically selected via a variable starting with `@t{LC_}'.
+
+@vindex LC_ALL
+@item @t{LC_ALL} <S>
+This variable overrides the value of the `@t{LANG}' variable and the value
+of any of the other variables starting with `@t{LC_}'.
+
+@vindex LC_COLLATE
+@item @t{LC_COLLATE} <S>
+This variable determines the locale category for character collation
+information within ranges in glob brackets and for sorting.
+
+@vindex LC_CTYPE
+@item @t{LC_CTYPE} <S>
+This variable determines the locale category for character handling
+functions.
+
+@vindex LC_MESSAGES
+@item @t{LC_MESSAGES} <S>
+This variable determines the language in which messages should be
+written.  Note that zsh does not use message catalogs.
+
+@vindex LC_NUMERIC
+@item @t{LC_NUMERIC} <S>
+This variable affects the decimal point character and thousands
+separator character for the formatted input/output functions
+and string conversion functions.  Note that zsh ignores this
+setting when parsing floating point mathematical expressions.
+
+@vindex LC_TIME
+@item @t{LC_TIME} <S>
+This variable determines the locale category for date and time
+formatting in prompt escape sequences.
+
+@vindex LINES
+@item @t{LINES} <S>
+The number of lines for this terminal session.
+Used for printing select lists and for the line editor.
+
+@vindex LISTMAX
+@item @t{LISTMAX}
+In the line editor, the number of matches to list without asking
+first. If the value is negative, the list will be shown if it spans at 
+most as many lines as given by the absolute value.
+If set to zero, the shell asks only if the top of the listing would scroll
+off the screen.
+
+@vindex LOGCHECK
+@item @t{LOGCHECK}
+The interval in seconds between checks for login/logout activity
+using the @t{watch} parameter.
+
+@vindex MAIL
+@item @t{MAIL}
+If this parameter is set and @t{mailpath} is not set,
+the shell looks for mail in the specified file.
+
+@vindex MAILCHECK
+@item @t{MAILCHECK}
+The interval in seconds between checks for new mail.
+
+@vindex mailpath
+@vindex MAILPATH
+@item @t{mailpath} <S> <Z> (@t{MAILPATH} <S>)
+An array (colon-separated list) of filenames to check for
+new mail.  Each filename can be followed by a `@t{?}' and a
+message that will be printed.  The message will undergo
+parameter expansion, command substitution and arithmetic
+expansion with the variable @t{$_} defined as the name
+of the file that has changed.  The default message is
+`@t{You have new mail}'.  If an element is a directory
+instead of a file the shell will recursively check every
+file in every subdirectory of the element.
+
+@vindex manpath
+@vindex MANPATH
+@item @t{manpath} <S> <Z> (@t{MANPATH} <S> <Z>)
+An array (colon-separated list)
+whose value is not used by the shell.  The @t{manpath}
+array can be useful, however, since setting it also sets
+@t{MANPATH}, and vice versa.
+
+@vindex module_path
+@vindex MODULE_PATH
+@item @t{module_path} <S> <Z> (@t{MODULE_PATH} <S>)
+An array (colon-separated list)
+of directories that @t{zmodload}
+searches for dynamically loadable modules.
+This is initialized to a standard pathname,
+usually `@t{/usr/local/lib/zsh/$ZSH_VERSION}'.
+(The `@t{/usr/local/lib}' part varies from installation to installation.)
+For security reasons, any value set in the environment when the shell
+is started will be ignored.
+
+@noindent
+These parameters only exist if the installation supports dynamic
+module loading.
+
+@vindex NULLCMD
+@cindex null command style
+@cindex csh, null command style
+@cindex ksh, null command style
+@item @t{NULLCMD} <S>
+The command name to assume if a redirection is specified
+with no command.  Defaults to @t{cat}.  For @cite{sh}/@cite{ksh}
+behavior, change this to @t{:}.  For @cite{csh}-like
+behavior, unset this parameter; the shell will print an
+error message if null commands are entered.
+
+@vindex path
+@vindex PATH
+@item @t{path} <S> <Z> (@t{PATH} <S>)
+An array (colon-separated list)
+of directories to search for commands.
+When this parameter is set, each directory is scanned
+and all files found are put in a hash table.
+
+@vindex POSTEDIT
+@item @t{POSTEDIT} <S>
+This string is output whenever the line editor exits.
+It usually contains termcap strings to reset the terminal.
+
+@vindex PROMPT
+@item @t{PROMPT} <S> <Z>
+@vindex PROMPT2
+@itemx @t{PROMPT2} <S> <Z>
+@vindex PROMPT3
+@itemx @t{PROMPT3} <S> <Z>
+@vindex PROMPT4
+@itemx @t{PROMPT4} <S> <Z>
+Same as @t{PS1}, @t{PS2}, @t{PS3} and @t{PS4},
+respectively.
+
+@vindex prompt
+@item @t{prompt} <S> <Z>
+Same as @t{PS1}.
+
+@vindex PS1
+@item @t{PS1} <S>
+The primary prompt string, printed before a command is read.
+the default is `@t{%m%# }'.  It undergoes a special form of expansion
+before being displayed; see @ref{Prompt Expansion}.
+
+@vindex PS2
+@item @t{PS2} <S>
+The secondary prompt, printed when the shell needs more information
+to complete a command.
+It is expanded in the same way as @t{PS1}.
+The default is `@t{%_> }', which displays any shell constructs or quotation
+marks which are currently being processed.
+
+@vindex PS3
+@item @t{PS3} <S>
+Selection prompt used within a @t{select} loop.
+It is expanded in the same way as @t{PS1}.
+The default is `@t{?# }'.
+
+@vindex PS4
+@item @t{PS4} <S>
+The execution trace prompt.  Default is `@t{+%N:%i> }', which displays
+the name of the current shell structure and the line number within it.
+In sh or ksh emulation, the default is `@t{+ }'.
+
+@vindex psvar
+@vindex PSVAR
+@item @t{psvar} <S> <Z> (@t{PSVAR} <S>)
+An array (colon-separated list) whose first nine values can be used in
+@t{PROMPT} strings.  Setting @t{psvar} also sets @t{PSVAR}, and
+vice versa.
+
+@vindex READNULLCMD
+@item @t{READNULLCMD} <S>
+The command name to assume if a single input redirection
+is specified with no command.  Defaults to @t{more}.
+
+@vindex REPORTTIME
+@item @t{REPORTTIME}
+If nonnegative, commands whose combined user and system execution times
+(measured in seconds) are greater than this value have timing
+statistics printed for them.
+
+@vindex REPLY
+@item @t{REPLY}
+This parameter is reserved by convention to pass string values between
+shell scripts and shell builtins in situations where a function call or
+redirection are impossible or undesirable.  The @t{read} builtin and the
+@t{select} complex command may set @t{REPLY}, and filename generation both
+sets and examines its value when evaluating certain expressions.  Some
+modules also employ @t{REPLY} for similar purposes.
+
+@vindex reply
+@item @t{reply}
+As @t{REPLY}, but for array values rather than strings.
+
+@vindex RPROMPT
+@item @t{RPROMPT} <S>
+@vindex RPS1
+@itemx @t{RPS1} <S>
+This prompt is displayed on the right-hand side of the screen
+when the primary prompt is being displayed on the left.
+This does not work if the @t{SINGLELINEZLE} option is set.
+It is expanded in the same way as @t{PS1}.
+
+@vindex RPROMPT2
+@item @t{RPROMPT2} <S>
+@vindex RPS2
+@itemx @t{RPS2} <S>
+This prompt is displayed on the right-hand side of the screen
+when the secondary prompt is being displayed on the left.
+This does not work if the @t{SINGLELINEZLE} option is set.
+It is expanded in the same way as @t{PS2}.
+
+@vindex SAVEHIST
+@item @t{SAVEHIST}
+The maximum number of history events to save in the history file.
+
+@vindex SPROMPT
+@item @t{SPROMPT} <S>
+The prompt used for spelling correction.  The sequence
+`@t{%R}' expands to the string which presumably needs spelling
+correction, and `@t{%r}' expands to the proposed correction.
+All other prompt escapes are also allowed.
+
+@vindex STTY
+@item @t{STTY}
+If this parameter is set in a command's environment, the shell runs the
+@t{stty} command with the value of this parameter as arguments in order to
+set up the terminal before executing the command. The modes apply only to the
+command, and are reset when it finishes or is suspended. If the command is
+suspended and continued later with the @t{fg} or @t{wait} builtins it will
+see the modes specified by @t{STTY}, as if it were not suspended.  This
+(intentionally) does not apply if the command is continued via `@t{kill
+-CONT}'.  @t{STTY} is ignored if the command is run in the background, or
+if it is in the environment of the shell but not explicitly assigned to in
+the input line. This avoids running stty at every external command by
+accidentally exporting it. Also note that @t{STTY} should not be used for
+window size specifications; these will not be local to the command.
+
+@vindex TERM
+@item @t{TERM} <S>
+The type of terminal in use.  This is used when looking up termcap
+sequences.  An assignment to @t{TERM} causes zsh to re-initialize the
+terminal, even if the value does not change (e.g., `@t{TERM=$TERM}').  It
+is necessary to make such an assignment upon any change to the terminal
+definition database or terminal type in order for the new settings to
+take effect.
+
+@vindex TIMEFMT
+@item @t{TIMEFMT}
+The format of process time reports with the @t{time} keyword.
+The default is `@t{%E real  %U user  %S system  %P %J}'.
+Recognizes the following escape sequences, although not all
+may be available on all systems, and some that are available
+may not be useful:
+
+@noindent
+@table @asis
+@item @t{%%}
+A `@t{%}'.
+@item @t{%U}
+CPU seconds spent in user mode.
+@item @t{%S}
+CPU seconds spent in kernel mode.
+@item @t{%E}
+Elapsed time in seconds.
+@item @t{%P}
+The CPU percentage, computed as
+(100*@t{%U}+@t{%S})/@t{%E}.
+@item @t{%W}
+Number of times the process was swapped.
+@item @t{%X}
+The average amount in (shared) text space used in Kbytes.
+@item @t{%D}
+The average amount in (unshared) data/stack space used in
+Kbytes.
+@item @t{%K}
+The total space used (%X+%D) in Kbytes.
+@item @t{%M}
+The  maximum memory the process had in use at any time in
+Kbytes.
+@item @t{%F}
+The number of major page faults (page needed to be brought
+from disk).
+@item @t{%R}
+The number of minor page faults.
+@item @t{%I}
+The number of input operations.
+@item @t{%O}
+The number of output operations.
+@item @t{%r}
+The number of socket messages received.
+@item @t{%s}
+The number of socket messages sent.
+@item @t{%k}
+The number of signals received.
+@item @t{%w}
+Number of voluntary context switches (waits).
+@item @t{%c}
+Number of involuntary context switches.
+@item @t{%J}
+The name of this job.
+@end table
+
+@noindent
+A star may be inserted between the percent sign and flags printing time.
+This cause the time to be printed in
+`@var{hh}@t{:}@var{mm}@t{:}@var{ss}@t{.}@var{ttt}'
+format (hours and minutes are only printed if they are not zero).
+
+@vindex TMOUT
+@item @t{TMOUT}
+If this parameter is nonzero, the shell will receive an @t{ALRM}
+signal if a command is not entered within the specified number of
+seconds after issuing a prompt. If there is a trap on @t{SIGALRM}, it
+will be executed and a new alarm is scheduled using the value of the
+@t{TMOUT} parameter after executing the trap.  If no trap is set, and
+the idle time of the terminal is not less than the value of the
+@t{TMOUT} parameter, zsh terminates.  Otherwise a new alarm is
+scheduled to @t{TMOUT} seconds after the last keypress.
+
+@vindex TMPPREFIX
+@item @t{TMPPREFIX}
+A pathname prefix which the shell will use for all temporary files.
+Note that this should include an initial part for the file name as
+well as any directory names.  The default is `@t{/tmp/zsh}'.
+
+@vindex watch
+@vindex WATCH
+@item @t{watch} <S> <Z> (@t{WATCH} <S>)
+An array (colon-separated list) of login/logout events to report.
+If it contains the single word `@t{all}', then all login/logout events
+are reported.  If it contains the single word `@t{notme}', then all
+events are reported as with `@t{all}' except @t{$USERNAME}.
+An entry in this list may consist of a username,
+an `@t{@@}' followed by a remote hostname,
+and a `@t{%}' followed by a line (tty).
+Any or all of these components may be present in an entry;
+if a login/logout event matches all of them,
+it is reported.
+
+@vindex WATCHFMT
+@item @t{WATCHFMT}
+The format of login/logout reports if the @t{watch} parameter is set.
+Default is `@t{%n has %a %l from %m}'.
+Recognizes the following escape sequences:
+
+@noindent
+@table @asis
+@item @t{%n}
+The name of the user that logged in/out.
+
+@item @t{%a}
+The observed action, i.e. "logged on" or "logged off".
+
+@item @t{%l}
+The line (tty) the user is logged in on.
+
+@item @t{%M}
+The full hostname of the remote host.
+
+@item @t{%m}
+The hostname up to the first `@t{.}'.  If only the
+IP address is available or the utmp field contains
+the name of an X-windows display, the whole name is printed.
+
+@noindent
+@emph{NOTE:}
+The `@t{%m}' and `@t{%M}' escapes will work only if there is a host name
+field in the utmp on your machine.  Otherwise they are
+treated as ordinary strings.
+
+@item @t{%S} (@t{%s})
+Start (stop) standout mode.
+
+@item @t{%U} (@t{%u})
+Start (stop) underline mode.
+
+@item @t{%B} (@t{%b})
+Start (stop) boldface mode.
+
+@item @t{%t}
+@itemx @t{%@@}
+The time, in 12-hour, am/pm format.
+
+@item @t{%T}
+The time, in 24-hour format.
+
+@item @t{%w}
+The date in `@var{day}@t{-}@var{dd}' format.
+
+@item @t{%W}
+The date in `@var{mm}@t{/}@var{dd}@t{/}@var{yy}' format.
+
+@item @t{%D}
+The date in `@var{yy}@t{-}@var{mm}@t{-}@var{dd}' format.
+
+@item @t{%(}@var{x}@t{:}@var{true-text}@t{:}@var{false-text}@t{)}
+Specifies a ternary expression.
+The character following the @var{x} is
+arbitrary; the same character is used to separate the text
+for the "true" result from that for the "false" result.
+Both the separator and the right parenthesis may be escaped
+with a backslash.
+Ternary expressions may be nested.
+
+@noindent
+The test character @var{x} may be any one of `@t{l}', `@t{n}', `@t{m}'
+or `@t{M}', which indicate a `true' result if the corresponding
+escape sequence would return a non-empty value; or it may be `@t{a}',
+which indicates a `true' result if the watched user has logged in,
+or `false' if he has logged out.
+Other characters evaluate to neither true nor false; the entire
+expression is omitted in this case.
+
+@noindent
+If the result is `true', then the @var{true-text}
+is formatted according to the rules above and printed,
+and the @var{false-text} is skipped.
+If `false', the @var{true-text} is skipped and the @var{false-text}
+is formatted and printed.
+Either or both of the branches may be empty, but
+both separators must be present in any case.
+
+@end table
+
+@vindex WORDCHARS
+@item @t{WORDCHARS} <S>
+A list of non-alphanumeric characters considered part of a word
+by the line editor.
+
+@vindex ZBEEP
+@item @t{ZBEEP}
+If set, this gives a string of characters, which can use all the same codes
+as the @t{bindkey} command as described in
+@ref{The zsh/zle Module}, that will be output to the terminal
+instead of beeping.  This may have a visible instead of an audible effect;
+for example, the string `@t{\e[?5h\e[?5l}' on a vt100 or xterm will have
+the effect of flashing reverse video on and off (if you usually use reverse
+video, you should use the string `@t{\e[?5l\e[?5h}' instead).  This takes
+precedence over the @t{NOBEEP} option.
+
+@vindex ZDOTDIR
+@item @t{ZDOTDIR}
+The directory to search for shell startup files (.zshrc, etc),
+if not @t{$HOME}.
+
+@end table
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/options.yo
+@node Options, Shell Builtin Commands, Parameters, Top
+
+@chapter Options
+@noindent
+@cindex options
+@menu
+* Specifying Options::
+* Description of Options::
+* Option Aliases::
+* Single Letter Options::
+@end menu
+@node Specifying Options, Description of Options, , Options
+
+@section Specifying Options
+@noindent
+@cindex options, specifying
+Options are primarily referred to by name.
+These names are case insensitive and underscores are ignored.
+For example, `@t{allexport}' is equivalent to `@t{A__lleXP_ort}'.
+
+@noindent
+The sense of an option name may be inverted by preceding it with
+`@t{no}', so `@t{setopt No_Beep}' is equivalent to `@t{unsetopt beep}'.
+This inversion can only be done once, so `@t{nonobeep}' is @emph{not}
+a synonym for `@t{beep}'.  Similarly, `@t{tify}' is not a synonym for
+`@t{nonotify}' (the inversion of `@t{notify}').
+
+@noindent
+Some options also have one or more single letter names.
+There are two sets of single letter options: one used by default,
+and another used to emulate @cite{sh}/@cite{ksh} (used when the
+@t{SH_OPTION_LETTERS} option is set).
+The single letter options can be used on the shell command line,
+or with the @t{set}, @t{setopt} and @t{unsetopt}
+builtins, as normal Unix options preceded by `@t{-}'.
+
+@noindent
+The sense of the single letter options may be inverted by using
+`@t{+}' instead of `@t{-}'.
+Some of the single letter option names refer to an option being off,
+in which case the inversion of that name refers to the option being on.
+For example, `@t{+n}' is the short name of `@t{exec}', and
+`@t{-n}' is the short name of its inversion, `@t{noexec}'.
+
+@noindent
+In strings of single letter options supplied to the shell at startup,
+trailing whitespace will be ignored; for example the string `@t{-f    }'
+will be treated just as `@t{-f}', but the string `@t{-f i}' is an error.
+This is because many systems which implement the `@t{#!}' mechanism for
+calling scripts do not strip trailing whitespace.
+
+@noindent
+@node Description of Options, Option Aliases, Specifying Options, Options
+
+@section Description of Options
+@noindent
+@cindex options, description
+In the following list, options set by default in all emulations are marked
+<D>; those set by default only in csh, ksh, sh, or zsh emulations are marked
+<C>, <K>, <S>, <Z> as appropriate.  When listing options (by `@t{setopt}',
+`@t{unsetopt}', `@t{set -o}' or `@t{set +o}'), those turned on by default
+appear in the list prefixed with `@t{no}'.  Hence (unless
+@t{KSH_OPTION_PRINT} is set), `@t{setopt}' shows all options whose settings
+are changed from the default.
+
+@noindent
+
+@subsection Changing Directories
+@noindent
+@table @asis
+@pindex AUTO_CD
+@cindex cd, automatic
+@item @t{AUTO_CD} (@t{-J})
+If a command is issued that can't be executed as a normal command,
+and the command is the name of a directory, perform the @t{cd}
+command to that directory.
+
+@pindex AUTO_PUSHD
+@cindex cd, behaving like pushd
+@cindex pushd, making cd behave like
+@item @t{AUTO_PUSHD} (@t{-N})
+Make @t{cd} push the old directory onto the directory stack.
+
+@pindex CDABLE_VARS
+@cindex cd, to parameter
+@item @t{CDABLE_VARS} (@t{-T})
+If the argument to a @t{cd} command (or an implied @t{cd} with the
+@t{AUTO_CD} option set) is not a directory, and does not begin with a
+slash, try to expand the expression as if it were preceded by a `@t{~}' (see
+@ref{Filename Expansion}).
+
+@pindex CHASE_DOTS
+@cindex cd, with .. in argument
+@item @t{CHASE_DOTS}
+When changing to a directory containing a path segment `@t{..}' which would
+otherwise be treated as canceling the previous segment in the path (in
+other words, `@t{foo/..}' would be removed from the path, or if `@t{..}' is
+the first part of the path, the last part of @t{$PWD} would be deleted),
+instead resolve the path to the physical directory.  This option is
+overridden by @t{CHASE_LINKS}.
+
+@noindent
+For example, suppose @t{/foo/bar} is a link to the directory @t{/alt/rod}.
+Without this option set, `@t{cd /foo/bar/..}' changes to @t{/foo}; with it
+set, it changes to @t{/alt}.  The same applies if the current directory
+is @t{/foo/bar} and `@t{cd ..}' is used.  Note that all other symbolic
+links in the path will also be resolved.
+
+@pindex CHASE_LINKS
+@cindex links, symbolic
+@cindex symbolic links
+@item @t{CHASE_LINKS} (@t{-w})
+Resolve symbolic links to their true values when changing directory.
+This also has the effect of @t{CHASE_DOTS}, i.e. a `@t{..}' path segment
+will be treated as referring to the physical parent, even if the preceding
+path segment is a symbolic link.
+
+@pindex PUSHD_IGNORE_DUPS
+@cindex directory stack, ignoring duplicates
+@item @t{PUSHD_IGNORE_DUPS}
+Don't push multiple copies of the same directory onto the directory stack.
+
+@pindex PUSHD_MINUS
+@cindex directory stack, controlling syntax
+@item @t{PUSHD_MINUS}
+Exchanges the meanings of `@t{+}' and `@t{-}'
+when used with a number to specify a directory in the stack.
+
+@pindex PUSHD_SILENT
+@cindex directory stack, silencing
+@item @t{PUSHD_SILENT} (@t{-E})
+Do not print the directory stack after @t{pushd} or @t{popd}.
+
+@pindex PUSHD_TO_HOME
+@cindex pushd, to home
+@item @t{PUSHD_TO_HOME} (@t{-D})
+Have @t{pushd} with no arguments act like `@t{pushd $HOME}'.
+
+@end table
+
+@noindent
+
+@subsection Completion
+@noindent
+@table @asis
+@pindex ALWAYS_LAST_PROMPT
+@item @t{ALWAYS_LAST_PROMPT} <D>
+If unset, key functions that list completions try to return to the last
+prompt if given a numeric argument. If set these functions try to
+return to the last prompt if given @emph{no} numeric argument.
+
+@pindex ALWAYS_TO_END
+@item @t{ALWAYS_TO_END}
+If a completion is performed with the cursor within a word, and a
+full completion is inserted, the cursor is moved to the end of the
+word.  That is, the cursor is moved to the end of the word if either
+a single match is inserted or menu completion is performed.
+
+@pindex AUTO_LIST
+@cindex completion, listing choices
+@item @t{AUTO_LIST} (@t{-9}) <D>
+Automatically list choices on an ambiguous completion.
+
+@pindex AUTO_MENU
+@cindex completion, menu
+@item @t{AUTO_MENU} <D>
+Automatically use menu completion after the second consecutive request for
+completion, for example by pressing the tab key repeatedly. This option
+is overridden by @t{MENU_COMPLETE}.
+
+@pindex AUTO_NAME_DIRS
+@cindex directories, named
+@item @t{AUTO_NAME_DIRS}
+Any parameter that is set to the absolute name of a directory
+immediately becomes a name for that directory, that will be used
+by the `@t{%~}'
+and related prompt sequences, and will be available when completion
+is performed on a word starting with `@t{~}'.
+(Otherwise, the parameter must be used in the form `@t{~}@var{param}' first.)
+
+@pindex AUTO_PARAM_KEYS
+@item @t{AUTO_PARAM_KEYS} <D>
+If a parameter name was completed and a following character
+(normally a space) automatically
+inserted, and the next character typed is one
+of those that have to come directly after the name (like `@t{@}}', `@t{:}',
+etc.), the automatically added character is deleted, so that the character
+typed comes immediately after the parameter name.
+Completion in a brace expansion is affected similarly: the added character
+is a `@t{,}', which will be removed if `@t{@}}' is typed next.
+
+@pindex AUTO_PARAM_SLASH
+@item @t{AUTO_PARAM_SLASH} <D>
+If a parameter is completed whose content is the name of a directory,
+then add a trailing slash instead of a space.
+
+@pindex AUTO_REMOVE_SLASH
+@cindex slash, removing trailing
+@item @t{AUTO_REMOVE_SLASH} <D>
+When the last character resulting from a completion is a slash and the next
+character typed is a word delimiter, a slash, or a character that ends 
+a command (such as a semicolon or an ampersand), remove the slash.
+
+@pindex BASH_AUTO_LIST
+@cindex completion, listing choices, bash style
+@item @t{BASH_AUTO_LIST}
+On an ambiguous completion, automatically list choices when the
+completion function is called twice in succession.  This takes
+precedence over @t{AUTO_LIST}.  The setting of @t{LIST_AMBIGUOUS} is
+respected.  If @t{AUTO_MENU} is set, the menu behaviour will then start
+with the third press.  Note that this will not work with
+@t{MENU_COMPLETE}, since repeated completion calls immediately cycle
+through the list in that case.
+
+@pindex COMPLETE_ALIASES
+@cindex aliases, completion of
+@item @t{COMPLETE_ALIASES}
+Prevents aliases on the command line from being internally substituted
+before completion is attempted.  The effect is to make the alias a
+distinct command for completion purposes.
+
+@pindex COMPLETE_IN_WORD
+@item @t{COMPLETE_IN_WORD}
+If unset, the cursor is set to the end of the word if completion is
+started. Otherwise it stays there and completion is done from both ends.
+
+@pindex GLOB_COMPLETE
+@item @t{GLOB_COMPLETE}
+When the current word has a glob pattern, do not insert all the words
+resulting from the expansion but generate matches as for completion and
+cycle through them like @t{MENU_COMPLETE}. The matches are generated as if
+a `@t{*}' was added to the end of the word, or inserted at the cursor when
+@t{COMPLETE_IN_WORD} is set.  This actually uses pattern matching, not
+globbing, so it works not only for files but for any completion, such as
+options, user names, etc.
+
+@pindex HASH_LIST_ALL
+@item @t{HASH_LIST_ALL} <D>
+Whenever a command completion is attempted, make sure the entire
+command path is hashed first.  This makes the first completion slower.
+
+@pindex LIST_AMBIGUOUS
+@cindex ambiguous completion
+@cindex completion, ambiguous
+@item @t{LIST_AMBIGUOUS} <D>
+This option works when @t{AUTO_LIST} or @t{BASH_AUTO_LIST} is also
+set.  If there is an unambiguous prefix to insert on the command line,
+that is done without a completion list being displayed; in other
+words, auto-listing behaviour only takes place when nothing would be
+inserted.  In the case of @t{BASH_AUTO_LIST}, this means that the list
+will be delayed to the third call of the function.
+
+@pindex LIST_BEEP
+@cindex beep, ambiguous completion
+@cindex completion, beep on ambiguous
+@item @t{LIST_BEEP} <D>
+Beep on an ambiguous completion.  More accurately, this forces the
+completion widgets to return status 1 on an ambiguous completion, which
+causes the shell to beep if the option @t{BEEP} is also set; this may
+be modified if completion is called from a user-defined widget.
+
+@pindex LIST_PACKED
+@cindex completion, listing
+@item @t{LIST_PACKED}
+Try to make the completion list smaller (occupying less lines) by
+printing the matches in columns with different widths.
+
+@pindex LIST_ROWS_FIRST
+@cindex completion, listing order
+@item @t{LIST_ROWS_FIRST}
+Lay out the matches in completion lists sorted horizontally, that is,
+the second match is to the right of the first one, not under it as
+usual.
+
+@pindex LIST_TYPES
+@cindex marking file types
+@cindex files, marking type of
+@item @t{LIST_TYPES} (@t{-X}) <D>
+When listing files that are possible completions, show the
+type of each file with a trailing identifying mark.
+
+@pindex MENU_COMPLETE
+@cindex completion, menu
+@item @t{MENU_COMPLETE} (@t{-Y})
+On an ambiguous completion, instead of listing possibilities or beeping,
+insert the first match immediately.  Then when completion is requested
+again, remove the first match and insert the second match, etc.
+When there are no more matches, go back to the first one again.
+@t{reverse-menu-complete} may be used to loop through the list
+in the other direction. This option overrides @t{AUTO_MENU}.
+
+@pindex REC_EXACT
+@cindex completion, exact matches
+@item @t{REC_EXACT} (@t{-S})
+In completion, recognize exact matches even
+if they are ambiguous.
+
+@end table
+
+@noindent
+
+@subsection Expansion and Globbing
+@noindent
+@table @asis
+@pindex BAD_PATTERN
+@cindex globbing, bad pattern
+@cindex filename generation, bad pattern
+@item @t{BAD_PATTERN} (@t{+2}) <C> <Z>
+If a pattern for filename generation is badly formed, print an error message.
+(If this option is unset, the pattern will be left unchanged.)
+
+@pindex BARE_GLOB_QUAL
+@cindex globbing qualifiers, enable
+@cindex enable globbing qualifiers
+@item @t{BARE_GLOB_QUAL} <Z>
+In a glob pattern, treat a trailing set of parentheses as a qualifier
+list, if it contains no `@t{|}', `@t{(}' or (if special) `@t{~}'
+characters.  See @ref{Filename Generation}.
+
+@pindex BRACE_CCL
+@cindex brace expansion, extending
+@cindex expansion, brace, extending
+@item @t{BRACE_CCL}
+Expand expressions in braces which would not otherwise undergo brace
+expansion to a lexically ordered list of all the characters.  See
+@ref{Brace Expansion}.
+
+@pindex CASE_GLOB
+@cindex case-insensitive globbing, option
+@item @t{CASE_GLOB} <D>
+Make globbing (filename generation) sensitive to case.  Note that other
+uses of patterns are always sensitive to case.  If the option is unset,
+the presence of any character which is special to filename generation
+will cause case-insensitive matching.  For example, @t{cvs(/)} can
+match the directory @t{CVS} owing to the presence of the globbing flag
+(unless the option @t{BARE_GLOB_QUAL} is unset).
+
+@pindex CSH_NULL_GLOB
+@cindex csh, null globbing style
+@cindex null globbing style, csh
+@cindex globbing, null, style, csh
+@item @t{CSH_NULL_GLOB} <C>
+If a pattern for filename generation has no matches,
+delete the pattern from the argument list;
+do not report an error unless all the patterns
+in a command have no matches.
+Overrides @t{NOMATCH}.
+
+@pindex EQUALS
+@cindex filename expansion, =
+@item @t{EQUALS} <Z>
+Perform @t{=} filename expansion.
+(See @ref{Filename Expansion}.)
+
+@pindex EXTENDED_GLOB
+@cindex globbing, extended
+@item @t{EXTENDED_GLOB}
+Treat the `@t{#}', `@t{~}' and `@t{^}' characters as part of patterns
+for filename generation, etc.  (An initial unquoted `@t{~}'
+always produces named directory expansion.)
+
+@pindex GLOB
+@cindex globbing, enabling
+@cindex enabling globbing
+@item @t{GLOB} (@t{+F}, ksh: @t{+f}) <D>
+Perform filename generation (globbing).
+(See @ref{Filename Generation}.)
+
+@pindex GLOB_ASSIGN
+@item @t{GLOB_ASSIGN} <C>
+If this option is set, filename generation (globbing) is
+performed on the right hand side of scalar parameter assignments of
+the form `@var{name}@t{=}@var{pattern} (e.g. `@t{foo=*}').
+If the result has more than one word the parameter will become an array
+with those words as arguments. This option is provided for backwards
+compatibility only: globbing is always performed on the right hand side
+of array assignments of the form `@var{name}@t{=(}@var{value}@t{)}'
+(e.g. `@t{foo=(*)}') and this form is recommended for clarity;
+with this option set, it is not possible to predict whether the result
+will be an array or a scalar.
+
+@pindex GLOB_DOTS
+@cindex globbing, of . files
+@item @t{GLOB_DOTS} (@t{-4})
+Do not require a leading `@t{.}' in a filename to be matched explicitly.
+
+@pindex GLOB_SUBST
+@item @t{GLOB_SUBST} <C> <K> <S>
+Treat any characters resulting from parameter expansion as being
+eligible for file expansion and filename generation, and any
+characters resulting from command substitution as being eligible for
+filename generation.  Braces (and commas in between) do not become eligible
+for expansion.
+
+@pindex IGNORE_BRACES
+@cindex disabling brace expansion
+@cindex brace expansion, disabling
+@cindex expansion, brace, disabling
+@item @t{IGNORE_BRACES} (@t{-I}) <S>
+Do not perform brace expansion.
+
+@pindex KSH_GLOB
+@item @t{KSH_GLOB} <K>
+In pattern matching, the interpretation of parentheses is affected by
+a preceding `@t{@@}', `@t{*}', `@t{+}', `@t{?}' or `@t{!}'.
+See @ref{Filename Generation}.
+
+@pindex MAGIC_EQUAL_SUBST
+@item @t{MAGIC_EQUAL_SUBST}
+All unquoted arguments of the form `@var{anything}@t{=}@var{expression}'
+appearing after the command name have filename expansion (that is,
+where @var{expression} has a leading `@t{~}' or `@t{=}') performed on
+@var{expression} as if it were a parameter assignment.  The argument is
+not otherwise treated specially; it is passed to the command as a single
+argument, and not used as an actual parameter assignment.  For example, in
+@t{echo foo=~/bar:~/rod}, both occurrences of @t{~} would be replaced.
+Note that this happens anyway with @t{typeset} and similar statements.
+
+@noindent
+This option respects the setting of the @t{KSH_TYPESET} option.  In other
+words, if both options are in effect, arguments looking like
+assignments will not undergo wordsplitting.
+
+@pindex MARK_DIRS
+@cindex directories, marking
+@cindex marking directories
+@item @t{MARK_DIRS} (@t{-8}, ksh: @t{-X})
+Append a trailing `@t{/}' to all directory
+names resulting from filename generation (globbing).
+
+@pindex NOMATCH
+@cindex globbing, no matches
+@item @t{NOMATCH} (@t{+3}) <C> <Z>
+If a pattern for filename generation has no matches,
+print an error, instead of
+leaving it unchanged in the argument list.
+This also applies to file expansion
+of an initial `@t{~}' or `@t{=}'.
+
+@pindex NULL_GLOB
+@cindex globbing, no matches
+@item @t{NULL_GLOB} (@t{-G})
+If a pattern for filename generation has no matches,
+delete the pattern from the argument list instead
+of reporting an error.  Overrides @t{NOMATCH}.
+
+@pindex NUMERIC_GLOB_SORT
+@cindex globbing, sorting numerically
+@item @t{NUMERIC_GLOB_SORT}
+If numeric filenames are matched by a filename generation pattern,
+sort the filenames numerically rather than lexicographically.
+
+@pindex RC_EXPAND_PARAM
+@cindex rc, parameter expansion style
+@cindex parameter expansion style, rc
+@item @t{RC_EXPAND_PARAM} (@t{-P})
+Array expansions of the form
+`@var{foo}@t{$@{}@var{xx}@t{@}}@var{bar}', where the parameter
+@var{xx} is set to @t{(}@var{a b c}@t{)}, are substituted with
+`@var{fooabar foobbar foocbar}' instead of the default
+`@var{fooa b cbar}'.
+
+@pindex SH_GLOB
+@cindex sh, globbing style
+@cindex globbing style, sh
+@item @t{SH_GLOB} <K> <S>
+Disables the special meaning of `@t{(}', `@t{|}', `@t{)}'
+and '@t{<}' for globbing the result of parameter and command substitutions,
+and in some other places where
+the shell accepts patterns.  This option is set by default if zsh is
+invoked as @t{sh} or @t{ksh}.
+
+@pindex UNSET
+@cindex parameters, substituting unset
+@cindex unset parameters, substituting
+@item @t{UNSET} (@t{+u}, ksh: @t{+u}) <K> <S> <Z>
+Treat unset parameters as if they were empty when substituting.
+Otherwise they are treated as an error.
+
+@end table
+
+@noindent
+
+@subsection History
+@noindent
+@table @asis
+@pindex APPEND_HISTORY
+@cindex history, appending to a file
+@item @t{APPEND_HISTORY} <D>
+If this is set, zsh sessions will append their history list to
+the history file, rather than overwrite it. Thus, multiple parallel
+zsh sessions will all have their history lists added to the
+history file, in the order they are killed.
+
+@pindex BANG_HIST
+@cindex history, enable substitution
+@cindex enable history substitution
+@item @t{BANG_HIST} (@t{+K}) <C> <Z>
+Perform textual history expansion, @cite{csh}-style,
+treating the character `@t{!}' specially.
+
+@pindex EXTENDED_HISTORY
+@cindex history, timestamping
+@item @t{EXTENDED_HISTORY} <C>
+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:
+
+@noindent
+`@t{:}@var{<beginning time>}@t{:}@var{<elapsed seconds>}@t{:}@var{<command>}'.
+
+@pindex HIST_ALLOW_CLOBBER
+@item @t{HIST_ALLOW_CLOBBER}
+Add `@t{|}' to output redirections in the history.  This allows history
+references to clobber files even when @t{CLOBBER} is unset.
+
+@pindex HIST_BEEP
+@cindex history beeping
+@cindex beep, history
+@item @t{HIST_BEEP} <D>
+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 @t{HIST_EXPIRE_DUPS_FIRST}
+If the internal history needs to be trimmed to add the current command line,
+setting this option will cause the oldest history event that has a duplicate
+to be lost before losing a unique event from the list.
+You should be sure to set the value of @t{HISTSIZE} to a larger number
+than @t{SAVEHIST} in order to give you some room for the duplicated
+events, otherwise this option will behave just like
+@t{HIST_IGNORE_ALL_DUPS} once the history fills up with unique events.
+
+@pindex HIST_FIND_NO_DUPS
+@cindex history, ignoring duplicates in search
+@item @t{HIST_FIND_NO_DUPS}
+When searching for history entries in the line editor, do not display
+duplicates of a line previously found, even if the duplicates are not
+contiguous.
+
+@pindex HIST_IGNORE_ALL_DUPS
+@cindex history, ignoring all duplicates
+@item @t{HIST_IGNORE_ALL_DUPS}
+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 @t{HIST_IGNORE_DUPS} (@t{-h})
+Do not enter command lines into the history list
+if they are duplicates of the previous event.
+
+@pindex HIST_IGNORE_SPACE
+@cindex history, ignoring spaces
+@item @t{HIST_IGNORE_SPACE} (@t{-g})
+Remove command lines from the history list when the first character on
+the line is a space, or when one of the expanded aliases contains a
+leading space.
+Note that the command lingers in the internal history until the next
+command is entered before it vanishes, allowing you to briefly reuse
+or edit the line.  If you want to make it vanish right away without
+entering another command, type a space and press return.
+
+@pindex HIST_NO_FUNCTIONS
+@item @t{HIST_NO_FUNCTIONS}
+Remove function definitions from the history list.
+Note that the function lingers in the internal history until the next
+command is entered before it vanishes, allowing you to briefly reuse
+or edit the definition.
+
+@pindex HIST_NO_STORE
+@item @t{HIST_NO_STORE}
+Remove the @t{history} (@t{fc -l}) command from the history list
+when invoked.
+Note that the command lingers in the internal history until the next
+command is entered before it vanishes, allowing you to briefly reuse
+or edit the line.
+
+@pindex HIST_REDUCE_BLANKS
+@item @t{HIST_REDUCE_BLANKS}
+Remove superfluous blanks from each command line
+being added to the history list.
+
+@pindex HIST_SAVE_NO_DUPS
+@item @t{HIST_SAVE_NO_DUPS}
+When writing out the history file, older commands that duplicate
+newer ones are omitted.
+
+@pindex HIST_VERIFY
+@cindex history, verifying substitution
+@item @t{HIST_VERIFY}
+Whenever the user enters a line with history expansion,
+don't execute the line directly; instead, perform
+history expansion and reload the line into the editing buffer.
+
+@pindex INC_APPEND_HISTORY
+@cindex history, incremental appending to a file
+@item @t{INC_APPEND_HISTORY}
+This options works like @t{APPEND_HISTORY} except that new history lines
+are added to the @t{$HISTFILE} incrementally (as soon as they are
+entered), rather than waiting until the shell is killed.
+The file is periodically trimmed to the number of lines specified by
+@t{$SAVEHIST}, but can exceed this value between trimmings.
+
+@pindex SHARE_HISTORY
+@cindex share history
+@cindex history, sharing
+@item @t{SHARE_HISTORY} <K>
+
+@noindent
+This option both imports new commands from the history file, and also
+causes your typed commands to be appended to the history file (the
+latter is like specifying @t{INC_APPEND_HISTORY}).
+The history lines are also output with timestamps ala
+@t{EXTENDED_HISTORY} (which makes it easier to find the spot where
+we left off reading the file after it gets re-written).
+
+@noindent
+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.
+
+@noindent
+If you find that you want more control over when commands
+get imported, you may wish to turn @t{SHARE_HISTORY} off,
+@t{INC_APPEND_HISTORY} on, and then manually import
+commands whenever you need them using `@t{fc -RI}'.
+
+@end table
+
+@noindent
+
+@subsection Initialisation
+@noindent
+@table @asis
+@pindex ALL_EXPORT
+@cindex export, automatic
+@item @t{ALL_EXPORT} (@t{-a}, ksh: @t{-a})
+All parameters subsequently defined are automatically exported.
+
+@pindex GLOBAL_EXPORT
+@cindex environment, and local parameters
+@item @t{GLOBAL_EXPORT} (@t{<Z>})
+If this option is set, passing the @t{-x} flag to the builtins @t{declare},
+@t{float}, @t{integer}, @t{readonly} and @t{typeset} (but not @t{local})
+will also set the @t{-g} flag;  hence parameters exported to
+the environment will not be made local to the enclosing function, unless
+they were already or the flag @t{+g} is given explicitly.  If the option is
+unset, exported parameters will be made local in just the same way as any
+other parameter.
+
+@noindent
+This option is set by default for backward compatibility; it is not
+recommended that its behaviour be relied upon.  Note that the builtin
+@t{export} always sets both the @t{-x} and @t{-g} flags, and hence its
+effect extends beyond the scope of the enclosing function; this is the
+most portable way to achieve this behaviour.
+
+@cindex exporting, and local parameters
+@pindex GLOBAL_RCS
+@cindex startup files, global, inhibiting
+@cindex files, global startup, inhibiting
+@item @t{GLOBAL_RCS} (@t{-d}) <D>
+If this option is unset, the startup files @t{/etc/zprofile},
+@t{/etc/zshrc}, @t{/etc/zlogin} and @t{/etc/zlogout} will not be run.  It
+can be disabled and re-enabled at any time, including inside local startup
+files (@t{.zshrc}, etc.).
+
+@pindex RCS
+@cindex startup files, sourcing
+@item @t{RCS} (@t{+f}) <D>
+After @t{/etc/zshenv} is sourced on startup, source the
+@t{.zshenv}, @t{/etc/zprofile}, @t{.zprofile},
+@t{/etc/zshrc}, @t{.zshrc}, @t{/etc/zlogin}, @t{.zlogin}, and @t{.zlogout}
+files, as described in @ref{Files}.
+If this option is unset, the @t{/etc/zshenv} file is still sourced, but any
+of the others will not be; it can be set at any time to prevent the
+remaining startup files after the currently executing one from
+being sourced.
+
+@end table
+
+@noindent
+
+@subsection Input/Output
+@noindent
+@table @asis
+@pindex ALIASES
+@cindex aliases, expansion
+@item @t{ALIASES} <D>
+Expand aliases.
+
+@pindex CLOBBER
+@cindex clobbering, of files
+@cindex file clobbering, allowing
+@item @t{CLOBBER} (@t{+C}, ksh: @t{+C}) <D>
+Allows `@t{>}' redirection to truncate existing files,
+and `@t{>>}' to create files.
+Otherwise `@t{>!}' or `@t{>|}' must be used to truncate a file,
+and `@t{>>!}' or `@t{>>|}' to create a file.
+
+@pindex CORRECT
+@cindex correction, spelling
+@cindex spelling correction
+@item @t{CORRECT} (@t{-0})
+Try to correct the spelling of commands.
+Note that, when the @t{HASH_LIST_ALL} option is not set or when some
+directories in the path are not readable, this may falsely report spelling
+errors the first time some commands are used.
+
+@pindex CORRECT_ALL
+@item @t{CORRECT_ALL} (@t{-O})
+Try to correct the spelling of all arguments in a line.
+
+@pindex DVORAK
+@item @t{DVORAK}
+Use the Dvorak keyboard instead of the standard qwerty keyboard as a basis
+for examining spelling mistakes for the @t{CORRECT} and @t{CORRECT_ALL}
+options and the @t{spell-word} editor command.
+
+@pindex FLOW_CONTROL
+@cindex flow control
+@item @t{FLOW_CONTROL} <D>
+If this option is unset,
+output flow control via start/stop characters (usually assigned to
+^S/^Q) is disabled in the shell's editor.
+
+@pindex IGNORE_EOF
+@cindex EOF, ignoring
+@item @t{IGNORE_EOF} (@t{-7})
+Do not exit on end-of-file.  Require the use
+of @t{exit} or @t{logout} instead.
+However, ten consecutive EOFs will cause the shell to exit anyway,
+to avoid the shell hanging if its tty goes away.
+
+@noindent
+Also, if this option is set and the Zsh Line Editor is used, widgets
+implemented by shell functions can be bound to EOF (normally
+Control-D) without printing the normal warning message.  This works
+only for normal widgets, not for completion widgets.
+
+@pindex INTERACTIVE_COMMENTS
+@cindex comments, in interactive shells
+@item @t{INTERACTIVE_COMMENTS} (@t{-k}) <K> <S>
+Allow comments even in interactive shells.
+
+@pindex HASH_CMDS
+@cindex hashing, of commands
+@cindex command hashing
+@item @t{HASH_CMDS} <D>
+Note the location of each command the first time it is executed.
+Subsequent invocations of the same command will use the
+saved location, avoiding a path search.
+If this option is unset, no path hashing is done at all.
+However, when @t{CORRECT} is set, commands whose names do not appear in
+the functions or aliases hash tables are hashed in order to avoid
+reporting them as spelling errors.
+
+@pindex HASH_DIRS
+@cindex hashing, of directories
+@cindex directories, hashing
+@item @t{HASH_DIRS} <D>
+Whenever a command name is hashed, hash the directory containing it,
+as well as all directories that occur earlier in the path.
+Has no effect if neither @t{HASH_CMDS} nor @t{CORRECT} is set.
+
+@pindex MAIL_WARNING
+@cindex mail, warning of reading
+@item @t{MAIL_WARNING} (@t{-U})
+Print a warning message if a mail file has been
+accessed since the shell last checked.
+
+@pindex PATH_DIRS
+@cindex path search, extended
+@item @t{PATH_DIRS} (@t{-Q})
+Perform a path search even on command names with slashes in them.
+Thus if `@t{/usr/local/bin}' is in the user's path, and he or she types
+`@t{X11/xinit}', the command `@t{/usr/local/bin/X11/xinit}' will be executed
+(assuming it exists).
+Commands explicitly beginning with `@t{/}', `@t{./}' or `@t{../}'
+are not subject to the path search.
+This also applies to the @t{.} builtin.
+
+@noindent
+Note that subdirectories of the current directory are always searched for
+executables specified in this form.  This takes place before any search
+indicated by this option, and regardless of whether `@t{.}' or the current
+directory appear in the command search path.
+
+@pindex PRINT_EIGHT_BIT
+@cindex eight bit characters, printing
+@item @t{PRINT_EIGHT_BIT}
+Print eight bit characters literally in completion lists, etc.
+This option is not necessary if your system correctly returns the
+printability of eight bit characters (see man page ctype(3)).
+
+@pindex PRINT_EXIT_VALUE
+@cindex exit status, printing
+@item @t{PRINT_EXIT_VALUE} (@t{-1})
+Print the exit value of programs with non-zero exit status.
+
+@pindex RC_QUOTES
+@cindex rc, quoting style
+@cindex quoting style, rc
+@item @t{RC_QUOTES}
+Allow the character sequence `@t{@value{dsq}}' to signify a single quote
+within singly quoted strings.  Note this does not apply in quoted strings
+using the format @t{$'}@var{...}@t{'}, where a backslashed single quote can
+be used.
+
+@pindex RM_STAR_SILENT
+@cindex rm *, querying before
+@cindex querying before rm *
+@item @t{RM_STAR_SILENT} (@t{-H}) <K> <S>
+Do not query the user before executing `@t{rm *}' or `@t{rm path/*}'.
+
+@pindex RM_STAR_WAIT
+@cindex rm *, waiting before
+@cindex waiting before rm *
+@item @t{RM_STAR_WAIT}
+If querying the user before executing `@t{rm *}' or `@t{rm path/*}',
+first wait ten seconds and ignore anything typed in that time.
+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 `@t{*}' in ZLE (with tab).
+
+@pindex SHORT_LOOPS
+@item @t{SHORT_LOOPS} <C> <Z>
+Allow the short forms of @t{for}, @t{repeat}, @t{select},
+@t{if}, and @t{function} constructs.
+
+@pindex SUN_KEYBOARD_HACK
+@cindex sun keyboard, annoying
+@cindex annoying keyboard, sun
+@item @t{SUN_KEYBOARD_HACK} (@t{-L})
+If a line ends with a backquote, and there are an odd number
+of backquotes on the line, ignore the trailing backquote.
+This is useful on some keyboards where the return key is
+too small, and the backquote key lies annoyingly close to it.
+
+@end table
+
+@noindent
+
+@subsection Job Control
+@noindent
+@table @asis
+@pindex AUTO_CONTINUE
+@cindex jobs, continuing automatically
+@cindex continuing jobs automatically
+@item @t{AUTO_CONTINUE}
+With this option set, stopped jobs that are removed from the job table
+with the @t{disown} builtin command are automatically sent a @t{CONT}
+signal to make them running.
+
+@pindex AUTO_RESUME
+@cindex jobs, resuming automatically
+@cindex resuming jobs automatically
+@item @t{AUTO_RESUME} (@t{-W})
+Treat single word simple commands without redirection
+as candidates for resumption of an existing job.
+
+@pindex BG_NICE
+@cindex jobs, background priority
+@cindex background jobs, priority of
+@cindex priority of background jobs
+@item @t{BG_NICE} (@t{-6}) <C> <Z>
+Run all background jobs at a lower priority.  This option
+is set by default.
+
+@pindex CHECK_JOBS
+@cindex exiting, checking jobs when
+@cindex logging out, checking jobs when
+@item @t{CHECK_JOBS} <Z>
+Report the status of background and suspended jobs before exiting a shell
+with job control; a second attempt to exit the shell will succeed.
+@t{NO_CHECK_JOBS} is best used only in combination with @t{NO_HUP}, else
+such jobs will be killed automatically.
+
+@noindent
+The check is omitted if the commands run from the previous command line
+included a `@t{jobs}' command, since it is assumed the user is aware that
+there are background or suspended jobs.  A `@t{jobs}' command run from the
+@t{precmd} function is not counted for this purpose.
+
+@pindex HUP
+@cindex jobs, HUP
+@item @t{HUP} <Z>
+Send the @t{HUP} signal to running jobs when the
+shell exits.
+
+@pindex LONG_LIST_JOBS
+@cindex jobs, list format
+@item @t{LONG_LIST_JOBS} (@t{-R})
+List jobs in the long format by default.
+
+@pindex MONITOR
+@cindex job control, allowing
+@item @t{MONITOR} (@t{-m}, ksh: @t{-m})
+Allow job control.  Set by default in interactive shells.
+
+@pindex NOTIFY
+@cindex background jobs, notification
+@cindex notification of background jobs
+@item @t{NOTIFY} (@t{-5}, ksh: @t{-b}) <Z>
+Report the status of background jobs immediately, rather than
+waiting until just before printing a prompt.
+
+@end table
+
+@noindent
+
+@subsection Prompting
+@noindent
+@table @asis
+@pindex PROMPT_BANG
+@cindex prompt, ! expansion
+@item @t{PROMPT_BANG} <K>
+If set, `@t{!}' is treated specially in prompt expansion.
+See @ref{Prompt Expansion}.
+
+@pindex PROMPT_CR
+@cindex prompt, with CR
+@item @t{PROMPT_CR} (@t{+V}) <D>
+Print a carriage return just before printing
+a prompt in the line editor.  This is on by default as multi-line editing
+is only possible if the editor knows where the start of the line appears.
+
+@pindex PROMPT_PERCENT
+@cindex prompt, % expansion
+@item @t{PROMPT_PERCENT} <C> <Z>
+If set, `@t{%}' is treated specially in prompt expansion.
+See @ref{Prompt Expansion}.
+
+@pindex PROMPT_SUBST
+@cindex prompt, parameter expansion
+@item @t{PROMPT_SUBST} <K>
+If set, @emph{parameter expansion}, @emph{command substitution} and
+@emph{arithmetic expansion} are performed in prompts.  Substitutions
+within prompts do not affect the command status.
+
+@pindex TRANSIENT_RPROMPT
+@item @t{TRANSIENT_RPROMPT}
+Remove any right prompt from display when accepting a command
+line.  This may be useful with terminals with other cut/paste methods.
+
+@end table
+
+@noindent
+
+@subsection Scripts and Functions
+@noindent
+@table @asis
+@pindex C_BASES
+@cindex bases, output in C format
+@cindex hexadecimal, output in C format
+@cindex octal, output in C format
+@item @t{C_BASES}
+Output hexadecimal numbers in the standard C format, for example `@t{0xFF}'
+instead of the usual `@t{16#FF}'.  If the option @t{OCTAL_ZEROES} is also
+set (it is not by default), octal numbers will be treated similarly and
+hence appear as `@t{077}' instead of `@t{8#77}'.  This option has no effect
+on the choice of the output base, nor on the output of bases other than
+hexadecimal and octal.  Note that these formats will be understood on input
+irrespective of the setting of @t{C_BASES}.
+
+@pindex ERR_EXIT
+@cindex exit status, trapping
+@item @t{ERR_EXIT} (@t{-e}, ksh: @t{-e})
+If a command has a non-zero exit status, execute the @t{ZERR}
+trap, if set, and exit.  This is disabled while running initialization
+scripts.
+
+@pindex ERR_RETURN
+@cindex function return, on error
+@cindex return from function, on error
+@item @t{ERR_RETURN}
+If a command has a non-zero exit status, return immediately from the
+enclosing function.  The logic is identical to that for @t{ERR_EXIT},
+except that an implicit @t{return} statement is executed instead of an
+@t{exit}.  This will trigger an exit at the outermost level of a
+non-interactive script.
+
+@pindex EVAL_LINENO
+@cindex line number, in evaluated expression
+@item @t{EVAL_LINENO} <Z>
+If set, line numbers of expressions evaluated using the builtin @t{eval}
+are tracked separately of the enclosing environment.  This applies both
+to the parameter @t{LINENO} and the line number output by the prompt
+escape @t{%i}.  If the option is set, the prompt escape @t{%N} will output
+the string `@t{(eval)}' instead of the script or function name as an
+indication.   (The two prompt escapes are typically used in the parameter
+@t{PS4} to be output when the option @t{XTRACE} is set.)  If
+@t{EVAL_LINENO} is unset, the line number of the surrounding script or
+function is retained during the evaluation.
+
+@pindex EXEC
+@cindex command execution, enabling
+@item @t{EXEC} (@t{+n}, ksh: @t{+n}) <D>
+Do execute commands.  Without this option, commands are
+read and checked for syntax errors, but not executed.
+This option cannot be turned off in an interactive shell,
+except when `@t{-n}' is supplied to the shell at startup.
+
+@pindex FUNCTION_ARGZERO
+@cindex $0, setting
+@item @t{FUNCTION_ARGZERO} <C> <Z>
+When executing a shell function or sourcing a script, set @t{$0}
+temporarily to the name of the function/script.
+
+@pindex LOCAL_OPTIONS
+@item @t{LOCAL_OPTIONS} <K>
+If this option is set at the point of return from a shell function,
+all the options (including this one) which were in force upon entry to
+the function are restored.  Otherwise, only this option and the
+@t{XTRACE} and @t{PRINT_EXIT_VALUE} options are restored.  Hence
+if this is explicitly unset by a shell function the other options in
+force at the point of return will remain so.
+A shell function can also guarantee itself a known shell configuration
+with a formulation like `@t{emulate -L zsh}'; the @t{-L} activates
+@t{LOCAL_OPTIONS}.
+
+@pindex LOCAL_TRAPS
+@item @t{LOCAL_TRAPS} <K>
+If this option is set when a signal trap is set inside a function, then the
+previous status of the trap for that signal will be restored when the
+function exits.  Note that this option must be set @emph{prior} to altering the
+trap behaviour in a function; unlike @t{LOCAL_OPTIONS}, the value on exit
+from the function is irrelevant.  However, it does not need to be set
+before any global trap for that to be correctly restored by a function.
+For example,
+
+@noindent
+@example
+unsetopt localtraps
+trap - INT
+fn() @{ setopt localtraps; trap @value{dsq} INT; sleep 3; @}
+@end example
+
+@noindent
+will restore normally handling of @t{SIGINT} after the function exits.
+
+@pindex MULTIOS
+@item @t{MULTIOS} <Z>
+Perform implicit @cite{tee}s or @cite{cat}s when multiple
+redirections are attempted (see @ref{Redirection}).
+
+@pindex OCTAL_ZEROES
+@cindex octal, arithmetic expressions
+@item @t{OCTAL_ZEROES} <S>
+Interpret any integer constant beginning with a 0 as octal, per IEEE Std
+1003.2-1992 (ISO 9945-2:1993).  This is not enabled by default as it
+causes problems with parsing of, for example, date and time strings with
+leading zeroes.
+
+@pindex TYPESET_SILENT
+@item @t{TYPESET_SILENT}
+If this is unset, executing any of the `@t{typeset}' family of
+commands with no options and a list of parameters that have no values
+to be assigned but already exist will display the value of the parameter.
+If the option is set, they will only be shown when parameters are selected
+with the `@t{-m}' option.  The option `@t{-p}' is available whether or not
+the option is set.
+
+@pindex VERBOSE
+@cindex tracing, of input lines
+@cindex input, tracing
+@item @t{VERBOSE} (@t{-v}, ksh: @t{-v})
+Print shell input lines as they are read.
+
+@pindex XTRACE
+@cindex tracing, of commands
+@cindex commands, tracing
+@item @t{XTRACE} (@t{-x}, ksh: @t{-x})
+Print commands and their arguments as they are executed.
+
+@end table
+
+@noindent
+
+@subsection Shell Emulation
+@noindent
+@table @asis
+@pindex BSD_ECHO
+@cindex echo, BSD compatible
+@item @t{BSD_ECHO} <S>
+Make the @t{echo} builtin compatible with the BSD man page echo(1) command.
+This disables backslashed escape sequences in echo strings unless the
+@t{-e} option is specified.
+
+@pindex CSH_JUNKIE_HISTORY
+@cindex csh, history style
+@cindex history style, csh
+@item @t{CSH_JUNKIE_HISTORY} <C>
+A history reference without an event specifier will always refer to the
+previous command.  Without this option, such a history reference refers
+to the same event as the previous history reference, defaulting to the
+previous command.
+
+@pindex CSH_JUNKIE_LOOPS
+@cindex csh, loop style
+@cindex loop style, csh
+@item @t{CSH_JUNKIE_LOOPS} <C>
+Allow loop bodies to take the form `@var{list}; @t{end}' instead of
+`@t{do} @var{list}; @t{done}'.
+
+@pindex CSH_JUNKIE_QUOTES
+@cindex csh, quoting style
+@cindex quoting style, csh
+@item @t{CSH_JUNKIE_QUOTES} <C>
+Changes the rules for single- and double-quoted text to match that of
+@cite{csh}.  These require that embedded newlines be preceded by a backslash;
+unescaped newlines will cause an error message.
+In double-quoted strings, it is made impossible to escape `@t{$}', `@t{`}'
+or `@t{"}' (and `@t{\}' itself no longer needs escaping).
+Command substitutions are only expanded once, and cannot be nested.
+
+@pindex CSH_NULLCMD
+@vindex NULLCMD, ignoring
+@vindex READNULLCMD, ignoring
+@cindex redirections with no command, csh
+@cindex csh, redirections with no command
+@item @t{CSH_NULLCMD} <C>
+Do not use the values of @t{NULLCMD} and @t{READNULLCMD} 
+when running redirections with no command.  This make 
+such redirections fail (see @ref{Redirection}).
+
+@pindex KSH_ARRAYS
+@cindex arrays, ksh style
+@cindex array style, ksh
+@cindex ksh, array style
+@item @t{KSH_ARRAYS} <K> <S>
+Emulate @cite{ksh} array handling as closely as possible.  If this option
+is set, array elements are numbered from zero, an array parameter
+without subscript refers to the first element instead of the whole array,
+and braces are required to delimit a subscript (`@t{$@{path[2]@}}' rather
+than just `@t{$path[2]}').
+
+@pindex KSH_AUTOLOAD
+@item @t{KSH_AUTOLOAD} <K> <S>
+Emulate @cite{ksh} function autoloading.  This means that when a function is
+autoloaded, the corresponding file is merely executed, and must define
+the function itself.  (By default, the function is defined to the contents
+of the file.  However, the most common @cite{ksh}-style case - of the file
+containing only a simple definition of the function - is always handled
+in the @cite{ksh}-compatible manner.)
+
+@pindex KSH_OPTION_PRINT
+@cindex option printing, ksh style
+@cindex option printing style, ksh
+@cindex ksh, option printing style
+@item @t{KSH_OPTION_PRINT} <K>
+Alters the way options settings are printed: instead of separate lists of
+set and unset options, all options are shown, marked `on' if
+they are in the non-default state, `off' otherwise.
+
+@pindex KSH_TYPESET
+@cindex argument splitting, in typeset etc.
+@cindex ksh, argument splitting in typeset
+@item @t{KSH_TYPESET} <K>
+Alters the way arguments to the @t{typeset} family of commands, including
+@t{declare}, @t{export}, @t{float}, @t{integer}, @t{local} and
+@t{readonly}, are processed.  Without this option, zsh will perform normal
+word splitting after command and parameter expansion in arguments of an
+assignment; with it, word splitting does not take place in those cases.
+
+@pindex POSIX_BUILTINS
+@item @t{POSIX_BUILTINS} <K> <S>
+When this option is set the @t{command} builtin can be used to execute
+shell builtin commands.  Parameter assignments specified before shell
+functions and special builtins are kept after the command completes unless
+the special builtin is prefixed with the @t{command} builtin.  Special
+builtins are
+@t{.},
+@t{:},
+@t{break},
+@t{continue},
+@t{declare},
+@t{eval},
+@t{exit},
+@t{export},
+@t{integer},
+@t{local},
+@t{readonly},
+@t{return},
+@t{set},
+@t{shift},
+@t{source},
+@t{times},
+@t{trap} and
+@t{unset}.
+
+@pindex SH_FILE_EXPANSION
+@cindex sh, expansion style
+@cindex expansion style, sh
+@item @t{SH_FILE_EXPANSION} <K> <S>
+Perform filename expansion (e.g., ~ expansion) @emph{before}
+parameter expansion, command substitution, arithmetic expansion
+and brace expansion.
+If this option is unset, it is performed @emph{after}
+brace expansion, so things like `@t{~$USERNAME}' and
+`@t{~@{pfalstad,rc@}}' will work.
+
+@pindex SH_NULLCMD
+@vindex NULLCMD, ignoring
+@vindex READNULLCMD, ignoring
+@cindex sh, redirections with no command
+@cindex ksh, redirections with no command
+@cindex redirections with no command, sh
+@cindex redirections with no command, ksh
+@item @t{SH_NULLCMD} <K> <S>
+Do not use the values of @t{NULLCMD} and @t{READNULLCMD} 
+when doing redirections, use `@t{:}' instead (see @ref{Redirection}).
+
+@pindex SH_OPTION_LETTERS
+@cindex sh, single letter options style
+@cindex ksh, single letter options style
+@cindex single letter options, ksh style
+@cindex options, single letter, ksh style
+@item @t{SH_OPTION_LETTERS} <K> <S>
+If this option is set the shell tries to interpret single letter options
+(which are used with @t{set} and @t{setopt}) like @cite{ksh} does.
+This also affects the value of the @t{-} special parameter.
+
+@pindex SH_WORD_SPLIT
+@cindex field splitting, sh style
+@cindex sh, field splitting style
+@item @t{SH_WORD_SPLIT} (@t{-y}) <K> <S>
+Causes field splitting to be performed on unquoted parameter expansions.
+Note that this option has nothing to do with word splitting.
+(See @ref{Parameter Expansion}.)
+
+@pindex TRAPS_ASYNC
+@cindex traps, asynchronous
+@item @t{TRAPS_ASYNC}
+While waiting for a program to exit, handle signals and run traps
+immediately.  Otherwise the trap is run after a child process has exited.
+Note this does not affect the point at which traps are run for any case
+other than when the shell is waiting for a child process.
+
+@end table
+
+@noindent
+
+@subsection Shell State
+@noindent
+@table @asis
+@pindex INTERACTIVE
+@item @t{INTERACTIVE} (@t{-i}, ksh: @t{-i})
+This is an interactive shell.  This option is set upon initialisation if
+the standard input is a tty and commands are being read from standard input.
+(See the discussion of @t{SHIN_STDIN}.)
+This heuristic may be overridden by specifying a state for this option
+on the command line.
+The value of this option cannot be changed anywhere other than the command line.
+
+@pindex LOGIN
+@item @t{LOGIN} (@t{-l}, ksh: @t{-l})
+This is a login shell.
+If this option is not explicitly set, the shell is a login shell if
+the first character of the @t{argv[0]} passed to the shell is a `@t{-}'.
+
+@pindex PRIVILEGED
+@cindex privileged mode
+@cindex mode, privileged
+@item @t{PRIVILEGED} (@t{-p}, ksh: @t{-p})
+Turn on privileged mode. This is enabled automatically on startup if the
+effective user (group) ID is not equal to the real user (group) ID.  Turning
+this option off causes the effective user and group IDs to be set to the
+real user and group IDs. This option disables sourcing user startup files.
+If zsh is invoked as `@t{sh}' or `@t{ksh}' with this option set,
+@t{/etc/suid_profile} is sourced (after @t{/etc/profile} on interactive
+shells). Sourcing @t{~/.profile} is disabled and the contents of the
+@t{ENV} variable is ignored. This option cannot be changed using the
+@t{-m} option of @t{setopt} and @t{unsetopt}, and changing it inside a
+function always changes it globally regardless of the @t{LOCAL_OPTIONS}
+option.
+
+@pindex RESTRICTED
+@cindex restricted shell
+@item @t{RESTRICTED} (@t{-r})
+Enables restricted mode.  This option cannot be changed using
+@t{unsetopt}, and setting it inside a function always changes it
+globally regardless of the @t{LOCAL_OPTIONS} option.  See
+@ref{Restricted Shell}.
+
+@pindex SHIN_STDIN
+@item @t{SHIN_STDIN} (@t{-s}, ksh: @t{-s})
+Commands are being read from the standard input.
+Commands are read from standard input if no command is specified with
+@t{-c} and no file of commands is specified.  If @t{SHIN_STDIN}
+is set explicitly on the command line,
+any argument that would otherwise have been
+taken as a file to run will instead be treated as a normal positional
+parameter.
+Note that setting or unsetting this option on the command line does not
+necessarily affect the state the option will have while the shell is
+running - that is purely an indicator of whether on not commands are
+@emph{actually} being read from standard input.
+The value of this option cannot be changed anywhere other 
+than the command line.
+
+@pindex SINGLE_COMMAND
+@cindex single command
+@pindex INTERACTIVE, use of
+@item @t{SINGLE_COMMAND} (@t{-t}, ksh: @t{-t})
+If the shell is reading from standard input, it exits after a single command
+has been executed.  This also makes the shell non-interactive, unless the
+@t{INTERACTIVE} option is explicitly set on the command line.
+The value of this option cannot be changed anywhere other than the command line.
+
+@end table
+
+@noindent
+
+@subsection Zle
+@noindent
+@table @asis
+@pindex BEEP
+@cindex beep, enabling
+@cindex enabling the beep
+@item @t{BEEP} (@t{+B}) <D>
+Beep on error in ZLE.
+
+@pindex EMACS
+@item @t{EMACS}
+If ZLE is loaded, turning on this option has the equivalent effect
+of `@t{bindkey -e}'.  In addition, the VI option is unset.
+Turning it off has no effect.  The option setting is
+not guaranteed to reflect the current keymap.  This option is
+provided for compatibility; @t{bindkey} is the recommended interface.
+
+@pindex OVERSTRIKE
+@cindex editor, overstrike mode
+@cindex overstrike mode, of editor
+@item @t{OVERSTRIKE}
+Start up the line editor in overstrike mode.
+
+@pindex SINGLE_LINE_ZLE
+@cindex editor, single line mode
+@item @t{SINGLE_LINE_ZLE} (@t{-M}) <K>
+Use single-line command line editing instead of multi-line.
+
+@pindex VI
+@item @t{VI}
+If ZLE is loaded, turning on this option has the equivalent effect
+of `@t{bindkey -v}'.  In addition, the EMACS option is unset.
+Turning it off has no effect.  The option setting is
+not guaranteed to reflect the current keymap.  This option is
+provided for compatibility; @t{bindkey} is the recommended interface.
+
+@pindex ZLE
+@cindex editor, enabling
+@cindex enabling the editor
+@item @t{ZLE} (@t{-Z})
+Use the zsh line editor.  Set by default in interactive shells connected to
+a terminal.
+
+@end table
+
+@noindent
+@node Option Aliases, Single Letter Options, Description of Options, Options
+
+@section Option Aliases
+@noindent
+@cindex options, aliases
+Some options have alternative names.  These aliases are never used for
+output, but can be used just like normal option names when specifying
+options to the shell.
+
+@noindent
+@table @asis
+@pindex BRACE_EXPAND
+@item @t{BRACE_EXPAND}
+@emph{NO_}@t{IGNORE_BRACES}
+(ksh and bash compatibility)
+
+@pindex DOT_GLOB
+@item @t{DOT_GLOB}
+@t{GLOB_DOTS}
+(bash compatibility)
+
+@pindex HASH_ALL
+@item @t{HASH_ALL}
+@t{HASH_CMDS}
+(bash compatibility)
+
+@pindex HIST_APPEND
+@item @t{HIST_APPEND}
+@t{APPEND_HISTORY}
+(bash compatibility)
+
+@pindex HIST_EXPAND
+@item @t{HIST_EXPAND}
+@t{BANG_HIST}
+(bash compatibility)
+
+@pindex LOG
+@item @t{LOG}
+@emph{NO_}@t{HIST_NO_FUNCTIONS}
+(ksh compatibility)
+
+@pindex MAIL_WARN
+@item @t{MAIL_WARN}
+@t{MAIL_WARNING}
+(bash compatibility)
+
+@pindex ONE_CMD
+@item @t{ONE_CMD}
+@t{SINGLE_COMMAND}
+(bash compatibility)
+
+@pindex PHYSICAL
+@item @t{PHYSICAL}
+@t{CHASE_LINKS}
+(ksh and bash compatibility)
+
+@pindex PROMPT_VARS
+@item @t{PROMPT_VARS}
+@t{PROMPT_SUBST}
+(bash compatibility)
+
+@pindex STDIN
+@item @t{STDIN}
+@t{SHIN_STDIN}
+(ksh compatibility)
+
+@pindex TRACK_ALL
+@item @t{TRACK_ALL}
+@t{HASH_CMDS}
+(ksh compatibility)
+
+@end table
+@node Single Letter Options, , Option Aliases, Options
+
+@section Single Letter Options
+@noindent
+@cindex options, single letter
+@cindex single letter options
+
+@subsection Default set
+@noindent
+@table @asis
+@item @t{-0}
+CORRECT
+@item @t{-1}
+PRINT_EXIT_VALUE
+@item @t{-2}
+@emph{NO_}BAD_PATTERN
+@item @t{-3}
+@emph{NO_}NOMATCH
+@item @t{-4}
+GLOB_DOTS
+@item @t{-5}
+NOTIFY
+@item @t{-6}
+BG_NICE
+@item @t{-7}
+IGNORE_EOF
+@item @t{-8}
+MARK_DIRS
+@item @t{-9}
+AUTO_LIST
+@item @t{-B}
+@emph{NO_}BEEP
+@item @t{-C}
+@emph{NO_}CLOBBER
+@item @t{-D}
+PUSHD_TO_HOME
+@item @t{-E}
+PUSHD_SILENT
+@item @t{-F}
+@emph{NO_}GLOB
+@item @t{-G}
+NULL_GLOB
+@item @t{-H}
+RM_STAR_SILENT
+@item @t{-I}
+IGNORE_BRACES
+@item @t{-J}
+AUTO_CD
+@item @t{-K}
+@emph{NO_}BANG_HIST
+@item @t{-L}
+SUN_KEYBOARD_HACK
+@item @t{-M}
+SINGLE_LINE_ZLE
+@item @t{-N}
+AUTO_PUSHD
+@item @t{-O}
+CORRECT_ALL
+@item @t{-P}
+RC_EXPAND_PARAM
+@item @t{-Q}
+PATH_DIRS
+@item @t{-R}
+LONG_LIST_JOBS
+@item @t{-S}
+REC_EXACT
+@item @t{-T}
+CDABLE_VARS
+@item @t{-U}
+MAIL_WARNING
+@item @t{-V}
+@emph{NO_}PROMPT_CR
+@item @t{-W}
+AUTO_RESUME
+@item @t{-X}
+LIST_TYPES
+@item @t{-Y}
+MENU_COMPLETE
+@item @t{-Z}
+ZLE
+@item @t{-a}
+ALL_EXPORT
+@item @t{-e}
+ERR_EXIT
+@item @t{-f}
+@emph{NO_}RCS
+@item @t{-g}
+HIST_IGNORE_SPACE
+@item @t{-h}
+HIST_IGNORE_DUPS
+@item @t{-i}
+INTERACTIVE
+@item @t{-k}
+INTERACTIVE_COMMENTS
+@item @t{-l}
+LOGIN
+@item @t{-m}
+MONITOR
+@item @t{-n}
+@emph{NO_}EXEC
+@item @t{-p}
+PRIVILEGED
+@item @t{-r}
+RESTRICTED
+@item @t{-s}
+SHIN_STDIN
+@item @t{-t}
+SINGLE_COMMAND
+@item @t{-u}
+@emph{NO_}UNSET
+@item @t{-v}
+VERBOSE
+@item @t{-w}
+CHASE_LINKS
+@item @t{-x}
+XTRACE
+@item @t{-y}
+SH_WORD_SPLIT
+@end table
+
+@subsection sh/ksh emulation set
+@noindent
+@table @asis
+@item @t{-C}
+@emph{NO_}CLOBBER
+@item @t{-T}
+TRAPS_ASYNC
+@item @t{-X}
+MARK_DIRS
+@item @t{-a}
+ALL_EXPORT
+@item @t{-b}
+NOTIFY
+@item @t{-e}
+ERR_EXIT
+@item @t{-f}
+@emph{NO_}GLOB
+@item @t{-i}
+INTERACTIVE
+@item @t{-l}
+LOGIN
+@item @t{-m}
+MONITOR
+@item @t{-n}
+@emph{NO_}EXEC
+@item @t{-p}
+PRIVILEGED
+@item @t{-r}
+RESTRICTED
+@item @t{-s}
+SHIN_STDIN
+@item @t{-t}
+SINGLE_COMMAND
+@item @t{-u}
+@emph{NO_}UNSET
+@item @t{-v}
+VERBOSE
+@item @t{-x}
+XTRACE
+@end table
+
+@subsection Also note
+@noindent
+@table @asis
+@item @t{-A}
+Used by @t{set} for setting arrays
+@item @t{-b}
+Used on the command line to specify end of option processing
+@item @t{-c}
+Used on the command line to specify a single command
+@item @t{-m}
+Used by @t{setopt} for pattern-matching option setting
+@item @t{-o}
+Used in all places to allow use of long option names
+@item @t{-s}
+Used by @t{set} to sort positional parameters
+@end table
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/builtins.yo
+@node Shell Builtin Commands, Zsh Line Editor, Options, Top
+
+@chapter Shell Builtin Commands
+@noindent
+@cindex builtin commands
+@cindex commands, builtin
+@table @asis
+@findex -
+@item @t{-} @var{simple command}
+See @ref{Precommand Modifiers}.
+
+@findex .
+@item @t{.} @var{file} [ @var{arg} ... ]
+Read commands from @var{file} and execute them in the current shell
+environment.
+
+@noindent
+If @var{file} does not contain a slash, or if @t{PATH_DIRS} is set,
+the shell looks in the components of @t{$path} to find the directory
+containing @var{file}.  Files in the current directory are not read
+unless `@t{.}' appears somewhere in @t{$path}.  If a file named
+`@var{file}@t{.zwc}' is found, is newer than @var{file}, and is the
+compiled form (created with the @t{zcompile} builtin) of @var{file},
+then commands are read from that file instead of @var{file}.
+
+@noindent
+If any arguments @var{arg} are given,
+they become the positional parameters; the old positional
+parameters are restored when the @var{file} is done executing.
+The exit status is the exit status of the last command executed.
+
+@findex :
+@cindex expanding parameters
+@cindex parameters, expanding
+@cindex doing nothing
+@item @t{:} [ @var{arg} ... ]
+This command does nothing, although normal argument expansions is performed
+which may have effects on shell parameters.  A zero exit code is returned.
+
+@findex alias
+@cindex aliases, defining
+@cindex aliases, listing
+@item @t{alias} [ @{@t{+|@t{-}}@}@t{gmrsL} ] [ @var{name}[@t{=}@var{value}] ... ]
+For each @var{name} with a corresponding @var{value}, define an alias
+with that value.  A trailing space in @var{value} causes the next word
+to be checked for alias expansion.  If the @t{-g} flag is present,
+define a global alias; global aliases are expanded even if they do not
+occur in command position.
+
+@noindent
+If the @t{-s} flags is present, define a suffix alias: if the command
+word on a command line is in the form `@var{text}@t{.}@var{name}', where
+@var{text} is any non-empty string, it is replaced by the text
+`@var{value} @var{text}@t{.}@var{name}'.  Note that @var{name} is treated as
+a literal string, not a pattern.  A trailing space in @var{value} is not
+special in this case.  For example,
+
+@noindent
+@example
+alias -s ps=gv
+@end example
+
+@noindent
+will cause the command `@t{*.ps}' to be expanded to `@t{gv *.ps}'.  As
+alias expansion is carried out earlier than globbing, the `@t{*.ps}' will
+then be expanded.  Suffix aliases constitute a different name space from
+other aliases (so in the above example it is still possible
+to create an alias for the command @t{ps}) and the two sets are never
+listed together.
+
+@noindent
+For each @var{name} with no @var{value},
+print the value of @var{name}, if any.  With no arguments, print all
+currently defined aliases other than suffix aliases.  If the @t{-m} flag
+is given the arguments are taken as patterns (they should be quoted to
+preserve them from being interpreted as glob patterns), and the aliases
+matching these patterns are printed.  When printing aliases and one of
+the @t{-g}, @t{-r} or @t{-s} flags is present, restrict the printing to
+global, regular or suffix aliases, respectively; a regular alias is one
+which is neither a global nor a suffix alias.   Using `@t{+}'
+instead of `@t{-}', or ending the option list with a single
+`@t{+}', prevents the values of the aliases from being printed.
+
+@noindent
+If the @t{-L} flag is present, then print each
+alias in a manner suitable for putting in a startup script.  The exit
+status is nonzero if a @var{name} (with no @var{value}) is given for
+which no alias has been defined.
+
+@findex autoload
+@cindex functions, autoloading
+@cindex autoloading functions
+@item @t{autoload} [ @{@t{+}|@t{-}@}@t{UXktz} ] [ @t{-w} ] [ @var{name} ... ]
+Equivalent to @t{functions -u}, with the exception of @t{-X}/@t{+X} and
+@t{-w}.
+
+@noindent
+The flag @t{-X} may be used only inside a shell function, and may not be
+followed by a @var{name}.  It causes the calling function to be marked for
+autoloading and then immediately loaded and executed, with the current
+array of positional parameters as arguments.  This replaces the previous
+definition of the function.  If no function definition is found, an error
+is printed and the function remains undefined and marked for autoloading.
+
+@noindent
+The flag @t{+X} attempts to load each @var{name} as an autoloaded function,
+but does @emph{not} execute it.  The exit status is zero (success) if the
+function was not previously defined @emph{and} a definition for it was found.
+This does @emph{not} replace any existing definition of the function.  The
+exit status is nonzero (failure) if the function was already defined or
+when no definition was found.  In the latter case the function remains
+undefined and marked for autoloading.  If ksh-style autoloading is
+enabled, the function created will contain the contents of the file
+plus a call to the function itself appended to it, thus giving normal
+ksh autoloading behaviour on the first call to the function.
+
+@noindent
+With the @t{-w} flag, the @var{name}s are taken as names of files compiled
+with the @t{zcompile} builtin, and all functions defined in them are
+marked for autoloading.
+
+@findex bg
+@cindex jobs, backgrounding
+@item @t{bg} [ @var{job} ... ]
+@itemx @var{job} ... @t{&}
+Put each specified @var{job} in the background,
+or the current job if none is specified.
+
+@item @t{bindkey}
+See @ref{Zle Builtins}.
+
+@findex break
+@cindex exiting loops
+@cindex loops, exiting
+@item @t{break} [ @var{n} ]
+Exit from an enclosing @t{for}, @t{while},
+@t{until}, @t{select} or @t{repeat} loop.  If @var{n}
+is specified, then break @var{n} levels instead of just one.
+
+@findex builtin
+@item @t{builtin} @var{name} [ @var{args} ... ]
+Executes the builtin @var{name}, with the given @var{args}.
+
+@findex bye
+@item @t{bye}
+Same as @t{exit}.
+
+@item @t{cap}
+See @ref{The zsh/cap Module}.
+
+@findex cd
+@cindex directories, changing
+@item @t{cd} [ @t{-sLP} ] [ @var{arg} ]
+@itemx @t{cd} [ @t{-sLP} ] @var{old} @var{new}
+@itemx @t{cd} [ @t{-sLP} ] @{@t{+}|@t{-}@}@var{n}
+Change the current directory.  In the first form, change the
+current directory to @var{arg}, or to the value of @t{$HOME} if
+@var{arg} is not specified.  If @var{arg} is `@t{-}', change to the
+value of @t{$OLDPWD}, the previous directory.
+Otherwise, if a directory named @var{arg} is not found in the current
+directory and @var{arg} does not begin with a slash, search each
+component of the shell parameter @t{cdpath}.  If no directory is found
+and the option @t{CDABLE_VARS} is set, and a parameter named @var{arg}
+exists whose value begins with a slash, treat its value as the
+directory.  In that case, the parameter is added to the named
+directory hash table.
+
+@noindent
+The second form of @t{cd} substitutes the string @var{new}
+for the string @var{old} in the name of the current directory,
+and tries to change to this new directory.
+
+@noindent
+The third form of @t{cd} extracts an entry from the directory
+stack, and changes to that directory.  An argument of the form
+`@t{+}@var{n}' identifies a stack entry by counting from the left
+of the list shown by the @t{dirs} command, starting with zero.
+An argument of the form `@t{-}@var{n}' counts from the right.
+If the @t{PUSHD_MINUS} option is set, the meanings of `@t{+}'
+and `@t{-}' in this context are swapped.
+
+@noindent
+If the @t{-s} option is specified, @t{cd} refuses to change the current
+directory if the given pathname contains symlinks.  If the @t{-P} option
+is given or the @t{CHASE_LINKS} option is set, symbolic links are resolved
+to their true values.  If the @t{-L} option is given symbolic links are
+followed regardless of the state of the @t{CHASE_LINKS} option.
+
+@findex chdir
+@item @t{chdir}
+Same as @t{cd}.
+
+@item @t{clone}
+See @ref{The zsh/clone Module}.
+
+@findex command
+@item @t{command} [ @t{-pvV} ] @var{simple command}
+The simple command argument is taken as an external command instead of
+a function or builtin and is executed. If the @t{POSIX_BUILTINS} option
+is set, builtins will also be executed but certain special properties
+of them are suppressed. The @t{-p} flag causes a default path to be
+searched instead of that in @t{$path}. With the @t{-v} flag, @t{command}
+is similar to @t{whence} and with @t{-V}, it is equivalent to @t{whence
+-v}.
+
+@noindent
+See also @ref{Precommand Modifiers}.
+
+@item @t{comparguments}
+See @ref{The zsh/computil Module}.
+
+@item @t{compcall}
+See @ref{The zsh/compctl Module}.
+
+@item @t{compctl}
+See @ref{The zsh/compctl Module}.
+
+@item @t{compdescribe}
+See @ref{The zsh/computil Module}.
+
+@item @t{compfiles}
+See @ref{The zsh/computil Module}.
+
+@item @t{compgroups}
+See @ref{The zsh/computil Module}.
+
+@item @t{compquote}
+See @ref{The zsh/computil Module}.
+
+@item @t{comptags}
+See @ref{The zsh/computil Module}.
+
+@item @t{comptry}
+See @ref{The zsh/computil Module}.
+
+@item @t{compvalues}
+See @ref{The zsh/computil Module}.
+
+@findex continue
+@cindex loops, continuing
+@cindex continuing loops
+@item @t{continue} [ @var{n} ]
+Resume the next iteration of the enclosing
+@t{for}, @t{while}, @t{until}, @t{select} or
+@t{repeat} loop.  If @var{n} is specified, break out of
+@var{n}-1 loops and resume at the @var{n}th enclosing loop.
+
+@findex declare
+@item @t{declare}
+Same as @t{typeset}.
+
+@findex dirs
+@cindex directory stack, printing
+@item @t{dirs} [ @t{-c} ] [ @var{arg} ... ]
+@itemx @t{dirs} [ @t{-lpv} ]
+With no arguments, print the contents of the directory stack.
+Directories are added to this stack with the @t{pushd} command,
+and removed with the @t{cd} or @t{popd} commands.
+If arguments are specified, load them onto the directory stack,
+replacing anything that was there, and push the current directory
+onto the stack.
+
+@noindent
+@table @asis
+@item @t{-c}
+clear the directory stack.
+
+@item @t{-l}
+print directory names in full instead of using of using @t{~} expressions.
+
+@item @t{-p}
+print directory entries one per line.
+
+@item @t{-v}
+number the directories in the stack when printing.
+
+@end table
+
+@noindent
+
+@findex disable
+@cindex disabling commands
+@cindex commands, disabling
+@item @t{disable} [ @t{-afmrs} ] @var{name} ...
+Temporarily disable the @var{name}d hash table elements.  The default
+is to disable builtin commands.  This allows you to use an external
+command with the same name as a builtin command.  The @t{-a} option
+causes @t{disable} to act on regular or global aliases.  The @t{-s}
+option causes @t{disable} to act on suffix aliases.  The @t{-f} option causes
+@t{disable} to act on shell functions.  The @t{-r} options causes
+@t{disable} to act on reserved words.  Without arguments all disabled
+hash table elements from the corresponding hash table are printed.
+With the @t{-m} flag the arguments are taken as patterns (which should be
+quoted to prevent them from undergoing filename expansion), and all hash
+table elements from the corresponding hash table matching these patterns
+are disabled.  Disabled objects can be enabled with the @t{enable}
+command.
+
+@findex disown
+@cindex jobs, disowning
+@item @t{disown} [ @var{job} ... ]
+@itemx @var{job} ... @t{&|}
+@itemx @var{job} ... @t{&!}
+Remove the specified @var{job}s from the job table; the shell will
+no longer report their status, and will not complain if you
+try to exit an interactive shell with them running or stopped.
+If no @var{job} is specified, disown the current job.
+
+@noindent
+If the @var{job}s are currently stopped and the @t{AUTO_CONTINUE} option
+is not set, a warning is printed containing information about how to
+make them running after they have been disowned.  If one of the latter
+two forms is used, the @var{job}s will automatically be made running,
+independent of the setting of the @t{AUTO_CONTINUE} option.
+
+@findex echo
+@item @t{echo} [ @t{-neE} ] [ @var{arg} ... ]
+Write each @var{arg} on the standard output, with a space separating
+each one.
+If the @t{-n} flag is not present, print a newline at the end.
+@t{echo} recognizes the following escape sequences:
+
+@noindent
+@table @asis
+@item @t{\a}
+bell character
+@item @t{\b}
+backspace
+@item @t{\c}
+suppress final newline
+@item @t{\e}
+escape
+@item @t{\f}
+form feed
+@item @t{\n}
+linefeed (newline)
+@item @t{\r}
+carriage return
+@item @t{\t}
+horizontal tab
+@item @t{\v}
+vertical tab
+@item @t{\\}
+backslash
+@item @t{\0}@var{NNN}
+character code in octal
+@item @t{\x}@var{NN}
+character code in hexadecimal
+@item @t{\u}@var{NNNN}
+unicode character code in hexadecimal
+@item @t{\U}@var{NNNNNNNN}
+unicode character code in hexadecimal
+@end table
+
+@noindent
+@pindex BSD_ECHO, use of
+The @t{-E} flag, or the @t{BSD_ECHO} option, can be used to disable
+these escape sequences.  In the latter case, @t{-e} flag can be used to
+enable them.
+
+@item @t{echotc}
+See @ref{The zsh/termcap Module}.
+
+@item @t{echoti}
+See @ref{The zsh/terminfo Module}.
+
+@findex emulate
+@cindex compatibility, sh
+@cindex compatibility, ksh
+@cindex compatibility, csh
+@cindex sh, compatibility
+@cindex ksh, compatibility
+@cindex csh, compatibility
+@item @t{emulate} [ @t{-LR} ] @{@t{zsh}|@t{sh}|@t{ksh}|@t{csh}@}
+Set up zsh options to emulate the specified shell as much as possible.
+@cite{csh} will never be fully emulated.
+If the argument is not one of the shells listed above, @t{zsh}
+will be used as a default; more precisely, the tests performed on the
+argument are the same as those used to determine the emulation at startup
+based on the shell name, see
+@ref{Compatibility}
+.  If the @t{-R} option is given, all options
+are reset to their default value corresponding to the specified emulation
+mode, except for certain options describing the interactive
+environment; otherwise, only those options likely to cause portability
+problems in scripts and functions are altered.  If the @t{-L} option
+is given, the options @t{LOCAL_OPTIONS} and @t{LOCAL_TRAPS} will be set as
+well, causing the effects of the @t{emulate} command and any @t{setopt} and
+@t{trap} commands to be local to the immediately surrounding shell
+function, if any; normally these options are turned off in all emulation
+modes except @t{ksh}.
+
+@findex enable
+@cindex enabling commands
+@cindex commands, enabling
+@item @t{enable} [ @t{-afmrs} ] @var{name} ...
+Enable the @var{name}d hash table elements, presumably disabled
+earlier with @t{disable}.  The default is to enable builtin commands.
+The @t{-a} option causes @t{enable} to act on regular or global aliases.
+The @t{-s} option causes @t{enable} to act on suffix aliases.
+The @t{-f} option causes @t{enable} to act on shell functions.  The @t{-r}
+option causes @t{enable} to act on reserved words.  Without arguments
+all enabled hash table elements from the corresponding hash table are
+printed.  With the @t{-m} flag the arguments are taken as patterns
+(should be quoted) and all hash table elements from the corresponding
+hash table matching these patterns are enabled.  Enabled objects can be
+disabled with the @t{disable} builtin command.
+
+@findex eval
+@cindex evaluating arguments as commands
+@item @t{eval} [ @var{arg} ... ]
+Read the arguments as input to the shell and execute the resulting
+command in the current shell process.
+
+@findex exec
+@item @t{exec} @var{simple command}
+See @ref{Precommand Modifiers}.
+
+@findex exit
+@item @t{exit} [ @var{n} ]
+Exit the shell with the exit code specified by @var{n}; if none
+is specified, use the exit code from the last command executed.
+@pindex IGNORE_EOF, use of
+An EOF condition will also cause the shell to exit, unless
+the @t{IGNORE_EOF} option is set.
+
+@findex export
+@item @t{export} [ @var{name}[@t{=}@var{value}] ... ]
+The specified @var{name}s are marked for automatic export
+to the environment of subsequently executed commands.
+Equivalent to @t{typeset -gx}.
+If a parameter specified does not
+already exist, it is created in the global scope.
+
+@findex false
+@cindex doing nothing, unsuccessfully
+@item @t{false} [ @var{arg} ... ]
+Do nothing and return an exit code of 1.
+
+@findex fc
+@cindex history, editing
+@cindex editing history
+@item @t{fc} [ @t{-e} @var{ename} ] [ @t{-nlrdDfEim} ] [ @var{old}@t{=}@var{new} ... ] [ @var{first} [ @var{last} ] ]
+@itemx @t{fc} @t{-p} [ @t{-a} ] [ @var{filename} [ @var{histsize} [ @var{savehistsize} ] ] ]
+@itemx @t{fc} @t{-P}
+@itemx @t{fc} @t{-ARWI} [ @var{filename} ]
+Select a range of commands from @var{first} to @var{last} from the
+history list.
+The arguments @var{first} and @var{last} may be specified as a
+number or as a string.  A negative number is used as an offset
+to the current history event number.
+A string specifies the most recent event beginning with the given string.
+All substitutions @var{old}@t{=}@var{new}, if any, are then performed
+on the commands.
+
+@noindent
+If the @t{-l} flag is given, the resulting commands are listed on
+standard output.
+If the @t{-m} flag is also given the first argument is taken as a
+pattern (should be quoted) and only the history events matching this
+pattern will be shown.
+Otherwise the editor program @var{ename} is invoked on a file containing
+these history events.  If @var{ename} is not given, the value
+of the parameter @t{FCEDIT} is used.  If @var{ename} is `@t{-}',
+no editor is invoked.  When editing is complete, the edited
+command is executed.
+
+@noindent
+If @var{first} is not specified, it will be set to -1 (the most recent
+event), or to -16 if the @t{-l} flag is given.
+If @var{last} is not specified, it will be set to @var{first},
+or to -1 if the @t{-l} flag is given.
+
+@noindent
+The flag @t{-r} reverses the order of the commands and the
+flag @t{-n} suppresses command numbers when listing.
+Also when listing, @t{-d} prints timestamps for each command, and
+@t{-f} prints full time-date stamps.  Adding the @t{-E} flag
+causes the dates to be printed as `@var{dd}@t{.}@var{mm}@t{.}@var{yyyy}',
+instead of the default `@var{mm}@t{/}@var{dd}@t{/}@var{yyyy}'.
+Adding the @t{-i} flag causes the dates to be printed in ISO8601
+`@var{yyyy}@t{-}@var{mm}@t{-}@var{dd}' format.
+With the @t{-D} flag, @t{fc} prints elapsed times.
+
+@noindent
+@cindex history, stack
+@cindex stack, history
+
+@noindent
+`@t{fc -p}' pushes the current history list onto a stack and switches to a
+new history list.  If the @t{-a} option is also specified, this history list
+will be automatically popped when the current function scope is exited, which
+is a much better solution than creating a trap function to call `@t{fc -P}'
+manually.  If no arguments are specified, the history list is left empty,
+@t{$HISTFILE} is unset, and @t{$HISTSIZE} & @t{$SAVEHIST} are set to their
+default values.  If one argument is given, @t{$HISTFILE} is set to that
+filename, @t{$HISTSIZE} & @t{$SAVEHIST} are left unchanged, and the history
+file is read in (if it exists) to initialize the new list.  If a second
+argument is specified, @t{$HISTSIZE} & @t{$SAVEHIST} are instead set to the
+single specified numeric value.  Finally, if a third argument is specified,
+@t{$SAVEHIST} is set to a separate value from @t{$HISTSIZE}.  You are free to
+change these environment values for the new history list however you desire
+in order to manipulate the new history list.
+
+@noindent
+`@t{fc -P}' pops the history list back to an older list saved by `@t{fc -p}'.
+The current list is saved to its @t{$HISTFILE} before it is destroyed
+(assuming that @t{$HISTFILE} and @t{$SAVEHIST} are set appropriately, of
+course).  The values of @t{$HISTFILE}, @t{$HISTSIZE}, and @t{$SAVEHIST} are
+restored to the values they had when `@t{fc -p}' was called.  Note that this
+restoration can conflict with making these variables "local", so your best
+bet is to avoid local declarations for these variables in functions that use
+`@t{fc -p}'.  The one other guaranteed-safe combination is declaring these
+variables to be local at the top of your function and using the automatic
+option (@t{-a}) with `@t{fc -p}'.  Finally, note that it is legal to manually
+pop a push marked for automatic popping if you need to do so before the
+function exits.
+
+@noindent
+@cindex history, file
+@cindex file, history
+`@t{fc -R}' reads the history from the given file,
+`@t{fc -W}' writes the history out to the given file,
+and `@t{fc -A}' appends the history out to the given file.
+If no filename is specified, the @t{$HISTFILE} is assumed.
+If the @t{-I} option is added to @t{-R}, only those events that are
+not already contained within the internal history list are added.
+If the @t{-I} option is added to @t{-A} or @t{-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 @t{$SAVEHIST}
+entries.
+
+@findex fg
+@cindex jobs, foregrounding
+@cindex jobs, resuming
+@item @t{fg} [ @var{job} ... ]
+@itemx @var{job} ...
+Bring each specified @var{job} in turn to the foreground.
+If no @var{job} is specified, resume the current job.
+
+@findex float
+@item @t{float} [ @{@t{+}|@t{-}@}@t{EFHghlprtux} ] [ @var{name}[@t{=}@var{value}] ... ]
+Equivalent to @t{typeset -E}, except that options irrelevant to floating
+point numbers are not permitted.
+
+@findex functions
+@item @t{functions} [ @{@t{+}|@t{-}@}@t{UXkmtuz} ] [ @var{name} ... ]
+Equivalent to @t{typeset -f}.
+
+@item @t{getcap}
+See @ref{The zsh/cap Module}.
+
+@findex getln
+@cindex line, reading
+@cindex reading a line
+@item @t{getln} [ @t{-AclneE} ] @var{name} ...
+Read the top value from the buffer stack and put it in
+the shell parameter @t{name}.  Equivalent to
+@t{read -zr}.
+
+@findex getopts
+@cindex options, processing
+@item @t{getopts} @var{optstring} @var{name} [ @var{arg} ... ]
+Checks the @var{arg}s for legal options.  If the @var{arg}s are omitted,
+use the positional parameters.  A valid option argument
+begins with a `@t{+}' or a `@t{-}'.  An argument not beginning with
+a `@t{+}' or a `@t{-}', or the argument `@t{--}', ends the options.
+Note that a single `@t{-}' is not considered a valid option argument.
+@var{optstring} contains the letters that @t{getopts}
+recognizes.  If a letter is followed by a `@t{:}', that option
+is expected to have an argument.  The options can be
+separated from the argument by blanks.
+
+@noindent
+Each time it is invoked, @t{getopts} places the option letter it finds
+in the shell parameter @var{name}, prepended with a `@t{+}' when
+@var{arg} begins with a `@t{+}'.  The index of the next @var{arg}
+is stored in @t{OPTIND}.  The option argument, if any,
+is stored in @t{OPTARG}.
+@vindex OPTIND, use of
+@vindex OPTARG, use of
+
+@noindent
+The first option to be examined may be changed by explicitly assigning
+to @t{OPTIND}.  @t{OPTIND} has an initial value of @t{1}, and is
+normally reset to @t{1} upon exit from a shell function.  @t{OPTARG}
+is not reset and retains its value from the most recent call to
+@t{getopts}.  If either of @t{OPTIND} or @t{OPTARG} is explicitly
+unset, it remains unset, and the index or option argument is not
+stored.  The option itself is still stored in @var{name} in this case.
+
+@noindent
+A leading `@t{:}' in @var{optstring} causes @t{getopts} to store the
+letter of any invalid option in @t{OPTARG}, and to set @var{name} to
+`@t{?}' for an unknown option and to `@t{:}' when a required option is
+missing.  Otherwise, @t{getopts} sets @var{name} to `@t{?}' and prints
+an error message when an option is invalid.  The exit status is
+nonzero when there are no more options.
+
+@findex hash
+@item @t{hash} [ @t{-Ldfmrv} ] [ @var{name}[@t{=}@var{value}] ] ...
+@t{hash} can be used to directly modify the contents of the command
+hash table, and the named directory hash table.  Normally one would
+modify these tables by modifying one's @t{PATH}
+(for the command hash table) or by creating appropriate shell parameters
+(for the named directory hash table).
+The choice of hash table to work on is determined by the @t{-d} option;
+without the option the command hash table is used, and with the option the
+named directory hash table is used.
+
+@noindent
+Given no arguments, and neither the @t{-r} or @t{-f} options,
+the selected hash table will be listed in full.
+
+@noindent
+The @t{-r} option causes the selected hash table to be emptied.
+It will be subsequently rebuilt in the normal fashion.
+The @t{-f} option causes the selected hash table to be fully
+rebuilt immediately.  For the command hash table this hashes
+all the absolute directories in the @t{PATH},
+and for the named directory hash table this adds all users' home directories.
+These two options cannot be used with any arguments.
+
+@noindent
+The @t{-m} option causes the arguments to be taken as patterns
+(which should be quoted) and the elements of the hash table
+matching those patterns are printed.  This is the only way to display
+a limited selection of hash table elements.
+
+@noindent
+For each @var{name} with a corresponding @var{value}, put `@var{name}' in
+the selected hash table, associating it with the pathname `@var{value}'.
+In the command hash table, this means that
+whenever `@var{name}' is used as a command argument, the shell will try
+to execute the file given by `@var{value}'.
+In the named directory hash table, this means
+that `@var{value}' may be referred to as `@t{~}@var{name}'.
+
+@noindent
+For each @var{name} with no
+corresponding @var{value}, attempt to add @var{name} to the hash table,
+checking what the appropriate @t{value} is in the normal manner for
+that hash table.  If an appropriate @t{value} can't be found, then
+the hash table will be unchanged.
+
+@noindent
+The @t{-v} option causes hash table entries to be listed as they are
+added by explicit specification.  If has no effect if used with @t{-f}.
+
+@noindent
+If the @t{-L} flag is present, then each hash table entry is printed in
+the form of a call to hash.
+
+@findex history
+@item @t{history}
+Same as @t{fc -l}.
+
+@findex integer
+@item @t{integer} [ @{@t{+}|@t{-}@}@t{Hghilprtux} ] [ @var{name}[@t{=}@var{value}] ... ]
+Equivalent to @t{typeset -i}, except that options irrelevant to
+integers are not permitted.
+
+@findex jobs
+@item @t{jobs} [ @t{-dlprs} ] [ @var{job} ... ]
+@itemx @t{jobs -Z} @var{string}
+Lists information about each given job, or all jobs
+if @var{job} is omitted.  The @t{-l} flag lists process
+IDs, and the @t{-p} flag lists process groups.
+If the @t{-r} flag is specified only running jobs will be listed
+and if the @t{-s} flag is given only stopped jobs are shown.
+If the @t{-d} flag is given, the directory from which the job was
+started (which may not be the current directory of the job) will also
+be shown.
+
+@noindent
+The @t{-Z} option replaces the shell's argument and environment space with
+the given string, truncated if necessary to fit.  This will normally be
+visible in @t{ps} (man page ps(1)) listings.  This feature is typically
+used by daemons, to indicate their state.
+
+@findex kill
+@cindex killing jobs
+@cindex jobs, killing
+@item @t{kill} [ @t{-s} @var{signal_name} | @t{-n} @var{signal_number} | @t{-}@var{sig} ] @var{job} ...
+@itemx @t{kill} @t{-l} [ @var{sig} ... ]
+Sends either @t{SIGTERM} or the specified signal to the given
+jobs or processes.
+Signals are given by number or by names, with or without the `@t{SIG}'
+prefix.
+If the signal being sent is not `@t{KILL}' or `@t{CONT}', then the job
+will be sent a `@t{CONT}' signal if it is stopped.
+The argument @var{job} can be the process ID of a job
+not in the job list.
+In the second form, @t{kill -l}, if @var{sig} is not
+specified the signal names are listed.  Otherwise, for each
+@var{sig} that is a name, the corresponding signal number is
+listed.  For each @var{sig} that is a signal number or a number
+representing the exit status of a process which was terminated or
+stopped by a signal the name of the signal is printed.
+
+@findex let
+@item @t{let} @var{arg} ...
+Evaluate each @var{arg} as an arithmetic expression.
+See @ref{Arithmetic Evaluation} for a description
+of arithmetic expressions.  The exit status is 0 if the
+value of the last expression is nonzero, and 1 otherwise.
+
+@findex limit
+@cindex resource limits
+@cindex limits, resource
+@item @t{limit} [ @t{-hs} ] [ @var{resource} [ @var{limit} ] ] ...
+Set or display resource limits.  Unless the @t{-s} flag is given,
+the limit applies only the children of the shell.  If @t{-s} is
+given without other arguments, the resource limits of the current
+shell is set to the previously set resource limits of the children.
+
+@noindent
+If @var{limit} is not specified, print the current limit placed
+on @var{resource}, otherwise
+set the limit to the specified value.  If the @t{-h} flag
+is given, use hard limits instead of soft limits.
+If no @var{resource} is given, print all limits.
+
+@noindent
+When looping over multiple resources, the shell will abort immediately if
+it detects a badly formed argument.  However, if it fails to set a limit
+for some other reason it will continue trying to set the remaining limits.
+
+@noindent
+@var{resource} can be one of:
+
+@noindent
+@table @asis
+@item @t{addressspace}
+Maximum amount of address space used.
+@item @t{aiomemorylocked}
+Maximum amount of memory locked in RAM for AIO operations.
+@item @t{aiooperations}
+Maximum number of AIO operations.
+@item @t{cachedthreads}
+Maximum number of cached threads.
+@item @t{coredumpsize}
+Maximum size of a core dump.
+@item @t{cputime}
+Maximum CPU seconds per process.
+@item @t{datasize}
+Maximum data size (including stack) for each process.
+@item @t{descriptors}
+Maximum value for a file descriptor.
+@item @t{filesize}
+Largest single file allowed.
+@item @t{maxproc}
+Maximum number of processes.
+@item @t{maxpthreads}
+Maximum number of threads per process.
+@item @t{memorylocked}
+Maximum amount of memory locked in RAM.
+@item @t{memoryuse}
+Maximum resident set size.
+@item @t{resident}
+Maximum resident set size.
+@item @t{sockbufsize}
+Maximum size of all socket buffers.
+@item @t{stacksize}
+Maximum stack size for each process.
+@item @t{vmemorysize}
+Maximum amount of virtual memory.
+@end table
+
+@noindent
+Which of these resource limits are available depends on the system.
+@var{resource} can be abbreviated to any unambiguous prefix.  It
+can also be an integer, which corresponds to the integer defined
+for the resource by the operating system.
+
+@noindent
+If argument corresponds to a number which is out of the range of the
+resources configured into the shell, the shell will try to read or write
+the limit anyway, and will report an error if this fails.  As the shell
+does not store such resources internally, an attempt to set the limit will
+fail unless the @t{-s} option is present.
+
+@noindent
+@var{limit} is a number, with an optional scaling factor, as follows:
+
+@noindent
+@table @asis
+@item @var{n}@t{h}
+hours
+@item @var{n}@t{k}
+kilobytes (default)
+@item @var{n}@t{m}
+megabytes or minutes
+@item [@var{mm}@t{:}]@var{ss}
+minutes and seconds
+@end table
+
+@findex local
+@item @t{local} [ @{@t{+}|@t{-}@}@t{AEFHLRUZahilprtux} [@var{n}]] [ @var{name}[@t{=}@var{value}] ] ...
+Same as @t{typeset}, except that the options @t{-g}, and
+@t{-f} are not permitted.  In this case the @t{-x} option does not force
+the use of @t{-g}, i.e. exported variables will be local to functions.
+
+@findex log
+@vindex watch, use of
+@cindex watching users
+@cindex users, watching
+@item @t{log}
+List all users currently logged in who are affected by
+the current setting of the @t{watch} parameter.
+
+@findex logout
+@item @t{logout} [ @var{n} ]
+Same as @t{exit}, except that it only works in a login shell.
+
+@findex noglob
+@item @t{noglob} @var{simple command}
+See @ref{Precommand Modifiers}.
+
+@findex popd
+@item @t{popd} [ @{@t{+}|@t{-}@}@var{n} ]
+Remove an entry from the directory stack, and perform a @t{cd} to
+the new top directory.  With no argument, the current top entry is
+removed.  An argument of the form `@t{+}@var{n}' identifies a stack
+entry by counting from the left of the list shown by the @t{dirs} command,
+starting with zero.  An argument of the form @t{-n} counts from the right.
+@pindex PUSHD_MINUS, use of
+If the @t{PUSHD_MINUS} option is set, the meanings of `@t{+}' and
+`@t{-}' in this context are swapped.
+
+@findex print
+@item @t{print} [ @t{-abcDilmnNoOpPrsz} ] [ @t{-u} @var{n} ] [ @t{-f} @var{format} ] [ @t{-C} @var{cols} ]
+@itemx   [ @t{-R} [ @t{-en} ]] [ @var{arg} ... ]
+With the `@t{-f}' option the arguments are printed as described by @t{printf}.
+With no flags or with the flag `@t{-}', the arguments are printed on
+the standard output as described by @t{echo}, with the following differences:
+the escape sequence `@t{\M-}@var{x}' metafies the character
+@var{x} (sets the highest bit),
+`@t{\C-}@var{x}' produces a control character (`@t{\C-@@}' and `@t{\C-?}' give the
+characters NUL and delete), and `@t{\E}' is a synonym for `@t{\e}'.
+Finally, if not in an escape
+sequence, `@t{\}' escapes the following character and is not printed.
+
+@noindent
+@table @asis
+@item @t{-a}
+Print arguments with the column incrementing first.  Only useful with the
+@t{-c} and @t{-C} options.
+
+@item @t{-b}
+Recognize all the escape sequences defined for the @t{bindkey} command,
+see 
+@ref{Zle Builtins}.
+
+@item @t{-c}
+Print the arguments in columns.  Unless @t{-a} is also given, arguments are
+printed with the row incrementing first.
+
+@item @t{-C} @var{cols}
+Print the arguments in @var{cols} columns.  Unless @t{-a} is also given,
+arguments are printed with the row incrementing first.
+
+@item @t{-D}
+Treat the arguments as directory names, replacing prefixes with @t{~}
+expressions, as appropriate.
+
+@item @t{-i}
+If given together with @t{-o} or @t{-O}, sorting is performed
+case-independently.
+
+@item @t{-l}
+Print the arguments separated by newlines instead of spaces.
+
+@item @t{-m}
+Take the first argument as a pattern (should be quoted), and remove
+it from the argument list together with subsequent arguments that
+do not match this pattern.
+
+@item @t{-n}
+Do not add a newline to the output.
+
+@item @t{-N}
+Print the arguments separated and terminated by nulls.
+
+@item @t{-o}
+Print the arguments sorted in ascending order.
+
+@item @t{-O}
+Print the arguments sorted in descending order.
+
+@item @t{-p}
+Print the arguments to the input of the coprocess.
+
+@item @t{-P}
+Perform prompt expansion (see
+@ref{Prompt Expansion}).
+
+@item @t{-r}
+Ignore the escape conventions of @t{echo}.
+
+@item @t{-R}
+Emulate the BSD @t{echo} command, which does not process escape sequences
+unless the @t{-e} flag is given.  The @t{-n} flag suppresses the trailing
+newline.  Only the @t{-e} and @t{-n} flags are recognized after
+@t{-R}; all other arguments and options are printed.
+
+@item @t{-s}
+Place the results in the history list instead of on the standard output.
+
+@item @t{-u} @var{n}
+Print the arguments to file descriptor @var{n}.
+
+@item @t{-z}
+Push the arguments onto the editing buffer stack, separated by spaces.
+
+@end table
+
+@noindent
+If any of `@t{-m}', `@t{-o}' or `@t{-O}' are used in combination with
+`@t{-f}' and there are no arguments (after the removal process in the
+case of `@t{-m}') then nothing is printed.
+
+@findex printf
+@item @t{printf} @var{format} [ @var{arg} ... ]
+Print the arguments according to the format specification. Formatting
+rules are the same as used in C. The same escape sequences as for @t{echo}
+are recognised in the format. All C conversion specifications ending in
+one of csdiouxXeEfgGn are handled. In addition to this, `@t{%b}' can be
+used instead of `@t{%s}' to cause escape sequences in the argument to be
+recognised and `@t{%q}' can be used to quote the argument in such a way
+that allows it to be reused as shell input. With the numeric format
+specifiers, if the corresponding argument starts with a quote character,
+the numeric value of the following character is used as the number to
+print otherwise the argument is evaluated as an arithmetic expression. See
+@ref{Arithmetic Evaluation} for a description of arithmetic
+expressions. With `@t{%n}', the corresponding argument is taken as an
+identifier which is created as an integer parameter.
+
+@noindent
+Normally, conversion specifications are applied to each argument in order
+but they can explicitly specify the @var{n}th argument is to be used by
+replacing `@t{%}' by `@t{%}@var{n}@t{$}' and `@t{*}' by `@t{*}@var{n}@t{$}'.
+It is recommended that you do not mix references of this explicit style
+with the normal style and the handling of such mixed styles may be subject
+to future change.
+
+@noindent
+If arguments remain unused after formatting, the format string is reused
+until all arguments have been consumed. With the @t{print} builtin, this
+can be suppressed by using the @t{-r} option. If more arguments are
+required by the format than have been specified, the behaviour is as if
+zero or an empty string had been specified as the argument.
+
+@findex pushd
+@pindex PUSHD_TO_HOME, use of
+@pindex PUSHD_MINUS, use of
+@pindex CDABLE_VARS, use of
+@pindex PUSHD_SILENT, use of
+@item @t{pushd} [ @t{-sLP} ] [ @var{arg} ]
+@itemx @t{pushd} [ @t{-sLP} ] @var{old} @var{new}
+@itemx @t{pushd} [ @t{-sLP} ] @{@t{+}|@t{-}@}@var{n}
+Change the current directory, and push the old current directory
+onto the directory stack.  In the first form, change the
+current directory to @var{arg}.
+If @var{arg} is not specified, change to the second directory
+on the stack (that is, exchange the top two entries), or
+change to @t{$HOME} if the @t{PUSHD_TO_HOME}
+option is set or if there is only one entry on the stack.
+Otherwise, @var{arg} is interpreted as it would be by @t{cd}.
+The meaning of @var{old} and @var{new} in the second form is also
+the same as for @t{cd}.
+
+@noindent
+The third form of @t{pushd} changes directory by rotating the
+directory list.  An argument of the form `@t{+}@var{n}' identifies a stack
+entry by counting from the left of the list shown by the @t{dirs}
+command, starting with zero.  An argument of the form `@t{-}@var{n}' counts
+from the right.  If the @t{PUSHD_MINUS} option is set, the meanings
+of `@t{+}' and `@t{-}' in this context are swapped.
+
+@noindent
+If the option @t{PUSHD_SILENT} is not set, the directory
+stack will be printed after a @t{pushd} is performed.
+
+@noindent
+The options @t{-s}, @t{-L} and @t{-P} have the same meanings as for the
+@t{cd} builtin.
+
+@findex pushln
+@item @t{pushln} [ @var{arg} ... ]
+Equivalent to @t{print -nz}.
+
+@findex pwd
+@pindex CHASE_LINKS, use of
+@item @t{pwd} [ @t{-rLP} ]
+Print the absolute pathname of the current working directory.
+If the @t{-r} or the @t{-P} flag is specified, or the @t{CHASE_LINKS}
+option is set and the @t{-L} flag is not given, the printed path will not
+contain symbolic links.
+
+@findex r
+@item @t{r}
+Same as @t{fc -e -}.
+
+@findex read
+@vindex IFS, use of
+
+@item @t{read} [ @t{-rszpqAclneE} ] [ @t{-t} [ @var{num} ] ] [ @t{-k} [ @var{num} ] ] [ @t{-d} @var{delim} ] [ @t{-u} @var{n} ] [ @var{name}[@t{?}@var{prompt}] ] [ @var{name} ...  ]
+@vindex REPLY, use of
+@vindex reply, use of
+Read one line and break it into fields using the characters
+in @t{$IFS} as separators, except as noted below.
+The first field is assigned to the first @var{name}, the second field
+to the second @var{name}, etc., with leftover
+fields assigned to the last @var{name}.
+If @var{name} is omitted then
+@t{REPLY} is used for scalars and @t{reply} for arrays.
+
+@noindent
+@table @asis
+@item @t{-r}
+Raw mode: a `@t{\}' at the end of a line does not signify line
+continuation and backslashes in the line don't quote the following
+character and are not removed.
+
+@item @t{-s}
+Don't echo back characters if reading from the terminal.  Currently does
+not work with the @t{-q} option.
+
+@item @t{-q}
+Read only one character from the terminal and set @var{name} to
+`@t{y}' if this character was `@t{y}' or `@t{Y}' and to `@t{n}' otherwise.
+With this flag set the return value is zero only if the character was
+`@t{y}' or `@t{Y}'.  Note that this always reads from the terminal, even
+if used with the @t{-p} or @t{-u} or @t{-z} flags or with redirected input.
+This option may also be used within zle widgets.
+
+@item @t{-k} [ @var{num} ]
+Read only one (or @var{num}) characters.  All are assigned to the first
+@var{name}, without word splitting.  This flag is ignored when @t{-q} is
+present.  Input is read from the terminal unless one of @t{-u} or @t{-p}
+is present.  This option may also be used within zle widgets.
+
+@item @t{-z}
+Read one entry from the editor buffer stack and assign it to the first
+@var{name}, without word splitting.  Text is pushed onto the stack with
+`@t{print -z}' or with @t{push-line} from the line editor (see
+@ref{Zsh Line Editor}).  This flag is ignored when the @t{-k} or @t{-q} flags are present.
+
+@item @t{-e}
+@itemx @t{-E}
+The input read is printed (echoed) to the standard output.  If the @t{-e}
+flag is used, no input is assigned to the parameters.
+
+@item @t{-A}
+The first @var{name} is taken as the name of an array and all words are
+assigned to it.
+
+@item @t{-c}
+@itemx @t{-l}
+These flags are allowed only if called inside a
+function used for completion (specified with the @t{-K} flag to
+@t{compctl}).  If the @t{-c} flag is given, the words of the
+current command are read. If the @t{-l} flag is given, the whole
+line is assigned as a scalar.  If both flags are present, @t{-l}
+is used and @t{-c} is ignored.
+
+@item @t{-n}
+Together with @t{-c}, the number of the word the cursor is on is
+read.  With @t{-l}, the index of the character the cursor is on is
+read.  Note that the command name is word number 1, not word 0,
+and that when the cursor is at the end of the line, its character
+index is the length of the line plus one.
+
+@item @t{-u} @var{n}
+Input is read from file descriptor @var{n}.
+
+@item @t{-p}
+Input is read from the coprocess.
+
+@item @t{-d} @var{delim}
+Input is terminated by the first character of @var{delim} instead of
+by newline.
+
+@item @t{-t} [ @var{num} ]
+Test if input is available before attempting to read.  If @var{num}
+is present, it must begin with a digit and will be evaluated
+to give a number of seconds, which may be a floating point number;
+in this case the read times out if input is not available within this
+time.  If @var{num} is not present, it is taken to be zero, so that
+@t{read} returns immediately if no input is available.
+If no input is available, return status 1 and do not set any variables.
+
+This option is not available when reading from the editor buffer with
+@t{-z}, when called from within completion with @t{-c} or @t{-l}, with
+@t{-q} which clears the input queue before reading, or within zle where
+other mechanisms should be used to test for input.
+
+Note that read does not attempt to alter the input processing mode.  The
+default mode is canonical input, in which an entire line is read at a time,
+so usually `@t{read -t}' will not read anything until an entire line has
+been typed.  However, when reading from the terminal with @t{-k}
+input is processed one key at a time; in this case, only availability of
+the first character is tested, so that e.g. `@t{read -t -k 2}' can still
+block on the second character.  Use two instances of `@t{read -t -k}' if
+this is not what is wanted.
+
+@end table
+If the first argument contains a `@t{?}', the remainder of this
+word is used as a @var{prompt} on standard error when the shell
+is interactive.
+
+@noindent
+The value (exit status) of @t{read} is 1 when an end-of-file is
+encountered, or when @t{-c} or @t{-l} is present and the command is
+not called from a @t{compctl} function, or as described for @t{-q}.
+Otherwise the value is 0.
+
+@noindent
+The behavior of some combinations of the @t{-k}, @t{-p}, @t{-q}, @t{-u}
+and @t{-z} flags is undefined.  Presently @t{-q} cancels all the others,
+@t{-p} cancels @t{-u}, @t{-k} cancels @t{-z}, and otherwise @t{-z}
+cancels both @t{-p} and @t{-u}.
+
+@noindent
+The @t{-c} or @t{-l} flags cancel any and all of @t{-kpquz}.
+
+@cindex parameters, marking readonly
+@findex readonly
+@item @t{readonly}
+Same as @t{typeset -r}.
+
+@findex rehash
+@item @t{rehash}
+Same as @t{hash -r}.
+
+@findex return
+@cindex functions, returning from
+@item @t{return} [ @var{n} ]
+Causes a shell function or @t{.} script to return to
+the invoking script with the return status specified by @var{n}.  If @var{n}
+is omitted, the return status is that of the last command
+executed.
+
+@noindent
+If @t{return} was executed from a trap in a @t{TRAP}@var{NAL} function,
+the effect is different for zero and non-zero return status.  With zero
+status (or after an implicit return at the end of the trap), the shell
+will return to whatever it was previously processing; with a non-zero
+status, the shell will behave as interrupted except that the return
+status of the trap is retained.  Note that the numeric value of the signal
+which caused the trap is passed as the first argument, so the statement
+`@t{return $((128+$1))}' will return the same status as if the signal
+had not been trapped.
+
+@item @t{sched}
+See @ref{The zsh/sched Module}.
+
+@findex set
+@cindex parameters, listing
+@cindex parameters, positional
+@cindex parameters, setting array
+@cindex array parameters, setting
+@pindex KSH_ARRAYS, use of
+@item @t{set} [ @{@t{+}|@t{-}@}@var{options} | @{@t{+}|@t{-}@}@t{o} [ @var{option_name} ] ] ... [ @{@t{+}|@t{-}@}@t{A} [ @var{name} ] ] [ @var{arg} ... ]
+Set the options for the shell and/or set the positional parameters, or
+declare and set an array.  If the @t{-s} option is given, it causes the
+specified arguments to be sorted before assigning them to the positional
+parameters (or to the array @var{name} if @t{-A} is used).  With @t{+s}
+sort arguments in descending order.  For the meaning of the other flags, see
+@ref{Options}.  Flags may be specified by name using the @t{-o} option. If no option
+name is supplied with @t{-o}, the current option states are printed.
+With @t{+o} they are printed in a form that can be used as input
+to the shell.
+
+@noindent
+If the @t{-A} flag is specified, @var{name} is set to an array containing
+the given @var{arg}s; if no @var{name} is specified, all arrays are printed
+together with their values.
+
+@noindent
+If @t{+A} is used and @var{name} is an array, the
+given arguments will replace the initial elements of that array; if no
+@var{name} is specified, all arrays are printed without their values.
+
+@noindent
+The behaviour of arguments after @t{-A} @var{name} or @t{+A} @var{name}
+depends on whether the option @t{KSH_ARRAYS} is set.  If it is not set, all
+arguments following @var{name} are treated as values for the array,
+regardless of their form.  If the option is set, normal option processing
+continues at that point; only regular arguments are treated as values for
+the array.  This means that
+
+@noindent
+@example
+set -A array -x -- foo
+@end example
+
+@noindent
+sets @t{array} to `@t{-x -- foo}' if @t{KSH_ARRAYS} is not set, but sets
+the array to @t{foo} and turns on the option `@t{-x}' if it is set.
+
+@noindent
+If the @t{-A} flag is not present, but there are arguments beyond the
+options, the positional parameters are set.  If the option list (if any)
+is terminated by `@t{-}@t{-}', and there are no further arguments, the
+positional parameters will be unset.
+
+@noindent
+If no arguments and no `@t{-}@t{-}' are given, then the names and values of
+all parameters are printed on the standard output.  If the only argument is
+`@t{+}', the names of all parameters are printed.
+
+@item @t{setcap}
+See @ref{The zsh/cap Module}.
+
+@findex setopt
+@cindex options, setting
+@item @t{setopt} [ @{@t{+}|@t{-}@}@var{options} | @{@t{+}|@t{-}@}@t{o} @var{option_name} ] [ @var{name} ... ]
+Set the options for the shell.  All options specified either
+with flags or by name are set.  If no arguments are supplied,
+the names of all options currently set are printed.
+If the @t{-m} flag is given the arguments are taken as patterns
+(which should be quoted to protect them from filename expansion), and all
+options with names matching these patterns are set.
+
+@findex shift
+@cindex parameters, positional
+@item @t{shift} [ @var{n} ] [ @var{name} ... ]
+The positional parameters @t{$@{}@var{n}+1@t{@}} ... are renamed
+to @t{$1} ..., where @var{n} is an arithmetic expression that
+defaults to 1.
+If any @var{name}s are given then the arrays with these names are
+shifted instead of the positional parameters.
+
+@findex source
+@item @t{source} @var{file} [ @var{arg} ... ]
+Same as @t{.}, except that the current directory is always searched and
+is always searched first, before directories in @t{$path}.
+
+@item @t{stat}
+See @ref{The zsh/stat Module}.
+
+@findex suspend
+@cindex shell, suspending
+@cindex suspending the shell
+@item @t{suspend} [ @t{-f} ]
+Suspend the execution of the shell (send it a @t{SIGTSTP})
+until it receives a @t{SIGCONT}.
+Unless the @t{-f} option is given, this will refuse to suspend a login shell.
+
+@findex test
+@item @t{test} [ @var{arg} ... ]
+@itemx @t{[} [ @var{arg} ... ] @t{]}
+Like the system version of @t{test}.  Added for compatibility;
+use conditional expressions instead (see @ref{Conditional Expressions}).
+The main differences between the conditional expression syntax and the
+@t{test} and @t{[} builtins are:  these commands are not handled
+syntactically, so for example an empty variable expansion may cause an
+argument to be omitted; syntax errors cause status 2 to be returned instead
+of a shell error; and arithmetic operators expect integer arguments rather
+than arithemetic expressions.
+
+@findex times
+@cindex shell, timing
+@cindex timing the shell
+@item @t{times}
+Print the accumulated user and system times for the shell
+and for processes run from the shell.
+
+@findex trap
+@cindex signals, trapping
+@cindex trapping signals
+@item @t{trap} [ @var{arg} [ @var{sig} ... ] ]
+@var{arg} is a series of commands (usually quoted to protect it from
+immediate evaluation by the shell) to be read and executed when the shell
+receives @var{sig}.  Each @var{sig} can be given as a number
+or as the name of a signal.
+If @var{arg} is `@t{-}', then all traps @var{sig} are reset to their
+default values.  If @var{arg} is the empty string, then this signal
+is ignored by the shell and by the commands it invokes.
+
+@noindent
+If @var{sig} is @t{ZERR} then @var{arg} will be executed
+after each command with a nonzero exit status.
+If @var{sig} is @t{DEBUG} then @var{arg} will be executed
+after each command.
+If @var{sig} is @t{0} or @t{EXIT}
+and the @t{trap} statement is executed inside the body of a function,
+then the command @var{arg} is executed after the function completes.
+If @var{sig} is @t{0} or @t{EXIT}
+and the @t{trap} statement is not executed inside the body of a function,
+then the command @var{arg} is executed when the shell terminates.
+
+@noindent
+@t{ZERR}, @t{DEBUG} and @t{EXIT} traps are not executed inside other traps.
+
+@noindent
+The @t{trap} command with no arguments prints a list of commands
+associated with each signal.
+
+@noindent
+Note that traps defined with the @t{trap} builtin are slightly different
+from those defined as `@t{TRAP}@var{NAL} () @{ ... @}', as the latter have
+their own function environment (line numbers, local variables, etc.) while
+the former use the environment of the command in which they were called.
+For example,
+
+@noindent
+@example
+trap 'print $LINENO' DEBUG
+@end example
+
+@noindent
+will print the line number of a command executed after it has run, while
+
+@noindent
+@example
+TRAPDEBUG() @{ print $LINENO; @}
+@end example
+
+@noindent
+will always print the number zero.
+
+@findex true
+@cindex doing nothing, successfully
+@item @t{true} [ @var{arg} ... ]
+Do nothing and return an exit code of 0.
+
+@findex ttyctl
+@cindex tty, freezing
+@item @t{ttyctl} @t{-fu}
+The @t{-f} option freezes the tty, and @t{-u} unfreezes it.
+When the tty is frozen, no changes made to the tty settings by
+external programs will be honored by the shell, except for changes in the
+size of the screen; the shell will
+simply reset the settings to their previous values as soon as each
+command exits or is suspended.  Thus, @t{stty} and similar programs have
+no effect when the tty is frozen.  Without options it reports whether the
+terminal is frozen or not.
+
+@findex type
+@item @t{type} [ @t{-wfpams} ] @var{name} ...
+Equivalent to @t{whence -v}.
+
+@findex typeset
+@cindex parameters, setting
+@cindex parameters, declaring
+@item @t{typeset} [ @{@t{+}|@t{-}@}@t{AEFHLRUZafghiklprtuxmz} [@var{n}]] [ @var{name}[@t{=}@var{value}] ... ]
+@itemx @t{typeset} -T [ @{@t{+|@t{-}}@}@t{LRUZrux} ] @var{SCALAR}[@t{=}@var{value}] @var{array} @t{[} @var{sep} @t{]}
+Set or display attributes and values for shell parameters.
+
+@noindent
+A parameter is created for each @var{name} that does not already refer
+to one.  When inside a function, a new parameter is created for every
+@var{name} (even those that already exist), and is unset again when the
+function completes.  See
+@ref{Local Parameters}.  The same rules apply to special shell parameters, which
+retain their special attributes when made local.
+
+@noindent
+For each @var{name}@t{=}@var{value} assignment, the parameter
+@var{name} is set to @var{value}.  Note that arrays currently cannot be
+assigned in @t{typeset} expressions, only scalars and integers.
+
+@noindent
+If the shell option @t{TYPESET_SILENT} is not set, for each remaining
+@var{name} that refers to a parameter that is set, the name and value of the
+parameter are printed in the form of an assignment.  Nothing is printed for
+newly-created parameters, or when any attribute flags listed below are
+given along with the @var{name}.  Using `@t{+}' instead of minus to
+introduce an attribute turns it off.
+
+@noindent
+If the @t{-p} option is given, parameters and values are printed in the
+form of a typeset comand and an assignment (which will be printed
+separately for arrays and associative arrays), regardless of other flags
+and options.  Note that the @t{-h} flag on parameters is respected; no
+value will be shown for these parameters.
+
+@noindent
+If the @t{-T} option is given, two or three arguments must be present (an
+exception is that zero arguments are allowed to show the list of parameters
+created in this fashion).  The first two are the name of a scalar and an
+array parameter (in that order) that will be tied together in the manner of
+@t{$PATH} and @t{$path}.  The optional third argument is a single-character
+separator which will be used to join the elements of the array to form the
+scalar; if absent, a colon is used, as with @t{$PATH}.  Only the first
+character of the separator is significant; any remaining characters are
+ignored.  Only the scalar parameter may be assigned an initial value.  Both
+the scalar and the array may otherwise be manipulated as normal.  If one is
+unset, the other will automatically be unset too.  There is no way of
+untying the variables without unsetting them, or converting the type of one
+of them with another @t{typeset} command; @t{+T} does not work, assigning
+an array to @var{SCALAR} is an error, and assigning a scalar to @var{array}
+sets it to be a single-element array.  Note that both `@t{typeset -xT ...}'
+and `@t{export -T ...}' work, but only the scalar will be marked for
+export.  Setting the value using the scalar version causes a split on all
+separators (which cannot be quoted).
+
+@noindent
+The @t{-g} (global) flag is treated specially: it means that any
+resulting parameter will not be restricted to local scope.  Note that this
+does not necessarily mean that the parameter will be global, as the flag
+will apply to any existing parameter (even if unset) from an enclosing
+function.  This flag does not affect the parameter after creation, hence it
+has no effect when listing existing parameters, nor does the flag @t{+g}
+have any effect except in combination with @t{-m} (see below).
+
+@noindent
+If no @var{name} is present, the names and values of all parameters are
+printed.  In this case the attribute flags restrict the display to only
+those parameters that have the specified attributes, and using `@t{+}'
+rather than `@t{-}' to introduce the flag suppresses printing of the values
+of parameters when there is no parameter name.  Also, if the last option
+is the word `@t{+}', then names are printed but values are not.
+
+@noindent
+If the @t{-m} flag is given the @var{name} arguments are taken as patterns
+(which should be quoted).  With no attribute flags, all parameters (or
+functions with the @t{-f} flag) with matching names are printed (the shell
+option @t{TYPESET_SILENT} is not used in this case).  Note that @t{-m} is
+ignored if no patterns are given.  If the @t{+g} flag is combined with
+@t{-m}, a new local parameter is created for every matching parameter that
+is not already local.  Otherwise @t{-m} applies all other flags or
+assignments to the existing parameters.  Except when assignments are made
+with @var{name}@t{=}@var{value}, using @t{+m} forces the matching parameters
+to be printed, even inside a function.
+
+@noindent
+If no attribute flags are given and either no @t{-m} flag is present or
+the @t{+m} form was used, each parameter name printed is preceded by a
+list of the attributes of that parameter (@t{array}, @t{association},
+@t{exported}, @t{integer}, @t{readonly}).  If @t{+m} is used with attribute
+flags, and all those flags are introduced with @t{+}, the matching
+parameter names are printed but their values are not.
+
+@noindent
+The following attribute flags may be specified:
+
+@noindent
+@table @asis
+@item @t{-A}
+The names refer to associative array parameters; see
+@ref{Array Parameters}.
+
+@item @t{-L}
+Left justify and remove leading blanks from @var{value}.
+If @var{n} is nonzero, it defines the width of the field;
+otherwise it is determined by the width of the value of the first
+assignment.
+When the parameter is expanded, it is filled on the right with
+blanks or truncated if necessary to fit the field.
+Leading zeros are removed if the @t{-Z} flag is also set.
+
+@item @t{-R}
+Right justify and fill with leading blanks.  If @var{n} is nonzero
+if defines the width of the field;
+otherwise it is determined by the width of the value of the first
+assignment.
+When the parameter is expanded, the field is left filled with
+blanks or truncated from the end.
+
+@item @t{-U}
+For arrays (but not for associative arrays), keep only the first
+occurrence of each duplicated value.  This may also be set for
+colon-separated special parameters like @t{PATH} or @t{FIGNORE}, etc.
+This flag has a different meaning when used with @t{-f}; see below.
+
+@item @t{-Z}
+Right justify and fill with leading zeros if the first non-blank
+character is a digit and the @t{-L} flag has not been set.
+If @var{n} is nonzero it defines the width of the field;
+otherwise it is determined by the width of the value of the
+first assignment.
+
+@item @t{-a}
+The names refer to array parameters.  An array parameter may be
+created this way, but it may not be assigned to in the @t{typeset}
+statement.  When displaying, both normal and associative arrays are
+shown.
+
+@item @t{-f}
+The names refer to functions rather than parameters.  No assignments
+can be made, and the only other valid flags are @t{-t}, @t{-k}, @t{-u},
+@t{-U} and @t{-z}.  The flag @t{-t} turns on execution tracing for this
+function.  The @t{-u} and @t{-U} flags cause the function to be
+marked for autoloading; @t{-U} also causes alias expansion to be
+suppressed when the function is loaded.  The @t{fpath} parameter
+will be searched to find the function definition when the function
+is first referenced; see @ref{Functions}. The @t{-k} and @t{-z} flags
+make the function be loaded using ksh-style or zsh-style autoloading
+respectively. If neither is given, the setting of the KSH_AUTOLOAD option
+determines how the function is loaded.
+
+@item @t{-h}
+Hide: only useful for special parameters (those marked `<S>' in the table in
+@ref{Parameters Set By The Shell}), and for local parameters with the same name as a special parameter,
+though harmless for others.  A special parameter with this attribute will
+not retain its special effect when made local.  Thus after `@t{typeset -h
+PATH}', a function containing `@t{typeset PATH}' will create an ordinary
+local parameter without the usual behaviour of @t{PATH}.  Alternatively,
+the local parameter may itself be given this attribute; hence inside a
+function `@t{typeset -h PATH}' creates an ordinary local parameter and the
+special @t{PATH} parameter is not altered in any way.  It is also possible
+to create a local parameter using `@t{typeset +h }@var{special}', where the
+local copy of @var{special} will retain its special properties regardless of
+having the @t{-h} attribute.  Global special parameters loaded from shell
+modules (currently those in @t{zsh/mapfile} and @t{zsh/parameter}) are
+automatically given the @t{-h} attribute to avoid name clashes.
+
+@item @t{-H}
+Hide value: specifies that @t{typeset} will not display the value of the
+parameter when listing parameters; the display for such parameters is
+always as if the `@t{+}' flag had been given.  Use of the parameter is
+in other respects normal, and the option does not apply if the parameter is
+specified by name, or by pattern with the @t{-m} option.  This is on by
+default for the parameters in the @t{zsh/parameter} and @t{zsh/mapfile}
+modules.  Note, however, that unlike the @t{-h} flag this is also useful
+for non-special parameters.
+
+@item @t{-i}
+Use an internal integer representation.  If @var{n} is nonzero it
+defines the output arithmetic base, otherwise it is determined by the
+first assignment.
+
+@item @t{-E}
+Use an internal double-precision floating point representation.  On output
+the variable will be converted to scientific notation.  If @var{n} is
+nonzero it defines the number of significant figures to display; the
+default is ten.
+
+@item @t{-F}
+Use an internal double-precision floating point representation.  On output
+the variable will be converted to fixed-point decimal notation.  If @var{n}
+is nonzero it defines the number of digits to display after the decimal
+point; the default is ten.
+
+@item @t{-l}
+Convert the result to lower case whenever the parameter is expanded.
+The value is @emph{not} converted when assigned.
+
+@item @t{-r}
+The given @var{name}s are marked readonly.  Note that if @var{name} is a
+special parameter, the readonly attribute can be turned on, but cannot then
+be turned off.
+
+@item @t{-t}
+Tags the named parameters.  Tags have no special meaning to the shell.
+This flag has a different meaning when used with @t{-f}; see above.
+
+@item @t{-u}
+Convert the result to upper case whenever the parameter is expanded.
+The value is @emph{not} converted when assigned.
+This flag has a different meaning when used with @t{-f}; see above.
+
+@item @t{-x}
+Mark for automatic export to the environment of subsequently
+executed commands.  If the option @t{GLOBAL_EXPORT} is set, this implies
+the option @t{-g}, unless @t{+g} is also explicitly given; in other words
+the parameter is not made local to the enclosing function.  This is for
+compatibility with previous versions of zsh.
+
+@end table
+
+@findex ulimit
+@cindex resource limits
+@cindex limits, resource
+@item @t{ulimit} [ [ @t{-SHacdflmnpstv} | @t{-N} @var{resource} [ @var{limit} ] ... ]
+Set or display resource limits of the shell and the processes started by
+the shell.  The value of @var{limit} can be a number in the unit specified
+below or the value `@t{unlimited}'.  By default, only soft limits are
+manipulated. If the @t{-H} flag is given use
+hard limits instead of soft limits.  If the @t{-S} flag is given
+together with the @t{-H} flag set both hard and soft limits.  If no
+options are used, the file size limit (@t{-f}) is assumed.  If
+@var{limit} is omitted the current value of the specified resources are
+printed.  When more than one resource values are printed the limit name and
+unit is printed before each value.
+
+@noindent
+When looping over multiple resources, the shell will abort immediately if
+it detects a badly formed argument.  However, if it fails to set a limit
+for some other reson it will continue trying to set the remaining limits.
+
+@noindent
+@table @asis
+@item @t{-a}
+Lists all of the current resource limits.
+@item @t{-c}
+512-byte blocks on the size of core dumps.
+@item @t{-d}
+K-bytes on the size of the data segment.
+@item @t{-f}
+512-byte blocks on the size of files written.
+@item @t{-l}
+K-bytes on the size of locked-in memory.
+@item @t{-m}
+K-bytes on the size of physical memory.
+@item @t{-n}
+open file descriptors.
+@item @t{-s}
+K-bytes on the size of the stack.
+@item @t{-t}
+CPU seconds to be used.
+@item @t{-u}
+processes available to the user.
+@item @t{-v}
+K-bytes on the size of virtual memory.  On some systems this
+refers to the limit called `address space'.
+@end table
+
+@noindent
+A resource may also be specified by integer in the form `@t{-N}
+@var{resource}', where @var{resource} corresponds to the integer defined for
+the resource by the operating system.  This may be used to set the limits
+for resources known to the shell which do not correspond to option letters.
+Such limits will be shown by number in the output of `@t{ulimit -a}'.
+
+@noindent
+The number may alternatively be out of the range of limits compiled into
+the shell.  The shell will try to read or write the limit anyway, and
+will report an error if this fails.
+
+@findex umask
+@cindex umask
+@item @t{umask} [ @t{-S} ] [ @var{mask} ]
+The umask is set to @var{mask}.  @var{mask} can be either
+an octal number or a symbolic value as described in man page chmod(1).
+If @var{mask} is omitted, the current value is printed.  The @t{-S}
+option causes the mask to be printed as a symbolic value.  Otherwise,
+the mask is printed as an octal number.  Note that in
+the symbolic form the permissions you specify are those which are to be
+allowed (not denied) to the users specified.
+
+@cindex aliases, removing
+@findex unalias
+@item @t{unalias}
+Same as @t{unhash -a}.
+
+@cindex functions, removing
+@findex unfunction
+@item @t{unfunction}
+Same as @t{unhash -f}.
+
+@findex unhash
+@item @t{unhash} [ @t{-adfms} ] @var{name} ...
+Remove the element named @var{name} from an internal hash table.  The
+default is remove elements from the command hash table.  The @t{-a}
+option causes @t{unhash} to remove regular or global aliases.
+The @t{-s} option causes @t{unhash} to remove suffix aliases.
+The @t{-f} option causes
+@t{unhash} to remove shell functions.  The @t{-d} options causes
+@t{unhash} to remove named directories.  If the @t{-m} flag is given
+the arguments are taken as patterns (should be quoted) and all elements
+of the corresponding hash table with matching names will be removed.
+
+@findex unlimit
+@cindex resource limits
+@cindex limits, resource
+@item @t{unlimit} [ @t{-hs} ] @var{resource} ...
+The resource limit for each @var{resource} is set to the hard limit.
+If the @t{-h} flag is given and the shell has appropriate privileges,
+the hard resource limit for each @var{resource} is removed.
+The resources of the shell process are only changed if the @t{-s}
+flag is given.
+
+@findex unset
+@cindex parameters, unsetting
+@item @t{unset} [ @t{-fmv} ] @var{name} ...
+Each named parameter is unset.
+Local parameters remain local even if unset; they appear unset within scope,
+but the previous value will still reappear when the scope ends.
+
+@noindent
+Individual elements of associative array parameters may be unset by using
+subscript syntax on @var{name}, which should be quoted (or the entire command
+prefixed with @t{noglob}) to protect the subscript from filename generation.
+
+@noindent
+If the @t{-m} flag is specified the arguments are taken as patterns (should
+be quoted) and all parameters with matching names are unset.  Note that this
+cannot be used when unsetting associative array elements, as the subscript
+will be treated as part of the pattern.
+
+@noindent
+The @t{-v} flag specifies that @var{name} refers to parameters. This is the
+default behaviour.
+
+@noindent
+@t{unset -f} is equivalent to @t{unfunction}.
+
+@findex unsetopt
+@cindex options, unsetting
+@item @t{unsetopt} [ @{@t{+}|@t{-}@}@var{options} | @{@t{+}|@t{-}@}@t{o} @var{option_name} ] [ @var{name} ... ]
+Unset the options for the shell.  All options specified either
+with flags or by name are unset.  If no arguments are supplied,
+the names of all options currently unset are printed.
+If the @t{-m} flag is given the arguments are taken as patterns
+(which should be quoted to preserve them from being interpreted as glob
+patterns), and all options with names matching these patterns are unset.
+
+@item @t{vared}
+See @ref{Zle Builtins}.
+
+@findex wait
+@cindex waiting for jobs
+@cindex jobs, waiting for
+@item @t{wait} [ @var{job} ... ]
+Wait for the specified jobs or processes.  If @var{job} is not given
+then all currently active child processes are waited for.
+Each @var{job} can be either a job specification or the process ID
+of a job in the job table.
+The exit status from this command is that of the job waited for.
+
+@findex whence
+@item @t{whence} [ @t{-vcwfpams} ] @var{name} ...
+For each name, indicate how it would be interpreted if used as a
+command name.
+
+@noindent
+@table @asis
+@item @t{-v}
+Produce a more verbose report.
+
+@item @t{-c}
+Print the results in a @cite{csh}-like format.
+This takes precedence over @t{-v}.
+
+@item @t{-w}
+For each @var{name}, print `@var{name}@t{:} @var{word}' where @var{word}
+is one of @t{alias}, @t{builtin}, @t{command}, @t{function},
+@t{hashed}, @t{reserved} or @t{none}, according as @var{name}
+corresponds to an alias, a built-in command, an external command, a
+shell function, a command defined with the @t{hash} builtin, a
+reserved word, or is not recognised.  This takes precedence over
+@t{-v} and @t{-c}.
+
+@item @t{-f}
+Causes the contents of a shell function to be
+displayed, which would otherwise not happen unless the @t{-c}
+flag were used.
+
+@item @t{-p}
+Do a path search for @var{name}
+even if it is an alias, reserved word, shell function or builtin.
+
+@item @t{-a}
+Do a search for all occurrences of @var{name}
+throughout the command path.
+Normally only the first occurrence is printed.
+
+@item @t{-m}
+The arguments are taken as patterns (should be
+quoted), and the information is displayed for each command matching one
+of these patterns.
+
+@item @t{-s}
+If a pathname contains symlinks, print the symlink-free pathname as well.
+
+@end table
+
+@findex where
+@item @t{where} [ @t{-wpms} ] @var{name} ...
+Equivalent to @t{whence -ca}.
+
+@findex which
+@item @t{which} [ @t{-wpams} ] @var{name} ...
+Equivalent to @t{whence -c}.
+
+@findex zcompile
+@cindex .zwc files, creation
+@cindex compilation
+@item @t{zcompile} [ @t{-U} ] [ @t{-z} | @t{-k} ] [ @t{-R} | @t{-M} ] @var{file} [ @var{name} ... ]
+@itemx @t{zcompile} @t{-ca} [ @t{-m} ] [ @t{-R} | @t{-M} ] @var{file} [ @var{name} ... ]
+@itemx @t{zcompile -t} @var{file} [ @var{name} ... ]
+This builtin command can be used to compile functions or scripts,
+storing the compiled form in a file, and to examine files containing
+the compiled form.  This allows faster autoloading of functions and
+execution of scripts by avoiding parsing of the text when the files
+are read.
+
+@noindent
+The first form (without the @t{-c}, @t{-a} or @t{-t} options) creates a
+compiled file.  If only the @var{file} argument is given, the
+output file has the name `@var{file}@t{.zwc}' and will be placed in
+the same directory as the @var{file}.  The shell will load the compiled
+file instead of the normal function file when the function
+is autoloaded; see
+@ref{Functions}
+for a description of how autoloaded functions are searched.  The
+extension @t{.zwc} stands for `zsh word code'.
+
+@noindent
+If there is at least one @var{name} argument, all the named files
+are compiled into the output @var{file} given as the first argument.  If
+@var{file} does not end in @t{.zwc}, this extension is automatically
+appended.  Files containing multiple compiled functions are called `digest'
+files, and are intended to be used as elements of the @t{FPATH}/@t{fpath}
+special array.
+
+@noindent
+The second form, with the @t{-c} or @t{-a} options, writes the compiled
+definitions for all the named functions into @var{file}.  For @t{-c}, the
+names must be functions currently defined in the shell, not those marked
+for autoloading.  Undefined functions that are marked for autoloading
+may be written by using the @t{-a} option, in which case the @t{fpath}
+is searched and the contents of the definition files for those
+functions, if found, are compiled into @var{file}.  If both @t{-c} and
+@t{-a} are given, names of both defined functions and functions marked
+for autoloading may be given.  In either case, the functions in files
+written with the @t{-c} or @t{-a} option will be autoloaded as if the
+@t{KSH_AUTOLOAD} option were unset.
+
+@noindent
+The reason for handling loaded and not-yet-loaded functions with
+different options is that some definition files for autoloading define
+multiple functions, including the function with the same name as the
+file, and, at the end, call that function.  In such cases the output of
+`@t{zcompile -c}' does not include the additional functions defined in
+the file, and any other initialization code in the file is lost.  Using
+`@t{zcompile -a}' captures all this extra information.
+
+@noindent
+If the @t{-m} option is combined with @t{-c} or @t{-a},
+the @var{name}s are used as patterns and all functions whose names
+match one of these patterns will be written. If no @var{name} is given,
+the definitions of all functions currently defined or marked as
+autoloaded will be written.
+
+@noindent
+The third form, with the @t{-t} option, examines an existing
+compiled file.  Without further arguments, the names of the original
+files compiled into it are listed.  The first line of output shows
+the version of the shell which compiled the file and how the file
+will be used (i.e. by reading it directly or by mapping it into memory).
+With arguments, nothing is output and the return value is set to zero if
+definitions for @emph{all} @var{name}s were found in the compiled
+file, and non-zero if the definition for at least one @var{name} was not
+found.
+
+@noindent
+Other options:
+
+@noindent
+@table @asis
+@item @t{-U}
+Aliases are not expanded when compiling the @var{name}d files.
+
+@item @t{-R}
+When the compiled file is read, its contents are copied into the
+shell's memory, rather than memory-mapped (see @t{-M}).  This
+happens automatically on systems that do not support memory mapping.
+
+@noindent
+When compiling scripts instead of autoloadable functions, it is
+often desirable to use this option; otherwise the whole file, including the
+code to define functions which have already been defined, will
+remain mapped, consequently wasting memory.
+
+@item @t{-M}
+The compiled file is mapped into the shell's memory when read. This
+is done in such a way that multiple instances of the shell running
+on the same host will share this mapped file.  If neither @t{-R} nor
+@t{-M} is given, the @t{zcompile} builtin decides what to do based
+on the size of the compiled file.
+
+@item @t{-k}
+@itemx @t{-z}
+These options are used when the compiled file contains functions which
+are to be autoloaded. If @t{-z} is given, the
+function will be autoloaded as if the @t{KSH_AUTOLOAD} option is
+@emph{not} set, even if it is set at the time the compiled file is
+read, while if the @t{-k} is given, the function will be loaded as if
+@t{KSH_AUTOLOAD} @emph{is} set.  These options also take precedence over
+any @t{-k} or @t{-z} options specified to the @t{autoload} builtin. If
+neither of these options is given, the function will be loaded as
+determined by the setting of the @t{KSH_AUTOLOAD} option at the time
+the compiled file is read.
+
+These options may also appear as many times as necessary between the listed
+@var{name}s to specify the loading style of all following functions, up to
+the next @t{-k} or @t{-z}.
+
+@end table
+
+@noindent
+The created file always contains two versions of the compiled
+format, one for big-endian machines and one for small-endian
+machines.  The upshot of this is that the compiled file is machine
+independent and if it is read or mapped, only one half of the file
+is actually used (and mapped).
+
+
+@item @t{zformat}
+See @ref{The zsh/zutil Module}.
+
+@item @t{zftp}
+See @ref{The zsh/zftp Module}.
+
+@item @t{zle}
+See @ref{Zle Builtins}.
+
+@findex zmodload
+@cindex modules, loading
+@cindex loading modules
+@item @t{zmodload} [ @t{-dL} ] [ ... ]
+@itemx @t{zmodload -e} [ @t{-A} ] [ ... ]
+@itemx @t{zmodload} [ @t{-a} [ @t{-bcpf} [ @t{-I} ] ] ] [ @t{-iL} ] ...
+@itemx @t{zmodload} @t{-u} [ @t{-abcdpf} [ @t{-I} ] ] [ @t{-iL} ] ...
+@itemx @t{zmodload} @t{-A} [ @t{-L} ] [ @var{modalias}[@t{=}@var{module}] ... ]
+@itemx @t{zmodload} @t{-R} @var{modalias} ... 
+Performs operations relating to zsh's loadable modules.
+Loading of modules while the shell is running (`dynamical loading') is not
+available on all operating systems, or on all installations on a particular
+operating system, although the @t{zmodload} command itself is always
+available and can be used to manipulate modules built into versions of the
+shell executable without dynamical loading.
+
+@noindent
+Without arguments the names of all currently loaded binary modules are
+printed.  The @t{-L} option causes this list to be in the form of a
+series of @t{zmodload} commands.  Forms with arguments are:
+
+@noindent
+@table @asis
+@item @t{zmodload} [ @t{-i} ] @var{name} ... 
+@itemx @t{zmodload} @t{-u} [ @t{-i} ] @var{name} ...
+In the simplest case, @t{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 `@t{.so}' (`@t{.sl}' on HPUX).
+If the module to be loaded is
+already loaded and the @t{-i} option is given, the duplicate module is
+ignored.  Otherwise @t{zmodload} prints an error message.
+
+@noindent
+The @var{name}d module is searched for in the same way a command is, using
+@t{$module_path} instead of @t{$path}.  However, the path search is
+performed even when the module name contains a `@t{/}', which it usually does.
+There is no way to prevent the path search.
+
+@noindent
+With @t{-u}, @t{zmodload} unloads modules.  The same @var{name}
+must be given that was given when the module was loaded, but it is not
+necessary for the module to exist in the filesystem.
+The @t{-i} option suppresses the error if the module is already
+unloaded (or was never loaded).
+
+@noindent
+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.
+
+@item @t{zmodload} @t{-d} [ @t{-L} ] [ @var{name} ]
+@itemx @t{zmodload} @t{-d} @var{name} @var{dep} ...
+@itemx @t{zmodload} @t{-ud} @var{name} [ @var{dep} ... ]
+The @t{-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.
+
+@noindent
+With @t{-d} and one argument, all dependencies for that module are listed.
+With @t{-d} and no arguments, all module dependencies are listed.  This
+listing is by default in a Makefile-like format.  The @t{-L} option
+changes this format to a list of @t{zmodload -d} commands.
+
+@noindent
+If @t{-d} and @t{-u} are both used, dependencies are removed.  If only one
+argument is given, all dependencies for that module are removed.
+
+@item @t{zmodload} @t{-ab} [ @t{-L} ]
+@itemx @t{zmodload} @t{-ab} [ @t{-i} ] @var{name} [ @var{builtin} ... ]
+@itemx @t{zmodload} @t{-ub} [ @t{-i} ] @var{builtin} ...
+The @t{-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.  @t{-i} suppresses
+the error if the builtin is already defined or autoloaded, regardless of
+which module it came from.
+
+@noindent
+With @t{-ab} and no arguments, all autoloaded builtins are listed, with the
+module name (if different) shown in parentheses after the builtin name.
+The @t{-L} option changes this format to a list of @t{zmodload -a}
+commands.
+
+@noindent
+If @t{-b} is used together with the @t{-u} option, it removes builtins
+previously defined with @t{-ab}.  This is only possible if the builtin is
+not yet loaded.  @t{-i} suppresses the error if the builtin is already
+removed (or never existed).
+
+@item @t{zmodload} @t{-ac} [ @t{-IL} ]
+@itemx @t{zmodload} @t{-ac} [ @t{-iI} ] @var{name} [ @var{cond} ... ]
+@itemx @t{zmodload} @t{-uc} [ @t{-iI} ] @var{cond} ...
+The @t{-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 @t{-I} option is used to define infix condition
+names. Without this option prefix condition names are defined.
+
+@noindent
+If given no condition names, all defined names are listed (as a series of
+@t{zmodload} commands if the @t{-L} option is given).
+
+@noindent
+The @t{-uc} option removes definitions for autoloaded conditions.
+
+@item @t{zmodload} @t{-ap} [ @t{-L} ]
+@itemx @t{zmodload} @t{-ap} [ @t{-i} ] @var{name} [ @var{parameter} ... ]
+@itemx @t{zmodload} @t{-up} [ @t{-i} ] @var{parameter} ...
+The @t{-p} option is like the @t{-b} and @t{-c} options, but makes
+@t{zmodload} work on autoloaded parameters instead.
+
+@item @t{zmodload} @t{-af} [ @t{-L} ]
+@itemx @t{zmodload} @t{-af} [ @t{-i} ] @var{name} [ @var{function} ... ]
+@itemx @t{zmodload} @t{-uf} [ @t{-i} ] @var{function} ...
+The @t{-f} option is like the @t{-b}, @t{-p}, and @t{-c} options, but
+makes @t{zmodload} work on autoloaded math functions instead. 
+
+@item @t{zmodload} @t{-a} [ @t{-L} ]
+@itemx @t{zmodload} @t{-a} [ @t{-i} ] @var{name} [ @var{builtin} ... ]
+@itemx @t{zmodload} @t{-ua} [ @t{-i} ] @var{builtin} ...
+Equivalent to @t{-ab} and @t{-ub}.
+
+@item @t{zmodload -e} [ @t{-A} ] [ @var{string} ... ]
+The @t{-e} option without arguments lists all loaded modules; if the @t{-A}
+option is also given, module aliases corresponding to loaded modules are
+also shown.  With arguments only the return status is set to zero
+if all @var{string}s given as arguments are names of loaded modules
+and to one if at least on @var{string} is not the name of a
+loaded module.  This can be used to test for the availability 
+of things implemented by modules.  In this case, any aliases are
+automatically resolved and the @t{-A} flag is not used.
+
+@item @t{zmodload} @t{-A} [ @t{-L} ] [ @var{modalias}[@t{=}@var{module}] ... ]
+For each argument, if both @var{modalias} and @var{module} are given,
+define @var{modalias} to be an alias for the module @var{module}.
+If the module @var{modalias} is ever subsequently requested, either via a
+call to @t{zmodload} or implicitly, the shell will attempt to load
+@var{module} instead.  If @var{module} is not given, show the definition of
+@var{modalias}.  If no arguments are given, list all defined module aliases.
+When listing, if the @t{-L} flag was also given, list the definition as a
+@t{zmodload} command to recreate the alias.
+
+@noindent
+The existence of aliases for modules is completely independent of whether
+the name resolved is actually loaded as a module: while the alias exists,
+loading and unloading the module under any alias has exactly the same
+effect as using the resolved name, and does not affect the connection
+between the alias and the resolved name which can be removed either by
+@t{zmodload -R} or by redefining the alias.  Chains of aliases (i.e. where
+the first resolved name is itself an alias) are valid so long as these are
+not circular.  As the aliases take the same format as module names, they
+may include path separators:  in this case, there is no requirement for any
+part of the path named to exist as the alias will be resolved first.  For
+example, `@t{any/old/alias}' is always a valid alias.
+
+@noindent
+Dependencies added to aliased modules are actually added to the resolved
+module; these remain if the alias is removed.  It is valid to create an
+alias whose name is one of the standard shell modules and which resolves to
+a different module.  However, if a module has dependencies, it
+will not be possible to use the module name as an alias as the module will
+already be marked as a loadable module in its own right.
+
+@noindent
+Apart from the above, aliases can be used in the @t{zmodload} command
+anywhere module names are required.  However, aliases will not be
+shown in lists of loaded modules with a bare `@t{zmodload}'.
+
+@item @t{zmodload} @t{-R} @var{modalias} ... 
+For each @var{modalias} argument that was previously defined as a module
+alias via @t{zmodload -A}, delete the alias.  If any was not defined, an
+error is caused and the remainder of the line is ignored.
+
+@end table
+
+@noindent
+Note that @t{zsh} makes no distinction between modules that were linked 
+into the shell and modules that are loaded dynamically. In both cases
+this builtin command has to be used to make available the builtins and
+other things defined by modules (unless the module is autoloaded on
+these definitions). This is true even for systems that don't support
+dynamic loading of modules.
+
+@item @t{zparseopts}
+See @ref{The zsh/zutil Module}.
+
+@item @t{zprof}
+See @ref{The zsh/zprof Module}.
+
+@item @t{zpty}
+See @ref{The zsh/zpty Module}.
+
+@item @t{zregexparse}
+See @ref{The zsh/zutil Module}.
+
+@item @t{zsocket}
+See @ref{The zsh/net/socket Module}.
+
+@item @t{zstyle}
+See @ref{The zsh/zutil Module}.
+
+@item @t{ztcp}
+See @ref{The zsh/net/tcp Module}.
+
+@end table
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/zle.yo
+@node Zsh Line Editor, Completion Widgets, Shell Builtin Commands, Top
+
+@chapter Zsh Line Editor
+@noindent
+@cindex line editor
+@cindex editor, line
+@cindex ZLE
+
+@section Description
+@noindent
+@pindex ZLE, use of
+If the @t{ZLE} option is set (which it is by default in interactive shells)
+and the shell input is attached to the terminal, the user
+is able to edit command lines.
+
+@noindent
+There are two display modes.  The first, multiline mode, is the
+default.  It only works if the @t{TERM} parameter is set to a valid
+terminal type that can move the cursor up.  The second, single line
+mode, is used if @t{TERM} is invalid or incapable of moving the
+cursor up, or if the @t{SINGLE_LINE_ZLE} option is set.
+@pindex SINGLE_LINE_ZLE, use of
+@cindex ksh, editor mode
+@cindex editor ksh style
+This mode
+is similar to @cite{ksh}, and uses no termcap sequences.  If @t{TERM} is
+"emacs", the @t{ZLE} option will be unset by default.
+
+@noindent
+@vindex BAUD, use of
+@vindex COLUMNS, use of
+@vindex LINES, use of
+The parameters @t{BAUD}, @t{COLUMNS}, and @t{LINES} are also used by the
+line editor.
+@ref{Parameters Used By The Shell}.
+
+@noindent
+@menu
+* Keymaps::
+* Zle Builtins::
+* Zle Widgets::
+@end menu
+
+@noindent
+@node Keymaps, Zle Builtins, , Zsh Line Editor
+
+@section Keymaps
+@noindent
+@cindex keymaps
+@cindex key bindings
+@cindex bindings, key
+A keymap in ZLE contains a set of bindings between key sequences
+and ZLE commands.  The empty key sequence cannot be bound.
+
+@noindent
+There can be any number of keymaps at any time, and each keymap has one
+or more names.  If all of a keymap's names are deleted, it disappears.
+@findex bindkey, use of
+@t{bindkey} can be used to manipulate keymap names.
+
+@noindent
+Initially, there are four keymaps:
+
+@noindent
+@table @asis
+@item @t{emacs}
+EMACS emulation
+@item @t{viins}
+vi emulation - insert mode
+@item @t{vicmd}
+vi emulation - command mode
+@item @t{.safe}
+fallback keymap
+@end table
+
+@noindent
+The `@t{.safe}' keymap is special.  It can never be altered, and the name
+can never be removed.  However, it can be linked to other names, which can
+be removed.  In the future other special keymaps may be added; users should
+avoid using names beginning with `@t{.}' for their own keymaps.
+
+@noindent
+@vindex VISUAL
+@vindex EDITOR
+In addition to these four names, either `@t{emacs}' or `@t{viins}' is
+also linked to the name `@t{main}'.  If one of the @t{VISUAL} or
+@t{EDITOR} environment variables contain the string `@t{vi}' when the shell
+starts up then it will be `@t{viins}', otherwise it will be `@t{emacs}'.
+@t{bindkey}'s @t{-e} and @t{-v}
+options provide a convenient way to override this default choice.
+
+@noindent
+When the editor starts up, it will select the `@t{main}' keymap.
+If that keymap doesn't exist, it will use `@t{.safe}' instead.
+
+@noindent
+In the `@t{.safe}' keymap, each single key is bound to @t{self-insert},
+except for ^J (line feed) and ^M (return) which are bound to @t{accept-line}.
+This is deliberately not pleasant to use; if you are using it, it
+means you deleted the main keymap, and you should put it back.
+
+@subsection Reading Commands
+@noindent
+When ZLE is reading a command from the terminal, it may read a sequence
+that is bound to some command and is also a prefix of a longer bound string.
+In this case ZLE will wait a certain time to see if more characters
+are typed, and if not (or they don't match any longer string) it will
+execute the binding.  This timeout is defined by the @t{KEYTIMEOUT} parameter;
+its default is 0.4 sec.  There is no timeout if the prefix string is not
+itself bound to a command.
+
+@noindent
+As well as ZLE commands, key sequences can be bound to other strings, by using
+`@t{bindkey -s}'.
+When such a sequence is read, the replacement string is pushed back as input,
+and the command reading process starts again using these fake keystrokes.
+This input can itself invoke further replacement strings, but in order to
+detect loops the process will be stopped if there are twenty such replacements
+without a real command being read.
+
+@noindent
+@node Zle Builtins, Zle Widgets, Keymaps, Zsh Line Editor
+
+@section Zle Builtins
+@noindent
+@cindex zle, builtin commands
+The ZLE module contains three related builtin commands. The @t{bindkey}
+command manipulates keymaps and key bindings; the @t{vared} command invokes
+ZLE on the value of a shell parameter; and the @t{zle} command manipulates
+editing widgets and allows command line access to ZLE commands from within
+shell functions.
+
+@noindent
+@table @asis
+@findex bindkey
+@cindex keys, rebinding
+@cindex rebinding keys
+@cindex keys, binding
+@cindex binding keys
+@cindex keymaps
+@item @t{bindkey} [ @var{options} ] @t{-l}
+@itemx @t{bindkey} [ @var{options} ] @t{-d}
+@itemx @t{bindkey} [ @var{options} ] @t{-D} @var{keymap} ...
+@itemx @t{bindkey} [ @var{options} ] @t{-A} @var{old-keymap new-keymap}
+@itemx @t{bindkey} [ @var{options} ] @t{-N} @var{new-keymap} [ @var{old-keymap} ]
+@itemx @t{bindkey} [ @var{options} ] @t{-m}
+@itemx @t{bindkey} [ @var{options} ] @t{-r} @var{in-string} ...
+@itemx @t{bindkey} [ @var{options} ] @t{-s} @var{in-string out-string} ...
+@itemx @t{bindkey} [ @var{options} ] @var{in-string command} ...
+@itemx @t{bindkey} [ @var{options} ] [ @var{in-string} ]
+@t{bindkey}'s options can be divided into three categories: keymap selection,
+operation selection, and others.  The keymap selection options are:
+
+@noindent
+@table @asis
+@item @t{-e}
+Selects keymap `@t{emacs}', and also links it to `@t{main}'.
+
+@item @t{-v}
+Selects keymap `@t{viins}', and also links it to `@t{main}'.
+
+@item @t{-a}
+Selects keymap `@t{vicmd}'.
+
+@item @t{-M} @var{keymap}
+The @var{keymap} specifies a keymap name.
+
+@end table
+
+@noindent
+If a keymap selection is required and none of the options above are used, the
+`@t{main}' keymap is used.  Some operations do not permit a keymap to be
+selected, namely:
+
+@noindent
+@table @asis
+@item @t{-l}
+List all existing keymap names.  If the @t{-L}
+option is also used, list in the form of @t{bindkey}
+commands to create the keymaps.
+
+@item @t{-d}
+Delete all existing keymaps and reset to the default state.
+
+@item @t{-D} @var{keymap} ...
+Delete the named @var{keymap}s.
+
+@item @t{-A} @var{old-keymap new-keymap}
+Make the @var{new-keymap} name an alias for @var{old-keymap}, so that
+both names refer to the same keymap.  The names have equal standing;
+if either is deleted, the other remains.  If there is already a keymap
+with the @var{new-keymap} name, it is deleted.
+
+@item @t{-N} @var{new-keymap} [ @var{old-keymap} ]
+Create a new keymap, named @var{new-keymap}.  If a keymap already has that
+name, it is deleted.  If an @var{old-keymap} name is given, the new keymap
+is initialized to be a duplicate of it, otherwise the new keymap will
+be empty.
+
+@end table
+
+@noindent
+To use a newly created keymap, it should be linked to @t{main}.  Hence
+the sequence of commands to create and use a new keymap `@t{mymap}'
+initialized from the @t{emacs} keymap (which remains unchanged) is:
+
+@noindent
+@example
+bindkey -N mymap emacs
+bindkey -A mymap main
+@end example
+
+@noindent
+Note that while `@t{bindkey -A} @var{newmap} @t{main}' will work when
+@var{newmap} is @t{emacs} or @t{viins}, it will not work for @t{vicmd}, as
+switching from vi insert to command mode becomes impossible.
+
+@noindent
+The following operations act on the `@t{main}' keymap if no keymap
+selection option was given:
+
+@noindent
+@table @asis
+@item @t{-m}
+Add the built-in set of meta-key bindings to the selected keymap.
+Only keys that are unbound or bound to @t{self-insert} are affected.
+
+@item @t{-r} @var{in-string} ...
+Unbind the specified @var{in-string}s in the selected keymap.
+This is exactly equivalent to binding the strings to @t{undefined-key}.
+
+@noindent
+When @t{-R} is also used, interpret the @var{in-string}s as ranges.
+
+@noindent
+When @t{-p} is also used, the @var{in-string}s specify prefixes.  Any
+binding that has the given @var{in-string} as a prefix, not including the
+binding for the @var{in-string} itself, if any, will be removed.  For
+example,
+
+@noindent
+@example
+bindkey -rpM viins '^['
+@end example
+
+@noindent
+will remove all bindings in the vi-insert keymap beginning with an escape
+character (probably cursor keys), but leave the binding for the escape
+character itself (probably @t{vi-cmd-mode}).  This is incompatible with the
+option @t{-R}.
+
+@item @t{-s} @var{in-string out-string} ...
+Bind each @var{in-string} to each @var{out-string}.
+When @var{in-string} is typed, @var{out-string} will be
+pushed back and treated as input to the line editor.
+When @t{-R} is also used, interpret the @var{in-string}s as ranges.
+
+@item @var{in-string command} ...
+Bind each @var{in-string} to each @var{command}.
+When @t{-R} is used, interpret the @var{in-string}s as ranges.
+
+@item [ @var{in-string} ]
+List key bindings.  If an @var{in-string} is specified, the binding of
+that string in the selected keymap is displayed.  Otherwise, all key
+bindings in the selected keymap are displayed.  (As a special case,
+if the @t{-e} or @t{-v} option is used alone, the keymap is @emph{not}
+displayed - the implicit linking of keymaps is the only thing that
+happens.)
+
+@noindent
+When the option @t{-p} is used, the @var{in-string} must be present.
+The listing shows all bindings which have the given key sequence as a
+prefix, not including any bindings for the key sequence itself.
+
+@noindent
+When the @t{-L} option is used, the list is in the form of @t{bindkey}
+commands to create the key bindings.
+
+@end table
+
+@noindent
+When the @t{-R} option is used as noted above, a valid range consists of
+two characters, with an optional `@t{-}' between them.  All characters
+between the two specified, inclusive, are bound as specified.
+
+@noindent
+For either @var{in-string} or @var{out-string}, the following
+escape sequences are recognised:
+
+@noindent
+@table @asis
+@item @t{\a}
+bell character
+@item @t{\b}
+backspace
+@item @t{\e}, @t{\E}
+escape
+@item @t{\f}
+form feed
+@item @t{\n}
+linefeed (newline)
+@item @t{\r}
+carriage return
+@item @t{\t}
+horizontal tab
+@item @t{\v}
+vertical tab
+@item @t{\}@var{NNN}
+character code in octal
+@item @t{\x}@var{NN}
+character code in hexadecimal
+@item @t{\M}[@t{-}]@var{X}
+character with meta bit set
+@item @t{\C}[@t{-}]@var{X}
+control character
+@item @t{^}@var{X}
+control character
+@end table
+
+@noindent
+In all other cases, `@t{\}' escapes the following character.  Delete is
+written as `@t{^?}'.  Note that `@t{\M^?}' and `@t{^\M?}' are not the same,
+and that (unlike emacs), the bindings `@t{\M-}@var{X}' and `@t{\e}@var{X}'
+are entirely distinct, although they are initialized to the same bindings
+by `@t{bindkey -m}'.
+
+@findex vared
+@cindex parameters, editing
+@cindex editing parameters
+@item @t{vared} [ @t{-Aache} ] [ @t{-p} @var{prompt} ] [ @t{-r} @var{rprompt} ]
+@itemx   [ -M @var{main-keymap} ] [ -m @var{vicmd-keymap} ] @var{name}
+The value of the parameter @var{name} is loaded into the edit
+buffer, and the line editor is invoked.  When the editor exits,
+@var{name} is set to the string value returned by the editor.
+When the @t{-c} flag is given, the parameter is created if it doesn't
+already exist.  The @t{-a} flag may be given with @t{-c} to create
+an array parameter, or the @t{-A} flag to create an associative array.
+If the type of an existing parameter does not match the type to be
+created, the parameter is unset and recreated.
+
+@noindent
+If an array or array slice is being edited, separator characters as defined
+in @t{$IFS} will be shown quoted with a backslash, as will backslashes
+themselves.  Conversely, when the edited text is split into an array, a
+backslash quotes an immediately following separator character or backslash;
+no other special handling of backslashes, or any handling of quotes, is
+performed.
+
+@noindent
+Individual elements of existing array or associative array parameters
+may be edited by using subscript syntax on @var{name}.  New elements are
+created automatically, even without @t{-c}.
+
+@noindent
+If the @t{-p} flag is given, the following string will be taken as
+the prompt to display at the left.  If the @t{-r} flag is given,
+the following string gives the prompt to display at the right.  If the
+@t{-h} flag is specified, the history can be accessed from ZLE. If the
+@t{-e} flag is given, typing @t{^D} (Control-D) on an empty line
+causes @t{vared} to exit immediately with a non-zero return value.
+
+@noindent
+The @t{-M} option gives a keymap to link to the @t{main} keymap during
+editing, and the @t{-m} option gives a keymap to link to the @t{vicmd}
+keymap during editing.  For vi-style editing, this allows a pair of keymaps
+to override @t{viins} and @t{vicmd}.  For emacs-style editing, only @t{-M}
+is normally needed but the @t{-m} option may still be used.  On exit, the
+previous keymaps will be restored.
+
+@findex zle
+@cindex widgets, rebinding
+@cindex rebinding widgets
+@cindex widgets, binding
+@cindex binding widgets
+@cindex widgets, invoking
+@cindex invoking widgets
+@cindex widgets, calling
+@cindex calling widgets
+@cindex widgets, defining
+@cindex defining widgets
+@item @t{zle}
+@itemx @t{zle} @t{-l} [ @t{-L} | @t{-a} ] [ @var{string} ... ]
+@itemx @t{zle} @t{-D} @var{widget} ...
+@itemx @t{zle} @t{-A} @var{old-widget} @var{new-widget}
+@itemx @t{zle} @t{-N} @var{widget} [ @var{function} ]
+@itemx @t{zle} @t{-C} @var{widget} @var{completion-widget} @var{function}
+@itemx @t{zle} @t{-R} [ @t{-c} ] [ @var{display-string} ] [ @var{string} ... ]
+@itemx @t{zle} @t{-M} @var{string}
+@itemx @t{zle} @t{-U} @var{string}
+@itemx @t{zle} @t{-K} @var{keymap}
+@itemx @t{zle} @t{-F} [ @t{-L} ] [ @var{fd} [ @var{handler} ] ]
+@itemx @t{zle} @t{-I}
+@itemx @t{zle} @var{widget} @t{[ -n} @var{num} @t{]} @t{[ -N ]} @var{args} ...
+The @t{zle} builtin performs a number of different actions concerning
+ZLE.
+
+@noindent
+With no options and no arguments, only the return status will be
+set.  It is zero if ZLE is currently active and widgets could be
+invoked using this builtin command and non-zero otherwise.
+Note that even if non-zero status is returned, zle may still be active as
+part of the completion system; this does not allow direct calls to ZLE
+widgets.
+
+@noindent
+Otherwise, which operation it performs depends on its options:
+
+@noindent
+@table @asis
+@item @t{-l} [ @t{-L} | @t{-a} ]
+List all existing user-defined widgets.  If the @t{-L}
+option is used, list in the form of @t{zle}
+commands to create the widgets.
+
+@noindent
+When combined with the @t{-a} option, all widget names are listed,
+including the builtin ones. In this case the @t{-L} option is ignored.
+
+@noindent
+If at least one @var{string} is given, nothing will be printed but the
+return status will be zero if all @var{string}s are names of existing
+widgets (or of user-defined widgets if the @t{-a} flag is not given)
+and non-zero if at least one @var{string} is not a name of an defined
+widget.
+
+@item @t{-D} @var{widget} ...
+Delete the named @var{widget}s.
+
+@item @t{-A} @var{old-widget} @var{new-widget}
+Make the @var{new-widget} name an alias for @var{old-widget}, so that
+both names refer to the same widget.  The names have equal standing;
+if either is deleted, the other remains.  If there is already a widget
+with the @var{new-widget} name, it is deleted.
+
+@item @t{-N} @var{widget} [ @var{function} ]
+Create a user-defined widget.  If there is already a widget with the
+specified name, it is overwritten.  When the new
+widget is invoked from within the editor, the specified shell @var{function}
+is called.  If no function name is specified, it defaults to
+the same name as the widget.  For further information, see the section
+@emph{Widgets} in
+@ref{Zsh Line Editor}.
+
+@cindex completion widgets, creating
+@item @t{-C} @var{widget} @var{completion-widget} @var{function}
+Create a user-defined completion widget named @var{widget}. The 
+completion widget will behave like the built-in completion-widget
+whose name is given as @var{completion-widget}. To generate the
+completions, the shell function @var{function} will be called.
+For further information, see
+@ref{Completion Widgets}.
+
+@item @t{-R} [ @t{-c} ] [ @var{display-string} ] [ @var{string} ... ]
+Redisplay the command line; this is to be called from within a user-defined
+widget to allow changes to become visible.  If a @var{display-string} is
+given and not empty, this is shown in the status line (immediately
+below the line being edited).
+
+@noindent
+If the optional @var{string}s are given they are listed below the
+prompt in the same way as completion lists are printed. If no
+@var{string}s are given but the @t{-c} option is used such a list is
+cleared.
+
+@noindent
+Note that this option is only useful for widgets that do not exit
+immediately after using it because the strings displayed will be erased 
+immediately after return from the widget.
+
+@noindent
+This command can safely be called outside user defined widgets; if zle is
+active, the display will be refreshed, while if zle is not active, the
+command has no effect.  In this case there will usually be no other
+arguments.
+
+@noindent
+The status is zero if zle was active, else one.
+
+@item @t{-M} @var{string}
+As with the @t{-R} option, the @var{string} will be displayed below the 
+command line; unlike the @t{-R} option, the string will not be put into
+the status line but will instead be printed normally below the
+prompt.  This means that the @var{string} will still be displayed after
+the widget returns (until it is overwritten by subsequent commands).
+
+@item @t{-U} @var{string}
+This pushes the characters in the @var{string} onto the input stack of
+ZLE.  After the widget currently executed finishes ZLE will behave as
+if the characters in the @var{string} were typed by the user.
+
+@noindent
+As ZLE uses a stack, if this option is used repeatedly
+the last string pushed onto the stack will be processed first.  However,
+the characters in each @var{string} will be processed in the order in which
+they appear in the string.
+
+@item @t{-K} @var{keymap}
+Selects the keymap named @var{keymap}.  An error message will be displayed if
+there is no such keymap.
+
+@noindent
+This keymap selection affects the interpretation of following keystrokes
+within this invocation of ZLE.  Any following invocation (e.g., the next
+command line) will start as usual with the `@t{main}' keymap selected.
+
+@item @t{-F} [ @t{-L} ] [ @var{fd} [ @var{handler} ] ]
+Only available if your system supports one of the `poll' or `select' system
+calls; most modern systems do.
+
+@noindent
+Installs @var{handler} (the name of a shell function) to handle input from
+file descriptor @var{fd}.  When zle is attempting to read data, it will
+examine both the terminal and the list of handled @var{fd}'s.  If data
+becomes available on a handled @var{fd}, zle will call @var{handler} with
+the fd which is ready for reading as the only argument.  If the handler
+produces output to the terminal, it should call `@t{zle -I}' before doing
+so (see below).  The handler should not attempt to read from the terminal.
+Note that zle makes no attempt to check whether this fd is actually
+readable when installing the handler.  The user must make their own
+arrangements for handling the file descriptor when zle is not active.
+
+@noindent
+Any number of handlers for any number of readable file descriptors may be
+installed.  Installing a handler for an @var{fd} which is already handled
+causes the existing handler to be replaced.
+
+@noindent
+If no @var{handler} is given, but an @var{fd} is present, any handler for
+that @var{fd} is removed.  If there is none, an error message is printed
+and status 1 is returned.
+
+@noindent
+If no arguments are given, or the @t{-L} option is supplied, a list of
+handlers is printed in a form which can be stored for later execution.
+
+@noindent
+An @var{fd} (but not a @var{handler}) may optionally be given with the @t{-L}
+option; in this case, the function will list the handler if any, else
+silently return status 1.
+
+@noindent
+Note that this feature should be used with care.  Activity on one of the
+@var{fd}'s which is not properly handled can cause the terminal to become
+unusable.
+
+@noindent
+Here is a simple example of using this feature.  A connection to a remote
+TCP port is created using the ztcp command; see 
+@ref{The zsh/net/tcp Module}.  Then a handler is installed
+which simply prints out any data which arrives on this connection.  Note
+that `select' will indicate that the file descriptor needs handling
+if the remote side has closed the connection; we handle that by testing
+for a failed read.
+@example
+if ztcp pwspc 2811; then
+  tcpfd=$REPLY
+  handler() @{
+    zle -I
+    local line
+    if ! read -r line <&$1; then
+      # select marks this fd if we reach EOF,
+      # so handle this specially.
+      print "[Read on fd $1 failed, removing.]" >&2
+      zle -F $1
+      return 1
+    fi
+    print -r - $line
+  @}
+  zle -F $tcpfd handler
+fi
+@end example
+
+@item @t{-I}
+Unusually, this option is most useful outside ordinary widget functions,
+though it may be used within if normal output to the terminal is required.
+It invalidates the current zle display in preparation for output; typically
+this will be from a trap function.  It has no effect if zle is not
+active.  When a trap exits, the shell checks to see if the display needs
+restoring, hence the following will print output in such a way as not to
+disturb the line being edited:
+
+@noindent
+@example
+TRAPUSR1() @{
+    # Invalidate zle display
+  [[ -o zle ]] && zle -I
+    # Show output
+  print Hello
+@}
+@end example
+
+@noindent
+In general, the trap function may need to test whether zle is active before
+using this method (as shown in the example), since the @t{zsh/zle} module
+may not even be loaded; if it is not, the command can be skipped.
+
+@noindent
+It is possible to call `@t{zle -I}' several times before control is
+returned to the editor; the display will only be invalidated the first time
+to minimise disruption.
+
+@noindent
+Note that there are normally better ways of manipulating the display from
+within zle widgets; see, for example, `@t{zle -R}' above.
+
+@noindent
+The returned status is zero if zle was invalidated, even though
+this may have been by a previous call to `@t{zle -I}' or by a system
+notification.  To test if a zle widget may be called at this point, execute
+@t{zle} with no arguments and examine the return status.
+
+@item @var{widget} @t{[ -n} @var{num} @t{]} @t{[ -N ]} @var{args} ...
+Invoke the specified widget.  This can only be done when ZLE is
+active; normally this will be within a user-defined widget.
+
+@noindent
+With the options @t{-n} and @t{-N}, the current numerical argument will be
+saved and then restored after the call to @t{widget}; `@t{-n} @var{num}'
+sets the numerical argument temporarily to @var{num}, while `@t{-N}' sets it
+to the default, i.e. as if there were none.
+
+@noindent
+Any further arguments will be passed to the widget.  If it is a shell
+function, these are passed down as positional parameters; for builtin
+widgets it is up to the widget in question what it does with them.
+Currently arguments are only handled by the incremental-search commands,
+the @t{history-search-forward} and @t{-backward} and the corresponding
+functions prefixed by @t{vi-}, and by @t{universal-argument}.  No error is
+flagged if the command does not use the arguments, or only uses some of
+them.
+
+@noindent
+The return status reflects the success or failure of the operation carried
+out by the widget, or if it is a user-defined widget the return status of
+the shell function.  
+
+@noindent
+A non-zero return status causes the shell to beep when the widget exits,
+unless the @t{BEEP} options was unset or the widget was called via the
+@t{zle} command.  Thus if a user defined widget requires an immediate beep,
+it should call the @t{beep} widget directly.
+
+@end table
+
+@end table
+
+@noindent
+@node Zle Widgets, , Zle Builtins, Zsh Line Editor
+
+@section Widgets
+@noindent
+@cindex widgets
+All actions in the editor are performed by `widgets'.  A widget's job is
+simply to perform some small action.  The ZLE commands that key sequences
+in keymaps are bound to are in fact widgets.  Widgets can be user-defined
+or built in.
+
+@noindent
+The standard widgets built in to ZLE are listed in Standard Widgets below.
+Other built-in widgets can be defined by other modules (see
+@ref{Zsh Modules}).  Each built-in widget has two names: its normal canonical name, and the
+same name preceded by a `@t{.}'.  The `@t{.}' name is special: it can't be
+rebound to a different widget.  This makes the widget available even when
+its usual name has been redefined.
+
+@noindent
+User-defined widgets are defined using `@t{zle -N}', and implemented
+as shell functions.  When the widget is executed, the corresponding
+shell function is executed, and can perform editing (or other) actions.
+It is recommended that user-defined widgets should not have names
+starting with `@t{.}'.
+
+@section User-Defined Widgets
+@noindent
+@cindex widgets, user-defined
+User-defined widgets, being implemented as shell functions,
+can execute any normal shell command.  They can also run other widgets
+(whether built-in or user-defined) using the @t{zle} builtin command.
+The standard input of the function is closed to prevent external commands
+from unintentionally blocking ZLE by reading from the terminal, but
+@t{read -k} or @t{read -q} can be used to read characters.  Finally,
+they can examine and edit the ZLE buffer being edited by
+reading and setting the special parameters described below.
+
+@noindent
+@cindex parameters, editor
+@cindex parameters, zle
+These special parameters are always available in widget functions, but
+are not in any way special outside ZLE.  If they have some normal value
+outside ZLE, that value is temporarily inaccessible, but will return
+when the widget function exits.  These special parameters in fact have
+local scope, like parameters created in a function using @t{local}.
+
+@noindent
+Inside completion widgets and traps called while ZLE is active, these
+parameters are available read-only.
+
+@noindent
+@table @asis
+@vindex BUFFER
+@item @t{BUFFER} (scalar)
+The entire contents of the edit buffer.  If it is written to, the
+cursor remains at the same offset, unless that would put it outside the
+buffer.
+
+@vindex BUFFERLINES
+@item @t{BUFFERLINES} (integer)
+The number of screen lines needed for the edit buffer currently
+displayed on screen (i.e. without any changes to the preceding
+parameters done after the last redisplay); read-only.
+
+@vindex CONTEXT
+@item @t{CONTEXT} (scalar)
+The context in which zle was called to read a line; read-only.  One of
+the values:
+@table @asis
+@item start
+The start of a command line (at prompt @t{PS1}).
+
+@item cont
+A continuation to a command line (at prompt @t{PS2}).
+
+@item select
+In a @t{select} loop.
+
+@item vared
+Editing a variable in @t{vared}.
+
+@end table
+
+@vindex CURSOR
+@item @t{CURSOR} (integer)
+The offset of the cursor, within the edit buffer.  This is in the range
+0 to @t{$#BUFFER}, and is by definition equal to @t{$#LBUFFER}.
+Attempts to move the cursor outside the buffer will result in the
+cursor being moved to the appropriate end of the buffer.
+
+@vindex CUTBUFFER
+@item @t{CUTBUFFER} (scalar)
+The last item to be cut using one of the `@t{kill-}' commands; the
+string which the next yank would insert in the line.
+
+@vindex HISTNO
+@item @t{HISTNO} (integer)
+The current history number.  Setting this has the same effect as
+moving up or down in the history to the corresponding history line.
+An attempt to set it is ignored if the line is not stored in the
+history.  Note this is not the same as the parameter @t{HISTCMD},
+which always gives the number of the history line being added to the main
+shell's history.  @t{HISTNO} refers to the line being retrieved within
+zle.
+
+@vindex KEYMAP
+@item @t{KEYMAP} (scalar)
+The name of the currently selected keymap; read-only.
+
+@vindex KEYS
+@item @t{KEYS} (scalar)
+The keys typed to invoke this widget, as a literal string; read-only.
+
+@vindex killring
+@item @t{killring} (array)
+The array of previously killed items, with the most recently killed first.
+This gives the items that would be retrieved by a @t{yank-pop} in the
+same order.
+
+@noindent
+The default size for the kill ring is eight, however the length may be
+changed by normal array operations.  Any empty string in the kill ring is
+ignored by the @t{yank-pop} command, hence the size of the array
+effectively sets the maximum length of the kill ring, while the number of
+non-zero strings gives the current length, both as seen by the user at the
+command line.
+
+
+@noindent
+@vindex LASTSEARCH
+@item @t{LASTSEARCH} (scalar)
+The last search string used by an interactive search ; read-only.
+
+@vindex LASTWIDGET
+@item @t{LASTWIDGET} (scalar)
+The name of the last widget that was executed; read-only.
+
+@vindex LBUFFER
+@item @t{LBUFFER} (scalar)
+The part of the buffer that lies to the left of the cursor position.
+If it is assigned to, only that part of the buffer is replaced, and the
+cursor remains between the new @t{$LBUFFER} and the old @t{$RBUFFER}.
+
+@vindex MARK
+@item @t{MARK} (integer)
+Like @t{CURSOR}, but for the mark.
+
+@vindex NUMERIC
+@item @t{NUMERIC} (integer)
+The numeric argument. If no numeric argument was given, this parameter
+is unset. When this is set inside a widget function, builtin widgets
+called with the @t{zle} builtin command will use the value
+assigned. If it is unset inside a widget function, builtin widgets
+called behave as if no numeric argument was given.
+
+@vindex PENDING
+@item @t{PENDING} (integer)
+The number of bytes pending for input, i.e. the number of bytes which have
+already been typed and can immediately be read. On systems where the shell
+is not able to get this information, this parameter will always have a
+value of zero.  Read-only.
+
+@vindex PREBUFFER
+@item @t{PREBUFFER} (scalar)
+In a multi-line input at the secondary prompt, this read-only parameter
+contains the contents of the lines before the one the cursor is
+currently in.
+
+@vindex PREDISPLAY
+@item @t{PREDISPLAY} (scalar)
+Text to be displayed before the start of the editable text buffer.  This
+does not have to be a complete line; to display a complete line, a newline
+must be appended explicitly.    The text is reset on each new invocation
+(but not recursive invocation) of zle.
+
+@vindex POSTDISPLAY
+@item @t{POSTDISPLAY} (scalar)
+Text to be displayed after the end of the editable text buffer.  This
+does not have to be a complete line; to display a complete line, a newline
+must be prepended explicitly.  The text is reset on each new invocation
+(but not recursive invocation) of zle.
+
+@vindex RBUFFER
+@item @t{RBUFFER} (scalar)
+The part of the buffer that lies to the right of the cursor position.
+If it is assigned to, only that part of the buffer is replaced, and the
+cursor remains between the old @t{$LBUFFER} and the new @t{$RBUFFER}.
+
+@vindex WIDGET
+@item @t{WIDGET} (scalar)
+The name of the widget currently being executed; read-only.
+
+@vindex WIDGETFUNC
+@item @t{WIDGETFUNC} (scalar)
+The name of the shell function that implements a widget defined with
+either @t{zle -N} or @t{zle -C}.  In the former case, this is the second
+argument to the @t{zle -N} command that defined the widget, or
+the first argument if there was no second argument.  In the latter case
+this is the the third argument to the @t{zle -C} command that defined the
+widget.  Read-only.
+
+@vindex WIDGETSTYLE
+@item @t{WIDGETSTYLE} (scalar)
+Describes the implementation behind the completion widget currently being
+executed; the second argument that followed @t{zle -C} when the widget was
+defined.  This is the name of a builtin completion widget.  For widgets
+defined with @t{zle -N} this is set to the empty string.  Read-only.
+
+@end table
+
+@noindent
+
+@subsection Special Widget
+@noindent
+
+@noindent
+There is one user-defined widget which is special to the shell.
+If it does not exist, no special action is taken.  The environment
+provided is identical to that for any other editing widget.
+
+@noindent
+@table @asis
+@tindex zle-line-init
+@item @t{zle-line-init}
+Executed every time the line editor is started to read a new line
+of input.  The following example puts the line editor into vi command
+mode when it starts up.
+
+@noindent
+@example
+zle-line-init() @{ zle -K vicmd; @}
+zle -N zle-line-init
+@end example
+
+@noindent
+(The command inside the function sets the keymap directly; it is
+equivalent to @t{zle vi-cmd-mode}.)
+
+@end table
+
+@noindent
+
+@section Standard Widgets
+@noindent
+@cindex widgets, standard
+The following is a list of all the standard widgets,
+and their default bindings in emacs mode,
+vi command mode and vi insert mode
+(the `@t{emacs}', `@t{vicmd}' and `@t{viins}' keymaps, respectively).
+
+@noindent
+Note that cursor keys are bound to movement keys in all three keymaps;
+the shell assumes that the cursor keys send the key sequences reported
+by the terminal-handling library (termcap or terminfo).  The key sequences
+shown in the list are those based on the VT100, common on many modern
+terminals, but in fact these are not necessarily bound.  In the case of the
+@t{viins} keymap, the initial escape character of the sequences serves also
+to return to the @t{vicmd} keymap: whether this happens is determined by
+the @t{KEYTIMEOUT} parameter, see @ref{Parameters}.
+@menu
+* Movement::
+* History Control::
+* Modifying Text::
+* Arguments::
+* Completion::
+* Miscellaneous::
+@end menu
+@node Movement, History Control, , Zle Widgets
+
+@subsection Movement
+@noindent
+@table @asis
+@tindex vi-backward-blank-word
+@item @t{vi-backward-blank-word} (unbound) (B) (unbound)
+Move backward one word, where a word is defined as a series of
+non-blank characters.
+
+@tindex backward-char
+@item @t{backward-char} (^B ESC-[D) (unbound) (unbound)
+Move backward one character.
+
+@tindex vi-backward-char
+@item @t{vi-backward-char} (unbound) (^H h ^?) (ESC-[D)
+Move backward one character, without changing lines.
+
+@tindex backward-word
+@item @t{backward-word} (ESC-B ESC-b) (unbound) (unbound)
+Move to the beginning of the previous word.
+
+@tindex emacs-backward-word
+@item @t{emacs-backward-word}
+Move to the beginning of the previous word.
+
+@tindex vi-backward-word
+@item @t{vi-backward-word} (unbound) (b) (unbound)
+Move to the beginning of the previous word, vi-style.
+
+@tindex beginning-of-line
+@item @t{beginning-of-line} (^A) (unbound) (unbound)
+Move to the beginning of the line.  If already at the beginning
+of the line, move to the beginning of the previous line, if any.
+
+@tindex vi-beginning-of-line
+@item @t{vi-beginning-of-line}
+Move to the beginning of the line, without changing lines.
+
+@tindex end-of-line
+@item @t{end-of-line} (^E) (unbound) (unbound)
+Move to the end of the line.  If already at the end
+of the line, move to the end of the next line, if any.
+
+@tindex vi-end-of-line
+@item @t{vi-end-of-line} (unbound) ($) (unbound)
+Move to the end of the line.
+If an argument is given to this command, the cursor will be moved to
+the end of the line (argument - 1) lines down.
+
+@tindex vi-forward-blank-word
+@item @t{vi-forward-blank-word} (unbound) (W) (unbound)
+Move forward one word, where a word is defined as a series of
+non-blank characters.
+
+@tindex vi-forward-blank-word-end
+@item @t{vi-forward-blank-word-end} (unbound) (E) (unbound)
+Move to the end of the current word, or, if at the end of the current word,
+to the end of the next word,
+where a word is defined as a series of non-blank characters.
+
+@tindex forward-char
+@item @t{forward-char} (^F ESC-[C) (unbound) (unbound)
+Move forward one character.
+
+@tindex vi-forward-char
+@item @t{vi-forward-char} (unbound) (space l) (ESC-[C)
+Move forward one character.
+
+@tindex vi-find-next-char
+@item @t{vi-find-next-char} (^X^F) (f) (unbound)
+Read a character from the keyboard, and move to
+the next occurrence of it in the line.
+
+@tindex vi-find-next-char-skip
+@item @t{vi-find-next-char-skip} (unbound) (t) (unbound)
+Read a character from the keyboard, and move to
+the position just before the next occurrence of it in the line.
+
+@tindex vi-find-prev-char
+@item @t{vi-find-prev-char} (unbound) (F) (unbound)
+Read a character from the keyboard, and move to
+the previous occurrence of it in the line.
+
+@tindex vi-find-prev-char-skip
+@item @t{vi-find-prev-char-skip} (unbound) (T) (unbound)
+Read a character from the keyboard, and move to
+the position just after the previous occurrence of it in the line.
+
+@tindex vi-first-non-blank
+@item @t{vi-first-non-blank} (unbound) (^) (unbound)
+Move to the first non-blank character in the line.
+
+@tindex vi-forward-word
+@item @t{vi-forward-word} (unbound) (w) (unbound)
+Move forward one word, vi-style.
+
+@tindex forward-word
+@item @t{forward-word} (ESC-F ESC-f) (unbound) (unbound)
+Move to the beginning of the next word.
+The editor's idea of a word is specified with the @t{WORDCHARS}
+parameter.
+
+@tindex emacs-forward-word
+@item @t{emacs-forward-word}
+Move to the end of the next word.
+
+@tindex vi-forward-word-end
+@item @t{vi-forward-word-end} (unbound) (e) (unbound)
+Move to the end of the next word.
+
+@tindex vi-goto-column
+@item @t{vi-goto-column} (ESC-|) (|) (unbound)
+Move to the column specified by the numeric argument.
+
+@tindex vi-goto-mark
+@item @t{vi-goto-mark} (unbound) (`) (unbound)
+Move to the specified mark.
+
+@tindex vi-goto-mark-line
+@item @t{vi-goto-mark-line} (unbound) (') (unbound)
+Move to beginning of the line containing the specified mark.
+
+@tindex vi-repeat-find
+@item @t{vi-repeat-find} (unbound) (;) (unbound)
+Repeat the last @t{vi-find} command.
+
+@tindex vi-rev-repeat-find
+@item @t{vi-rev-repeat-find} (unbound) (,) (unbound)
+Repeat the last @t{vi-find} command in the opposite direction.
+
+@end table
+@node History Control, Modifying Text, Movement, Zle Widgets
+
+@subsection History Control
+@noindent
+@table @asis
+@tindex beginning-of-buffer-or-history
+@item @t{beginning-of-buffer-or-history} (ESC-<) (unbound) (unbound)
+Move to the beginning of the buffer, or if already there,
+move to the first event in the history list.
+
+@tindex beginning-of-line-hist
+@item @t{beginning-of-line-hist}
+Move to the beginning of the line.  If already at the
+beginning of the buffer, move to the previous history line.
+
+@tindex beginning-of-history
+@item @t{beginning-of-history}
+Move to the first event in the history list.
+
+@tindex down-line-or-history
+@item @t{down-line-or-history} (^N ESC-[B) (j) (ESC-[B)
+Move down a line in the buffer, or if already at the bottom line,
+move to the next event in the history list.
+
+@tindex vi-down-line-or-history
+@item @t{vi-down-line-or-history} (unbound) (+) (unbound)
+Move down a line in the buffer, or if already at the bottom line,
+move to the next event in the history list.
+Then move to the first non-blank character on the line.
+
+@tindex down-line-or-search
+@item @t{down-line-or-search}
+Move down a line in the buffer, or if already at the bottom line,
+search forward in the history for a line beginning with the first
+word in the buffer.
+
+@noindent
+If called from a function by the @t{zle} command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
+
+@tindex down-history
+@item @t{down-history} (unbound) (^N) (unbound)
+Move to the next event in the history list.
+
+@tindex history-beginning-search-backward
+@item @t{history-beginning-search-backward}
+Search backward in the history for a line beginning with the current
+line up to the cursor.
+This leaves the cursor in its original position.
+
+@tindex end-of-buffer-or-history
+@item @t{end-of-buffer-or-history} (ESC->) (unbound) (unbound)
+Move to the end of the buffer, or if already there,
+move to the last event in the history list.
+
+@tindex end-of-line-hist
+@item @t{end-of-line-hist}
+Move to the end of the line.  If already at the end of
+the buffer, move to the next history line.
+
+@tindex end-of-history
+@item @t{end-of-history}
+Move to the last event in the history list.
+
+@tindex vi-fetch-history
+@item @t{vi-fetch-history} (unbound) (G) (unbound)
+Fetch the history line specified by the numeric argument.
+This defaults to the current history line
+(i.e. the one that isn't history yet).
+
+@tindex history-incremental-search-backward
+@item @t{history-incremental-search-backward} (^R ^Xr) (unbound) (unbound)
+Search backward incrementally for a specified string.  The search is
+case-insensitive if the search string does not have uppercase letters and no
+numeric argument was given.  The string may begin with `@t{^}' to anchor the
+search to the beginning of the line.
+
+@noindent
+A restricted set of editing functions
+is available in the mini-buffer.  An interrupt signal, as defined by the stty
+setting, will stop the search and go back to the original line.  An undefined
+key will have the same effect. The supported functions are:
+@t{backward-delete-char},
+@t{vi-backward-delete-char},
+@t{clear-screen},
+@t{redisplay},
+@t{quoted-insert},
+@t{vi-quoted-insert},
+@t{accept-and-hold},
+@t{accept-and-infer-next-history},
+@t{accept-line} and
+@t{accept-line-and-down-history}.
+
+@noindent
+@t{magic-space} just inserts a space.
+@t{vi-cmd-mode} toggles between the `@t{main}' and `@t{vicmd}' keymaps;
+the `@t{main}' keymap (insert mode) will be selected initially.
+@t{history-incremental-search-backward} will get the
+next occurrence of the contents of the mini-buffer.
+@t{history-incremental-search-forward} inverts the sense of the search.
+@t{vi-repeat-search} and @t{vi-rev-repeat-search} are similarly supported.
+The direction of the search is indicated in the mini-buffer.
+
+@noindent
+Any multi-character string
+that is not bound to one of the above functions will beep and interrupt the
+search, leaving the last found line in the buffer. Any single character that
+is not bound to one of the above functions, or @t{self-insert} or
+@t{self-insert-unmeta}, will have the same effect but the function will be
+executed.
+
+@noindent
+When called from a widget function by the @t{zle} command, the incremental
+search commands can take a string argument.  This will be treated as a
+string of keys, as for arguments to the @t{bindkey} command, and used as
+initial input for the command.  Any characters in the string which are
+unused by the incremental search will be silently ignored.  For example,
+
+@noindent
+@example
+zle history-incremental-search-backward forceps
+@end example
+
+@noindent
+will search backwards for @t{forceps}, leaving the minibuffer containing
+the string `@t{forceps}'.
+
+@tindex history-incremental-search-forward
+@item @t{history-incremental-search-forward} (^S ^Xs) (unbound) (unbound)
+Search forward incrementally for a specified string.  The search is
+case-insensitive if the search string does not have uppercase letters and no
+numeric argument was given.  The string may begin with `@t{^}' to anchor the
+search to the beginning of the line.  The functions available in the
+mini-buffer are the same as for @t{history-incremental-search-backward}.
+
+@tindex history-search-backward
+@item @t{history-search-backward} (ESC-P ESC-p) (unbound) (unbound)
+Search backward in the history for a line beginning with the first
+word in the buffer.
+
+@noindent
+If called from a function by the @t{zle} command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
+
+@tindex vi-history-search-backward
+@item @t{vi-history-search-backward} (unbound) (/) (unbound)
+Search backward in the history for a specified string.
+The string may begin with `@t{^}' to anchor the search to the
+beginning of the line.
+
+@noindent
+A restricted set of editing functions is available in
+the mini-buffer.  An interrupt signal, as defined by the stty setting,  will
+stop the search.
+The functions available in the mini-buffer are:
+@t{accept-line},
+@t{backward-delete-char},
+@t{vi-backward-delete-char},
+@t{backward-kill-word},
+@t{vi-backward-kill-word},
+@t{clear-screen},
+@t{redisplay},
+@t{quoted-insert}
+and
+@t{vi-quoted-insert}.
+
+@noindent
+@t{vi-cmd-mode} is treated the same as accept-line, and
+@t{magic-space} is treated as a space.
+Any other character that is not bound to self-insert or
+self-insert-unmeta will beep and be ignored. If the function is called from vi
+command mode, the bindings of the current insert mode will be used.
+
+@noindent
+If called from a function by the @t{zle} command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
+
+@tindex history-search-forward
+@item @t{history-search-forward} (ESC-N ESC-n) (unbound) (unbound)
+Search forward in the history for a line beginning with the first
+word in the buffer.
+
+@noindent
+If called from a function by the @t{zle} command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
+
+@tindex vi-history-search-forward
+@item @t{vi-history-search-forward} (unbound) (?) (unbound)
+Search forward in the history for a specified string.
+The string may begin with `@t{^}' to anchor the search to the
+beginning of the line. The functions available in the mini-buffer are the same
+as for @t{vi-history-search-backward}.  Argument handling is also the same
+as for that command.
+
+@tindex infer-next-history
+@item @t{infer-next-history} (^X^N) (unbound) (unbound)
+Search in the history list for a line matching the current one and
+fetch the event following it.
+
+@tindex insert-last-word
+@item @t{insert-last-word} (ESC-_ ESC-.) (unbound) (unbound)
+Insert the last word from the previous history event at the
+cursor position.  If a positive numeric argument is given,
+insert that word from the end of the previous history event.
+If the argument is zero or negative insert that word from the
+left (zero inserts the previous command word).  Repeating this command
+replaces the word just inserted with the last word from the
+history event prior to the one just used; numeric arguments can be used in
+the same way to pick a word from that event.
+
+@noindent
+When called from a shell function invoked from a user-defined widget, the
+command can take one to three arguments.  The first argument specifies a
+history offset which applies to successive calls to this widget: if is -1,
+the default behaviour is used, while if it is 1, successive calls will move
+forwards through the history.  The value 0 can be used to indicate that the
+history line examined by the previous execution of the command will be
+reexamined.  Note that negative numbers should be preceded with a
+`@t{-}@t{-}' argument to avoid confusing them with options.
+
+@noindent
+If two arguments are given, the second specifies the word on the command
+line in normal array index notation (as a more natural alternative to the
+prefix argument).  Hence 1 is the first word, and -1 (the default) is the
+last word.
+
+@noindent
+If a third argument is given, its value is ignored, but it is used to
+signify that the history offset is relative to the current history line,
+rather than the one remembered after the previous invocations of
+@t{insert-last-word}.
+
+@noindent
+For example, the default behaviour of the command corresponds to
+
+@noindent
+@example
+zle insert-last-word -- -1 -1
+@end example
+
+@noindent
+while the command
+
+@noindent
+@example
+zle insert-last-word -- -1 1 -
+@end example
+
+@noindent
+always copies the first word of the line in the history immediately before
+the line being edited.  This has the side effect that later invocations of
+the widget will be relative to that line.
+
+@tindex vi-repeat-search
+@item @t{vi-repeat-search} (unbound) (n) (unbound)
+Repeat the last vi history search.
+
+@tindex vi-rev-repeat-search
+@item @t{vi-rev-repeat-search} (unbound) (N) (unbound)
+Repeat the last vi history search, but in reverse.
+
+@tindex up-line-or-history
+@item @t{up-line-or-history} (^P ESC-[A) (k) (ESC-[A)
+Move up a line in the buffer, or if already at the top line,
+move to the previous event in the history list.
+
+@tindex vi-up-line-or-history
+@item @t{vi-up-line-or-history} (unbound) (-) (unbound)
+Move up a line in the buffer, or if already at the top line,
+move to the previous event in the history list.
+Then move to the first non-blank character on the line.
+
+@tindex up-line-or-search
+@item @t{up-line-or-search}
+Move up a line in the buffer, or if already at the top line,
+search backward in the history for a line beginning with the
+first word in the buffer.
+
+@noindent
+If called from a function by the @t{zle} command with arguments, the first
+argument is taken as the string for which to search, rather than the
+first word in the buffer.
+
+@tindex up-history
+@item @t{up-history} (unbound) (^P) (unbound)
+Move to the previous event in the history list.
+
+@tindex history-beginning-search-forward
+@item @t{history-beginning-search-forward}
+Search forward in the history for a line beginning with the current
+line up to the cursor.
+This leaves the cursor in its original position.
+
+@end table
+@node Modifying Text, Arguments, History Control, Zle Widgets
+
+@subsection Modifying Text
+@noindent
+@table @asis
+@tindex vi-add-eol
+@item @t{vi-add-eol} (unbound) (A) (unbound)
+Move to the end of the line and enter insert mode.
+
+@tindex vi-add-next
+@item @t{vi-add-next} (unbound) (a) (unbound)
+Enter insert mode after the current cursor position, without changing lines.
+
+@tindex backward-delete-char
+@item @t{backward-delete-char} (^H ^?) (unbound) (unbound)
+Delete the character behind the cursor.
+
+@tindex vi-backward-delete-char
+@item @t{vi-backward-delete-char} (unbound) (X) (^H)
+Delete the character behind the cursor, without changing lines.
+If in insert mode, this won't delete past the point where insert mode was
+last entered.
+
+@tindex backward-delete-word
+@item @t{backward-delete-word}
+Delete the word behind the cursor.
+
+@tindex backward-kill-line
+@item @t{backward-kill-line}
+Kill from the beginning of the line to the cursor position.
+
+@tindex backward-kill-word
+@item @t{backward-kill-word} (^W ESC-^H ESC-^?) (unbound) (unbound)
+Kill the word behind the cursor.
+
+@tindex vi-backward-kill-word
+@item @t{vi-backward-kill-word} (unbound) (unbound) (^W)
+Kill the word behind the cursor, without going past the point where insert
+mode was last entered.
+
+@tindex capitalize-word
+@item @t{capitalize-word} (ESC-C ESC-c) (unbound) (unbound)
+Capitalize the current word and move past it.
+
+@tindex vi-change
+@item @t{vi-change} (unbound) (c) (unbound)
+Read a movement command from the keyboard, and kill
+from the cursor position to the endpoint of the movement.
+Then enter insert mode.
+If the command is @t{vi-change}, change the current line.
+
+@tindex vi-change-eol
+@item @t{vi-change-eol} (unbound) (C) (unbound)
+Kill to the end of the line and enter insert mode.
+
+@tindex vi-change-whole-line
+@item @t{vi-change-whole-line} (unbound) (S) (unbound)
+Kill the current line and enter insert mode.
+
+@tindex copy-region-as-kill
+@item @t{copy-region-as-kill} (ESC-W ESC-w) (unbound) (unbound)
+Copy the area from the cursor to the mark to the kill buffer.
+
+@tindex copy-prev-word
+@item @t{copy-prev-word} (ESC-^_) (unbound) (unbound)
+Duplicate the word to the left of the cursor.
+
+@tindex copy-prev-shell-word
+@item @t{copy-prev-shell-word}
+Like @t{copy-prev-word}, but the word is found by using shell parsing, 
+whereas @t{copy-prev-word} looks for blanks. This makes a difference
+when the word is quoted and contains spaces.
+
+@tindex vi-delete
+@item @t{vi-delete} (unbound) (d) (unbound)
+Read a movement command from the keyboard, and kill
+from the cursor position to the endpoint of the movement.
+If the command is @t{vi-delete}, kill the current line.
+
+@tindex delete-char
+@item @t{delete-char}
+Delete the character under the cursor.
+
+@tindex vi-delete-char
+@item @t{vi-delete-char} (unbound) (x) (unbound)
+Delete the character under the cursor,
+without going past the end of the line.
+
+@tindex delete-word
+@item @t{delete-word}
+Delete the current word.
+
+@tindex down-case-word
+@item @t{down-case-word} (ESC-L ESC-l) (unbound) (unbound)
+Convert the current word to all lowercase and move past it.
+
+@tindex kill-word
+@item @t{kill-word} (ESC-D ESC-d) (unbound) (unbound)
+Kill the current word.
+
+@tindex gosmacs-transpose-chars
+@item @t{gosmacs-transpose-chars}
+Exchange the two characters behind the cursor.
+
+@tindex vi-indent
+@item @t{vi-indent} (unbound) (>) (unbound)
+Indent a number of lines.
+
+@tindex vi-insert
+@item @t{vi-insert} (unbound) (i) (unbound)
+Enter insert mode.
+
+@tindex vi-insert-bol
+@item @t{vi-insert-bol} (unbound) (I) (unbound)
+Move to the first non-blank character on the line and enter insert mode.
+
+@tindex vi-join
+@item @t{vi-join} (^X^J) (J) (unbound)
+Join the current line with the next one.
+
+@tindex kill-line
+@item @t{kill-line} (^K) (unbound) (unbound)
+Kill from the cursor to the end of the line.
+If already on the end of the line, kill the newline character.
+
+@tindex vi-kill-line
+@item @t{vi-kill-line} (unbound) (unbound) (^U)
+Kill from the cursor back to wherever insert mode was last entered.
+
+@tindex vi-kill-eol
+@item @t{vi-kill-eol} (unbound) (D) (unbound)
+Kill from the cursor to the end of the line.
+
+@tindex kill-region
+@item @t{kill-region}
+Kill from the cursor to the mark.
+
+@tindex kill-buffer
+@item @t{kill-buffer} (^X^K) (unbound) (unbound)
+Kill the entire buffer.
+
+@tindex kill-whole-line
+@item @t{kill-whole-line} (^U) (unbound) (unbound)
+Kill the current line.
+
+@tindex vi-match-bracket
+@item @t{vi-match-bracket} (^X^B) (%) (unbound)
+Move to the bracket character (one of @t{@{@}}, @t{()} or @t{[]}) that
+matches the one under the cursor.
+If the cursor is not on a bracket character, move forward without going
+past the end of the line to find one, and then go to the matching bracket.
+
+@tindex vi-open-line-above
+@item @t{vi-open-line-above} (unbound) (O) (unbound)
+Open a line above the cursor and enter insert mode.
+
+@tindex vi-open-line-below
+@item @t{vi-open-line-below} (unbound) (o) (unbound)
+Open a line below the cursor and enter insert mode.
+
+@tindex vi-oper-swap-case
+@item @t{vi-oper-swap-case}
+Read a movement command from the keyboard, and swap
+the case of all characters
+from the cursor position to the endpoint of the movement.
+If the movement command is @t{vi-oper-swap-case},
+swap the case of all characters on the current line.
+
+@tindex overwrite-mode
+@item @t{overwrite-mode} (^X^O) (unbound) (unbound)
+Toggle between overwrite mode and insert mode.
+
+@tindex vi-put-before
+@item @t{vi-put-before} (unbound) (P) (unbound)
+Insert the contents of the kill buffer before the cursor.
+If the kill buffer contains a sequence of lines (as opposed to characters),
+paste it above the current line.
+
+@tindex vi-put-after
+@item @t{vi-put-after} (unbound) (p) (unbound)
+Insert the contents of the kill buffer after the cursor.
+If the kill buffer contains a sequence of lines (as opposed to characters),
+paste it below the current line.
+
+@tindex quoted-insert
+@item @t{quoted-insert} (^V) (unbound) (unbound)
+Insert the next character typed into the buffer literally.
+An interrupt character will not be inserted.
+
+@tindex vi-quoted-insert
+@item @t{vi-quoted-insert} (unbound) (unbound) (^Q ^V)
+Display a `@t{^}' at the cursor position, and
+insert the next character typed into the buffer literally.
+An interrupt character will not be inserted.
+
+@tindex quote-line
+@item @t{quote-line} (ESC-') (unbound) (unbound)
+Quote the current line; that is, put a `@t{'}' character at the
+beginning and the end, and convert all `@t{'}' characters
+to `@t{'\@value{dsq}}'.
+
+@tindex quote-region
+@item @t{quote-region} (ESC-") (unbound) (unbound)
+Quote the region from the cursor to the mark.
+
+@tindex vi-replace
+@item @t{vi-replace} (unbound) (R) (unbound)
+Enter overwrite mode.
+
+@tindex vi-repeat-change
+@item @t{vi-repeat-change} (unbound) (.) (unbound)
+Repeat the last vi mode text modification.
+If a count was used with the modification, it is remembered.
+If a count is given to this command, it overrides the remembered count,
+and is remembered for future uses of this command.
+The cut buffer specification is similarly remembered.
+
+@tindex vi-replace-chars
+@item @t{vi-replace-chars} (unbound) (r) (unbound)
+Replace the character under the cursor with a character
+read from the keyboard.
+
+@tindex self-insert
+@item @t{self-insert} (printable characters) (unbound) (printable characters and some control characters)
+Insert a character into the buffer at the cursor position.
+
+@tindex self-insert-unmeta
+@item @t{self-insert-unmeta} (ESC-^I ESC-^J ESC-^M) (unbound) (unbound)
+Insert a character into the buffer after stripping the meta bit
+and converting ^M to ^J.
+
+@tindex vi-substitute
+@item @t{vi-substitute} (unbound) (s) (unbound)
+Substitute the next character(s).
+
+@tindex vi-swap-case
+@item @t{vi-swap-case} (unbound) (~) (unbound)
+Swap the case of the character under the cursor and move past it.
+
+@tindex transpose-chars
+@item @t{transpose-chars} (^T) (unbound) (unbound)
+Exchange the two characters to the left of the
+cursor if at end of line, else exchange the
+character under the cursor with the character
+to the left.
+
+@tindex transpose-words
+@item @t{transpose-words} (ESC-T ESC-t) (unbound) (unbound)
+Exchange the current word with the one before it.
+
+@tindex vi-unindent
+@item @t{vi-unindent} (unbound) (<) (unbound)
+Unindent a number of lines.
+
+@tindex up-case-word
+@item @t{up-case-word} (ESC-U ESC-u) (unbound) (unbound)
+Convert the current word to all caps and move past it.
+
+@tindex yank
+@item @t{yank} (^Y) (unbound) (unbound)
+Insert the contents of the kill buffer at the cursor position.
+
+@tindex yank-pop
+@item @t{yank-pop} (ESC-y) (unbound) (unbound)
+Remove the text just yanked, rotate the kill-ring,
+and yank the new top.  Only works following
+@t{yank} or @t{yank-pop}.
+
+@tindex vi-yank
+@item @t{vi-yank} (unbound) (y) (unbound)
+Read a movement command from the keyboard, and copy the region
+from the cursor position to the endpoint of the movement
+into the kill buffer.
+If the command is @t{vi-yank}, copy the current line.
+
+@tindex vi-yank-whole-line
+@item @t{vi-yank-whole-line} (unbound) (Y) (unbound)
+Copy the current line into the kill buffer.
+
+@tindex vi-yank-eol
+@item @t{vi-yank-eol}
+Copy the region from the cursor position to the end of the line
+into the kill buffer.
+Arguably, this is what Y should do in vi, but it isn't what it actually does.
+
+@end table
+@node Arguments, Completion, Modifying Text, Zle Widgets
+
+@subsection Arguments
+@noindent
+@table @asis
+@tindex digit-argument
+@item @t{digit-argument} (ESC-0..ESC-9) (1-9) (unbound)
+Start a new numeric argument, or add to the current one.
+See also @t{vi-digit-or-beginning-of-line}.  This only works if bound to a
+key sequence ending in a decimal digit.
+
+@noindent
+Inside a widget function, a call to this function treats the last key of
+the key sequence which called the widget as the digit.
+
+@tindex neg-argument
+@item @t{neg-argument} (ESC---) (unbound) (unbound)
+Changes the sign of the following argument.
+
+@tindex universal-argument
+@item @t{universal-argument}
+Multiply the argument of the next command by 4.  Alternatively, if
+this command is followed by an integer (positive or negative), use
+that as the argument for the next command.  Thus digits cannot be
+repeated using this command.  For example, if this command occurs
+twice, followed immediately by @t{forward-char}, move forward sixteen
+spaces; if instead it is followed by @t{-2}, then @t{forward-char},
+move backward two spaces.
+
+@noindent
+Inside a widget function, if passed an argument, i.e. `@t{zle
+universal-argument} @var{num}', the numerical argument will be set to
+@var{num}; this is equivalent to `@t{NUMERIC=}@var{num}'.
+
+@end table
+@node Completion, Miscellaneous, Arguments, Zle Widgets
+
+@subsection Completion
+@noindent
+@table @asis
+@tindex accept-and-menu-complete
+@item @t{accept-and-menu-complete}
+In a menu completion, insert the current completion into the buffer,
+and advance to the next possible completion.
+
+@tindex complete-word
+@item @t{complete-word}
+Attempt completion on the current word.
+
+@tindex delete-char-or-list
+@item @t{delete-char-or-list} (^D) (unbound) (unbound)
+Delete the character under the cursor.  If the cursor
+is at the end of the line, list possible completions for the
+current word.
+
+@tindex expand-cmd-path
+@item @t{expand-cmd-path}
+Expand the current command to its full pathname.
+
+@tindex expand-or-complete
+@item @t{expand-or-complete} (TAB) (unbound) (TAB)
+Attempt shell expansion on the current word.
+If that fails,
+attempt completion.
+
+@tindex expand-or-complete-prefix
+@item @t{expand-or-complete-prefix}
+Attempt shell expansion on the current word up to cursor.
+
+@tindex expand-history
+@item @t{expand-history} (ESC-space ESC-!) (unbound) (unbound)
+Perform history expansion on the edit buffer.
+
+@tindex expand-word
+@item @t{expand-word} (^X*) (unbound) (unbound)
+Attempt shell expansion on the current word.
+
+@tindex list-choices
+@item @t{list-choices} (ESC-^D) (^D =) (^D)
+List possible completions for the current word.
+
+@tindex list-expand
+@item @t{list-expand} (^Xg ^XG) (^G) (^G)
+List the expansion of the current word.
+
+@tindex magic-space
+@item @t{magic-space}
+Perform history expansion and insert a space into the
+buffer.  This is intended to be bound to space.
+
+@tindex menu-complete
+@pindex MENU_COMPLETE, use of
+@item @t{menu-complete}
+Like @t{complete-word}, except that menu completion is used.
+See the @t{MENU_COMPLETE} option.
+
+@tindex menu-expand-or-complete
+@item @t{menu-expand-or-complete}
+Like @t{expand-or-complete}, except that menu completion is used.
+
+@tindex reverse-menu-complete
+@item @t{reverse-menu-complete}
+Perform menu completion, like @t{menu-complete}, except that if
+a menu completion is already in progress, move to the @emph{previous}
+completion rather than the next.
+
+@tindex end-of-list
+@item @t{end-of-list}
+When a previous completion displayed a list below the prompt, this
+widget can be used to move the prompt below the list.
+
+@end table
+@node Miscellaneous, , Completion, Zle Widgets
+
+@subsection Miscellaneous
+@noindent
+@table @asis
+@tindex accept-and-hold
+@item @t{accept-and-hold} (ESC-A ESC-a) (unbound) (unbound)
+Push the contents of the buffer on the buffer stack
+and execute it.
+
+@tindex accept-and-infer-next-history
+@item @t{accept-and-infer-next-history}
+Execute the contents of the buffer.
+Then search the history list for a line matching the current one
+and push the event following onto the buffer stack.
+
+@tindex accept-line
+@item @t{accept-line} (^J ^M) (^J ^M) (^J ^M)
+Finish editing the buffer.  Normally this causes the buffer to be
+executed as a shell command.
+
+@tindex accept-line-and-down-history
+@item @t{accept-line-and-down-history} (^O) (unbound) (unbound)
+Execute the current line, and push the next history
+event on the the buffer stack.
+
+@tindex beep
+@item @t{beep}
+Beep, unless the @t{BEEP} option is unset.
+
+@tindex vi-cmd-mode
+@item @t{vi-cmd-mode} (^X^V) (unbound) (^[)
+Enter command mode; that is, select the `@t{vicmd}' keymap.
+Yes, this is bound by default in emacs mode.
+
+@tindex vi-caps-lock-panic
+@item @t{vi-caps-lock-panic}
+Hang until any lowercase key is pressed.
+This is for vi users without the mental capacity to keep
+track of their caps lock key (like the author).
+
+@tindex clear-screen
+@item @t{clear-screen} (^L ESC-^L) (^L) (^L)
+Clear the screen and redraw the prompt.
+
+@tindex describe-key-briefly
+@item @t{describe-key-briefly}
+Reads a key sequence, then prints the function bound to that sequence.
+
+@tindex exchange-point-and-mark
+@item @t{exchange-point-and-mark} (^X^X) (unbound) (unbound)
+Exchange the cursor position with the position of the mark.
+
+@tindex execute-named-cmd
+@item @t{execute-named-cmd} (ESC-x) (unbound) (unbound)
+Read the name of an editor command and
+execute it.  A restricted set of editing functions is available in the
+mini-buffer.  An interrupt signal, as defined by the stty setting, will
+abort the function. The allowed functions are:
+@t{backward-delete-char},
+@t{vi-backward-delete-char},
+@t{clear-screen},
+@t{redisplay},
+@t{quoted-insert},
+@t{vi-quoted-insert},
+@t{backward-kill-word},
+@t{vi-backward-kill-word},
+@t{kill-whole-line},
+@t{vi-kill-line},
+@t{backward-kill-line},
+@t{list-choices},
+@t{delete-char-or-list},
+@t{complete-word},
+@t{accept-line},
+@t{expand-or-complete} and
+@t{expand-or-complete-prefix}.
+
+@noindent
+@t{kill-region} kills the last word,
+and vi-cmd-mode is treated the same as accept-line.
+The space and tab characters, if not bound to one of
+these functions, will complete the name and then list the
+possibilities if the @t{AUTO_LIST} option is set.
+Any other character that is not bound to @t{self-insert} or
+@t{self-insert-unmeta} will beep and be ignored.
+The bindings of the current insert mode will be used.
+
+@tindex execute-last-named-cmd
+@item @t{execute-last-named-cmd} (ESC-z) (unbound) (unbound)
+Redo the last function executed with @t{execute-named-cmd}.
+
+@tindex get-line
+@item @t{get-line} (ESC-G ESC-g) (unbound) (unbound)
+Pop the top line off the buffer stack and insert it at the
+cursor position.
+
+@tindex pound-insert
+@item @t{pound-insert} (unbound) (#) (unbound)
+If there is no # character at the beginning of the buffer,
+add one to the beginning of each line.
+If there is one, remove a # from each line that has one.
+In either case, accept the current line.
+The @t{INTERACTIVE_COMMENTS} option must be set
+for this to have any usefulness.
+
+@tindex vi-pound-insert
+@item @t{vi-pound-insert}
+If there is no # character at the beginning of the current line,
+add one.  If there is one, remove it.
+The @t{INTERACTIVE_COMMENTS} option must be set
+for this to have any usefulness.
+
+@tindex push-input
+@item @t{push-input}
+Push the entire current multiline construct onto the buffer stack and
+return to the top-level (@t{PS1}) prompt.
+If the current parser construct is only a single line, this is exactly
+like @t{push-line}.
+Next time the editor starts up or is popped with @t{get-line}, the
+construct will be popped off the top of the buffer stack and loaded
+into the editing buffer.
+
+@tindex push-line
+@item @t{push-line} (^Q ESC-Q ESC-q) (unbound) (unbound)
+Push the current buffer onto the buffer stack and clear
+the buffer.
+Next time the editor starts up, the buffer will be popped
+off the top of the buffer stack and loaded into the editing
+buffer.
+
+@tindex push-line-or-edit
+@item @t{push-line-or-edit}
+At the top-level (@t{PS1}) prompt, equivalent to @t{push-line}.
+At a secondary (@t{PS2}) prompt, move the entire current multiline
+construct into the editor buffer.
+The latter is equivalent to @t{push-input} followed by @t{get-line}.
+
+@tindex recursive-edit
+@item @t{recursive-edit}
+Only useful from a user-defined widget.  At this point in the function,
+the editor regains control until one of the standard widgets which would
+normally cause zle to exit (typically an @t{accept-line} caused by
+hitting the return key) is executed.  Instead, control returns to the
+user-defined widget.  The status returned is non-zero if the return was
+caused by an error, but the function still continues executing and hence
+may tidy up.  This makes it safe for the user-defined widget to alter
+the command line or key bindings temporarily.
+
+@noindent
+The following widget, @t{caps-lock}, serves as an example.
+@example
+self-insert-ucase() @{
+  LBUFFER+=$@{(U)KEYS[-1]@}
+@}
+
+@noindent
+integer stat
+
+@noindent
+zle -N self-insert self-insert-ucase
+zle -A caps-lock save-caps-lock
+zle -A accept-line caps-lock
+
+@noindent
+zle recursive-edit
+stat=$?
+
+@noindent
+zle -A .self-insert self-insert
+zle -A save-caps-lock caps-lock
+zle -D save-caps-lock
+
+@noindent
+(( stat )) && zle send-break
+
+@noindent
+return $stat
+
+@end example
+This causes typed letters to be inserted capitalised until either
+@t{accept-line} (i.e. typically the return key) is typed or the
+@t{caps-lock} widget is invoked again; the later is handled by saving
+the old definition of @t{caps-lock} as @t{save-caps-lock} and then
+rebinding it to invoke @t{accept-line}.  Note that an error from the
+recursive edit is detected as a non-zero return status and propagated by
+using the @t{send-break} widget.
+
+@tindex redisplay
+@item @t{redisplay} (unbound) (^R) (^R)
+Redisplays the edit buffer.
+
+@tindex reset-prompt
+@item @t{reset-prompt} (unbound) (unbound) (unbound)
+Force the prompts on both the left and right of the screen to be
+re-expanded, then redisplay the edit buffer.  This
+reflects changes both to the prompt variables themselves and changes
+in the expansion of the values (for example, changes in time or
+directory, or changes to the value of variables referred to by the
+prompt).
+
+@noindent
+Otherwise, the prompt is only expanded each time zle starts, and
+when the display as been interrupted by output from another part of the
+shell (such as a job notification) which causes the command line to be
+reprinted.
+
+@tindex send-break
+@item @t{send-break} (^G ESC-^G) (unbound) (unbound)
+Abort the current editor function, e.g. @t{execute-named-command}, or the
+editor itself, e.g. if you are in @t{vared}. Otherwise abort the parsing of
+the current line.
+
+@tindex run-help
+@item @t{run-help} (ESC-H ESC-h) (unbound) (unbound)
+Push the buffer onto the buffer stack, and execute the
+command `@t{run-help} @var{cmd}', where @var{cmd} is the current
+command.  @t{run-help} is normally aliased to @t{man}.
+
+@tindex vi-set-buffer
+@item @t{vi-set-buffer} (unbound) (") (unbound)
+Specify a buffer to be used in the following command.
+There are 35 buffers that can be specified:
+the 26 `named' buffers @t{"a} to @t{"z}
+and the nine `queued' buffers @t{"1} to @t{"9}.  The named buffers can also
+be specified as @t{"A} to @t{"Z}.
+
+@noindent
+When a buffer is specified for a cut command, the text being cut replaces
+the previous contents of the specified buffer.  If a named buffer
+is specified using a capital, the newly cut text is appended to the buffer
+instead of overwriting it.
+
+@noindent
+If no buffer is specified for a cut command, @t{"1} is used, and the
+contents of @t{"1} to @t{"8} are each shifted along one buffer; the contents of
+@t{"9} is lost.
+
+@tindex vi-set-mark
+@item @t{vi-set-mark} (unbound) (m) (unbound)
+Set the specified mark at the cursor position.
+
+@tindex set-mark-command
+@item @t{set-mark-command} (^@@) (unbound) (unbound)
+Set the mark at the cursor position.
+
+@tindex spell-word
+@item @t{spell-word} (ESC-$ ESC-S ESC-s) (unbound) (unbound)
+Attempt spelling correction on the current word.
+
+@tindex undefined-key
+@item @t{undefined-key}
+This command is executed when a key sequence that is not bound to any
+command is typed.  By default it beeps.
+
+@tindex undo
+@item @t{undo} (^_ ^Xu ^X^U) (unbound) (unbound)
+Incrementally undo the last text modification.
+
+@tindex redo
+@item @t{redo}
+Incrementally redo undone text modifications.
+
+@tindex vi-undo-change
+@item @t{vi-undo-change} (unbound) (u) (unbound)
+Undo the last text modification.
+If repeated, redo the modification.
+
+@tindex what-cursor-position
+@item @t{what-cursor-position} (^X=) (unbound) (unbound)
+Print the character under the cursor, its code as an octal, decimal and
+hexadecimal number, the current cursor position within the buffer and the
+column of the cursor in the current line.
+
+@tindex where-is
+@item @t{where-is}
+Read the name of an editor command and and print the listing of key
+sequences that invoke the specified command.
+
+@tindex which-command
+@item @t{which-command} (ESC-?) (unbound) (unbound)
+Push the buffer onto the buffer stack, and execute the
+command `@t{which-command} @var{cmd}'. where @var{cmd} is the current
+command.  @t{which-command} is normally aliased to @var{whence}.
+
+@tindex vi-digit-or-beginning-of-line
+@item @t{vi-digit-or-beginning-of-line} (unbound) (0) (unbound)
+If the last command executed was a digit as part of an argument,
+continue the argument.  Otherwise, execute vi-beginning-of-line.
+
+@end table
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/compwid.yo
+@node Completion Widgets, Completion System, Zsh Line Editor, Top
+
+@chapter Completion Widgets
+@noindent
+@cindex completion, widgets
+@cindex completion, programmable
+@cindex completion, controlling
+
+@section Description
+@noindent
+The shell's programmable completion mechanism can be manipulated in two
+ways; here the low-level features supporting the newer, function-based
+mechanism are defined.  A complete set of shell functions based on these
+features is described in
+the next chapter, @ref{Completion System},
+and users with no interest in adding to that system (or, potentially,
+writing their own --- see dictionary entry for `hubris') should skip this
+section.  The older system based on the @t{compctl} builtin command is
+described in
+@ref{Completion Using compctl}.
+
+@noindent
+Completion widgets are defined by the @t{-C} option to the @t{zle}
+builtin command provided by the @t{zsh/zle} module (see
+@ref{The zsh/zle Module}). For example,
+
+@noindent
+@example
+zle -C complete expand-or-complete completer
+@end example
+
+@noindent
+defines a widget named `@t{complete}'.  The second argument is the name
+of any of the builtin widgets that handle completions:
+@t{complete-word}, @t{expand-or-complete},
+@t{expand-or-complete-prefix}, @t{menu-complete},
+@t{menu-expand-or-complete}, @t{reverse-menu-complete},
+@t{list-choices}, or @t{delete-char-or-list}.  Note that this will still
+work even if the widget in question has been re-bound.
+
+@noindent
+When this newly defined widget is bound to a key
+using the @t{bindkey} builtin command defined in the @t{zsh/zle} module
+(@ref{Zsh Line Editor}), typing that key will call the shell function `@t{completer}'. This
+function is responsible for generating the possible matches using the
+builtins described below.  As with other ZLE widgets, the function is
+called with its standard input closed.
+
+@noindent
+Once the function returns, the completion code takes over control again
+and treats the matches in the same manner as the specified builtin
+widget, in this case @t{expand-or-complete}.
+
+@noindent
+@menu
+* Special Parameters::
+* Builtin Commands::
+* Condition Codes::
+* Matching Control::
+* Completion Widget Example::
+@end menu
+
+@noindent
+@node Special Parameters, Builtin Commands, , Completion Widgets
+
+@section Special Parameters
+@noindent
+
+@noindent
+Inside completion widgets, and any functions called from them, some
+parameters have special meaning; outside these functions they are not
+special to the shell in any way.  These parameters are used to pass
+information between the completion code and the completion widget. Some of
+the builtin commands and the condition codes use or change the current
+values of these parameters.  Any existing values will be hidden during
+execution of completion widgets; except for @t{compstate}, the parameters
+are reset on each function exit (including nested function calls from
+within the completion widget) to the values they had when the function was
+entered.
+
+@noindent
+@table @asis
+@vindex CURRENT
+@item @t{CURRENT}
+This is the number of the current word, i.e. the word the cursor is
+currently on in the @t{words} array.  Note that this value is only
+correct if the @t{ksharrays} option is not set.
+
+@vindex IPREFIX
+@item @t{IPREFIX}
+Initially this will be set to the empty string.  This parameter functions
+like @t{PREFIX}; it contains a string which precedes the one in @t{PREFIX}
+and is not considered part of the list of matches.  Typically, a string is
+transferred from the beginning of @t{PREFIX} to the end of @t{IPREFIX}, for
+example:
+
+@noindent
+@example
+IPREFIX=$@{PREFIX%%\=*@}=
+PREFIX=$@{PREFIX#*=@}
+@end example
+
+@noindent
+causes the part of the prefix up to and including the first equal sign not
+to be treated as part of a matched string.  This can be done automatically
+by the @t{compset} builtin, see below.
+
+@vindex ISUFFIX
+@item @t{ISUFFIX}
+As @t{IPREFIX}, but for a suffix that should not be considered part
+of the matches; note that the @t{ISUFFIX} string follows the @t{SUFFIX}
+string.
+
+@vindex PREFIX
+@item @t{PREFIX}
+Initially this will be set to the part of the current word from the
+beginning of the word up to the position of the cursor; it may be altered
+to give a common prefix for all matches.
+
+@vindex QIPREFIX
+@item @t{QIPREFIX}
+This parameter is read-only and contains the quoted string up to the
+word being completed. E.g. when completing `@t{"foo}', this parameter
+contains the double quote. If the @t{-q} option of @t{compset} is used 
+(see below), and the original string was `@t{"foo bar}' with the
+cursor on the `@t{bar}', this parameter contains `@t{"foo }'.
+
+@vindex QISUFFIX
+@item @t{QISUFFIX}
+Like @t{QIPREFIX}, but containing the suffix.
+
+@vindex SUFFIX
+@item @t{SUFFIX}
+Initially this will be set to the part of the current word from the
+cursor position to the end; it may be altered to give a common suffix for
+all matches.  It is most useful when the option @t{COMPLETE_IN_WORD} is
+set, as otherwise the whole word on the command line is treated as a
+prefix.
+
+@vindex compstate
+@cindex completion widgets, examining and setting state in
+@item @t{compstate}
+This is an associative array with various keys and values that the
+completion code uses to exchange information with the completion widget.
+The keys are:
+
+@noindent
+@table @asis
+@vindex all_quotes, compstate
+@item @t{all_quotes}
+The @t{-q} option of the @t{compset} builtin command (see below)
+allows a quoted string to be broken into separate words; if the cursor is
+on one of those words, that word will be completed, possibly invoking
+`@t{compset -q}' recursively.  With this key it is possible to test the
+types of quoted strings which are currently broken into parts in this
+fashion.  Its value contains one character for each quoting level.  The
+characters are a single quote or a double quote for strings quoted with
+these characters and a backslash for strings not starting with a quote
+character.  The first character in the value always corresponds to the
+innermost quoting level.
+
+@vindex context, compstate
+@item @t{context}
+This will be set by the completion code to the overall context
+in which completion is attempted. Possible values are:
+
+@noindent
+@table @asis
+@item @t{array_value}
+when completing inside the value of an array parameter assignment; in
+this case the @t{words} array contains the words inside the parentheses.
+
+@item @t{brace_parameter}
+when completing the name of a parameter in a parameter expansion beginning
+with @t{$@{}.
+
+@item @t{assign_parameter}
+when completing the name of a parameter in a parameter assignment.
+
+@item @t{command}
+when completing for a normal command (either in command position or for
+an argument of the command).
+
+@item @t{condition}
+when completing inside a `@t{[[}...@t{]]}' conditional expression; in
+this case the @t{words} array contains only the words inside the
+conditional expression.
+
+@item @t{math}
+when completing in a mathematical environment such as a
+`@t{((}...@t{))}' construct.
+
+@item @t{parameter}
+when completing the name of a parameter in a parameter expansion beginning
+with @t{$} but not @t{$@{}.
+
+@item @t{redirect}
+when completing after a redirection operator.
+
+@item @t{subscript}
+when completing inside a parameter subscript.
+
+@item @t{value}
+when completing the value of a parameter assignment.
+
+@end table
+
+@vindex exact, compstate
+@item @t{exact}
+Controls the behaviour when the @t{REC_EXACT} option is set.  It will be
+set to @t{accept} if an exact match would be accepted, and will be unset
+otherwise.
+
+@noindent
+If it was set when at least one match equal to the string on the line
+was generated, the match is accepted.
+
+@vindex exact_string, compstate
+@item @t{exact_string}
+The string of an exact match if one was found, otherwise unset.
+
+@vindex ignored, compstate
+@item @t{ignored}
+The number of words that were ignored because they matched one of the
+patterns given with the @t{-F} option to the @t{compadd} builtin
+command.
+
+@vindex insert, compstate
+@item @t{insert}
+This controls the manner in which a match is inserted into the command
+line.  On entry to the widget function, if it is unset the command line is
+not to be changed; if set to @t{unambiguous}, any prefix common to all
+matches is to be inserted; if set to @t{automenu-unambiguous}, the
+common prefix is to be inserted and the next invocation of the
+completion code may start menu completion (due to the @t{AUTO_MENU}
+option being set); if set to @t{menu} or @t{automenu} menu completion
+will be started for the matches currently generated (in the
+latter case this will happen because the @t{AUTO_MENU} is set). The
+value may also contain the string `@t{tab}' when the completion code
+would normally not really do completion, but only insert the TAB
+character.
+
+@noindent
+On exit it may be set to any of the values above (where setting it to
+the empty string is the same as unsetting it), or to a number, in which
+case the match whose number is given will be inserted into the command line.
+Negative numbers count backward from the last match (with `@t{-1}'
+selecting the last match) and out-of-range values are wrapped
+around, so that a value of zero selects the last match and a value
+one more than the maximum selects the first. Unless the value of this
+key ends in a space, the match is inserted as in a menu completion,
+i.e. without automatically appending a space.
+
+@noindent
+Both @t{menu} and @t{automenu} may also specify the the number of the
+match to insert, given after a colon.  For example, `@t{menu:2}' says
+to start menu completion, beginning with the second match.
+
+@noindent
+Note that a value containing the substring `@t{tab}' makes the
+matches generated be ignored and only the TAB be inserted.
+
+@noindent
+Finally, it may also be set to @t{all}, which makes all matches
+generated be inserted into the line.
+
+@vindex insert_positions, compstate
+@item @t{insert_positions}
+When the completion system inserts an unambiguous string into the
+line, there may be multiple places where characters are missing or
+where the character inserted differs from at least one match.  The
+value of this key contains a colon separated list of all these
+positions, as indexes into the command line.
+
+@vindex last_prompt, compstate
+@item @t{last_prompt}
+If this is set to a non-empty string for every match added, the
+completion code will move the cursor back to the previous prompt after
+the list of completions has been displayed.  Initially this is set or
+unset according to the @t{ALWAYS_LAST_PROMPT} option.
+
+@vindex list, compstate
+@item @t{list}
+This controls whether or how the list of matches will be displayed.  If it
+is unset or empty they will never be listed; if its value begins with
+@t{list}, they will always be listed; if it begins with @t{autolist}
+or @t{ambiguous}, they will be listed when the @t{AUTO_LIST} or
+@t{LIST_AMBIGUOUS} options respectively would normally cause them to
+be.
+
+@noindent
+If the substring @t{force} appears in the value, this makes the
+list be shown even if there is only one match. Normally, the list
+would be shown only if there are at least two matches.
+
+@noindent
+The value contains the substring @t{packed} if the @t{LIST_PACKED}
+option is set. If this substring is given for all matches added to a
+group, this group will show the @t{LIST_PACKED} behavior. The same is
+done for the @t{LIST_ROWS_FIRST} option with the substring @t{rows}.
+
+@noindent
+Finally, if the value contains the string @t{explanations}, only the
+explanation strings, if any, will be listed and if it contains
+@t{messages}, only the messages (added with the @t{-x} option of
+@t{compadd}) will be listed.  If it contains both @t{explanations} and 
+@t{messages} both kinds of explanation strings will be listed.  It
+will be set appropriately on entry to a completion widget and may be
+changed there.
+
+@vindex list_lines, compstate
+@item @t{list_lines}
+This gives the number of lines that are needed to display the full
+list of completions.  Note that to calculate the total number of lines
+to display you need to add the number of lines needed for the command
+line to this value, this is available as the value of the @t{BUFFERLINES}
+special parameter.
+
+@vindex list_max, compstate
+@item @t{list_max}
+Initially this is set to the value of the @t{LISTMAX} parameter.
+It may be set to any other value; when the widget exits this value
+will be used in the same way as the value of @t{LISTMAX}.
+
+@vindex nmatches, compstate
+@item @t{nmatches}
+The number of matches generated and accepted by the completion code so
+far.
+
+@vindex old_insert, compstate
+@item @t{old_insert}
+On entry to the widget this will be set to the number of the match of
+an old list of completions that is currently inserted into the command
+line. If no match has been inserted, this is unset.
+
+@noindent
+As with @t{old_list}, the value of this key will only be used if it is the
+string @t{keep}. If it was set to this value by the widget and there was an
+old match inserted into the command line, this match will be kept and if
+the value of the @t{insert} key specifies that another match should be
+inserted, this will be inserted after the old one.
+
+@vindex old_list, compstate
+@item @t{old_list}
+This is set to @t{yes} if there is still a valid list of completions
+from a previous completion at the time the widget is invoked.  This will
+usually be the case if and only if the previous editing operation was a
+completion widget or one of the builtin completion functions.  If there is a
+valid list and it is also currently shown on the screen, the value of this
+key is @t{shown}.
+
+@noindent
+After the widget has exited the value of this key is only used if it
+was set to @t{keep}.  In this case the completion code will continue
+to use this old list.  If the widget generated new matches, they will
+not be used.
+
+@vindex parameter, compstate
+@item @t{parameter}
+The name of the parameter when completing in a subscript or in the
+value of a parameter assignment.
+
+@vindex pattern_insert, compstate
+@item @t{pattern_insert}
+Normally this is set to @t{menu}, which specifies that menu completion will
+be used whenever a set of matches was generated using pattern matching.  If
+it is set to any other non-empty string by the user and menu completion is
+not selected by other option settings, the code will instead insert any
+common prefix for the generated matches as with normal completion.
+
+@vindex pattern_match, compstate
+@item @t{pattern_match}
+Locally controls the behaviour given by the @t{GLOB_COMPLETE} option.
+Initially it is set to `@t{*}' if and only if the option is set.
+The completion widget may set it to this value, to an empty string
+(which has the same effect as unsetting it), or to any
+other non-empty string.  If it is non-empty, unquoted metacharacters on the
+command line will be treated as patterns; if it is `@t{*}', then
+additionally a wildcard `@t{*}' is assumed at the cursor position; if
+it is empty or unset, metacharacters will be treated literally.
+
+@noindent
+Note that the matcher specifications given to the @t{compadd} builtin
+command are not used if this is set to a non-empty string.
+
+@vindex quote, compstate
+@item @t{quote}
+When completing inside quotes, this contains the quotation character
+(i.e. either a single quote, a double quote, or a backtick).  Otherwise it
+is unset.
+
+@vindex quoting, compstate
+@item @t{quoting}
+When completing inside single quotes, this is set to the string
+@t{single}; inside double quotes, the string
+@t{double}; inside backticks, the string @t{backtick}.
+Otherwise it is unset.
+
+@vindex redirect, compstate
+@item @t{redirect}
+The redirection operator when completing in a redirection position,
+i.e. one of @t{<}, @t{>}, etc.
+
+@vindex restore, compstate
+@item @t{restore}
+This is set to @t{auto} before a function is entered, which forces the
+special parameters mentioned above (@t{words}, @t{CURRENT}, @t{PREFIX},
+@t{IPREFIX}, @t{SUFFIX}, and @t{ISUFFIX}) to be restored to their
+previous values when the function exits.   If a function unsets it or
+sets it to any other string, they will not be restored.
+
+@vindex to_end, compstate
+@item @t{to_end}
+Specifies the occasions on which the cursor is moved to the end of a string
+when a match is inserted.  On entry to a widget function, it may be
+@t{single} if this will happen when a single unambiguous match was inserted
+or @t{match} if it will happen any time a match is inserted (for example,
+by menu completion; this is likely to be the effect of the @t{ALWAYS_TO_END}
+option).
+
+@noindent
+On exit, it may be set to @t{single} as above.  It may also be set to
+@t{always}, or to the empty string or unset; in those cases the cursor will
+be moved to the end of the string always or never respectively.  Any
+other string is treated as @t{match}.
+
+@vindex unambiguous, compstate
+@item @t{unambiguous}
+This key is read-only and will always be set to the common (unambiguous)
+prefix the completion code has generated for all matches added so far.
+
+@vindex unambiguous_cursor, compstate
+@item @t{unambiguous_cursor}
+This gives the position the cursor would be placed at if the
+common prefix in the @t{unambiguous} key were inserted, relative to
+the value of that key. The cursor would be placed before the character
+whose index is given by this key.
+
+@vindex unambiguous_positions, compstate
+@item @t{unambiguous_positions}
+This contains all positions where characters in the unambiguous string
+are missing or where the character inserted differs from at least one
+of the matches.  The positions are given as indexes into the string
+given by the value of the @t{unambiguous} key.
+
+@vindex vared, compstate
+@item @t{vared}
+If completion is called while editing a line using the @t{vared}
+builtin, the value of this key is set to the name of the parameter
+given as an argument to @t{vared}.  This key is only set while a @t{vared}
+command is active.
+
+@end table
+
+@vindex words
+@item @t{words}
+This array contains the words present on the command line currently being
+edited.
+
+@end table
+
+@noindent
+@node Builtin Commands, Condition Codes, Special Parameters, Completion Widgets
+
+@section Builtin Commands
+@noindent
+@table @asis
+@findex compadd
+@cindex completion widgets, adding specified matches
+@item @t{compadd} [ @t{-akqQfenUl12C} ] [ @t{-F} @var{array} ]
+@itemx [ @t{-P} @var{prefix} ] [ @t{-S} @var{suffix} ]
+@itemx [ @t{-p} @var{hidden-prefix} ] [ @t{-s} @var{hidden-suffix} ]
+@itemx [ @t{-i} @var{ignored-prefix} ] [ @t{-I} @var{ignored-suffix} ]
+@itemx [ @t{-W} @var{file-prefix} ] [ @t{-d} @var{array} ]
+@itemx [ @t{-J} @var{name} ] [ @t{-V} @var{name} ] [ @t{-X} @var{explanation} ] [ @t{-x} @var{message} ]
+@itemx [ @t{-r} @var{remove-chars} ] [ @t{-R} @var{remove-func} ]
+@itemx [ @t{-D} @var{array} ] [ @t{-O} @var{array} ] [ @t{-A} @var{array} ]
+@itemx [ @t{-E} @var{number} ]
+@itemx [ @t{-M} @var{match-spec} ] [ @t{--} ] [ @var{words} ... ]
+
+@noindent
+This builtin command can be used to add matches directly and control
+all the information the completion code stores with each possible
+match. The return value is zero if at least one match was added and
+non-zero if no matches were added.
+
+@noindent
+The completion code breaks the string to complete into seven fields in
+the order: 
+
+@noindent
+@quotation
+@var{<ipre><apre><hpre><word><hsuf><asuf><isuf>}
+@end quotation
+
+@noindent
+The first field
+is an ignored prefix taken from the command line, the contents of the
+@t{IPREFIX} parameter plus the string given with the @t{-i}
+option. With the @t{-U} option, only the string from the @t{-i}
+option is used. The field @var{<apre>} is an optional prefix string
+given with the @t{-P} option.  The @var{<hpre>} field is a string
+that is considered part of the match but that should not be shown when 
+listing completions, given with the @t{-p} option; for example,
+functions that do filename generation might specify
+a common path prefix this way.  @var{<word>} is the part of the match that
+should appear in the list of completions, i.e. one of the @var{words} given
+at the end of the @t{compadd} command line. The suffixes @var{<hsuf>},
+@var{<asuf>} and @var{<isuf>} correspond to the prefixes @var{<hpre>},
+@var{<apre>} and @var{<ipre>} and are given by the options @t{-s}, @t{-S} and
+@t{-I}, respectively.
+
+@noindent
+The supported flags are:
+
+@noindent
+@table @asis
+@item @t{-P} @var{prefix}
+This gives a string to be inserted before the given @var{words}.  The
+string given is not considered as part of the match and any shell
+metacharacters in it will not be quoted when the string is inserted.
+
+@item @t{-S} @var{suffix}
+Like @t{-P}, but gives a string to be inserted after the match.
+
+@item @t{-p} @var{hidden-prefix}
+This gives a string that should be inserted into the command line before the
+match but that should not appear in the list of matches. Unless the
+@t{-U} option is given, this string must be matched as part of the string
+on the command line.
+
+@item @t{-s} @var{hidden-suffix}
+Like `@t{-p}', but gives a string to insert after the match.
+
+@item @t{-i} @var{ignored-prefix}
+This gives a string to insert into the command line just before any
+string given with the `@t{-P}' option.  Without `@t{-P}' the string is
+inserted before the string given with `@t{-p}' or directly before the
+match.
+
+@item @t{-I} @var{ignored-suffix}
+Like @t{-i}, but gives an ignored suffix.
+
+@item @t{-a}
+With this flag the @var{words} are taken as names of arrays and the
+possible matches are their values.  If only some elements of the
+arrays are needed, the @var{words} may also contain subscripts, as in
+`@t{foo[2,-1]}'.
+
+@item @t{-k}
+With this flag the @var{words} are taken as names of associative arrays
+and the possible matches are their keys.  As for @t{-a}, the
+@var{words} may also contain subscripts, as in `@t{foo[(R)*bar*]}'.
+
+@item @t{-d} @var{array}
+This adds per-match display strings. The @var{array} should contain one 
+element per @var{word} given. The completion code will then display the 
+first element instead of the first @var{word}, and so on. The
+@var{array} may be given as the name of an array parameter or directly
+as a space-separated list of words in parentheses.
+
+@noindent
+If there are fewer display strings than @var{words}, the leftover
+@var{words} will be displayed unchanged and if there are more display
+strings than @var{words}, the leftover display strings will be silently
+ignored.
+
+@item @t{-l}
+This option only has an effect if used together with the @t{-d}
+option. If it is given, the display strings are listed one per line,
+not arrayed in columns.
+
+@item @t{-J} @var{name}
+Gives the name of the group of matches the words should be stored in.
+
+@item @t{-V} @var{name}
+Like @t{-J} but naming a unsorted group. These are in a different name 
+space than groups created with the @t{-J} flag.
+
+@item @t{-1}
+If given together with the @t{-V} option, makes
+only consecutive duplicates in the group be removed. If combined with
+the @t{-J} option, this has no visible effect. Note that groups
+with and without this flag are in different name spaces.
+
+@item @t{-2}
+If given together with the @t{-J} or @t{-V} option, makes all
+duplicates be kept. Again, groups with and without this flag are in
+different name spaces.
+
+@item @t{-X} @var{explanation}
+The @var{explanation} string will be printed with the list of matches,
+above the group currently selected.
+
+@item @t{-x} @var{message}
+Like @t{-X}, but the @var{message} will be printed even if there are no 
+matches in the group.
+
+@item @t{-q}
+The suffix given with @t{-S} will be automatically removed if 
+the next character typed is a blank or does not insert anything, or if
+the suffix consists of only one character and the next character typed 
+is the same character.
+
+@item @t{-r} @var{remove-chars}
+This is a more versatile form of the @t{-q} option.
+The suffix given with @t{-S} or the slash automatically added after
+completing directories will be automatically removed if
+the next character typed inserts one of the characters given in the
+@var{remove-chars}.  This string is parsed as a characters class and
+understands the backslash sequences used by the @t{print} command.  For
+example, `@t{-r "a-z\t"}' removes the suffix if the next character typed
+inserts a lowercase character or a TAB, and `@t{-r "^0-9"}' removes the
+suffix if the next character typed inserts anything but a digit. One extra
+backslash sequence is understood in this string: `@t{\-}' stands for
+all characters that insert nothing. Thus `@t{-S "=" -q}' is the same
+as `@t{-S "=" -r "= \t\n\-"}'.
+
+@noindent
+This option may also be used without the @t{-S} option; then any
+automatically added space will be removed when one of the characters in the
+list is typed.
+
+@item @t{-R} @var{remove-func}
+This is another form of the @t{-r} option. When a suffix 
+has been inserted and the completion accepted, the function
+@var{remove-func} will be called after the next character typed.  It is
+passed the length of the suffix as an argument and can use the special
+parameters available in ordinary (non-completion) zle widgets (see
+@ref{Zsh Line Editor}) to analyse and modify the command line.
+
+@item @t{-f}
+If this flag is given, all of the matches built from @var{words} are
+marked as being the names of files.  They are not required to be actual
+filenames, but if they are, and the option @t{LIST_TYPES} is set, the
+characters describing the types of the files in the completion lists will
+be shown. This also forces a slash to be added when the name of a
+directory is completed.
+
+@item @t{-e}
+This flag can be used to tell the completion code that the matches
+added are parameter names for a parameter expansion. This will make
+the @t{AUTO_PARAM_SLASH} and @t{AUTO_PARAM_KEYS} options be used for
+the matches.
+
+@item @t{-W} @var{file-prefix}
+This string is a pathname that will be
+prepended to each of the matches formed by the given @var{words} together 
+with any prefix specified by the @t{-p} option to form a complete filename
+for testing.  Hence it is only useful if combined with the @t{-f} flag, as
+the tests will not otherwise be performed.
+
+@item @t{-F} @var{array}
+Specifies an array containing patterns. Words matching one of these
+patterns are ignored, i.e. not considered to be possible matches.
+
+@noindent
+The @var{array} may be the name of an array parameter or a list of
+literal patterns enclosed in parentheses and quoted, as in `@t{-F "(*?.o
+*?.h)"}'. If the name of an array is given, the elements of the array are
+taken as the patterns.
+
+@item @t{-Q}
+This flag instructs the completion 
+code not to quote any metacharacters in the words when inserting them
+into the command line.
+
+@item @t{-M} @var{match-spec}
+This gives local match specifications as described below in
+@ref{Matching Control}. This option may be given more than once. In 
+this case all @var{match-spec}s given are concatenated with spaces
+between them to form the specification string to use.
+Note that they will only be used if the @t{-U} option is not given.
+
+@item @t{-n}
+Specifies that the words added are to be used as possible
+matches, but are not to appear in the completion listing.
+
+@item @t{-U}
+If this flag is given, all words given will be accepted and no matching
+will be done by the completion code. Normally this is used in
+functions that do the matching themselves.
+
+@item @t{-O} @var{array}
+If this option is given, the @var{words} are @emph{not} added to the set of
+possible completions.  Instead, matching is done as usual and all of the
+@var{words} given as arguments that match the string on the command line
+will be stored in the array parameter whose name is given as @var{array}.
+
+@item @t{-A} @var{array}
+As the @t{-O} option, except that instead of those of the @var{words} which
+match being stored in @var{array}, the strings generated internally by the
+completion code are stored. For example,
+with a matching specification of `@t{-M "L:|no="}', the string `@t{nof}'
+on the command line and the string `@t{foo}' as one of the @var{words}, this
+option stores the string `@t{nofoo}' in the array, whereas the @t{-O}
+option stores the `@t{foo}' originally given.
+
+@item @t{-D} @var{array}
+As with @t{-O}, the @var{words} are not added to the set of possible
+completions.  Instead, the completion code tests whether each @var{word} 
+in turn matches what is on the line.  If the @var{n}'th @var{word} does not
+match, the @var{n}'th element of the @var{array} is removed.  Elements
+for which the corresponding @var{word} is matched are retained.
+
+@item @t{-C}
+This option adds a special match which expands to all other matches
+when inserted into the line, even those that are added after this
+option is used.  Together with the @t{-d} option it is possible to
+specify a string that should be displayed in the list for this special 
+match.  If no string is given, it will be shown as a string containing 
+the strings that would be inserted for the other matches, truncated to 
+the width of the screen.
+
+@item @t{-E}
+This option adds @var{number} empty matches after the @var{words} have
+been added.  An empty match takes up space in completion listings but
+will never be inserted in the line and can't be selected with menu
+completion or menu selection.  This makes empty matches only useful to
+format completion lists and to make explanatory string be shown in
+completion lists (since empty matches can be given display strings
+with the @t{-d} option).  And because all but one empty string would
+otherwise be removed, this option implies the @t{-V} and @t{-2}
+options (even if an explicit @t{-J} option is given).
+
+@item @t{-}
+@itemx @t{-}@t{-}
+This flag ends the list of flags and options. All arguments after it
+will be taken as the words to use as matches even if they begin with
+hyphens.
+
+@end table
+
+@noindent
+Except for the @t{-M} flag, if any of these flags is given more than
+once, the first one (and its argument) will be used.
+
+@findex compset
+@cindex completion widgets, modifying special parameters
+@item @t{compset -p} @var{number}
+@itemx @t{compset -P} [ @var{number} ] @var{pattern}
+@itemx @t{compset -s} @var{number}
+@itemx @t{compset -S} [ @var{number} ] @var{pattern}
+@itemx @t{compset -n} @var{begin} [ @var{end} ]
+@itemx @t{compset -N} @var{beg-pat} [ @var{end-pat} ]
+@itemx @t{compset -q}
+This command simplifies modification of the special parameters,
+while its return value allows tests on them to be carried out.
+
+@noindent
+The options are:
+
+@noindent
+@table @asis
+@item @t{-p} @var{number}
+If the contents of the @t{PREFIX} parameter is longer than @var{number}
+characters, the first @var{number} characters are removed from it and
+appended to the contents of the @t{IPREFIX} parameter.
+
+@item @t{-P} [ @var{number} ] @var{pattern}
+If the value of the @t{PREFIX} parameter begins with anything that
+matches the @var{pattern}, the matched portion is removed from
+@t{PREFIX} and appended to @t{IPREFIX}.
+
+@noindent
+Without the optional @var{number}, the longest match is taken, but
+if @var{number} is given, anything up to the @var{number}'th match is
+moved.  If the @var{number} is negative, the @var{number}'th longest
+match is moved. For example, if @t{PREFIX} contains the string
+`@t{a=b=c}', then @t{compset -P '*\='} will move the string `@t{a=b=}' 
+into the @t{IPREFIX} parameter, but @t{compset -P 1 '*\='} will move only
+the string `@t{a=}'.
+
+@item @t{-s} @var{number}
+As @t{-p}, but transfer the last @var{number} characters from the
+value of @t{SUFFIX} to the front of the value of @t{ISUFFIX}.
+
+@item @t{-S} [ @var{number} ] @var{pattern}
+As @t{-P}, but match the last portion of @t{SUFFIX} and transfer the
+matched portion to the front of the value of @t{ISUFFIX}.
+
+@item @t{-n} @var{begin} [ @var{end} ]
+If the current word position as specified by the parameter @t{CURRENT} 
+is greater than or equal to @var{begin}, anything up to the
+@var{begin}'th word is removed from the @t{words} array and the value
+of the parameter @t{CURRENT} is decremented by @var{begin}.
+
+@noindent
+If the optional @var{end} is given, the modification is done only if
+the current word position is also less than or equal to @var{end}. In
+this case, the words from position @var{end} onwards are also removed from
+the @t{words} array.
+
+@noindent
+Both @var{begin} and @var{end} may be negative to count backwards
+from the last element of the @t{words} array.
+
+@item @t{-N} @var{beg-pat} [ @var{end-pat} ]
+If one of the elements of the @t{words} array before the one at the
+index given by the value of the parameter @t{CURRENT} matches the
+pattern @var{beg-pat}, all elements up to and including the matching one are
+removed from the @t{words} array and the value of @t{CURRENT} is changed to
+point to the same word in the changed array.
+
+@noindent
+If the optional pattern @var{end-pat} is also given, and there is an
+element in the @t{words} array matching this pattern, the parameters
+are modified only if the index of this word is higher than the one
+given by the @t{CURRENT} parameter (so that the matching word has 
+to be after the cursor). In this case, the words starting with the one
+matching @t{end-pat} are also removed from the @t{words}
+array. If @t{words} contains no word matching @var{end-pat}, the
+testing and modification is performed as if it were not given.
+
+@item @t{-q}
+The word
+currently being completed is split on spaces into separate words,
+respecting the usual shell quoting conventions.  The 
+resulting words are stored in the @t{words} array, and @t{CURRENT},
+@t{PREFIX}, @t{SUFFIX}, @t{QIPREFIX}, and @t{QISUFFIX} are modified to
+reflect the word part that is completed.
+
+@end table
+
+@noindent
+In all the above cases the return value is zero if the test succeeded
+and the parameters were modified and non-zero otherwise. This allows
+one to use this builtin in tests such as:
+
+@noindent
+@example
+if compset -P '*\='; then ...
+@end example
+
+@noindent
+This forces anything up to and including the last equal sign to be
+ignored by the completion code.
+
+@item @t{compcall} [ @t{-TD} ]
+This allows the use of completions defined with the @t{compctl} builtin
+from within completion widgets.  The list of matches will be generated as
+if one of the non-widget completion function (@t{complete-word}, etc.)
+had been called, except that only @t{compctl}s given for specific commands
+are used. To force the code to try completions defined with the @t{-T}
+option of @t{compctl} and/or the default completion (whether defined by
+@t{compctl -D} or the builtin default) in the appropriate places, the
+@t{-T} and/or @t{-D} flags can be passed to @t{compcall}.
+
+@noindent
+The return value can be used to test if a matching @t{compctl}
+definition was found. It is non-zero if a @t{compctl} was found and
+zero otherwise.
+
+@noindent
+Note that this builtin is defined by the @t{zsh/compctl} module.
+
+@end table
+
+@noindent
+@node Condition Codes, Matching Control, Builtin Commands, Completion Widgets
+
+@section Condition Codes
+@noindent
+@cindex completion widgets, condition codes
+
+@noindent
+The following additional condition codes for use within the @t{[[ ... ]]}
+construct are available in completion widgets.  These work on the special
+parameters.  All of these tests can also be performed by the @t{compset}
+builtin, but in the case of the condition codes the contents of the special
+parameters are not modified.
+
+@noindent
+@table @asis
+@item @t{-prefix} [ @var{number} ] @var{pattern}
+true if the test for the @t{-P} option of @t{compset} would succeed.
+
+@item @t{-suffix} [ @var{number} ] @var{pattern}
+true if the test for the @t{-S} option of @t{compset} would succeed.
+
+@item @t{-after} @var{beg-pat}
+true if the test of the @t{-N} option with only the @var{beg-pat} given 
+would succeed.
+
+@item @t{-between} @var{beg-pat end-pat}
+true if the test for the @t{-N} option with both patterns would succeed.
+
+@end table
+
+@noindent
+@node Matching Control, Completion Widget Example, Condition Codes, Completion Widgets
+
+@section Matching Control
+@noindent
+
+@noindent
+It is possible by use of the
+@t{-M} option of the @t{compadd} builtin command to specify how the
+characters in the string to be completed (referred to here as the
+command line) map onto the characters in the list of matches produced by
+the completion code (referred to here as the trial completions). Note
+that this is not used if the command line contains a glob pattern and
+the @t{GLOB_COMPLETE} option is set or the @t{pattern_match} of the
+@t{compstate} special association is set to a non-empty string.
+
+@noindent
+The @var{match-spec} given as the argument to the @t{-M} option (see
+@ref{Builtin Commands}) consists of one or more matching descriptions separated by
+whitespace.  Each description consists of a letter followed by a colon
+and then the patterns describing which character sequences on the line match
+which character sequences in the trial completion.  Any sequence of
+characters not handled in this fashion must match exactly, as usual.
+
+@noindent
+The forms of @var{match-spec} understood are as follows. In each case, the
+form with an uppercase initial character retains the string already
+typed on the command line as the final result of completion, while with
+a lowercase initial character the string on the command line is changed
+into the corresponding part of the trial completion.
+
+@noindent
+@table @asis
+@item @t{m:}@var{lpat}@t{=}@var{tpat}
+@itemx @t{M:}@var{lpat}@t{=}@var{tpat}
+Here, @var{lpat} is a pattern that matches on the command line,
+corresponding to @var{tpat} which matches in the trial completion.
+
+@item @t{l:}@var{lanchor}@t{|}@var{lpat}@t{=}@var{tpat}
+@itemx @t{L:}@var{lanchor}@t{|}@var{lpat}@t{=}@var{tpat}
+@itemx @t{l:}@var{lanchor}@t{||}@var{ranchor}@t{=}@var{tpat}
+@itemx @t{L:}@var{lanchor}@t{||}@var{ranchor}@t{=}@var{tpat}
+@itemx @t{b:}@var{lpat}@t{=}@var{tpat}
+@itemx @t{B:}@var{lpat}@t{=}@var{tpat}
+These letters are for patterns that are anchored by another pattern on
+the left side. Matching for @var{lpat} and @var{tpat} is as for @t{m} and
+@t{M}, but the pattern @var{lpat} matched on the command line must be
+preceded by the pattern @var{lanchor}.  The @var{lanchor} can be blank to
+anchor the match to the start of the command line string; otherwise the
+anchor can occur anywhere, but must match in both the command line and
+trial completion strings.
+
+@noindent
+If no @var{lpat} is given but a @var{ranchor} is, this matches the gap
+between substrings matched by @var{lanchor} and @var{ranchor}. Unlike
+@var{lanchor}, the @var{ranchor} only needs to match the trial
+completion string.
+
+@noindent
+The @t{b} and @t{B} forms are similar to @t{l} and @t{L} with an empty 
+anchor, but need to match only the beginning of the trial completion
+or the word on the command line, respectively.
+
+@item @t{r:}@var{lpat}@t{|}@var{ranchor}@t{=}@var{tpat}
+@itemx @t{R:}@var{lpat}@t{|}@var{ranchor}@t{=}@var{tpat}
+@itemx @t{r:}@var{lanchor}@t{||}@var{ranchor}@t{=}@var{tpat}
+@itemx @t{R:}@var{lanchor}@t{||}@var{ranchor}@t{=}@var{tpat}
+@itemx @t{e:}@var{lpat}@t{=}@var{tpat}
+@itemx @t{E:}@var{lpat}@t{=}@var{tpat}
+As @t{l}, @t{L}, @t{b} and @t{B}, with the difference that the command
+line and trial completion patterns are anchored on the right side.
+Here an empty @var{ranchor} and the @t{e} and @t{E} forms force the
+match to the end of the trial completion or command line string.
+
+@end table
+
+@noindent
+Each @var{lpat}, @var{tpat} or @var{anchor} is either an empty string or
+consists of a sequence of literal characters (which may be quoted with a
+backslash), question marks, character classes, and correspondence
+classes; ordinary shell patterns are not used.  Literal characters match
+only themselves, question marks match any character, and character
+classes are formed as for globbing and match any character in the given
+set.
+
+@noindent
+Correspondence classes are defined like character classes, but with two
+differences: they are delimited by a pair of braces, and negated classes
+are not allowed, so the characters @t{!} and @t{^} have no special
+meaning directly after the opening brace.  They indicate that a range of
+characters on the line match a range of characters in the trial
+completion, but (unlike ordinary character classes) paired according to
+the corresponding position in the sequence. For example, to make any
+lowercase letter on the line match the corresponding uppercase letter in
+the trial completion, you can use `@t{m:@{a-z@}=@{A-Z@}}'.  More than one
+pair of classes can occur, in which case the first class before the
+@t{=} corresponds to the first after it, and so on.  If one side has
+more such classes than the other side, the superfluous classes behave
+like normal character classes.  In anchor patterns correspondence classes
+also behave like normal character classes.
+
+@noindent
+The pattern @var{tpat} may also be one or two stars, `@t{*}' or
+`@t{**}'. This means that the pattern on the command line can match
+any number of characters in the trial completion. In this case the
+pattern must be anchored (on either side); in the case of a single
+star, the @var{anchor} then determines how much of the trial completion
+is to be included --- only the characters up to the next appearance of
+the anchor will be matched. With two stars, substrings matched by the
+anchor can be matched, too.
+
+@noindent
+Examples:
+
+@noindent
+The keys of the @t{options} association defined by the @t{parameter}
+module are the option names in all-lowercase form, without
+underscores, and without the optional @t{no} at the beginning even
+though the builtins @t{setopt} and @t{unsetopt} understand option names
+with uppercase letters, underscores, and the optional @t{no}.  The
+following alters the matching rules so that the prefix @t{no} and any
+underscore are ignored when trying to match the trial completions
+generated and uppercase letters on the line match the corresponding
+lowercase letters in the words:
+
+@noindent
+@example
+compadd -M 'L:|[nN][oO]= M:_= M:@{A-Z@}=@{a-z@}' - \ 
+  $@{(k)options@} 
+@end example
+
+@noindent
+The first part says that the pattern `@t{[nN][oO]}' at the beginning
+(the empty anchor before the pipe symbol) of the string on the
+line matches the empty string in the list of words generated by
+completion, so it will be ignored if present. The second part does the
+same for an underscore anywhere in the command line string, and the
+third part uses correspondence classes so that any
+uppercase letter on the line matches the corresponding lowercase
+letter in the word. The use of the uppercase forms of the
+specification characters (@t{L} and @t{M}) guarantees that what has
+already been typed on the command line (in particular the prefix
+@t{no}) will not be deleted.
+
+@noindent
+Note that the use of @t{L} in the first part means that it matches
+only when at the beginning of both the command line string and the
+trial completion. I.e., the string `@t{_NO_f}' would not be
+completed to `@t{_NO_foo}', nor would `@t{NONO_f}' be completed to
+`@t{NONO_foo}' because of the leading underscore or the second
+`@t{NO}' on the line which makes the pattern fail even though they are 
+otherwise ignored. To fix this, one would use `@t{B:[nN][oO]=}'
+instead of the first part. As described above, this matches at the
+beginning of the trial completion, independent of other characters or
+substrings at the beginning of the command line word which are ignored
+by the same or other @var{match-spec}s.
+
+@noindent
+The second example makes completion case insensitive.  This is just
+the same as in the option example, except here we wish to retain the
+characters in the list of completions:
+
+@noindent
+@example
+compadd -M 'm:@{a-z@}=@{A-Z@}' ... 
+@end example
+
+@noindent
+This makes lowercase letters match their uppercase counterparts.
+To make uppercase letters match the lowercase forms as well:
+
+@noindent
+@example
+compadd -M 'm:@{a-zA-Z@}=@{A-Za-z@}' ... 
+@end example
+
+@noindent
+A nice example for the use of @t{*} patterns is partial word
+completion. Sometimes you would like to make strings like `@t{c.s.u}'
+complete to strings like `@t{comp.source.unix}', i.e. the word on the
+command line consists of multiple parts, separated by a dot in this
+example, where each part should be completed separately --- note,
+however, that the case where each part of the word, i.e. `@t{comp}',
+`@t{source}' and `@t{unix}' in this example, is to be completed from
+separate sets of matches
+is a different problem to be solved by the implementation of the
+completion widget.  The example can be handled by:
+
+@noindent
+@example
+compadd -M 'r:|.=* r:|=*' \ 
+  - comp.sources.unix comp.sources.misc ...
+@end example
+
+@noindent
+The first specification says that @var{lpat} is the empty string, while
+@var{anchor} is a dot; @var{tpat} is @t{*}, so this can match anything
+except for the `@t{.}' from the anchor in
+the trial completion word.  So in `@t{c.s.u}', the matcher sees `@t{c}',
+followed by the empty string, followed by the anchor `@t{.}', and
+likewise for the second dot, and replaces the empty strings before the
+anchors, giving `@t{c}[@t{omp}]@t{.s}[@t{ources}]@t{.u}[@t{nix}]', where
+the last part of the completion is just as normal.
+
+@noindent
+With the pattern shown above, the string `@t{c.u}' could not be
+completed to `@t{comp.sources.unix}' because the single star means
+that no dot (matched by the anchor) can be skipped. By using two stars 
+as in `@t{r:|.=**}', however, `@t{c.u}' could be completed to
+`@t{comp.sources.unix}'. This also shows that in some cases,
+especially if the anchor is a real pattern, like a character class,
+the form with two stars may result in more matches than one would like.
+
+@noindent
+The second specification is needed to make this work when the cursor is
+in the middle of the string on the command line and the option
+@t{COMPLETE_IN_WORD} is set. In this case the completion code would
+normally try to match trial completions that end with the string as
+typed so far, i.e. it will only insert new characters at the cursor
+position rather then at the end.  However in our example we would like
+the code to recognise matches which contain extra characters after the
+string on the line (the `@t{nix}' in the example).  Hence we say that the
+empty string at the end of the string on the line matches any characters
+at the end of the trial completion.
+
+@noindent
+More generally, the specification
+
+@noindent
+@example
+compadd -M 'r:|[.,_-]=* r:|=*' ... 
+@end example
+
+@noindent
+allows one to complete words with abbreviations before any of the
+characters in the square brackets.  For example, to
+complete @t{veryverylongfile.c} rather than @t{veryverylongheader.h}
+with the above in effect, you can just type @t{very.c} before attempting
+completion.
+
+@noindent
+The specifications with both a left and a right anchor are useful to
+complete partial words whose parts are not separated by some
+special character. For example, in some places strings have to be
+completed that are formed `@t{LikeThis}' (i.e. the separate parts are
+determined by a leading uppercase letter) or maybe one has to
+complete strings with trailing numbers. Here one could use the simple
+form with only one anchor as in:
+
+@noindent
+@example
+compadd -M 'r:|[A-Z0-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234
+@end example
+
+@noindent
+But with this, the string `@t{H}' would neither complete to `@t{FooHoo}'
+nor to `@t{LikeTHIS}' because in each case there is an uppercase
+letter before the `@t{H}' and that is matched by the anchor. Likewise, 
+a `@t{2}' would not be completed. In both cases this could be changed
+by using `@t{r:|[A-Z0-9]=**}', but then `@t{H}' completes to both
+`@t{LikeTHIS}' and `@t{FooHoo}' and a `@t{2}' matches the other
+strings because characters can be inserted before every uppercase
+letter and digit. To avoid this one would use:
+
+@noindent
+@example
+compadd -M 'r:[^A-Z0-9]||[A-Z0-9]=** r:|=*' \ 
+    LikeTHIS FooHoo foo123 bar234
+@end example
+
+@noindent
+By using these two anchors, a `@t{H}' matches only uppercase `@t{H}'s that 
+are immediately preceded by something matching the left anchor
+`@t{[^A-Z0-9]}'. The effect is, of course, that `@t{H}' matches only
+the string `@t{FooHoo}', a `@t{2}' matches only `@t{bar234}' and so on.
+
+@noindent
+When using the completion system (see
+@ref{Completion System}), users can define match specifications that are to be used for
+specific contexts by using the @t{matcher} and @t{matcher-list}
+styles. The values for the latter will be used everywhere.
+
+@noindent
+@node Completion Widget Example, , Matching Control, Completion Widgets
+
+@section Completion Widget Example
+@noindent
+@cindex completion widgets, example
+
+@noindent
+The first step is to define the widget:
+
+@noindent
+@example
+zle -C complete complete-word complete-files
+@end example
+
+@noindent
+Then the widget can be bound to a key using the @t{bindkey} builtin
+command:
+
+@noindent
+@example
+bindkey '^X\t' complete
+@end example
+
+@noindent
+After that the shell function @t{complete-files} will be invoked
+after typing control-X and TAB. The function should then generate the
+matches, e.g.:
+
+@noindent
+@example
+complete-files () @{ compadd - * @}
+@end example
+
+@noindent
+This function will complete files in the current directory matching the 
+current word.
+@c (avoiding a yodl bug)
+@c Yodl file: Zsh/compsys.yo
+@node Completion System, Completion Using compctl, Completion Widgets, Top
+
+@chapter Completion System
+@noindent
+@cindex completion system
+@cindex completion, programmable
+@cindex completion, controlling
+
+@section Description
+@noindent
+
+@noindent
+This describes the shell code for the new completion system.  It consists
+of various shell functions; those beginning `@t{comp}' are to be called
+directly, while those beginning `@t{_}' are called by the
+completion code.  The shell functions of the second set, which implement
+completion behaviour and may be bound to keystrokes, are referred to
+as `widgets'.
+
+@noindent
+@menu
+* Initialization::
+* Completion System Configuration::
+* Control Functions::
+* Bindable Commands::
+* Completion Functions::
+* Completion Directories::
+@end menu
+
+@noindent
+@node Initialization, Completion System Configuration, , Completion System
+
+@section Initialization
+@noindent
+@findex compinstall
+@cindex completion system, installing
+
+@noindent
+If the system was installed completely, it should be enough to
+call the shell function @t{compinit} from your initialization file; see the
+next section.  However, the function @t{compinstall} can be run by a user
+to configure various aspects of the completion system.
+
+@noindent
+Usually, @t{compinstall} will insert code into @t{.zshrc}, although if
+that is not writable it will save it in another file and tell you that
+file's location.  Note that it is up to you to make sure that the lines
+added to @t{.zshrc} are actually run; you may, for example, need to move
+them to an earlier place in the file if @t{.zshrc} usually returns early.
+So long as you keep them all together (including the comment lines at the
+start and finish), you can rerun @t{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 @t{compinstall},
+although lines using the command `@t{zstyle}' should be gracefully handled.
+
+@noindent
+The new code will take effect next time you start the shell, or run
+@t{.zshrc} by hand; there is also an option to make them take effect
+immediately.  However, if @t{compinstall} has removed definitions, you will
+need to restart the shell to see the changes.
+
+@noindent
+To run @t{compinstall} you will need to make sure it is in a directory
+mentioned in your @t{fpath} parameter, which should already be the case if
+zsh was properly configured as long as your startup files do not remove the
+appropriate directories from @t{fpath}.  Then it must be autoloaded
+(`@t{autoload -U compinstall}' is recommended).  You can abort the
+installation any time you are being prompted for information, and your
+@t{.zshrc} will not be altered at all; changes only take place right at the
+end, where you are specifically asked for confirmation.
+
+@noindent
+
+@subsection Use of compinit
+@noindent
+@findex compinit
+@cindex completion system, initializing
+
+@noindent
+This section describes the use of @t{compinit} to initialize completion for
+the current session when called directly; if you have run
+@t{compinstall} it will be called automatically from your @t{.zshrc}.
+
+@noindent
+To initialize the system, the function @t{compinit} should be in a
+directory mentioned in the @t{fpath} parameter, and should be autoloaded
+(`@t{autoload -U compinit}' is recommended), and then run simply as
+`@t{compinit}'.  This will define a
+few utility functions, arrange for all the necessary shell functions to be
+autoloaded, and will then re-define all widgets that do completion to use the
+new system.  If you use the @t{menu-select} widget, which is part of the
+@t{zsh/complist} module, you should make sure that that module is loaded
+before the call to @t{compinit} so that that widget is also
+re-defined.  If completion styles (see below) are set up to perform
+expansion as well as completion by default, and the TAB key is bound to
+@t{expand-or-complete}, @t{compinit} will rebind it to @t{complete-word};
+this is necessary to use the correct form of expansion.
+
+@noindent
+Should you need to use the original completion commands, you can still
+bind keys to the old widgets by putting a `@t{.}' in front of the
+widget name, e.g. `@t{.expand-or-complete}'.
+
+@noindent
+To speed up the running of @t{compinit}, it can be made to produce a dumped
+configuration that will be read in on future invocations; this is the
+default, but can be turned off by calling @t{compinit} with the
+option @t{-D}.  The dumped file is @t{.zcompdump} in the same
+directory as the startup files (i.e. @t{$ZDOTDIR} or @t{$HOME});
+alternatively, an explicit file name can be given by `@t{compinit -d}
+@var{dumpfile}'.  The next invocation of @t{compinit} will read the dumped
+file instead of performing a full initialization.
+
+@noindent
+If the number of completion files changes, @t{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 @t{#compdef} function (as described below)
+change, it is easiest to delete the dump file by hand so that
+@t{compinit} will re-create it the next time it is run.  The check
+performed to see if there are new functions can be omitted by giving
+the option @t{-C}.  In this case the dump file will only be created if
+there isn't one already.
+
+@noindent
+The dumping is actually done by another function, @t{compdump}, but you
+will only need to run this yourself if you change the configuration
+(e.g. using @t{compdef}) and then want to dump the new one.  The name of
+the old dumped file will be remembered for this purpose.
+
+@noindent
+If the parameter @t{_compdir} is set, @t{compinit} uses it as a directory
+where completion functions can be found; this is only necessary if they are
+not already in the function search path.
+
+@noindent
+For security reasons @t{compinit} also checks if the completion system
+would use files not owned by root or by the current user, or files in
+directories that are world- or group-writable or that are not owned by 
+root or by the current user.  If such files or directories are found,
+@t{compinit} will ask if the completion system should really be used.  To
+avoid these tests and make all files found be used without asking, use the
+option @t{-u}, and to make @t{compinit} silently ignore all insecure files
+and directories use the option @t{-i}.  This security check is skipped
+entirely when the @t{-C} option is given.
+
+@noindent
+@findex compaudit
+The security check can be retried at any time by running the function
+@t{compaudit}.  This is the same check used by @t{compinit}, but when it
+is executed directly any changes to @t{fpath} are made local to the
+function so they do not persist.  The directories to be checked may be
+passed as arguments; if none are given, @t{compaudit} uses @t{fpath} and
+@t{_compdir} to find completion system directories, adding missing ones
+to @t{fpath} as necessary.  To force a check of exactly the directories
+currently named in @t{fpath}, set @t{_compdir} to an empty string before
+calling @t{compaudit} or @t{compinit}.
+
+@noindent
+
+@subsection Autoloaded files
+@noindent
+@cindex completion system, autoloaded functions
+
+@noindent
+The convention for autoloaded functions used in completion is that they
+start with an underscore; as already mentioned, the @t{fpath/FPATH}
+parameter must contain the directory in which they are stored.  If @t{zsh}
+was properly installed on your system, then @t{fpath/FPATH} automatically
+contains the required directories for the standard functions.
+
+@noindent
+For incomplete installations, if @t{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 the directory @t{_compdir} to the search
+path.  If that directory has a subdirectory named @t{Base}, all
+subdirectories will be added to the path.  Furthermore, if the subdirectory
+@t{Base} has a subdirectory named @t{Core}, @t{compinit} will add all
+subdirectories of the subdirectories is to the path: this allows
+the functions to be in the same format as in the @t{zsh} source
+distribution.
+
+@noindent
+@cindex compdef, use of by compinit
+When @t{compinit} is run, it searches all such files accessible via
+@t{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
+completion system and will not be treated specially.
+
+@noindent
+The tags are:
+
+@noindent
+@table @asis
+@item @t{#compdef} @var{names...} [ @t{-[pP]} @var{patterns...} [ @t{-N} @var{names...} ] ]
+The file will be made autoloadable and the function defined 
+in it will be called when completing @var{names}, each of which is
+either the name of a command whose arguments are to be completed or one of
+a number of special contexts in the form @t{-}@var{context}@t{-} described
+below.
+
+@noindent
+Each @var{name} may also be of the form `@var{cmd}@t{=}@var{service}'.
+When completing the command @var{cmd}, the function typically behaves as
+if the command (or special context) @var{service} was being completed
+instead.  This provides a way of altering the behaviour of functions
+that can perform many different completions.  It is implemented
+by setting the parameter @t{$service} when calling the function;
+the function may choose to interpret this how it wishes, and simpler
+functions will probably ignore it.
+
+@noindent
+If the @t{#compdef} line contains one of the options @t{-p} or @t{-P},
+the words following are taken to be patterns.  The function will be
+called when completion is attempted for a command or context that matches
+one of the patterns.  The options @t{-p} and @t{-P} are used to specify
+patterns to be tried before or after other completions respectively.
+Hence @t{-P} may be used to specify default actions.
+
+@noindent
+The option @t{-N} is used after a list following @t{-p} or @t{-P}; it
+specifies that remaining words no longer define patterns.  It is
+possible to toggle between the three options as many times as necessary.
+
+@item @t{#compdef -k} @var{style key-sequences...}
+This option creates a widget behaving like the
+builtin widget @var{style} and binds it to the given @var{key-sequences},
+if any.  The @var{style} must be one of the builtin widgets that perform
+completion, namely @t{complete-word}, @t{delete-char-or-list},
+@t{expand-or-complete}, @t{expand-or-complete-prefix}, @t{list-choices},
+@t{menu-complete}, @t{menu-expand-or-complete}, or
+@t{reverse-menu-complete}.  If the @t{zsh/complist} module is loaded (see
+@ref{The zsh/complist Module}) the widget @t{menu-select} is also available.
+
+@noindent
+When one of the @var{key-sequences} is typed, the function in the file will
+be invoked to generate the matches.  Note that a key will not be re-bound
+if if it already was (that is, was bound to something other than
+@t{undefined-key}).  The widget created has the same name as the file and
+can be bound to any other keys using @t{bindkey} as usual.
+
+@item @t{#compdef -K} @var{widget-name} @var{style} @var{key-sequences} ...
+This is similar to @t{-k} except that only one @var{key-sequences}
+argument may be given for each @var{widget-name} @var{style} pair.
+However, the entire set of three arguments may be repeated with a
+different set of arguments.  Note in particular that the
+@var{widget-name} must be distinct in each set.  If it does not begin with
+`@t{_}' this will be added.  The @var{widget-name} should not clash with
+the name of any existing widget: names based on the name of the function
+are most useful.  For example,
+
+@noindent
+@example
+#compdef -K _foo_complete complete-word "^X^C" \ 
+  _foo_list list-choices "^X^D"
+@end example
+
+@noindent
+(all on one line) defines a widget @t{_foo_complete} for completion, bound
+to `@t{^X^C}', and a widget @t{_foo_list} for listing, bound to `@t{^X^D}'.
+
+@item @t{#autoload} [ @var{options} ]
+Functions with the @t{#autoload} tag are marked for autoloading but
+are not otherwise treated specially.  Typically they are to be called
+from within one of the completion functions.  Any @var{options} supplied
+will be passed to the @t{autoload} builtin; a typical use is @t{+X} to
+force the function to be loaded immediately.  Note that the @t{-U} and
+@t{-z} flags are always added implicitly.
+
+@end table
+
+@noindent
+The @t{#} is part of the tag name and no white space is allowed after it.
+The @t{#compdef} tags use the @t{compdef} function described below; the
+main difference is that the name of the function is supplied implicitly.
+
+@noindent
+The special contexts for which completion functions can be defined are:
+
+@noindent
+@table @asis
+@kindex -array-value-, completion context
+@item @t{-array-value-}
+The right hand side of an array-assignment
+(`@t{foo=(...)}')
+
+@kindex -brace-parameter-, completion context
+@item @t{-brace-parameter-}
+The name of a parameter expansion within braces (`@t{$@{...@}}')
+
+@kindex -assign-parameter-, completion context
+@item @t{-assign-parameter-}
+The name of a parameter in an assignment, i.e. on the left hand side of
+an `@t{=}'
+
+@kindex -command-, completion context
+@item @t{-command-}
+A word in command position
+
+@kindex -condition-, completion context
+@item @t{-condition-}
+A word inside a condition (`@t{[[...]]}')
+
+@kindex -default-, completion context
+@item @t{-default-}
+Any word for which no other completion is defined
+
+@kindex -equal-, completion context
+@item @t{-equal-}
+A word beginning with an equals sign
+
+@kindex -first-, completion context
+@item @t{-first-}
+This is tried before any other completion function.  The function called
+may set the @t{_compskip} parameter to one of various values: 
+@t{all}: no further completion is attempted; a string
+containing the substring @t{patterns}: no pattern completion functions
+will be called; a string containing @t{default}: the
+function for the `@t{-default-}' context will not be called, but
+functions defined for commands will
+
+@kindex -math-, completion context
+@item @t{-math-}
+Inside mathematical contexts, such as
+`@t{((}...@t{))}'
+
+@kindex -parameter-, completion context
+@item @t{-parameter-}
+The name of a parameter expansion (`@t{$...}')
+
+@kindex -redirect-, completion context
+@item @t{-redirect-}
+The word after a redirection operator.
+
+@kindex -subscript-, completion context
+@item @t{-subscript-}
+The contents of a parameter subscript.
+
+@kindex -tilde-, completion context
+@item @t{-tilde-}
+After an initial tilde (`@t{~}'), but before the first slash
+in the word.
+
+@kindex -value-, completion context
+@item @t{-value-}
+On the right hand side of an assignment.
+
+@end table
+
+@noindent
+Default implementations are supplied for each of these
+contexts.  In most cases the context @t{-}@var{context}@t{-} is
+implemented by a corresponding function @t{_}@var{context}, for example
+the context `@t{-tilde-}' and the function `@t{_tilde}').
+
+@noindent
+The contexts @t{-redirect-} and @t{-value-} allow extra context-specific
+information.  (Internally, this is handled by the functions for each
+context calling the function @t{_dispatch}.)  The extra
+information is added separated by commas.
+
+@noindent
+For the @t{-redirect-} context, the extra information is in the form
+`@t{-redirect-,}@var{op}@t{,}@var{command}', where @var{op} is the
+redirection operator and @var{command} is the name of the command on
+the line.  If there is no command on the line yet, the @var{command}
+field will be empty.
+
+@noindent
+For the @t{-value-} context, the form is
+`@t{-value-,}@var{name}@t{,}@var{command}', where @var{name} is the name of
+the parameter.  In the case of elements of an associative array, for
+example `@t{assoc=(key <TAB>}', @var{name} is expanded to
+`@var{name}@t{-}@var{key}'.  In certain special contexts, such as
+completing after `@t{make CFLAGS=}', the @var{command} part gives the
+name of the command, here @t{make}; otherwise it is empty.
+
+@noindent
+It is not necessary to define fully specific completions as the
+functions provided will try to generate completions by progressively
+replacing the elements with `@t{-default-}'.  For example, when
+completing after `@t{foo=<TAB>}', @t{_value} will try the names
+`@t{-value-,foo,}' (note the empty @var{command} part),
+`@t{-value-,foo,-default-}' and`@t{-value-,-default-,-default-}', in
+that order, until it finds a function to handle the context.
+
+@noindent
+As an example:
+
+@noindent
+@example
+compdef '_files -g "*.log"' '-redirect-,2>,-default-'
+@end example
+
+@noindent
+completes files matching `@t{*.log}' after `@t{2> <TAB>}' for any
+command with no more specific handler defined.
+
+@noindent
+Also:
+
+@noindent
+@example
+compdef _foo -value-,-default-,-default-
+@end example
+
+@noindent
+specifies that @t{_foo} provides completions for the values of
+parameters for which no special function has been defined.  This is
+usually handled by the function @t{_value} itself.
+
+@noindent
+The same lookup rules are used when looking up styles (as described
+below); for example
+
+@noindent
+@example
+zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log'
+@end example
+
+@noindent
+is another way to make completion after `@t{2> <TAB>}' complete files
+matching `@t{*.log}'.
+
+@noindent
+
+@subsection Functions
+@noindent
+
+@noindent
+The following function is defined by @t{compinit} and may be called
+directly.
+
+@noindent
+@findex compdef
+@cindex completion system, adding definitions
+@table @asis
+@item @t{compdef} [ @t{-an} ] @var{function names...} [ @t{-[pP]} @var{patterns...} [ @t{-N} @var{names...} ] ]
+@itemx @t{compdef -d} @var{names...}
+@itemx @t{compdef -k} [ @t{-an} ] @var{function style key-sequences...}
+@itemx @t{compdef -K} [ @t{-an} ] @var{function name style key-sequences ...}
+The first form defines the @var{function} to call for completion in the
+given contexts as described for the @t{#compdef} tag above.
+
+@noindent
+Alternatively, all the arguments may have the form
+`@var{cmd}@t{=}@var{service}'.  Here @var{service} should already have been
+defined by `@var{cmd1}@t{=}@var{service}' lines in @t{#compdef} files, as
+described above.  The argument for @var{cmd} will be completed in the
+same way as @var{service}.
+
+@noindent
+The @var{function} argument may alternatively be a string containing any
+shell code.  The string will be executed using the @t{eval} builtin
+command to generate completions.  This provides a way of avoiding having
+to define a new completion function.  For example, to complete
+files ending in `@t{.h}' as arguments to the command @t{foo}:
+
+@noindent
+@example
+compdef '_files -g "*.h"' foo
+@end example
+
+@noindent
+The option @t{-n} prevents any completions already defined for the
+command or context from being overwritten.
+
+@noindent
+The option @t{-d} deletes any completion defined for the command or
+contexts listed.
+
+@noindent
+The @var{names} may also contain @t{-p}, @t{-P} and @t{-N} options as
+described for the @t{#compdef} tag.  The effect on the argument list is
+identical, switching between definitions of patterns tried initially,
+patterns tried finally, and normal commands and contexts.
+
+@noindent
+The parameter @t{$_compskip} may be set by any function defined for a
+pattern context.  If it is set to a value containing the substring
+`@t{patterns}' none of the pattern-functions will be called; if it is
+set to a value containing the substring `@t{all}', no other function
+will be called.
+
+@noindent
+The form with @t{-k} defines a widget with the same name as the @var{function}
+that will be called for each of the @var{key-sequences}; this is like the
+@t{#compdef -k} tag.  The function should generate the completions needed
+and will otherwise behave like the builtin widget whose name is given as
+the @var{style} argument.  The widgets usable for this are:
+@t{complete-word}, @t{delete-char-or-list}, @t{expand-or-complete},
+@t{expand-or-complete-prefix}, @t{list-choices}, @t{menu-complete},
+@t{menu-expand-or-complete}, and @t{reverse-menu-complete}, as well as
+@t{menu-select} if the @t{zsh/complist} module is loaded.  The option @t{-n}
+prevents the key being bound if it is already to bound to something other
+than @t{undefined-key}.
+
+@noindent
+The form with @t{-K} is similar and defines multiple widgets based on the
+same @var{function}, each of which requires the set of three arguments
+@var{name}, @var{style} and @var{key-sequences}, where the latter two are as
+for @t{-k} and the first must be a unique widget name beginning with an
+underscore.
+
+@noindent
+Wherever applicable, the @t{-a} option makes the @var{function}
+autoloadable, equivalent to @t{autoload -U }@var{function}.
+
+@end table
+
+@noindent
+The function @t{compdef} can be used to associate existing completion
+functions with new commands.  For example,
+
+@noindent
+@example
+compdef _pids foo
+@end example
+
+@noindent
+uses the function @t{_pids} to complete process IDs for the command @t{foo}.
+
+@noindent
+Note also the @t{_gnu_generic} function described below, which can be
+used to complete options for commands that understand the
+`@t{-}@t{-help}' option.
+
+@noindent
+@node Completion System Configuration, Control Functions, Initialization, Completion System
+
+@section Completion System Configuration
+@noindent
+@cindex completion system, configuration
+
+@noindent
+This section gives a short overview of how the completion system works,
+and then more detail on how users can configure how and when matches are
+generated.
+
+@noindent
+
+@subsection Overview
+@noindent
+
+@noindent
+When completion is attempted somewhere on the command line the
+completion system first works out the context.  This takes account of a
+number of things including the command word (such as `@t{grep}' or
+`@t{zsh}') and options to which the current word may be an argument
+(such as the `@t{-o}' option to @t{zsh} which takes a shell option as an
+argument).
+
+@noindent
+This context information is condensed into a string consisting of
+multiple fields separated by colons, referred to simply as `the context'
+in the remainder of the documentation.  This is used to look up
+@emph{styles}, context-sensitive options that can be used to configure the
+completion system.  The context used for lookup may vary during the same
+call to the completion system.
+
+@noindent
+The context string always consists of the following fields, separated
+by colons and with a leading colon before the first:
+
+@noindent
+@itemize @bullet
+
+@noindent
+@item 
+The literal string @t{completion}, saying that this style is used by
+the completion system.  This distinguishes the context from those used
+by, for example, zle widgets and ZFTP functions.
+
+@item 
+The @var{function}, if completion is called from a named widget rather
+than through the normal completion system.  Typically this is blank, but
+it is set by special widgets such as @t{predict-on} and the various
+functions in the @t{Widget} directory of the distribution to the name of
+that function, often in an abbreviated form.
+
+@item 
+The @var{completer} currently active, the name of the function
+without the leading underscore.  A `completer' is in
+overall control of how completion is to be performed; `@t{complete}'
+is the simplest, but other completers exist to perform
+related tasks such as correction, or to modify the behaviour of a
+later completer.  See
+@ref{Control Functions} 
+for more information.  
+
+@item 
+The @var{command} or a special @t{-}@var{context}@t{-}, just at it appears
+following the @t{#compdef} tag or the @t{compdef} function.  Completion
+functions for commands that have sub-commands usually modify this field
+to contain the name of the command followed by a minus sign and the
+sub-command.  For example, the completion function for the @t{cvs}
+command sets this field to @t{cvs-add} when completing arguments to
+the @t{add} subcommand.
+
+@item 
+The @var{argument}; this indicates which command line or option argument
+we are completing.  For command arguments this generally takes the form
+@t{argument-}@var{n}, where @var{n} is the number of the argument,
+and for arguments to options the form @t{option-}@var{opt}@t{-}@var{n}
+where @var{n} is the number of the argument to option @var{opt}.  However,
+this is only the case if the command line is parsed with standard
+UNIX-style options and arguments, so many completions do not set this.
+
+@item 
+The @var{tag}.  Tags are used to discriminate between the types
+of matches a completion function can generate in a certain context and
+are described further below.
+
+@end itemize
+
+@noindent
+As an example, the context name
+
+@noindent
+@example
+@t{:completion::complete:dvips:option-o-1:files}
+@end example
+
+@noindent
+says that normal completion was attempted as the first argument to the
+option @t{-o} of the command @t{dvips}:
+
+@noindent
+@example
+@t{dvips -o ...}
+@end example
+
+@noindent
+and the completion function will generate filenames.
+
+@noindent
+Each type of completion the system can perform in a given context is
+described by a `tag', a short descriptive string such as @t{files} in
+the example above.  Any completion function may use any tag name it
+likes, but a list of the more common ones is given below.
+
+@noindent
+Usually completion will be tried by all possible tags in an order given
+by the completion function.  However, this can be altered by using the
+@t{tag-order} style.  Completion is then restricted to the list of given
+tags in the given order.
+
+@noindent
+The @t{_complete_help} bindable command shows all the contexts and tags
+available for completion at a particular point.  This provides an easy
+way of finding information for @t{tag-order} and other styles.  It is
+described in
+@ref{Bindable Commands}.
+
+@noindent
+Styles determine such things as how the matches are generated, similarly
+to shell options but with much more control.  They can have any number
+of strings as their value.  They are defined with the @t{zstyle} builtin
+command (@ref{The zsh/zutil Module}).
+
+@noindent
+When looking up styles the completion system uses full context names,
+including the tag.  Looking up the value of a style therefore consists
+of two things:  the context, which may be matched as a pattern, and the
+name of the style itself, which must be given exactly.
+
+@noindent
+For example, many completion functions can generate matches in a
+simple and a verbose form and use the @t{verbose} style to decide
+which form should be used.  To make all such functions use the verbose form,
+put
+
+@noindent
+@example
+zstyle ':completion:*' verbose yes
+@end example
+
+@noindent
+in a startup file (probably @t{.zshrc}).
+This gives the @t{verbose} style the value @t{yes} in every
+context inside the completion system, unless that context has a more
+specific definition.  It is best to avoid giving the context as `@t{*}'
+in case the style has some meaning outside the completion system.
+
+@noindent
+Many such general purpose styles can be configured simply by using the
+@t{compinstall} function.
+
+@noindent
+A more specific example of the use of the @t{verbose} style is by the
+completion for the @t{kill} builtin.  If the style is set, the builtin
+lists full job texts and process command lines; otherwise it shows the
+bare job numbers and PIDs.  To turn the style off for this use only:
+
+@noindent
+@example
+zstyle ':completion:*:*:kill:*' verbose no
+@end example
+
+@noindent
+For even more control, the style can use one of the tags `@t{jobs}' or
+`@t{processes}'.  To turn off verbose display only for jobs:
+
+@noindent
+@example
+zstyle ':completion:*:*:kill:*:jobs' verbose no
+@end example
+
+@noindent
+The @t{-e} option to @t{zstyle} even allows completion function code to
+appear as the argument to a style; this requires some understanding of
+the internals of completion functions (see
+@ref{Completion Widgets})).  For example:
+
+@noindent
+@example
+zstyle -e ':completion:*' completer '
+    if [[ $words[1] = cvs ]]; then
+      reply=(_complete)
+    else
+      reply=(_complete _approximate)
+    fi'
+@end example
+
+@noindent
+uses the value `@t{_complete}' for the @t{completer} style in most
+contexts, but the value `@t{_complete _approximate}' when the first word
+on the command line is `@t{cvs}'.  This is probably more conveniently done
+by specifying the style for two different contexts.  This form can be
+slow and should be avoided for commonly examined styles such
+as @t{menu} and @t{list-rows-first}.
+
+@noindent
+Note that the order in which styles are @emph{defined} does not matter; the
+style mechanism uses the most specific possible match for a particular
+style to determine the set of values.  More precisely, strings are
+preferred over patterns (for example, `@t{:completion::complete:foo}' is
+more specific than `@t{:completion::complete:*'}), and longer patterns are
+preferred over shorter patterns.
+
+@noindent
+Style names like those of tags are arbitrary and depend on the completion
+function.  However, the following two sections list some of the most
+common tags and styles.
+
+@noindent
+
+@subsection Standard Tags
+@noindent
+@cindex completion system, tags
+
+@noindent
+Some of the following are only used when looking up particular styles
+and do not refer to a type of match.
+
+@noindent
+@table @asis
+@kindex accounts, completion tag
+@item @t{accounts}
+used to look up the @t{users-hosts} style
+
+@kindex all-expansions, completion tag
+@item @t{all-expansions}
+used by the @t{_expand} completer when adding the single string containing
+all possible expansions
+
+@kindex all-files, completion tag
+@item @t{all-files}
+for the names of all files (as distinct from a particular subset, see the
+@t{globbed-files} tag).
+
+@kindex arguments, completion tag
+@item @t{arguments}
+for arguments to a command
+
+@kindex arrays, completion tag
+@item @t{arrays}
+for names of array parameters
+
+@kindex association-keys, completion tag
+@item @t{association-keys}
+for keys of associative arrays; used when completing inside a
+subscript to a parameter of this type
+
+@kindex bookmarks, completion tag
+@item @t{bookmarks}
+when completing bookmarks (e.g. for URLs and the @t{zftp} function suite)
+
+@kindex builtins, completion tag
+@item @t{builtins}
+for names of builtin commands
+
+@kindex characters, completion tag
+@item @t{characters}
+for single characters in arguments of commands such as @t{stty}.   Also used
+when completing character classes after an opening bracket
+
+@kindex colormapids, completion tag
+@item @t{colormapids}
+for X colormap ids
+
+@kindex colors, completion tag
+@item @t{colors}
+for color names
+
+@kindex commands, completion tag
+@item @t{commands}
+for names of external commands.  Also used by complex commands such as
+@t{cvs} when completing names subcommands.
+
+@kindex contexts, completion tag
+@item @t{contexts}
+for contexts in arguments to the @t{zstyle} builtin command
+
+@kindex corrections, completion tag
+@item @t{corrections}
+used by the @t{_approximate} and @t{_correct} completers for possible
+corrections
+
+@kindex cursors, completion tag
+@item @t{cursors}
+for cursor names used by X programs
+
+@kindex default, completion tag
+@item @t{default}
+used in some contexts to provide a way of supplying a default when more
+specific tags are also valid.  Note that this tag is
+used when only the @var{function} field of the context name is set
+
+@kindex descriptions, completion tag
+@item @t{descriptions}
+used when looking up the value of the @t{format} style to generate
+descriptions for types of matches
+
+@kindex devices, completion tag
+@item @t{devices}
+for names of device special files
+
+@kindex directories, completion tag
+@item @t{directories}
+for names of directories
+
+@kindex directory-stack, completion tag
+@item @t{directory-stack}
+for entries in the directory stack
+
+@kindex displays, completion tag
+@item @t{displays}
+for X display names
+
+@kindex domains, completion tag
+@item @t{domains}
+for network domains
+
+@kindex expansions, completion tag
+@item @t{expansions}
+used by the @t{_expand} completer for individual words (as opposed to
+the complete set of expansions) resulting from the expansion of a word
+on the command line
+
+@kindex extensions, completion tag
+@item @t{extensions}
+for X server extensions
+
+@kindex file-descriptors, completion tag
+@item @t{file-descriptors}
+for numbers of open file descriptors
+
+@kindex files, completion tag
+@item @t{files}
+the generic file-matching tag used by functions completing filenames
+
+@kindex fonts, completion tag
+@item @t{fonts}
+for X font names
+
+@kindex fstypes, completion tag
+@item @t{fstypes}
+for file system types (e.g. for the @t{mount} command)
+
+@kindex functions, completion tag
+@item @t{functions}
+names of functions --- normally shell functions, although certain
+commands may understand other kinds of function
+
+@kindex globbed-files, completion tag
+@item @t{globbed-files}
+for filenames when the name has been generated by pattern matching
+
+@kindex groups, completion tag
+@item @t{groups}
+for names of user groups
+
+@kindex history-words, completion tag
+@item @t{history-words}
+for words from the history
+
+@kindex hosts, completion tag
+@item @t{hosts}
+for hostnames
+
+@kindex indexes, completion tag
+@item @t{indexes}
+for array indexes
+
+@kindex jobs, completion tag
+@item @t{jobs}
+for jobs (as listed by the `@t{jobs}' builtin)
+
+@kindex interfaces, completion tag
+@item @t{interfaces}
+for network interfaces
+
+@kindex keymaps, completion tag
+@item @t{keymaps}
+for names of zsh keymaps
+
+@kindex keysyms, completion tag
+@item @t{keysyms}
+for names of X keysyms
+
+@kindex libraries, completion tag
+@item @t{libraries}
+for names of system libraries
+
+@kindex limits, completion tag
+@item @t{limits}
+for system limits
+
+@kindex local-directories, completion tag
+@item @t{local-directories}
+for names of directories that are subdirectories of the current working
+directory when completing arguments of @t{cd} and related builtin
+commands (compare @t{path-directories})
+
+@kindex manuals, completion tag
+@item @t{manuals}
+for names of manual pages
+
+@kindex mailboxes, completion tag
+@item @t{mailboxes}
+for e-mail folders
+
+@kindex maps, completion tag
+@item @t{maps}
+for map names (e.g. NIS maps)
+
+@kindex messages, completion tag
+@item @t{messages}
+used to look up the @t{format} style for messages
+
+@kindex modifiers, completion tag
+@item @t{modifiers}
+for names of X modifiers
+
+@kindex modules, completion tag
+@item @t{modules}
+for modules (e.g. @t{zsh} modules)
+
+@kindex my-accounts, completion tag
+@item @t{my-accounts}
+used to look up the @t{users-hosts} style
+
+@kindex named-directories, completion tag
+@item @t{named-directories}
+for named directories (you wouldn't have guessed that, would you?)
+
+@kindex names, completion tag
+@item @t{names}
+for all kinds of names
+
+@kindex newsgroups, completion tag
+@item @t{newsgroups}
+for USENET groups
+
+@kindex nicknames, completion tag
+@item @t{nicknames}
+for nicknames of NIS maps
+
+@kindex options, completion tag
+@item @t{options}
+for command options
+
+@kindex original, completion tag
+@item @t{original}
+used by the @t{_approximate}, @t{_correct} and @t{_expand} completers when
+offering the original string as a match
+
+@kindex other-accounts, completion tag
+@item @t{other-accounts}
+used to look up the @t{users-hosts} style
+
+@kindex packages, completion tag
+@item @t{packages}
+for packages (e.g. @t{rpm} or installed @t{Debian} packages)
+
+@kindex parameters, completion tag
+@item @t{parameters}
+for names of parameters
+
+@kindex path-directories, completion tag
+@item @t{path-directories}
+for names of directories found by searching the @t{cdpath} array when
+completing arguments of @t{cd} and related builtin commands (compare
+@t{local-directories})
+
+@kindex paths, completion tag
+@item @t{paths}
+used to look up the values of the @t{expand}, @t{ambiguous} and
+@t{special-dirs} styles
+
+@kindex pods, completion tag
+@item @t{pods}
+for perl pods (documentation files)
+
+@kindex ports, completion tag
+@item @t{ports}
+for communication ports
+
+@kindex prefixes, completion tag
+@item @t{prefixes}
+for prefixes (like those of a URL)
+
+@kindex printers, completion tag
+@item @t{printers}
+for print queue names
+
+@kindex processes, completion tag
+@item @t{processes}
+for process identifiers
+
+@kindex processes-names, completion tag
+@item @t{processes-names}
+used to look up the @t{command} style when generating the names of
+processes for @t{killall}
+
+@kindex sequences, completion tag
+@item @t{sequences}
+for sequences (e.g. @t{mh} sequences)
+
+@kindex sessions, completion tag
+@item @t{sessions}
+for sessions in the @t{zftp} function suite
+
+@kindex signals, completion tag
+@item @t{signals}
+for signal names
+
+@kindex strings, completion tag
+@item @t{strings}
+for strings (e.g. the replacement strings for the @t{cd} builtin
+command)
+
+@kindex styles, completion tag
+@item @t{styles}
+for styles used by the zstyle builtin command
+
+@kindex suffixes, completion tag
+@item @t{suffixes}
+for filename extensions
+
+@kindex tags, completion tag
+@item @t{tags}
+for tags (e.g. @t{rpm} tags)
+
+@kindex targets, completion tag
+@item @t{targets}
+for makefile targets
+
+@kindex time-zones, completion tag
+@item @t{time-zones}
+for time zones (e.g. when setting the @t{TZ} parameter)
+
+@kindex types, completion tag
+@item @t{types}
+for types of whatever (e.g. address types for the @t{xhost} command)
+
+@kindex urls, completion tag
+@item @t{urls}
+used to look up the @t{urls} and @t{local} styles when completing URLs
+
+@kindex users, completion tag
+@item @t{users}
+for usernames
+
+@kindex values, completion tag
+@item @t{values}
+for one of a set of values in certain lists
+
+@kindex variant, completion tag
+@item @t{variant}
+used by @t{_pick_variant} to look up the command to run when determining
+what program is installed for a particular command name.
+
+@kindex visuals, completion tag
+@item @t{visuals}
+for X visuals
+
+@kindex warnings, completion tag
+@item @t{warnings}
+used to look up the @t{format} style for warnings
+
+@kindex widgets, completion tag
+@item @t{widgets}
+for zsh widget names
+
+@kindex windows, completion tag
+@item @t{windows}
+for IDs of X windows
+
+@kindex zsh-options, completion tag
+@item @t{zsh-options}
+for shell options
+
+@end table
+
+@noindent
+
+@subsection Standard Styles
+@noindent
+@cindex completion system, styles
+
+@noindent
+Note that the values of several of these styles represent boolean
+values.  Any of the strings `@t{true}', `@t{on}',
+`@t{yes}', and `@t{1}' can be used for the value `true' and
+any of the strings `@t{false}', `@t{off}', `@t{no}', and `@t{0}' for
+the value `false'.  The behavior for any other value is undefined 
+except where explicitly mentioned.  The default value may
+be either true or false if the style is not set.
+
+@noindent
+Some of these styles are tested first for every possible tag
+corresponding to a type of match, and if no style was found, for the
+@t{default} tag.  The most notable styles of this type are @t{menu}, 
+@t{list-colors} and styles controlling completion listing such as 
+@t{list-packed} and @t{last-prompt}).  When tested for the @t{default}
+tag, only the @var{function} field of the context will be set so that
+a style using the default tag will normally be defined along the lines of:
+
+@noindent
+@example
+zstyle ':completion:*:default' menu ...
+@end example
+
+@noindent
+@table @asis
+@kindex accept-exact, completion style
+@item @t{accept-exact}
+This is tested for the default tag in addition to the tags valid for
+the current context.  If it is set to `true' and any of the trial
+matches is the same as the string on the command line, this match will
+immediately be accepted (even if it would otherwise be considered
+ambiguous).
+
+@noindent
+When completing pathnames (where the tag used is `@t{paths}')
+this style accepts any number of patterns as the value in addition to
+the boolean values.  Pathnames matching one of these
+patterns will be accepted immediately even if the command line contains
+some more partially typed pathname components and these match no file
+under the directory accepted.
+
+@noindent
+This style is also used by the @t{_expand} completer to decide if
+words beginning with a tilde or parameter expansion should be
+expanded.  For example, if there are parameters
+@t{foo} and @t{foobar}, the string `@t{$foo}' will only be expanded if 
+@t{accept-exact} is set to `true'; otherwise the completion system will
+be allowed to complete @t{$foo} to @t{$foobar}. If the style is set to
+`continue', _expand will add the expansion as a match and the completion
+system will also be allowed to continue.
+
+@kindex add-space, completion style
+@item @t{add-space}
+This style is used by the @t{_expand} completer.  If it is true (the
+default), a space will be inserted after all words resulting from the 
+expansion, or a slash in the case of directory names.  If the value
+is `@t{file}', the completer will only add a space
+to names of existing files.  Either a boolean true or the value
+`@t{file}' may be combined with `@t{subst}', in which case the completer
+will not add a space to words generated from the expansion of a
+substitution of the form `@t{$(...)}' or `@t{$@{...@}}'.
+
+@noindent
+The @t{_prefix} completer uses this style as a simple boolean value
+to decide if a space should be inserted before the suffix.
+
+@kindex ambiguous, completion style
+@item @t{ambiguous}
+This applies when completing non-final components of filename paths, in
+other words those with a trailing slash.  If it is set, the cursor is
+left after the first ambiguous component, even if menu completion is in
+use.  The style is always tested with the @t{paths} tag.
+
+@kindex assign-list, completion style
+@item @t{assign-list}
+When completing after an equals sign that is being treated as an
+assignment, the completion system normally completes only one filename.
+In some cases the value  may be a list of filenames separated by colons,
+as with @t{PATH} and similar parameters.  This style can be set to a
+list of patterns matching the names of such parameters.
+
+@noindent
+The default is to complete lists when the word on the line already
+contains a colon.
+
+@kindex auto-description, completion style
+@item @t{auto-description}
+If set, this style's value will be used as the description for options that
+are not described by the completion functions, but that have exactly
+one argument.  The sequence `@t{%d}' in the value will be replaced by
+the description for this argument.  Depending on personal preferences,
+it may be useful to set this style to something like `@t{specify: %d}'. 
+Note that this may not work for some commands.
+
+@kindex avoid-completer, completion style
+@item @t{avoid-completer}
+This is used by the @t{_all_matches} completer to decide if the string 
+consisting of all matches should be added to the list currently being
+generated.  Its value is a list of names of completers.  If any of
+these is the name of the completer that generated the matches in this
+completion, the string will not be added.
+
+@noindent
+The default value for this style is `@t{_expand _old_list _correct
+_approximate}', i.e. it contains the completers for which a string
+with all matches will almost never be wanted.
+
+@kindex cache-path, completion style
+@item @t{cache-path}
+This style defines the path where any cache files containing dumped
+completion data are stored.  It defaults to `@t{$ZDOTDIR/.zcompcache}', or
+`@t{$HOME/.zcompcache}' if @t{$ZDOTDIR} is not defined.  The completion
+cache will not be used unless the @t{use-cache} style is set.
+
+@kindex cache-policy, completion style
+@item @t{cache-policy}
+This style defines the function that will be used to determine whether
+a cache needs rebuilding.  See the section on the @t{_cache_invalid}
+function below.
+
+@kindex call-command, completion style
+@item @t{call-command}
+This style is used in the function for commands such as @t{make} and
+@t{ant} where calling the command directly to generate matches suffers
+problems such as being slow or, as in the case of @t{make} can
+potentially causes actions in the makefile to be executed. If it is set
+to `true' the command is called to generate matches. The default value
+of this style is `false'.
+
+@kindex command, completion style
+@item @t{command}
+In many places, completion functions need to call external commands to
+generate the list of completions.  This style can be used to override the
+command that is called in some such cases.  The elements of the value are
+joined with spaces to form a command line to execute.  The value can also
+start with a hyphen, in which case the usual command will be added to the
+end; this is most useful for putting `@t{builtin}' or `@t{command}' in
+front to make sure the appropriate version of a command is called, for
+example to avoid calling a shell function with the same name as an external
+command.
+
+@noindent
+As an example, the completion function for process IDs uses this
+style with the @t{processes} tag to generate the IDs to complete and
+the list of processes to display (if the @t{verbose} style is `true').
+The list produced by the command should look like the output of the
+@t{ps} command.  The first line is not displayed, but is searched for
+the string `@t{PID}' (or `@t{pid}') to find the position of the
+process IDs in the following lines.  If the line does not contain
+`@t{PID}', the first numbers in each of the other lines are taken as the 
+process IDs to complete.
+
+@noindent
+Note that the completion function generally has to call the specified
+command for each attempt to generate the completion list.  Hence
+care should be taken to specify only commands that take a short
+time to run, and in particular to avoid any that may never terminate.
+
+@kindex command-path, completion style
+@item @t{command-path}
+This is a list of directories to search for commands to complete.  The
+default for this style is the value of the special parameter @t{path}.
+
+@kindex commands, completion style
+@item @t{commands}
+This is used by the function completing sub-commands for the system
+initialisation scripts (residing in @t{/etc/init.d} or somewhere not
+too far away from that).  Its values give the default commands to
+complete for those commands for which the completion function isn't
+able to find them out automatically.  The default for this style are
+the two strings `@t{start}' and `@t{stop}'.
+
+@kindex complete, completion style
+@item @t{complete}
+This is used by the @t{_expand_alias} function when invoked as a
+bindable command.  If it set to `true' and the word on the command
+line is not the name of an alias, matching alias names will be
+completed.
+
+@kindex completer, completion style
+@item @t{completer}
+The strings given as the value of this style provide the names of the
+completer functions to use. The available completer functions are
+described in
+@ref{Control Functions}.
+
+@noindent
+Each string may be either the name of a completer function or a string
+of the form `@var{function}@t{:}@var{name}'.  In the first case the
+@var{completer} field of the context will contain the name of the
+completer without the leading underscore and with all other
+underscores replaced by hyphens.  In the second case the
+@var{function} is the name of the completer to call, but the context
+will contain the user-defined @var{name} in the @var{completer} field of
+the context.  If the @var{name} starts with a hyphen, the string for the
+context will be build from the name of the completer function as in
+the first case with the @var{name} appended to it.  For example: 
+
+@noindent
+@example
+zstyle ':completion:*' completer _complete _complete:-foo
+@end example
+
+@noindent
+Here, completion will call the @t{_complete} completer twice, once
+using `@t{complete}' and once using `@t{complete-foo}' in the
+@var{completer} field of the context.  Normally, using the same
+completer more than once only makes sense when used with the
+`@var{functions}@t{:}@var{name}' form, because otherwise the context
+name will be the same in all calls to the completer; possible
+exceptions to this rule are the @t{_ignored} and @t{_prefix}
+completers.
+
+@noindent
+The default value for this style is `@t{_complete _ignored}':
+only completion will be done, first using the @t{ignored-patterns} style
+and the @t{$fignore} array and then without ignoring matches.
+
+@kindex condition, completion style
+@item @t{condition}
+This style is used by the @t{_list} completer function to decide if
+insertion of matches should be delayed unconditionally. The default is 
+`true'.
+
+@kindex disabled, completion style
+@item @t{disabled}
+If this is set to `true', the @t{_expand_alias} completer and bindable 
+command will try to expand disabled aliases, too.  The default is
+`@t{false}'.
+
+@kindex disable-stat, completion style
+@item @t{disable-stat}
+This is used with an empty tag by the @t{_cvs} function
+to decide whether the @t{zsh/stat} module should be used to
+generate names of modified files in the appropriate places (this is its
+only use).  If the style is set, completion will use the @t{ls} command.
+
+@kindex domains, completion style
+@item @t{domains}
+A list of names of network domains for completion.
+If this is not set, domain names will be taken from
+the file @t{/etc/resolv.conf}.
+
+@kindex expand, completion style
+@item @t{expand}
+This style is used when completing strings consisting of multiple
+parts, such as path names.
+
+@noindent
+If one of its values is the string `@t{prefix}', the partially typed
+word from the line will be expanded as far as possible even if trailing
+parts cannot be completed.
+
+@noindent
+If one of its values is the string `@t{suffix}', matching names for
+components after the first ambiguous one will also be added.  This means
+that the resulting string is the longest unambiguous string possible.
+However, menu completion can be used to cycle through all matches.
+
+@kindex fake, completion style
+@item @t{fake}
+This style may be set for any completion context.  It
+specifies additional strings that will always be completed in that
+context.  The form of each string is `@var{value}@t{:}@var{description}'; 
+the colon and description may be omitted, but any literal colons in
+@var{value} must be quoted with a backslash.  Any @var{description}
+provided is shown alongside the value in completion listings.
+
+@noindent
+It is important to use a sufficiently restrictive context when specifying
+fake strings.  Note that the styles @t{fake-files} and @t{fake-parameters}
+provide additional features when completing files or parameters.
+
+@kindex fake-files, completion style
+@item @t{fake-files}
+This style is used when completing files and looked up 
+without a tag.  Its values are of the form
+`@var{dir}@t{:}@var{names...}'.  This will add the @var{names} (strings
+separated by spaces) as
+possible matches when completing in the directory @var{dir}, even if no 
+such files really exist.
+
+@noindent
+This can be useful on systems that support special filesystems whose
+top-level pathnames can not be listed or generated with glob patterns.
+It can also be used for directories for which one does not have read
+permission.
+
+@kindex fake-parameters, completion style
+@item @t{fake-parameters}
+This is used by the completion function for parameter names.
+Its values are names of parameters that might not yet be
+set but should be completed nonetheless.  Each name may also be 
+followed by a colon and a string specifying the type of the parameter
+(like `@t{scalar}', `@t{array}' or `@t{integer}').  If the type is
+given, the name will only be completed if parameters of that type are
+required in the particular context.  Names for which no type is
+specified will always be completed.
+
+@kindex file-patterns, completion style
+@item @t{file-patterns}
+This is used by the standard function for completing filenames,
+@t{_files}.  If the style is unset up to three tags are offered,
+`@t{globbed-files}',`@t{directories}' and `@t{all-files}', depending on
+the types of files  expected by the caller of @t{_files}.  The first two
+(`@t{globbed-files}' and `@t{directories}') are normally offered
+together to make it easier to complete files in sub-directories.
+
+@noindent
+The @t{file-patterns} style provides alternatives to the default tags,
+which are not used.  Its value consists of elements of the form
+`@var{pattern}@t{:}@var{tag}'; each string may contain any number of
+such specifications separated by spaces.
+
+@noindent
+The @var{pattern} is a pattern that is to be used to generate filenames.
+Any occurrence of the sequence `@t{%p}' is replaced by any pattern(s)
+passed by the function calling @t{_files}.  Colons in the pattern must
+be preceded by a backslash to make them distinguishable from the colon
+before the @var{tag}.  If more than one pattern is needed, the patterns
+can be given inside braces, separated by commas.
+
+@noindent
+The @var{tag}s of all strings in the value will be offered by @t{_files}
+and used when looking up other styles.  Any @var{tag}s in the same
+word will be offered at the same time and before later words.
+If no `@t{:}@var{tag}' is given the `@t{files}' tag will be used.
+
+@noindent
+The @var{tag} may also be followed by an optional second colon and a
+description, which will be used for the `@t{%d}' in the value of
+the @t{format} style (if that is set) instead of the default
+description supplied by the completion function.  If the description
+given here contains itself a `@t{%d}', that is replaced with the
+description supplied by the completion function.
+
+@noindent
+For example, to make the @t{rm} command first complete only names of
+object files and then the names of all files if there is no matching
+object file:
+
+@noindent
+@example
+zstyle ':completion:*:*:rm:*' file-patterns \ 
+    '*.o:object-files' '%p:all-files'
+@end example
+
+@noindent
+To alter the default behaviour of file completion --- offer files
+matching a pattern and directories on the first attempt, then all files
+--- to offer only matching files on the first attempt, then directories,
+and finally all files:
+
+@noindent
+@example
+zstyle ':completion:*' file-patterns \ 
+    '%p:globbed-files' '*(-/):directories' '*:all-files'
+@end example
+
+@noindent
+This works even where there is no special pattern: @t{_files} matches
+all files using the pattern `@t{*}' at the first step and stops when it
+sees this pattern.  Note also it will never try a pattern more than once
+for a single completion attempt.
+
+@noindent
+During the execution of completion functions, the @t{EXTENDED_GLOB}
+option is in effect, so the characters `@t{#}', `@t{~}' and `@t{^}' have
+special meanings in the patterns.
+
+@kindex file-sort, completion style
+@item @t{file-sort}
+The standard filename completion function uses this style without a tag
+to determine in which order the names should be listed; menu completion
+will cycle through them in the same order.  The possible
+values are: `@t{size}' to sort by the size of the file;
+`@t{links}' to sort by the number of links to the file;
+`@t{modification}' (or `@t{time}' or `@t{date}') to sort by the last
+modification time; `@t{access}' to sort by the last access time; and
+`@t{inode}' (or `@t{change}') to sort by the last inode change
+time.  If the style is set to any other value, or is unset, files will be
+sorted alphabetically by name.  If the value contains the string
+`@t{reverse}', sorting is done in the opposite order.
+
+@kindex filter, completion style
+@item @t{filter}
+This is used by the LDAP plugin for e-mail address completion to specify
+the attributes to match against when filtering entries.  So for example, if
+the style is set to `@t{sn}', matching is done against surnames.  Standard
+LDAP filtering is used so normal completion matching is bypassed.  If this
+style is not set, the LDAP plugin is skipped.  You may also need to set the
+@t{command} style to specify how to connect to your LDAP server.
+
+@kindex force-list, completion style
+@item @t{force-list}
+This forces a list of completions to be shown at any point where listing is
+done, even in cases where the list would usually be suppressed.
+For example, normally the list is only shown if
+there are at least two different matches.  By setting this style to
+`@t{always}', the list will always be shown, even if there is only a
+single match that will immediately be accepted.  The style may also
+be set to a number.  In this case the list will be shown if there are
+at least that many matches, even if they would all insert the same
+string.
+
+@noindent
+This style is tested for the default tag as well as for each tag valid
+for the current completion.  Hence the listing can be forced only for
+certain types of match.
+
+@kindex format, completion style
+@item @t{format}
+If this is set for the @t{descriptions} tag, its value is used as a
+string to display above matches in completion lists.  The sequence
+`@t{%d}' in this string will be replaced with a short description of
+what these matches are.  This string may also contain the sequences to
+specify output attributes, such as `@t{%B}', `@t{%S}' and
+`@t{%@{}...@t{%@}}'.
+
+@noindent
+The style is tested with each tag valid for the current completion
+before it is tested for the @t{descriptions} tag.  Hence different format 
+strings can be defined for different types of match.
+
+@noindent
+Note also that some completer functions define additional
+`@t{%}'-sequences.  These are described for the completer functions that 
+make use of them.
+
+@noindent
+Some completion functions display messages that may be customised by
+setting this style for the @t{messages} tag.  Here, the `@t{%d}' is
+replaced with a message given by the completion function.
+
+@noindent
+Finally, the format string is looked up with the @t{warnings} tag, 
+for use when no matches could be generated at all.  In this case the
+`@t{%d}' is replaced with the descriptions for the matches that were
+expected separated by spaces.  The sequence `@t{%D}' is replaced with
+the same descriptions separated by newlines.
+
+@noindent
+It is possible to use printf-style field width specifiers with `@t{%d}'
+and similar escape sequences.  This is handled by the @t{zformat}
+builtin command from the @t{zsh/zutil} module, see
+@ref{The zsh/zutil Module}.
+
+@kindex glob, completion style
+@item @t{glob}
+This is used by the @t{_expand} completer.  If
+it is set to `true' (the default), globbing will be attempted on the
+words resulting from a previous substitution (see the @t{substitute}
+style) or else the original string from the line.
+
+@kindex global, completion style
+@item @t{global}
+If this is set to `true' (the default), the @t{_expand_alias}
+completer and bindable command will try to expand global aliases.
+
+@kindex group-name, completion style
+@item @t{group-name}
+The completion system can group different types of matches, which appear
+in separate lists.  This style can be used to give the names of groups
+for particular tags.  For example, in command position the completion
+system generates names of builtin and external commands, names of
+aliases, shell functions and parameters and reserved words as possible
+completions.  To have the external commands and shell functions listed
+separately:
+
+@noindent
+@example
+zstyle ':completion:*:*:-command-:*:commands' group-name commands
+zstyle ':completion:*:*:-command-:*:functions' group-name functions
+@end example
+
+@noindent
+As a consequence, any match with the same tag will be displayed in the
+same group.
+
+@noindent
+If the name given is the empty string the name of the tag for
+the matches will be used as the name of the group.  So, to have all
+different types of matches displayed separately, one can just set:
+
+@noindent
+@example
+zstyle ':completion:*' group-name @value{dsq}
+@end example
+
+@noindent
+All matches for which no group name is defined will be put in a group
+named @t{-default-}.
+
+@kindex group-order, completion style
+@item @t{group-order}
+This style is additional to the @t{group-name} style to specify the
+order for display of the groups defined by that style (compare @t{tag-order},
+which determines which completions appear at all).  The groups named
+are shown in the given order; any other groups
+are shown in the order defined by the completion function.
+
+@noindent
+For example, to have names of builtin commands, shell functions and
+external commands appear in that order when completing in command
+position:
+
+@noindent
+@example
+zstyle ':completion:*:*:-command-:*' group-order \ 
+       builtins functions commands
+@end example
+
+@kindex groups, completion style
+@item @t{groups}
+A list of names of UNIX groups.  If this is not set,
+group names are taken from the YP database or the file `@t{/etc/group}'.
+
+@kindex hidden, completion style
+@item @t{hidden}
+If this is set to true, matches for the given context
+will not be listed, although
+any description for the matches set with the @t{format} style will be
+shown.  If it is set to `@t{all}', not even the description will be
+displayed.
+
+@noindent
+Note that the matches will still be completed; they are just not shown 
+in the list.  To avoid having matches considered as possible
+completions at all, the @t{tag-order} style can be modified as described
+below.
+
+@kindex hosts, completion style
+@item @t{hosts}
+A list of names of hosts that should be completed.  If this is not set,
+hostnames are taken from the file `@t{/etc/hosts}'.
+
+@kindex hosts-ports, completion style
+@item @t{hosts-ports}
+This style is used by commands that need or accept hostnames and
+network ports.  The strings in the value should be of the form
+`@var{host}@t{:}@var{port}'.  Valid ports are determined by the presence
+of hostnames; multiple ports for the same host may appear.
+
+@kindex ignore-line, completion style
+@item @t{ignore-line}
+This is tested for each tag valid for the current completion.  If
+it is set to `@t{true}', none of the words that are already on the line
+will be considered as possible completions.  If it is set to
+`@t{current}', the word the cursor is on will not be considered as a
+possible completion.  The value `@t{current-shown}' is similar but only
+applies if the list of completions is currently shown on the screen.
+Finally, if the style is set to `@t{other}', no word apart from the
+current one will be considered as a possible completion.
+
+@noindent
+The values `@t{current}' and `@t{current-shown}' are a bit like the
+opposite of the @t{accept-exact} style:  only strings with
+missing characters will be completed.
+
+@noindent
+Note that you almost certainly don't want to set this to `true' or
+`@t{other}' for a general
+context such as `@t{:completion:*}'.  This is because it would disallow
+completion of, for example, options multiple times even if the command
+in question accepts the option more than once.
+
+@kindex ignore-parents, completion style
+@item @t{ignore-parents}
+The style is tested without a tag by the function completing pathnames
+in order to determine whether to ignore
+the names of directories already mentioned in the current word, or the
+name of the current working directory.  The value must include one or both
+of the following strings:
+
+@noindent
+@table @asis
+@item @t{parent}
+The name of any directory whose path is already contained in the word on
+the line is ignored.  For example, when completing after @t{foo/../}, the
+directory @t{foo} will not be considered a valid completion.
+
+@item @t{pwd}
+The name of the current working directory will not be completed; hence,
+for example, completion after @t{../} will not use the name of the current
+directory.
+
+@end table
+
+@noindent
+In addition, the value may include one or both of:
+
+@noindent
+@table @asis
+@item @t{..}
+Ignore the specified directories only when the word on the line contains
+the substring `@t{../}'.
+
+@item @t{directory}
+Ignore the specified directories only when names of directories are
+completed, not when completing names of files.
+
+@end table
+
+@noindent
+Excluded values act in a similar fashion to values of the
+@t{ignored-patterns} style, so they can be restored to consideration by
+the @t{_ignored} completer.
+
+@kindex ignored-patterns, completion style
+@item @t{ignored-patterns}
+A list of patterns; any trial completion matching one of the patterns
+will be excluded from consideration.  The
+@t{_ignored} completer can appear in the list of completers to
+restore the ignored matches.  This is a more configurable
+version of the shell parameter @t{$fignore}.
+
+@noindent
+Note that the
+@t{EXTENDED_GLOB} option is set during the execution of completion
+functions, so the characters `@t{#}', `@t{~}' and `@t{^}' have special
+meanings in the patterns.
+
+@kindex insert, completion style
+@item @t{insert}
+This style is used by the @t{_all_matches} completer to decide whether to
+insert the list of all matches unconditionally instead of adding the
+list as another match.
+
+@kindex insert-ids, completion style
+@item @t{insert-ids}
+When completing process IDs, for example as arguments to the @t{kill} and
+@t{wait} builtins the name of a
+command may be converted to the appropriate process ID.  A problem
+arises when the process name typed is not unique.  By default (or if this
+style is set explicitly to `@t{menu}') the name will be converted
+immediately to a set of possible IDs, and menu completion will be started
+to cycle through them.
+
+@noindent
+If the value of the style is `@t{single}',
+the shell will wait until the user has typed enough to make the command
+unique before converting the name to an ID; attempts at completion will
+be unsuccessful until that point.  If the value is any other
+string, menu completion will be started when the string typed by the
+user is longer than the common prefix to the corresponding IDs.
+
+@kindex insert-tab, completion style
+@item @t{insert-tab}
+If this is set to `true', the completion system will
+insert a TAB character (assuming that was used to start completion) instead
+of performing completion when there is no non-blank character to the left
+of the cursor.  If it is set to `false', completion will be done even there.
+
+@noindent
+The value may also contain the substrings `@t{pending}' or
+`@t{pending=}@var{val}'.  In this case, the typed character will be
+inserted instead of staring completion when there is unprocessed input
+pending.  If a @var{val} is given, completion will not be done if there
+are at least that many characters of unprocessed input.  This is often
+useful when pasting characters into a terminal.  Note
+however, that it relies on the @t{$PENDING} special parameter from the
+@t{zsh/zle} module being set properly which is not guaranteed on all
+platforms.
+
+@noindent
+The default value of this style is `true' except for completion within
+@t{vared} builtin command where it is `false'.
+
+@kindex insert-unambiguous, completion style
+@item @t{insert-unambiguous}
+This is used by the @t{_match} and @t{_approximate} completers.
+These completers are often used with menu completion since the word typed
+may bear little resemblance to the final completion.
+However, if this style is `true', the completer will start menu
+completion only if it could find no unambiguous initial string at
+least as long as the original string typed by the user.
+
+@noindent
+In the case of the @t{_approximate} completer, the completer
+field in the context will already have been set to one of
+@t{correct-}@var{num} or @t{approximate-}@var{num}, where @var{num} is the
+number of errors that were accepted.
+
+@noindent
+In the case of the @t{_match} completer, the style may also be set to
+the string `@t{pattern}'.  Then the pattern on the line is left
+unchanged if it does not match unambiguously.
+
+@kindex keep-prefix, completion style
+@item @t{keep-prefix}
+This style is used by the @t{_expand} completer.  If it is `true', the
+completer will try to keep a prefix containing a tilde or parameter
+expansion.  Hence, for example, the string `@t{~/f*}' would be expanded to
+`@t{~/foo}' instead of `@t{/home/user/foo}'.  If the style is set to
+`@t{changed}' (the default), the prefix will only be left unchanged if
+there were other changes between the expanded words and the original
+word from the command line.  Any other value forces the prefix to be
+expanded unconditionally.
+
+@noindent
+The behaviour of expand when this style is true is to cause @t{_expand}
+to give up when a single expansion with the restored prefix is the same
+as the original; hence any remaining completers may be called.
+
+@kindex last-prompt, completion style
+@item @t{last-prompt}
+This is a more flexible form of the @t{ALWAYS_LAST_PROMPT} option.
+If it is true, the completion system will try to return the cursor to
+the previous command line after displaying a completion list.  It is
+tested for all tags valid for the current completion, then the
+@t{default} tag.  The cursor will be moved back to the
+previous line if this style is `true' for all types of match.  Note
+that unlike the @t{ALWAYS_LAST_PROMPT} option this is independent of the
+numeric prefix argument.
+
+@kindex list, completion style
+@item @t{list}
+This style is used by the @t{_history_complete_word} bindable command.
+If it is set to `true' it has no effect.  If it is set to `false'
+matches will not be listed.  This overrides the setting of the options
+controlling listing behaviour, in particular @t{AUTO_LIST}.  The context
+always starts with `@t{:completion:history-words}'.
+
+@kindex list-colors, completion style
+@item @t{list-colors}
+If the @t{zsh/complist} module is loaded, this style can be used to set
+color specifications.  This mechanism replaces the use of the
+@t{ZLS_COLORS} and @t{ZLS_COLOURS} parameters described in
+@ref{The zsh/complist Module}, but the syntax is the same.
+
+@noindent
+If this style is set for the @t{default} tag, the strings in the value 
+are taken as specifications that are to be used everywhere.  If it is
+set for other tags, the specifications are used only for matches of
+the type described by the tag.  For this to work best, the @t{group-name}
+style must be set to an empty string.  
+
+@noindent
+In addition to setting styles for specific tags, it is also possible to
+use group names specified explicitly by the @t{group-name} tag together
+with the `@t{(group)}' syntax allowed by the @t{ZLS_COLORS} and
+@t{ZLS_COLOURS} parameters and simply using the @t{default} tag.
+
+@noindent
+It is possible to use any color specifications already set up for the GNU
+version of the @t{ls} command:
+
+@noindent
+@example
+zstyle ':completion:*:default' list-colors $@{(s.:.)LS_COLORS@}
+@end example
+
+@noindent
+The default colors are the same as for the GNU @t{ls} command and can be
+obtained by setting the style to an empty string (i.e. @t{@value{dsq}}).
+
+@kindex list-grouped, completion style
+@item @t{list-grouped}
+If this style is `true' (the default), the completion system will try to
+make certain completion listings more compact by grouping matches.
+For example, options for commands that have the same description (shown
+when the @t{verbose} style is set to `true') will appear as a single
+entry.  However, menu selection can be used to cycle through all the
+matches.
+
+@kindex list-packed, completion style
+@item @t{list-packed}
+This is tested for each tag valid in the current context as well as the
+@t{default} tag.  If it is set to `true', the corresponding matches
+appear in listings as if the @t{LIST_PACKED} option were set.  If it is
+set to `false', they are listed normally.
+
+@kindex list-prompt, completion style
+@item @t{list-prompt}
+If this style is set for the @t{default} tag,
+completion lists that don't fit on the screen can be scrolled (see
+@ref{The zsh/complist Module}).  The value, if not the empty string, will be displayed after every
+screenful and the shell will prompt for a key press; if the style is
+set to the empty string,
+a default prompt will be used.
+
+@noindent
+The value may contain the escape sequences:
+`@t{%l}' or `@t{%L}', which will be replaced by the number of the last line
+displayed and the total number of lines; `@t{%m}' or `@t{%M}', 
+the number of the  last match shown and the total number of
+matches; and `@t{%p}' and `@t{%P}', `@t{Top}'
+when at the beginning of the list, `@t{Bottom}' when at the end and the
+position shown as a percentage of the total length otherwise.  In each
+case the form with the uppercase letter will be replaced by a string of fixed
+width, padded to the  right with spaces, while the lowercase form will
+be replaced by a variable width string.  As in other prompt strings, the
+escape sequences `@t{%S}', `@t{%s}', `@t{%B}', `@t{%b}', `@t{%U}',
+`@t{%u}' for entering and leaving the display modes
+standout, bold and underline are also available, as is the form
+`@t{%@{}...@t{%@}}' for enclosing escape sequences which display with zero
+width.
+
+@kindex list-rows-first, completion style
+@item @t{list-rows-first}
+This style is tested in the same way as the @t{list-packed} style and
+determines whether matches are to be listed in a rows-first fashion as
+if the @t{LIST_ROWS_FIRST} option were set.
+
+@kindex list-suffixes, completion style
+@item @t{list-suffixes}
+This style is used by the function that completes filenames.  If it is
+true, and completion is attempted on a string containing multiple partially
+typed pathname components, all ambiguous components will be shown.
+Otherwise, completion stops at the first ambiguous component.
+
+@kindex list-separator, completion style
+@item @t{list-separator}
+The value of this style is used in completion listing to separate the
+string to complete from a description when possible (e.g. when
+completing options).  It defaults to `@t{-}@t{-}' (two hyphens).
+
+@kindex local, completion style
+@item @t{local}
+This is for use with functions that complete URLs for which the
+corresponding files are available directly from the filing system.
+Its value should consist of three strings: a
+hostname, the path to the default web pages for the server, and the
+directory name used by a user placing web pages within their home
+area.
+
+@noindent
+For example:
+
+@noindent
+@example
+zstyle ':completion:*' local toast \ 
+    /var/http/public/toast public_html
+@end example
+
+@noindent
+Completion after `@t{http://toast/stuff/}' will look for files in the
+directory @t{/var/http/public/toast/stuff},  while completion after
+`@t{http://toast/~yousir/}' will look for files in the directory
+@t{~yousir/public_html}.
+
+@kindex mail-directory, completion style
+@item @t{mail-directory}
+If set, zsh will assume that mailbox files can be found in
+the directory specified.  It defaults to `@t{~/Mail}'.
+
+@kindex match-original, completion style
+@item @t{match-original}
+This is used by the @t{_match} completer.  If it is set to
+@t{only}, @t{_match} will try to generate matches without inserting a
+`@t{*}' at the cursor position.  If set to any other non-empty value,
+it will first try to generate matches without inserting the `@t{*}'
+and if that yields no matches, it will try again with the `@t{*}'
+inserted.  If it is unset or set to the empty string, matching will
+only be performed with the `@t{*}' inserted.
+
+@kindex matcher, completion style
+@item @t{matcher}
+This style is tested separately for each tag valid in the current
+context.  Its value is added to any match specifications given by the 
+@t{matcher-list} style.  It should be in the form described in
+@ref{Matching Control}.
+
+@kindex matcher-list, completion style
+@item @t{matcher-list}
+This style can be set to a list of match specifications that are to
+be applied everywhere. Match specifications are described in
+@ref{Matching Control}.
+The completion system will try them one after another for each completer
+selected.  For example, to try first simple completion and, if that
+generates no matches, case-insensitive completion:
+
+@noindent
+@example
+zstyle ':completion:*' matcher-list @value{dsq} 'm:@{a-zA-Z@}=@{A-Za-z@}'
+@end example
+
+@noindent
+By default each specification replaces the previous one; however, if a
+specification is prefixed with @t{+}, it is added to the existing list.
+Hence it is possible to create increasingly general specifications
+without repetition:
+
+@noindent
+@example
+zstyle ':completion:*' matcher-list @value{dsq} '+m@{a-Z@}=@{A-Z@}' '+m@{A-Z@}=@{a-z@}'
+@end example
+
+@noindent
+It is possible to create match specifications valid for particular
+completers by using the third field of the context.  For example, to
+use the completers @t{_complete} and @t{_prefix} but only allow
+case-insensitive completion with @t{_complete}:
+
+@noindent
+@example
+zstyle ':completion:*' completer _complete _prefix
+zstyle ':completion:*:complete:*' matcher-list \ 
+       @value{dsq} 'm:@{a-zA-Z@}=@{A-Za-z@}'
+@end example
+
+@noindent
+User-defined names, as explained for the @t{completer} style, are
+available.  This makes it possible to try the same completer more than
+once with different match specifications each time.  For example, to try
+normal completion without a match specification, then normal completion
+with case-insensitive matching, then correction, and finally
+partial-word completion:
+
+@noindent
+@example
+zstyle ':completion:*' completer _complete _correct _complete:foo
+zstyle ':completion:*:complete:*' matcher-list \ 
+    @value{dsq} 'm:@{a-zA-Z@}=@{A-Za-z@}'
+zstyle ':completion:*:foo:*' matcher-list \ 
+    'm:@{a-zA-Z@}=@{A-Za-z@} r:|[-_./]=* r:|=*'
+@end example
+
+@noindent
+If the style is unset in any context no match specification is applied.
+Note also that some completers such as @t{_correct} and @t{_approximate}
+do not use the match specifications at all, though these completers will
+only ever called once even if the @t{matcher-list} contains more than
+one element.
+
+@noindent
+Where multiple specifications are useful, note that the @emph{entire}
+completion is done for each element of @t{matcher-list}, which can
+quickly reduce the shell's performance.  As a rough rule of thumb,
+one to three strings will give acceptable performance.  On the other
+hand, putting multiple space-separated values into the same string does
+not have an appreciable impact on performance.
+
+@kindex max-errors, completion style
+@item @t{max-errors}
+This is used by the @t{_approximate} and @t{_correct} completer functions
+to determine the maximum number of errors to allow.  The completer will try
+to generate completions by first allowing one error, then two errors, and
+so on, until either a match or matches were found or the maximum number of
+errors given by this style has been reached.
+
+@noindent
+If the value for this style contains the string `@t{numeric}', the 
+completer function will take any numeric argument as the
+maximum number of errors allowed. For example, with
+
+@noindent
+@example
+zstyle ':completion:*:approximate:::' max-errors 2 numeric
+@end example
+
+@noindent
+two errors are allowed if no numeric argument is given, but with
+a numeric argument of six (as in `@t{ESC-6 TAB}'), up to six
+errors are accepted.  Hence with a value of `@t{0 numeric}', no correcting
+completion will be attempted unless a numeric argument is given.
+
+@noindent
+If the value contains the string `@t{not-numeric}', the completer
+will @emph{not} try to generate corrected
+completions when given a numeric argument, so in this case the number given
+should be greater than zero.  For example, `@t{2 not-numeric}' specifies that
+correcting completion with two errors will usually be performed, but if a
+numeric argument is given, correcting completion will not be
+performed.
+
+@noindent
+The default value for this style is `@t{2 numeric}'.
+
+@kindex max-matches-width, completion style
+@item @t{max-matches-width}
+This style is used to determine the trade off between the width of the
+display used for matches and the width used for their descriptions when
+the @t{verbose} style is in effect.  The value gives the number of
+display columns to reserve for the matches.  The default is half the
+width of the screen.
+
+@noindent
+This has the most impact when several matches have the
+same description and so will be grouped together.  Increasing the style
+will allow more matches to be grouped together; decreasing it will allow
+more of the description to be visible.
+
+@kindex menu, completion style
+@item @t{menu}
+If this is true in the context of any of the tags defined
+for the current completion menu completion will be used.  The value for
+a specific tag will take precedence over that for the `@t{default}' tag.
+
+@noindent
+If none of the values found in this way is true but at least
+one is set to `@t{auto}', the shell behaves as if the @t{AUTO_MENU}
+option is set.
+
+@noindent
+If one of the values is explicitly set to false, menu
+completion will be explicitly turned off, overriding the
+@t{MENU_COMPLETE} option and other settings.
+
+@noindent
+In the form `@t{yes=}@var{num}', where `@t{yes}' may be any of the
+true values (`@t{yes}', `@t{true}', `@t{on}' and `@t{1}'),
+menu completion will be turned on if there are at least @var{num} matches.
+In the form `@t{yes=long}', menu completion will be turned on
+if the list does not fit on the screen.  This does not activate menu
+completion if the widget normally only lists completions, but menu
+completion can be activated in that case with the value `@t{yes=long-list}'
+(Typically, the value `@t{select=long-list}' described later is more
+useful as it provides control over scrolling.)
+
+@noindent
+Similarly, with any of the `false' values (as in `@t{no=10}'), menu
+completion will @emph{not} be used if there are @var{num} or more matches.  
+
+@noindent
+The value of this widget also controls menu selection, as implemented by
+the @t{zsh/complist} module.  The following values may appear either
+alongside or instead of the values above.
+
+@noindent
+If the value contains the string `@t{select}', menu selection
+will be started unconditionally.
+
+@noindent
+In the form `@t{select=}@var{num}', menu selection will only be started if
+there are at least @var{num} matches.  If the values for more than one
+tag provide a number, the smallest number is taken.
+
+@noindent
+Menu selection can be turned off explicitly by defining a value
+containing the string`@t{no-select}'.
+
+@noindent
+It is also possible to start menu selection only if the list of
+matches does not fit on the screen by using the value
+`@t{select=long}'.  To start menu selection even if the current widget
+only performs listing, use the value `@t{select=long-list}'.
+
+@noindent
+To turn on menu completion or menu selection when a there are a certain
+number of matches @emph{or} the list of matches does not fit on the
+screen, both of `@t{yes=}' and `@t{select=}' may be given twice, once
+with a number and once with `@t{long}' or `@t{long-list}'.
+
+@noindent
+Finally, it is possible to activate two special modes of menu selection.
+The word `@t{interactive}' in the value causes interactive mode
+to be entered immediately when menu selection is started; see
+@ref{The zsh/complist Module} for a description of interactive mode.  Including the string
+`@t{search}' does the same for incremental search mode.  To select backward
+incremental search, include the string `@t{search-backward}'.
+)
+@kindex muttrc, completion style
+@item @t{muttrc}
+If set, gives the location of the mutt configuration file.  It defaults
+to `@t{~/.muttrc}'.
+
+@kindex numbers, completion style
+@item @t{numbers}
+This is used with the @t{jobs} tag.  If it is `true', the shell will
+complete job numbers instead of the shortest unambiguous prefix
+of the job command text.  If the value is a number, job numbers will
+only be used if that many words from the job descriptions are required to
+resolve ambiguities.  For example, if the value is `@t{1}', strings will
+only be used if all jobs differ in the first word on their command lines.
+
+@kindex old-list, completion style
+@item @t{old-list}
+This is used by the @t{_oldlist} completer.  If it is set to `@t{always}',
+then standard widgets which perform listing will retain the current list of
+matches, however they were generated; this can be turned off explicitly
+with the value `@t{never}', giving the behaviour without the @t{_oldlist}
+completer.  If the style is unset, or any other value, then the existing
+list of completions is displayed if it is not already; otherwise, the
+standard completion list is generated; this is the default behaviour of
+@t{_oldlist}.  However, if there is an old list and this style contains
+the name of the completer function that generated the list, then the
+old list will be used even if it was generated by a widget which does
+not do listing.
+
+@noindent
+For example, suppose you type @t{^Xc} to use the @t{_correct_word}
+widget, which generates a list of corrections for the word under the
+cursor.  Usually, typing @t{^D} would generate a standard list of
+completions for the word on the command line, and show that.  With
+@t{_oldlist}, it will instead show the list of corrections already
+generated.
+
+@noindent
+As another example consider the @t{_match} completer: with the
+@t{insert-unambiguous} style set to `true' it inserts only a common prefix
+string, if there is any.  However, this may remove parts of the original
+pattern, so that further completion could produce more matches than on the
+first attempt.  By using the @t{_oldlist} completer and setting this style
+to @t{_match}, the list of matches generated on the first attempt will be
+used again.
+
+@kindex old-matches, completion style
+@item @t{old-matches}
+This is used by the @t{_all_matches} completer to decide if an old
+list of matches should be used if one exists.  This is selected by one of
+the `true' values or by the string `@t{only}'.  If
+the value is `@t{only}', @t{_all_matches} will only use an old list
+and won't have any effect on the list of matches currently being
+generated.
+
+@noindent
+If this style is set it is generally unwise to call the @t{_all_matches}
+completer unconditionally.  One possible use is for either this style or
+the @t{completer} style to be defined with the @t{-e} option to
+@t{zstyle} to make the style conditional.
+
+@kindex old-menu, completion style
+@item @t{old-menu}
+This is used by the @t{_oldlist} completer.  It controls how menu
+completion behaves when a completion has already been inserted and the
+user types a standard completion key such as @t{TAB}.  The default
+behaviour of @t{_oldlist} is that menu completion always continues
+with the existing list of completions.  If this style is set to
+`false', however, a new completion is started if the old list was
+generated by a different completion command; this is the behaviour without
+the @t{_oldlist} completer.
+
+@noindent
+For example, suppose you type @t{^Xc} to generate a list of corrections,
+and menu completion is started in one of the usual ways.  Usually, or with
+this style set to @t{false}, typing @t{TAB} at this point would start
+trying to complete the line as it now appears.  With @t{_oldlist}, it
+instead continues to cycle through the list of corrections.
+
+@kindex original, completion style
+@item @t{original}
+This is used by the @t{_approximate} and @t{_correct}
+completers to decide if the original string should be added as
+a possible completion.  Normally, this is done only if there are
+at least two possible corrections, but if this style is set to `true', it
+is always added.  Note that the style will be examined with the
+completer field in the context name set to @t{correct-}@var{num} or
+@t{approximate-}@var{num}, where @var{num} is the number of errors that
+were accepted.
+
+@kindex packageset, completion style
+@item @t{packageset}
+This style is used when completing arguments of the Debian `@t{dpkg}'
+program.  It contains an override for the default package set
+for a given context.  For example,
+
+@noindent
+@example
+zstyle ':completion:*:complete:dpkg:option--status-1:*' \ 
+               packageset avail
+@end example
+
+@noindent
+causes available packages, rather than only installed packages,
+to be completed for `dpkg --status'.
+
+@kindex path, completion style
+@item @t{path}
+The function that completes color names uses this style with the 
+@t{colors} tag.  The value should be the pathname of a file
+containing color names in the format of an X11 @t{rgb.txt} file.  If
+the style is not set but this file is found in one of various standard
+locations it will be used as the default.
+
+@kindex pine-directory, completion style
+@item @t{pine-directory}
+If set, specifies the directory containing PINE mailbox files.  It
+defaults to `@t{~/mail}'.
+
+@kindex ports, completion style
+@item @t{ports}
+A list of Internet service names (network ports) to complete.  If this is
+not set, service names are taken from the file `@t{/etc/services}'.
+
+@kindex prefix-hidden, completion style
+@item @t{prefix-hidden}
+This is used for certain completions which share a common prefix, for
+example command options beginning with dashes.  If it is `true', the
+prefix will not be shown in the list of matches.
+
+@noindent
+The default value for this style is `false'.
+
+@kindex prefix-needed, completion style
+@item @t{prefix-needed}
+This, too, is used for matches with a common prefix.  If it is set to
+`true' this common prefix must be typed by the user to generate the
+matches.  In the case of command options, this means that the initial
+`@t{-}', `@t{+}', or `@t{-}@t{-}' must be typed explicitly before option
+names will be completed.
+
+@noindent
+The default value for this style is `true'.
+
+@kindex preserve-prefix, completion style
+@item @t{preserve-prefix}
+This style is used when completing path names.  Its value should be a
+pattern matching an initial prefix of the word to complete that should
+be left unchanged under all circumstances.  For example, on some Unices
+an initial `@t{//}' (double slash) has a special meaning; setting
+this style to the string `@t{//}' will preserve it.  As another example,
+setting this style to `@t{?:/}' under Cygwin would allow completion
+after `@t{a:/...}' and so on.
+
+@kindex range, completion style
+@item @t{range}
+This is used by the @t{_history} completer and the
+@t{_history_complete_word} bindable command to decide which words
+should be completed.  
+
+@noindent
+If it is a singe number, only the last @var{N} words from the history
+will be completed.
+
+@noindent
+If it is a range of the form `@var{max}@t{:}@var{slice}',
+the last @var{slice} words will be completed; then if that
+yields no matches, the @var{slice} words before those will be tried and 
+so on.  This process stops either when at least one match was been
+found, or @var{max} words have been tried.
+
+@noindent
+The default is to complete all words from the history at once.
+
+@kindex regular, completion style
+@item @t{regular}
+This style is used by the @t{_expand_alias} completer and bindable 
+command.  If set to `@t{true}' (the default), regular aliases will be
+expanded but only in command position.  If it is set to `@t{false}',
+regular aliases will never be expanded.   If it is set to `@t{always}',
+regular aliases will be expanded even if not in command position.
+
+@kindex remote-access, completion style
+@item @t{remote-access}
+If set to @t{false}, certain commands will be prevented from making
+Internet connections to retrieve remote information.  This includes the
+completion for the @t{CVS} command.
+
+@noindent
+It is not always possible to know if connections are in fact to a remote
+site, so some may be prevented unnecessarily.
+
+@kindex remove-all-dups, completion style
+@item @t{remove-all-dups}
+The @t{_history_complete_word} bindable command and the @t{_history}
+completer use this to decide if all duplicate matches should be
+removed, rather than just consecutive duplicates.
+
+@kindex select-prompt, completion style
+@item @t{select-prompt}
+If this is set for the @t{default} tag, its
+value will be displayed during menu selection (see the @t{menu} style
+above) when the completion list does not fit on the screen as a
+whole.  The same escapes as for the @t{list-prompt} style are
+understood, except that the numbers refer to the match or line the mark is
+on.  A default prompt is used when the value is the empty string.
+
+@kindex select-scroll, completion style
+@item @t{select-scroll}
+This style is tested for the @t{default} tag and determines how a
+completion list is scrolled during a menu selection (see the @t{menu}
+style above) when the completion list does not fit on the screen as a
+whole.  If the value is `@t{0}' (zero), the list is scrolled by
+half-screenfuls; if it is a positive integer, the list is scrolled by the
+given number of lines; if it is a negative number, the list is scrolled by a
+screenful minus the absolute value of the given number of lines.
+The default is to scroll by single lines.
+
+@kindex separate-sections, completion style
+@item @t{separate-sections}
+This style is used with the @t{manuals} tag when completing names of
+manual pages.  If it is `true', entries for different sections are
+added separately using tag names of the form `@t{manual.}@var{X}',
+where @var{X} is the section number.  When the @t{group-name} style is
+also in effect, pages from different sections will appear separately.
+This style is also used similarly with the @t{words} style when
+completing words for the dict command. It allows words from different
+dictionary databases to be added separately.
+The default for this style is `false'.
+
+@kindex show-completer, completion style
+@item @t{show-completer}
+Tested whenever a new completer is tried.  If it is true, the completion
+system outputs a progress message in the listing area showing what
+completer is being tried.  The message will be overwritten by any output
+when completions are found and is removed after completion is finished.
+
+@kindex single-ignored, completion style
+@item @t{single-ignored}
+This is used by the @t{_ignored} completer when there is only one match.
+If its value is `@t{show}', the single match will be
+displayed but not inserted.  If the value is `@t{menu}', then the single
+match and the original string are both added as matches and menu completion
+is started, making it easy to select either of them.
+
+@kindex sort, completion style
+@item @t{sort}
+Many completion widgets call @t{_description} at some point which
+decides whether the matches are added sorted or unsorted (often
+indirectly via @t{_wanted} or @t{_requested}).  This style can be set
+explicitly to one of the usual true or false values as an override.
+If it is not set for the context, the standard behaviour of the
+calling widget is used.
+
+@noindent
+The style is tested first against the full context including the tag, and
+if that fails to produce a value against the context without the tag.
+
+@noindent
+If the calling widget explicitly requests unsorted matches, this is usually
+honoured.  However, the default (unsorted) behaviour of completion
+for the command history may be overridden by setting the style to
+@t{true}.
+
+@noindent
+In the @t{_expand} completer, if it is set to
+`true', the expansions generated will always be sorted.  If it is set
+to `@t{menu}', then the expansions are only sorted when they are offered 
+as single strings but not in the string containing all possible
+expansions.
+
+@kindex special-dirs, completion style
+@item @t{special-dirs}
+Normally, the completion code will not produce the directory names
+`@t{.}' and `@t{..}' as possible completions.  If this style is set to
+`true', it will add both `@t{.}' and `@t{..}' as possible completions;
+if it is set to `@t{..}', only `@t{..}' will be added.
+
+@noindent
+The following example sets @t{special-dirs} to `@t{..}' when the
+current prefix is empty, is a single `@t{.}', or consists only of a path
+beginning with `@t{../}'.  Otherwise the value is `false'.
+
+@noindent
+@example
+zstyle -e ':completion:*' special-dirs \ 
+   '[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'
+@end example
+
+@kindex squeeze-slashes, completion style
+@item @t{squeeze-slashes}
+If set to `true', sequences of slashes in filename paths (for example in
+`@t{foo//bar}') will be treated as a single slash.  This is the usual
+behaviour of UNIX paths.  However, by default the file completion
+function behaves as if there were a `@t{*}' between the slashes.
+
+@kindex stop, completion style
+@item @t{stop}
+If set to `true', the @t{_history_complete_word} bindable
+command will stop once when reaching the beginning or end of the
+history.  Invoking @t{_history_complete_word} will then wrap around to 
+the opposite end of the history.  If this style is set to `false' (the 
+default), @t{_history_complete_word} will loop immediately as in a
+menu completion.
+
+@kindex strip-comments, completion style
+@item @t{strip-comments}
+If set to `true', this style causes non-essential comment text to be
+removed from completion matches.  Currently it is only used when
+completing e-mail addresses where it removes any display name from the
+addresses, cutting them down to plain @var{user@@host} form.
+
+@kindex subst-globs-only, completion style
+@item @t{subst-globs-only}
+This is used by the @t{_expand} completer.  If it is set to `true',
+the expansion will only be used if it resulted from globbing; hence,
+if expansions resulted from the use of the @t{substitute} style
+described below, but these were not further changed by globbing, the
+expansions will be rejected.
+
+@noindent
+The default for this style is `false'.
+
+@kindex substitute, completion style
+@item @t{substitute}
+This boolean style controls whether the @t{_expand} completer will
+first try to expand all substitutions in the string (such as
+`@t{$(...)}' and `@t{$@{...@}}').
+
+@noindent
+The default is `true'.
+
+@kindex suffix, completion style
+@item @t{suffix}
+This is used by the @t{_expand} completer if the word starts with a
+tilde or contains a parameter expansion.  If it is set to `true', the
+word will only be expanded if it doesn't have a suffix, i.e. if it is
+something like `@t{~foo}' or `@t{$foo}' rather than `@t{~foo/}' or
+`@t{$foo/bar}', unless that suffix itself contains characters eligible
+for expansion.  The default for this style is `true'.
+
+@kindex tag-order, completion style
+@item @t{tag-order}
+This provides a mechanism for sorting how the tags available in a
+particular context will be used.
+
+@noindent
+The values for the style are sets of space-separated lists of tags.
+The tags in each value will be tried at the same time; if no match is
+found, the next value is used.  (See the @t{file-patterns} style for
+an exception to this behavior.)
+
+@noindent
+For example:
+
+@noindent
+@example
+zstyle ':completion:*:complete:-command-:*' tag-order \ 
+    'commands functions'
+@end example
+
+@noindent
+specifies that completion in command position first offers
+external commands and shell functions.  Remaining tags will be tried if
+no completions are found.
+
+@noindent
+In addition to tag names, each string in the value may take one of the
+following forms:
+
+@noindent
+@table @asis
+@item @t{-}
+If any value consists of only a hyphen,
+then @emph{only} the tags specified in the other values are
+generated.  Normally all tags not explicitly selected are tried last
+if the specified tags fail to generate any matches.  This means 
+that a single value consisting only of a single hyphen
+turns off completion.
+
+@item @t{!} @var{tags}...
+A string starting with an exclamation mark
+specifies names of tags that are @emph{not} to be used.  The effect is
+the same as if all other possible tags for the context had been
+listed.
+
+@item @var{tag}@t{:}@var{label} ...
+Here, @var{tag} is one of the standard tags and @var{label} is an
+arbitrary name.  Matches are generated as normal but the name @var{label}
+is used in contexts instead of @var{tag}.  This is not useful in words
+starting with @t{!}.
+
+@noindent
+If the @var{label} starts with a hyphen, the @var{tag} is prepended to the
+@var{label} to form the name used for lookup.  This can be
+used to make the completion system try a certain tag more than once,
+supplying different style settings for each attempt; see below for an
+example.
+
+@item @var{tag}@t{:}@var{label}@t{:}@var{description}
+As before, but @t{description} will replace the `@t{%d}' in
+the value of the @t{format} style instead of the default description
+supplied by the completion function.  Spaces in the description must
+be quoted with a backslash.  A `@t{%d}' appearing
+in @var{description} is replaced with the description given by the
+completion function.
+
+@end table
+
+@noindent
+In any of the forms above the tag may be a pattern or several
+patterns in the form `@t{@{}@var{pat1}@t{,}@var{pat2...}@t{@}}'.  In this
+case all matching tags will be used except 
+for any given explicitly in the same string.
+
+@noindent
+One use of these features is to try
+one tag more than once, setting other styles differently on
+each attempt, but still to use all the other tags without having to
+repeat them all.  For example, to make completion of function names in
+command position ignore all the completion functions starting with an
+underscore the first time completion is tried:
+
+@noindent
+@example
+zstyle ':completion:*:*:-command-:*' tag-order \ 
+    'functions:-non-comp *' functions
+zstyle ':completion:*:functions-non-comp' ignored-patterns '_*'
+@end example
+
+@noindent
+On the first attempt, all tags will be offered but the @t{functions} tag
+will be replaced by @t{functions-non-comp}.  The @t{ignored-patterns} style 
+is set for this tag to exclude functions starting with an underscore.
+If there are no matches, the second value of the
+@t{tag-order} style is used which completes functions using the default
+tag, this time presumably including all function names.
+
+@noindent
+The matches for one tag can be split into different groups.  For example:
+
+@noindent
+@example
+zstyle ':completion:*' tag-order \ 
+    'options:-long:long\ options
+     options:-short:short\ options
+     options:-single-letter:single\ letter\ options'
+
+@noindent
+zstyle ':completion:*:options-long' ignored-patterns '[-+](|-|[^-]*)'
+zstyle ':completion:*:options-short' ignored-patterns '--*' '[-+]?'
+zstyle ':completion:*:options-single-letter' ignored-patterns '???*'
+@end example
+
+@noindent
+With the @t{group-names} style set, options beginning with
+`@t{-}@t{-}', options beginning with a single `@t{-}' or `@t{+}' but
+containing multiple characters, and single-letter options will be
+displayed in separate groups with different descriptions.
+
+@noindent
+Another use of patterns is to
+try multiple match specifications one after another.  The
+@t{matcher-list} style offers something similar, but it is tested very
+early in the completion system and hence can't be set for single
+commands nor for more specific contexts.  Here is how to
+try normal completion without any match specification and, if that
+generates no matches, try again with case-insensitive matching, restricting
+the effect to arguments of the command @t{foo}:
+
+@noindent
+@example
+zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
+zstyle ':completion:*-case' matcher 'm:@{a-z@}=@{A-Z@}'
+@end example
+
+@noindent
+First, all the tags offered when completing after @t{foo} are tried using
+the normal tag name.  If that generates no matches, the second value of
+@t{tag-order} is used, which tries all tags again except that this time
+each has @t{-case} appended to its name for lookup of styles.  Hence this
+time the value for the @t{matcher} style from the second call to @t{zstyle}
+in the example is used to make completion case-insensitive.
+
+@noindent
+It is possible to use the @t{-e} option of the @t{zstyle} builtin
+command to specify conditions for the use of particular tags.  For
+example:
+
+@noindent
+@example
+zstyle -e '*:-command-:*' tag-order '
+    if [[ -n $PREFIX$SUFFIX ]]; then
+      reply=( )
+    else
+      reply=( - )
+    fi'
+@end example
+
+@noindent
+Completion in command position will be attempted only if the string
+typed so far is not empty.  This is tested using the @t{PREFIX}
+special parameter; see
+@ref{Completion Widgets}
+for a description of parameters which are special inside completion widgets.
+Setting @t{reply} to an empty array provides the default
+behaviour of trying all tags at once; setting it to an
+array containing only a hyphen disables the use of all tags and hence of
+all completions.
+
+@noindent
+If no @t{tag-order} style has been defined for a context, the strings
+`@t{(|*-)argument-* (|*-)option-* values}' and `@t{options}' plus all
+tags offered by the completion function will be used to provide a
+sensible default behavior that causes arguments (whether normal command
+arguments or arguments of options) to be completed before option names for
+most commands.
+
+@kindex urls, completion style
+@item @t{urls}
+This is used together with the the @t{urls} tag by
+functions completing URLs.
+
+@noindent
+If the value consists of more than one string, or if the only string
+does not name a file or directory, the strings are used as the URLs to
+complete.
+
+@noindent
+If the value contains only one string which is the name of a normal 
+file the URLs are taken from that file (where the URLs may be
+separated by white space or newlines).
+
+@noindent
+Finally, if the only string in the value names a directory, the
+directory hierarchy rooted at this directory gives the completions.  The
+top level directory should be the file access method, such as
+`@t{http}', `@t{ftp}', `@t{bookmark}' and so on.  In many cases the next
+level of directories will be a filename.  The directory hierarchy can
+descend as deep as necessary.
+
+@noindent
+For example, 
+
+@noindent
+@example
+zstyle ':completion:*' urls ~/.urls
+mkdir -p ~/.urls/ftp/ftp.zsh.org/pub/development
+
+@end example
+
+@noindent
+allows completion of all the components of the URL
+@t{ftp://ftp.zsh.org/pub/development} after suitable commands such as
+`@t{netscape}' or `@t{lynx}'.  Note, however, that access methods and
+files are completed separately, so if the @t{hosts} style is set hosts
+can be completed without reference to the @t{urls} style.
+
+@noindent
+See the description in the function @t{_urls} itself
+for more information (e.g. `@t{more $^fpath/_urls(N)}').
+
+@kindex use-cache, completion style
+@item @t{use-cache}
+If this is set, the completion caching layer is activated for any completions
+which use it (via the @t{_store_cache}, @t{_retrieve_cache}, and
+@t{_cache_invalid} functions).  The directory containing the cache
+files can be changed with the @t{cache-path} style.
+
+@kindex use-compctl, completion style
+@item @t{use-compctl}
+If this style is set to a string @emph{not} equal to @t{false}, @t{0},
+@t{no}, and @t{off}, the completion system may use any completion
+specifications defined with the @t{compctl} builtin command.  If the
+style is unset, this is done only if the @t{zsh/compctl} module
+is loaded.  The string may also contain the substring `@t{first}' to
+use completions defined with `@t{compctl -T}', and the substring
+`@t{default}' to use the completion defined with `@t{compctl -D}'.
+
+@noindent
+Note that this is only intended to smooth the transition from
+@t{compctl} to the new completion system and may disappear in the
+future.
+
+@noindent
+Note also that the definitions from @t{compctl} will only be used if
+there is no specific completion function for the command in question.  For
+example, if there is a function @t{_foo} to complete arguments to the
+command @t{foo}, @t{compctl} will never be invoked for @t{foo}.
+However, the @t{compctl} version will be tried if @t{foo} only uses
+default completion.
+
+@kindex use-perl, completion style
+@item @t{use-perl}
+Various parts of the function system use awk to extract words from
+files or command output as this universally available.  However, many
+versions of awk have arbitrary limits on the size of input.  If this
+style is set, perl will be used instead.  This is almost always
+preferable if perl is available on your system.
+
+@noindent
+Currently this is only used in completions for `make', but it may be
+extended depending on authorial frustration.
+
+@kindex users, completion style
+@item @t{users}
+This may be set to a list of usernames to be completed.
+If it is not set or the string on the line
+doesn't match any of the strings in this list, all usernames will be
+completed.
+
+@kindex users-hosts, completion style
+@item @t{users-hosts}
+The values of this style should be of the form
+`@var{user}@t{@@}@var{host}' or `@var{user}@t{:}@var{host}'. It is used for
+commands that need pairs of
+user- and hostnames.  These commands will complete usernames from this
+style (only), and will restrict subsequent hostname completion to hosts
+paired with that user in one of the values of the style.
+
+@noindent
+It is possible to group values for sets of commands which allow a remote
+login, such as @t{rlogin} and @t{ssh}, by using the @t{my-accounts} tag.
+Similarly, values for sets of commands which usually refer to the
+accounts of other people, such as @t{talk} and @t{finger}, can be
+grouped by using the @t{other-accounts} tag.  More ambivalent commands
+may use the @t{accounts} tag.
+
+@kindex users-hosts-ports, completion style
+@item @t{users-hosts-ports}
+Like @t{users-hosts} but used for commands like @t{telnet} and
+containing strings of the form `@var{user}@t{@@}@var{host}@t{:}@var{port}'.
+
+@kindex verbose, completion style
+@item @t{verbose}
+If set, as it is by default, the completion listing is more verbose.
+In particular many commands show descriptions for options if this
+style is `true'.
+
+@kindex word, completion style
+@item @t{word}
+This is used by the @t{_list} completer, which prevents the insertion of
+completions until a second completion attempt when the line has not
+changed.  The normal way of finding out if the line has changed is to
+compare its entire contents between the two occasions.  If this style is
+true, the comparison is instead performed only on the current word.
+Hence if completion is performed on another word with the same contents,
+completion will not be delayed.
+
+@end table
+
+@noindent
+@node Control Functions, Bindable Commands, Completion System Configuration, Completion System
+
+@section Control Functions
+@noindent
+@cindex completion system, choosing completers
+
+@noindent
+The initialization script @t{compinit} redefines all the widgets
+which perform completion to call the supplied widget function
+@t{_main_complete}.  This function acts as a wrapper calling the
+so-called `completer' functions that generate matches.  If
+@t{_main_complete} is called with arguments, these are taken as the
+names of completer functions to be called in the order given.  If no
+arguments are given, the set of functions to try is taken from the
+@t{completer} style.  For example, to use normal completion and
+correction if that doesn't generate any matches:
+
+@noindent
+@example
+zstyle ':completion:*' completer _complete _correct
+@end example
+
+@noindent
+after calling @t{compinit}. The default value for this style is
+`@t{_complete _ignored}', i.e. normally only ordinary completion is tried,
+first with the effect of the @t{ignored-patterns} style and then without
+it.  The @t{_main_complete} function uses the return value of the completer
+functions to decide if other completers should be called.  If the return
+value is zero, no other completers are tried and the @t{_main_complete}
+function returns.
+
+@noindent
+If the first argument to @t{_main_complete} is a single hyphen, the
+arguments will not be taken as names of completers.  Instead, the
+second argument gives a name to use in the @var{completer} field of the 
+context and the other arguments give a command name and arguments to
+call to generate the matches.
+
+@noindent
+The following completer functions are contained in the distribution,
+although users may write their own.  Note that in contexts the leading
+underscore is stripped, for example basic completion is performed in the
+context `@t{:completion::complete:}@var{...}'.
+
+@noindent
+@cindex completion system, completers
+@table @asis
+@findex _all_matches
+@item @t{_all_matches}
+This completer can be used to add a string consisting of all other
+matches.  As it influences later completers it must appear as the first
+completer in the list.  The list of all matches is affected by the
+@t{avoid-completer} and @t{old-matches} styles described above.
+
+@noindent
+It may be useful to use the @t{_generic} function described below
+to bind @t{_all_matches} to its own keystroke, for example:
+
+@noindent
+@example
+zle -C all-matches complete-word _generic
+bindkey '^Xa' all-matches
+zstyle ':completion:all-matches:*' old-matches only
+zstyle ':completion:all-matches::::' completer _all_matches
+@end example
+
+@findex _approximate
+@item @t{_approximate}
+This is similar to the basic @t{_complete} completer but allows the
+completions to undergo corrections.  The maximum number of errors can be
+specified by the @t{max-errors} style; see the description of
+approximate matching in
+@ref{Filename Generation}
+for how errors are counted.  Normally this completer will only be tried
+after the normal @t{_complete} completer:
+
+@noindent
+@example
+zstyle ':completion:*' completer _complete _approximate
+@end example
+
+@noindent
+This will give correcting completion if and only if
+normal completion yields no possible completions.  When
+corrected completions are found, the completer will normally start
+menu completion allowing you to cycle through these strings.
+
+@noindent
+This completer uses the tags @t{corrections} and @t{original} when
+generating the possible corrections and the original string.  The
+@t{format} style for the former may contain the additional sequences
+`@t{%e}' and `@t{%o}' which will be replaced by the number of errors
+accepted to generate the corrections and the original string,
+respectively.
+
+@noindent
+The completer progressively increases the number of errors allowed up to
+the limit by the @t{max-errors} style, hence if a completion is found
+with one error, no completions with two errors will be shown, and so on.
+It modifies the completer name in the context to indicate the number of
+errors being tried: on the first try the completer field contains
+`@t{approximate-1}', on the second try `@t{approximate-2}', and so on.
+
+@noindent
+When @t{_approximate} is called from another function, the number of
+errors to accept may be passed with the @t{-a} option.  The argument
+is in the same format as the @t{max-errors} style, all in one string.
+
+@noindent
+Note that this completer (and the @t{_correct} completer mentioned
+below) can be quite expensive to call, especially when a large number
+of errors are allowed.  One way to avoid this is to set up the
+@t{completer} style using the @t{-e} option to zstyle so that some
+completers are only used when completion is attempted a second time on 
+the same string, e.g.:
+
+@noindent
+@example
+zstyle -e ':completion:*' completer '
+  if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then
+    _last_try="$HISTNO$BUFFER$CURSOR"
+    reply=(_complete _match _prefix)
+  else
+    reply=(_ignored _correct _approximate)
+  fi'
+@end example
+
+@noindent
+This uses the @t{HISTNO} parameter and the @t{BUFFER} and @t{CURSOR}
+special parameters that are available inside zle and completion
+widgets to find out if the command line hasn't changed since the last
+time completion was tried.  Only then are the @t{_ignored},
+@t{_correct} and @t{_approximate} completers called.
+
+@findex _complete
+@item @t{_complete}
+This completer generates all possible completions in a context-sensitive
+manner, i.e. using the settings defined with the @t{compdef} function
+explained above and the current settings of all special parameters.
+This gives the normal completion behaviour.
+
+@noindent
+To complete arguments of commands, @t{_complete} uses the utility function
+@t{_normal}, which is in turn responsible for finding the particular
+function; it is described below.  Various contexts of the form
+@t{-}@var{context}@t{-} are handled specifically. These are all
+mentioned above as possible arguments to the @t{#compdef} tag.
+
+@noindent
+Before trying to find a function for a specific context, @t{_complete} 
+checks if the parameter `@t{compcontext}' is set. Setting
+`@t{compcontext}' allows the usual completion dispatching to be
+overridden which is useful in places such as a function that uses
+@t{vared} for input. If it is set to an array, the elements are taken
+to be the possible matches which will be completed using the tag
+`@t{values}' and the description `@t{value}'. If it is set to an
+associative array, the keys are used as the possible completions and
+the values (if non-empty) are used as descriptions for the matches.  If
+`@t{compcontext}' is set to a string containing colons, it should be of
+the form `@var{tag}@t{:}@var{descr}@t{:}@var{action}'.  In this case the
+@var{tag} and @var{descr} give the tag and description to use and the
+@var{action} indicates what should be completed in one of the forms
+accepted by the @t{_arguments} utility function described below.
+
+@noindent
+Finally, if `@t{compcontext}' is set to a string without colons, the
+value is taken as the name of the context to use and the function
+defined for that context will be called.  For this purpose, there is a
+special context named @t{-command-line-} that completes whole command
+lines (commands and their arguments).  This is not used by the completion
+system itself but is nonetheless handled when explicitly called.
+
+@findex _correct
+@item @t{_correct}
+Generate corrections, but not completions, for the current word; this is
+similar to @t{_approximate} but will not allow any number of extra
+characters at the cursor as that completer does.  The effect is
+similar to spell-checking.  It is based on @t{_approximate}, but the
+completer field in the context name is @t{correct}.
+
+@noindent
+For example, with:
+
+@noindent
+@example
+zstyle ':completion:::::' completer _complete _correct _approximate
+zstyle ':completion:*:correct:::' max-errors 2 not-numeric
+zstyle ':completion:*:approximate:::' max-errors 3 numeric
+@end example
+
+@noindent
+correction will accept up to two errors.  If a numeric argument is
+given, correction will not be performed, but correcting completion
+will be, and will accept as many errors as given by the numeric
+argument.  Without a numeric argument, first correction and then
+correcting completion will be tried, with the first one accepting two
+errors and the second one accepting three errors.
+
+@noindent
+When @t{_correct} is called as a function, the number of errors to accept
+may be given following the @t{-a} option.  The argument is in the same
+form a values to the @t{accept} style, all in one string.
+
+@noindent
+This completer function is intended to be used without the
+@t{_approximate} completer or, as in the example, just before
+it.  Using it after the @t{_approximate} completer is useless since
+@t{_approximate} will at least generate the corrected strings
+generated by the @t{_correct} completer -- and probably more.
+
+@findex _expand
+@item @t{_expand}
+This completer function does not really perform completion, but instead
+checks if the word on the command line is eligible for expansion and,
+if it is, gives detailed control over how this expansion is done.  For
+this to happen, the completion system needs to be invoked with
+@t{complete-word}, not @t{expand-or-complete} (the default binding for
+@t{TAB}), as otherwise the string will be expanded by the shell's
+internal mechanism before the completion system is started.
+Note also this completer should be called before the @t{_complete} 
+completer function.
+
+@noindent
+The tags used when generating expansions are @t{all-expansions} for the
+string containing all possible expansions, @t{expansions} when adding
+the possible expansions as single matches and @t{original} when adding
+the original string from the line.  The order in which these strings are
+generated, if at all, can be controlled by the @t{group-order} and
+@t{tag-order} styles, as usual.
+
+@noindent
+The format string for @t{all-expansions} and for @t{expansions} may
+contain the sequence `@t{%o}' which will be replaced by the original
+string from the line.
+
+@noindent
+The kind of expansion to be tried is controlled by the @t{substitute},
+@t{glob} and @t{subst-globs-only} styles.
+
+@noindent
+It is also possible to call @t{_expand} as a function, in which case the
+different modes may be selected with options: @t{-s} for
+@t{substitute}, @t{-g} for @t{glob} and @t{-o} for @t{subst-globs-only}.
+
+@findex _expand_alias
+@item @t{_expand_alias}
+If the word the cursor is on is an alias, it is expanded and no other
+completers are called.  The types of aliases which are to be expanded can
+be controlled with the styles @t{regular}, @t{global} and @t{disabled}.
+
+@noindent
+This function is also a bindable command, see
+@ref{Bindable Commands}.
+
+@findex _history
+@item @t{_history}
+Complete words from the shell's command  history.  This completer 
+can be controlled by the @t{remove-all-dups}, and @t{sort} styles as for the
+@t{_history_complete_word} bindable command, see
+@ref{Bindable Commands}
+and
+@ref{Completion System Configuration}.
+
+@findex _ignored
+@item @t{_ignored}
+The @t{ignored-patterns} style can be set to a list of patterns which are
+compared against possible completions; matching ones are removed.
+With this completer those matches can be reinstated, as
+if no @t{ignored-patterns} style were set.  The completer actually
+generates its own list of matches; which completers are invoked
+is determined in the same way as for the @t{_prefix} completer.
+The @t{single-ignored} style is also available as described above.
+
+@findex _list
+@item @t{_list}
+This completer allows the insertion of matches to be delayed until
+completion is attempted a second time without the word on the line
+being changed.  On the first attempt, only the list of matches will be
+shown.  It is affected by the styles @t{condition} and @t{word}, see
+@ref{Completion System Configuration}.
+
+@findex _match
+@item @t{_match}
+This completer is intended to be used after the @t{_complete}
+completer.  It behaves similarly but the string on the command line may
+be a pattern to match against trial completions.  This gives the effect
+of the @t{GLOB_COMPLETE} option.
+
+@noindent
+Normally completion will be performed by taking the pattern from the line,
+inserting a `@t{*}' at the cursor position and comparing the resulting
+pattern with the possible completions generated.  This can be modified
+with the @t{match-original} style described above.
+
+@noindent
+The generated matches will be offered in a menu completion unless the
+@t{insert-unambiguous} style is set to `true'; see the description above
+for other options for this style.
+
+@noindent
+Note that matcher specifications defined globally or used by the
+completion functions (the styles @t{matcher-list} and @t{matcher}) will
+not be used.
+
+@findex _menu
+@item @t{_menu}
+This completer was written as simple example function to show how menu
+completion can be enabled in shell code. However, it has the notable
+effect of disabling menu selection which can be useful with
+@t{_generic} based widgets. It should be used as the first completer in
+the list.  Note that this is independent of the setting of the
+@t{MENU_COMPLETE} option and does not work with the other menu
+completion widgets such as @t{reverse-menu-complete}, or
+@t{accept-and-menu-complete}.
+
+@findex _oldlist
+@item @t{_oldlist}
+This completer controls how the standard completion widgets behave
+when there is an existing list of completions which may have been
+generated by a special completion (i.e. a separately-bound completion
+command).  It allows the ordinary completion keys to continue to use the
+list of completions thus generated, instead of producing a new list of
+ordinary contextual completions.
+It should appear in the list of completers before any of
+the widgets which generate matches.  It uses two styles: @t{old-list} and
+@t{old-menu}, see
+@ref{Completion System Configuration}.
+
+@findex _prefix
+@item @t{_prefix}
+This completer can be used to try completion with the suffix (everything
+after the cursor) ignored.  In other words, the suffix will not be
+considered to be part of the word to complete.  The effect is similar
+to the @t{expand-or-complete-prefix} command.
+
+@noindent
+The @t{completer} style is used to decide which other completers are to
+be called to generate matches.  If this style is unset, the list of
+completers set for the current context is used -- except, of course, the
+@t{_prefix} completer itself.  Furthermore, if this completer appears
+more than once in the list of completers only those completers not
+already tried by the last invocation of @t{_prefix} will be called.
+
+@noindent
+For example, consider this global @t{completer} style:
+
+@noindent
+@example
+zstyle ':completion:*' completer \ 
+    _complete _prefix _correct _prefix:foo
+@end example
+
+@noindent
+Here, the @t{_prefix} completer tries normal completion but ignoring the
+suffix.  If that doesn't generate any matches, and neither does
+the call to the @t{_correct} completer after it, @t{_prefix} will 
+be called a second time and, now only trying correction with the
+suffix ignored.  On the second invocation the completer part of the
+context appears as `@t{foo}'.
+
+@noindent
+To use @t{_prefix} as the last resort and try only normal completion
+when it is invoked:
+
+@noindent
+@example
+zstyle ':completion:*' completer _complete ... _prefix
+zstyle ':completion::prefix:*' completer _complete
+@end example
+
+@noindent
+The @t{add-space} style is also respected.  If it is set to `true' then
+@t{_prefix} will insert a space between the matches generated (if any) 
+and the suffix.
+
+@noindent
+Note that this completer is only useful if the
+@t{COMPLETE_IN_WORD} option is set; otherwise, the cursor will
+be moved to the end of the current word before the completion code is
+called and hence there will be no suffix.
+
+@findex bashcompinit
+@item @t{bashcompinit}
+This function provides compatibility with bash's programmable completion
+system.  When run it will define the functions, @t{compgen} and
+@t{complete} which correspond to the bash builtins with the same names.
+It will then be possible to use completion specifications and functions
+written for bash.
+
+@end table
+
+@noindent
+@node Bindable Commands, Completion Functions, Control Functions, Completion System
+
+@section Bindable Commands
+@noindent
+@cindex completion system, bindable commands
+
+@noindent
+In addition to the context-dependent completions provided, which are
+expected to work in an intuitively obvious way, there are a few widgets
+implementing special behaviour which can be bound separately to keys.  The
+following is a list of these and their default bindings.
+
+@noindent
+@table @asis
+@findex _bash_completions
+@item @t{_bash_completions}
+This function is used by two widgets, @t{_bash_complete-word} and
+@t{_bash_list-choices}.  It exists to provide compatibility with
+completion bindings in bash.  The last character of the binding determines
+what is completed: `@t{!}', command names; `@t{$}', environment variables;
+`@t{@@}', host names; `@t{/}', file names; `@t{~}' user names.  In bash, the
+binding preceded by `@t{\e}' gives completion, and preceded by `@t{^X}'
+lists options.  As some of these bindings clash with standard zsh
+bindings, only `@t{\e~}' and `@t{^X~}' are bound by default.  To add the
+rest, the following should be added to @t{.zshrc} after @t{compinit} has
+been run:
+
+@noindent
+@example
+for key in '!' '$' '@@' '/' '~'; do
+  bindkey "\e$key" _bash_complete-word
+  bindkey "^X$key" _bash_list-choices
+done
+@end example
+
+@noindent
+This includes the bindings for `@t{~}' in case they were already bound to
+something else; the completion code does not override user bindings.
+
+@findex _correct_filename (^XC)
+@item @t{_correct_filename (^XC)}
+Correct the filename path at the cursor position.  Allows up to six errors
+in the name.  Can also be called with an argument to correct
+a filename path, independently of zle; the correction is printed on
+standard output.
+
+@findex _correct_word (^Xc)
+@item @t{_correct_word} (^Xc)
+Performs correction of the current argument using the usual contextual
+completions as possible choices. This stores the string
+`@t{correct-word}' in the @var{function} field of the context name and
+then calls the @t{_correct} completer.
+
+@findex _expand_alias (^Xa)
+@item @t{_expand_alias (^Xa)}
+This function can be used as a completer and as a bindable command.
+It expands the word the cursor is on if it is an alias.  The types of
+alias expanded can be controlled with the styles @t{regular}, @t{global}
+and @t{disabled}.
+
+@noindent
+When used as a bindable command there is one additional feature that
+can be selected by setting the @t{complete} style to `true'.  In this
+case, if the word is not the name of an alias, @t{_expand_alias} tries
+to complete the word to a full alias name without expanding it.  It
+leaves the cursor directly after the completed word so that invoking
+@t{_expand_alias} once more will expand the now-complete alias name.
+
+@findex _expand_word (^Xe)
+@item @t{_expand_word (^Xe)}
+Performs expansion on the current word:  equivalent to the standard
+@t{expand-word} command, but using the @t{_expand} completer.  Before
+calling it, the @var{function} field of the context is set to
+`@t{expand-word}'.
+
+@findex _generic
+@item @t{_generic}
+This function is not defined as a widget and not bound by
+default.  However, it can be used to define a widget and will then
+store the name of the widget in the @var{function} field of the context 
+and call the completion system.  This allows custom completion widgets
+with their own set of style settings to be defined easily.  For example, 
+to define a widget that performs normal completion and starts
+menu selection:
+
+@noindent
+@example
+zle -C foo complete-word _generic
+bindkey '...' foo
+zstyle ':completion:foo:*' menu yes select=1
+@end example
+
+@findex _history_complete_word (\e/)
+@item @t{_history_complete_word} (\e/)
+Complete words from the shell's command history. This uses the
+@t{list}, @t{remove-all-dups}, @t{sort}, and @t{stop} styles.
+
+@findex _most_recent_file (^Xm)
+@item @t{_most_recent_file (^Xm)}
+Complete the name of the most recently modified file matching the pattern
+on the command line (which may be blank).  If given a numeric argument
+@var{N}, complete the @var{N}th most recently modified file.  Note the
+completion, if any, is always unique.
+
+@findex _next_tags (^Xn)
+@item @t{_next_tags} (^Xn)
+This command alters the set of matches used to that for the next tag, or
+set of tags, either as given by the @t{tag-order} style or as set by
+default; these matches would otherwise not be available.
+Successive invocations of the command cycle through all possible sets of
+tags.
+
+@findex _read_comp (^X^R)
+@item @t{_read_comp (^X^R)}
+Prompt the user for a string, and use that to perform completion on the
+current word.  There are two possibilities for the string.  First, it can
+be a set of words beginning `@t{_}', for example `@t{_files -/}', in which
+case the function with any arguments will be called to generate the
+completions.  Unambiguous parts of the function name will be completed
+automatically (normal completion is not available at this point) until a
+space is typed.
+
+@noindent
+Second, any other string will be passed as a set of arguments to
+@t{compadd} and should hence be an expression specifying what should
+be completed.
+
+@noindent
+A very restricted set of editing commands is available when reading the
+string:  `@t{DEL}' and `@t{^H}' delete the last character; `@t{^U}' deletes
+the line, and `@t{^C}' and `@t{^G}' abort the function, while `@t{RET}'
+accepts the completion.  Note the string is used verbatim as a command
+line, so arguments must be quoted in accordance with standard shell rules.
+
+@noindent
+Once a string has been read, the next call to @t{_read_comp} will use the
+existing string instead of reading a new one.  To force a new string to be
+read, call @t{_read_comp} with a numeric argument.
+
+@findex _complete_debug (^X?)
+@item @t{_complete_debug (^X?)}
+This widget performs ordinary completion, but captures in a temporary file
+a trace of the shell commands executed by the completion system.  Each
+completion attempt gets its own file.  A command to view each of these
+files is pushed onto the editor buffer stack.
+
+@findex _complete_help (^Xh)
+@item @t{_complete_help (^Xh)}
+This widget displays information about the context names, 
+the tags, and the completion functions used 
+when completing at the current cursor position. If given a numeric
+argument other than @t{1} (as in `@t{ESC-2 ^Xh}'), then the styles
+used and the contexts for which they are used will be shown, too.
+
+@noindent
+Note that the information about styles may be incomplete; it depends on the
+information available from the completion functions called, which in turn
+is determined by the user's own styles and other settings.
+
+@findex _complete_tag (^Xt)
+@item @t{_complete_tag (^Xt)}
+This widget completes symbol tags created by the @t{etags} or @t{ctags}
+programmes (note there is no connection with the completion system's tags)
+stored in a file @t{TAGS}, in the format used by @t{etags}, or @t{tags}, in the
+format created by @t{ctags}.  It will look back up the path hierarchy for
+the first occurrence of either file; if both exist, the file @t{TAGS} is
+preferred.  You can specify the full path to a @t{TAGS} or @t{tags} file by
+setting the parameter @t{$TAGSFILE} or @t{$tagsfile} respectively.
+The corresponding completion tags used are @t{etags} and @t{vtags}, after
+emacs and vi respectively.
+
+@end table
+
+@noindent
+@node Completion Functions, Completion Directories, Bindable Commands, Completion System
+
+@section Utility Functions
+@noindent
+@cindex completion system, utility functions
+
+@noindent
+Descriptions follow for utility functions that may be
+useful when writing completion functions.  If functions are installed in
+subdirectories, most of these reside in the
+@t{Base} subdirectory.  Like the example 
+functions for commands in the distribution, the utility functions
+generating matches all follow the convention of returning zero if they
+generated completions and non-zero if no matching completions could be 
+added.
+
+@noindent
+Two more features are offered by the @t{_main_complete} function.  The
+arrays @t{compprefuncs} and @t{comppostfuncs} may contain
+names of functions that are to be called immediately before or after
+completion has been tried.  A function will only be called once unless
+it explicitly reinserts itself into the array.
+
+@noindent
+@table @asis
+@findex _all_labels
+@item @t{_all_labels} [ @t{-x} ] [ @t{-12VJ} ] @var{tag} @var{name} @var{descr} [ @var{command} @var{args} ... ]
+This is a convenient interface to the @t{_next_label} function below,
+implementing the loop shown in the @t{_next_label} example.  The
+@var{command} and its arguments are called to generate the matches.  The
+options stored in the parameter @var{name} will automatically be inserted
+into the @var{args} passed to the @var{command}.  Normally, they are put
+directly after the @var{command}, but if one of the @var{args} is a single
+hyphen, they are inserted directly before that.  If the hyphen is the last
+argument, it will be removed from the argument list before the
+@var{command} is called.  This allows @t{_all_labels} to be used in almost all
+cases where the matches can be generated by a single call to the
+@t{compadd} builtin command or by a call to one of the utility functions.
+
+@noindent
+For example:
+
+@noindent
+@example
+local expl
+...
+if _requested foo; then
+  ...
+  _all_labels foo expl '...' compadd ... - $matches
+fi
+@end example
+
+@noindent
+Will complete the strings from the @t{matches} parameter, using
+@t{compadd} with additional options which will take precedence over
+those generated by @t{_all_labels}.
+
+@findex _alternative
+@item @t{_alternative} [ @t{-C} @var{name} ] @var{spec} ...
+This function is useful in simple cases where multiple tags are available.
+Essentially it implements a loop like the one described for the @t{_tags}
+function below.
+
+@noindent
+The tags to use and the action to perform if a tag is requested are
+described using the @var{spec}s which are of the form:
+`@var{tag}@t{:}@var{descr}@t{:}@var{action}'.  The @var{tag}s are offered using
+@t{_tags} and if the tag is requested, the @var{action} is executed with the
+given description @var{descr}.  The @var{action}s are those accepted
+by the @t{_arguments} function (described below), excluding the
+`@t{->}@var{state}' and `@t{=}@var{...}' forms.
+
+@noindent
+For example, the @var{action} may be a simple function call:
+
+@noindent
+@example
+_alternative \ 
+    'users:user:_users' \ 
+    'hosts:host:_hosts'
+@end example
+
+@noindent
+offers usernames and hostnames as possible matches,
+generated by the @t{_users} and @t{_hosts} functions respectively.
+
+@noindent
+Like @t{_arguments}, this functions uses @t{_all_labels} to execute 
+the actions, which will loop over all sets of tags.  Special handling is
+only required if there is an additional valid tag, for example inside a
+function called from @t{_alternative}.
+
+@noindent
+Like @t{_tags} this function supports the @t{-C} option to give a
+different name for the argument context field.
+
+@findex _arguments
+@item @t{_arguments} [ @t{-swWACRS} ] [ @t{-O} @var{name} ] [ @t{-M} @var{matchspec} ] [ @t{:} ] @var{spec} ...
+This function can be used to give a complete specification for
+completion for a command whose arguments follow standard UNIX option and
+argument conventions.  The following forms specify individual sets of
+options and arguments; to avoid ambiguity, these may be separated from the
+options to @t{_arguments} itself by a single colon.
+
+@noindent
+@table @asis
+@item @var{n}@t{:}@var{message}@t{:}@var{action}
+@itemx @var{n}@t{::}@var{message}@t{:}@var{action}
+This describes the @var{n}'th normal argument.  The @var{message} will be 
+printed above the matches generated and the @var{action} indicates what can
+be completed in this position (see below).  If there are two colons
+before the @var{message} the argument is optional.  If the
+@var{message} contains only white space, nothing will be printed above
+the matches unless the action adds an explanation string itself.
+
+@item @t{:}@var{message}@t{:}@var{action}
+@itemx @t{::}@var{message}@t{:}@var{action}
+Similar, but describes the @emph{next} argument, whatever number that
+happens to be.  If all arguments are specified in this form in the
+correct order the numbers are unnecessary.
+
+@item @t{*:}@var{message}@t{:}@var{action}
+@itemx @t{*::}@var{message}@t{:}@var{action}
+@itemx @t{*:::}@var{message}@t{:}@var{action}
+This describes how arguments (usually non-option arguments, those not
+beginning with @t{-} or @t{+}) are to be completed when neither
+of the first two forms was provided.  Any number of arguments can
+be completed in this fashion.
+
+@noindent
+With two colons before the @var{message}, the @t{words} special array and
+the @t{CURRENT} special parameter are modified to refer only to the
+normal arguments when the @var{action} is executed or evaluated.  With
+three colons before the @var{message} they are modified to refer only to
+the normal arguments covered by this description.
+
+@item @var{optspec}
+@itemx @var{optspec}:@var{...}
+This describes an option.  The colon indicates handling for one or more
+arguments to the option; if it is not present, the option is assumed to
+take no arguments.
+
+@noindent
+By default, options are multi-character name, one `@t{-}@var{word}' per
+option.  With @t{-s}, options may be single characters, with more than
+one option per word, although words starting with two hyphens, such as
+`@t{-}@t{-prefix}', are still considered complete option names.  This is
+suitable for standard GNU options.
+
+@noindent
+The combination of @t{-s} with @t{-w} allows single-letter options to be
+combined in a single word even if one or more of the options take
+arguments.  For example, if @t{-a} takes an argument, with no
+@t{-s} `@t{-ab}' is considered as a single (unhandled) option; with
+@t{-s} @t{-ab} is an option with the argument `@t{b}'; with both @t{-s}
+and @t{-w}, @t{-ab} may be the option @t{-a} and the option(-b) with
+arguments still to come.
+
+@noindent
+The option @t{-W} takes this a stage further:  it is possible to
+complete single-letter options even after an argument that occurs in the
+same word.  However, it depends on the action performed whether options
+will really be completed at this point.  For more control, use a
+utility function like @t{_guard} as part of the action.
+
+@noindent
+The following forms are available for the initial @var{optspec}, whether
+or not the option has arguments.
+
+@noindent
+@table @asis
+@item @t{*}@var{optspec}
+Here @var{optspec} is one of the remaining forms below.  This indicates
+the following @var{optspec} may be repeated.  Otherwise if the
+corresponding option is already present on the command line to the left
+of the cursor it will not be offered again.
+
+@item @t{-}@var{optname}
+@itemx @t{+}@var{optname}
+In the simplest form the @var{optspec} is just the option name beginning
+with a minus or a plus sign, such as `@t{-foo}'.  The first argument for
+the option (if any) must follow as a @emph{separate} word directly after the
+option.
+
+@noindent
+Either of `@t{-+}@var{optname}' and `@t{+-}@var{optname}' can be used to
+specify that @t{-}@var{optname} and @t{+}@var{optname} are both valid.
+
+@noindent
+In all the remaining forms, the leading `@t{-}' may be replaced by or
+paired with `@t{+}' in this way.
+
+@item @t{-}@var{optname}@t{-}
+The first argument of the option must come directly after the option name
+@emph{in the same word}.  For example, `@t{-foo-:}@var{...}' specifies that
+the completed option and argument will look like `@t{-foo}@var{arg}'.
+
+@item @t{-}@var{optname}@t{+}
+The first argument may appear immediately after @var{optname} in the same
+word, or may appear as a separate word after the option.  For example,
+`@t{-foo+:}@var{...}' specifies that the completed option and argument
+will look like either `@t{-foo}@var{arg}' or `@t{-foo} @var{arg}'.
+
+@item @t{-}@var{optname}@t{=}
+The argument may appear as the next word, or in same word as the option
+name provided that it is separated from it by an equals sign, for
+example `@t{-foo=}@var{arg}' or `@t{-foo} @var{arg}'.
+
+@item @t{-}@var{optname}@t{=-}
+The argument to the option must appear after an equals sign in the same
+word, and may not be given in the next argument.
+
+@item @var{optspec}@t{[}@var{explanation}@t{]}
+An explanation string may be appended to any of the preceding forms of
+@var{optspec} by enclosing it in brackets, as in `@t{-q[query operation]}'.
+
+@noindent
+The @t{verbose} style is used to decide whether the explanation strings
+are displayed with the option in a completion listing.
+
+@noindent
+If no bracketed explanation string is given but the @t{auto-description}
+style is set and only one argument is described for this @var{optspec}, the
+value of the style is displayed, with any appearance of the sequence
+`@t{%d}' in it replaced by the @var{message} of the first @var{optarg}
+that follows the @var{optspec}; see below.
+
+@end table
+
+@noindent
+It is possible for options with a literal `+' or `@t{=}' to
+appear, but that character must be quoted, for example `@t{-\+}'.
+
+@noindent
+Each @var{optarg} following an @var{optspec} must take one of the
+following forms:
+
+@noindent
+@table @asis
+@item @t{:}@var{message}@t{:}@var{action}
+@itemx @t{::}@var{message}@t{:}@var{action}
+An argument to the option; @var{message} and @var{action} are treated as
+for ordinary arguments.  In the first form, the argument is mandatory,
+and in the second form it is optional.
+
+@noindent
+This group may be repeated for options which take multiple arguments.
+In other words,
+@t{:}@var{message1}@t{:}@var{action1}@t{:}@var{message2}@t{:}@var{action2}
+specifies that the option takes two arguments.
+
+@item @t{:*}@var{pattern}@t{:}@var{message}@t{:}@var{action}
+@itemx @t{:*}@var{pattern}@t{::}@var{message}@t{:}@var{action}
+@itemx @t{:*}@var{pattern}@t{:::}@var{message}@t{:}@var{action}
+This describes multiple arguments.  Only the last @var{optarg} for
+an option taking multiple arguments may be
+given in this form.  If the @var{pattern} is empty (i.e., @t{:*:}), all
+the remaining words on the line are to be completed as described by the
+@var{action}; otherwise, all the words up to a word matching the
+@var{pattern} are to be completed using the @var{action}.
+
+@noindent
+Multiple colons are treated as for the `@t{*:}@var{...}' forms for
+ordinary arguments:  when the @var{message} is preceded by two colons,
+the @t{words} special array and the @t{CURRENT} special parameter are
+modified during the execution or evaluation of the @var{action} to refer
+only to the words after the option.  When preceded by three colons, they
+are modified to refer only to the words covered by this description.
+
+@end table
+
+@end table
+
+@noindent
+Any literal colon in an @var{optname}, @var{message}, or @var{action}
+must be preceded by a backslash, `@t{\:}'.
+
+@noindent
+Each of the forms above may be preceded by a list in parentheses
+of option names and argument numbers.  If the given option is on
+the command line, the options and arguments indicated in parentheses
+will not be offered.  For example, 
+`@t{(-two -three 1)-one:...}' completes the option `@t{-one}'; if this
+appears on the command line, the options @t{-two} and @t{-three} and the
+first ordinary argument will not be completed after it.
+`@t{(-foo):}@var{...}' specifies an ordinary argument completion;
+@t{-foo} will not be completed if that argument is already present.
+
+@noindent
+Other items may appear in the list of excluded options to indicate
+various other items that should not be applied when the current
+specification is matched: a single star (@t{*}) for the rest arguments
+(i.e. a specification of the form `@t{*:...}'); a colon (@t{:})
+for all normal (non-option-) arguments; and a hyphen (@t{-}) for all
+options.  For example, if `@t{(*)}' appears before an option and the
+option appears on the command line, the list of remaining arguments
+(those shown in the above table beginning with `@t{*:}') will not be
+completed.
+
+@noindent
+To aid in reuse of specifications, it is possible to precede any of the
+forms above with `@t{!}'; then the form will no longer be completed,
+although if the option or argument appears on the command line they will
+be skipped as normal.  The main use for this is when the arguments are
+given by an array, and @t{_arguments} is called repeatedly for more
+specific contexts: on the first call `@t{_arguments $global_options}' is
+used, and on subsequent calls `@t{_arguments !$^global_options}'.
+
+@noindent
+In each of the forms above the @var{action} determines how
+completions should be generated.  Except for the `@t{->}@var{string}'
+form below, the @var{action} will be executed by calling the
+@t{_all_labels} function to process all tag labels.  No special handling
+of tags is needed unless a function call introduces a new one.
+
+@noindent
+The forms for @var{action} are as follows.
+
+@noindent
+@table @asis
+@item @t{ } (single unquoted space)
+This is useful where an argument is required but it is not possible or
+desirable to generate matches for it.  The
+@var{message} will be displayed but no completions listed.  Note
+that even in this case the colon at the end of the @var{message} is
+needed; it may only be omitted when neither a @var{message}
+nor an @var{action} is given.
+
+@item @t{(}@var{item1} @var{item2} @var{...}@t{)}
+One of a list of possible matches, for example:
+
+@noindent
+@example
+@t{:foo:(foo bar baz}@t{)}
+@end example
+
+@item @t{((@var{item1}\:@var{desc1} @var{...}))}
+Similar to the above, but with descriptions for each possible match.
+Note the backslash before the colon.  For example,
+
+@noindent
+@example
+@t{:foo:((a\:bar b\:baz}@t{))}
+@end example
+
+@noindent
+The matches will be listed together with their descriptions if the
+@t{description} style is set with the @t{values} tag in the context.
+
+@item @t{->}@var{string}
+@vindex context, use of
+@vindex line, use of
+@vindex opt_args, use of
+In this form, @t{_arguments} processes the arguments and options and then
+returns control to the calling function with parameters set to indicate the
+state of processing; the calling function then makes its own arrangements
+for generating completions.  For example, functions that implement a state
+machine can use this type of action.
+
+@noindent
+Where @t{_arguments} encounters a `@t{->}@var{string}', it will strip
+all leading and trailing whitespace from @var{string} and set the array
+@t{state} to the set of all @var{strings}s for which an action is to be
+performed.
+
+@noindent
+By default and in common with all other well behaved completion
+functions, _arguments returns zero if it was able to add matches and
+non-zero otherwise. However, if the @t{-R} option is given,
+@t{_arguments} will instead return a status of 300 to indicate that
+@t{$state} is to be handled.
+
+@noindent
+In addition to @t{$state}, @t{_arguments} also sets the global
+parameters `@t{context}', `@t{line}' and `@t{opt_args}' as described
+below, and does not reset any changes made to the special parameters
+such as @t{PREFIX} and @t{words}.  This gives the calling function the
+choice of resetting these parameters or propagating changes in them.
+
+@noindent
+A function calling @t{_arguments} with at least
+one action containing a `@t{->}@var{string}' therefore must declare
+appropriate local parameters:
+
+@noindent
+@example
+local context state line
+typeset -A opt_args
+@end example
+
+@noindent
+to avoid @t{_arguments} from altering the global environment.
+
+@item @t{@{}@var{eval-string}@t{@}}
+@vindex expl, use of
+A string in braces is evaluated as shell code to generate matches.  If the
+@var{eval-string} itself does not begin with an opening parenthesis or
+brace it is split into separate words before execution.
+
+@item @t{= }@var{action}
+If the @var{action} starts with `@t{= }' (an equals sign followed by a
+space), @t{_arguments} will insert the contents of the @var{argument}
+field of the current context as the new first element in the @t{words} 
+special array and increment the value of the @t{CURRENT} special
+parameter.  This has the effect of inserting a dummy word onto the
+completion command line while not changing the point at which completion is
+taking place.
+
+@noindent
+This is most useful with one of the specifiers that restrict the words on
+the command line on which the @var{action} is to operate (the two- and
+three-colon forms above).  One particular use is when an @var{action} itself
+causes @t{_arguments} on a restricted range; it is necessary to use this
+trick to insert an appropriate command name into the range for the second
+call to @t{_arguments} to be able to parse the line.
+
+@item  @var{word...}
+@itemx @var{word...}
+This covers all forms other than those above.  If the @var{action}
+starts with a space, the remaining list of words will be invoked unchanged.
+
+@noindent
+Otherwise it will be invoked with some extra strings placed after the
+first word; these are to be passed down as options to the @t{compadd}
+builtin.  They ensure that the state specified by @t{_arguments}, in
+particular the descriptions of options and arguments, is correctly passed
+to the completion command.  These additional arguments
+are taken from the array parameter `@t{expl}'; this will be set up
+before executing the @var{action} and hence may be referred to inside it,
+typically in an expansion of the form `@t{$expl[@@]}' which preserves empty
+elements of the array.
+
+@end table
+
+@noindent
+During the performance of the action the array `@t{line}'
+will be set to the command name and normal arguments from the command
+line, i.e. the words from the command line excluding all options
+and their arguments.  Options are stored in the associative array
+`@t{opt_args}' with option names as keys and their arguments as
+the values.  For options that have more than one argument these are
+given as one string, separated by colons.  All colons in the original
+arguments are preceded with backslashes.
+
+@noindent
+The parameter `@t{context}' is set when returning to the calling function
+to perform an action of the form `@t{->}@var{string}'.  It is set to an
+array of elements corresponding to the elements of @t{$state}.  Each
+element is a suitable name for the argument field of the context: either a
+string of the form `@t{option}@var{-opt}@t{-}@var{n}' for the @var{n}'th
+argument of the option @var{-opt}, or a string of the form
+`@t{argument-}@var{n}' for the @var{n}'th argument.  For `rest' arguments,
+that is those in the list at the end not handled by position, @var{n} is the
+string `@t{rest}'.  For example, when completing the argument of the @t{-o}
+option, the name is `@t{option-o-1}', while for the second normal
+(non-option-) argument it is `@t{argument-2}'.
+
+@noindent
+Furthermore, during the evaluation of the @var{action} the context name in
+the @t{curcontext} parameter is altered to append the same string that is
+stored in the @t{context} parameter.
+
+@noindent
+It is possible to specify multiple sets of options and
+arguments with the sets separated by single hyphens.  The specifications
+before the first hyphen (if any) are shared by all the remaining sets.
+The first word in every other set provides a name for the
+set which may appear in exclusion lists in specifications,
+either alone or before one of the possible values described above.
+In the second case a `@t{-}' should appear between this name and the
+remainder.
+
+@noindent
+For example:
+
+@noindent
+@example
+_arguments \ 
+    -a \ 
+  - set1 \ 
+    -c \ 
+  - set2 \ 
+    -d \ 
+    ':arg:(x2 y2)'
+@end example
+
+@noindent
+This defines two sets.  When the command line contains the option
+`@t{-c}', the `@t{-d}' option and the argument will not be considered
+possible completions.  When it contains `@t{-d}' or an argument, the
+option `@t{-c}' will not be considered.  However, after `@t{-a}'
+both sets will still be considered valid.
+
+@noindent
+If the name given for one of the mutually exclusive sets is of the form
+`@t{(}@var{name}@t{)}' then only one value from each set will ever
+be completed; more formally, all specifications are mutually
+exclusive to all other specifications in the same set.  This is
+useful for defining multiple sets of options which are mutually
+exclusive and in which the options are aliases for each other.  For
+example:
+
+@noindent
+@example
+_arguments \ 
+    -a -b \ 
+  - '(compress)' \ 
+    @{-c,--compress@}'[compress]' \ 
+  - '(uncompress)' \ 
+    @{-d,--decompress@}'[decompress]'
+@end example
+
+@noindent
+As the completion code has to parse the command line separately for each
+set this form of argument is slow and should only be used when necessary.
+A useful alternative is often an option specification with rest-arguments
+(as in `@t{-foo:*:...}'); here the option @t{-foo} swallows up all
+remaining arguments as described by the @var{optarg} definitions.
+
+@noindent
+The options @t{-S} and @t{-A} are available to simplify the specifications
+for commands with standard option parsing.  With @t{-S}, no option will be
+completed after a `@t{-}@t{-}' appearing on its own on the line; this
+argument will otherwise be ignored; hence in the line
+
+@noindent
+@example
+foobar -a -- -b
+@end example
+
+@noindent
+the `@t{-a}' is considered an option but the `@t{-b}' is considered an
+argument, while the `@t{-}@t{-}' is considered to be neither.
+
+@noindent
+With @t{-A}, no options will be completed after the first non-option
+argument on the line.  The @t{-A} must be followed by a pattern matching
+all strings which are not to be taken as arguments.  For example, to make
+@t{_arguments} stop completing options after the first normal argument, but
+ignoring all strings starting with a hyphen even if they are not described
+by one of the @var{optspec}s, the form is `@t{-A "-*"}'.
+
+@noindent
+The option `@t{-O} @var{name}' specifies the name of an array whose elements
+will be passed as arguments to functions called to execute @var{actions}.
+For example, this can be used to pass the same set of options for the
+@t{compadd} builtin to all @var{action}s.
+
+@noindent
+The option `@t{-M} @var{spec}' sets a match specification to use to
+completion option names and values.  It must appear before the first
+argument specification.  The default is `@t{r:|[_-]=* r:|=*}': this allows
+partial word completion after `@t{_}' and `@t{-}', for example `-f-b'
+can be completed to `@t{-foo-bar}'.
+
+@noindent
+The option @t{-C} tells @t{_arguments} to modify
+the @t{curcontext} parameter for an action of the form
+`@t{->}@var{state}'.  This is the standard parameter used to keep track of
+the current context.  Here it (and not the @t{context} array) should be
+made local to the calling function
+to avoid passing back the modified value and should be initialised to the
+current value at the start of the function:
+
+@noindent
+@example
+local curcontext="$curcontext"
+@end example
+
+@noindent
+This is useful where it is not possible for multiple states to be valid
+together.
+
+@noindent
+The option `@t{--}' allows @t{_arguments} to work out the names of long
+options that support the `@t{-}@t{-help}' option which is standard in many
+GNU commands.  The command word is called with the argument
+`@t{-}@t{-help}' and the output examined for option names.  Clearly, it can
+be dangerous to pass this to commands which may not support this option as
+the behaviour of the command is unspecified.
+
+@noindent
+In addition to options, `@t{_arguments -}@t{-}' will try to deduce the
+types of arguments available for options when the form
+`@t{-}@t{-}@var{opt}=@var{val}' is valid.  It is also possible to provide
+hints by examining the help text of the command and adding specifiers of
+the form `@var{pattern}@t{:}@var{message}@t{:}@var{action}'; note that normal
+@t{_arguments} specifiers are not used.  The @var{pattern} is matched
+against the help text for an option, and if it matches the @var{message} and
+@var{action} are used as for other argument specifiers.  For example:
+
+@noindent
+@example
+_arguments -- '*\*:toggle:(yes no)' \ 
+              '*=FILE*:file:_files' \ 
+              '*=DIR*:directory:_files -/' \ 
+              '*=PATH*:directory:_files -/'
+@end example
+
+@noindent
+Here, `@t{yes}' and `@t{no}' will be completed as the argument of
+options whose description ends in a star; file names will be completed for
+options that contain the substring `@t{=FILE}' in the description; and
+directories will be completed for options whose description contains
+`@t{=DIR}' or `@t{=PATH}'.  The last three are in fact the default and so
+need not be given explicitly, although it is possible to override the use
+of these patterns.  A typical help text which uses this feature is:
+
+@noindent
+@example
+  -C, --directory=DIR          change to directory DIR
+@end example
+
+@noindent
+so that the above specifications will cause directories to be completed
+after `@t{--directory}', though not after `@t{-C}'.
+
+@noindent
+Note also that @t{_arguments} tries to find out automatically if the
+argument for an option is optional.  This can be specified explicitly by
+doubling the colon before the @var{message}.
+
+@noindent
+If the @var{pattern} ends in `@t{(-)}', this will removed from the
+pattern and the @var{action} will be used only directly after the
+`@t{=}', not in the next word.  This is the behaviour of a normal
+specification defined with the form `@t{=-}'.
+
+@noindent
+The `@t{_arguments -}@t{-}' can be followed by the option `@t{-i}
+@var{patterns}' to give patterns for options which are not to be
+completed.  The patterns can be given as the name of an array parameter
+or as a literal list in parentheses.  For example,
+
+@noindent
+@example
+_arguments -- -i \ 
+    "(-@t{-(en|dis)able-FEATURE*)"}
+@end example
+
+@noindent
+will cause completion to ignore the options
+`@t{-}@t{-enable-FEATURE}' and `@t{-}@t{-disable-FEATURE}' (this example is
+useful with GNU @t{configure}).
+
+@noindent
+The `@t{_arguments -}@t{-}' form can also be followed by the option `@t{-s}
+@var{pair}' to describe option aliases.  Each @var{pair} consists of a
+pattern and a replacement.  For example, some @t{configure}-scripts
+describe options only as `@t{-}@t{-enable-foo}', but also accept
+`@t{-}@t{-disable-foo}'.  To allow completion of the second form:
+
+@noindent
+@example
+_arguments -- -s "(#-@t{-enable- -}@t{-disable-)"}
+@end example
+
+@noindent
+Here is a more general example of the use of @t{_arguments}:
+
+@noindent
+@example
+_arguments '-l+:left border:' \ 
+           '-format:paper size:(letter A4)' \ 
+           '*-copy:output file:_files::resolution:(300 600)' \ 
+           ':postscript file:_files -g \*.\(ps\|eps\)' \ 
+           '*:page number:'
+@end example
+
+@noindent
+This describes three options: `@t{-l}', `@t{-format}', and
+`@t{-copy}'.  The first takes one argument described as `@var{left
+border}' for which no completion will be offered because of the empty
+action.  Its argument may come directly after the `@t{-l}' or it may be 
+given as the next word on the line.
+
+@noindent
+The `@t{-format}' option takes one
+argument in the next word, described as `@var{paper size}' for which
+only the strings `@t{letter}' and `@t{A4}' will be completed.
+
+@noindent
+The `@t{-copy}' option may appear more than once on the command line and
+takes two arguments.  The first is mandatory and will be completed as a
+filename.  The second is optional (because of the second colon before
+the description `@var{resolution}') and will be completed from the strings
+`@t{300}' and `@t{600}'.
+
+@noindent
+The last two descriptions say what should be completed as
+arguments.  The first describes the first argument as a
+`@var{postscript file}' and makes files ending in `@t{ps}' or `@t{eps}' 
+be completed.  The last description gives all other arguments the
+description `@var{page numbers}' but does not offer completions.
+
+@findex _cache_invalid
+@item @t{_cache_invalid} @var{cache_identifier}
+This function returns status zero if the completions cache corresponding to
+the given cache identifier needs rebuilding.  It determines this by
+looking up the @t{cache-policy} style for the current context.
+This should provide a function name which is run with the full path to the
+relevant cache file as the only argument.
+
+@noindent
+Example:
+
+@noindent
+@example
+_example_caching_policy () @{
+    # rebuild if cache is more than a week old
+    oldp=( "$1"(Nmw+1) )
+    (( $#oldp ))
+@}
+@end example
+
+@findex _call_function
+@item @t{_call_function} @var{return} @var{name} [ @var{args} ... ]
+If a function @var{name} exists, it is called with the arguments
+@var{args}.  The @var{return} argument gives the name of a parameter in which
+the return status from the function @var{name}; if @var{return} is empty or a
+single hyphen it is ignored.
+
+@noindent
+The return value of @t{_call_function} itself is zero if the function
+@var{name} exists and was called and non-zero otherwise.
+
+@findex _call_program
+@item @t{_call_program} @var{tag} @var{string} ...
+This function provides a mechanism for the user to override the use of an
+external command.  It looks up the @t{command} style with the supplied
+@var{tag}.  If the style is set, its value is used as the command to
+execute.  The @var{string}s from the c