$Id: README,v 1.5 2001/10/27 15:17:28 joern Exp $

NAME
	JaM - Just a Mailer

SYNOPSIS
	bin/jam.pl

DESCRIPTION
	The working title for this piece of software is:

	"Highly Secure Personal Free Highspeed Archiving
	 Gtk Perl Mailer Against Micro$oftism"

	which describes its purpose in a nutshell.

	But, primarily, it is: Just a Mailer. ;)
	
	It is designed exactly for Unix users like me. If other
	Unix users at least like reading mail my way, they may
	like this program, too ;)
	
	JaM handles big mail folders, has a powerful filter engine
	and a lean and quick Gtk+ GUI. It uses a MySQL database
	to store its data, which makes JaM capable of handling
	huge mail folders very quickly.
	
	If you're using Netscape Messenger and are fed up with its
	bugs, JaM is for you, because it can import your mail from
	the Netscape nsmail folder.
	
	Generally JaM is not designed to have any feature a mail
	client possibly may have!

PREREQUISITES
	1. An up and running MySQL database
	
	Currently only MySQL is supported as the storage backend.
	Attaching other RDMBS is possible but not currently realized.
	
	2. Gtk+ version 1.2 or better
	
	JaM uses the Gtk+ toolkit for its gui.
	
	3. html2ps
	
	html2ps is used for printing mails.
	
	4. A bunch of Perl modules:
	
	  DBI 1.20
	  DBD::mysql
	  Date::Manip
	  Gtk
	  Gtk::HTML
	  MIME::Entity
	  MIME::Parser
	  MIME::Types
	  MIME::WordDecoder
	  Net::POP3
	  Net::SMTP
	  Storable
	  Unicode::String

	I recommend using the powerfull CPAN module to install
	these modules automatically. JaM ships with a CPAN Bundle
	file which contains the modules listed above, so installation
	of these may be as easy as to write:
	
	  # perl -MCPAN -Ilib -e "install Bundle::JaM"

	after extracting the JaM archive and changing to the created
	installation directory.

	Unfortunately the DBD::MySQL CPAN distribution is currently
	experimental, so the Bundle has to point explicitely to
	the stable Msql-Mysql-modules distribution, what makes CPAN
	automatic version check fail. If you repeatedly install the
	JaM Bundle CPAN will always install DBD::MySQL, although it
	is installed already. You can interrupt via Ctrl+C when the
	installer asks you which drivers should be installed.
	
	Also installation of Gtk::HTML isn't easy, because it needs
	a lot of installed libraries. I know, that makes satisfying JaM's
	prerequisites a really hard task. But such is life, folks ;)
	SuSE 7.2 provides all needed libraries, just struggle arround
	with YaST a bit, if you're a lucky SuSE 7.2 owner ;)

	JaM will crash unpredictable if any of the needed modules are
	missing. There is no startup check routine, because some modules
	are loaded at runtime when needed.

INSTALLATION
	There is no installation program. Just extract the archive
	wherever you want, eg. in /usr/local, and set a symlink to
	the version you want to use (the JaM archive creates a directory
	which includes the version number):
	
	  # cd /usr/local
	  # tar xfz /tmp/JaM-x.xx.tar.gz
	  # ln -s JaM-x.xx/ JaM

	Install needed Perl modules, if not already done:
	
	  # cd JaM
	  # perl -MCPAN -Ilib -e "install Bundle::JaM"

	Now you can start JaM using:
	
	  /usr/local/JaM/bin/jam.pl

	You can set a symlink inside a common bin directory. JaM find
	its installation directory automatically.
	
	  # cd /usr/local/bin
	  # ln -s /usr/local/JaM/bin/jam.pl .

	On first startup JaM recognizes, that the MySQL database needs to
	be initialized. It asks you some questions and will create
	the database for you. A help text will guide you through this.
	
	It then creates a .JaMrc file inside the users home directory, which
	contains the MySQL connection information. All other files of JaM
	did not to be writable by the user, so you can install JaM in a
	read only system area. Multiuser access is no problem at all.
	
	You also may set the JAMRC environment variable pointing to another
	.JaMrc file. This way multiple database instances per user are
	supported.

UPDATING TO NEWER VERSION
	Updating is as easy as installing. Just extract the archive where
	you installed JaM and recreate the symlink, so that the new
	directory will be used.
	
	On next startup JaM will check your database schema version. If
	the schema needs to be updated, JaM suggests you to make a backup
	of your MySQL database. Then it can update the schema automatically.
	Update across several versions of JaM is supported.

AUTHOR
	Joern Reder <joern@zyn.de>

COPYRIGHT
	Copyright (C) 2001 by Joern Reder, All Rights Reserved.

	This program is free software; you can redistribute it and/or
	modify it under the same terms as Perl itself.

SEE ALSO
	perl(1).