Balsa E-Mail Client 2.5.x
=========================

See ChangeLog for the list of the recent changes and NEWS for highlights.

Copyright (C) 1997-2016 Stuart Parmenter and others

See 'COPYING' for licence information.  Please note linking against
OpenSSL libraries is explicitly allowed.

See 'AUTHORS' for a list of contributors


Authors:
-------
	See AUTHORS


Website:
-------
	http://pawsa.fedorapeople.org/balsa/


Description:
-----------
 	Balsa is an e-mail reader.  This client is part of the GNOME
desktop environment.  It supports local mailboxes, POP3 and IMAP.


Configuration:
-------------
	Balsa has a lot of options to its configure script; you
should run './configure --help' to get an idea of them. More
complete descriptions are here.

Basically, Balsa requires
- glib-2.0 >= 2.40.0
- gtk+-3.0 >= 3.10.0
- gmime-2.6
- gio-2.0
- gthread-2.0

--disable-more-warnings
	Balsa by default is very sensitive to compilation warnings
which often mean simply programming or configuration errors. If you
are sure this is not the case, or you cannot change your system setup
use this option to compile the code and hope for the best. 
(some Solaris setups require this).

--with-gnome
	Use GNOME libraries.  FIXME - what do we actually require?

--with-libsecret
	Link to libsecret instead of gnome-keyring.

--with-gpgme[=gpgme-config]
	Use GPGME library for GnuPG message signing and encryption.
The path of the gpgme-config tool must be specified only if it is
installed in an uncommon place.  See the (rather outdated) web page
http://home.arcor.de/dralbrecht.dress/balsa/UsingGnuPG.html#FAQ
for more details.
Note: requires GpgME version >= 1.5.0

--with-gss[=/usr/kerberos]
	This enables GSSAPI Kerberos based authentication scheme. 
Specify the kerberos directory as the argument.

--with-html-widget=(no|gtkhtml4|webkit|webkit2)
        Choose preferred HTML renderer library.  Note that webkit is
not actively supported any more and thus not recommended.
When using webkit or webkit2, in order to quote html-only messages
it is recommended to install a html-to-text conversion tool.  Supported
tools are python-html2text, html2markdown, html2markdown.py2,
html2markdown.py3 and html2text.

--with-spell-checker=(no|gtkspell|gspell)
	Select the external spell checker for the message composer.

--with-ldap
        Use ldap libraries for a read-only address book. The read/write
address book is in the works but needs some finishing touches.

--with-sqlite
	Use SQLite for GPE address books.

--with-rubrica
	Use libxml2 for Rubrica2 address book support.

--with-osmo
	Enable experimental support for read-only DBus access to the Osmo
	contacts.  Note that Osmo svn rev. 1099 or later is required.

--with-canberra
	Use libcanberra-gtk3 for filter sounds.

--with-compface
	Use Compface for rendering X-Face format thumbnails of email
authors in a mail header.

--with-gtksourceview
	Use GtkSourceview for highlighting structured phrases in
messages, and for syntax highlighting in attachments.

--with-libnotify
	Use libnotify for sending desktop notifications.


Libraries:
---------
Balsa needs the aspell spell checking libraries.

	Make sure you have libtool installed (if you get some error 
messages during compilation or when running precompiled binaries saying that
libtdl is missing it means you need to install just that package).


Website:
--------
	Balsa source comes with the Balsa website in the
directory for balsa/website/. Read balsa/website/README and
balsa/website/INSTALL for more information. If you retrieved
this source as a tarball or RPM or deb, this directory 
may not exist. To get it, you need to go to ....


Balsa GIT:
----------
	Balsa is hosted on the Gnome git servers. To get
the latest source, get the module 'balsa' from
https://wiki.gnome.org/Git/Developers


Specifying the SMTP Server:
---------------------------

Remote SMTP Server:
	Specify the domain name and optionally the port for of the SMTP
	server you use for submitting mail.  Please note that the
	default port number is 587 or 465 for SMTPS (see below).  The
	syntax is hostname[:port].  Port can be a decimal number or the
	name of the service as specified in /etc/services.  Typically
	you can just set this to localhost:25.

Security:
	Specify the security level.  For an ISP, this is typically "SMTP
	over SSL (SMTPS)" (default port 465) or "TLS required" (default
	587, but many ISP's listen on port 25).  If your ISP does not
	support either, choose a different ISP.  For a local connection
	(i.e. to localhost), an unencrypted connection is fine.
	Note that Balsa will not use the PLAIN or LOGIN authentication
	mechanisms if the connection is not encrypted.

User:
	If the remote SMTP server requires authentication, enter your
	user name here.  Note that the exact format depends on the MTA
	in use.  For example, some systems expect a user name, others
	may require an email address.

Pass Phrase:
	If the remote SMTP server requires authentication, enter your
	pass phrase here.  Some systems refer to the pass phrase as a
	password.  Limitations on the length of the pass phrase depend
	on the SMTP server.

Client Certificate and Pass Phrase:
	Few ISP's hand over a client certificate Balsa must present when
	connecting.  Choose the PEM-encoded certificate file and -if it
	has an encrypted private key- set the key's pass phrase.

Split large messages:
	Some ISP's impose a message size limit.  In this case, enter the
	appropriate value here.


Gtk+-3 Dialog Header Bars:
--------------------------
	If the Gtk+ version is >= 3.12.0, Balsa uses the new Gtk header
bars instead of the traditional action areas.  As this may look ugly when
using other desktop environments than Gnome (e.g. XFCE), Balsa can be
switched to the old style by defining the environment variable

	BALSA_DIALOG_HEADERBAR=0


Help System:
------------
	In order to compile the help files, you need to have the
Mallard documentation system. Very good documentation
can be found at: http://projectmallard.org/


Balsa as mailto protocol handler:
---------------------------------
	Balsa can be used as mailto protocol handler; by default, a
        desktop file that declares this capability is installed.


Mailbox locking:
----------------
    Balsa uses flock+dotfile for mailbox file locking. It does not
    use fcntl (although it can be enabled) since this locking method is
    very fragile and often not portable (see for example
    http://www.washington.edu/pine/tech-notes/low-level.html#locking).

    Make sure that your spool directory has drwxrwxrwt (01777) access
    privileges. Presently, dotfile locking requires this unconditionally
    In the future, we may relax this requirement and will allow you to
    shoot yourself in your leg.

POP3 mail filtering:
-------------------

    When the respective POP3 'mailbox' has the 'filter' box checked, the
    downloaded mail is passed on to procmail which will use
    ~/.procmailrc file as its configuration, so you can share it between
    balsa and fetchmail and get consistent behavior no matter you use
    balsa or fetchmail for downloading.

Simple example ~/.procmailrc file:
--------- cut here ----------------
:0H:
* ^Subject:.*balsa
mail/balsa-related-mail
--------- cut here ----------------

It is recommended to read procmail(1) and procmailrc(1) for more
real-life examples and syntax explanation.


Alternative browsers:
--------------------
Start from checking settings in your Gnome Control Center. If your
version of gnomecc does provide option to change the default browser,
you will need to create a file named gnome-moz-remote in your .gnome
directory. It should contain the following:

[Mozilla]
filename=/path/to/your/browser


Reporting Bugs:
--------------
	See http://balsa.gnome.org/bugs.html for instructions.
        Patches are welcome.


Known issues:
------------

*	When dotlocking is not possible (Wrong access privilieges for
	the mailbox file) balsa will open mailbox for reading only.
	Verify that balsa can create dot file in the mailbox directory.
	Recommended access privileges to /var/spool/mail are rwxrwxrwxt (01777)

