Merge of unposted: correct opening remarks.

INSTALL

@@ -2,11 +2,13 @@
                         INSTALLING ZSH
                         ++++++++++++++
 
-This file is divided into two parts:  making and installing the shell, and
+This file is divided into two parts:  making and installing the shell, a
+note on the script run to set up the environment for new users, and
 a description of various additional configuration options.  You should
-have a look at the items in the second part before following the
+have a look at the items in the second and third parts before following the
 instructions in the first.
 
+
 =====================
 MAKING AND INSTALLING
 =====================
@@ -14,7 +16,7 @@ MAKING AND INSTALLING
 Check MACHINES File
 -------------------
 
-Check the file MACHINES in the subdirectory Etc to see the architectures
+Check the file MACHINES in the top directory to see the architectures
 that zsh is known to compile on, as well as any special instructions
 for your particular architecture.  Most architectures will not require any
 special instructions.
@@ -39,14 +41,15 @@ Configure accepts several options (explained below).  To display
 currently available options, do the command:
     ./configure --help
 
-Most of the interesting configuration options can be added after running
+Many of the interesting configuration options can be added after running
 configure by editing the user configuration section of config.h and the
-top level Makefile.
+top level Makefile.  However, see the end of this file for a list of
+features configurable on the command line.
 
 Dynamic loading
 ---------------
 
-Zsh-3.1 has support for dynamically loadable modules.  This is now enabled
+Zsh has support for dynamically loadable modules.  This is now enabled
 by default; to disable it, run configure with the --disable-dynamic option.
 Note that dynamic loading does not work on all systems.  On these systems
 this option will have no effect.  When dynamic loading is enabled, major
@@ -66,50 +69,48 @@ The zsh distribution contains several modules, in the Src/Builtins,
 Src/Modules and Src/Zle directories.  If you have any additional zsh
 modules that you wish to compile for this version of zsh, create another
 subdirectory of the Src directory and put them there.  You can create
