PRE-COMPILED BINARIES
=====================

If you have downloaded binaries for Gnu Emacs version 22 or 23, you
can unpack it to a directory, say ~/vm, and go to step (3) below.

However, this build assumes that you are not using any supporting
libraries such as BBDB, W3 or W3M.  If you are using such libraries,
please rebuild VM as indicated below.  

If you are using XEmacs, you need to do your own build.

USING CONFIGURE
===============

0) If you get VM from the revision control, the ./configure script is
   not included. You have to run "autoconf" to create it.  If you got
   VM from a public release, you should skip this step.

1) Select your emacs flavor, this is the option --with-emacs and its
   default is emacs (GNU Emacs).  Choose a prefix for the installation
   with --prefix, by default /usr/local.

   The default locations are as follows:

   a) GNU Emacs: lisp files goto ${prefix}/share/emacs/site-lisp and
      info files to ${prefix}/info (overridable with --with-lispdir=...
      and --infodir=...)

   b) XEmacs: lisp files goto ${prefix}/lib/xemacs/site-packages/lisp/vm and
      info files to ${prefix}/lib/xemacs/site-packages/info, (overridable
      with --with-lispdir=... and --infodir=...)

   ATTENTION: Files byte-compiled with GNU Emacs are NOT COMPATIBLE with the
   XEmacs and you may experience strange problems during startup when doing
   so.  Even between GNU Emacs versions there might be problems! Thus you must
   ensure you are configuring with --with-emacs=xemacs when installing VM for
   XEmacs!  Also if you want to use BBDB or Emacs-w3m features please
   specify the path to their source files with the -with-other-dirs option. 

   a) GNU Emacs+BBDB users run:
	./configure --with-other-dirs=/absolute/path/to/bbdb/lisp

   b) XEmacs+BBDB users run:
	./configure --with-emacs=xemacs --with-other-dirs=/path/to/bbdb/lisp
   
   c) GNU Emacs+BBDB+Emacs-w3m users run:
	./configure --with-other-dirs="/absolute/path/to/bbdb/lisp;/absolute/path/to/emacs-w3m"

   d) XEmacs with no additional packages
        ./configure --with-emacs=xemacs

   It is currently not possible to build VM in a separate directory.

2) Compile everything by running:

	make

   You may ignore warnings, however error messages indicate that some modules
   (partially) will not work, i.e. if other library files are missing or you
   are running GNU Emacs.

3) Installing the files

   a) The manual way

      Add the "lisp" and "info" directories in the VM built directory to the
      Emacs search paths, e.g. if you have built vm in ~/vm add the following
      to your ~/.emacs resp. ~/.xemacs/init.el. 

         (add-to-list 'load-path
                      (expand-file-name "~/vm/lisp"))
         (add-to-list 'Info-default-directory-list
	              (expand-file-name "~/vm/info"))

      GNU Emacs users, have to load the autoloads by hand by adding

         (require 'vm-autoloads)

      to their ~/.emacs.  If there are any old VM-related autoloads in
      your ~/.emacs file, you should remove them.  The vm-autoloads
      library takes care of all the autoloads for VM.

      XEmacs: Since XEmacs has a built-in distribution of VM, you have two
      options.  (i) You can delete the built-in package in the XEmacs
      xemacs-packages directory.  Then the new copy of VM in ~/vm/lisp
      will get loaded.  (ii) You can include the following line in
      your ~/.xemacs/init.el file:

        (load-library "~/vm/lisp/auto-autoloads")

   b) make install

      Which might work, but might not work as most distros have their own
      directory layout.

4) Add the following line to your info directory (dir):

* VM: (vm.info).		  VM Mail Reader
* VM-PCrisis: (vm-pcrisis.info).  Personality Crisis package for VM

   Note that vm-pcrisis is a separate add-on package (not officially a
   part of VM).

   You are now ready to use VM.  C-h i should start up the Emacs Info
   system and if you have installed the Info documents properly you can
   use the online documentation to teach yourself how to use VM.

COMPANION PACAKAGES
===================

VM uses companion packages for address book maintenance and HTML
display.  VM will work fine even if the companion packages are
unavailable, but the best functionality is obtained with them.

* BBDB or "Big Brother Insidious DataBase" is an address book
  application that runs within Emacs.  It is able to watch the email
  addresses in the headers of your email addresses and record them in
  the database.

  Assuming that you have compiled VM with BBDB included in the
  `lispdir' list, include the following lines in your .emacs to turn
  on BBDB support:

         (require 'bbdb)
	 (bbdb-initialize 'vm)

* For rendering HTML messages, VM can make use of the following Emacs
  libraries:

  - Emacs/W3 - a web browser written by William Perry in Emacs Lisp.
    It is said to be slow and its current maintenance (in 2010) is
    weak.

  - Emacs/W3M - an Emacs interface to the text-mode web browser W3M.

  For guidance on installing either of these libraries, please check
  their EmacsWiki pages and their own installation instructions.

  VM can also make use of the following external text-mode web
  browsers (as basically converters from html to plain text).

  - Lynx - A fast text-based web browser that runs under Unix.
  Developed at the University of Kansas.

  - W3M - Possibly the best text-based web browser.  Written by
  Akinori Ito and his team, it runs fast and renders pages
  as true to form as possible in plain text.
  
  VM can check the libraries available on your path and pick the best
  one for HTML rendering, but you can also specify the choice
  explicitly by including in your .emacs file, e.g.,

          (setq vm-mime-text/html-handler 'emacs-w3m)

  Other than 'emacs-w3m, you can also use 'w3, 'w3m and 'lynx.
