Revamped documentation structure and some doc fixes

`make` in the `docs` dir or `make doc` in the root dir will now
create the 1) man page and 2) the user documentation using sphinx
(requiring python-doctools, and sphinx).

The resulting user docs are in `docs/html`. You can also
only create the man pages with `make man` in the `docs` dir.

Also fixed all .rst conversion errors as requested by Gentoo downstream.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

docs/HACKING.rst

@@ -183,6 +183,5 @@ branch. ,-)
 API
 ===
 
-API is documented in the dev-doc-src directory using the sphinx tools (also used
-for python itself). This is a WIP. Contributions in this area would be very
+The API is documented in the user documentation in the docs/ directory and browsable at `<http://docs.offlineimap.org>`_. This is a WIP. Contributions in this area would be very
 appreciated.

docs/MANUAL.rst

@@ -2,17 +2,14 @@
  OfflineIMAP Manual
 ====================
 
+.. _OfflineIMAP: http://offlineimap.org
+
 --------------------------------------------------------
 Powerful IMAP/Maildir synchronization and reader support
 --------------------------------------------------------
 
 :Author: John Goerzen <jgoerzen@complete.org> & contributors
-:Date: 2011-01-15
-:Copyright: GPL v2
-:Manual section: 1
-
-.. TODO: :Manual group:
-
+:Date: 2012-02-23
 
 DESCRIPTION
 ===========
@@ -45,7 +42,7 @@ OfflineImap is well suited to be frequently invoked by cron jobs, or can run in
 
 The documentation is included in the git repository and can be created by 
 issueing `make dev-doc` in the `doc` folder (python-sphinx required), or it can
-be viewed online at `http://docs.offlineimap.org`_.
+be viewed online at http://docs.offlineimap.org.
 
 .. _configuration:
 
@@ -72,7 +69,7 @@ OPTIONS
 
 The command line options are described by issueing `offlineimap --help`.
 Details on their use can be found either in the sample offlineimap.conf file or
-in the user docs at `http://docs.offlineimap.org`_.
+in the user docs at http://docs.offlineimap.org.
 
 User Interfaces
 ===============
@@ -306,6 +303,8 @@ as Man-In-The-Middle attacks which cause you to connect to the wrong
 server and pretend to be your mail server. DO NOT RELY ON STARTTLS AS A
 SAFE CONNECTION GUARANTEEING THE AUTHENTICITY OF YOUR IMAP SERVER!
 
+.. _UNIX signals:
+
 UNIX Signals
 ============
 
@@ -445,7 +444,7 @@ and Sent which should keep the same name::
 
 Synchronizing 2 IMAP accounts to local Maildirs that are "next to each
 other", so that mutt can work on both. Full email setup described by
-Thomas Kahle at `http://dev.gentoo.org/~tomka/mail.html`_
+Thomas Kahle at `<http://dev.gentoo.org/~tomka/mail.html>`_
 
 offlineimap.conf::
 
@@ -507,7 +506,7 @@ purposes: Fetching passwords from the gnome-keyring and translating
 folder names on the server to local foldernames.  An example
 implementation of get_username and get_password showing how to query
 gnome-keyring is contained in
-`http://dev.gentoo.org/~tomka/mail-setup.tar.bz2`_ The folderfilter is
+`<http://dev.gentoo.org/~tomka/mail-setup.tar.bz2>`_ The folderfilter is
 a lambda term that, well, filters which folders to get. The function
 `oimaptransfolder_acc2` translates remote folders into local folders
 with a very simple logic. The `INBOX` folder will have the same name

docs/Makefile

@@ -9,7 +9,7 @@ RST2HTML=`type rst2html >/dev/null 2>&1 && echo rst2html || echo rst2html.py`
 RST2MAN=`type rst2man >/dev/null 2>&1 && echo rst2man || echo rst2man.py`
 SPHINXBUILD = sphinx-build
 
-all: html dev-doc
+all: man doc
 
 html: $(HTML_TARGETS)
 
@@ -22,12 +22,12 @@ offlineimap.1: MANUAL.rst
 	$(RST2MAN) MANUAL.rst offlineimap.1
 	cp -f offlineimap.1 ..
 
-dev-doc:
-	$(SPHINXBUILD) -b html -d dev-doc/doctrees dev-doc-src dev-doc/html
+doc:
+	$(SPHINXBUILD) -b html -d html/doctrees doc-src html
 
 clean:
 	$(RM) -f $(HTML_TARGETS)
 	$(RM) -f offlineimap.1 ../offlineimap.1
