Improve documentation
Improve wording, and integrate the MANUAL and INSTALL and FAQ documents into our complete user manual that is hosted online. Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>
This commit is contained in:
Sebastian Spaeth
170
docs/INSTALL.rst
170
docs/INSTALL.rst
@@ -1,81 +1,90 @@
|
||||
.. -*- coding: utf-8 -*-
|
||||
|
||||
.. _OfflineIMAP: https://github.com/nicolas33/offlineimap
|
||||
|
||||
.. contents::
|
||||
.. sectnum::
|
||||
|
||||
=============
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
In order to use `OfflineIMAP`_, you need to have these conditions satisfied:
|
||||
|
||||
1. Your mail server must support IMAP. Most Internet Service Providers and
|
||||
corporate networks do, and most operating systems have an IMAP implementation
|
||||
readily available. A special Gmail mailbox type is available to interface with
|
||||
Gmail's IMAP front-end.
|
||||
|
||||
2. You must have Python version 2.6 or above installed. If you are running on
|
||||
Debian GNU/Linux, this requirement will automatically be taken care of for you.
|
||||
If you do not have Python already, check with your system administrator or
|
||||
operating system vendor; or, download it from the Python website. If you intend
|
||||
to use the SSL interface, your Python must have been built with SSL support.
|
||||
|
||||
3. Have a mail reader that supports the Maildir mailbox format. Most modern
|
||||
mail readers have this support built-in, so you can choose from a wide variety
|
||||
of mail servers. This format is also known as the "qmail" format, so any mail
|
||||
reader compatible with it will work with `OfflineIMAP`_. If you do not have a
|
||||
mail reader that supports Maildir, you can often install a local IMAP server and
|
||||
point both `OfflineIMAP`_ and your mail reader at it.
|
||||
|
||||
.. _OfflineIMAP: https://github.com/spaetz/offlineimap
|
||||
.. _OLI_git_repo: git://github.com/spaetz/offlineimap.git
|
||||
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
You have three options:
|
||||
.. contents::
|
||||
.. .. sectnum::
|
||||
|
||||
1. a system-wide installation with Debian
|
||||
2. a system-wide installation with other systems
|
||||
3. a single-user installation. You can checkout the latest version of
|
||||
`OfflineIMAP`_ from official `OfflineIMAP`_ repository.
|
||||
-------------
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
In order to use `OfflineIMAP`_, you need to have these conditions satisfied:
|
||||
|
||||
1. Your mail server must support IMAP. Mail access via POP is not
|
||||
supported. A special Gmail mailbox type is available to interface
|
||||
with Gmail's IMAP front-end, although Gmail has a very peculiar and
|
||||
non-standard implementation of its IMAP interface.
|
||||
|
||||
2. You must have Python version 2.6 or above installed. If you are
|
||||
running on Debian GNU/Linux, this requirement will automatically be
|
||||
taken care of for you. If you intend to use the SSL interface,
|
||||
your Python must have been built with SSL support.
|
||||
|
||||
3. If you use OfflineImap as an IMAP<->Maildir synchronizer, you will
|
||||
obviously need to have a mail reader that supports the Maildir
|
||||
mailbox format. Most modern mail readers have this support built-in,
|
||||
so you can choose from a wide variety of mail servers. This format
|
||||
is also known as the "qmail" format, so any mail reader compatible
|
||||
with it will work with `OfflineIMAP`_.
|
||||
|
||||
|
||||
System-Wide Installation, Debian
|
||||
================================
|
||||
------------
|
||||
Installation
|
||||
------------
|
||||
|
||||
If you are tracking Debian unstable, you may install `OfflineIMAP`_ by simply
|
||||
running the following command as root::
|
||||
Installing OfflineImap should usually be quite easy, as you can simply unpack and run OfflineImap in place if you wish to do so. There are a number of options though:
|
||||
|
||||
apt-get install offlineimap
|
||||
#. system-wide :ref:`installation via your distribution package manager <inst_pkg_man>`
|
||||
#. system-wide or single user :ref:`installation from the source package <inst_src_tar>`
|
||||
#. system-wide or single user :ref:`installation from a git checkout <inst_git>`
|
||||
|
||||
If you are not tracking Debian unstable, download the Debian `.deb` package from
|
||||
the `OfflineIMAP`_ website and then run ``dpkg -i`` to install the downloaded
|
||||
package. Then, skip to below. You will type offlineimap to invoke the
|
||||
program.
|
||||
Having installed OfflineImap, you will need to configure it, to be actually useful. Please check the :ref:`Configuration` section in the :doc:`MANUAL` for more information on the configuration step.
|
||||
|
||||
System-Wide Installation, Other
|
||||
===============================
|
||||
.. _inst_pkg_man:
|
||||
|
||||
Check your distribution packaging tool, OfflineIMAP may already be packaged for
|
||||
you.
|
||||
System-Wide Installation via distribution
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
The easiest way to install OfflineIMAP is via your distribution's package manager. OfflineImap is available under the name `offlineimap` in most Linux and BSD distributions.
|
||||
|
||||
System-Wide Installation, From source
|
||||
=====================================
|
||||
|
||||
Get your own copy of the official git repository at `OfflineIMAP`_::
|
||||
.. _inst_src_tar:
|
||||
|
||||
git clone git://github.com/nicolas33/offlineimap.git
|
||||
Installation from source package
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Download the latest source archive from our `download page <https://github.com/spaetz/offlineimap/downloads>`_. Simply click the "Download as .zip" or "Download as .tar.gz" buttons to get the latest "stable" code from the master branch. If you prefer command line, you will want to use:
|
||||
wget https://github.com/spaetz/offlineimap/tarball/master
|
||||
|
||||
This will download all the sources with history. By default, git set up the
|
||||
local master branch up which is most likely what you want. If not, you can
|
||||
checkout a particular release::
|
||||
Unpack and continue with the :ref:`system-wide installation <system_wide_inst>` or the :ref:`single-user installation <single_user_inst>` section.
|
||||
|
||||
|
||||
.. _inst_git:
|
||||
|
||||
Installation from git checkout
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Get your own copy of the `official git repository <OLI_git_repo>`_ at `OfflineIMAP`_::
|
||||
|
||||
git clone git://github.com/spaetz/offlineimap.git
|
||||
|
||||
This will download the source with history. By default, git sets up the
|
||||
`master` branch up, which is most likely what you want. If not, you can
|
||||
checkout a particular release like this::
|
||||
|
||||
cd offlineimap
|
||||
git checkout -b local_version v6.3.3
|
||||
git checkout v6.5.2.1
|
||||
|
||||
The latter creates a local branch called "local_version" of the v6.3.3 release.
|
||||
You have now a source tree available and proceed with either the :ref:`system-wide installation <system_wide_inst>` or the :ref:`single-user installation <single_user_inst>`.
|
||||
|
||||
|
||||
.. _system_wide_inst:
|
||||
|
||||
System-wide installation
|
||||
++++++++++++++++++++++++
|
||||
|
||||
Then run these commands, to build the python package::
|
||||
|
||||
@@ -86,47 +95,38 @@ Finally, install the program (as root)::
|
||||
|
||||
python setup.py install
|
||||
|
||||
Next, proceed to below. You will type offlineimap to invoke the program.
|
||||
Next, proceed to below. You tofflineimap to invoke the program.
|
||||
|
||||
Single-Account Installation
|
||||
===========================
|
||||
|
||||
.. _single_user_inst:
|
||||
|
||||
Single-user installation
|
||||
++++++++++++++++++++++++
|
||||
|
||||
Download the git repository as described above. Instead of installing the
|
||||
program as root, you type `./offlineimap.py`; there is no installation step
|
||||
necessary.
|
||||
|
||||
=============
|
||||
Configuration
|
||||
=============
|
||||
|
||||
`OfflineIMAP`_ is regulated by a configuration file that is normally stored in
|
||||
`~/.offlineimaprc`. `OfflineIMAP`_ ships with a file named `offlineimap.conf`
|
||||
that you should copy to that location and then edit. This file is vital to
|
||||
proper operation of the system; it sets everything you need to run
|
||||
`OfflineIMAP`_. Full documentation for the configuration file is included
|
||||
within the sample file.
|
||||
|
||||
|
||||
`OfflineIMAP`_ also ships a file named `offlineimap.conf.minimal` that you can
|
||||
also try. It's useful if you want to get started with the most basic feature
|
||||
set, and you can read about other features later with `offlineimap.conf`.
|
||||
|
||||
|
||||
===============
|
||||
---------
|
||||
Uninstall
|
||||
===============
|
||||
---------
|
||||
|
||||
If you installed a system-wide installation via "python setup.py
|
||||
install", there are a few files to purge to uninstall it again. I assume
|
||||
that /usr/local is the standard prefix that your system and you use
|
||||
python 2.7. Adapt to your system. In that case you need to:
|
||||
install", there are a few files to purge to cleanly uninstall
|
||||
`OfflineImap`_ again. Assuming that `/usr/local` is the standard prefix of
|
||||
your system and that you use python 2.7, you need to:
|
||||
|
||||
#) Delete the OfflineImap installation itself::
|
||||
|
||||
1) Delete:
|
||||
/usr/local/lib/python2.7/dist-packages/offlineimap-6.4.4.egg-info
|
||||
/usr/local/lib/python2.7/dist-packages/offlineimap
|
||||
|
||||
2) Delete the cache at (default location) ~/.offlineimap
|
||||
Delete your manually created (default loc) ~/.offlineimaprc
|
||||
In case, you did the single-user installation, simply delete your
|
||||
offlineimap directory.
|
||||
|
||||
#) Delete all files that OfflineImap creates during its operation.
|
||||
- The cache at (default location) ~/.offlineimap
|
||||
- Your manually created (default loc) ~/.offlineimaprc
|
||||
(It is possible that you created those in different spots)
|
||||
|
||||
That's it. Have fun without OfflineImap.
|
||||
|
||||
Reference in New Issue
Block a user