-as many extra subdirectory hierarchies as you need.  The subdirectories
+as many extra subdirectories as you need, but currently configure will only
-must be actual directories; symbolic links will not work.
+search in immediate subdirectories of Src.  The subdirectories must be
+actual directories; symbolic links will not work.  You will then need to
+rerun configure; the easiest way is to run `config.status --recheck' from
+the top-level build directory which retains the existing configuration as
+much as possible.
 
-If you wish to add or remove modules or module directories after you
+The key to the module system is the file config.modules, created in the
-have already run make, then after adding or removing the modules run:
+configuration process.  In the normal case that dynamic loading is
-    make prep
+available, all modules relevant to your configuration will be compiled and
+installed as separate files, so unless you want the modules to be loaded by
+default you don't need to do anything.  For a non-dynamic zsh, the default
+is to compile the complete, compctl, zle, computil, complist, sched,
+parameter, zleparameter and rlimits modules into the shell, and you will
+need to edit config.modules to make any other modules available.
 
-You can also instruct the configuration process that a certain module
+If you wish to change the configuration, here is how config.modules works.
-should neither be compiled nor installed without modifying any files.  To
+Each module has a line in the file.  Be careful to retain the (strict)
-do this, give the argument `--enable-omit-modules=mod1,mod2,...' to
+format for lines in the file:
-configure.  The module arguments are the full names of the modules,
+link - `dynamic', if the module is to be dynamically linked -- meaningless
-probably including the prefix `zsh/'.  For example,
+           if this is not available on your system.
-`configure --enable-omit-modules=zsh/zpty,zsh/example' says that the
+       `static' if the module is to be linked directly into the executable.
-modules zsh/zpty and zsh/example are not to be compiled nor installed.
+       `no' if the module is not to be linked at all.  In this case it will
-Note that it is up to you to make sure the modules in question are not going
+           not even be compiled.
-to be compiled into the main zsh binary, as described in the next section.
+load - `yes' if the module is to be visible to the user.  This will make
-It is unlikely you would want to omit any of the modules liable to be
+           builtins, parameters etc. visible to the user without any need
-compiled in by default.
+           to use the zmodload builtin.
-
+       `no' if an explicit zmodload command is to be required to load the
-Controlling what is compiled into the main zsh binary
+           utilities in the module.  Note that this applies both to
------------------------------------------------------
+	   statically and dynamically linked modules.
-
+auto - `yes' if the entry is to be regenerated whenever configure is run.
-By default the complete, compctl, zle, computil, complist, sched, parameter,
+       `no' if you wish to retain your hand-edited version.
-zleparameter and rlimits modules are compiled into non-dynamic zsh and no
+Do not edit the entry for the pseudo-module zsh/main (apart from the
-modules are compiled into the main binary if dynamic loading is available.
+`functions=' part) as this is the main shell.  After you have edited this
-This can be overridden by creating the file mymods.conf in the compilation
+file, run `make prep' in the Src subdirectory.
-directory (Src, unless you have told configure to use another directory)
-with the list of modules which are to be compiled into the main binary, one
-module name per line with no punctuation and no suffix.  See the zshmodules
-manual page for the list of available modules.
-
-Note that mymods.conf replaces the standard list of linked-in modules from
-Src/xmods.conf.  If you wish to add to the standard list, copy the lines
-that begin with "L " from xmods.conf into mymods.conf and remove the "L "
-from each such line in mymods.conf.  Then add the names of other modules
-that you want to link.  Module names typically must begin with "zsh/";
-only modules appearing in Src/Aliases/*.mdd may omit the "zsh/" prefix.
 
 Note that the modules depending on zle or complete (e.g.: complist and
 deltochar) cannot be loaded dynamically on systems which do not allow symbols
 in one dynamically loaded library to be visible from another; this is true,
 for example, of version 4 of SunOS.  The most convenient workaround is to
-compile zle and complete into the base executable by including them in
+compile zle and complete into the base executable by setting their `link'
-mymods.conf as described above.
+entries in config.modules to `static' as described above.
 
 Compiler Options or Using a Different Compiler
 ----------------------------------------------
@@ -120,12 +121,21 @@ the "configure" script does not know about, by either editing the user
 configuration section of the top level Makefile (after running configure)
 or giving "configure" initial values for these variables by setting them
 in the environment.  Using a Bourne-compatible shell (such as sh,ksh,zsh),
-
 you can do that on the command line like this:
+    CC=c89 ./configure --enable-cflags=-O2 --enable-libs=-lposix
+This is almost equivalent to
     CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
+but has the advantage that the CFLAGS and LIBS variables are remembered if
+the configuration is recreated by means of `config.status --recheck' (this
+happens automatically if certain configuration files change).  You can
+set the make variables CFLAGS, CPPFLAGS, LDFLAGS and LIBS in this way,
+however CC must appear as shown.  If you are configuring from a csh-derived
+shell, you may need to use the "env" program:
+    env CC=c89 ./configure --enable-cflags=-O2 --enable-libs=-lposix.
 
-Or on systems that have the "env" program, you can do it like this:
+You can override the variables directly when running `make':
-    env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
+    make CFLAGS=-g
+However, these will not be passed down via `config.status --recheck'.
 
 Check Generated Files
 ---------------------
@@ -139,42 +149,55 @@ the corresponding default shell parameters.  Since these shell parameters
 are only for informational purposes, you can change them to whatever
 you feel is appropriate.
 
-Also configure will create a Makefile in the top level directory as well
+Also, configure will create a Makefile in the top level directory as well
 as in the various subdirectories.  You should check the user configuration
 section of the top level Makefile.
 
 Compiling Zsh
 -------------
 
-After configuring, to build zsh, do the command:
+After configuring, to build zsh, execute the command:
     make
 
+It's then a good idea to check that your build is working properly:
+    make check
+
+If you have trouble with a particular test, you can run it separately:
+    make TESTNUM=C02 check
+
+The TESTNUM value can be a single test number, as above, or a letter to
+run an entire category of tests:
+    make TESTNUM=Y check
+
+See Test/README for a list of test categories.
+
 Installing Zsh
 --------------
 
-If no make/compilation errors occur, then to install the zsh binary, do
+If no make/compilation errors occur, then execute the command
-the command:
+    make install
-    make install.bin
+to install all the necessary files except for the info files.
 
+Alternatively, you can install the various parts in separate stages.  To
+install the zsh binary, execute the command:
+    make install.bin
 Any previous copy of zsh will be renamed "zsh.old"
 
-To install the dynamically-loadable modules, do the command:
+To install the dynamically-loadable modules, execute the command:
     make install.modules
