Updated considerably.

svn path=/trunk/; revision=20365

1 files changed, 173 insertions, 154 deletions

diff --git a/README b/README
index f0aad5cb05..4413d468a6 100644
--- a/README
+++ b/README
@@ -1,23 +1,23 @@
-Evolution is the integrated mail, calendar and address book
-distributed suite from Ximian, Inc.
+Evolution is the integrated mail, calendar and address book suite from
+Ximian, Inc.
 
 See http://www.ximian.com/products/evolution for more information.
 
 If you are using Evolution, you may wish to subscribe to the Evolution
-users mailing list. If you are interested in contributing to
+users mailing list.  If you are interested in contributing to
 development on it, you should certainly subscribe to the Evolution
-Hackers mailing list. Visit
-http://developer.ximian.com/community/lists.html to subscribe to
-Ximian mailing lists. If you are planning to work on any part of
-Evolution, please send mail to the mailing list first, to avoid
-duplicated effort (and to make sure that you aren't basing your work
-on interfaces that are expected to change).
+Hackers mailing list.  Visit
 
-There are mailing list archives available at
-http://lists.ximian.com/archives/public/evolution/     and
-http://lists.ximian.com/archives/public/evolution-hackers/
+	http://developer.ximian.com/community/lists.html
 
-There is also an #evolution IRC channel on irc.gnome.org.
+to subscribe or view archives of the Ximian mailing lists.
+
+If you are planning to work on any part of Evolution, please send mail
+to the mailing list first, to avoid duplicated effort (and to make
+sure that you aren't basing your work on interfaces that are expected
+to change).
+
+There is also a #evolution IRC channel on irc.gnome.org.
 
 Help for Evolution is available in the user manual (select "Help" from
 the menu after running the application), at the Ximian knowledge base
@@ -27,211 +27,230 @@ evolution" at the command line), and in the --help strings (run
 
 The rest of this file is dedicated to building Evolution.
 
-PROBLEMS BUILDING EVOLUTION
----------------------------
 
-Did you read the "How to build" section below?
+DEPENDENCIES
+------------
 
