zsh/README

-----------------
THE Z SHELL (ZSH)
-----------------

Version
-------

This is zsh version 4.0.  This is a stable release.

Installing Zsh
--------------

The instructions for compiling zsh are in the file INSTALL.  You should
also check the file MACHINES in the subdirectory Etc to see if there
are any special instructions for your particular architecture.

Features
--------

Zsh is a shell with lots of features.  For a list of some of these, see the
file Etc/FEATURES, and for the latest changes see Etc/NEWS.  For more
details, see the documentation.

Possible incompatibilities
---------------------------

Some particular differences you may notice between version 3.0 and 4.0
(mostly based on 3.0.8; there are other differences from earlier versions):

  o  The options ALWAYS_LAST_PROMPT (return to the line you were
     editing after displaying completion lists) and LIST_AMBIGUOUS
     (don't do AUTO_LIST if there was an unambiguous prefix that could be
     inserted, i.e. only list if it is ambiguous what to insert next) are
     now set by default.  This is in response to complaints that too many
     zsh features are never noticed by many users.  To turn them off,
     just put `unsetopt alwayslastprompt listambiguous' in your
     .zshrc file.
  o  The editor commands history-search-{forward,backward} are implemented
     slightly differently, as are {up,down}-line-or-search.  You may
     well not notice this, however.
  o  Cursor keys are now usually bound in both vi command and insert
     mode.  In the latter case, this may result in a slight delay after
     hitting ESCAPE to exit insert mode.  Purists who object to this can
     unbind the appropriate key sequences (see zshzle(1)).  Most beginning
     users of zsh apparently find the current behaviour preferable.
  o  History file format is incompatible with versions older than 3.0.6,
     but this should only affect people who try to share history files
     between the two versions -- 4.0 can read the old format, 3.0.6 and
     later can read the new format.  Just beware of INC_APPEND_HISTORY,
     which could conceivably mix the two.
  o  Default compctl completions have been removed for some builtin
     commands.  Either use the new compinit-derived system, use the
     improved compctls from Misc/compctl-examples, or restore these
     equivalents yourself:
	 compctl -b bindkey
	 compctl -v export typeset vared
	 compctl -o setopt unsetopt
         compctl -c which

Documentation
-------------

There are a number of documents about zsh in this distribution:

Doc/Zsh/*.yo	The master source for the zsh documentation is written in
		yodl.  Yodl is a document language written by Karel Kubat.
		It is not required by zsh but but it is a nice program so
		you might want to get it anyway, especially if you are a
		zsh developer.  It can be downloaded from
		ftp://ftp.lilypond.org/pub/yodl/

Doc/zsh*.1	Man pages in nroff format.  These will be installed
		by "make install.man" or "make install".  By default,
		these will be installed in /usr/local/man/man1, although
		you can change this with the --mandir option to configure
		or editing the user configuration section of the top level
		Makefile.

Doc/zsh.texi	Everything the man pages have, but in texinfo format.  These
		will be installed by "make install.info" or "make install".
		By default, these will be installed in /usr/local/info,
		although you can change this with the --infodir option to
		configure or editing the user configuration section of the
		top level Makefile.  Version 4.0 or above of the
		Texinfo tools are recommended for processing this file.

Also include in the distribution are:

Doc/intro.ms	An introduction to zsh in troff format using the ms
		macros.  This document explains many of the features
		that make zsh more equal than other shells.
		Unfortunately this is based on zsh-2.5 so some examples
		may not work without changes but it is still a good
		introduction.

For more information, see the website, as described in the META-FAQ.

If you do not have the necessary tools to process these documents,
PostScript, ASCII, Info and DVI versions are available in the separate
file zsh-doc.tar.gz at the archive sites listed in the META-FAQ.

The distribution also contains a Perl script in Utils/helpfiles which
can be used to extract the descriptions of builtin commands from the
zshbuiltins manual page.  See the comments at the beginning of the
script about its usage.  The files created by this script can be used
by example function run-help located in the subdirectory Functions/Misc to
show information about zsh builtins and run `man' on external commands.
For this the shell variable HELPDIR should point to a directory containing
the files generated by the helpfiles script.  run-help should be
unaliased before loading the run-help function.  After that this function
will be executed by the run-help ZLE function which is by default bound
to ESC-h in emacs mode.

Examples
--------

Examples of zsh startup files are located in the subdirectory
StartupFiles.  Examples of zsh functions and scripts are located in
the subdirectory Functions.  Examples of completion control commands
(compctl) are located in the file Misc/compctl-examples.

Zsh FTP Sites, Web Pages, and Mailing Lists
-------------------------------------------

The current list of zsh FTP sites, web pages, and mailing lists can be
found in the META-FAQ.  A copy is included in this distribution and is
available separately at any of the zsh FTP sites.

Common Problems and Frequently Asked Questions
----------------------------------------------

Zsh has a list of Frequently Asked Questions (FAQ) maintained by Peter
Stephenson <pws@zsh.org>.  It covers many common problems encountered
when building, installing, and using zsh.  A copy is included in this
distribution in Etc/FAQ and is available separately at any of the zsh
ftp sites.

Zsh Maintenance and Bug Reports
-------------------------------

Zsh is currently maintained by the members of the zsh-workers mailing list
and coordinated by Peter Stephenson <coordinator@zsh.org>.  Please send
any feedback and bugs reports to <zsh-workers@sunsite.dk>.

Reports are most helpful if you can reproduce the bug starting zsh with
the -f option.  This skips the execution of local startup files except
/etc/zshenv.  If a bug occurs only when some options set try to locate
the option which triggers the bug.

There is a script "reporter" in the subdirectory Util which will print out
your current shell environment/setup.  If you cannot reproduce the bug
with "zsh -f", use this script and include the output from sourcing this
file.  This way, the problem you are reporting can be recreated.

The known bugs in zsh are listed in the file Etc/BUGS.  Check this as
well as the Frequently Asked Questions (FAQ) list before sending a bug
report.  Note that zsh has some features which are not compatible with
sh but these are not bugs.  Most of these incompatibilities go away
when zsh is invoked as sh or ksh (e.g. using a symbolic link).

If you send a bug report to the list and are not a subscriber, please
mention this in your message if you want a response.

If you would like to contribute to the development and maintenance of zsh,
then you should join the zsh-workers mailing list (check the META-FAQ
for info on this).  You should also read the "zsh-development-guide"
located in the subdirectory Util.

Contributors
------------

The people who have contributed to this software project are listed
in Etc/CONTRIBUTORS.