[README for cmail]

Please refer to documents in doc/ directory for more information about
usage of optional packages and OS environment.

What is cmail?
==============

Cmail is a mail user agent (MUA) that works on emacsen. Cmail supports
your email handling -- reading, composing and sending messages. Cmail
was originally written by Makoto Hayashi, it was called `chain-mail'
(version 1.*). Since then, Yukihiro Matsumoto has greatly modified it
and released as the name of `cmail'. The current cmail version is 2.*.

Installation
============

Standard installation procedure
-------------------------------

1a) If you can use `make' utility.

You can install cmail simply by doing following:

% make install EMACS=mule PREFIX=/usr/local

You can also specify the other options such as EXEC_PREFIX (current
version of cmail will ignore this option), LISPDIR, INFODIR.

1b) If you can't use `make' utility.

You can install it by using Emacs directly.

% mule -batch -q -no-site-file -l CMAIL-MK -f install-cmail \
    /usr/local NONE /usr/local/lib/emacs/site-lisp /usr/local/info

Please specify these options in the order of PREFIX, EXEC_PREFIX,
LISPDIR, INFODIR. If you don't want to specify one of these options,
please specify NONE as the option. Then it will be ignored.

2) Installation of tm/SEMI.

If you want to use MIME with cmail, you should install the package tm
(intended for use with GNU Emacs 18.xx and 19.xx) or SEMI (intended
for use with GNU Emacs 20.x and 21.x).

Please get the source package for example at the following site,

http://cvs.m17n.org/elisp/SEMI/
http://cvs.m17n.org/elisp/FLIM/
http://cvs.m17n.org/tomo/comp/emacsen/tm/tm-8/

and install it.

You can use cmail without them, but we recommend the use of MIME
extention pacakge for your convenience.

If you install cmail without tm/SEMI, the required file for using
tm/SEMI from cmail is not installed. If you want to use tm/SEMI,
please install cmail after installing tm/SEMI.

3) How to register Info file.

Detail usage for cmail is described in the cmail.info file that is
installed by the step 1a) or 2b).

Please add the following description in the `dir' file at the
Info file directory (default is /usr/local/info).

* cmail: (cmail). cmail reference manual.

Now you can ready to read it with `M-x info'.

NOTE: if you can use 'install-info' command, executing it will update
the 'dir' file for you. (install-info --help will tell you its usage.)
The command can be invoked as follows:

$ install-info --info-dir=INFORDIR INFODIR/cmail.info
$ install-info --info-dir=INFORDIR INFODIR/cmail.en.info

Where INFODIR is the name of the info diretory.

For example, if INFODIR=//c/Meadow/1.14/info, then type:

$ install-info --info-dir=//c/Meadow/1.14/info //c/Meadow/1.14/info/cmail.info
$ install-info --info-dir=//c/Meadow/1.14/info //c/Meadow/1.14/info/cmail.en.info

Or if INFODIR=/usr/local/info, type:

$ install-info --info-dir=/usr/local/info /usr/local/info/cmail.info
$ install-info --info-dir=/usr/local/info /usr/local/info/cmail.en.info


Installation Notes
------------------

1) APEL

Due to introduction of customize interface, version 2.61 or later
release requires APEL (or A Portable Emacs lisp Library -
http://cvs.m17n.org/elisp/APEL/) which supports pcustom
module. Because of this change, please note the following:

  o If a compatible version of APEL is already installed, only cmail
    modules will be compiled and installed.

  o If APEL is not installed, and the standard installation procedure
    is followed, first, APEL included in the cmail distribution will
    be compiled and cmail modules will be compiled, then installation
    will be done for both packages.

    Parameters passed in to the make utility such as PREFIX,
    EXEC_PREFIX, LISPDIR, INFODIR will be shared by both APEL and
    cmail. If you prefer to use different parameters, install APEL
    from apel/ directory first, adjust load-path by changing
    subdirs.el etc. such that Emacs can find apel modules, and then
    install cmail.

  o If standard installation procedure is not followed, and compiled
    cmail directory is manually included in your load-path, apel/
    directory needs to be added as well.

  o If APEL is first installed, you need to adjust load-path
    accordingly, otherwise cmail may not start properly due to errors
    such as "Cannot open load file: path-util". Add apel directories
    to your load-path.

In addition, cmail uses a feature provided by the custom library to
dynamically setup necessary modules when a customizable variable is
modified. This feature provide a convenient way to perform rather
complicated procedures to activate the option without restarting cmail
or Emacs, however, it is unfortunate that old custom versions do not
support it. Making things worse, with such version of custom, when
compiling or invoking cmail, an error might result. Currently
custom.el version 1.15 which comes with Gnus 5.4.1 has been confirmed
to be this type of custom.el. There is some code put in place in cmail
to workaround this problem, but this does not cover every case as
cmail can do only things that would not affect other packages (such as
Gnus). In either case, this type of custom library will do any good in
a long run, so it is recommended to upgrade to a recent version of
custom library as soon as possible. Please refer to apel/README.ja
"old custom" vs "new custom" section as well for more detail.

2) Install Directory

Starting from version 2.61, for 20.x version Emacs the installation
directory has been changed. It creates "cmail" sub-directory under
LISPDIR. This is the same rule as for xemacs in 2.60 and older
version. An exception is that if cmail has been already installed
directly under LISPDIR, in order to avoid confusion in having two
versions under LISPDIR, cmail will not attempt to create "cmail"
sub-directory, instead, overwrite existing cmail modules in the same
manner as 2.60.

"what-where" make target can be used with the make utility to display
where modules will be installed. This is useful to confirm the
destination before actual installation.


Post Installation Configuration
===============================

After installation is completed, configure your .emacs by refering to
Info. It contains explanation of variables you should minimally set,
in order to make cmail usable.

If your can use the custom feature (such as version 20.x GNU Emacs),
after loading cmail by:

  M-x load-library<CR>
  cmail<CR>

Type:

  M-x cmail-customize

to invoke the customize editor. This allows you to configure option
variables while refering detailed explanation of each option variable.


Misc
====

If you use Meadow, Mule for Windows, or other Windows based Emacs, it
is recommended to review doc/README.Windows, which details windows
specific installation tips and explanation of external packages.