-If the configure script complains that you don't have a library that
-you know you have installed, it usually means either that you've
-installed things into multiple prefixes (see the bits on GNOME_PATH
-below) or (if you're on Linux) that you installed the "foo" package
-but forgot the "foo-devel" or "foo-dev" packages.
+In order to build Evolution you need to have the full set of GNOME 2
+or GNOME 2.2 development libraries installed.
 
+GNOME 2 comes with most of the modern distributions, so in most cases
+it should be enough to just install all the devel packages from your
+distribution.  If, on the other hand, you want to build GNOME 2 from
+source, please refer to this page:
 
-HOW TO BUILD EVOLUTION
-----------------------
+	http://gnome.org/start/2.2/notes/rninstallation.html
 
-	*** READ THIS BEFORE YOU START BUILDING ANYTHING! ***
+Please make sure you have the most recent versions of the libraries
+installed, since bugs in the libraries can cause bugs in Evolution.
 
-Evolution depends on a large number of unreleased and rapidly-changing
-libraries. Some of these libraries in turn depend on other unreleased
-and rapidly-changing libraries.
+Additional dependencies, besides the stock GNOME libraries (the
+dependencies should be compiled in the order they are listed here):
 
-Building Evolution is HARD, and it's going to stay hard until all of
-the libraries it depends on stabilize, and there's nothing we can do
-to make it any easier until then.
+	* [If compiling against GNOME 2.0] libgnomeprint and
+          libgnomeprintui 2.2.0 or later
 
+	  These library come with GNOME 2.2 installations, but not
+	  with GNOME 2.0 ones.  The source code can be downloaded from
+	  the following locations:
 
-GENERAL PRINCIPLES
-------------------
+	     ftp://ftp.gnome.org/pub/gnome/sources/libgnomeprint
+	     ftp://ftp.gnome.org/pub/gnome/sources/libgnomeprintui
 
-[FIXME: This section is badly out of date.]
+	* [If compiling against GNOME 2.2] libgnomecanvas 2.2.0.2 or
+          later
 
-First you have to decide whether you want to install Evolution (and
-its dependencies) into the same prefix as the rest of your GNOME
-install, or into a new prefix. Installing everything into the same
-prefix as the rest of your GNOME install will make it much easier to
-build and run programs, and easier to switch between using packages
-and building it yourself, but it may also make it harder to uninstall
-later.
+	  If you have a GNOME 2.2 installation, you need to upgrade
+	  libgnomecanvas to this version (or a later one), since
+	  Evolution exposes a bug in the older versions of the library
+	  which causes a crash.
 
-If you want to install into the same prefix as the rest of GNOME,
-type:
+	  If you have a GNOME 2.0 installation, libgnomecanvas 2.0 is
+	  safe to use.
 
-	gnome-config --prefix
-	gnome-config --sysconfdir
+	* libsoup 1.99.12 or later
 
-and remember the answers, and pass them to "configure" or "autogen.sh"
-when building the other packages you need. For example:
+	     ftp://ftp.gnome.org/pub/gnome/sources/libsoup
 
-	./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var/lib
+	* gtkhtml 3.0.1 or later
 
-    --localstatedir is needed to make the docs integrate with scrollkeeper
-    and needs to point to the directory containing the scrollkeeper indices
-    which are in: gnome-config --localstatedir
+	     ftp://ftp.gnome.org/pub/gnome/sources/gtkhtml
 
-If you build in another prefix instead, you will need to set the
-GNOME_PATH environment variable (and ACLOCAL_FLAGS as well if building
-from CVS) to include the prefix you install into. For example:
+	* gal 1.99.2 or later
 
-        export GNOME_PATH=/usr/local
-	export ACLOCAL_FLAGS="-I /usr/local/share/aclocal"
+	     ftp://ftp.gnome.org/pub/gnome/sources/gal
 
-(Assuming your shell is bash, and you installed into /usr/local.) You
-need to set GNOME_PATH both during compiling AND when you run
-evolution. Remember also that if you're installing into an odd prefix
-such as /evolution, that you also need to make sure to put
-${prefix}/bin in your PATH and ${prefix}/lib in your LD_LIBRARY_PATH.
+	* Berkeley's libdb 3.1.17
 
+	  It is important to use *exactly* this version, and not a
+	  later one, to compile Evolution.  Please check the "Building
+	  Berkeley DB" section below for more information.
 
-DEPENDENCIES
-------------
+   	     ftp://ftp.ximian.com/pub/ximian-evolution-beta/source/
 
-In order to compile Evolution, you need all the GNOME 2.0 (or later)
-core libraries to be installed on your system.
+	* [Optional] Mozilla NSPR/NSS libraries
 
-Evolution also requires libgnomeprint and libgnomeprintui 2.2 (which
-are part of GNOME 2.2); so if you are compiling against a GNOME 2.0
-development platform, you will also need to install these libraries.
-If you are compiling against GNOME 2.2, you don't need to do so.
-libgnomeprint and libgnomeprintui are available from
-ftp://ftp.gnome.org/pub/GNOME/sources.
+	  These are needed if you want to compile Evolution with SSL
+	  support.
 
-In addition to the GNOME development libraries, Evolution depends on
-the following packages:
+	     http://www.mozilla.org/
 
- - gal - 1.99.2 or later
+          Many distributions ship these as Mozilla development
+          packages.
 
- - gtkhtml - 3.0.1 or later 
+	* [Optional] gnome-pilot 2.0 or later
 
- - libsoup - 1.99.12 or later
+	  This is only necessary if you want to be able to synchronize
+	  your Palm device with Evolution.
 
-All these libraries are available from
-ftp://ftp.gnome.or/pub/GNOME/sources , or can be fetched from GNOME
-CVS (just check out the trunk).
+	     ftp://ftp.gnome.org/pub/gnome/sources/gnome-pilot
+	     ftp://ftp.gnome.org/pub/gnome/sources/gnome-pilot-conduits
 
-Other dependencies:
+	* [Optional] gnome-spell 1.0.1 or later
 
- - Berkeley's libdb - 3.1.17
+	  This is only necessary if you want to have the spell
+	  checking functionality in Evolution's message composer.
 
-   db3 is available from http://www.sleepycat.com. Make sure to get
-   3.1.17, which isn't the latest version.
+	     ftp://ftp.gnome.org/pub/gnome/sources/gnome-spell
 
-     --- IMPORTANT WARNING ---
 
-     The on-disk format of DB files has been changing between versions
-     2, 3 and 4.  Also, because of the libdb API, there is no way to
-     easily handle the different formats from within the application.
-     For this reason, Evolution has chosen to use one specific version
-     of the library (version 3) and stick to it, so that users do not
-     need to convert their addressbook files to use them with
-     different version of Evolution.
+COMPILING BERKELEY DB
+---------------------
 
-     That's why Evolution REQUIRES libdb 3.1.17, and NO OTHER VERSION.
+    --- IMPORTANT WARNING ---
 
-     If you force the check to accept a version different from 3.1.17,
-     your binary of Evolution will be using a different format from
-     the chosen one; this means that it will not be able to read
-     addressbook databases created by other versions of Evolution
-     which were compiled in the standard way.  Also, we DO NOT
-     GUARRANTEE that Evolution will work with different versions of
-     libdb at all, even if it can be trivially made to compile against
-     them.
+    The on-disk format of DB files has been changing between versions 2, 3
+    and 4.  Also, because of the libdb API, there is no way to easily
+    handle the different formats from within the application.  For this
+    reason, Evolution has chosen to use one specific version of the
+    library (version 3) and stick to it, so that users do not need to
+    convert their addressbook files to use them with different version of
+    Evolution.
 
-     SPECIAL NOTE FOR BINARY PACKAGERS:
+    That's why Evolution REQUIRES libdb 3.1.17, and NO OTHER VERSION.
 
-     If you are making binary packages for end-users (e.g. if you are
-     a distribution vendor), please statically link Evolution to
-     Berkeley DB 3.1.17, as mandated by the configure.in check.  DO
-     NOT patch configure.in to work around the check.  Forcing the
-     check to link to a different version of the library will only
-     give headaches and pain to your users, who will see their
-     addressbook disappear and will complain to us (the Evolution
-     team) about losing their data.
+    If you force the check to accept a version different from 3.1.17, your
+    binary of Evolution will be using a different format from the chosen
+    one; this means that it will not be able to read addressbook databases
+    created by other versions of Evolution which were compiled in the
+    standard way.  Also, we DO NOT GUARRANTEE that Evolution will work
+    with different versions of libdb at all, even if it can be trivially
+    made to compile against them.
 
-     Besides, libdb will be linked statically, which means that your
-     distribution doesn't actually need to ship DB 3.1.17 itself
-     separately.
+    SPECIAL NOTE FOR BINARY PACKAGERS:
 
-     The Evolution team will be infinitely grateful for your
-     co-operation. Thanks.
+    If you are making binary packages for end-users (e.g. if you are a
+    distribution vendor), please statically link Evolution to Berkeley
+    DB 3.1.17, as mandated by the configure.in check.  DO NOT patch
+    configure.in to work around the check.  Forcing the check to link
+    to a different version of the library will only give headaches and
+    pain to your users, who will see their addressbook disappear and
+    will complain to us (the Evolution team) about losing their data.
 
+    Besides, libdb will be linked statically, which means that your
+    distribution doesn't actually need to ship DB 3.1.17 itself
+    separately.
 
-COMPILING BERKELEY DB
----------------------
+    The Evolution team will be infinitely grateful for your
+    co-operation.  Thanks!
 
-If you don't have 3.1.17 installed on your system or Evolution doesn't
-detect it for some reason, here is a way to get Evolution to link to
-it without messing up your system installation.
+If you don't have version 3.1.17 installed on your system or Evolution
+doesn't detect it for some reason, here is a way to get Evolution to
+link to it without messing up your system installation.
 
-  * Get the Sleepycat tarball from:
-
-      http://www.sleepycat.com/update/snapshot/db-3.1.17.tar.gz
-
-  * Install the content somewhere _other_ than the evolution source tree.
-     e.g: NOT evolution/db-3.1.17
+  * Install the content of the tarball somewhere *other* than the
+    evolution source tree, e.g: NOT evolution/db-3.1.17 .
 
   * Compile according to instructions, but installing into some custom
     prefix, for example:
 
       ../dist/configure --prefix=/home/user/berkeleydb-3.1.17
 
-  * Autogen Evolution specifying that it has to look for the DB
+  * Configure Evolution specifying that it has to look for the DB
     library there, for example:
 
-      ./autogen.sh --prefix=/opt/gnome
+      ./configure --prefix=/opt/gnome
       --with-db3-includes=/home/user/berkeleydb-3.1.17/include
       --with-db3-libs=/home/user/berkeleydb-3.1.17/lib
 
+Evolution links statically to the library, so after you have compiled
+Evolution you can remove the installed library from your system.
+
+
+CONFIGURING EVOLUTION
+---------------------
+
+First you have to decide whether you want to install Evolution (and
+its dependencies) into the same prefix as the rest of your GNOME
+install, or into a new prefix.
+
+Installing everything into the same prefix as the rest of your GNOME
+install will make it much easier to build and run programs, and easier
+to switch between using packages and building it yourself, but it may
+also make it harder to uninstall later.  Also, it increases the chance
+that something goes wrong and your GNOME installation gets ruined.
+
+If you want to install in a different prefix, you need to do the
+following things:
+
+	* Set the PKG_CONFIG_PATH environment variable to contain a
+          colon-separated list of all the pkg-config directories that
+          will be involved in the build.  This basically means a list
+          of $prefix/lib/pkgconfig directory names, where $prefix is
+          the prefix where a library is installed.
+
+	  For example, if you have GNOME installed in /usr and you
+          are installing Evolution and its dependencies in
+          /opt/evolution, you want to do something like the following
+          (assuming you are using Bash):
+
+	      export PKG_CONFIG_PATH=/usr/lib/pkgconfig:/opt/evolution/lib/pkgconfig
+
+	* Edit the bonobo-activation-config.xml file (which is
+          normally found in /etc/bonobo-activation/) to include the
+          location where you are installing Evolution.
+
+	  In the example given above (GNOME in /usr, Evolution and
+          dependencies in /opt/evolution), your
+          bonobo-activation-config.xml will have to look like this:
+
+	      <?xml version="1.0"?>
+	      <oafconfig>
+	        <searchpath>
+	          <item>/usr/lib/bonobo/servers</item>
+	          <item>/opt/evolution/lib/bonobo/servers</item>
+	        </searchpath>
+	      </oafconfig>
+
+	* Pass an appropriate --prefix parameter to the configure
+          scripts of Evolution and its dependencies, eg:
 
-COMPILING PALM PILOT SUPPORT
-----------------------------
+	      ./configure --prefix=/opt/evolution
 
-If you want support for PalmPilot syncing you will also need recent
-versions of:
+More information on how to use the configure script is available in
+the INSTALL file which is part of the Evolution tarball.
 
-1) pilot-link 
-http://www.pilot-link.org
 
