docker-offlineimap/offlineimap/head/offlineimap.sgml

<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
  <!ENTITY OfflineIMAP "<application>OfflineIMAP</application>">
]>
<!-- -*- DocBook -*- -->
<!--      "file:///usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd"> -->

<reference>
  <title>OfflineIMAP Manual</title>

  <refentry>
    <refentryinfo>
      <address><email>jgoerzen@complete.org</email></address>
      <author><firstname>John</firstname><surname>Goerzen</surname></author>
      <date>$Date$</date>
    </refentryinfo>

    <refmeta>
      <refentrytitle>offlineimap</refentrytitle>
      <manvolnum>1</manvolnum>
      <refmiscinfo>John Goerzen</refmiscinfo>
    </refmeta>

    <refnamediv>
      <refname>OfflineIMAP</refname>
      <refpurpose>Powerful IMAP/Maildir synchronization
	and reader support</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <cmdsynopsis>
	<command>offlineimap</command>
	<arg>-1</arg>
	<arg>-P <replaceable>profiledir</replaceable></arg>
	<arg>-a <replaceable>accountlist</replaceable></arg>
	<arg>-c <replaceable>configfile</replaceable></arg>
	<arg>-d <replaceable>debugtype[,...]</replaceable></arg>
	<arg>-o</arg>
	<arg>-u <replaceable>interface</replaceable></arg>
      </cmdsynopsis>
      <cmdsynopsis>
	<command>offlineimap</command>
	<group choice="plain"><arg>-h</arg><arg>--help</arg></group>
      </cmdsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para>&OfflineIMAP; is  a  tool  to  simplify  your  e-mail
	reading.  With &OfflineIMAP;, you can read the same mailbox
	from multiple computers.  You get a current copy of your
	messages on each computer, and changes you make one place will be
	visible on all other systems.  For instance, you can delete a message
	on your home computer, and it will appear deleted on your work
	computer as well.  &OfflineIMAP; is also useful if you want to
	use a mail reader that does not have IMAP support, has poor IMAP
	support, or does not provide disconnected operation.
      </para>

      <para>&OfflineIMAP; is <emphasis>FAST</emphasis>; it synchronizes
        my two accounts with over 50 folders in 3 seconds.  Other
        similar tools might take over a minute, and achieve a
        less-reliable result.  Some mail readers can take over 10
        minutes to do the same thing, and some don't even support it
        at all.  Unlike other mail tools, &OfflineIMAP; features a
        multi-threaded synchronization algorithm that can dramatically
        speed up performance in many situations by synchronizing
        several different things simultaneously.
      </para>

      <para>&OfflineIMAP; is <emphasis>FLEXIBLE</emphasis>; you can
        customize which folders are synced via regular expressions,
        lists, or Python expressions; a versatile and comprehensive
        configuration file is used to control behavior; two user
        interfaces are built-in; fine-tuning of synchronization
        performance is possible; internal or external automation is
        supported; SSL and PREAUTH tunnels are both supported; offline
        (or "unplugged") reading is supported; and esoteric IMAP
        features are supported to ensure compatibility with the widest
        variety of IMAP servers.
      </para>

      <para>&OfflineIMAP; is <emphasis>SAFE</emphasis>; it uses an
        algorithm designed to prevent mail loss at all costs.  Because
        of the design of this algorithm, even programming errors
        should not result in loss of mail.  I am so confident in the
        algorithm that I use my own personal and work accounts for
        testing of &OfflineIMAP; pre-release, development, and beta
	releases.  Of course, legally speaking, &OfflineIMAP; comes
        with no warranty, so I am not responsible if this turns out
        to be wrong.
      </para>

      <refsect2>
        <title>Method of Operation</title>
       
        <para>&OfflineIMAP; operates by maintaining a hierarchy of
	  mail folders in Maildir format locally.  Your own mail
	  reader will read mail from this tree, and need never know
	  that the mail comes from IMAP.  &OfflineIMAP; will detect
	  changes to the mail folders on your IMAP server and your own
	  computer and bi-directionally synchronize them, copying,
	  marking, and deleting messages as necessary.
        </para>
      </refsect2>
    </refsect1>
    
    <refsect1>
      <title>Quick Start</title>
      <para>If you have already installed &OfflineIMAP; system-wide,
        or your system adminstrator has done that for you, your task
        for setting up &OfflineIMAP; for the first time is quite
        simple.  You just need to set up your configuration file, make
        your folder directory, and run it!
      </para>

	<para>You can quickly set up your configuration file.  The distribution
	  includes a file <filename>offlineimap.conf.minimal</filename>
	  (Debian users
	  may find this at
          <filename>/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal</filename>) that is a basic example of setting of &OfflineIMAP;.  You can
	  simply copy this file into your home directory and name it
	  <filename>.offlineimaprc</filename> (note the leading period).  A
	  command such as <command>cp offlineimap.conf.minimal ~/.offlineimaprc</command> will do it.  Or, if you prefer, you can just copy this text to
	  <filename>~/.offlineimaprc</filename>:
	</para>

	<PROGRAMLISTING>[general]