+Note that this is required for the shell to operate properly if dynamic
+loading is enabled.
 
-To install the zsh man page, do the command:
+To install the zsh man page, execute the command:
     make install.man
 
-To install all the shell functions which come with the distribution, do the
+To install all the shell functions which come with the distribution,
-command:
+execute the command:
     make install.fns
 
-Or alternatively, you can install all the above with the command:
+To install the zsh info files (this must be done separately), execute the
-    make install
-
-To install the zsh info files (this must be done separately), do the
 command:
     make install.info
-
 If the programme install-info is available, "make install.info" will
 insert an entry in the file "dir" in the same directory as the info
 files.  Otherwise you will have to edit the topmost node of the info
@@ -205,6 +228,9 @@ source code in the directory that "configure" is in.  For example,
     /usr/local/src/zsh-3.0/configure
     make
 
+Note that this is mutually exclusive with using the source directories
+as make can become confused by build files created in the source directories.
+
 
 =====================
 CONFIGURATION OPTIONS
@@ -218,7 +244,7 @@ which reduce memory usage on some systems. To use these, add the option
   --enable-zsh-mem
 when invoking "configure".
 
-You should check Etc/MACHINES to see if there are specific recommendations
+You should check MACHINES to see if there are specific recommendations
 about using the zsh malloc routines on your particular architecture.
 
 Debugging Routines
@@ -257,8 +283,8 @@ can be overriden using one of the options below when invoking "configure".
  --enable-zlogout=pathname    # the full pathname of the global zlogout script
 
 Any startup/shutdown script can be disabled by giving the
---disable-scriptname option to "configure".  The --disable-etcdir option
+--disable-SCRIPTNAME option to "configure".  The --disable-etcdir option
-disables all startup/shutdown files which are not explicitely enabled.
+disables all startup/shutdown files which are not explicitly enabled.
 
 Shell functions
 ---------------
@@ -268,38 +294,33 @@ By default, the shell functions which are installed with `make install' or
 unless you have specified --datadir is the same as
 ${prefix}/share/zsh/$ZSH_VERSION/functions ($prefix itself defaults to
 /usr/local, as described below).  This directory will also be compiled into
-the shell as the default directory for the variable $fpath/$FPATH. You can
+the shell as the default directory for the parameters $fpath and
-override it with --enable-fndir=directory; --disable-fndir or
+$FPATH. You can override it with --enable-fndir=directory; --disable-fndir
---enable-fndir=no will turn off both installation of functions and the
+or --enable-fndir=no will turn off both installation of functions and the
 setting of a default value for $fpath/$FPATH.  Note the presence of
 $ZSH_VERSION (e.g. `3.1.7') to avoid clashes between versions of zsh.
 If you only run one version of zsh at once, installing into a common
-directory such as /usr/local/share/zsh/functions is fine.
+directory such as /usr/local/share/zsh/functions is fine --- note, however,
+that uninstallation is more likely to create problems in this case.
 