-	$(RM) -rf dev-doc/*
+	$(RM) -rf html/*
 
-.PHONY: dev-doc
+.PHONY: clean doc

docs/dev-doc-src/FAQ.rst

@@ -1 +0,0 @@
-../FAQ.rst

docs/doc-src/FAQ.rst

@@ -203,9 +203,10 @@ How is OfflineIMAP conformance?
 Can I force OfflineIMAP to sync a folder right now?
 ---------------------------------------------------
 
-Yes, 
-  1) if you use the `Blinkenlights` UI.  That UI shows the active accounts
-as follows::
+Yes:
+
+1) if you use the `Blinkenlights` UI.  That UI shows the active
+accounts as follows::
 
    4: [active]      *Control: .
    3: [  4:36]      personal:
@@ -216,8 +217,9 @@ as follows::
    resync that account immediately.  This will be ignored if a resync is
    already in progress for that account.
 
-  2) while in sleep mode, you can also send a SIGUSR1. See the `Signals
-    on UNIX`_ section in the MANUAL for details.
+2) while in sleep mode, you can also send a SIGUSR1. See the :ref:`UNIX
+   signals` section in the MANUAL for details.
+
 
 I get a "Mailbox already exists" error
 --------------------------------------
@@ -291,14 +293,17 @@ certificates chain) in PEM format.  (See the documentation of
 `ssl.wrap_socket`_'s `certfile` parameter for the gory details.)  You can use either openssl or gnutls to create a certificate file in the required format.
 
 #. via openssl::
+
     openssl s_client -CApath /etc/ssl/certs -connect ${hostname}:imaps -showcerts \
        | perl -ne 'print if /BEGIN/../END/; print STDERR if /return/' > $sslcacertfile
     ^D
 
+
 #. via gnutls::
     gnutls-cli --print-cert -p imaps ${host} </dev/null | sed -n \
     |     '/^-----BEGIN CERT/,/^-----END CERT/p' > $sslcacertfile
 
+
 The path `/etc/ssl/certs` is not standardized; your system may store
 SSL certificates elsewhere.  (On some systems it may be in
 `/usr/local/share/certs/`.)

docs/doc-src/features.rst

@@ -0,0 +1,66 @@
+Description
+===========
+
+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.
+
+OfflineIMAP works on pretty much any POSIX operating system, such as Linux, BSD
+operating systems, MacOS X, Solaris, etc.
+
+OfflineIMAP is a Free Software project licensed under the GNU General Public
+License. You can download it for free, and you can modify it. In fact, you are
+encouraged to contribute to OfflineIMAP, and doing so is fast and easy.
+
+OfflineIMAP is FAST; 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.
+
+OfflineIMAP is FLEXIBLE; 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.
+
+OfflineIMAP is SAFE; 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.
+
+.. note: OfflineImap was written by John Goerzen, who retired from
+    maintaining.  It is now maintained by Nicolas Sebrecht & Sebastian
+    Spaeth at https://github.com/spaetz/offlineimap. Thanks to John
+    for his great job and to have share this project with us.
+
+Method of Operation
+===================
+
+OfflineIMAP traditionally 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.
+
+With OfflineIMAP 4.0, a powerful new ability has been introduced ― the program
+can now synchronize two IMAP servers with each other, with no need to have a
+Maildir layer in-between.  Many people use this if they use a mail reader on
+their local machine that does not support Maildirs.  People may install an IMAP
+server on their local machine, and point both OfflineIMAP and their mail reader
+of choice at it.  This is often preferable to the mail reader's own IMAP support
+since OfflineIMAP supports many features (offline reading, for one) that most
+IMAP-aware readers don't.  However, this feature is not as time-tested as
+traditional syncing, so my advice is to stick with normal methods of operation
+for the time being.

docs/doc-src/index.rst

@@ -15,6 +15,7 @@ If you just want to get started with minimal fuzz, have a look at our `online qu
 More information on specific topics can be found on the following pages:
 
 **User documentation**
+  * :doc:`Overview and features <features>`
   * :doc:`installation/uninstall <INSTALL>`
   * :doc:`user manual/Configuration <MANUAL>`
   * :doc:`Folder filtering & name transformation guide <nametrans>`
@@ -28,6 +29,7 @@ More information on specific topics can be found on the following pages:
 .. toctree::
    :hidden:
 
+   features
    INSTALL
    MANUAL
    nametrans

docs/doc-src/nametrans.rst

@@ -48,7 +48,7 @@ at the end when required by Python syntax)  For instance::
 Usually it suffices to put a `folderfilter`_ setting in the remote repository section. You might want to put a folderfilter option on the local repository if you want to prevent some folders on the local repository to be created on the remote one. (Even in this case, folder filters on the remote repository will prevent that)
 
 folderincludes
-^^^^^^^^^^^^^^
+--------------
 
 You can specify `folderincludes`_ to manually include additional folders to be synced, even if they had been filtered out by a folderfilter setting. `folderincludes`_ should return a Python list.
 
@@ -92,8 +92,9 @@ locally?  Try this::
     this rule will result in undefined behavior. See also *Sharing a
     maildir with multiple IMAP servers* in the :ref:`pitfalls` section.
 
+
 Reverse nametrans
-^^^^^^^^^^^^^^^^^^
++++++++++++++++++
 
 Since 6.4.0, OfflineImap supports the creation of folders on the remote repository and that complicates things. Previously, only one nametrans setting on the remote repository was needed and that transformed a remote to a local name. However, nametrans transformations are one-way, and OfflineImap has no way using those rules on the remote repository to back local names to remote names.
 
@@ -161,9 +162,10 @@ What folder separators do I need to use in nametrans rules?
   Maildir using the default folder separator '.' which do I need to use
   in nametrans rules?::
 
-  nametrans = lambda f: "INBOX/" + f
-or::
-  nametrans = lambda f: "INBOX." + f
+      nametrans = lambda f: "INBOX/" + f
+
+  or::
+      nametrans = lambda f: "INBOX." + f
 
 **A:** Generally use the folder separator as defined in the repository
   you write the nametrans rule for. That is, use '/' in the above