-2) gnome-pilot
-http://www.eskil.org/gnome-pilot/
+OPTIONAL FEATURES
+-----------------
 
-3) evolution
-In your evolution source directory do ./autogen.sh --prefix=<evo-prefix> 
---with-pisock=<pilot-link-prefix> --enable-pilot-conduits=yes
-make
-make install
+Some optional features can be enabled at compilation time by passing
+appropriate flags to the configure script:
 
+	* GNOME Pilot support.
 
-SSL SUPPORT
------------
+	  Assuming you have installed gnome-pilot, add the following
+	  options:
 
-If you want SSL support (and someday S/MIME), you will also need
-mozilla-nspr and mozilla-nss, which can be found at
-http://www.mozilla.org.
+	    --with-pisock=<prefix> --enable-pilot-conduits=yes
 
-Once you have those libraries (and their respective includes)
-installed, in your evolution source directory do:
+	  Where <prefix> is the location where pilot-link (a package
+	  that gnome-pilot depends on) was installed.
 
-./autogen.sh --prefix=<evo-prefix> --with-nspr-includes=<nspr-includes-prefix>
---with-nspr-libs=<nspr-libs-prefix> --with-nss-includes=<nss-includes-prefix>
---with-nss-libs=<nss-libs-prefix>
+	* SSL support.
 
+	  Make sure you have Mozilla's NSS nad NSPR libraries
+	  installed and pass the following flag:
 
-NEWSGROUP (NNTP) SUPPORT
-------------------------
+	    --enable-nss
 
-Experimental support for NNTP is enabled if you use the --enable-nntp
-configure option, but it's currently unmaintained and highly unstable
-and experimental.