Zsh Mailing List Archive
Messages sorted by:
Reverse Date,
Date,
Thread,
Author
PATCH: documentation changes
- X-seq: zsh-workers 14573
- From: Peter Stephenson <pws@xxxxxxx>
- To: zsh-workers@xxxxxxxxxx (Zsh hackers list)
- Subject: PATCH: documentation changes
- Date: Wed, 30 May 2001 16:58:25 +0100
- Mailing-list: contact zsh-workers-help@xxxxxxxxxx; run by ezmlm
Here are some changes for the documentation, in particular INSTALL and
README, which you may want to check in case I've got it completely wrong.
The list of incompatibilities from 3.0 in README is probably rather
incomplete, has anyone (not *necessarily* Bart) been keeping better track?
The one for builtins.yo is beacause the `read' entry spills onto two lines,
which nroff in particular handles very badly, though it's not the cause of
the problem I just mentioned.
Util/helpfiles chokes on the complicated zmodload entry. I'm not sure I'll
get round to fixing this.
Index: INSTALL
===================================================================
RCS file: /cvsroot/zsh/zsh/INSTALL,v
retrieving revision 1.9
diff -u -r1.9 INSTALL
--- INSTALL 2001/05/30 10:26:59 1.9
+++ INSTALL 2001/05/30 15:52:59
@@ -7,6 +7,7 @@
have a look at the items in the second part before following the
instructions in the first.
+
=====================
MAKING AND INSTALLING
=====================
@@ -39,9 +40,10 @@
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
---------------
@@ -74,9 +76,17 @@
much as possible.
The key to the module system is the file config.modules, created in the
-configuration process. Each module has a line in the file. It may be
-edited to change the following values for each module; be careful to retain
-the (strict) format for the file:
+configuration process. In the normal case that dynamic loading is
+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.
+
+If you wish to change the configuration, here is how config.modules works.
+Each module has a line in the file. Be careful to retain the (strict)
+format for lines in the file:
link - `dynamic', if the module is to be dynamically linked -- meaningless
if this is not available on your system.
`static' if the module is to be linked directly into the executable.
@@ -90,13 +100,9 @@
statically and dynamically linked modules.
auto - `yes' if the entry is to be regenerated whenever configure is run.
`no' if you wish to retain your hand-edited version.
-Do not edit the entry for the pseudo-module zsh/main, which is the main
-shell. After you have edited this file, run `make prep' in the Src
-subdirectory.
-
-By default the complete, compctl, zle, computil, complist, sched, parameter,
-zleparameter and rlimits modules are compiled into non-dynamic zsh and no
-modules are compiled into the main binary if dynamic loading is available.
+Do not edit the entry for the pseudo-module zsh/main (apart from the
+`functions=' part) as this is the main shell. After you have edited this
+file, run `make prep' in the Src subdirectory.
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
@@ -114,21 +120,21 @@
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
-
-Or on systems that have the "env" program, you can do it like this:
- env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
-
-The flags CFLAGS, CPPFLAGS, LDFLAGS and LIBS can also be set as flags to
-configure, where the name appears in lower case:
- configure --enable-cflags=-O2 --enable-libs=-lposix
-
-The advantage of this form is that `config.status --recheck' will remember
-the flags you originally specified. You can still override the flags when
-running `make' (although these will not be passed down via `config.status
---recheck').
+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.
+
+You can override the variables directly when running `make':
+ make CFLAGS=-g
+However, these will not be passed down via `config.status --recheck'.
Check Generated Files
---------------------
@@ -142,14 +148,14 @@
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:
@@ -167,29 +173,30 @@
Installing Zsh
--------------
-If no make/compilation errors occur, then to install the zsh binary, do
-the command:
- make install.bin
+If no make/compilation errors occur, then execute the command
+ make install
+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
-command:
+To install all the shell functions which come with the distribution,
+execute the command:
make install.fns
-
-Or alternatively, you can install all the above with the command:
- make install
-To install the zsh info files (this must be done separately), do the
+To install the zsh info files (this must be done separately), execute 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
@@ -220,6 +227,9 @@
/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
@@ -272,7 +282,7 @@
--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 explicitly enabled.
Shell functions
@@ -283,9 +293,9 @@
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
-override it with --enable-fndir=directory; --disable-fndir or
---enable-fndir=no will turn off both installation of functions and the
+the shell as the default directory for the parameters $fpath and
+$FPATH. You can override it with --enable-fndir=directory; --disable-fndir
+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
@@ -297,7 +307,7 @@
line is taken verbatim as shell command line text, i.e. no quoting is used
around the value as a whole and unquoted wildcards will be expanded. To
prevent any functions from being installed, either remove the `functions='
-entry or delete the reset of the line after it.
+entry or delete the rest of the line after it.
Functions not specific to a particular module are listed on the zsh/main
line. None of these are crucial to shell operation, so you may choose not
@@ -305,7 +315,7 @@
only if the module itself is installed. This will usually be what you
want; in particular, the zsh/complete and zsh/zftp modules are of much less
use without the associated functions. The functions listed with zsh/zle
-are optional, however.
+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
@@ -324,23 +334,21 @@
------------------------------------
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
-for support for large files. This is now enabled by default; use
---disable-lfs to turn it off. Not all systems recognize the test used by
-zsh (via the getconf command), so flags may need to be set by hand. On
-HP-UX 10.20, zsh has been successfully compiled with large file support by
-configuring with
+file size barrier. This is enabled by default; use --disable-lfs to turn
+it off. Not all systems recognize the test used by zsh (via the getconf
+command), so flags may need to be set by hand. On 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
-name of a 64-bit integer type, for example --enable-lfs="long long"
-(although this type is checked for anyway).
+You can also specify --enable-lfs together with a value, which will be
+interpreted as the name of a 64-bit integer type, for example
+--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
@@ -360,41 +368,48 @@
options of interest for configuring zsh.
Configuration:
- --cache-file=FILE # cache test results in FILE
- --help # print a help message
- --version # print the version of autoconf that create configure
- --quiet, --silent # do not print `checking...' messages
- --no-create # do not create output files
+ --cache-file=FILE # cache test results in FILE
+ --help # print a help message
+ --version # print the version of autoconf that create configure
+ --quiet, --silent # do not print `checking...' messages
+ --no-create # do not create output files
Directories:
- --prefix=PREFIX # install host independent files in PREFIX [/usr/local]
- --exec-prefix=EPREFIX # install host dependent files in EPREFIX [same as 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 ..]
+ --prefix=PREFIX # install host independent files in PREFIX [/usr/local]
+ --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
+ --enable-FEATURE # enable use of this feature
+ --disable-FEATURE # disable use of this feature
+
+Here is the list of FEATURES currently supported. Defaults are shown in
+brackets, though a value shown as `yes' (equivalent to --enable-FEATURE)
+will be ignored if your OS doesn't support that feature.
+
+zsh-debug # compile debugging features into zsh [no]
+zsh-mem # use zsh's memory allocators [no]
+zsh-mem-debug # debug zsh's memory allocators [no]
+zsh-mem-warning # turn on warnings of memory allocation errors [no]
+zsh-secure-free # turn on memory checking of free() [no]
+zsh-hash-debug # turn on debugging of internal hash tables [no]
+etcdir=directory # default directory for global zsh scripts [/etc]
+zshenv=pathname # the path to the global zshenv script [/etc/zshenv]
+zshrc=pathname # the path to the global zshrc script [/etc/zshrc]
+zlogin=pathname # the path to the global zlogin script [/etc/zlogin]
+zprofile=pathname # the path to the global zprofile script [/etc/zprofile]
+zlogout=pathname # the path to the global zlogout script [/etc/zlogout]
+fndir=directory # the directory where shell functions will go
+ # [DATADIR/zsh/VERSION/functions]
+site-fndir=directory # the directory where site-specific functions can go
+ # [DATADIR/zsh/site-functions]
+function-subdirs # if functions will be installed into subdirectories [no]
+omit-modules=mod1,.. # don't compile or install the modules named mod1,...
+dynamic # allow dynamically loaded binary modules [yes]
+lfs # allow configure check for large files [yes]
+locale # allow use of locale library [yes]
- The FEATURES currently supported are:
- zsh-debug # use it if you want to debug zsh
- zsh-mem # use zsh's memory allocators
- zsh-mem-debug # debug zsh's memory allocators
- zsh-mem-warning # turn on warnings of memory allocation errors
- zsh-secure-free # turn on memory checking of free()
- zsh-hash-debug # turn on debugging of internal hash tables
- etcdir=directory # default directory for global zsh scripts
- zshenv=pathname # the full pathname of the global zshenv script
- zshrc=pathname # the full pathname of the global zshrc script
- zlogin=pathname # the full pathname of the global zlogin script
- zprofile=pathname # the full pathname of the global zprofile script
- zlogout=pathname # the full pathname of the global zlogout script
- fndir=directory # the directory where shell functions will go
- site-fndir=directory# the directory where site-specific functions can go
- function-subdirs # if functions will be installed into subdirectories
- omit-modules=mod1,..# don't compile nor install the modules named mod1,...
- dynamic # allow dynamically loaded binary modules
- lfs # allow configure check for large files
- locale # allow use of locale library
Index: README
===================================================================
RCS file: /cvsroot/zsh/zsh/README,v
retrieving revision 1.5
diff -u -r1.5 README
--- README 2001/03/12 17:39:23 1.5
+++ README 2001/05/30 15:52:59
@@ -5,10 +5,8 @@
Version
-------
-This is zsh version 3.1 (beta)
+This is zsh version 4.0. This is a stable release.
-Note that this is a beta version. The latest stable version is zsh-3.0.7.
-
Installing Zsh
--------------
@@ -19,35 +17,31 @@
Features
--------
-Zsh is a shell with lots of features. For a list of these, see the
+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
---------------------------
-If you have been using recent versions of zsh 3.1, the following changes in
-the shell may affect you:
-- The traditional bindings of \M-n (history-search-backward) and
- \M-p (history-search-forward) in older versions of zsh have returned,
- as has the traditional behaviour of those functions and the functions
- up-line-or-search and down-line-or-search. In 3.1.5, the functions
- behaved differently and \M-n and \M-p were bound by default to
- history-beginning-search-backward and history-beginning-search-forward.
-- Prompt truncation behaviour via %<...< and %>...> (or %[<...] etc.) has
- changed slightly: the string to be truncated runs to the end of the
- prompt or to the next truncation sequence; %<< will turn off truncation.
- Previously it only covered individual prompt escapes. So for example the
- prompt `%10<...<%~%% ' will now include the `%% ' in the string to be
- truncated, and you should change the prompt to `%10<...<%~%<<%% ' to turn
- off truncation immediately after the `%~'.
-- If for some reason you have `setopt norcs' or `unsetopt rcs' anywhere in
- your startup files (e.g. to stop .zlogout being run), this will now
- take effect immediately, preventing later startup files from being
- run. It is safe to put `setopt norcs' in .zlogin as this is always
- the last run.
+Some particular differences you may notice between version 3.0 and 4.0:
-See the FAQ for a discussion of changes over the longer term.
+ 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.
Documentation
-------------
@@ -84,9 +78,11 @@
may not work without changes but it is still a good
introduction.
+For more information, see the website, as described in the META-FAQ.
+
If you do not have the necessary tools to process these documents,
PostScript, ASCII, Info and DVI versions are available in the separate
-file zsh-beta-doc.tar.gz at the archive sites listed in the META-FAQ.
+file zsh-doc.tar.gz at the archive sites listed in the META-FAQ.
The distribution also contains a Perl script in Utils/helpfiles which
can be used to extract the descriptions of builtin commands from the
@@ -128,7 +124,7 @@
-------------------------------
Zsh is currently maintained by the members of the zsh-workers mailing list
-and coordinated by Peter Stephenson <pws@xxxxxxx>. Please send
+and coordinated by Peter Stephenson <coordinator@xxxxxxx>. Please send
any feedback and bugs reports to <zsh-workers@xxxxxxxxxx>.
There is a script "reporter" in the subdirectory Util which will print
Index: Doc/Zsh/builtins.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/builtins.yo,v
retrieving revision 1.25
diff -u -r1.25 builtins.yo
--- Doc/Zsh/builtins.yo 2001/04/01 16:19:16 1.25
+++ Doc/Zsh/builtins.yo 2001/05/30 15:52:59
@@ -749,8 +749,8 @@
alias(r)(fc -e -)
findex(read)
vindex(IFS, use of)
-item(tt(read) [ tt(-rzpqAclneEt) ] [ tt(-k) [ var(num) ] ] \
-[ tt(-u)var(n) ] [ var(name)[tt(?)var(prompt)] ] [ var(name) ... ])(
+xitem(tt(read) [ tt(-rzpqAclneEt) ] [ tt(-k) [ var(num) ] ])
+item([ tt(-u)var(n) ] [ var(name)[tt(?)var(prompt)] ] [ var(name) ... ])(
vindex(REPLY, use of)
vindex(reply, use of)
Read one line and break it into fields using the characters
Index: Test/README
===================================================================
RCS file: /cvsroot/zsh/zsh/Test/README,v
retrieving revision 1.1
diff -u -r1.1 README
--- Test/README 2001/04/02 13:04:05 1.1
+++ Test/README 2001/05/30 15:52:59
@@ -11,3 +11,17 @@
X: line editing
Y: completion
Z: separate systems and user contributions
+
+You will need to run these by using `make test' in the Test subdirectory of
+the build area for your system (which may or may not be the same as the
+Test subdirectory of the source tree), or the directory above. You can get
+more information about the tests being performed with
+ ZTST_verbose=1 make check
+(`test' is equivalent to `check') or change 1 to 2 for even more detail.
+
+Individual or groups of tests can be performed with
+ make TESTNUM=C02 check
+or
+ make TESTNUM=C check
+to perform just the test beginning C02, or all tests beginning C,
+respectively.
Index: Util/helpfiles
===================================================================
RCS file: /cvsroot/zsh/zsh/Util/helpfiles,v
retrieving revision 1.2
diff -u -r1.2 helpfiles
--- Util/helpfiles 2000/09/03 05:22:59 1.2
+++ Util/helpfiles 2001/05/30 15:52:59
@@ -21,12 +21,12 @@
# previous line (so you see what we're up against).
# Example usage:
-# cd ~/zsh-3.0.0 # or wherever
+# cd ~/zsh-4.0.1 # or wherever
# mkdir Help
# cd Help
-# man zsh | colcrt - | helpfiles
+# man zshbuiltins | colcrt - | helpfiles
# run-help() {
-# typeset zhelp=~/zsh-3.0.0/Help # or wherever
+# typeset zhelp=~/zsh-4.0.1/Help # or wherever
# [[ $1 = . ]] && 1=dot
# [[ $1 = : ]] && 1=colon
# if [[ $1 = compctl ]]; then
--
Peter Stephenson <pws@xxxxxxx> Software Engineer
CSR Ltd., Unit 300, Science Park, Milton Road,
Cambridge, CB4 0XL, UK Tel: +44 (0)1223 392070
**********************************************************************
The information transmitted is intended only for the person or
entity to which it is addressed and may contain confidential
and/or privileged material.
Any review, retransmission, dissemination or other use of, or
taking of any action in reliance upon, this information by
persons or entities other than the intended recipient is
prohibited.
If you received this in error, please contact the sender and
delete the material from any computer.
**********************************************************************
Messages sorted by:
Reverse Date,
Date,
Thread,
Author