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>
This commit is contained in:
Sebastian Spaeth
parent
2800a71a28
commit
74b133c500
3
.gitignore
vendored
3
.gitignore
vendored
@ -1,9 +1,10 @@
|
||||
# Generated files
|
||||
/docs/dev-doc/
|
||||
/docs/html/
|
||||
/build/
|
||||
*.pyc
|
||||
offlineimap.1
|
||||
# backups
|
||||
.*.swp
|
||||
.*.swo
|
||||
*.html
|
||||
*~
|
||||
|
||||
@ -33,5 +33,11 @@ Changes
|
||||
* Revert "* Slight performance enhancement uploading mails to an IMAP
|
||||
server in the common case." It might have led to instabilities.
|
||||
|
||||
* Revamped documentation structure. `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.
|
||||
|
||||
Bug Fixes
|
||||
---------
|
||||
|
||||
1
Makefile
1
Makefile
@ -46,7 +46,6 @@ man:
|
||||
doc:
|
||||
@$(MAKE) -C docs
|
||||
$(RST2HTML) README.rst readme.html
|
||||
$(RST2HTML) SubmittingPatches.rst SubmittingPatches.html
|
||||
$(RST2HTML) Changelog.rst Changelog.html
|
||||
|
||||
targz: ../$(TARGZ)
|
||||
|
||||
120
README.rst
120
README.rst
@ -1,26 +1,13 @@
|
||||
.. -*- coding: utf-8 -*-
|
||||
|
||||
.. _mailing list: http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project
|
||||
|
||||
======
|
||||
README
|
||||
======
|
||||
|
||||
.. contents::
|
||||
.. sectnum::
|
||||
|
||||
|
||||
Description
|
||||
===========
|
||||
|
||||
Welcome to the official OfflineIMAP project.
|
||||
|
||||
*NOTICE:* this software was written by John Goerzen, who retired from
|
||||
maintaining. It is now maintained by Nicolas Sebrecht at
|
||||
https://github.com/nicolas33/offlineimap. Thanks to John for his great job and
|
||||
to have share this project with us.
|
||||
|
||||
|
||||
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
|
||||
@ -29,75 +16,42 @@ 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 does not require additional python dependencies (although python-sqlite is strongly recommended)
|
||||
|
||||
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.
|
||||
|
||||
Documentation
|
||||
=============
|
||||
|
||||
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.
|
||||
The documentation (in .rst format) is included in the `docs`
|
||||
directory. Read it directly or generate nicer html (python-sphinx
|
||||
needed) or the man page (python-docutils needed) via::
|
||||
|
||||
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.
|
||||
'make doc' (user docs), 'make man' (man page only) or 'make' (both)
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
(`make html` will simply create html versions of all *.rst files in /docs)
|
||||
|
||||
The resulting user documentation will be in `docs/html`. The full user
|
||||
docs are also at: `<http://docs.offlineimap.org>`_. Please see there for
|
||||
detailed information on how to install and configure OfflineImap.
|
||||
|
||||
Quick Start
|
||||
===========
|
||||
|
||||
If you have already installed OfflineIMAP system-wide, or your system
|
||||
administrator 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!
|
||||
First, install OfflineIMAP. See docs/INSTALL.rst or read
|
||||
`<http://docs.offlineimap.org/en/latest/INSTALL.html>`_.
|
||||
(hint: `sudo python setup.py install`)
|
||||
|
||||
You can quickly set up your configuration file. The distribution includes a
|
||||
file offlineimap.conf.minimal (Debian users may find this at
|
||||
``/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal``) that is a
|
||||
basic example of setting of OfflineIMAP. You can simply copy this file into
|
||||
your home directory and name it ``.offlineimaprc`` (note the leading period). A
|
||||
command such as ``cp offlineimap.conf.minimal ~/.offlineimaprc`` will do it.
|
||||
Or, if you prefer, you can just copy this text to ``~/.offlineimaprc``::
|
||||
Second, set up your configuration file and run it! The distribution
|
||||
includes offlineimap.conf.minimal (Debian users may find this at
|
||||
``/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal``) that
|
||||
provides you with the bare minimum of setting up OfflineIMAP. You can
|
||||
simply copy this file into your home directory and name it
|
||||
``.offlineimaprc``. A command such as ``cp offlineimap.conf.minimal
|
||||
~/.offlineimaprc`` will do it. Or, if you prefer, you can just copy
|
||||
this text to ``~/.offlineimaprc``::
|
||||
|
||||
[general]
|
||||
accounts = Test
|
||||
@ -121,30 +75,23 @@ to do is specify a directory for your folders to be in (on the localfolders
|
||||
line), the host name of your IMAP server (on the remotehost line), and your
|
||||
login name on the remote (on the remoteuser line). That's it!
|
||||
|
||||
To run OfflineIMAP, you just have to say offlineimap ― it will fire up, ask you
|
||||
for a login password if necessary, synchronize your folders, and exit. See?
|
||||
To run OfflineIMAP, you just have to say `offlineimap` ― 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!
|
||||
|
||||
|
||||
Documentation
|
||||
=============
|
||||
|
||||
If you are reading this file on github, you can find more documentations in the
|
||||
`docs` directory.
|
||||
|
||||
Using your git repository, you can generate documentation with::
|
||||
|
||||
$ make doc
|
||||
You can just throw away the rest of the finely-crafted,
|
||||
perfectly-honed user 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 our full user documentation and peruse the sample
|
||||
offlineimap.conf (which includes all available options) for further
|
||||
tweaks!
|
||||
|
||||
|
||||
Mailing list
|
||||
============
|
||||
|
||||
The user discussion, development and all exciting stuff take place in the
|
||||
`mailing list`_. You're *NOT* supposed to subscribe to send emails.
|
||||
`mailing list`_. You do *NOT* need to subscribe to send emails.
|
||||
|
||||
|
||||
Reporting bugs and contributions
|
||||
@ -154,9 +101,6 @@ Bugs
|
||||
----
|
||||
|
||||
Bugs, issues and contributions should be reported to the `mailing list`_.
|
||||
**Please, don't use the github features (messages, pull requests, etc) at all.
|
||||
It would most likely be discarded or ignored.**
|
||||
|
||||
|
||||
========
|
||||
Examples
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -1 +0,0 @@
|
||||
../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/`.)
|
||||
66
docs/doc-src/features.rst
Normal file
66
docs/doc-src/features.rst
Normal file
@ -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.
|
||||
@ -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
|
||||
@ -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.
|
||||
|
||||
@ -162,6 +163,7 @@ What folder separators do I need to use in nametrans rules?
|
||||
in nametrans rules?::
|
||||
|
||||
nametrans = lambda f: "INBOX/" + f
|
||||
|
||||
or::
|
||||
nametrans = lambda f: "INBOX." + f
|
||||
|
||||
Loading…
Reference in New Issue
Block a user