                                                        -*- coding: utf-8 -*-
TABLE OF CONTENTS
=================

1. Introduction
2. Copyright and License
3. System Requirements
4. Installation
5. Getting Started
6. Documentation
7. Testing
8. Bugs
9. Author Information


INTRODUCTION
============

The svnmailer is a tool, which is usually called by a subversion hook
to submit commit notifications in various ways (at the moment: mail via
SMTP or a pipe to a sendmail like program, news via NNTP, CIA live
tracker notification via XML-RPC). It is derived from the original
mailer.py distributed with subversion, but supposed to be much more
consistent, better extensible and to have much more features. Have a
look at the documentation for further details.


COPYRIGHT AND LICENSE
=====================

Copyright 2004-2005 André Malo or his licensors, as applicable.

The whole package is distributed under the Apache License Version 2.0.
You'll find a copy in the root directory of the distribution or online
at: <http://www.apache.org/licenses/LICENSE-2.0>.

However, some implementation ideas (and the config format, because it's
supposed to be compatible) are derived from the subversion mailer and
the variant the ASF is using. So:

This product includes software developed by
CollabNet (http://www.Collab.Net/).

This product includes software developed by
The Apache Software Foundation (http://www.apache.org/).

Hoping that I didn't forget any of the legal stuff.


SYSTEM REQUIREMENTS
===================

In order to use the svnmailer, you need to have subversion >= 1.0 and the
subversion python bindings installed. Further you need python 2.3 or later.
The code is supposed to run with subversion 1.0.x, 1.1.x and 1.2.x.

The svnmailer was written for POSIX and Win32 systems.

So far, it's tested on
 * Gentoo Linux / svn 1.0.9     / python 2.3
 * Gentoo Linux / svn 1.1.1     / python 2.3
 * Gentoo Linux / svn 1.1.3     / python 2.3
 * Gentoo Linux / svn 1.2.0     / python 2.3
 * Gentoo Linux / svn 1.2.1     / python 2.3
 * Gentoo Linux / svn 1.2.3     / python 2.3
 * SuSE 9.1     / svn 1.1.1     / python 2.3
 * SuSE 9.1     / svn 1.2.1     / python 2.3
 * FreeBSD 4.11 / svn 1.1.2     / python 2.4
 * FreeBSD 4.11 / svn 1.1.4     / python 2.4
 * FreeBSD 5.4  / svn 1.2.3     / python 2.4
 * Windows 2000 / svn 1.1.3     / python 2.3

Furthermore there are packages out there for Debian, Redhat, Mandriva and
more, but not tested personally.


INSTALLATION
============

svnmailer is set up using the standard python distutils. So you can install
it using the usual command:

$ python setup.py install

The command above will install a new "svnmailer" package into python's
library path and a script called "svn-mailer" ("svn-mailer.py" on Win32)
into the appropriate script directory. This may be /usr/bin or
/usr/local/bin or something totally different on unixish systems, depending
on the prefix of your python installation. On Win32 it's the Scripts
directory in your python installation (like C:\Python\Scripts).

Additionally it will install the documentation. On Win32 the target location
is the Doc directory in your python installation (C:\Python\Docs). On unices
it will be installed by default into <prefix>/doc/svnmailer and
<prefix>/man/man1. In order to change the location, you can use the
--install-data command line parameter after the install subcommand, for
instance:

$ python setup.py install --install-data=/usr/share

For further customization options please study the output of

$ python setup.py --help


GETTING STARTED
===============

After the installation, first make sure that the mailer works in general.
The following command gives you the version of the svnmailer and the svn
version it uses. If this does not crash (which may happen on missing
subversion bindings), chances are good, that the installation was successful:

$ svn-mailer --version

In order to let the svnmailer do some real work, you need to create a
configuration file and then configure your repository properly to actually
use the mailer. You'll find some sample files in the sample/ directory of
the distribution. Don't forget to adjust the mail addresses and such ;-)
How to configure the svnmailer is described in great detail in the
documentation.


DOCUMENTATION
=============

You'll find a user documentation in the docs/ directory of the
distribution package (index.html). It is installed by default under
<prefix>/doc/svnmailer (e.g. /usr/doc/svnmailer). Further, there's the
code documentation, generated by epydoc (<http://epydoc.sourceforge.net/>),
which can be found in the apidoc/ subdirectory.

The latest documentation is also available online at
<http://opensource.perlig.de/svnmailer/>.


TESTING
=======

A (still incomplete) test suite is available as an extra package
(svnmailer_test). This test package needs to be downloaded seperatly.


BUGS
====

No bugs, of course. ;-)
But if you've found one or have an idea how to improve the svnmailer,
please send a mail to <svnmailer-bugs@perlig.de>.


AUTHOR INFORMATION
==================

André "nd" Malo <nd@perlig.de>
GPG: 0x8103A37E


If God intended people to be naked, they would be born that way.
                                                 -- Oscar Wilde