-You can control the functions which get installed by setting
+The functions to be installed are controlled by config.modules.  These
-FUNCTIONS_INSTALL, either when running configure (e.g.
+appear at the end of the line after `functions=': note that the rest of the
-`FUNCTIONS_INSTALL="..." configure ...') or when running `make install' or
+line is taken verbatim as shell command line text, i.e. no quoting is used
-`make install.fns'.  It includes a list of files relative to either the
+around the value as a whole and unquoted wildcards will be expanded.  To
-Completion or Functions subdirectories.  By default, all the functions for
+prevent any functions from being installed, either remove the `functions='
-the Completion system will be installed (see the zshcompsys manual page),
+entry or delete the rest of the line after it.
-plus those provide functions for the line editor, i.e.
-  FUNCTIONS_INSTALL='Core/* Base/* Builtins/* User/* Commands/* Debian/* Linux/* X/* Zle/* Prompts/* Misc/*'
-and if the --enable-dynamic option was given, the functions in
-Functions/Zftp, which require the zftp module to be available (see the
-zshzftpsys manual page), will be included as well.  Note, however, that
-some of the functions in the User subdirectory are version- and
-system-specific.
 
-There are also some miscellaneous functions with documentation in comments;
+Functions not specific to a particular module are listed on the zsh/main
-the complete set of functions can be installed with
+line.  None of these are crucial to shell operation, so you may choose not
-  FUNCTIONS_INSTALL='Core/* Base/* Builtins/* User/* Commands/* \
+to install them.  For other modules, the functions will be installed if and
-  Debian/* Linux/* X/* Misc/* Zftp/* Zle/*'
+only if the module itself is installed.  This will usually be what you
-Note you should set this by hand to include `Zftp/*' if you have zftp
+want; in particular, the zsh/complete and zsh/zftp modules are of much less
-compiled into a statically linked shell.
+use without the associated functions.  The functions listed with zsh/zle
+are not used by the editor unless you explicitly load them, however.
 
 You can also use the configure option --enable-function-subdirs to allow
 shell functions to be installed into subdirectories of the function
-directory, i.e. `Core/*' files will be installed into `FNDIR/Core', and so
+directory, i.e. `Base/*' files will be installed into `FNDIR/Base, and so
 on. This also initialises $fpath/$FPATH appropriately.
 
 The option --enable-site-fndir controls whether to create and initialise
@@ -310,27 +331,38 @@ $fpath array on shell startup.  This directory will not be affected by
 `make uninstall' or `make uninstall.fns', although the version-specific
 directory and its contents will be deleted.
 
+Function depth
+--------------
+
+Shell functions may be called recursively.  In order to detect infinite
+recursion the shell has a limit on the depth to which functions may be
+called:  note that this is a single limit for all functions, not a limit
+for each function called recursively.  The default for the limit is 4096.
+The limit may be altered to the value MAX by passing the option
+--enable-max-function-depth=MAX to configure.  Alternatively, the limit may
+be disabled with --disable-max-function-depth.  However, this is not
+recommended as it is likely to cause the shell to crash on an infinite
+recursion.
+
 Support for large files and integers
 ------------------------------------
 
 Some 32-bit systems allow special compilation modes to get around the 2GB
-file size barrier.  The option --enable-lfs turns on the configure check
+file size barrier.  This is enabled by default; use --disable-lfs to turn
-for support for large files.  This is now enabled by default; use
+it off.  Not all systems recognize the test used by zsh (via the getconf
---disable-lfs to turn it off.  Not all systems recognize the test used by
+command), so flags may need to be set by hand.  On HP-UX 10.20, zsh has
-zsh (via the getconf command), so flags may need to be set by hand.  On
+been successfully compiled with large file support by configuring with
-HP-UX 10.20, zsh has been successfully compiled with large file support by
-configuring with
   CC="cc -Ae" CPPFLAGS="-D_LARGEFILE_SOURCE -D_FILE64" configure \
   --enable-lfs ...
-You can also give a value to --enable-lfs, which will be interpreted as the
+You can also specify --enable-lfs together with a value, which will be
-name of a 64-bit integer type, for example --enable-lfs="long long"
+interpreted as the name of a 64-bit integer type, for example
-(although this type is checked for anyway).
+--enable-lfs="long long" (although this type is checked for anyway).
 
 Furthermore, use of --enable-lfs will also enable 64-bit arithmetic for
 shell parameters, and anywhere they are used such as in mathematical
 formulae.  This depends only on the shell finding a suitable 64-bit integer
 type; it does not require that support for large files is actually
-enabled.  Hence you might consider using --enable-lfs on any 32-bit system
+enabled.  Hence --enable-lfs is useful on many 32-bit systems
 with a suitable compiler such as gcc.
 
 Also note that if `configure' finds out that either of the types off_t or
@@ -341,6 +373,39 @@ correct handling of these types.
 None of this is relevant for 64-bit systems; zsh should compile and run
 without problems if (sizeof(long) == 8).
 
+Searching for additional features
+---------------------------------
+
+Various additional features are turned off by default to avoid
+compatibility problems.
+
+--enable-pcre:
+
+Zsh has a module which allows the pcre regular expression library to be
+used via shell builtins.  Compiling this library into the shell with
+dynamic loading (the default where available) produces a dependency on the
+library libpcre.so.  This is a problem on systems where zsh needs to be
+available at boot before the directory containing libpcre.so (for example
+/usr/lib or /usr/local/lib) is mounted.  For this reason, pcre support will
+only be searched for if the option --enable-pcre is passed to configure.
+
+(Future versions of the shell may have a better fix for this problem.)
+
+--enable-cap:
+
+This searches for POSIX capabilities; if found, the `cap' library
+is available and the shell will use these to determine if the
+shell is running in some privileged mode.  This is turned off by
+default as on some systems non-standard headers (in particular AIX) are
+required.  A direct fix for that problem would be appreciated.
+
+A test for the function tcsetpgrp is turned on by default.  The test
+needs to run the function to determine if the implementation is
+usable. However, this can cause problems when configure is run without
+a controlling terminal (eg. from cron).  To avoid this, use
+--with-tcsetpgrp or --without-tcsetpgrp to tell configure whether the
+function should be used.
+
 Options For Configure
 ---------------------
 
@@ -358,33 +423,39 @@ Configuration:
 
 Directories:
   --prefix=PREFIX       # install host independent files in PREFIX [/usr/local]
-  --exec-prefix=EPREFIX  # install host dependent files in EPREFIX [same as prefix]
+  --exec-prefix=EPREFIX # install host dependent files in EPREFIX [PREFIX]
   --bindir=DIR          # install user executables in DIR [EPREFIX/bin]
   --infodir=DIR         # install info documentation in DIR [PREFIX/info]
   --mandir=DIR          # install man documentation in DIR [PREFIX/man]
   --srcdir=DIR          # find the sources in DIR [configure dir or ..]
+  --datadir=DATADIR     # install shared files in DATADIR [PREFIX/share]
 
 Features:
   --enable-FEATURE      # enable use of this feature
   --disable-FEATURE     # disable use of this feature
 
-     The FEATURES currently supported are:
+Here is the list of FEATURES currently supported.  Defaults are shown in
-     zsh-debug           # use it if you want to debug zsh
+brackets, though a value shown as `yes' (equivalent to --enable-FEATURE)
-     zsh-mem             # use zsh's memory allocators
+will be ignored if your OS doesn't support that feature.
-     zsh-mem-debug       # debug zsh's memory allocators
+
-     zsh-mem-warning     # turn on warnings of memory allocation errors
+zsh-debug            # compile debugging features into zsh [no]
-     zsh-secure-free     # turn on memory checking of free()
+zsh-mem              # use zsh's memory allocators [no]
-     zsh-hash-debug      # turn on debugging of internal hash tables
+zsh-mem-debug        # debug zsh's memory allocators [no]
-     etcdir=directory    # default directory for global zsh scripts
+zsh-mem-warning      # turn on warnings of memory allocation errors [no]
-     zshenv=pathname     # the full pathname of the global zshenv script
+zsh-secure-free      # turn on memory checking of free() [no]
-     zshrc=pathname      # the full pathname of the global zshrc script
+zsh-hash-debug       # turn on debugging of internal hash tables [no]
-     zlogin=pathname     # the full pathname of the global zlogin script
+etcdir=directory     # default directory for global zsh scripts [/etc]
-     zprofile=pathname   # the full pathname of the global zprofile script
+zshenv=pathname      # the path to the global zshenv script [/etc/zshenv]
-     zlogout=pathname    # the full pathname of the global zlogout script
+zshrc=pathname       # the path to the global zshrc script [/etc/zshrc]
-     fndir=directory     # the directory where shell functions will go
+zlogin=pathname      # the path to the global zlogin script [/etc/zlogin]
-     site-fndir=directory# the directory where site-specific functions can go
+zprofile=pathname    # the path to the global zprofile script [/etc/zprofile]
-     function-subdirs    # if functions will be installed into subdirectories
+zlogout=pathname     # the path to the global zlogout script [/etc/zlogout]
-     omit-modules=mod1,..# don't compile nor install the modules named mod1,...
+fndir=directory      # the directory where shell functions will go
-     dynamic             # allow dynamically loaded binary modules
+                     # [DATADIR/zsh/VERSION/functions]
-     lfs                 # allow configure check for large files
+site-fndir=directory # the directory where site-specific functions can go
-     locale              # allow use of locale library
+                     # [DATADIR/zsh/site-functions]
+function-subdirs     # if functions will be installed into subdirectories [no]
+dynamic              # allow dynamically loaded binary modules [yes]
+lfs                  # allow configure check for large files [yes]
+locale               # allow use of locale library [yes]
+