accounts = Test

[Test]
localfolders = ~/Test
remotehost = examplehost
remoteuser = jgoerzen
</PROGRAMLISTING>

        <para>Now, edit the <filename>~/.offlineimaprc</filename> file with
	  your favorite editor.  All you have to do is specify a directory
	  for your folders to be in (on the <property>localfolders</property>
	  line), the host name of your IMAP server (on the
	  <property>remotehost</property> line), and your login name on
	  the remote (on the <property>remoteuser</property> line).  That's
	  it!</para>

	<para>To run &OfflineIMAP;, you just have to say
	  <command>offlineimap</command> -- it will fire up, ask you for
	  a login password if necessary, synchronize your folders, and exit.
	  See?  You can just throw away the rest of this finely-crafted,
	  perfectly-honed manual!  Of course, if you want to see how you can
	  make &OfflineIMAP; FIVE TIMES FASTER FOR JUST $19.95 (err, well,
	  $0), you have to read on!
	</para>

    </refsect1>

    <refsect1>
      <title>Installation</title>

      <para>If you are reading this document via the "man" command, it is
	likely
	that you have no installation tasks to perform; your system
	administrator has already installed it.  If you need to install it
	yourself, you have three options: a system-wide installation with
	Debian, system-wide installation with other systems, and a single-user
	installation.  You can download the latest version of &OfflineIMAP; from
	<ulink url="http://quux.org/devel/offlineimap/">the &OfflineIMAP;
	website</ulink>.
      </para>

      <refsect2>
	<title>Prerequisites</title>

	<para>In order to use &OfflineIMAP;, you need to have these conditions
	  satisfied:
	</para>

	<itemizedlist>
	  <listitem>
	    <para>Your mail server must support IMAP.  Most Internet Service
	      Providers
	      and corporate networks do, and most operating systems
	      have an IMAP
	      implementation readily available.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      You must have Python version 2.2.1 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
	      <ulink url="http://www.python.org/">the Python website</ulink>.
	      If you intend to use the Tk interface, you must have Tkinter
		(python-tk) installed.  If you intend to use the SSL interface, your
		Python must have been built with SSL support.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      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;.
	</itemizedlist>
      </refsect2>

      <refsect2>
	<title>System-Wide Installation, Debian</title>
	<para>
	  If you are tracking Debian unstable, you may install
	  &OfflineIMAP; by simply running the following command as root:
	</para>
	<para>
	  <command>apt-get install offlineimap</command>
	</para>
	<para>
	  If you are not tracking Debian unstable, download the Debian .deb
	  package from the <ulink url="http://quux.org/devel/offlineimap/">&OfflineIMAP; website</ulink>
	  and then run <command>dpkg -i</command> to install the downloaded
	  package.  Then, skip to <xref linkend="configuration" endterm="configuration-title"> below.  You will type <command>offlineimap</command> to
	  invoke the program.
	</para>
      </refsect2>

      <refsect2>
	<title>System-Wide Installation, Other</title>
	<para>
	  Download the tar.gz version of the package from the
	  <ulink url="http://quux.org/devel/offlineimap/">website</ulink>.
	  Then run
	  these commands, making sure that you are the "root" user first:
	</para>

	<ProgramListing>tar -zxvf offlineimap_x.y.z.tar.gz
cd offlineimap-x.y.z
python2.2 setup.py install</ProgramListing>
	<para>On some systems, you will need to use
	  <command>python</command> instead of <command>python2.2</command>.
	  Next, proceed to <xref linkend="configuration" endterm="configuration-title"> below.  You will type <command>offlineimap</command> to
	  invoke the program.
	</para>
      </refsect2>

      <refsect2>
	<title>Single-Account Installation</title>
	<para>
	  Download the tar.gz version of the package from the
	  <ulink url="http://quux.org/devel/offlineimap/">website</ulink>.
	  Then run these commands:
	</para>

	<ProgramListing>tar -zxvf offlineimap_x.y.z.tar.gz
cd offlineimap-x.y.z</ProgramListing>

	<para>When you want to run &OfflineIMAP;, you will issue the
	  <command>cd</command> command as above and then type
	  <command>./offlineimap.py</command>; there is no installation
	  step necessary.
	</para>
      </refsect2>
    </refsect1>

    <refsect1 id="configuration">
      <title id="configuration-title">Configruation</title>
      <para>
	&OfflineIMAP; is regulated by a configuration file that is normally 
	stored in <filename>~/.offlineimaprc</filename>.  &OfflineIMAP;
	ships with a file named <filename>offlineimap.conf</filename>
	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.
      </para>
      <para>
	&OfflineIMAP; also ships a file named
	<filename>offlineimap.conf.minimal</filename> 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 <filename>offlineimap.conf</filename>.
      </para>
    </refsect1>



    <refsect1>
      <title>See Also</title>
      <para>This is also a test.  Foo bar.</para>
    </refsect1>
  </refentry>
</reference>